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

第2章节：环境搭建

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

⚠️ 当前基线：截至 2026-06-18，本教程推荐使用 OpenClaw v2026.6.8（稳定版，2026-06-16 发布）。运行时优先使用 Node 24；如果自行管理 Node，至少使用 Node 22.19+。

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.6.8），说明安装成功！

第四步：初始化配置

运行配置向导：

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 24（推荐）

# 添加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：一键脚本安装

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 24（推荐）

方法一：官网下载安装

  1. 访问 https://nodejs.org/zh-cn
  2. 下载Windows安装包（推荐 24.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_24.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.6.8），说明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回复，说明配置成功
    • 右上角会显示使用的模型名称

腾讯龙虾产品矩阵（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 (微信插件)              │
└──────────┴──────────┴───────────────────┘

使用建议：

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

优势与限制

优势：

限制：

阿里云部署（可选）

阿里云也提供了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 status --usage

故障排查

常见访问题：

  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 迭代很快，升级通常会带来安全修复、provider 兼容性修复、渠道稳定性改进和新模型目录。

⚠️ 当前推荐版本：截至 2026-06-18，本教程推荐使用 OpenClaw 2026.6.8（稳定版）。升级前先备份 ~/.openclaw；升级后先运行 openclaw update repair、openclaw doctor 和状态检查。

推荐版本

当前推荐版本：2026.6.8

版本确认命令：

npm view openclaw version
openclaw --version

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

升级前必做

# 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 是 2026.6 CLI 的统一升级入口。全局 npm 安装会通过检测到的包管理器更新；source checkout 会走 git 更新、依赖安装、构建和 doctor 流程。

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

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

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

升级完成后：

openclaw update repair
openclaw doctor
openclaw gateway restart
openclaw --version
openclaw gateway status
openclaw channels status

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

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

# 停止 Gateway
openclaw gateway stop

# 安装推荐版本
npm install -g openclaw@2026.6.8 --force

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

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

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

npm install -g openclaw@latest

方式三：官方安装脚本

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

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

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

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

方式四：Docker / 云端部署

Docker 部署通常按镜像更新：

docker compose down
docker compose pull
docker compose up -d

docker compose logs -f

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

升级后验证清单

openclaw --version
openclaw doctor
openclaw gateway status
openclaw channels status
openclaw models status
openclaw models status --probe
openclaw skills check

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

2026.6.8 升级后重点验证

v2026.6.8 的重点不是“换一个版本号”，而是这些能力更稳了：

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

openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
openclaw infer web search --query "OpenClaw v2026.6.8 release notes" --json
openclaw models status --probe
openclaw gateway status

常见升级问题

npm 报 EEXIST

npm install -g openclaw@2026.6.8 --force

Gateway 启动失败

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

配置由更高版本写入

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

npm install -g openclaw@2026.6.8 --force
openclaw update repair
openclaw doctor

端口被占用

lsof -i :18789
kill -9 <PID>

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

回滚建议

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

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

升级节奏建议

本章节小结

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

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

实战练习

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

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

返回目附录：README

🌐 在线阅读

📖 想在线阅读此章节节？

🔗 在线阅读此章节节

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

🏠 访问完整教网站