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

OpenClaw 安装界面

📋 前提条件与推荐配置

推荐配置

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

操作系统：

IM工具选择：

部署方式：

为什么推荐Mac？

OpenClaw在Mac上体验最好，因为：

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

为什么推荐Telegram（国外）？

快速导航

推荐路径：

所有部署方式：

配置指南：

Mac本地部署（推荐）

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

为什么选择Mac本地部署？

优势：

适合人群：

系统要求

硬件要求：

系统版本：

前置软件：

安装步骤

第一步：打开终端

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

Mac终端打开方式 - 通过Spotlight搜索Terminal

第二步：安装 OpenClaw

在终端中执行以下命令：

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

安装过程会自动：

预计时间：2-5分钟

第三步：验证安装

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

openclaw --version

如果显示版本号（如 2026.3.2），说明安装成功！

第四步：初始化配置

运行配置向导：

openclaw onboard

配置流程：

1. 接受风险提示：

选择 Yes 继续

安装向导 - 接受风险提示

2. 选择启动模式：

推荐选择 QuickStart 快速启动：

安装向导 - 选择QuickStart快速启动模式

3. 选择AI模型：

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

安装向导 - 选择AI模型供应商

国内推荐：

4. 输入API Key：

根据选择的模型，输入对应的API Key（参见API配置指南）

5. 选择聊天工具：

安装向导 - 选择聊天平台（飞书/企微/QQ等）

6. Gateway端口设置：

默认 18789 即可：

安装向导 - Gateway端口配置（默认18789）

7. 选择Skills：

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

安装向导 - 选择需要安装的技能包

8. API Key配置：

没有的可以选择 no 跳过：

安装向导 - 配置AI模型API 密钥

9. 启用Hooks：

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

安装向导 - 启用自动化钩子功能

10. 完成配置：

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

第五步：验证安装

# 检查Gateway状态
openclaw channels status

# 应该显示：
# Gateway reachable.

日常使用

启动OpenClaw：

# 启动Gateway服务
openclaw gateway start

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

访问Web UI：

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

停止服务：

openclaw gateway stop

接入飞书（推荐）

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

  1. 参考 第9章节：飞书Bot配置
  2. 配置完成后，可以在飞书中随时与OpenClaw对话
  3. 支持文本、图片、文件等多种消息类型

常见访问题

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

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

Q2：如何更新OpenClaw？

openclaw update

Q3：如何卸载？

openclaw uninstall

Windows本地部署

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

Windows系统部署架构 - WSL2+Ubuntu方案

系统要求

硬件要求：

操作系统：

前置软件：

部署方式选择

Windows有两种部署方式：

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

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

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

第一步：启用WSL2

以管理员身份打开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终端中执行：

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

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

第四步：安装Node.js 22+

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

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

# 验证版本（必须≥22.x）
node -v
npm -v

第五步：安装 OpenClaw

方法A：一键脚本安装

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

第六步：验证安装

# 查看版本
openclaw --version

# 查看帮助
openclaw --help

# 查看系统状态
openclaw status

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

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

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

@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中启动：

# 在WSL2 Ubuntu终端中
openclaw gateway run --port 18789

然后在Windows浏览器访问 http://localhost:18789

方式二：PowerShell原生部署

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

第一步：安装Node.js 22+

方法一：官网下载安装

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

第二步：验证Node.js安装

# 打开PowerShell
node -v
npm -v

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

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

# 安装最新稳定版
npm install -g openclaw@latest

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

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

如果遇到权限错误：

# 方法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")

第五步：验证安装

openclaw --version
openclaw --help

第六步：解决常见访问题

访问题：sharp模块加载失败

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

# 重新安装
npm install -g openclaw@latest --force

访问题：Windows Defender阻止

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

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

初始化配置

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

启动初始化向导

openclaw onboard --install-daemon

配置AI模型提供商

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

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

📖 详细说明: 完整的 API Key 配置方式和优先级说明请参考 API Key 配置完整指南

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

绑定消息渠道

1. Telegram

创建Bot：

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

配置：

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

2. WhatsApp

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

# 用手机WhatsApp扫码

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

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

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

4. 飞书（国内推荐）

