企业官网建设流程全解析

📌 前言

最近遇到一次 OpenClaw 从v2026.9.5升级到v2026.10.3版时反复失败的问题。
经过排查发现根本原因是数据库 Schema 未正确迁移以及systemd 配置不当导致的进程锁冲突。特此总结实践，以便后续遇到类似问题时查阅对照。

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

🔑 核心变化

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

📋 前置检查

升级前确认以下信息：

# 查看当前版本openclaw--version# 输出: OpenClaw 2026.9.5 (ec9c1a1)# 确认 Node.js 运行时版本node-v# 推荐: v24.x+# 查看可用最新版本npmview openclaw version# 输出: 2026.10.3 (stable)

🚀 升级流程

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

# systemd user 单元（本机采用此方式）systemctl--userdisable--nowopenclaw-gateway.service# 如果是系统级 unit（旧版方式，已不使用）# sudo systemctl disable --now openclaw-gateway.service

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

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

# 先正常终止pkill-f"openclaw"||truesleep2# 检查是否还有残留进程pgrep-fa"openclaw"# 如果有输出，强制终止ifpgrep-f"openclaw";thenpkill-9-f"openclaw"sleep1fi

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

第 3 步：清理残留锁文件

rm-rf/root/.openclaw/tmp/

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

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 步：执行升级

openclaw update--yes

等待完成后验证版本：

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

第 6 步：重启并验证

# 恢复自启服务同时设置为开机启动systemctl--userenable--nowopenclaw-gateway.service# 验证 Gateway 健康状态openclaw health--json# 或openclaw status--all

💡 升级完成

🔧 系统相关优化

优化 1：KillMode 改为 mixed

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

配置方法：

mkdir-p~/.config/systemd/user/openclaw-gateway.service.dcat>~/.config/systemd/user/openclaw-gateway.service.d/killmode-override.conf<<'EOF' [Service] KillMode=mixed TimeoutStopSec=45 EOFsystemctl--userdaemon-reload

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

为什么这样改：

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

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

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

# 清理所有 .bak 备份文件（保留必要的恢复点）find~/.openclaw-name"*.bak"-typef-size+1M-delete# 或只删除特定类型的备份find~/.openclaw-name"*pre-startup-migration*.bak"-typef-delete

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

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

sudosystemctl stop openclaw-gateway.service2>/dev/nullsudosystemctl disable openclaw-gateway.service2>/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：

# 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"]}'

验证

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

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

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

["zai/glm-4.7"]

📝 参考链接

• OpenClaw 官方文档