AI 原生开放教材

外观

Claude Code & OpenClaw & Codex & WorkBuddy 中文教程课时教程·中文原文 ↗原件 ↓仓库 ↗

十一、版本升级与迁移（v2026.3.28 → v2026.6.8） ​

📌 本节包含 4 个问题：Q80: 升级要点 | Q81: 反向代理配置变更 | Q82: 插件白名单变更 | Q83: 性能提升

Q1: 从 v2026.3.2x 升级到 v2026.6.8 有哪些注意事项？ ​

v2026.6.8 新增关注点：除了 v2026.4.x 和 v2026.5.x 的安全、通道、Transcript、模型目录、Docker 和 release integrity 改动之外，v2026.6.x 还重点改进 Agents / CLI runtime 恢复、消息通道稳定性、Skill Workshop、插件安装索引、Workboard、provider/model 覆盖、Control UI、fail-closed 边界、agent run recovery、SecretRef、/usage 和 release / diagnostics 证据链。升级后如果发现模型、通道、插件、技能或多 Agent 行为变化，先运行 openclaw doctor，再对照当前 release notes。

说明： 从 v2026.4.x 到 v2026.6.8 的升级包含多项安全加固、性能优化、通道能力、插件/技能和多 Agent 更新。大部分配置向后兼容，但以下几点需要注意：

  1. Owner-Enforced Commands（v2026.4.5+）：/allowlist add 和 /allowlist remove 现在需要 Owner 身份验证。如果你之前在自动化脚本中使用了这些命令，需要确保调用者具有 Owner 权限
  2. 转发头安全检查（v2026.4.x+）：如果你使用反向代理，Gateway 现在会检查转发头的一致性（详见 Q81）
  3. 环境变量过滤（v2026.4.7+）：Gateway 会自动拦截危险的环境变量覆盖，如果你的部署脚本依赖特定的环境变量传递，建议测试确认
  4. Hook 失败模式变更（v2026.4.5+）：Hook 崩溃时从 fail-open 改为 fail-closed，如果你有自定义 Hook，升级后请确认它们运行正常
  5. Cron 状态拆分（v2026.4.20+）：定时任务运行时状态拆分到独立的 jobs-state.json 文件，升级后首次启动会自动迁移

升级步骤：

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

# 2. 升级
npm update -g openclaw

# 3. 验证
openclaw --version
openclaw doctor
openclaw security audit

# 4. 如果使用反向代理，检查转发头配置（见 Q81）

Q2: 升级后反向代理配置需要改吗？ ​

说明： 如果你通过 Nginx 等反向代理暴露 Gateway，v2026.4.x 的转发头安全检查可能影响你的配置。

需要确认的事项：

  1. 反向代理的 X-Forwarded-For 头必须覆盖客户端值，不能追加
nginx
# 正确：覆盖客户端的转发头
proxy_set_header X-Forwarded-For $remote_addr;

# 错误（旧写法）：追加模式，可能被客户端伪造
# proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  1. 如果使用 trusted-proxy 认证模式，trustedProxies 中不能填 loopback 地址（127.0.0.1、::1）
  2. 如果 Gateway 和代理在同一台机器上通过 loopback 通信，改用 token/password 认证模式

Q3: 升级后 /allowlist 相关操作报权限错误 ​

现象： 升级到 v2026.4.5+ 后，执行 /allowlist add 或 /allowlist remove 时提示权限不足。

原因： 这是 v2026.4.5 引入的 Owner-Enforced Commands 特性。白名单修改现在需要 Gateway 所有者的实际身份验证，不再接受宽松的回退。

解决方案：

bash
# 确保你通过已认证的 Owner 身份操作
# 1. 如果使用 Token 认证，确保连接时提供了正确的 Token
# 2. 如果使用配对系统，确保你是已配对的 Owner 用户
# 3. 通过 CLI 直接管理白名单
openclaw approvals get