# 安装飞书插件
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用户：适合开发布者，配置灵活。

系统要求

推荐发布行版：

安装步骤

第一步：安装Node.js

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

# 验证安装
node --version

第二步：安装 OpenClaw

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

第三步：验证安装

openclaw --version

第四步：初始化配置

openclaw onboard

2.1 系统要求与准备

云端部署要求

如果选择云端部署，无需任何本地环境，只需要：

云端一键部署

🔥 适合场景：无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控制台 - 创建实例界面

💡 免费白嫖方案（可选）

如果你想免费试用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安装：

    openclaw --version

    如果显示版本号（如 2026.3.2），说明OpenClaw已预装成功。

OpenClaw镜像

第三步：配置大模型

  1. 进入应用管理：
    • 点击服务器卡片
    • 切换到”应用管理”标签
  2. 选择模型：
    • 推荐使用 Kimi k2.5（性价比最高）
    • 也可以选择其他国产大模型

选择AI供应商

  1. 获取API Key：

    Kimi k2.5配置（推荐）：

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

  2. 填入配置：

    • 将API Key粘贴到配置框
    • 点击”保存”
    • 等待配置生效

第四步：测试连接

  1. 访问WebUI：
    • 使用控制台提供的访问地址
    • 格式：http://你的服务器IP:18789/?token=xxx
  2. 发布送测试消息： 
    你好，能听到我说话吗？

测试对话

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

火山引擎部署（更便宜）

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

  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对话

优势与限制

优势：

限制：

阿里云部署（可选）

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

  1. 访问活动页面： 
    https://www.aliyun.com/activity/ecs/clawdbot
  2. 选择轻量应用服务器：
    • 使用 OpenClaw镜像
    • 一键安装配置

阿里云轻量服务器

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

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

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

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

存量服务器部署

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

云端部署常见访问题

Q1: 云端部署安全吗？

Q2: 可以随时停止吗？

Q3: 手机怎么访问？

国内一键安装（推荐）

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

为什么选择国内版？

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

表 2-3 国内版优势

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

image-20260213122830687

前置要求

必需环境：

推荐配置：

系统要求：

快速开始

macOS/Linux 安装

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

Windows 安装

使用 PowerShell（管理员权限）：

# 使用国内官方安装脚本
iwr -useb https://clawd.org.cn/install.ps1 | iex

⚠️ Windows 用户注意：强烈推荐使用 WSL2（Ubuntu），原生 Windows 支持有限。

WSL2 安装步骤：

# 1. 安装 WSL2
wsl --install

# 2. 重启电脑

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

全局安装（替代方案）

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

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

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

运行入门向导

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

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

配置向导流程

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

1. 选择网关模式：

2. 配置认证：

3. 选择 AI 提供商：

4. 配置聊天平台（可选）：

5. 安装后台服务（推荐）：

6. 网关令牌：

认证配置说明

认证存储位置（重要）：

无头/服务器提示：

启动 Gateway

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

# 检查 Gateway 状态
openclaw-cn gateway status

手动运行（前台）：

# 在前台运行，查看实时日志
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分钟）

# 检查状态
openclaw-cn status

# 健康检查
openclaw-cn health

配对 + 连接聊天界面

WhatsApp（二维码登录）

# 登录 WhatsApp
openclaw-cn channels login

通过 WhatsApp → 设置 → 已连接的设备 扫描二维码。

Telegram / Discord / 其他

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

Telegram：

openclaw-cn channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"

Discord：

openclaw-cn channels add \
  --channel discord \
  --token "YOUR_BOT_TOKEN"

💡 Telegram 私信提示：首次私信会返回配对码，需要批准后机器人才会响应。

私信安全（配对审批）

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

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

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

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

从源码运行（开发布）

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

# 克隆仓库
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：

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

端到端验证

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

# 发布送测试消息
openclaw-cn message send --target +15555550123 --message "Hello from OpenClaw"

如果 openclaw-cn health 显示 “no auth configured”，需要返回向导设置 OAuth/密钥认证。

调试提示：

配置文件位置

📖 详细说明: 完整的配置文件结构和使用指南请参考 配置文件结构完整指南

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

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

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

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

国内版特色功能

