OpenClaw 教程

主题

第2章：环境搭建 ​

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

OpenClaw 安装界面

📋 前提条件与推荐配置 ​

推荐配置 ​

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

操作系统：

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

IM工具选择：

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

部署方式：

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

为什么推荐Mac？ ​

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

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

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

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

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

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

快速导航 ​

推荐路径：

所有部署方式：

配置指南：

Mac本地部署（推荐） ​

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

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

优势：

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

适合人群：

  • 有Mac电脑的用户
  • 注重隐私的用户
  • 需要系统集成功能的用户
  • 开发者和技术爱好者

系统要求 ​

硬件要求：

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

系统版本：

  • macOS 12 Monterey 或更高版本
  • 推荐 macOS 14 Sonoma 或 macOS 15 Sequoia

前置软件：

  • Node.js 22.0.0+（会自动安装）
  • Homebrew（可选，用于安装依赖）

安装步骤 ​

第一步：打开终端 ​

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

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

第二步：安装 OpenClaw ​

在终端中执行以下命令：

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

安装过程会自动：

  • 检测系统环境
  • 安装Node.js（如果未安装）
  • 下载OpenClaw
  • 配置环境变量

预计时间：2-5分钟

第三步：验证安装 ​

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

bash
openclaw --version

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

第四步：初始化配置 ​

运行配置向导：

bash
openclaw onboard

配置流程：

1. 接受风险提示：

选择 Yes 继续

安装向导 - 接受风险提示

2. 选择启动模式：

推荐选择 QuickStart 快速启动：

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

3. 选择AI模型：

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

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

国内推荐：

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

4. 输入API Key：

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

5. 选择聊天工具：

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

安装向导 - 选择聊天平台（飞书/企微/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）

第五步：验证安装 ​

bash
# 检查Gateway状态
openclaw channels status

# 应该显示：
# Gateway reachable.

日常使用 ​

启动OpenClaw：

bash
# 启动Gateway服务
openclaw gateway start

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

访问Web UI：

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

停止服务：

bash
openclaw gateway stop

接入飞书（推荐） ​

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

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

常见问题 ​

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

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

Q2：如何更新OpenClaw？

bash
openclaw update

Q3：如何卸载？

bash
openclaw uninstall

Windows本地部署 ​

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

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

系统要求 ​

硬件要求：

  • CPU：2核以上
  • 内存：4GB以上（推荐8GB）
  • 硬盘：10GB以上空闲空间

操作系统：

  • Windows 10 或 Windows 11

前置软件：

  • Node.js 22.0.0+

部署方式选择 ​

Windows有两种部署方式：

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

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

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

第一步：启用WSL2 ​

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

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

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

重启计算机。

第二步：安装Ubuntu ​

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

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

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

第三步：更新Ubuntu系统 ​

在Ubuntu终端中执行：

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

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

第四步：安装Node.js 22+ ​

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

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

第六步：验证安装 ​

bash
# 查看版本
openclaw --version

# 查看帮助
openclaw --help

# 查看系统状态
openclaw status

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

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

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

batch
@echo off
echo Starting OpenClaw Gateway in WSL2...
wsl -d Ubuntu-22.04 -u root service openclaw start
timeout /t 3
start http://localhost:18789

或直接在WSL2中启动：

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

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

方式二：PowerShell原生部署 ​

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

第一步：安装Node.js 22+ ​

方法一：官网下载安装

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

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

powershell
# 打开PowerShell
node -v
npm -v

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

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

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

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

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

如果遇到权限错误：

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

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

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

第五步：验证安装 ​

powershell
openclaw --version
openclaw --help

第六步：解决常见问题 ​

问题：sharp模块加载失败

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

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

问题：Windows Defender阻止

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

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

初始化配置 ​

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

启动初始化向导 ​

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

绑定消息渠道 ​

1. Telegram

创建Bot：

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

配置：

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

2. WhatsApp

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

# 用手机WhatsApp扫码

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

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

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

4. 飞书（国内推荐）

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

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

Windows常用命令速查 ​

系统管理：

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

配置管理：

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

Linux本地部署 ​

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

系统要求 ​

推荐发行版：

  • Ubuntu 20.04+
  • Debian 11+
  • CentOS 8+

安装步骤 ​

第一步：安装Node.js ​

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

# 验证安装
node --version

第二步：安装 OpenClaw ​

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

第三步：验证安装 ​

bash
openclaw --version

第四步：初始化配置 ​

bash
openclaw onboard

API配置指南 ​

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

