openclaw升级踩坑笔记

📌 前言

最近遇到一次 OpenClaw 从 v2026.9.5 升级到v2026.10.3版时反复失败的问题。

经过排查发现根本原因是数据库 Schema 未正确迁移 以及 systemd 配置不当导致的进程锁冲突。特此总结实践，以便后续遇到类似问题时查阅对照。

⚠️ 重要变化（v2026.9 → v2026.10）

项目	旧版 (≤2026.9.5)	新版 (≥2026.10.3)
数据库 Schema	版本 17	升级到 20
自启方式	系统级 unit 或 user unit	统一为 systemd user unit
KillMode 默认值	`control-group`	改为 `mixed`
升级阻塞原因	doctor 被 Gateway 持有锁阻止	同上，但修复机制更明确

🔑 核心变化

新版升级不再能"一步到位" ------必须在停止 Gateway 后、执行升级前手动运行 openclaw doctor --fix 完成数据库 Schema 迁移（17→20）。

📋 前置检查

升级前确认以下信息：

bash 复制代码

# 查看当前版本
openclaw --version
# 输出: OpenClaw 2026.9.5 (ec9c1a1)

# 确认 Node.js 运行时版本
node -v
# 推荐: v24.x+

# 查看可用最新版本
npm view openclaw version
# 输出: 2026.10.3 (stable)

🚀 升级流程

第 1 步：临时禁用自启服务

bash 复制代码

# systemd user 单元（本机采用此方式）
systemctl --user disable --now openclaw-gateway.service

# 如果是系统级 unit（旧版方式，已不使用）
# sudo systemctl disable --now openclaw-gateway.service

这一步非常关键，目的是防止 Gateway 在升级过程中被 systemd 自动拉起 。如果 Gateway 在升级期间意外启动，它会重新持有数据库独占锁，导致后续的 openclaw doctor --fix 报出 StateDatabaseCoordinatorContentionError，从而阻塞整个升级流程。

第 2 步：彻底杀掉所有 OpenClaw 进程

bash 复制代码

# 先正常终止
pkill -f "openclaw" || true
sleep 2

# 检查是否还有残留进程
pgrep -fa "openclaw"
# 如果有输出，强制终止
if pgrep -f "openclaw"; then
    pkill -9 -f "openclaw"
    sleep 1
fi

注意：这一步会断开在用的 Agent 连接，是正常的。

第 3 步：清理残留锁文件

bash 复制代码

rm -rf /root/.openclaw/tmp/

第 4 步：运行医生模式（必须！）

bash 复制代码

openclaw doctor --fix

预期成功输出示例：

复制代码

OpenClaw 2026.10.3 (59cb447) --- Your config is valid, your assumptions are not.
Doctor could enter maintenance. StateDatabaseCoordinatorReleased.
Schema migrated from 17 to 20 ✓
Config validated ✓
Health check passed ✓

常见错误：

复制代码

StateDatabaseCoordinatorContentionError: another OpenClaw process owns gateway-lifecycle

这说明 Gateway 还在运行，数据库仍被占用。回到第 2 步确保进程全部杀掉。

第 5 步：执行升级

bash 复制代码

openclaw update --yes

等待完成后验证版本：

bash 复制代码

openclaw --version
# 输出: OpenClaw 2026.10.3 (59cb447)

第 6 步：重启并验证

bash 复制代码

systemctl --user enable --now openclaw-gateway.service

# 验证 Gateway 健康状态
openclaw health --json
# 或
openclaw status --all

💡 升级完成

🔧 系统相关优化

优化 1：KillMode 改为 mixed

背景：默认的 KillMode=control-group 在 OOM-kill 时可能导致子进程残留，从而阻止后续的 doctor 修复。

配置方法：

bash 复制代码

mkdir -p ~/.config/systemd/user/openclaw-gateway.service.d

cat > ~/.config/systemd/user/openclaw-gateway.service.d/killmode-override.conf << 'EOF'
[Service]
KillMode=mixed
TimeoutStopSec=45
EOF

systemctl --user daemon-reload

生效时机：配置立即写入，下次 Gateway 重启周期后生效。

为什么这样改：

mixed 模式下，systemd 等待主进程退出后再做 cleanup
减少"僵尸锁"的概率，避免 doctor 报"另一个进程持有锁"

优化 2：清理升级产生的临时备份

升级会产生 .bak 副本用于回滚，确认无误后可安全删除：

bash 复制代码

# 清理所有 .bak 备份文件（保留必要的恢复点）
find ~/.openclaw -name "*.bak" -type f -size +1M -delete

# 或只删除特定类型的备份
find ~/.openclaw -name "*pre-startup-migration*.bak" -type f -delete

优化 3：关闭旧版系统级 Unit（如有）

如果之前使用的是系统级 service unit，建议完全移除以避免冲突：

bash 复制代码

sudo systemctl stop openclaw-gateway.service 2>/dev/null
sudo systemctl disable openclaw-gateway.service 2>/dev/null

❌ 常见问题

Q1: doctor 报 "StateDatabaseCoordinatorContentionError"

原因：Gateway 正在运行，持有数据库独占锁。

解决：确保所有 openclaw 相关进程已全部终止（pgrep -fa "openclaw" 无输出）。

Q2: 升级卡在 validating / activating 阶段

原因：网络问题或新版本包下载不完整。

解决：重试一次 openclaw update --yes，确认网络连接通畅。

Q3: 升级后 Doctor 仍然失败

原因：数据库 Schema 未从 17 迁移到 20。

解决：必须先跑 openclaw doctor --fix，再执行 update --yes（顺序不能颠倒）。

Q4: Gateway 被 OOM-kill 后无法重启

原因：旧的 KillMode 设置导致子进程残留。

解决：参照上述"优化 1"修改配置并 reload systemd。

Q5：切换模型无效

通过命令行配置模型：openclaw configure --section model后，没有改变实际使用的模型。

原因：要切换模型生效，三处必须同步改：

agents.entries.main.model.primary → 新模型（这是最关键的）
agents.entries.main.modelPolicy.allow → 含新模型（白名单放行）
agents.defaults.model.primary → 新模型（保持 defaults 一致，避免其他 agent/subagent 走旧模型）

解决：命令行切换模型

假设要切换到 zai/glm-4.7-flash：

bash 复制代码

# 1. 改 main agent 的 model.primary（关键，覆盖 defaults）
openclaw config patch agents.entries.main.model '{"primary":"zai/glm-4.7-flash"}'

# 2. 改 main agent 的 modelPolicy.allow（白名单放行）
openclaw config patch agents.entries.main.modelPolicy '{"allow":["zai/glm-4.7-flash"]}'

# 3. 改 defaults4.defaults.model（保持一致，影响 subagent 等）
openclaw config patch agents.defaults.model '{"primary":"zai/glm-4.7-flash"}'

# 4. 改 defaults 白名单
openclaw config patch agents.defaults.modelPolicy '{"allow":["zai/glm-4.7-flash"]}'

验证

bash 复制代码

openclaw config get agents.entries.main.model
openclaw config get agents.entries.main.modelPolicy.allow

可分别看到如下类似输出：

bash 复制代码

{
  "primary": "zai/glm-4.7"
}

bash 复制代码

[
  "zai/glm-4.7"
]

📝 参考链接

OpenClaw 官方文档