AI 原生开放教材

外观

Awesome OpenClaw Tutorial（中文）清单与速查·中文原文 ↗原件 ↓仓库 ↗

2.X 版本升级指南 ​

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

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

推荐版本 ​

当前推荐版本：2026.9.3

版本确认命令：

bash
npm view openclaw version
openclaw --version

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

升级前必做 ​

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

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

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

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

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

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

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

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

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

升级完成后：

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

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

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

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

bash
# 停止 Gateway
openclaw gateway stop

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

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

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

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

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

方式三：官方安装脚本 ​

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

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

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

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

方式四：Docker / 云端部署 ​

Docker 部署通常按镜像更新：

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

docker compose logs -f

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

升级后验证清单 ​

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

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

bash
openclaw doctor --fix

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

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

2026.9.3 升级后重点验证 ​

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

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

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

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

常见升级问题 ​

npm 报 EEXIST ​

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

Gateway 启动失败 ​

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

配置由更高版本写入 ​

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

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

端口被占用 ​

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

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

回滚建议 ​

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

bash
openclaw gateway stop
cp -r ~/.openclaw.backup-YYYYMMDD-HHMMSS/* ~/.openclaw/