为什么需要API？ ​

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

  • 官方API：价格贵、国内访问困难
  • 第三方API：价格便宜、国内直连

API模型分类 ​

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

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

什么是内置API模型？

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

  • ✅ 获取API Key
  • ✅ 在配置向导中选择对应模型
  • ✅ 粘贴API Key即可使用

一般内置的API价格都比较昂贵，推荐使用中转站API

2. 中转站 API ​

什么是中转站API？

如果你想使用：

  • 🔧 OpenClaw未内置的模型
  • 🔧 第三方API代理服务
  • 🔧 企业内部的模型接口

就需要使用自定义API配置。 推荐中转站：api.sharesai.xyz,codex每消耗官方1刀 低至0.08元 ，真正实现龙虾自由

如何获取API-KEY ​

首先，我们要去发卡网购买一个额度 发卡网地址 : https://xzfk.sharesai.xyz/ 购买额度后，我们进入到中转站兑换额度

生成api-key流程 ​

首先点击创建key

选择对应的模型，这里以codex为例

即可创建Key

得到APIKey后，我们需要配置到我们的龙虾里面。

配置方式：

需要手动编辑配置文件 ~/.openclaw/openclaw.json，指定：

  • baseUrl：https://api.sharesai.xyz
  • apiKey：上面获得的APIKEY
  • api：API协议类型
  • models：模型列表和参数 #手动编辑配置文件会比较容易出错，这里推荐一款插件

第三方 API 供应商配置插件,可以一键配置

插件安装方式如下：

shell
openclaw plugins install openclaw-config-generator

重启 Gateway 加载插件：
openclaw gateway restart

然后在浏览器中访问：
http://127.0.0.1:18789/plugins/openclaw-config-generator

访问插件的界面按图示输入：

配置后重启服务 ​

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

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

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

验证配置 ​

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

常见问题 ​

Q1：配置后无法连接？

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

Q2：如何切换模型？

bash
# 临时切换
openclaw agent --message --model 

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

Q3：如何添加多个模型？

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

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

白白 中转 配置（推荐） ​

特点：

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

配置步骤：

第一步：访问白白 Code平台

访问发卡平台购买卡密：https://xzfk.sharesai.xyz

中转 Code平台

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

推荐套餐：

  • Allegretto套餐：适合日常使用
  • 按需选择其他套餐

购买套餐

第三步：创建API Key

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

创建API Key

第四步：保存API Key

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

保存API Key

第五步：配置到OpenClaw

bash
# 运行配置向导
openclaw onboard

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

成本估算：

  • 轻度使用：10-20元/月
  • 中度使用：30-50元/月

2.1 系统要求与准备 ​

云端部署要求 ​

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

  • ✅ 一个浏览器
  • ✅ 20元/月预算
  • ✅ 10分钟时间

云端一键部署 ​

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

为什么选择云端部署？ ​

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

表 2-1 云端部署优势

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

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

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

# 安装依赖
pnpm install

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

# 构建项目
pnpm build

# 运行入门向导
openclaw-cn onboard --install-daemon

如果还没有全局安装，可以从仓库中通过 pnpm openclaw-cn ... 运行命令。

从源码运行 Gateway：

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

端到端验证 ​

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

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

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

调试提示：

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

配置文件位置 ​

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

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

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

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

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

Q1: 安装失败怎么办？

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

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

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

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

Q3: 如何卸载？

bash
# 停止服务
openclaw-cn gateway stop

# 卸载
npm uninstall -g openclaw-cn

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

Q4: 支持哪些系统？

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

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

bash
# 按 Ctrl+C 中断

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

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

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

需要配置认证：

bash
# 重新运行向导
openclaw-cn onboard

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

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

  • macOS 菜单栏应用 + 语音唤醒：macOS 应用
  • iOS/Android 节点（Canvas/摄像头/语音）：节点
  • 远程访问（SSH 隧道 / Tailscale 服务）：远程访问
  • 始终在线 / VPN 设置：Tailscale

下一步 ​

安装完成后，可以：

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

更新和维护 ​

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

检查更新 ​

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

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

本地安装更新 ​

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

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

Docker 更新 ​

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

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

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

备份数据 ​

本地安装备份：

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

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

Docker 备份：

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

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

监控和日志 ​

查看日志：

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

# Docker
docker logs -f openclaw

监控指标：

bash
# 查看系统状态
openclaw gateway status

# 查看资源使用
openclaw stats

# 查看 API 消耗
openclaw stats api

故障排查 ​