1. 预配置国产模型：

2. 国内平台集成：

3. 优化的网络配置：

常见访问题

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

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

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

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

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

Q3: 如何卸载？

# 停止服务
openclaw-cn gateway stop

# 卸载
npm uninstall -g openclaw-cn

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

Q4: 支持哪些系统？

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

# 按 Ctrl+C 中断

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

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

Q6: 健康检查显示 “no auth configured”

需要配置认证：

# 重新运行向导
openclaw-cn onboard

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

下一步（可选，但很棒）

下一步

安装完成后，可以：

  1. 配置 AI 模型（见下文”API配置指南”）
  2. 连接聊天平台（见第9章节：多平台集成）
  3. 安装 Skills（见第8章节：Skills扩展）
  4. 开始使用（见第3章节：快速上手)

Cloudflare Workers 部署（进阶）

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

为什么选择 Cloudflare Workers？

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

表 2-4 Cloudflare Workers 优势

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

前置要求

必需条件：

成本说明：

💡 成本参考：详见 GitHub 讨论：What’s the cost running it 24/7 for a month

部署流程

第一步：一键部署 Moltworker

  1. 点击部署按钮： 
    https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/moltworker
  2. 配置 Gateway Token：
    • 务必修改并妥善保存 MOLTBOT_GATEWAY_TOKEN
    • 这是后续进入管理后台的唯一凭证
    • 建议使用强密码生成器

Cloudflare Workers 部署

第二步：等待构建

构建过程

第三步：配置 Access（Zero Trust）

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

1. 创建应用：

创建应用

2. 设置域名：

3. 配置策略：

4. 获取配置变量：

CF_ACCESS_AUD：

CF_ACCESS_TEAM_DOMAIN：

第四步：配置 R2 对象存储

OpenClaw 需要 R2 来存储状态，需配置以下三个变量：

操作步骤：

1. 获取 Account ID：

获取 Account ID

2. 创建 API 令牌：

3. 设置权限：

设置权限

4. 保存密钥：

保存密钥

⚠️ 重要提示：修改 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 重新部署
    • 等待部署完成

注入变量

访问与管理

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

访问 Worker（需要 token）：

https://moltbot-sandbox.xxxxxxxx.workers.dev?token=MOLTBOT_GATEWAY_TOKEN

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

https://moltbot-sandbox.xxxxxxxx.workers.dev/_admin/

通过 Cloudflare Access 的邮箱验证码验证后，即可进入管理后台并接受 Pairing Requests。

管理后台

基础使用

查看或切换模型

# 查看当前模型
/model

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

设置开机自启命令

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

set model minimax/MiniMax-M2.1

远程终端连接

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

# 配置 Skills
openclaw configure --section skills

避坑指南

访问题 1：模型配置报错

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

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

解决方案：

访问题 2：Worker 构建失败

症状：部署后 Worker 无法启动

原因：不慎修改了 Build Token

解决方案：

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

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

原因：Zero Trust 配置不正确

解决方案：

成本估算

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

适用场景

推荐使用：

不推荐使用：

总结

Cloudflare Workers + OpenClaw 是一个低成本的尝鲜方案，适合：

但需要注意：

下一步：

Docker 部署（可选）

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

为什么选择 Docker？

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

表 2-5 Docker 部署优势

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

前置要求

安装 Docker：

macOS：

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

# 或使用 Homebrew
brew install --cask docker

Windows：

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

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

Linux (Ubuntu)：

# 安装 Docker
curl -fsSL https://get.docker.com | sh

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

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

验证安装：

docker --version
# 应显示：Docker version 24.x.x

快速开始

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

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

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

这个脚本会自动：

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

脚本后续操作：

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

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

步骤 1：创建工作目附录

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

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

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 文件

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：启动内容器

# 拉取最新镜像
docker compose pull

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

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

步骤 5：运行配置向导

docker compose run --rm openclaw-cn-cli onboard

配置向导会提示你：

步骤 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 文件（推荐）

# 编辑 .env 文件
nano .env

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

方式 B：命令行设置

export OPENCLAW_GATEWAY_PORT=18789
docker compose up -d

方式 C：命令行临时覆盖

