> 📖 **纸质书《OpenClaw超级个体实操手册》已上市！** 清华大学出版社出版，在开源教程基础上全面重写+逐条验证。🛒 [京东专属购买链接（¥42，原价¥59.8）](https://item.jd.com/14669463.html)

# 第2章节：环境搭建

> 本章节将手把手教你安装 OpenClaw。

> ⚠️ **当前基线**：截至 **2026-09-10**，本教程推荐使用 **OpenClaw v2026.9.3（稳定版，2026-09-08 发布）**。运行时要求 **Node 24.16+** 或 **Node 26.1+**（推荐 Node 26）；Node 22 / 旧 24.x 已不再支持。

![OpenClaw 安装界面](https://upload.maynor1024.live/file/1771085321300_installation-interface.png)



## 📋 前提条件与推荐配置

### 推荐配置

为了获得最佳体验，我们推荐：

**操作系统**：
- 🍎 **Mac（强烈推荐）**：原生支持最完善，可操作日历、备忘附录、截图等系统功能
- 🪟 Windows：完全可用，但部分系统集成功能受限
- 🐧 Linux：适合开发布者，配置灵活

**IM工具选择**：
- 🌍 **国外用户**：推荐 **Telegram**（适配度最好，功能最完整）
- 🇨🇳 **国内用户**：推荐 **飞书**（现代化、开发布友好、功能丰富）
- 备选：企业微信、钉钉、QQ

**部署方式**：
- 💻 **有Mac电脑**：推荐本地部署（体验最好，功能最全）
- ☁️ **无Mac或想24小时运行**：推荐云端部署（成本低，稳定可靠）

### 为什么推荐Mac？

OpenClaw在Mac上体验最好，因为：
- ✅ 原生支持最完善，系统集成度高
- ✅ 可以操作Mac日历、备忘附录、提醒事项
- ✅ 截图功能完美支持
- ✅ 与iPhone、iPad无缝同步
- ✅ 文件管理更智能
- ✅ 开发布环境配置简单

### 为什么推荐飞书（国内）？

- ✅ 现代化设计，用户体验好
- ✅ 开发布者友好，API完善
- ✅ 支持富文本、文档、表格
- ✅ 消息推送稳定
- ✅ 免费版功能丰富

### 为什么推荐Telegram（国外）？

- ✅ 全球用户基础大
- ✅ API最完善，功能最强
- ✅ 支持Bot功能丰富
- ✅ 消息推送实时
- ✅ 隐私保护好

## 快速导航

**推荐路径**：
- 🍎 **有Mac** → [Mac本地部署](#mac本地部署推荐) + [飞书配置](../03-advanced/09-multi-platform-integration.md#91-飞书bot配置)
- ☁️ **无Mac/想24小时运行** → [云端一键部署](#云端一键部署) + [飞书配置](../03-advanced/09-multi-platform-integration.md#91-飞书bot配置)

**所有部署方式**：
- 🍎 [Mac本地部署（推荐）](#mac本地部署推荐)
- 🪟 [Windows本地部署](#windows本地部署)
- 🐧 [Linux本地部署](#linux本地部署)
- 🚀 [云端一键部署](#云端一键部署)
- 🇨🇳 [国内一键安装](#国内一键安装推荐)
- ☁️ [Cloudflare Workers 部署（进阶）](#cloudflare-workers-部署进阶)
- 🐳 [Docker 部署（可选）](#docker-部署可选)

**配置指南**：
- 🔑 [API配置指南](#api配置指南)
- 🔄 [版本升级指南](#2x-版本升级指南)
- ❓ [常见访问题解决](#常见访问题解决)

---

## Mac本地部署（推荐）

> 🍎 **最佳体验**：如果你有Mac电脑，强烈推荐本地部署，体验最好、功能最全！

### 为什么选择Mac本地部署？

**优势**：
- ✅ **系统集成**：可操作日历、备忘附录、文件系统
- ✅ **隐私安全**：数据完全本地，不上传云端
- ✅ **响应速度快**：本地运行，无网络延迟
- ✅ **功能最全**：支持所有高级功能
- ✅ **成本低**：无需购买云服务器
- ✅ **开发布友好**：方便调试和自定义

**适合人群**：
- 有Mac电脑的用户
- 注重隐私的用户
- 需要系统集成功能的用户
- 开发布者和技术爱好者

### 系统要求

**硬件要求**：
- CPU：M系列芯片或Intel i5以上
- 内存：8GB以上（推荐16GB）
- 硬盘：10GB以上空闲空间

**系统版本**：
- macOS 12 Monterey 或更高版本
- 推荐 macOS 14 Sonoma 或 macOS 15 Sequoia

**前置软件**：
- Node.js 24（推荐）/ 22.16+（兼容路径，会自动安装）
- Homebrew（可选，用于安装依赖）

### 安装步骤

#### 第一步：打开终端

1. 按 `Command + 空格` 打开 Spotlight
2. 输入 `Terminal` 或`终端`
3. 按回车打开终端

![Mac终端打开方式 - 通过Spotlight搜索Terminal](https://upload.maynor1024.live/file/1770742238798_07-select-quickstart.png)

#### 第二步：安装 OpenClaw

在终端中执行以下命令：

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
安装过程会自动：
- 检测系统环境
- 安装Node.js（如果未安装）
- 下载OpenClaw
- 配置环境变量

**预计时间**：2-5分钟

#### 第三步：验证安装

安装完成后，执行以下命令验证：

```bash
openclaw --version
```
如果显示版本号（如 `2026.9.3`），说明安装成功！

#### 第四步：初始化配置

运行配置向导：

```bash
openclaw onboard
```

**配置流程**：

**1. 接受风险提示**：

选择 `Yes` 继续

![安装向导 - 接受风险提示](https://upload.maynor1024.live/file/1770742238798_07-select-quickstart.png)

**2. 选择启动模式**：

推荐选择 `QuickStart` 快速启动：

![安装向导 - 选择QuickStart快速启动模式](https://upload.maynor1024.live/file/1770742238798_07-select-quickstart.png)

**3. 选择AI模型**：

选择你的AI供应商（支持国内外主流模型）：

![安装向导 - 选择AI模型供应商](https://upload.maynor1024.live/file/1770742221938_03-select-ai-provider.png)

国内推荐：
- **Kimi（Moonshot AI）**：长文本专家，200万字上下文
- **DeepSeek**：性价比之王，推理能力强
- **智谱GLM**：中文理解好，多模态支持

**4. 输入API Key**：

根据选择的模型，输入对应的API Key（参见[API配置指南](#api配置指南)）

**5. 选择聊天工具**：

- 如果要接入飞书/Telegram，选择对应选项
- 如果暂时不接入，选择 `None`（后续可配置）

![安装向导 - 选择聊天平台（飞书/企微/QQ等）](https://upload.maynor1024.live/file/1770742247561_08-select-chat-tool.png)

**6. Gateway端口设置**：

默认 `18789` 即可：

![安装向导 - Gateway端口配置（默认18789）](https://upload.maynor1024.live/file/1770742247410_09-port-setting.png)

**7. 选择Skills**：

使用空格键选择你需要的技能，也可以直接跳过：

![安装向导 - 选择需要安装的技能包](https://upload.maynor1024.live/file/1770742255849_10-select-skills.png)

**8. API Key配置**：

没有的可以选择 `no` 跳过：

![安装向导 - 配置AI模型API 密钥](https://upload.maynor1024.live/file/1770742264976_11-api-key-config.png)

**9. 启用Hooks**：

推荐启用这三个钩子（用于内内容引导、日志和会话记附录）：

![安装向导 - 启用自动化钩子功能](https://upload.maynor1024.live/file/1770742261487_12-enable-hooks.png)

**10. 完成配置**：

配置完成后，会自动启动Gateway服务并打开Web UI（`http://127.0.0.1:18789/chat`）

#### 第五步：验证安装

```bash
# 检查Gateway状态
openclaw channels status

# 应该显示：
# Gateway reachable.
```

### 日常使用

**启动OpenClaw**：

```bash
# 启动Gateway服务
openclaw gateway start

# 或使用systemd（推荐，开机自启）
openclaw gateway enable
```

**访问Web UI**：

打开浏览器访问：`http://127.0.0.1:18789/chat`

**停止服务**：

```bash
openclaw gateway stop
```

### 接入飞书（推荐）

Mac本地部署后，强烈推荐接入飞书，获得最佳体验：

1. 参考 [第9章节：飞书Bot配置](../03-advanced/09-multi-platform-integration.md#91-飞书bot配置)
2. 配置完成后，可以在飞书中随时与OpenClaw对话
3. 支持文本、图片、文件等多种消息类型

### 常见访问题

**Q1：安装时提示权限不足？**

```bash
# 使用sudo安装
curl -fsSL https://openclaw.ai/install.sh | sudo bash
```

**Q2：如何更新OpenClaw？**

```bash
openclaw update
```

**Q3：如何卸载？**

```bash
openclaw uninstall
```
---

## Windows本地部署

> 🪟 **Windows用户**：完全可用，但部分系统集成功能受限。

![Windows系统部署架构 - WSL2+Ubuntu方案](https://upload.maynor1024.live/file/1770963301031_attachment_531c0e90-e8a2-469c-b6ec-b9811a55edfa_image.png)

### 系统要求

**硬件要求**：
- CPU：2核以上
- 内存：4GB以上（推荐8GB）
- 硬盘：10GB以上空闲空间

**操作系统**：
- Windows 10 或 Windows 11

**前置软件**：
- Node.js 24（推荐）/ 22.16+（兼容路径）

### 部署方式选择

Windows有两种部署方式：

1. **WSL2 + Ubuntu（强烈推荐）**：官方推荐方式，提供完整Linux环境支持
2. **PowerShell原生部署**：纯Windows环境，适合不想使用WSL2的用户

---

### 方式一：WSL2 + Ubuntu部署（强烈推荐）

这是官方推荐的Windows部署方式，提供最完整的Linux环境支持。

#### 第一步：启用WSL2

**以管理员身份打开PowerShell**，执行：

```powershell
# 启用WSL功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 设置WSL 2为默认版本
wsl --set-default-version 2
```

**重启计算机**。

#### 第二步：安装Ubuntu

**方法一：Microsoft Store安装（推荐）**

1. 打开Microsoft Store
2. 搜索「Ubuntu 22.04 LTS」或「Ubuntu 24.04 LTS」
3. 点击「获取」并安装
4. 首次启动设置用户名和密码

安装完成后会自动打开Ubuntu终端，按提示设置用户名和密码。

#### 第三步：更新Ubuntu系统

在Ubuntu终端中执行：

```bash
# 更新软件包列表
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y curl git wget build-essential
```

#### 第四步：安装Node.js 24（推荐）

```bash
# 添加NodeSource仓库
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

# 安装Node.js
sudo apt install -y nodejs

# 验证版本（推荐 v24.x）
node -v
npm -v
```

#### 第五步：安装 OpenClaw

**方法A：一键脚本安装**

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```

#### 第六步：验证安装

```bash
# 查看版本
openclaw --version

# 查看帮助
openclaw --help

# 查看系统状态
openclaw status
```

#### 第七步：配置Windows访问WSL2服务

由于OpenClaw运行在WSL2中，需要配置端口转发布以便Windows访问。

**创建启动脚本** `start-openclaw.bat`：

```batch
@echo off
echo Starting OpenClaw Gateway in WSL2...
wsl -d Ubuntu-22.04 -u root service openclaw start
timeout /t 3
start http://localhost:18789
```
或直接在WSL2中启动：

```bash
# 在WSL2 Ubuntu终端中
openclaw gateway run --port 18789
```
然后在Windows浏览器访问 `http://localhost:18789`

---

### 方式二：PowerShell原生部署

适合不想使用WSL2的纯Windows用户。

#### 第一步：安装Node.js 24（推荐）

**方法一：官网下载安装**

1. 访问 https://nodejs.org/zh-cn
2. 下载Windows安装包（推荐 24.x 版本）
3. 运行安装程序，勾选「自动安装必要的工具」

#### 第二步：验证Node.js安装

```powershell
# 打开PowerShell
node -v
npm -v
```

#### 第三步：以管理员身份安装 OpenClaw

**重要**：必须以**管理员身份**运行PowerShell。

```powershell
# 安装最新稳定版
npm install -g openclaw@latest --allow-scripts=openclaw

# 或安装汉化版
npm install -g @qingchencloud/openclaw-zh@latest
```

#### 第四步：解决安装权限访问题

如果遇到权限错误：

```powershell
# 方法A：启用PowerShell脚本执行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 方法B：修改npm安装目附录
npm config set prefix "C:\npm"
npm config set cache "C:\npm-cache"

# 将目附录添加到PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\npm", "User")
```

#### 第五步：验证安装

```powershell
openclaw --version
openclaw --help
```

#### 第六步：解决常见访问题

**访问题：sharp模块加载失败**

```powershell
# 清理npm缓存
npm cache clean --force

# 重新安装
npm install -g openclaw@latest --allow-scripts=openclaw --force
```

**访问题：Windows Defender阻止**

将OpenClaw安装目附录添加到Windows Defender排除项：

```
C:\Users\你的用户名\AppData\Roaming\npm
C:\Users\你的用户名\.openclaw
```
---

### 初始化配置

安装完成后，需要运行初始化向导。

#### 启动初始化向导

```bash
openclaw onboard --install-daemon
```

#### 配置AI模型提供商

OpenClaw需要对接AI模型才能工作。

**以配置Anthropic Claude（推荐）为例：**

> 📖 **详细说明**: 完整的 API Key 配置方式和优先级说明请参考 [API Key 配置完整指南](../api-key-config-guide.md)

```bash
# WSL2或PowerShell
openclaw models auth add
# 按提示选择 anthropic
# 输入 API Key: sk-ant-xxx
```

#### 绑定消息渠道

**1. Telegram**

创建Bot：
1. 在Telegram搜索 `@BotFather`
2. 发布送 `/newbot` 创建机器人
3. 保存Bot Token

配置：

```bash
openclaw channels add telegram
openclaw config set channels.telegram.botToken "your-bot-token"
openclaw gateway restart
```

**2. WhatsApp**

```bash
# 登录WhatsApp（显示二维码）
openclaw channels login whatsapp

# 用手机WhatsApp扫码
```

**3. 企业微信（国内推荐）**

```bash
# 安装企业微信插件
openclaw plugins install @m1heng-clawd/wework

# 配置
openclaw config set channels.wework '{"enabled":true,"corpId":"xxx","agentSecret":"xxx"}' --json
```

**4. 飞书（国内推荐）**

```bash
# 安装飞书插件
openclaw plugins install @m1heng-clawd/feishu

# 配置
openclaw config set channels.feishu '{"enabled":true,"appId":"cli_xxx","appSecret":"xxx"}' --json
```

### Windows常用命令速查

**系统管理**：

| 命令 | 功能 |
|------|------|
| `openclaw --version` | 查看版本 |
| `openclaw status` | 查看系统状态 |
| `openclaw health` | 健康检查 |
| `openclaw update` | 更新OpenClaw |
| `openclaw doctor` | 诊断系统访问题 |

**配置管理**：

| 命令 | 功能 |
|------|------|
| `openclaw onboard` | 初始化向导 |
| `openclaw configure` | 交互式配置 |
| `openclaw config get <key>` | 查看配置项 |
| `openclaw config set <key> <value>` | 修改配置项 |
| `openclaw config unset <key>` | 删除配置项 |

---

## Linux本地部署

> 🐧 **Linux用户**：适合开发布者，配置灵活。

### 系统要求

**推荐发布行版**：
- Ubuntu 20.04+
- Debian 11+
- CentOS 8+

### 安装步骤

#### 第一步：安装Node.js

```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
```

#### 第二步：安装 OpenClaw

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```

#### 第三步：验证安装

```bash
openclaw --version
```

#### 第四步：初始化配置

```bash
openclaw onboard
```
---

## 2.1 系统要求与准备

### 云端部署要求

如果选择云端部署，**无需任何本地环境**，只需要：
- ✅ 一个浏览器
- ✅ 20元/月预算
- ✅ 10分钟时间

## 云端一键部署

> 🔥 **适合场景**：无Mac电脑、需要24小时运行、多设备访问。

### 为什么选择云端部署？

云端部署相比本地部署具有多项优势，如表 2-1 所示。

**表 2-1 云端部署优势**

| 优势 | 说明 |
|------|------|
| ⚡ **秒级部署** | 点几下鼠标就完成，无需配置环境 |
| 💰 **成本低** | 20元/月起，比买Mac Mini便宜太多 |
| 📱 **手机可用** | 通过QQ、企微、飞书随时随地访问 |
| 🔒 **稳定可靠** | 24小时运行，不用担心电脑关机 |
| 🎥 **视频教程** | 官方视频手把手教学 |

### 方案对比

目前主流的云端部署方案对比如表 2-2 所示。

**表 2-2 云端部署方案对比**

| 方案 | 价格 | 带宽 | 推荐场景 |
|------|------|------|----------|
| 腾讯云Lighthouse | 20元/月，99元/年 | 20M | QQ、企微用户 |
| 火山引擎 | 9.9元/月，58元/年 | 5M | 飞书用户 |

### 腾讯云Lighthouse部署（推荐）

#### 第一步：购买服务器

1. **访问活动页面**：
   ```
   https://cloud.tencent.com/act/pro/lighthouse-moltbot
   ```

2. **选择配置**：
   - 配置：2核2G
   - 带宽：20M
   - 地域：建议选择**硅谷**（国外地域访问AI模型更稳定）
   - 价格：20元/月 或 99元/年

3. **实名认证**：
   - 首次使用需要实名认证
   - 选择个人认证即可
   - 按提示完成认证

4. **完成购买**：
   - 点击"立即购买"
   - 支付20元（建议先买1个月试用）
   - 等待服务器创建完成
   - **可选**：关闭自动续费

5. **获取服务器信息**：
   - 购买完成后，点击头像 → "站内信"
   - 查看并记附录：
     - 公网IP地址
     - 默认用户名（通常是 `lighthouse`）
     - 初始密码

![腾讯云Lighthouse控制台 - 创建实例界面](https://upload.maynor1024.live/file/1770742212222_01-tencent-cloud-server.png)

#### 💡 免费白嫖方案（可选）

> 如果你想免费试用3个月，可以通过 CodeBuddy 活动获取免费服务器。

**步骤**：

1. **注册 CodeBuddy**：
   - 国际版：https://www.codebuddy.ai/promotion/?ref=lweelxalgm（谷歌/GitHub账户）
   - 国内版：https://www.codebuddy.cn/promotion/?ref=7zucxaz7zvqi（手机号）
   - 建议使用新账号注册

2. **领取奖励**：
   - 登录后点击"实战礼" → "立刻领奖"
   - 获得1个月免费使用权
   - **累计活跃7日可再延长2个月**（每天在CodeBuddy中访问候即可）

3. **重装系统为OpenClaw**：
   - 登录腾讯云控制台：https://console.cloud.tencent.com/
   - 进入"轻量应用服务器"
   - 点击"重装系统"
   - 选择"使用应用模板" → "OpenClaw"
   - 选择"无需备份"，点击"确定"

4. **后续操作**：
   - 重装完成后，按照下面的步骤继续配置

#### 第二步：连接服务器

1. **使用SSH客户端连接**：
   
   **方式一：使用SSH客户端（推荐）**
   - 下载SSH客户端（如 Xterminal、Termius、FinalShell）
   - 新建SSH连接：
     - 名称：随便取
     - 地址：公网IP地址
     - 端口：22
     - 用户名：lighthouse（或站内信中的用户名）
     - 密码：购买时设置的密码
   
   **方式二：使用网页终端**
   - 在腾讯云控制台，点击实例卡片
   - 点击"登录"按钮
   - 直接在浏览器中打开终端

2. **验证OpenClaw安装**：
   ```bash
   openclaw --version
   ```
   
   如果显示版本号（如 `2026.9.3`），说明OpenClaw已预装成功。

![OpenClaw镜像](https://upload.maynor1024.live/file/1770742213992_02-openclaw-image.png)

#### 第三步：配置大模型

1. **进入应用管理**：
   - 点击服务器卡片
   - 切换到"应用管理"标签

2. **选择模型**：
   - 推荐使用 **Kimi k2.5**（性价比最高）
   - 也可以选择其他国产大模型

![选择AI供应商](https://upload.maynor1024.live/file/1770742221938_03-select-ai-provider.png)

3. **获取API Key**：
   
   **Kimi k2.5配置**（推荐）：
   ```
   1. 访问：https://platform.moonshot.cn/
   2. 注册账号并登录
   3. 进入"API管理"
   4. 点击"创建API Key"
   5. 复制API Key（格式：sk-xxx）
   ```

4. **填入配置**：
   - 将API Key粘贴到配置框
   - 点击"保存"
   - 等待配置生效

#### 第四步：测试连接

1. **访问WebUI**：
   - 使用控制台提供的访问地址
   - 格式：`http://你的服务器IP:18789/?token=xxx`

2. **发布送测试消息**：
   ```
   你好，能听到我说话吗？
   ```

![测试对话](https://upload.maynor1024.live/file/1770742223389_04-test-chat.png)

3. **验证成功**：
   - 如果收到AI回复，说明配置成功
   - 右上角会显示使用的模型名称

### 腾讯龙虾产品矩阵（2026年新增）

> 💡 2026年3月，腾讯推出了「龙虾全家桶」系列产品，围绕 OpenClaw 构建了完整的产品矩阵。以下是各产品的关系和定位：

| 产品 | 类型 | 平台 | 状态 | 定位 |
|------|------|------|------|------|
| **Lighthouse** | 云服务器 | 全平台 | ✅ 稳定 | 轻量云服务器，适合部署 OpenClaw 后端 |
| **QClaw** | 桌面客户端 | macOS | ✅ 全量公测 | 腾讯官方 OpenClaw 桌面客户端，开箱即用 |
| **WorkBuddy** | 桌面Agent | Windows/macOS | ✅ 公测 | 桌面端AI助手，支持多IM（微信、QQ、飞书等） |
| **ClawBot** | 微信插件 | 全平台 | ✅ 公测 | 官方微信接入方案，基于 WeChatFerry |

**各产品关系**：

```
┌─────────────────────────────────────────┐
│           腾讯龙虾产品矩阵               │
├──────────┬──────────┬───────────────────┤
│  Lighthouse │  QClaw  │    WorkBuddy      │
│ (云服务器)  │ (桌面端) │   (多IM Agent)    │
│   ↓部署    │  ↓内置   │      ↓集成         │
│  OpenClaw后端 ───────→ OpenClaw核心     │
│              ↑                          │
│         ClawBot (微信插件)              │
└──────────┴──────────┴───────────────────┘
```

**使用建议**：

- **个人用户 / macOS**：优先试用 QClaw，一键安装无需折腾服务器
- **需要多IM接入**：选择 WorkBuddy，支持微信、QQ、飞书等同时在线
- **微信深度用户**：搭配 ClawBot 插件实现微信消息收发
- **需要服务器部署**：选择 Lighthouse，20元/月性价比极高

> ⚠️ QClaw 于 2026-03-20 从内测转为全量公测，目前仅支持 macOS。Windows 版本正在开发中。

### 火山引擎部署（更便宜）

如果你是飞书重度用户，推荐使用火山引擎：

1. **访问活动页面**：
   ```
   https://www.volcengine.com/activity/clawdbot
   ```

2. **价格优势**：
   - 9.9元/月
   - 58元/年
   - 比腾讯云便宜10元

3. **配置对比**：
   - 2核2G（相同）
   - 5M带宽（腾讯云20M）
   - 适合飞书用户

4. **部署流程**：
   - 与腾讯云类似
   - 按照页面提示操作即可

### 百度智能云部署（0.01元试用）

> 💰 **超值试用**：百度智能云提供0.01元/月的特惠活动，适合想要低成本试用的用户。

#### 活动信息

1. **访问活动页面**：
   ```
   https://cloud.baidu.com/product/BCC/moltbot.html
   ```

2. **活动规则**：
   - 首月仅需 **0.01元**
   - 需要注册并绑定个人身份证
   - 每个账号限购一次

#### 部署步骤

**第一步：购买服务器**

1. 注册百度智能云账号
2. 完成个人实名认证（绑定身份证）
3. 抢购特惠LS实例（0.01元/月）
4. 如果售罄，可以原价购买轻量应用服务器

**第二步：创建实例**

1. 进入轻量应用服务器LS控制台
2. 点击"创建实例"：
   - 名称：随机生成或自定义
   - 密码：**务必记住**，后续登录需要
3. 等待实例创建完成

**第三步：一键配置 OpenClaw**

1. **进入实例详情页**：
   - 点击实例卡片
   - 进入"应用管理"标签

2. **应用配置**：
   - 点击"一键开通"
   - 点击"一键放行"（开放防火墙端口）
   - 等待显示"已放行"

3. **模型配置**：
   - 下拉选择模型（如：文心一言、千帆大模型）
   - 点击"应用模型配置"
   - 系统会自动创建千帆API Key并配置

4. **接入方式配置**（可选）：
   - 支持接入：飞书、钉钉、企业微信、QQ
   - 选择你常用的通讯工具
   - 按照提示完成配置（详见后续章节节）

5. **Skills 配置**（可选）：
   - 默认提供：百度搜索、百度百科
   - 可以按需选择并点击"应用"
   - 更多Skills可访问OpenClaw官网获取

**第四步：访问WebUI**

1. 点击"获取网站地址"
2. 复制访问链接
3. 在浏览器中打开，即可与OpenClaw对话

#### 优势与限制

**优势**：
- ✅ 价格极低（首月0.01元）
- ✅ 一键配置，无需手动安装
- ✅ 集成百度千帆大模型
- ✅ 自动配置APIKey

**限制**：
- ⚠️ 仅限首月优惠
- ⚠️ 需要实名认证
- ⚠️ 活动可能售罄

### 阿里云部署（可选）

阿里云也提供了OpenClaw一键部署方案：

1. **访问活动页面**：
   ```
   https://www.aliyun.com/activity/ecs/clawdbot
   ```

2. **选择轻量应用服务器**：
   - 使用 OpenClaw镜像
   - 一键安装配置

![阿里云轻量服务器](https://upload.maynor1024.live/file/1770742237148_05-aliyun-server.png)

3. **价格参考**：
   - 与腾讯云类似
   - 具体以活动页面为准

### 官方视频教程（强烈推荐）

腾讯云提供了详细的视频教程，跟着视频操作更简单：

1. **云上OpenClaw一键部署并接入企微和QQ**
   - 视频地址：https://cloud.tencent.com/developer/video/85003
   - 时长：约10分钟
   - 内内容：从购买到配置完成

2. **云上OpenClaw一键部署并接入飞书和钉钉**
   - 视频地址：https://cloud.tencent.com/developer/video/85055
   - 时长：约10分钟
   - 内内容：飞书和钉钉接入全流程

### 存量服务器部署

如果你已经有轻量服务器，可以使用AI助手对话式部署：

- **官方教程**：https://cloud.tencent.com/developer/article/2625605
- **适用场景**：已有轻量服务器
- **部署方式**：通过AI对话完成配置
- **优势**：更灵活，可自定义

### 云端部署常见访问题

**Q1: 云端部署安全吗？**
- ✅ 数据存储在你的服务器上
- ✅ 只有你能访问
- ✅ 可以设置访问密码

**Q2: 可以随时停止吗？**
- ✅ 可以随时删除服务器
- ✅ 按使用时长计费
- ✅ 不用了就删除，不浪费钱

**Q3: 手机怎么访问？**
- 通过QQ、企微、飞书等平台
- 详见[第9章节：多平台集成](../03-advanced/09-multi-platform-integration.md)

## 国内一键安装（推荐）

> 🇨🇳 **国内用户推荐**：使用官方中文版一键安装脚本，速度快、配置简单。

### 为什么选择国内版？

国内版相比国际版具有多项本地化优势，如表 2-3 所示。

**表 2-3 国内版优势**

| 优势 | 说明 |
|------|------|
| ⚡ **速度快** | 使用国内镜像源，下载速度快 |
| 🇨🇳 **中文友好** | 完整中文界面和提示 |
| 📦 **一键安装** | 自动配置所有依赖 |
| 🎯 **开箱即用** | 预配置国内常用服务 |
| 💰 **成本优化** | 默认配置国产模型 |

![image-20260213122830687](https://upload.maynor1024.live/file/1770956917086_image-20260213122830687.png)

### 前置要求

**必需环境**：
- Node.js 24（推荐）/ 22.16+（兼容路径）（必需）
- pnpm（可选，推荐用于源码构建）

**推荐配置**：
- Brave Search API 密钥（用于网络搜索）
- 可通过 `openclaw-cn configure --section web` 配置

**系统要求**：
- macOS：需要 Xcode / Command Line Tools（仅 CLI + Gateway 需要 Node.js）
- Windows：强烈推荐使用 WSL2（Ubuntu），原生 Windows 未经测试
- Linux：Ubuntu 20.04+、Debian、CentOS

### 快速开始

#### macOS/Linux 安装

```bash
# 使用国内官方安装脚本
curl -fsSL https://clawd.org.cn/install.sh | bash
```

#### Windows 安装

使用 PowerShell（管理员权限）：

```powershell
# 使用国内官方安装脚本
iwr -useb https://clawd.org.cn/install.ps1 | iex
```
> ⚠️ **Windows 用户注意**：强烈推荐使用 WSL2（Ubuntu），原生 Windows 支持有限。

**WSL2 安装步骤**：
```powershell
# 1. 安装 WSL2
wsl --install

# 2. 重启电脑

# 3. 在 WSL2 中运行 Linux 安装命令
curl -fsSL https://clawd.org.cn/install.sh | bash
```

#### 全局安装（替代方案）

如果一键脚本失败，可以使用 npm 全局安装：

```bash
# 使用 npm
npm install -g openclaw-cn@latest

# 或使用 pnpm（推荐）
pnpm add -g openclaw-cn@latest
```

### 运行入门向导

安装完成后，运行配置向导：

```bash
# 运行入门向导并安装后台服务
openclaw-cn onboard --install-daemon
```

### 配置向导流程

向导会引导你完成以下配置：

**1. 选择网关模式**：
- 本地网关（推荐）：Gateway 运行在本机
- 远程网关：Gateway 运行在服务器

**2. 配置认证**：
- OpenAI Code（Codex）订阅（OAuth）
- API 密钥（推荐用于 Anthropic）
- 也支持 `claude setup-token`

**3. 选择 AI 提供商**：
- 推荐：Kimi、DeepSeek、GLM-4（国产模型）
- 可选：Claude、GPT（需要 API key）

**4. 配置聊天平台**（可选）：
- WhatsApp：QR 扫码登录
- Telegram：输入 Bot Token
- Discord：输入 Bot Token
- Mattermost：插件令牌
- 飞书/企微/钉钉：输入应用凭证

**5. 安装后台服务**（推荐）：
- macOS：使用 launchd
- Linux：使用 systemd
- WSL2：使用 systemd
- 运行时：Node（推荐，WhatsApp/Telegram 必需）

**6. 网关令牌**：
- 向导默认生成一个令牌
- 存储在 `gateway.auth.token` 中
- 即使在回环地址上也会生成

### 认证配置说明

**认证存储位置**（重要）：

- **推荐的 Anthropic 路径**：设置 API 密钥（向导可存储）
- OAuth 凭据（旧版导入）：`~/.openclaw/credentials/oauth.json`
- 认证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`

**无头/服务器提示**：
- 先在普通机器上完成 OAuth
- 然后将 `oauth.json` 复制到网关主机

### 启动 Gateway

如果安装了后台服务，Gateway 应该已经在运行：

```bash
# 检查 Gateway 状态
openclaw-cn gateway status
```

**手动运行（前台）**：

```bash
# 在前台运行，查看实时日志
openclaw-cn gateway --port 18789 --verbose
```

**Dashboard 访问**：

本地回环地址：`http://127.0.0.1:18789/`

如果配置了令牌，需要将其粘贴到控制界面设置中（存储为 `connect.params.auth.token`）。

> ⚠️ **Bun 警告（WhatsApp + Telegram）**：Bun 在这些渠道上有已知访问题。如果使用 WhatsApp 或 Telegram，请使用 Node 运行网关。

### 快速验证（2分钟）

```bash
# 检查状态
openclaw-cn status

# 健康检查
openclaw-cn health
```

### 配对 + 连接聊天界面

#### WhatsApp（二维码登录）

```bash
# 登录 WhatsApp
openclaw-cn channels login
```
通过 WhatsApp → 设置 → 已连接的设备 扫描二维码。

#### Telegram / Discord / 其他

向导可以为你写入令牌/配置。如果手动配置：

**Telegram**：
```bash
openclaw-cn channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"
```

**Discord**：
```bash
openclaw-cn channels add \
  --channel discord \
  --token "YOUR_BOT_TOKEN"
```
> 💡 **Telegram 私信提示**：首次私信会返回配对码，需要批准后机器人才会响应。

### 私信安全（配对审批）

默认策略：未知私信会收到短代码，消息在获得批准前不会被处理。

如果首次私信没有得到回复，需要批准配对：

```bash
# 查看配对列表
openclaw-cn pairing list whatsapp

# 批准配对
openclaw-cn pairing approve whatsapp <code>
```

### 从源码运行（开发布）

如果需要修改 OpenClaw 本身，可以从源码运行：

```bash
# 克隆仓库
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

# 安装依赖
pnpm install

# 构建 UI（首次运行时自动安装 UI 依赖）
pnpm ui:build

# 构建项目
pnpm build

# 运行入门向导
openclaw-cn onboard --install-daemon
```
如果还没有全局安装，可以从仓库中通过 `pnpm openclaw-cn ...` 运行命令。

**从源码运行 Gateway**：

```bash
node dist/entry.js gateway --port 18789 --verbose
```

### 端到端验证

在新终端中，发布送测试消息：

```bash
# 发布送测试消息
openclaw-cn message send --target +15555550123 --message "Hello from OpenClaw"
```
如果 `openclaw-cn health` 显示 "no auth configured"，需要返回向导设置 OAuth/密钥认证。

**调试提示**：
- `openclaw-cn status --all`：最佳的只读调试报告
- `openclaw-cn health`：向运行中的网关请求健康快照
- `openclaw-cn status --deep`：深度状态检查

### 配置文件位置

> 📖 **详细说明**: 完整的配置文件结构和使用指南请参考 [配置文件结构完整指南](../config-file-structure.md)

```bash
# 主配置文件
~/.openclaw/openclaw.json

# 认证配置
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

# OAuth 凭据（旧版）
~/.openclaw/credentials/oauth.json

# 日志文件件
~/.openclaw/logs/gateway.log
```

### 国内版特色功能

**1. 预配置国产模型**：
- Kimi（月之暗面）
- DeepSeek（深度求索）
- GLM-4（智谱 AI）
- 通义千访问（阿里）
- 文心一言（百度）

**2. 国内平台集成**：
- 飞书（字节跳动）
- 企业微信（腾讯）
- 钉钉（阿里）
- QQ（腾讯）

**3. 优化的网络配置**：
- 使用国内镜像源
- 优化 API 访问速度
- 支持代理配置

### 常见访问题

**Q1: 安装失败怎么怎么办？**

```bash
# 检查 Node.js 版本（需要 22+）
node --version

# 如果版本过低，使用 nvm 升级
nvm install 22
nvm use 22
```

**Q2: 如何更新到最新版本？**

```bash
# 重新运行安装脚本
curl -fsSL https://clawd.org.cn/install.sh | bash
```

**Q3: 如何卸载？**

```bash
# 停止服务
openclaw-cn gateway stop

# 卸载
npm uninstall -g openclaw-cn

# 删除配置（可选）
rm -rf ~/.openclaw
```

**Q4: 支持哪些系统？**

- ✅ macOS 12+
- ✅ Linux（Ubuntu 20.04+、Debian、CentOS）
- ✅ Windows 10/11（通过 WSL2）

**Q5: 配置向导卡住怎么怎么办？**

```bash
# 按 Ctrl+C 中断

# 检查网关是否运行
openclaw-cn gateway status

# 重新启动网关并重试
openclaw-cn gateway restart
openclaw-cn onboard
```

**Q6: 健康检查显示 "no auth configured"**

需要配置认证：
```bash
# 重新运行向导
openclaw-cn onboard

# 或手动配置 API 密钥
openclaw-cn configure --section auth
```

### 下一步（可选，但很棒）

- macOS 菜单栏应用 + 语音唤醒：[macOS 应用](https://docs.openclaw.ai/platforms/macos.html)
- iOS/Android 节点（Canvas/摄像头/语音）：[节点](https://docs.openclaw.ai/nodes.html)
- 远程访问（SSH 隧道 / Tailscale 服务）：[远程访问](https://docs.openclaw.ai/gateway/remote.html)
- 始终在线 / VPN 设置：[Tailscale](https://docs.openclaw.ai/gateway/tailscale.html)

### 下一步

安装完成后，可以：

1. 配置 AI 模型（见下文"API配置指南"）
2. 连接聊天平台（见[第9章节：多平台集成](../03-advanced/09-multi-platform-integration.md)）
3. 安装 Skills（见[第8章节：Skills扩展](../03-advanced/08-skills-extension.md)）
4. 开始使用（见[第3章节：快速上手](03-quick-start.md))

---

## Cloudflare Workers 部署（进阶）

> ☁️ **全球 CDN 加速**：使用 Cloudflare Workers 部署 OpenClaw，分享受全球边缘网络加速。

### 为什么选择 Cloudflare Workers？

Cloudflare Workers 提供全球边缘网络部署能力，如表 2-4 所示。

**表 2-4 Cloudflare Workers 优势**

| 优势 | 说明 |
|------|------|
| 🌍 **全球加速** | 部署在 Cloudflare 全球边缘网络 |
| 💰 **成本可控** | 5美元/月起步，24小时在线 |
| 🔒 **安全可靠** | 内置 Zero Trust 安全认证 |
| ⚡ **快速部署** | 一键部署，10分钟完成 |
| 📦 **无需服务器** | Serverless 架构，无需维护 |

### 前置要求

**必需条件**：
- Cloudflare 账号
- Workers Paid 计划（5美元/月）
- 信用卡（用于订阅付费计划）

**成本说明**：
- 基础费用：5美元/月（起步价）
- 高频使用可能产生额外费用
- 作为 24 小时在线的 AI 服务，月成本在可接受范围内

> 💡 **成本参考**：详见 [GitHub 讨论：What's the cost running it 24/7 for a month](https://github.com/cloudflare/moltworker/issues/76)

### 部署流程

#### 第一步：一键部署 Moltworker

1. **点击部署按钮**：
   ```
   https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/moltworker
   ```

2. **配置 Gateway Token**：
   - 务必修改并妥善保存 `MOLTBOT_GATEWAY_TOKEN`
   - 这是后续进入管理后台的唯一凭证
   - 建议使用强密码生成器

![Cloudflare Workers 部署](https://upload.maynor1024.live/file/1770956993044_webp)

#### 第二步：等待构建

- 部署过程约需 10 分钟
- 可点击「继续处理项目」跳过等待页面
- 构建完成后会自动跳转到项目页面

![构建过程](https://upload.maynor1024.live/file/1770956995188_webp-20260213122951843)

#### 第三步：配置 Access（Zero Trust）

访问网页界面需要配置 `CF_ACCESS_AUD` 和 `CF_ACCESS_TEAM_DOMAIN` 两个变量。

**1. 创建应用**：
- 进入 Zero Trust → Access → Applications
- 添加一个 Self-hosted 应用

![创建应用](https://upload.maynor1024.live/file/1770957006656_1770956995941_webp-20260213122946760)

**2. 设置域名**：
- 子域默认为 `moltbot-sandbox`
- 域名可使用 Cloudflare 分配的 Worker 域名或自定义域名
- Session Duration（会话时间）建议设置长一些，避免频繁登录

**3. 配置策略**：
- 系统会自动创建 `moltbot-sandbox - Production` 策略
- 默认通过邮箱验证码登录

**4. 获取配置变量**：

**CF_ACCESS_AUD**：
- 保存应用后，点击右侧「⋮」编辑
- 在应用程序受众（AUD）标签页找到 Application Audience (AUD)

**CF_ACCESS_TEAM_DOMAIN**：
- 进入 Zero Trust → Settings
- 团队域名格式：`xxxxxx.cloudflareaccess.com`

#### 第四步：配置 R2 对象存储

OpenClaw 需要 R2 来存储状态，需配置以下三个变量：
- `CF_ACCOUNT_ID`
- `R2_ACCESS_KEY_ID`
- `R2_SECRET_ACCESS_KEY`

**操作步骤**：

**1. 获取 Account ID**：
- 在 Cloudflare 侧边栏进入 R2 → Overview
- 右侧 Account Details 中的 Account ID 即为 `CF_ACCOUNT_ID`

![获取 Account ID](https://upload.maynor1024.live/file/1770957013012_webp-20260213123002670)

**2. 创建 API 令牌**：
- 点击 Manage R2 API Tokens
- 选择 Create API Token

**3. 设置权限**：
- 权限选择 Object Read & Write
- 建议范围通过 Specific Bucket 限制在 `moltbot-data`

![设置权限](https://upload.maynor1024.live/file/1770957013719_webp-20260213123006410)

**4. 保存密钥**：
- 创建成功后，记附录 Access Key ID 和 Secret Access Key

![保存密钥](https://upload.maynor1024.live/file/1770957016450_webp-20260213123010373)

> ⚠️ **重要提示**：修改 Token 时请务必核对变量名称。如果不慎修改了 Build Token，会导致 Worker 构建失败。

#### 第五步：注入变量并重启

1. **进入设置**：
   - Workers → Settings → Variables and Secrets

2. **填入变量**：
   - `MOLTBOT_GATEWAY_TOKEN`（第一步设置的）
   - `CF_ACCESS_AUD`（第三步获取的）
   - `CF_ACCESS_TEAM_DOMAIN`（第三步获取的）
   - `CF_ACCOUNT_ID`（第四步获取的）
   - `R2_ACCESS_KEY_ID`（第四步获取的）
   - `R2_SECRET_ACCESS_KEY`（第四步获取的）

3. **重新部署**：
   - 点击 Deploy 重新部署
   - 等待部署完成

![注入变量](https://upload.maynor1024.live/file/1770957030499_webp-20260213123020335)

### 访问与管理

部署完成后，可通过以下地址访问：

**访问 Worker**（需要 token）：
```
https://moltbot-sandbox.xxxxxxxx.workers.dev?token=MOLTBOT_GATEWAY_TOKEN
```

**管理后台**（需要邮箱验证）：

```
https://moltbot-sandbox.xxxxxxxx.workers.dev/_admin/
```
通过 Cloudflare Access 的邮箱验证码验证后，即可进入管理后台并接受 Pairing Requests。

![管理后台](https://upload.maynor1024.live/file/1770957055794_webp-20260213123047239)

### 基础使用

#### 查看或切换模型

```bash
# 查看当前模型
/model

# 切换模型
/model minimax/MiniMax-M2.1
```

#### 设置开机自启命令

为了避免 Worker 重启后模型被重置，建议设置开机自启命令：

```bash
set model minimax/MiniMax-M2.1
```

#### 远程终端连接

```bash
# 登录到 Gateway
openclaw gateway login --url https://moltbot-sandbox.xxxxxxxx.workers.dev

# 配置 Skills
openclaw configure --section skills
```

### 避坑指南

**访问题 1：模型配置报错**

**症状**：通过配置文件修改默认模型后报错

**原因**：国内 AI 服务商通常区分国内与海外端点，Cloudflare Workers 环境下配置文件修改内容易出错

**解决方案**：
- 直接通过开机命令强制指定模型
- 不要依赖配置文件或后台 UI
- 使用 `set model` 命令设置开机自启

**访问题 2：Worker 构建失败**

**症状**：部署后 Worker 无法启动

**原因**：不慎修改了 Build Token

**解决方案**：
- 检查所有变量名称是否正确
- 确保没有修改 Build Token
- 重新部署

**访问题 3：无法访问管理后台**

**症状**：访问 `/_admin/` 时无法登录

**原因**：Zero Trust 配置不正确

**解决方案**：
- 检查 `CF_ACCESS_AUD` 和 `CF_ACCESS_TEAM_DOMAIN` 是否正确
- 确认邮箱验证码是否正确
- 检查 Session Duration 设置

### 成本估算

| 项目 | 费用 | 说明 |
|------|------|------|
| Workers Paid 计划 | 5美元/月 | 基础费用 |
| 额外请求费用 | 按量计费 | 高频使用时产生 |
| R2 存储 | 免费额度内 | 通常不会超出 |
| 总计 | 5-10美元/月 | 取决于使用频率 |

### 适用场景

**推荐使用**：
- ✅ 想低成本尝试 OpenClaw
- ✅ 已有 Cloudflare 付费订阅
- ✅ 需要全球 CDN 加速
- ✅ 不想维护服务器

**不推荐使用**：
- ❌ 期望开箱即用
- ❌ 没有技术背景
- ❌ 需要复杂的自动化流程
- ❌ 预算非常有限

### 总结

Cloudflare Workers + OpenClaw 是一个低成本的尝鲜方案，适合：
- 未体验过 Agent 自动化，想低成本试手
- 已有 Cloudflare 付费订阅，资源闲置
- 需要全球 CDN 加速的场景

但需要注意：
- OpenClaw 目前还不是一个能「即刻提升效率」的工具
- 更像是一个为 AI 自动化搭建的系统底座
- 如果没有明确的、可标准化的长流程需求，可能只会带来维护成本

**下一步**：
- 配置 AI 模型（见下文"API配置指南"）
- 配置通讯渠道（见[第9章节：多平台集成](../03-advanced/09-multi-platform-integration.md)）
- 安装 Skills（见[第8章节：Skills扩展](../03-advanced/08-skills-extension.md)）

---

## Docker 部署（可选）

> 🐳 **开发布者选项**：Docker 部署适合需要环境隔离的场景。

### 为什么选择 Docker？

Docker 部署提供环境隔离和便捷管理，如表 2-5 所示。

**表 2-5 Docker 部署优势**

| 优势 | 说明 |
|------|------|
| 🔒 **环境隔离** | 不影响系统环境，干净整洁 |
| 📦 **一键部署** | 无需配置依赖，开箱即用 |
| 🔄 **易于更新** | 一条命令完成更新 |
| 🌐 **跨平台** | Windows/macOS/Linux 统一方案 |
| 🚀 **快速启动** | 5分钟完成部署 |

### 前置要求

**安装 Docker**：

**macOS**：
```bash
# 下载 Docker Desktop
# 访问：https://www.docker.com/products/docker-desktop

# 或使用 Homebrew
brew install --cask docker
```

**Windows**：
```bash
# 下载 Docker Desktop
# 访问：https://www.docker.com/products/docker-desktop

# 安装 WSL2（如果还没安装）
wsl --install
```

**Linux (Ubuntu)**：
```bash
# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

# 添加当前用户到 docker 组
sudo usermod -aG docker $USER
```

**验证安装**：
```bash
docker --version
# 应显示：Docker version 24.x.x
```

### 快速开始

#### 方式一：一键脚本部署（推荐新手）

最简单的方式，一条命令搞定所有配置！

```bash
curl -fsSL https://clawd.org.cn/install.sh | bash
```

**这个脚本会自动：**
- ✅ 检查 Docker 环境
- ✅ 下载镜像（使用国内镜像：`jiulingyun803/openclaw-cn:latest`）
- ✅ 配置环境变量
- ✅ 启动内容器
- ✅ 运行配置向导
- ✅ 生成网关令牌

完成后，在浏览器打开 `http://127.0.0.1:18789/` 即可使用。

**脚本后续操作**：
- 按照提示输入渠道信息（可选）
- 将生成的令牌复制到 Web UI 登录

#### 方式二：手动 Docker Compose 部署（适合进阶用户）

如果一键脚本不适用，或需要自定义配置，按以下步骤操作。

**步骤 1：创建工作目附录**

```bash
mkdir -p ~/openclaw-docker
cd ~/openclaw-docker
```

**步骤 2：创建 `.env` 环境文件**

```bash
cat > .env << 'EOF'
# 镜像配置（使用国内镜像）
OPENCLAW_IMAGE=jiulingyun803/openclaw-cn:latest

# 数据目附录
OPENCLAW_CONFIG_DIR=./data/.openclaw
OPENCLAW_WORKSPACE_DIR=./data/clawd

# 网关配置
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=your-secure-token-here

# Claude 集成（可选）
CLAUDE_AI_SESSION_KEY=
CLAUDE_WEB_SESSION_KEY=
CLAUDE_WEB_COOKIE=
EOF
```

**步骤 3：创建 `docker-compose.yml` 文件**

```yaml
services:
  openclaw-cn-gateway:
    image: ${OPENCLAW_IMAGE:-jiulingyun803/openclaw-cn:latest}
    user: node:node
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE}
    volumes:
      - ${OPENCLAW_CONFIG_DIR:-./data/.openclaw}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR:-./data/clawd}:/home/node/clawd
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
    init: true
    restart: unless-stopped
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND:-lan}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT:-18789}"
      ]

  openclaw-cn-cli:
    image: ${OPENCLAW_IMAGE:-jiulingyun803/openclaw-cn:latest}
    user: node:node
    environment:
      HOME: /home/node
      TERM: xterm-256color
      BROWSER: echo
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE}
    volumes:
      - ${OPENCLAW_CONFIG_DIR:-./data/.openclaw}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR:-./data/clawd}:/home/node/clawd
    stdin_open: true
    tty: true
    init: true
    entrypoint: ["node", "dist/index.js"]
```

**步骤 4：启动内容器**

```bash
# 拉取最新镜像
docker compose pull

# 启动网关（后台运行）
docker compose up -d openclaw-cn-gateway

# 查看日志（可选）
docker compose logs -f openclaw-cn-gateway
```

**步骤 5：运行配置向导**

```bash
docker compose run --rm openclaw-cn-cli onboard
```
配置向导会提示你：
- 选择网关后端（Claude、Gemini 等）
- 配置 Feishu、Telegram 等渠道
- 生成和保存配置

**步骤 6：访问 Web UI**

打开浏览器访问：`http://127.0.0.1:18789/`

将配置向导生成的令牌复制到登录页面即可。

### 环境变量详解

| 变量 | 含义 | 默认值 | 必需 | 说明 |
|------|------|--------|------|------|
| OPENCLAW_IMAGE | Docker 镜像名称 | jiulingyun803/openclaw-cn:latest | ❌ | 使用国内镜像，也可指定版本号 |
| OPENCLAW_CONFIG_DIR | 配置文件目附录 | ./data/.openclaw | ❌ | OpenClaw 配置和凭证存储位置 |
| OPENCLAW_WORKSPACE_DIR | 工作空间目附录 | ./data/clawd | ❌ | 代理工作文件存储位置 |
| OPENCLAW_GATEWAY_PORT | 网关端口号 | 18789 | ❌ | 访问 Web UI 的端口 |
| OPENCLAW_BRIDGE_PORT | 桥接端口号 | 18790 | ❌ | 用于客户端连接的端口 |
| OPENCLAW_GATEWAY_BIND | 网关绑定地址 | lan | ❌ | localhost（仅本机）/ lan（局域网）/ 0.0.0.0（公网，⚠️ 谨慎使用） |
| OPENCLAW_GATEWAY_TOKEN | 网关认证令牌 | 自动生成 | ❌ | Web UI 登录令牌（可自定义或留空自动生成） |
| CLAUDE_AI_SESSION_KEY | Claude.ai 会话密钥 | 空 | ❌ | ⚠️ 仅使用 Claude AI 作为后端时填写 |
| CLAUDE_WEB_SESSION_KEY | Claude Web 会话密钥 | 空 | ❌ | ⚠️ 仅使用 Claude Web 版时填写 |
| CLAUDE_WEB_COOKIE | Claude Web Cookie | 空 | ❌ | ⚠️ 仅使用 Claude Web 版时填写 |

**环境变量设置方式**：

**方式 A：编辑 `.env` 文件（推荐）**
```bash
# 编辑 .env 文件
nano .env

# docker compose 会自动读取
docker compose up -d
```

**方式 B：命令行设置**
```bash
export OPENCLAW_GATEWAY_PORT=18789
docker compose up -d
```

**方式 C：命令行临时覆盖**
```bash
docker compose -e OPENCLAW_GATEWAY_PORT=8080 up -d
```

### 常用操作

#### 查看网关状态

```bash
# 检查内容器是否运行
docker compose ps

# 查看网关日志
docker compose logs openclaw-cn-gateway

# 实时查看日志（支持续跟踪）
docker compose logs -f openclaw-cn-gateway
```

#### 配置渠道

通过 CLI 内容器配置各类渠道：

**Telegram（需要机器人令牌）**：
```bash
docker compose run --rm openclaw-cn-cli channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"
```

**Discord（需要机器人令牌）**：
```bash
docker compose run --rm openclaw-cn-cli channels add \
  --channel discord \
  --token "YOUR_BOT_TOKEN"
```

**WhatsApp（QR 扫码）**：
```bash
docker compose run --rm openclaw-cn-cli channels login
```

**Feishu（需要 App ID 和 Secret）**：
```bash
docker compose run --rm openclaw-cn-cli onboard
# 按提示输入信息
```

#### 重新配置

```bash
# 重新运行配置向导
docker compose run --rm openclaw-cn-cli onboard

# 查看当前配置
docker compose run --rm openclaw-cn-cli config get
```

#### 重启网关

```bash
# 重启网关内容器
docker compose restart openclaw-cn-gateway

# 停止网关
docker compose down

# 重新启动
docker compose up -d openclaw-cn-gateway
```

#### 更新到最新版本

```bash
# 拉取最新镜像
docker compose pull

# 重启内容器（自动使用新镜像）
docker compose up -d openclaw-cn-gateway
```

#### 清理数据（谨慎操作）

```bash
# 停止并删除内容器
docker compose down

# 删除本地数据目附录
rm -rf ./data/

# 删除本地镜像（可选）
docker rmi jiulingyun803/openclaw-cn:latest
```

### 数据支持久化

Docker 内容器的数据存储在工作目附录的 `data` 文件夹：

```bash
~/openclaw-docker/data/
├── .openclaw/         # 配置文件
│   ├── openclaw.json  # 主配置
│   └── logs/          # 日志文件件
└── clawd/             # 工作空间
    └── workspace/     # 代理工作文件
```

**备份数据**：
```bash
# 备份配置和数据
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ./data

# 恢复数据
tar -xzf openclaw-backup-20260210.tar.gz
```

### Docker 部署常见访问题

#### 访问题 1：内容器无法启动

**症状**：`docker compose up` 后内容器立即退出

**解决方案**：
```bash
# 查看详细错误日志
docker compose logs openclaw-cn-gateway

# 检查端口是否被占用
sudo netstat -ltnp | grep 18789
# macOS 使用：lsof -i :18789

# 如果被占用，修改 OPENCLAW_GATEWAY_PORT
# 编辑 .env，将端口改为其他（如 18790）
nano .env
```

#### 访问题 2：权限拒绝（Permission Denied）

**症状**：`Error: EACCES: permission denied, mkdir ...`

**解决方案**：
```bash
# 确保数据目附录存在且权限正确
mkdir -p ./data/.openclaw ./data/clawd
chmod 755 ./data/.openclaw ./data/clawd

# 如果使用了宿主机路径，确保目附录可写
chmod 777 ./data
```

#### 访问题 3：无法访问 Web UI

**症状**：浏览器访问 `http://127.0.0.1:18789` 无响应

**解决方案**：
```bash
# 检查内容器是否运行
docker compose ps

# 检查网关日志
docker compose logs openclaw-cn-gateway

# 验证端口是否正确
# 如果 OPENCLAW_GATEWAY_PORT=18789，则访问 :18789
# 如果改了端口，访问对应的新端口

# 检查防火墙设置
# macOS
sudo pfctl -d  # 临时关闭防火墙测试

# Linux
sudo ufw status
sudo ufw allow 18789
```

#### 访问题 4：配置向导卡住

**症状**：`docker compose run --rm openclaw-cn-cli onboard` 无反应

**解决方案**：
```bash
# 按 Ctrl+C 中断

# 检查网关是否运行
docker compose logs openclaw-cn-gateway

# 重新启动网关并重试
docker compose restart openclaw-cn-gateway
docker compose run --rm openclaw-cn-cli onboard
```

#### 访问题 5：镜像拉取失败（403 错误）

**症状**：`docker pull openclaw/openclaw:latest` 返回 403 错误

**解决方案**：
```bash
# 使用国内镜像（推荐）
docker pull jiulingyun803/openclaw-cn:latest

# 或在 .env 文件中指定国内镜像
echo "OPENCLAW_IMAGE=jiulingyun803/openclaw-cn:latest" >> .env

# 重新拉取
docker compose pull
```

#### 访问题 6：网络超时

**症状**：拉取镜像或访问 API 时网络超时

**解决方案**：
```bash
# 配置 Docker 镜像加速（国内用户）
# 编辑 Docker 配置
sudo nano /etc/docker/daemon.json

# 添加镜像加速器
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

# 重启 Docker
sudo systemctl restart docker

# macOS 用户在 Docker Desktop 设置中添加镜像加速器
```

#### 访问题 7：数据丢失

**症状**：重启内容器后配置和数据丢失

**解决方案**：
```bash
# 确保使用了数据卷挂载
# 检查 docker-compose.yml 中的 volumes 配置

# 查看数据是否存在
ls -la ./data/.openclaw
ls -la ./data/clawd

# 如果数据丢失，从备份恢复
tar -xzf openclaw-backup-20260210.tar.gz
```

#### 访问题 8：性能访问题

**症状**：内容器运行缓慢或占用资源过高

**解决方案**：
```bash
# 限制资源使用（编辑 docker-compose.yml）
services:
  openclaw-cn-gateway:
    # ... 其他配置
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

# 重启内容器
docker compose up -d openclaw-cn-gateway
```

### 从一键脚本迁移到手动配置

如果想从一键脚本切换到手动配置（或反之）：

```bash
# 停止现有内容器
docker compose down

# 备份现有配置
cp -r ~/.openclaw ~/.openclaw.backup

# 更新 .env 和 docker-compose.yml

# 重新启动
docker compose up -d openclaw-cn-gateway
```
配置会自动保留在数据目附录中，无需重新设置。

### Docker 部署优势总结

✅ **环境隔离**：不影响系统环境  
✅ **快速部署**：5分钟完成  
✅ **易于管理**：一条命令更新  
✅ **跨平台**：统一部署方案  
✅ **可扩展**：支持多实例部署  
✅ **国内优化**：使用国内镜像，下载速度快

**推荐使用场景**：
- 开发布者本地测试
- 服务器部署
- 多环境隔离
- 快速体验 OpenClaw

**下一步**：
- 配置 API 模型（见下文"API配置指南"）
- 配置通讯渠道（见[第9章节：多平台集成](../03-advanced/09-multi-platform-integration.md)）
- 安装 Skills（见[第8章节：Skills扩展](../03-advanced/08-skills-extension.md)）

---

## 更新和维护

> 🔄 **保支持最新**：定期更新 OpenClaw 以获得新功能和安全修复。

### 检查更新

```bash
# 检查当前版本
openclaw --version

# 检查最新版本
curl -s https://api.github.com/repos/openclaw/openclaw/releases/latest | grep tag_name
```

### 本地安装更新

```bash
# 方式一：使用安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 方式二：手动更新
cd ~/openclaw
git pull origin main
pnpm install
pnpm build
```

### Docker 更新

```bash
# 拉取最新镜像
docker pull openclaw/openclaw:latest

# 停止并删除旧内容器
docker stop openclaw
docker rm openclaw

# 启动新内容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  --restart unless-stopped \
  openclaw/openclaw:latest
```

### 备份数据

**本地安装备份**：
```bash
# 备份配置和数据
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

# 恢复数据
tar -xzf openclaw-backup-20260210.tar.gz -C ~/
```

**Docker 备份**：
```bash
# 备份数据卷
docker run --rm \
  -v ~/.openclaw:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/openclaw-backup-$(date +%Y%m%d).tar.gz /data

# 恢复数据
docker run --rm \
  -v ~/.openclaw:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/openclaw-backup-20260210.tar.gz -C /
```

### 监控和日志

**查看日志**：
```bash
# 本地安装
tail -f ~/.openclaw/logs/gateway.log

# Docker
docker logs -f openclaw
```

**监控指标**：
```bash
# 查看系统状态
openclaw gateway status

# 查看资源使用
openclaw stats

# 查看 API 消耗和额度
openclaw status --usage
```

### 故障排查

**常见访问题**：

1. **Gateway 无法启动**
   ```bash
   # 查看日志
   openclaw logs
   
   # 检查端口占用
   lsof -i :18789
   
   # 重启 Gateway
   openclaw gateway restart
   ```

2. **API 连接失败**
   ```bash
   # 测试 API 连接
   openclaw test api
   
   # 检查 API Key
   openclaw config get models.providers
   ```

3. **性能访问题**
   ```bash
   # 清理缓存
   openclaw cache clear
   
   # 重启服务
   openclaw gateway restart
   ```

### 卸载

**本地安装卸载**：
```bash
# 停止服务
openclaw gateway stop

# 删除文件
rm -rf ~/.openclaw
rm -rf ~/openclaw

# 删除命令
npm uninstall -g openclaw
```

**Docker 卸载**：
```bash
# 停止并删除内容器
docker stop openclaw
docker rm openclaw

# 删除镜像
docker rmi openclaw/openclaw

# 删除数据
rm -rf ~/.openclaw
```
---

## API配置指南

> OpenClaw需要连接AI模型才能工作，推荐使用**国产大模型**，性价比高。

### 为什么需要API？

OpenClaw本身不包含AI模型，需要连接第三方API：
- 官方API：价格贵、国内访问困难
- 第三方API：价格便宜、国内直连

### API模型分类

OpenClaw支持两种类型的API模型配置：

#### 1. 内置 API 模型（推荐新手）

**什么是内置API模型？**

OpenClaw已经预先配置好了多个主流AI模型的连接方式，你只需要：
- ✅ 获取API Key
- ✅ 在配置向导中选择对应模型
- ✅ 粘贴API Key即可使用

**支持的内置模型**：

OpenClaw内置支持非常多的API模型，包括但不限于：

![内置API模型列表](https://upload.maynor1024.live/file/1770957195044__null_)

**国内模型**（推荐）：
- 🌙 **Moonshot AI (Kimi)**：长文本专家，200万字上下文
- 🧠 **DeepSeek**：性价比之王，推理能力强
- 🎯 **智谱GLM**：中文理解好，多模态支持
- 🚀 **通义千访问 (Qwen)**：阿里出品，稳定可靠
- 🎨 **MiniMax**：对话自然，创意能力强
- 📚 **百度文心**：中文语料丰富
- 🔥 **字节豆包**：性价比高

**国外模型**：
- 🤖 **OpenAI (GPT-4/GPT-3.5)**：最强大但价格贵
- 🦙 **Anthropic (Claude)**：推理能力强，安全性高
- 🔷 **Google (Gemini)**：多模态能力强
- 🌐 **Groq**：推理速度快

**优势**：
- ✅ 配置简单，无需手动编写配置文件
- ✅ 参数已优化，开箱即用
- ✅ 自动更新，跟随OpenClaw版本
- ✅ 适合新手，降低使用门槛

**使用场景**：
- 🎯 新手用户快速上手
- 🎯 使用主流大模型
- 🎯 不想折腾配置文件

#### 2. 自定义 API（进阶用户）

**什么是自定义API？**

如果你想使用：
- 🔧 OpenClaw未内置的模型
- 🔧 自己搭建的模型服务
- 🔧 第三方API代理服务
- 🔧 企业内部的模型接口

就需要使用自定义API配置。

**配置方式**：

需要手动编辑配置文件 `~/.openclaw/openclaw.json`，指定：
- `baseUrl`：API服务地址
- `apiKey`：认证密钥
- `api`：API协议类型（如 `openai-chat`、`anthropic-messages`）
- `models`：模型列表和参数

**优势**：
- ✅ 灵活性高，支持任何兼内容的API
- ✅ 可以使用小众模型
- ✅ 可以自定义模型参数
- ✅ 适合企业定制化需求

**劣势**：
- ⚠️ 配置复杂，需要了解JSON格式
- ⚠️ 需要手动维护配置
- ⚠️ 参数错误可能导致无法使用

**使用场景**：
- 🎯 进阶用户
- 🎯 使用非主流模型
- 🎯 企业内部部署
- 🎯 需要精细控制参数

### 配置方式对比

两种配置方式的对比如表 2-6 所示。

**表 2-6 API 配置方式对比**

| 特性 | 内置API模型 | 自定义API |
|------|------------|-----------|
| 配置难度 | ⭐ 简单 | ⭐⭐⭐⭐ 复杂 |
| 适用人群 | 新手 | 进阶用户 |
| 模型选择 | 主流模型 | 任意模型 |
| 配置方式 | 向导选择 | 手动编辑 |
| 维护成本 | 低 | 高 |
| 灵活性 | 中 | 高 |

### 推荐配置路径

**新手推荐**：
```
1. 使用内置API模型
2. 选择国产模型（如 Kimi、DeepSeek）
3. 通过 openclaw onboard 向导配置
4. 先体验，熟悉后再考虑自定义
```

**进阶用户**：
```
1. 先用内置API模型熟悉OpenClaw
2. 了解配置文件结构
3. 根据需求添加自定义API
4. 测试验证后投入使用
```
---

### 自定义API配置（进阶用户）

> ⚠️ **适合人群**：进阶用户、需要使用非主流模型、企业定制化需求

#### 什么时候需要自定义API？

如果你遇到以下情况，需要使用自定义API配置：

1. **使用非内置模型**：
   - OpenClaw未内置的小众模型
   - 新发布布的模型（OpenClaw还未更新）
   - 区域限定的模型

2. **使用第三方代理**：
   - API代理服务（如 OpenRouter、API2D）
   - 企业内部的API网关
   - 自建的模型服务

3. **精细控制参数**：
   - 自定义模型参数
   - 调整上下文窗口大小
   - 修改默认配置

#### 配置文件位置

> 📖 **详细说明**: 完整的配置文件结构和使用指南请参考 [配置文件结构完整指南](../config-file-structure.md)

```bash
# 配置文件路径
~/.openclaw/openclaw.json

# 编辑配置文件
nano ~/.openclaw/openclaw.json
```

#### 配置文件结构

```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "你的供应商名称": {
        "baseUrl": "API服务地址",
        "apiKey": "你的API 密钥",
        "auth": "认证方式",
        "api": "API协议类型",
        "models": [
          {
            "id": "模型ID",
            "name": "模型显示名称",
            "contextWindow": 上下文窗口大小,
            "maxTokens": 最大输出tokens
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "供应商名称/模型ID"
      }
    }
  }
}
```

#### 示例1：配置DeepSeek（自定义方式）

```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-你的API 密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "contextWindow": 64000,
            "maxTokens": 4096
          },
          {
            "id": "deepseek-coder",
            "name": "DeepSeek Coder",
            "contextWindow": 64000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat"
      }
    }
  }
}
```

#### 示例2：配置第三方API代理

如果你使用API代理服务（如OpenRouter），配置如下：

```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "sk-or-v1-你的密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "anthropic/claude-3.5-sonnet",
            "name": "Claude 3.5 Sonnet",
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "openai/gpt-4",
            "name": "GPT-4",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-3.5-sonnet"
      }
    }
  }
}
```

#### 示例3：配置多个模型供应商

你可以同时配置多个供应商，根据需要切换：

```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-你的DeepSeek密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "contextWindow": 64000,
            "maxTokens": 4096
          }
        ]
      },
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "apiKey": "sk-你的Kimi密钥",
        "auth": "api-key",
        "api": "openai-chat",
        "models": [
          {
            "id": "moonshot-v1-128k",
            "name": "Kimi 128K",
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "deepseek/deepseek-chat",
        "fallback": "moonshot/moonshot-v1-128k"
      }
    }
  }
}
```

#### 配置参数说明

| 参数 | 说明 | 示例 |
|------|------|------|
| `baseUrl` | API服务地址 | `https://api.deepseek.com` |
| `apiKey` | API 密钥 | `sk-xxx` |
| `auth` | 认证方式 | `api-key` 或 `bearer` |
| `api` | API协议 | `openai-chat`、`anthropic-messages` |
| `id` | 模型ID | `deepseek-chat` |
| `name` | 显示名称 | `DeepSeek Chat` |
| `contextWindow` | 上下文窗口 | `64000` |
| `maxTokens` | 最大输出 | `4096` |

#### 常见API协议类型

- `openai-chat`：OpenAI兼内容接口（最常用）
- `anthropic-messages`：Anthropic Claude接口
- `google-generative-ai`：Google Gemini接口
- `azure-openai`：Azure OpenAI接口

#### 配置后重启服务

```bash
# 方式1：重启Gateway
openclaw gateway restart

# 方式2：停止后重新启动
systemctl --user stop openclaw-gateway.service
systemctl --user start openclaw-gateway.service

# 方式3：完全重启
systemctl --user restart openclaw-gateway.service
```

#### 验证配置

```bash
# 查看当前配置的模型
openclaw models list

# 测试模型连接
openclaw models test deepseek/deepseek-chat
```

#### 常见访问题

**Q1：配置后无法连接？**
```
检查项：
✅ baseUrl是否正确
✅ apiKey是否有效
✅ 网络是否能访问API地址
✅ 配置文件JSON格式是否正确
```

**Q2：如何切换模型？**
```bash
# 临时切换
openclaw agent --message --model deepseek/deepseek-chat

# 永久切换：修改配置文件中的 primary 字段
```

**Q3：如何添加多个模型？**
```
在 models 数组中添加多个模型对象即可
每个模型需要有唯一的 id
```
---

### 内置API模型配置（推荐新手）

> 💡 **适合人群**：新手用户、想要快速上手的用户

以下是几个常用的内置API模型配置教程，选择一个你喜欢的即可。

#### 1. Kimi 2.5 配置（推荐）

**特点**：
- 📚 **超长上下文**：支持200万字
- 📄 **长文档处理**：论文、报告分析专家
- 🎯 **中文理解好**：适合中文场景
- 💰 **套餐划算**：重度使用建议购买套餐

**配置步骤**：

**第一步：访问Kimi Code平台**

访问：https://www.kimi.com/code

![Kimi Code平台](https://upload.maynor1024.live/file/1770957261204__null_-20260213123415103._null_)

**第二步：购买套餐（可选）**

> 💡 **提示**：OpenClaw消耗token较大，建议购买套餐更划算。

推荐套餐：
- **Allegretto套餐**：适合日常使用
- 按需选择其他套餐

![购买套餐](https://my.feishu.cn/space/api/box/stream/download/asynccode/?code=Mzk3ODdjZjE0NDY3Y2NkMTU1ZDZmMzg4YTAwYTg3ZDdfV3haZXdRMEU5OENVN0RCTzBwbmp2U2M5dU1XSm9MMWdfVG9rZW46Q0dYQWJ5NzRVbzB4MWt4b09QRmNwckUybm1lXzE3NzA5NTcyMzY6MTc3MDk2MDgzNl9WNA)

**第三步：创建API Key**

1. 打开控制台
2. 创建API Key
3. 名称随便取

![创建API Key](https://upload.maynor1024.live/file/1770957262024__null_-20260213123418045._null_)

**第四步：保存API Key**

⚠️ **重要**：这个API Key一定要复制并保存！点击"完成"后就无法再查看了。

![保存API Key](https://upload.maynor1024.live/file/1770957271422__null_-20260213123420103._null_)

**第五步：配置到OpenClaw**

```bash
# 运行配置向导
openclaw onboard

# 配置流程：
# 1. 选择 QuickStart
# 2. 选择模型供应商：Moonshot AI
# 3. 粘贴刚才复制的API Key
# 4. 选择默认模型：kimi-code/kimi-for-codi
# 5. 完成其他配置
```

**成本估算**：
- 轻度使用：10-20元/月
- 中度使用：30-50元/月
- 重度使用：建议购买套餐

---

#### 2. DeepSeek 配置（性价比之王）

**特点**：
- 💰 **最便宜**：输入0.001元/千tokens
- 🧠 **推理能力强**：适合复杂任务
- 💻 **编程能力出色**：代码生成质量高

**配置步骤**：

**第一步：注册并充值**

访问：https://platform.deepseek.com/

> ⚠️ **注意**：DeepSeek采用按量付费，账户余额必须大于0才能调用API。

![DeepSeek平台](https://upload.maynor1024.live/file/1770957195044__null_)

**第二步：充值账户**

建议先充值10元试用：

![充值账户](https://my.feishu.cn/space/api/box/stream/download/asynccode/?code=OWU5ZGEzMDE0Y2YyNDhhOTYwZjliNWY0OTM1YjgzMmVfa0dlYzNvMzFvUDVuY0J3cWZ6b3VDUkNLRHpKbmhHSURfVG9rZW46UmZuamJDV29vb0Q2bXl4VHUwcWNxYWFRbnZ1XzE3NzA5NTcxNjg6MTc3MDk2MDc2OF9WNA)

**第三步：创建API Key**

1. 保证账号有余额
2. 点击"API keys"
3. 点击"创建API key"

![创建API Key](https://upload.maynor1024.live/file/1770957195220__null_-20260213123309627._null_)

**第四步：保存API Key**

⚠️ **重要**：API Key只显示一次，务必复制保存！

名称随便取，复制API Key后妥善保存。

![保存API Key](https://upload.maynor1024.live/file/1770957204667__null_-20260213123316852._null_)

**第五步：配置到OpenClaw**

```bash
# 运行配置向导
openclaw onboard

# 配置流程：
# 1. 选择 QuickStart
# 2. 选择模型供应商：DeepSeek
# 3. 粘贴API Key
# 4. 选择默认模型：deepseek-chat
# 5. 完成其他配置
```

**成本估算**：
- 日常使用：5-10元/月
- 中度使用：10-30元/月
- 重度使用：30-50元/月

---

### 国产大模型配置（其他选项）

#### 1. DeepSeek配置（性价比之王）

**特点**：
- 💰 **最便宜**：输入0.001元/千tokens
- 🧠 **推理能力强**：适合复杂任务
- 💻 **编程能力出色**：代码生成质量高



 DeepSeek 的 API 调用是**按量付费**的，你的账户余额必须大于 0 才能正常调用接口。

 如果账户没钱或余额不足，API 请求会直接失败，所以提前充值是保证服务可用的必要操作。

 其他大模型也是同理，你要去找到对应网址去充值，然后获取API keys

![img](https://upload.maynor1024.live/file/1770957195044__null_)

 如果你只想先尝，可以就先花个10块钱玩一下

![img](https://upload.maynor1024.live/file/1770961892504__null_-20260213135123663._null_)

 保证账号有余额之后，点击”API keys“，然后点”创建 API key“

![img](https://upload.maynor1024.live/file/1770961848240_1770957195220__null_-20260213123309627._null_)

 API key的名称：随便取。然后这个APIkey一定！一定！要复制下来，因为一般你点完”关闭“之后，你就再也无法查看你的API key了，如果你我忘记了你的API key，那只能重新创建一个了。

 复制完后，找地方先存起来，后续在”第四步：OpenClaw 配置“的时候会用到

![img](https://upload.maynor1024.live/file/1770957204667__null_-20260213123316852._null_)

好，至此”第二步：配置模型“完成，进入”第三步：配置Bot“吧

**配置步骤**：

1. **注册账号**：
   ```
   访问：https://platform.deepseek.com/
   注册并登录
   ```

2. **获取API Key**：
   
   ```
   进入"API管理"
   点击"创建API Key"
   复制API Key（格式：sk-xxx）
   ```
   
3. **配置到OpenClaw**：
   ```bash
   # 编辑配置文件
   nano ~/.openclaw/openclaw.json
   ```

   添加配置：
   ```json
   {
     "models": {
       "mode": "merge",
       "providers": {
         "deepseek": {
           "baseUrl": "https://api.deepseek.com",
           "apiKey": "sk-你的API 密钥",
           "auth": "api-key",
           "api": "openai-chat",
           "models": [
             {
               "id": "deepseek-chat",
               "name": "DeepSeek Chat",
               "contextWindow": 64000,
               "maxTokens": 4096
             }
           ]
         }
       }
     },
     "agents": {
       "defaults": {
         "model": {
           "primary": "deepseek/deepseek-chat"
         }
       }
     }
   }
   ```

4. **重启Gateway**：
   ```bash
   openclaw gateway restart
   ```

**成本估算**：
- 日常使用：5-10元/月
- 中度使用：10-30元/月
- 重度使用：30-50元/月

#### 2. Kimi配置（长文本专家）

**特点**：
- 📚 **超长上下文**：支持200万字
- 📄 **长文档处理**：论文、报告分析专家
- 🎯 **中文理解好**：适合中文场景

 那如何使用，第一步，搜索 kimi code：https://www.kimi.com/code

![img](https://upload.maynor1024.live/file/1770957261204__null_-20260213123415103._null_)

 第二步，购买优惠套餐 plan，说实话，目前 OpenClaw 消耗 token 还挺大的，最好买个套餐划算一些，我买的是 Allegretto 套餐。

![img](https://upload.maynor1024.live/file/1770961947439__null_-20260213135221938._null_)

 第二步，打开控制台，创建 API key。名字随便取。

![img](https://upload.maynor1024.live/file/1770957262024__null_-20260213123418045._null_)

 这个APIkey一定！一定！要复制下来，因为一般你点完”完成“之后，你就再也无法查看你的API key了，如果你忘记了你的API key，那就只能重新创建一个了。复制完后，找地方先存起来，后续在”第四步：OpenClaw 配置“的时候会用到

![img](https://upload.maynor1024.live/file/1770957271422__null_-20260213123420103._null_)

**配置步骤**：

1. **注册账号**：
   ```
   访问：https://platform.moonshot.cn/
   注册并登录
   ```

2. **获取API Key**：
   ```
   进入"API管理"
   点击"创建API Key"
   复制API Key
   ```

3. **配置到OpenClaw**：
   ```json
   {
     "models": {
       "mode": "merge",
       "providers": {
         "moonshot": {
           "baseUrl": "https://api.moonshot.cn/v1",
           "apiKey": "sk-你的API 密钥",
           "auth": "api-key",
           "api": "openai-chat",
           "models": [
             {
               "id": "moonshot-v1-8k",
               "name": "Kimi k2.5",
               "contextWindow": 8000,
               "maxTokens": 4096
             }
           ]
         }
       }
     },
     "agents": {
       "defaults": {
         "model": {
           "primary": "moonshot/moonshot-v1-8k"
         }
       }
     }
   }
   ```

**成本估算**：
- 日常使用：10-20元/月
- 中度使用：20-50元/月
- 重度使用：50-100元/月

#### 3. 其他国产大模型

| 模型 | 特点 | 价格 | 官网 |
|------|------|------|------|
| GLM-4 | 多模态能力强 | 中等 | https://open.bigmodel.cn/ |
| 文心一言 | 百度生态 | 中高 | https://cloud.baidu.com/ |
| 通义千访问 | 阿里生态 | 中等 | https://dashscope.aliyun.com/ |

### 国际模型配置（可选）

如果需要使用Claude、GPT等国际模型：

1. **直接使用官方API**（需要魔法）
2. **使用第三方API服务**（国内直连）

**推荐第三方API**：

- 价格便宜50%-70%
- 国内直连，无需魔法
- 支持支付宝、微信支付

### 成本对比

| 模型 | 输入价格 | 输出价格 | 月费用估算 |
|------|----------|----------|-----------|
| DeepSeek | 0.001元/千tokens | 0.002元/千tokens | 5-30元 |
| Kimi | 0.012元/千tokens | 0.012元/千tokens | 10-50元 |
| GLM-4 | 0.005元/千tokens | 0.005元/千tokens | 10-40元 |
| Claude（第三方） | 0.015元/千tokens | 0.075元/千tokens | 50-200元 |
| GPT-4（第三方） | 0.03元/千tokens | 0.06元/千tokens | 100-300元 |

💡 **省钱技巧**：
- 日常对话用DeepSeek（最便宜）
- 长文档用Kimi（长上下文）
- 复杂任务用Claude（质量最高）

## 常见访问题解决

### 安装访问题

**Q1: Node.js版本不对**

```bash
# 检查版本
node --version

# 如果低于22，升级
nvm install 22
nvm use 22
```

**Q2: 权限错误**
```bash
# macOS/Linux
sudo chown -R $USER ~/.openclaw

# Windows
# 以管理员身份运行PowerShell
```

**Q3: 网络连接失败**
- 检查网络连接
- 尝试使用代理
- 或使用云端部署

### API配置访问题

**Q1: API Key无效**
- 检查是否完整复制（包括sk-前缀）
- 检查是否有多余空格
- 检查账户余额是否充足

**Q2: 模型不可用**
- 检查模型ID是否正确
- 检查API服务是否正常
- 尝试切换其他模型

**Q3: Token消耗太快**
- 使用更便宜的模型（DeepSeek）
- 优化提示词
- 定期清理会话历史

### Gateway访问题

**Q1: Gateway无法启动**
```bash
# 查看日志
tail -f ~/.openclaw/logs/gateway.log

# 重启Gateway
openclaw gateway restart
```

**Q2: 端口被占用**
```bash
# 查看端口占用
lsof -i :18789

# 修改端口
openclaw config set gateway.port 18790
```

## 2.X 版本升级指南

> 🔄 **保持最新**：OpenClaw 迭代很快，升级通常会带来安全修复、provider 兼容性修复、渠道稳定性改进和新模型目录。

> ⚠️ **当前推荐版本**：截至 **2026-09-10**，本教程推荐使用 **OpenClaw 2026.9.3（稳定版）**。升级前先备份 `~/.openclaw`；升级后务必运行 `openclaw doctor --fix`、`openclaw update repair` 和状态检查。

### 推荐版本

**当前推荐版本**：`2026.9.3`

**版本确认命令**：

```bash
npm view openclaw version
openclaw --version
```

如果 `npm view openclaw version` 显示 `2026.9.3` 或更高版本，而你本机 `openclaw --version` 更低，就可以考虑升级。

### 升级前必做

```bash
# 1) 备份配置和本地状态
cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d-%H%M%S)

# 2) 记录当前版本
openclaw --version > ~/openclaw-version-before-upgrade.txt

# 3) 检查当前服务状态
openclaw gateway status
openclaw channels status
```

> 不要跳过备份。OpenClaw 的配置、凭据引用、会话、插件状态都可能保存在 `~/.openclaw` 下。

### 方式一：使用 `openclaw update`（推荐）

`openclaw update` 是当前 CLI 的统一升级入口。全局 npm 安装会通过检测到的包管理器更新；source checkout 会走 git 更新、依赖安装、构建和 doctor 流程。

```bash
# 预览升级动作，不真正写入
openclaw update --tag 2026.9.3 --dry-run

# 升级到教程推荐版本
openclaw update --tag 2026.9.3 --yes

# 如果你想直接跟随稳定频道
openclaw update --channel stable --yes
```

升级完成后：

```bash
openclaw update repair
openclaw doctor --fix
openclaw gateway restart
openclaw --version
openclaw gateway status
openclaw channels status
openclaw models status
```

> 从 `2026.6.x` / `2026.7.x` / `2026.8.x` 跨大版本升级时，`doctor --fix` 会处理：OpenAI 路由迁移（`codex/*`、`openai-codex/*` → `openai/*`）、OpenProse 残留清理、会话 SQLite 相关修复、Workshop 技能归属迁移等。

### 方式二：npm 固定版本安装（兜底）

如果 `openclaw update` 在你的环境里失败，或者你明确知道自己是 npm 全局安装，可以用固定版本覆盖安装。

```bash
# 停止 Gateway
openclaw gateway stop

# 安装推荐版本
npm install -g openclaw@2026.9.3 --allow-scripts=openclaw

# 修复更新后的插件/配置收敛状态
openclaw update repair
openclaw doctor --fix

# 重启并验证
openclaw gateway restart
openclaw --version
openclaw gateway status
openclaw channels status
```

如果你不想固定版本，也可以使用：

```bash
npm install -g openclaw@latest --allow-scripts=openclaw
```

### 方式三：官方安装脚本

如果你是首次安装，或希望安装器自动处理 Node、路径和 onboarding，可以继续使用官方脚本：

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```

如果只想安装 CLI、不立即跑 onboarding：

```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
```

### 方式四：Docker / 云端部署

Docker 部署通常按镜像更新：

```bash
docker compose down
docker compose pull
docker compose up -d

docker compose logs -f
```

云端一键镜像、面板插件或第三方托管版本，需要进入对应控制台查看镜像版本。不要只看网页 UI 是否能打开，一定要确认后端 OpenClaw 版本。

### 升级后验证清单

```bash
openclaw --version
node -v
openclaw doctor
openclaw gateway status
openclaw channels status
openclaw models status
openclaw models status --probe
openclaw skills check
```

跨大版本后若仍有旧路由/插件残留，再跑一次：

```bash
openclaw doctor --fix
```

看到下面结果，才算升级基本完成：

- `openclaw --version` 返回 `2026.9.3` 或你指定的新版本
- `openclaw doctor` 没有阻塞级错误
- `openclaw gateway status` 显示 Gateway 正常运行
- `openclaw channels status` 能看到你需要的渠道状态
- `openclaw models status --probe` 没有明显认证失败

### 2026.9.3 升级后重点验证

从旧基线跳到 `v2026.9.3`，优先确认这些主线变化（而不是只核对版本号）：

- **Node 运行时**：需要 Node **24.16+** 或 **26.1+**（推荐 26）；升级 OpenClaw 前先升级 Node
- **Doctor 迁移**：`openclaw doctor --fix`（OpenAI 路由、`OpenProse` 清理、会话/状态修复）
- **会话存储**：`2026.8.1` 起会话/转录进入 SQLite——**不要在未备份时降级**
- **Skills / Workshop**：优先 `openclaw skills …`；Workshop 技能按 Agent 持久化；旧 `clawhub install …` 仅作历史参考
- **更新恢复**：`2026.9.x` 支持更新预演与更干净的失败恢复；可用 `openclaw update status` 查看报告

建议升级后至少做这组 smoke test：

```bash
node -v
openclaw --version
openclaw doctor
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
openclaw models status --probe
openclaw gateway status
openclaw channels status
```

### 常见升级问题

#### npm 报 EEXIST

```bash
npm install -g openclaw@2026.9.3 --allow-scripts=openclaw
```

#### Gateway 启动失败

```bash
openclaw update repair
openclaw doctor --fix
openclaw gateway restart
tail -f ~/.openclaw/logs/gateway.log
```

#### 配置由更高版本写入

这通常说明你正在用旧 CLI 读取新配置。先升级 CLI，再运行 repair 和 doctor：

```bash
npm install -g openclaw@2026.9.3 --allow-scripts=openclaw
openclaw update repair
openclaw doctor --fix
```

#### 端口被占用

```bash
lsof -i :18789
kill -9 <PID>

# 或换端口
openclaw config set gateway.port 18790
openclaw gateway restart
```

### 回滚建议

回滚可能导致新版本写入的配置无法被旧版本识别，所以只在确实无法恢复时使用。优先从备份恢复配置，再安装目标版本。

```bash
openclaw gateway stop
cp -r ~/.openclaw.backup-YYYYMMDD-HHMMSS/* ~/.openclaw/
npm install -g openclaw@<target-version> --force
openclaw doctor
openclaw gateway restart
```

### 升级节奏建议

- 普通用户：每月检查一次 `npm view openclaw version`
- 生产环境：先在测试机升级，跑完 smoke test 再动主环境
- 安全修复或渠道故障修复：优先升级
- 正在跑重要自动化时：先暂停任务、备份，再升级

---

## 本章节小结

通过本章节，你应该已经：

✅ 了解了云端部署和本地部署的区别  
✅ 完成了OpenClaw的安装（云端或本地）  
✅ 配置了API（推荐国产大模型）  
✅ 验证了安装是否成功  
✅ 学会了如何升级OpenClaw

## 实战练习

1. 完成OpenClaw安装（云端或本地）
2. 配置至少一个API（推荐DeepSeek或Kimi）
3. 发布送第一条测试消息
4. 验证AI是否正常回复
5. 检查当前版本，如有更新可尝试升级

---

**下一章节**：[第3章节：快速上手](03-quick-start.md) - 开始使用 OpenClaw

**返回目附录**：[README](../../README.md)


---

## 🌐 在线阅读

📖 **想在线阅读此章节节？**

[🔗 在线阅读此章节节](https://awesome.tryopenclaw.asia/docs/01-basics/02-installation/)

访问网站获取更好的阅读体验：
- 📱 响应式设计，支持手机、平板、电脑
-  支持黑暗模式，保护眼睛
- 🔍 内置搜索功能，快速定位内内容
- 📋 目附录导航，轻松跳转章节节

[🏠 访问完整教网站](https://awesome.tryopenclaw.asia)