常见问题：

  1. Gateway 无法启动

    bash
    # 查看日志
openclaw logs

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

# 重启 Gateway
openclaw gateway restart

  2. API 连接失败

    bash
    # 测试 API 连接
openclaw test api

# 检查 API Key
openclaw config get models.providers

  3. 性能问题

    bash
    # 清理缓存
openclaw cache clear

# 重启服务
openclaw gateway restart

卸载 ​

本地安装卸载：

bash
# 停止服务
openclaw gateway stop

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

# 删除命令
npm uninstall -g openclaw

Docker 卸载：

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

# 删除镜像
docker rmi openclaw/openclaw

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

常见问题解决 ​

安装问题 ​

Q1: Node.js版本不对

bash
# 检查版本
node --version

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

Q2: 权限错误

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

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

Q3: 网络连接失败

  • 检查网络连接
  • 尝试使用代理
  • 或使用云端部署

API配置问题 ​

Q1: API Key无效

  • 检查是否完整复制（包括sk-前缀）
  • 检查是否有多余空格
  • 检查账户余额是否充足

Q2: 模型不可用

  • 检查模型ID是否正确
  • 检查API服务是否正常
  • 尝试切换其他模型

Gateway问题 ​

Q1: Gateway无法启动

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

# 重启Gateway
openclaw gateway restart

Q2: 端口被占用

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

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

2.X 版本升级指南 ​

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

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

推荐版本 ​

当前推荐版本：2026.3.2

已知问题版本：

  • ❌ 2026.2.12：Session 路径验证 bug，影响 heartbeat 和 Telegram/飞书消息处理

为什么要升级？ ​

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

  • ✅ 新功能和改进
  • ✅ 性能优化
  • ✅ 安全修复
  • ✅ Bug修复
  • ✅ 更好的兼容性

检查当前版本 ​

bash
# 查看当前版本
openclaw --version

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

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

升级方式选择 ​

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

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

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

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

升级步骤 ​

第一步：备份配置

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

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

第二步：停止Gateway服务

bash
# 停止Gateway
openclaw gateway stop

# 验证已停止
openclaw gateway status

第三步：卸载旧版本

bash
# 卸载旧版本
npm uninstall -g openclaw

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

第四步：安装新版本

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

⚠️ 版本选择说明：

  • 推荐安装 2026.3.2 版本（稳定）
  • 避免安装 2026.2.12 版本（存在 session 路径 bug）
  • 如果需要最新功能，等待 2026.2.13+ 版本修复后再升级

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

第五步：修复配置

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

doctor工具会自动：

  • 更新Gateway服务入口点路径
  • 检查配置兼容性
  • 修复已知问题
  • 重新安装LaunchAgent（macOS）或systemd服务（Linux）

第六步：重启Gateway

bash
# 重启Gateway
openclaw gateway restart

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

第七步：验证升级

bash
# 检查版本
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

方式二：官方脚本升级 ​

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

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

优点：

  • ✅ 一键完成
  • ✅ 自动处理依赖

缺点：

  • ❌ 可能遇到npm错误
  • ❌ 不如方式一可靠

如果遇到错误：

  • 切换到方式一（npm直接升级）
  • 或查看下文的故障排查

方式三：Docker升级 ​

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

bash
# 停止并删除旧容器
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工具会自动：

  • 更新配置文件格式
  • 迁移旧版本配置
  • 创建备份文件：~/.openclaw/openclaw.json.bak

服务管理改进 ​

macOS：

  • LaunchAgent自动重新安装
  • 服务路径更新为新版本
  • 日志位置：~/.openclaw/logs/gateway.log

Linux：

  • systemd服务自动更新
  • 服务路径更新为新版本
  • 日志位置：~/.openclaw/logs/gateway.log

已知警告 ​

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

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

解决方案：

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

问题2：Gateway启动失败 ​

症状：

Gateway not running

解决方案：

bash
# 运行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

解决方案：

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

问题4：插件加载失败 ​

症状：

plugin not found: xxx

解决方案：

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

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

问题5：端口被占用 ​

症状：

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

解决方案：

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

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

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

回滚到旧版本 ​

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

方式一：从备份恢复 ​

bash
# 停止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

方式二：安装指定版本 ​

bash
# 查看可用版本
npm view openclaw versions

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

# 修复配置
openclaw doctor --fix

# 重启Gateway
openclaw gateway restart

升级最佳实践 ​