docker compose -e OPENCLAW_GATEWAY_PORT=8080 up -d

常用操作

查看网关状态

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

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

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

配置渠道

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

Telegram（需要机器人令牌）：

docker compose run --rm openclaw-cn-cli channels add \
  --channel telegram \
  --token "YOUR_BOT_TOKEN"

Discord（需要机器人令牌）：

docker compose run --rm openclaw-cn-cli channels add \
  --channel discord \
  --token "YOUR_BOT_TOKEN"

WhatsApp（QR 扫码）：

docker compose run --rm openclaw-cn-cli channels login

Feishu（需要 App ID 和 Secret）：

docker compose run --rm openclaw-cn-cli onboard
# 按提示输入信息

重新配置

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

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

重启网关

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

# 停止网关
docker compose down

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

更新到最新版本

# 拉取最新镜像
docker compose pull

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

清理数据（谨慎操作）

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

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

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

数据支持久化

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

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

备份数据：

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

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

Docker 部署常见访问题

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

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

解决方案：

# 查看详细错误日志
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 ...

解决方案：

# 确保数据目附录存在且权限正确
mkdir -p ./data/.openclaw ./data/clawd
chmod 755 ./data/.openclaw ./data/clawd

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

访问题 3：无法访问 Web UI

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

解决方案：

# 检查内容器是否运行
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 无反应

解决方案：

# 按 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 错误

解决方案：

# 使用国内镜像（推荐）
docker pull jiulingyun803/openclaw-cn:latest

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

# 重新拉取
docker compose pull

访问题 6：网络超时

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

解决方案：

# 配置 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：数据丢失

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

解决方案：

# 确保使用了数据卷挂载
# 检查 docker-compose.yml 中的 volumes 配置

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

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

访问题 8：性能访问题

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

解决方案：

# 限制资源使用（编辑 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

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

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

# 停止现有内容器
docker compose down

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

# 更新 .env 和 docker-compose.yml

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

配置会自动保留在数据目附录中，无需重新设置。

Docker 部署优势总结

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

推荐使用场景：

下一步：

更新和维护

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

检查更新

# 检查当前版本
openclaw --version

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

本地安装更新

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

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

Docker 更新

# 拉取最新镜像
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

备份数据

本地安装备份：

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

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

Docker 备份：

# 备份数据卷
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 /

监控和日志

查看日志：

# 本地安装
tail -f ~/.openclaw/logs/gateway.log

# Docker
docker logs -f openclaw

监控指标：

# 查看系统状态
openclaw gateway status

# 查看资源使用
openclaw stats

# 查看 API 消耗
openclaw stats api

故障排查

常见访问题：

  1. Gateway 无法启动 
    # 查看日志
openclaw logs

# 检查端口占用
lsof -i :18789

# 重启 Gateway
openclaw gateway restart
  2. API 连接失败 
    # 测试 API 连接
openclaw test api

# 检查 API Key
openclaw config get models.providers
  3. 性能访问题 
    # 清理缓存
openclaw cache clear

# 重启服务
openclaw gateway restart

卸载

本地安装卸载：

# 停止服务
openclaw gateway stop

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

# 删除命令
npm uninstall -g openclaw

Docker 卸载：

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

# 删除镜像
docker rmi openclaw/openclaw

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

API配置指南

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

为什么需要API？

OpenClaw本身不包含AI模型，需要连接第三方API：

API模型分类

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

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

什么是内置API模型？

OpenClaw已经预先配置好了多个主流AI模型的连接方式，你只需要：

支持的内置模型：

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

内置API模型列表

国内模型（推荐）：

国外模型：

优势：

使用场景：

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

什么是自定义API？

如果你想使用：

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

配置方式：

需要手动编辑配置文件 ~/.openclaw/openclaw.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. 精细控制参数：
    • 自定义模型参数
    • 调整上下文窗口大小
    • 修改默认配置

配置文件位置

📖 详细说明: 完整的配置文件结构和使用指南请参考 配置文件结构完整指南

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

# 编辑配置文件
nano ~/.openclaw/openclaw.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（自定义方式）

