---
name: "upgrade-openclaw-gateway"
description: "OpenClaw 升级/降级/重启网关：先备份配置并记录 cron 任务，含卡死与半途中断的恢复步骤。"
---

# OpenClaw 网关 升级 / 降级 / 重启

触发：用户说「升级 openclaw」「降级到 X 版本」「重启网关」。

## 动手前

1. 备份配置：`cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-<日期>-<改动名>`
2. **记录定时任务**：`openclaw cron list`。自定义 job 会在重启/升降级后消失——实测降到 8.2 后只剩 3 个内置 job，morning-data / morning-digest / daily-summary / daily-leetcode 全没了（靠 MEMORY.md 里记的定义才重建回来）。重启前把要保留的 job（时间、payload、投递目标）落到记忆文件。
3. 看版本：`openclaw --version`；`npm view openclaw versions --json` 列可用版本。

## 重启

```bash
export XDG_RUNTIME_DIR=/run/user/0
systemctl --user restart openclaw-gateway
```

- 重启会**杀掉自己正在跑的 turn**（exec 收到 SIGTERM）——预期行为，别当失败重试。
- 卡在 `deactivating (stop-sigterm)` 超过 ~40 秒不退出：先 `systemctl --user show openclaw-gateway -p Restart -p RestartUSec` 确认是 `Restart=always` / `5s`，再 `kill -9 <MainPID>`，systemd 会自动拉起；用 `systemctl --user is-active` + `ps aux | grep "dist/index.js gateway"` 确认 PID 换新。

## 半途中断的恢复（npm 装坏包）

`npm install -g openclaw@<ver>` 被中断会让包目录残缺：现象是 `exec` 直接报 ENOENT（例如 `.../openclaw/dist/supervisor-log.runtime.js` 不存在），而 npm 暂存目录 `.openclaw-<随机串>` 里是**完整**的一份。恢复：

```bash
cd /root/.nvm/versions/node/v24.18.0/lib/node_modules
mv openclaw openclaw.broken-<日期> && mv .openclaw-<随机串> openclaw
openclaw --version
```

## 收尾核验（顺带是常用自检命令）

- `openclaw --version`；`openclaw logs --limit 100 | grep -E "CLI version|Gateway version"`
- `openclaw plugins list` — 插件版本是否跟着升/降
- `openclaw cron list` — 定时任务是否还在，丢了的按记录重建
- `openclaw models list` — 已接入供应商与模型清单（含 alias / 默认 / fallback）；切换或登记模型见 `configure-models`
- 回复不逐字**不是**版本问题，见 `fix-reply-streaming`