升级前必做 ​

  1. 备份配置：

    bash
    cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d)

  2. 记录当前版本：

    bash
    openclaw --version > ~/openclaw-version-before-upgrade.txt

  3. 导出重要配置：

    bash
    openclaw config get > ~/openclaw-config-backup.json

  4. 检查磁盘空间：

    bash
    df -h ~

升级时注意 ​

  1. 使用--force参数：

    bash
    npm install -g openclaw@2026.3.2 --force

  2. 运行doctor修复：

    bash
    openclaw doctor --fix

  3. 检查Gateway状态：

    bash
    openclaw gateway status

  4. 查看日志：

    bash
    tail -f ~/.openclaw/logs/gateway.log

升级后验证 ​

  1. 检查版本号：

    bash
    openclaw --version

  2. 测试Gateway连接：

    bash
    openclaw channels status

  3. 验证插件功能：

    bash
    openclaw plugins list

  4. 测试频道连接：

    • 发送测试消息
    • 验证AI回复
    • 检查Skills功能

  5. 检查API消耗：

    bash
    openclaw stats api

已知问题版本警告 ​

2026.2.12 版本问题 ​

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

问题描述：

  • Session 文件路径验证逻辑错误
  • 导致 heartbeat 功能失败
  • 导致 Telegram/飞书消息处理异常
  • 错误信息：Session file path must be within sessions directory

影响范围：

  • ❌ Heartbeat 功能完全不可用
  • ❌ Telegram bot 无法响应消息
  • ❌ 飞书 bot 可能无法正常回复
  • ✅ 网页版不受影响

官方 Issue：

解决方案：

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

推荐做法：

  • 使用 2026.3.2 版本（当前最稳定）
  • 等待 2026.2.13+ 版本修复后再升级
  • 关注官方 GitHub Issues 获取最新信息

升级时间建议 ​

推荐升级时机：

  • 🌙 晚上或周末（使用量低）
  • 📅 每月检查一次更新
  • 🐛 发现Bug时及时升级
  • 🔒 安全更新立即升级

不推荐升级时机：

  • ❌ 工作日高峰期
  • ❌ 重要任务进行中
  • ❌ 网络不稳定时
  • ❌ 没有备份时

自动更新（可选） ​

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

macOS/Linux：

bash
# 编辑crontab
crontab -e

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

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

版本发布说明 ​

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

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

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

升级成本估算 ​

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

升级检查清单 ​

升级前：

  • [ ] 备份配置目录
  • [ ] 记录当前版本
  • [ ] 检查磁盘空间
  • [ ] 选择合适的升级时间

升级中：

  • [ ] 停止Gateway服务
  • [ ] 卸载旧版本
  • [ ] 安装新版本（使用--force）
  • [ ] 运行doctor修复
  • [ ] 重启Gateway

升级后：

  • [ ] 验证版本号
  • [ ] 测试Gateway连接
  • [ ] 验证插件功能
  • [ ] 测试频道连接
  • [ ] 检查日志无错误

升级支持 ​

如果升级遇到问题：

  1. 查看日志：

    bash
    tail -f ~/.openclaw/logs/gateway.log

  2. 运行诊断：

    bash
    openclaw doctor

  3. 查看官方文档：

    https://docs.openclaw.ai/

  4. 加入社区：

    • GitHub Issues
    • Discord社区
    • 飞书群组

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

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

升级背景：

  • 原版本：2026.2.1-zh.3（中文版）
  • 目标版本：2026.3.2（推荐稳定版）
  • 升级原因：获取新功能和性能优化

升级过程：

  1. 备份配置：

    bash
    cp -r ~/.openclaw ~/.openclaw.backup-20260213

  2. 停止Gateway：

    bash
    openclaw gateway stop

  3. 卸载旧版本：

    bash
    npm uninstall -g openclaw

  4. 安装新版本：

    bash
    npm install -g openclaw@2026.3.2 --force

  5. 修复配置：

    bash
    openclaw doctor --fix

  6. 重启Gateway：

    bash
    openclaw gateway restart

  7. 验证升级：

    bash
    openclaw --version  # 显示：2026.3.2
openclaw gateway status  # 显示：running

升级结果：

  • ✅ 升级成功
  • ✅ 配置自动迁移
  • ✅ Gateway运行正常
  • ✅ 所有功能正常

遇到的问题：

  • npm install报错EEXIST → 使用--force解决

总耗时：约5分钟

本章小结 ​

通过本章，你应该已经：

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

实战练习 ​

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

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

返回目录：README

采用 GPL-3.0 License 开源协议，禁止倒卖

© 2026 @xianyu110