{
  "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），配置如下：

{
  "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：配置多个模型供应商

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

{
  "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协议类型

配置后重启服务

# 方式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

验证配置

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

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

常见访问题

Q1：配置后无法连接？

检查项：
✅ baseUrl是否正确
✅ apiKey是否有效
✅ 网络是否能访问API地址
✅ 配置文件JSON格式是否正确

Q2：如何切换模型？

# 临时切换
openclaw agent --message --model deepseek/deepseek-chat

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

Q3：如何添加多个模型？

在 models 数组中添加多个模型对象即可
每个模型需要有唯一的 id

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

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

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

1. Kimi 2.5 配置（推荐）

特点：

配置步骤：

第一步：访问Kimi Code平台

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

Kimi Code平台

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

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

推荐套餐：

购买套餐

第三步：创建API Key

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

创建API Key

第四步：保存API Key

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

保存API Key

第五步：配置到OpenClaw

# 运行配置向导
openclaw onboard

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

成本估算：

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

特点：

配置步骤：

第一步：注册并充值

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

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

DeepSeek平台

第二步：充值账户

建议先充值10元试用：

充值账户

第三步：创建API Key

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

创建API Key

第四步：保存API Key

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

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

保存API Key

第五步：配置到OpenClaw

# 运行配置向导
openclaw onboard

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

成本估算：

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

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

特点：

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

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

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

img

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

img

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

img

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

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

img

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

配置步骤：

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

  2. 获取API Key：

    进入"API管理"
点击"创建API Key"
复制API Key（格式：sk-xxx）
  3. 配置到OpenClaw： 
    # 编辑配置文件
nano ~/.openclaw/openclaw.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： 
    openclaw gateway restart

成本估算：

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

特点：

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

img

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

img

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

img

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

img

配置步骤：

  1. 注册账号： 
    访问：https://platform.moonshot.cn/
注册并登录
  2. 获取API Key： 
    进入"API管理"
点击"创建API Key"
复制API Key
  3. 配置到OpenClaw： 
    {
  "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"
      }
    }
  }
}

成本估算：

3. 其他国产大模型

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

国际模型配置（可选）

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

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

推荐第三方API：

成本对比

模型 输入价格 输出价格 月费用估算
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元

💡 省钱技巧：

常见访问题解决

安装访问题

Q1: Node.js版本不对

# 检查版本
node --version

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

Q2: 权限错误

# macOS/Linux
sudo chown -R $USER ~/.openclaw

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

Q3: 网络连接失败

API配置访问题

Q1: API Key无效

Q2: 模型不可用

Q3: Token消耗太快

Gateway访问题

Q1: Gateway无法启动

# 查看日志
tail -f ~/.openclaw/logs/gateway.log

# 重启Gateway
openclaw gateway restart

Q2: 端口被占用

# 查看端口占用
lsof -i :18789

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

2.X 版本升级指南

🔄 保支持最新：定期升级OpenClaw以获得新功能、性能优化和安全修复。

⚠️ 重要提示：目前推荐使用 2026.3.2 版本。2026.2.12 版本存在已知 bug（Issue #15141），会导致 heartbeat 和消息处理功能异常。

推荐版本

当前推荐版本：2026.3.2

已知访问题版本：

为什么要升级？

OpenClaw支持续迭代更新，升级可以获得：

检查当前版本

# 查看当前版本
openclaw --version

# 查看配置文件版本
cat ~/.openclaw/openclaw.json | grep version

如果配置文件版本比当前版本新，说明需要升级。

升级方式选择

根据你的安装方式选择对应的升级方法：

安装方式 升级方法 难度 推荐度
云端部署 重新部署镜像 ⭐ ⭐⭐⭐⭐⭐
Docker 拉取新镜像 ⭐⭐ ⭐⭐⭐⭐⭐
本地安装（npm） npm升级 ⭐⭐⭐ ⭐⭐⭐⭐
本地安装（源码） git pull ⭐⭐⭐⭐ ⭐⭐⭐

方式一：npm直接升级（推荐）

这是最可靠的升级方式，适用于通过npm安装的用户。

升级步骤

第一步：备份配置

# 备份整个配置目附录
cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d)

# 验证备份
ls -la ~/.openclaw.backup-*

第二步：停止Gateway服务

# 停止Gateway
openclaw gateway stop

