OpenClaw 更新运行手册（Runbook）

当 OpenClaw 主机刚刚完成更新、即将执行更新，或更新后行为异常时，请使用本技能。这是一份通用型运维操作手册，而非面向某次特定发布的检查清单。

本技能应以文件夹形式安装，而非作为单个文件复制。它要求在同个技能包（skill bundle）内，SKILL.md 所在目录旁存在本地文件 references/failure-patterns.md。

目标不仅是让系统恢复运行，更要准确定位故障发生的层级：

• 服务生命周期与服务管理器（service-manager）状态
• 主机软件包版本
• 插件/软件包兼容性
• 配置漂移（config drift）
• 模型/提供方（model/provider）运行时路由
• 通道（channel）健康度
• 任务账本（task ledger）健康度
• cron/session 隔离机制与通道车道（channel-lane）所有权
• 运行时性能
• 命令路径（command-path）与更新通道（update-channel）假设
• 自更新风险：当 agent 更新正在运行自身的 gateway 时
• 插件/npm 依赖变更后的供应链与软件包完整性抽查（supply-chain and package-integrity spot checks）

快速工作流

1. 确认真实的初始状态。
   对于远程多主机更新，请首先通过短超时 SSH 连通性测试验证每台主机的可达性。若某主机无法直接访问，也无法经由可用跳板机（jump host）访问，则应将其记录为传输/访问阻塞（transport/access blocker），而非 OpenClaw 更新失败——因为此时尚未在该主机上执行任何 OpenClaw 命令。

   若通过非交互式 SSH 连接，请勿假定登录 shell 的 PATH 可用。请先在常见安装路径（如包管理器前缀、~/.local/bin/openclaw）中定位二进制文件，再为审计会话导出正确的 PATH。

   若 gateway 进程归属的 OS 用户与 SSH 登录用户不同，请以 gateway 服务用户身份运行 OpenClaw 诊断命令。SSH 用户的 PATH 中可能无 openclaw，或私有包管理器 shim 文件可能不可读；而 LaunchAgent/systemd 服务在另一用户主目录下仍可健康运行。请先从运行中的进程/服务定义中推导出服务用户、状态目录（state dir）、CLI 路径及端口，再运行 doctor 或编辑配置。

   需检查以下内容：

   • openclaw --version
   • openclaw update status
   • openclaw status --deep
   • openclaw doctor --non-interactive --no-workspace-suggestions
   • openclaw channels status --deep
   • openclaw tasks audit
   • 当前模型路由：agent 默认模型、agent 级别模型映射（model maps）、回退链（fallback chains）及 cron 有效载荷模型
   • 主模型与运行时（runtime）最近成功的会话记录，而不仅限于显示的模型名称

2. 验证 gateway 是否确实被正确管理。
   检查服务管理器状态、运行中 PID 及 /health 接口。服务标签/名称与 gateway 端口应从 openclaw status --deep 输出和/或服务定义中获取，切勿猜测。请勿仅依赖以下任一来源：

   • 主机的服务管理器
   • 进程列表
   • 健康检查（health）端点

   常见情形包括：

   • 服务定义存在但未加载
   • gateway 进程已脱离（detached）但仍持续处理流量
   • 服务管理器与实际运行进程状态不一致

3. 区分捆绑插件（bundled plugins）与全局安装插件（globally installed plugins）。
   首先检查插件健康状态：

   • openclaw plugins doctor
   • openclaw plugins list --json
   • openclaw plugins inspect

   重要规则：

   • 若某能力本应为捆绑插件，请验证是否存在陈旧的全局 npm 安装并因此造成遮蔽（shadowing）。
   • 若某能力未被捆绑，请在假设配置错误前，先检查 npm 和 ClawHub。
   • 对 codex 等特殊运行时插件，请对比 plugins inspect 与 plugins list --json 输出；inspect 可能报告运行时已加载，但原始插件元数据仍标记为禁用。
   • 对 codex 等 ClawHub/运行时插件，请即使 plugins doctor 显示无误，也需将插件版本与主机版本比对。可先执行 openclaw plugins update --dry-run，确认是否存在官方匹配包，再调整更广泛的模型配置。

