$cd ../troubleshooting/
High📦 Installation
升级后网关崩溃 — openclaw.json 路径陈旧
// 重大 OpenClaw 升级（尤其 Clawdbot → OpenClaw 重命名与 npm 全局路径变更）后，~/.openclaw/openclaw.json 中的 sourcePath 与 installPath 仍指向已不存在的目录。网关服务启动后立即退出，日志出现 ENOENT 或 install path invalid。openclaw doctor --fix 会将这些键重写为当前二进制位置。
diagnose.sh
🔍 这是您的问题吗？
?openclaw gateway start 或 systemctl restart 后网关立即退出
?日志提及 ENOENT、install path invalid 或 sourcePath not found
?openclaw.json 仍引用 clawdbot、旧 nvm 版本路径或已删除的主目录
doctor_fix.sh
✅ 修复方法 1 — 运行 openclaw doctor --fix（最快）
首选修复 — 写入前会备份配置
# 对比当前路径与二进制 openclaw doctor # 自动修复陈旧路径与 schema 漂移 openclaw doctor --fix # 验证网关 openclaw gateway restart openclaw gateway status
openclaw.json
✅ 修复方法 2 — 手动更新 openclaw.json 中的路径
installPath = 含 openclaw package.json 的目录
# 查找实际安装位置
which openclaw
# 例如 /home/you/.nvm/versions/node/v22.4.0/bin/openclaw
# 编辑 ~/.openclaw/openclaw.json
{
"installPath": "/home/you/.nvm/versions/node/v22.4.0/lib/node_modules/openclaw",
"sourcePath": null
}
openclaw gateway restartgateway_install.sh
✅ 修复方法 3 — 重新安装 Gateway 服务
用当前二进制路径 regenerate 服务
# Linux systemd openclaw gateway stop openclaw gateway uninstall openclaw gateway install systemctl --user daemon-reload systemctl --user restart openclaw-gateway # macOS openclaw gateway install --force # Windows（计划任务可能需提升一次） openclaw gateway install
💡 专业技巧：每次升级前备份配置
在 npm update -g openclaw 前将 ~/.openclaw/openclaw.json 复制为 openclaw.json.bak。若网关无法启动，对比备份与新文件 — 陈旧 path 键通常是唯一破坏性变更。
🛡️ 预防清单
- • 每次升级后运行 openclaw doctor（不加 --fix）— 在崩溃前阅读警告
- • 除非 symlink 自定义 checkout，避免手改 sourcePath/installPath
- • 迁移机器时 rsync ~/.openclaw/，但在新主机上重新 doctor --fix
- • 保持 npm prefix 稳定（见 Windows EACCES 指南）以免 installPath 静默漂移
- • 在 README 笔记中记录 gateway 安装方式（systemd / launchd / 计划任务）
❓ 常见问题
Q1. sourcePath 与 installPath 有什么用？
installPath 是运行中的 openclaw CLI 与捆绑资源所在目录。sourcePath（若设置）指向用于开发插件或本地补丁的 git checkout。网关在启动时校验两者，以便技能、默认配置与自动更新钩子正确解析。陈旧值会导致立即启动失败而非静默错路由。
Q2. 为什么 npm update -g 没有自动修复路径？
npm 会替换全局 prefix 下的包，但不会编辑 ~/.openclaw/ 中的用户配置。path 键在 openclaw setup 或 gateway install 时写入一次并跨升级保留。doctor --fix 将 live 二进制位置（npm 已更新）与配置对比并修补不一致。
Q3. 完全删除 sourcePath 安全吗？
若不从源码开发 OpenClaw，可以 — 删除 sourcePath 或设为 null，仅依赖 installPath。保留指向旧 Clawdbot clone 的死 sourcePath 是迁移后常见坑。生产安装只需 installPath 指向全局 npm 树或 nvm slot。
Q4. doctor --fix 还改了其他设置 — 正常吗？
doctor 还可能规范化 schema 版本、迁移重命名键、刷新 gateway.auth 占位符。查看 diff：可用时 openclaw doctor --fix --dry-run，或先备份。路径修复是关键部分；除非触及您手动轮换的密钥，否则接受良性迁移。
Q5. 修复 1 后网关仍崩溃 — 下一步？
查日志：journalctl --user -u openclaw-gateway -n 50（Linux）或 openclaw gateway logs。寻找其他 ENOENT（skills 目录、频道 auth）。重跑修复 3 regenerate 服务单元。确认服务调用的 openclaw 二进制 — /usr/local/bin 中遮蔽的旧二进制是另一问题（见 dual-install 指南）。
Q6. 我用 Docker — 需要本指南吗？
容器内 bind-mount 的 ~/.openclaw/openclaw.json 可能携带容器文件系统中不存在的主机路径（如 /home/user/.nvm/...）。要么挂载一致路径，在容器内设置 installPath（如 /app），要么让 entrypoint 在启动时运行 doctor --fix。