# 验证已停止
openclaw gateway status

第三步：卸载旧版本

# 卸载旧版本
npm uninstall -g openclaw

# 验证卸载
which openclaw  # 应该没有输出

第四步：安装新版本

# 安装推荐版本 2026.3.2（需要使用--force参数）
npm install -g openclaw@2026.3.2 --force

⚠️ 版本选择说明：

⚠️ 为什么需要–force？ npm会检测到已存在的文件，使用--force强制覆盖。

第五步：修复配置

# 运行doctor工具自动修复配置
openclaw doctor --fix

doctor工具会自动：

第六步：重启Gateway

# 重启Gateway
openclaw gateway restart

# 等待几秒后检查状态
sleep 5
openclaw gateway status

第七步：验证升级

# 检查版本
openclaw --version

# 检查Gateway状态
openclaw gateway status

# 测试连接
openclaw channels status

成功的输出应该显示：

2026.3.2

Runtime: running (pid xxxxx, state active)
RPC probe: ok
Listening: *:18789
Dashboard: http://127.0.0.1:18789/

升级示例

以下是一次真实的升级过程：

升级前版本检查

图：升级前版本检查，配置文件版本(2026.2.6-3)比当前版本(2026.2.1-zh.3)新

npm安装过程

图：使用npm install –force安装新版本

升级完成验证

图：升级完成，版本更新到2026.3.2

方式二：官方脚本升级

使用官方提供的一键升级脚本。

# 运行升级脚本
curl -fsSL https://openclaw.ai/install.sh | bash

优点：

缺点：

如果遇到错误：

方式三：Docker升级

如果使用Docker部署，升级非常简单。

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

# 拉取最新镜像
docker compose pull

# 启动新内容器
docker compose up -d openclaw-cn-gateway

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

方式四：云端部署升级

腾讯云Lighthouse

  1. 进入轻量应用服务器控制台
  2. 选择你的OpenClaw实例
  3. 点击”重置应用”
  4. 选择最新的OpenClaw镜像
  5. 等待重置完成
  6. 重新配置API（配置会保留）

升级后的变化

配置文件自动迁移

升级后，doctor工具会自动：

服务管理改进

macOS：

Linux：

已知警告

升级后可能看到一些警告，这些通常不影响使用：

Config warnings:
- plugins.entries.feishu: plugin feishu: duplicate plugin id detected

说明：这是一个已知的插件重复警告，不影响正常使用。

升级故障排查

访问题1：npm install报错EEXIST

症状：

npm error code EEXIST
npm error path /usr/local/bin/openclaw
npm error EEXIST: file already exists

解决方案：

# 使用--force参数强制覆盖
npm install -g openclaw@2026.3.2 --force

访问题2：Gateway启动失败

症状：

Gateway not running

解决方案：

# 运行doctor修复
openclaw doctor --fix

# 重启Gateway
openclaw gateway restart

# 查看详细日志
tail -f ~/.openclaw/logs/gateway.log

访问题3：配置文件版本不匹配

症状：

Config was last written by a newer OpenClaw (2026.2.6-3);
current version is 2026.2.1-zh.3

解决方案：

# 升级到推荐版本 2026.3.2
npm install -g openclaw@2026.3.2 --force
openclaw doctor --fix

访问题4：插件加载失败

症状：

plugin not found: xxx

解决方案：

# 重新安装插件
openclaw plugins install <plugin-name>

# 或禁用有访问题的插件
openclaw config set plugins.allow []

访问题5：端口被占用

症状：

Error: listen EADDRINUSE: address already in use :::18789

解决方案：

# 查找占用端口的进程
lsof -i :18789

# 停止旧的Gateway进程
kill -9 <PID>

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

回滚到旧版本

如果升级后遇到访问题，可以回滚到旧版本。

方式一：从备份恢复

# 停止Gateway
openclaw gateway stop