4. 检查升级过程中继承的配置是否已失效（即不再通过校验）。
   重点关注：

   • tools.web.search.provider
   • plugins.allow
   • plugins.entries.*
   • 模型别名（model aliases）与回退链（fallback chains）
   • openai/*、openai-codex/*、codex 与 pi 的运行时映射
   • cron 作业有效载荷模型引用（payload model refs），其可独立于 agent 默认模型进行标准化
   • 更新通道元数据（update channel metadata）

   若 doctor 提示某 provider 或插件“未知”，请务必检查实际配置文件，切勿假设 doctor --fix 已彻底修复。

5. 比对插件安装记录与磁盘实际内容。
   检查以下位置：

   • ~/.openclaw/plugins/installs.json
   • ~/.openclaw/npm/node_modules/@openclaw/...
   • ~/.openclaw/extensions/...

   重点关注：

   • 记录中存在但实际路径不存在的安装路径
   • 记录版本与已安装版本出现偏差
   • 位于 ~/.openclaw/extensions/ 下的 ClawHub 安装运行时插件：虽能成功加载，但滞后于主机集群版本
   • npm 安装记录中 resolvedSpec、完整性哈希（integrity）与已安装版本完全匹配，但存储的 spec 仍为裸包名（如 @openclaw/discord）
   • 执行 openclaw update --channel ... 期间重写或保留的包规范（package specs）
   • 外部插件未发布所选通道对应版本，因而从 @latest 等回退标签安装
   • 仅含 TypeScript 源码、缺失编译后 dist/ 目录的插件包
   • 第三方插件目录中被移除的插件运行时依赖项

6. 在大幅修改前，先检查近期 gateway 日志。
   阅读以下日志文件：

   • ~/.openclaw/logs/gateway.log
   • ~/.openclaw/logs/gateway.err.log
   • /tmp/openclaw/openclaw-YYYY-MM-DD.log

   优先关注近期启动日志行及以下警告：

   • 插件加载失败
   • 配置校验失败
   • provider 回退尝试，以及主路由的身份认证（auth）或模块加载失败
   • 更新生命周期消息：如服务停止回退（service stop fallbacks）、配置覆盖/备份（config overwrites/backups）、服务重载时机（service reload timing）
   • 通道身份认证（channel auth）：若通道在更新后返回 401/认证失败，请先检查 ~/.openclaw/service-env/*.env 中 token 行引号损坏问题（参见 Pattern #23），再假设上游凭证已被轮换
   • 上下文引擎（context-engine）回退
   • 主动内存（active-memory）超时
   • 事件循环（event loop）性能下降
   • 任务重启阻塞（task restart blocking）
   • 网关就绪后自动清除的瞬态 UI/WebSocket 作用域错误（transient post-restart UI/websocket scope errors）

7. 升级后审计运行时/任务健康度。
   检查以下内容：

   • 陈旧的运行中任务（stale running tasks）
   • 丢失的任务（lost tasks）
   • 投递失败（delivery failures）
   • 时间戳不一致
   • cron 作业中持久化的 sessionKey 指向活跃通道车道（如 agent::discord:direct:*），尽管其 sessionTarget 设置为 isolated

   即使软件包更新成功，若陈旧任务阻塞重启或导致审计持续报错，系统仍处于不健康状态。

8. 验证主模型路由（primary model route），而非仅依赖整体 agent 成功状态。
   使用全新 session id 执行窄范围直连 agent 冒烟测试（smoke test），并检查返回的元数据：

   • 最终 provider 与模型
   • 运行时（runtime）或 harness id
   • fallbackAttempts
   • provider 身份认证错误
   • 模块加载错误
   • 模式（schema）校验错误

   若主模型失败、仅靠回退 provider 完成运行，则 status: ok 不足以视为成功。
   即使 plugins doctor 显示无误，对运行时插件而言，也须通过一次全新的直连 agent 运行，证实预期 harness 可成功加载并执行，才可认定其健康。

9. 若更新由 OpenClaw 内部发起，请将其视为特殊风险场景审计。
   OpenClaw agent 有时可更新自身正在运行的软件包，但该路径多次导致主机软件包已变更、而受管服务却未加载或未重启。请从外部 SSH Shell 中验证：

   • 请求版本是否确实已安装
   • 更新后受管服务是否已加载/运行
   • gateway /health 接口与通道是否已恢复
   • 执行一次干净的 openclaw gateway restart 是否可在不更改任何软件包的前提下，修复已安装但未加载的服务

   切勿将 agent 对话中的最终消息视为权威依据。请信任更新后的主机实际状态。

10. 至少测试一条具有代表性的 cron 路径。
    检查以下内容：

• cron 有效载荷模型数量
• 按 agentId 统计的模型数量，以便在不混淆全量与迷你（mini）cron 路由的前提下，回滚临时 provider 适配方案
• 持久化的 sessionKey 值，尤其关注隔离型 cron 作业的通道/直接消息密钥
• 命名或高价值 cron 作业的状态
• 手动 cron run 行为
• --expect-final 是否确实在当前构建版本中等待最终完成
• 特定作业 ID 的近期运行历史（而非仅当前作业状态），以便将陈旧的上次运行错误与活跃回归问题分离

若 cron 验证仅能证明任务入队（enqueue），请在交接说明（handoff notes）中明确指出。

11. 当插件安装发生变更时，执行针对性 npm/插件供应链抽查。
    此步骤在插件安装失败、外部插件回退或公开 npm 安全通告（public npm compromise advisory）后尤为重要。需检查：

• 插件更新波动后，openclaw security audit --deep 是否标记了未锁定（unpinned）的 npm 插件规范
• 已安装包版本是否与安全通告列表完全一致
• 插件安装根目录（如 ~/.openclaw/npm/node_modules）
• 全局 OpenClaw/npm 根目录（如 /opt/homebrew/lib/node_modules）
• package.json 中明显的恶意生命周期钩子（malicious lifecycle hooks）
• 安全通告中提及的持久化产物（persistence artifacts）
• 锁文件（lockfiles）与配置文件中的强指标（strong IoCs）

需声明本次检查的局限性：运行中系统的扫描无法证明某软件包此前从未安装或已被卸载。

12. 执行最小范围修复，随后再次验证。
    常见修复顺序如下：

• 干净地停止 gateway
• 更新主机软件包
• 如有必要，刷新插件注册表（plugin registry）
• 修复或更新损坏的插件安装
• 重启 gateway
• 重新运行 doctor、plugins doctor、status --deep、channels status --deep 与 tasks audit

首要排查位置

诊断更新后故障时，请按以下顺序开展：

• 服务状态：服务管理器、PID、/health
• 主机版本：openclaw --version
• 插件不匹配：openclaw plugins doctor
• 配置漂移：openclaw doctor
• 通道真实状态：openclaw channels status --deep
• 任务账本：openclaw tasks audit
• 模型/运行时路由真实状态：直连冒烟测试元数据与回退尝试
• 运行时症状：gateway 日志

何时查阅参考资料

请首先阅读本文件。

当出现以下情形时，请打开 references/failure-patterns.md：

• doctor 或 plugins doctor 指向一个看似已知的回归问题
• channels status 或日志结果与表观服务健康状态矛盾
• 插件安装、安装记录或配置状态与磁盘实际内容不符
• 更新已完成，但主机仍响应缓慢、断连、日志嘈杂或部分功能失效

请在主工作流已缩小潜在故障范围后，再使用参考资料文件进行症状匹配与具体案例参考。

捆绑插件 vs 外部插件规则

切勿假设插件故障即意味着“插件缺失”。

常见情形有三类：

• 该能力本应为捆绑插件，但陈旧配置仍指向旧 provider/插件 ID。
• 该能力确为捆绑插件，但全局安装的 npm 插件版本错误，导致其遮蔽了捆绑插件。
• 该能力未被捆绑，因此修复方式应为检查 npm 或 ClawHub，并同步安装记录。

通道插件（channel plugin）是第二类情形的良好示例：主机可正确升级，但仍加载了旧版全局安装的插件包。

若该功能未被捆绑，请在重写配置前先检查 npm 和 ClawHub。

修复思维准则

优先采用最小修复动作，使系统状态恢复一致：

• 在重装全部插件前，先刷新注册表
• 在移除所有插件前，先更新单个陈旧插件
• 当辅助命令看似成功但警告仍存时，请检查实际配置文件
• 在删除插件侧 node_modules 前，请先验证第三方插件是否需要本地运行时依赖

切勿止步于“服务已启动”。一次良好的收尾应满足：

• 已安装正确版本
• gateway 被正确管理
• 通道已连接
• 预期主模型路由成功执行，且未发生意外回退
• cron 有效载荷模型与代表性 cron 作业均健康
• plugins doctor 无报错，或报错原因已明确解释
• 任务审计（task audit）未携带新的阻塞性错误

交接说明（Handoff Notes）

若升级暴露的是 OpenClaw 自身缺陷（bug），而非本地配置漂移，请收集足够信息供后续运维人员或项目/支持联系人使用。请勿假设用户拥有特定外部账号，或希望创建公开报告。

• 升级前后确切版本号
• 相关配置键（config keys）
• 主模型路由在升级前后的变化（含 runtime id）
• 直连冒烟测试结果元数据，尤其关注 fallbackAttempts
• cron 模型映射在任何临时适配方案前后的变化（含迷你路由及继承/默认模型情形）
• 首次异常 cron 运行的确切时间戳（来自 openclaw cron runs --id ），而非仅操作员发现异常的时间
• 跨越通道/会话边界的 cron sessionKey 值（替换其中的通道 ID 与账号 ID 为占位符后）
• 实际加载的插件源路径（plugin source path）
• 任意失败 npm 插件的已安装包版本与文件布局
• 该插件属于捆绑安装还是全局安装
• gateway OS 服务用户与命令路径（当其与 SSH 用户不同时）
• 确切的更新命令与所选通道
• 外部插件是否使用通道特定版本，或采用了回退策略
• 服务停止/重启消息（尤其当服务管理器需启用回退停止/卸载路径时）
• doctor/plugins doctor 的警告文本
• 启动失败或重启附近的具体日志行

对外共享前，请对交接说明进行脱敏处理：

• 移除主机名、用户名、IP 地址、机器名、令牌（tokens）、账号 ID、通道 ID 及个人作业名称
• 将本地路径替换为占位符，如 、 和 ~/.openclaw
• 对私有提示（prompt）/会话内容进行概括性描述，而非直接引用原文
• 在需复现缺陷时，保留确切版本号、包名、模型 ID、运行时 ID 与错误类名

关于具体回归模式与示例症状，请参阅 references/failure-patterns.md。

本技能的更新规范

当其他运维人员或 agent 在不同 OpenClaw 主机上获得新认知时：

• 除非现有步骤明显错误，否则不得删除已有工作流步骤
• 不得以更窄的失败模式替代现有失败模式
• 优先采用增量式更新（additive updates），而非重写
• 将新发现的回归模式添加至 references/failure-patterns.md
• 仅当新认知改变了大多数主机推荐的审计顺序时，才收紧本文件中的主工作流

若新发现属主机特有或尚不确定，请以新失败模式形式添加，包含：

• 症状（symptom）
• 应检查项（what to inspect）
• 其重要性（why it matters）

切勿因当前主机未触发某旧模式，便悄然删除之。