第2章:环境搭建

本章将手把手教你安装 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. 选择配置

  3. 实名认证

  4. 完成购买

  5. 获取服务器信息

腾讯云Lighthouse控制台 - 创建实例界面

💡 免费白嫖方案(可选)

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

步骤

  1. 注册 CodeBuddy

  2. 领取奖励

  3. 重装系统为OpenClaw

  4. 后续操作

第二步:连接服务器

  1. 使用SSH客户端连接

    方式一:使用SSH客户端(推荐)

    方式二:使用网页终端

  2. 验证OpenClaw安装

    openclaw --version

    如果显示版本号(如 2026.3.2),说明OpenClaw已预装成功。

OpenClaw镜像

第三步:配置大模型

  1. 进入应用管理

  2. 选择模型

选择AI供应商

  1. 获取API Key

    Kimi k2.5配置(推荐):

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

第四步:测试连接

  1. 访问WebUI

  2. 发送测试消息

    你好,能听到我说话吗?
    

测试对话

  1. 验证成功

火山引擎部署(更便宜)

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

  1. 访问活动页面

    https://www.volcengine.com/activity/clawdbot
    
  2. 价格优势

  3. 配置对比

  4. 部署流程

百度智能云部署(0.01元试用)

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

活动信息

  1. 访问活动页面

    https://cloud.baidu.com/product/BCC/moltbot.html
    
  2. 活动规则

部署步骤

第一步:购买服务器

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

第二步:创建实例

  1. 进入轻量应用服务器LS控制台
  2. 点击"创建实例":
  3. 等待实例创建完成

第三步:一键配置 OpenClaw

  1. 进入实例详情页

  2. 应用配置

  3. 模型配置

  4. 接入方式配置(可选):

  5. Skills 配置(可选):

第四步:访问WebUI

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

优势与限制

优势

限制

阿里云部署(可选)

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

  1. 访问活动页面

    https://www.aliyun.com/activity/ecs/clawdbot
    
  2. 选择轻量应用服务器

阿里云轻量服务器

  1. 价格参考

官方视频教程(强烈推荐)

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

  1. 云上OpenClaw一键部署并接入企微和QQ

  2. 云上OpenClaw一键部署并接入飞书和钉钉

存量服务器部署

如果你已经有轻量服务器,可以使用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

Cloudflare Workers 部署

第二步:等待构建

构建过程

第三步:配置 Access(Zero Trust)

访问网页界面需要配置 CF_ACCESS_AUDCF_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. 进入设置

  2. 填入变量

  3. 重新部署

注入变量

访问与管理

部署完成后,可通过以下地址访问:

访问 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. 使用非内置模型

  2. 使用第三方代理

  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-keybearer
api API协议 openai-chatanthropic-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. 测试频道连接

  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. 加入社区

升级案例: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

返回目录首页