OpenClaw Gateway 重启标准流程

适用于任何 OpenClaw agent。涉及 gateway 重启操作时加载并遵循此流程。 核心：改 openclaw.json 走五道校验门（Gate0-4），全绿才重启；重启用平台工具托管 + 自动回执， 绝不在会话内裸跑会自杀进程的复合命令。

前置条件

• 仅授权用户（operator）明确确认后才能执行重启
• 修改 openclaw.json 前必须先备份

五道校验门（Gate0-4，改 openclaw.json 必走）

教训：python3 -m json.tool 和 openclaw config validate 都只验"格式合法"， 不验"模型真的能调用"。曾出现 JSON 合法、config validate 通过， 但因为模型只写进 agents.defaults.models 白名单、没写进 models.providers.<provider>.models[]，运行时静默 fallback 到别的模型。 所以校验必须分门逐层，缺一不可。

Gate 0 · 官方文档 / 实现核对

改动涉及不确定的配置字段前，先查官方文档或本机实现确认字段名、取值、语义， 不要凭印象改。这是"改对方向"的前提，不能跳。

Gate 1 · JSON 语法

cp openclaw.json openclaw.json.bak      # 先备份
python3 -m json.tool openclaw.json > /dev/null

• ✅ 通过 → 下一门
• ❌ 失败 → 立即回滚 .bak，不准重启，汇报授权用户

Gate 2 · Schema 校验

openclaw config validate

• 只验配置结构合法，不代表模型可调用，通过也要继续 Gate 3

Gate 3 · 模型可调用性（改动涉及模型/provider/cron model 时必做）

改动只要碰到 agents.defaults.model、agents.defaults.models、 agents.list[].model、或任何 cron 的 payload.model，必须逐个核对模型引用 都在 provider 层真正注册：

openclaw models list          # primary/fallback 引用的模型是否都可用
openclaw models aliases list  # 每个 alias 的目标是否真实存在于 catalog

核对要点：

• primary + 所有 fallback，都要能在 models.providers.<provider>.models[] 找到注册
• 每个 alias 的目标模型必须真实存在于 provider catalog（杜绝"白名单有、catalog 无"的半注册）
• cron 的 payload.model 逐个核对，别只查主 agent 配置

任一模型引用查不到 provider 注册 → 视为失败，先补齐注册再重启。

Gate 4 · 执行重启

Gate0-3 全绿 + 授权用户已确认 → 才能进入本门。见下节"如何重启"。

如何重启 —— 优先用平台工具，不要在会话里裸跑 shell

教训：不要在 agent 会话内直接执行 openclaw gateway stop && openclaw gateway start。 stop 一旦生效会立即杀掉当前 agent 自己的进程，&& 后面的 start 根本没机会执行， 也拿不到返回值——结果是只 stop 没 start，要人工补 start。

做法 A（推荐）：调用 gateway 工具，平台托管重启 + 自动回执

gateway restart:
  note: "简短说明本次改动内容"
  continuationMessage: "重启完毕。[改动简述]，[后续状态]。"

gateway 工具由平台在新进程里托管重启，continuationMessage 在重启后由新进程自动投递， 不依赖被杀掉的旧进程。这是会话内触发重启唯一安全的方式。

做法 B（会话外 / 确需 shell）：单条 restart，绝不用 stop && start

openclaw gateway restart

单条 restart 是原子操作，不会在两步之间自杀。但发出后当前进程仍会被终止—— 不能在同一回合声称"重启成功"，只能说"已发出重启指令"，由新进程或事后检查确认结果。

会话内自触发重启的授权条件（三者同时满足）：

1. Gate0-4 全绿
2. 授权用户已明确确认本次改动
3. 走做法 A（gateway 工具 + continuationMessage），而非裸 shell

不满足任一条 → 走会话外 / 外部终端手动重启。

continuationMessage 铁律：

• 必填，不能省略
• 内容 = 重启完毕 + 改动摘要 + 后续状态
• 示例：重启完毕。fallback 链已从 A 模型切到 B 模型，下次定时任务会走新链。

重启后

• 需要补充说明 → 用 message 工具再发一条；不需要 → continuationMessage 已足够
• 涉及模型 / provider 改动的，重启后再核对一次运行时实际生效的模型，确认没有静默 fallback

为什么这样做

systemd 警告

systemd override.conf 绝对不允许自行修改（改错会失联）。

变更记录

• v1.2.0：校验流程整理为五道门 Gate0-4（新增 Gate0 文档核对、Gate2 schema 校验）； 全文角色中性化，去除特定部署的私有称呼，适配所有 OpenClaw 用户。
• v1.1.0：新增模型可调用性校验、self-restart 自杀进程规避、自触发授权条件、重启后模型生效复核。
• v1.0.0：备份 → JSON 校验 → continuationMessage 回执重启 → systemd 禁改。