# 恢复配置
cp -r ~/.openclaw.backup-20260213/* ~/.openclaw/

# 降级到旧版本（以中文版为例）
npm uninstall -g openclaw
npm install -g @qingchencloud/openclaw-zh@2026.2.1-zh.3 --force

# 重启Gateway
openclaw gateway restart

方式二：安装指定版本

# 查看可用版本
npm view openclaw versions

# 安装指定版本
npm install -g openclaw@2026.2.8 --force

# 修复配置
openclaw doctor --fix

# 重启Gateway
openclaw gateway restart

升级最佳实践

升级前必做

  1. 备份配置： 
    cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d)
  2. 记附录当前版本： 
    openclaw --version > ~/openclaw-version-before-upgrade.txt
  3. 导出重要配置： 
    openclaw config get > ~/openclaw-config-backup.json
  4. 检查磁盘空间： 
    df -h ~

升级时注意

  1. 使用–force参数： 
    npm install -g openclaw@2026.3.2 --force
  2. 运行doctor修复： 
    openclaw doctor --fix
  3. 检查Gateway状态： 
    openclaw gateway status
  4. 查看日志： 
    tail -f ~/.openclaw/logs/gateway.log

升级后验证

  1. 检查版本号： 
    openclaw --version
  2. 测试Gateway连接： 
    openclaw channels status
  3. 验证插件功能： 
    openclaw plugins list
  4. 测试频道连接：
    • 发布送测试消息
    • 验证AI回复
    • 检查Skills功能
  5. 检查API消耗： 
    openclaw stats api

已知访问题版本警告

2026.2.12 版本访问题

不推荐使用 2026.2.12 版本，该版本存在严重 bug：

访问题描述：

影响范围：

官方 Issue：

解决方案：

  1. 不要升级到 2026.2.12
  2. 如果已升级，回退到 2026.3.2： 
    openclaw gateway stop
npm uninstall -g openclaw
npm install -g openclaw@2026.3.2 --force
openclaw doctor --fix
openclaw gateway restart

推荐做法：

升级时间建议

推荐升级时机：

不推荐升级时机：

自动更新（可选）

如果想自动检查更新，可以设置定时任务。

macOS/Linux：

# 编辑crontab
crontab -e

# 添加每周检查更新（周日凌晨2点）
0 2 * * 0 /usr/local/bin/openclaw doctor --check-updates

Windows： 使用任务计划程序创建定时任务。

版本发布布说明

查看每个版本的更新内内容：

# 访问GitHub发布布页面
https://github.com/openclaw/openclaw/releases

# 或使用命令行
curl -s https://api.github.com/repos/openclaw/openclaw/releases/latest

升级成本估算

升级方式 时间成本 风险等级 推荐度
npm直接升级 5-10分钟 低 ⭐⭐⭐⭐⭐
官方脚本 3-5分钟 中 ⭐⭐⭐⭐
Docker 2-3分钟 低 ⭐⭐⭐⭐⭐
云端重置 5-10分钟 中 ⭐⭐⭐

升级检查清单

升级前：

升级中：

升级后：

升级支持

如果升级遇到访问题：

  1. 查看日志： 
    tail -f ~/.openclaw/logs/gateway.log
  2. 运行诊断： 
    openclaw doctor
  3. 查看官方文档： 
    https://docs.openclaw.ai/
  4. 加入社区：
    • GitHub Issues
    • Discord社区
    • 飞书群组

升级案例：2026.2.1-zh.3 → 2026.3.2

以下是一次真实的升级案例，供参考。

升级背景：

升级过程：

  1. 备份配置： 
    cp -r ~/.openclaw ~/.openclaw.backup-20260213
  2. 停止Gateway： 
    openclaw gateway stop
  3. 卸载旧版本： 
    npm uninstall -g openclaw
  4. 安装新版本： 
    npm install -g openclaw@2026.3.2 --force
  5. 修复配置： 
    openclaw doctor --fix
  6. 重启Gateway： 
    openclaw gateway restart
  7. 验证升级： 
    openclaw --version  # 显示：2026.3.2
openclaw gateway status  # 显示：running

升级结果：

遇到的访问题：

总耗时：约5分钟

本章节小结

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

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

实战练习

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

下一章节：第3章节：快速上手 - 开始使用 OpenClaw

返回目附录：README

🌐 在线阅读

📖 想在线阅读此章节节？

🔗 在线阅读此章节节

访问网站获取更好的阅读体验：

🏠 访问完整教网站