Charpup/openclaw-upgrade-ops
GitHub: Charpup/openclaw-upgrade-ops
一个 Claude Code 技能，为 OpenClaw 网关提供端到端升级编排与升级后故障应急响应能力，将历史故障经验沉淀为可快速检索的症状索引和叙述式案例。
Stars: 0 | Forks: 0
# 🚀 OpenClaw 升级运维
[](https://docs.claude.com/en/docs/claude-code/skills)
[](./LICENSE)
[](https://github.com/Charpup/openclaw-upgrade-ops/releases)
[](https://github.com/Charpup/openclaw-upgrade-ops/commits/main)
[](https://docs.openclaw.ai)
[](https://github.com/anthropics/skills)
## 功能说明
OpenClaw 在 systemd 下运行多通道代理网关（Discord / 飞书 / Telegram / ……），而 `npm install -g openclaw@` 是一个耗时 3 分钟的操作，但在出现某些细微问题时（npm 镜像延迟、systemd PATH 偏移、共享 `node_modules` 的并发重新暂存、Discord 斜杠命令速率限制），过去曾导致网关宕机数小时。此技能使 Claude 成为一名主动运维人员，能够：
- **端到端驱动升级** — 预快照 → 版本锁定安装 → 配置验证 → 10 项冒烟测试 (T1–T10) → 24 小时延迟重新冒烟计时器 → 在遇到任何阻断情况时回滚
- **将实时症状映射到已记录的故障模式** — `references/symptom-index.md` 是一个支持 `⌘F` 查找的索引，可从字面日志字符串（`ETARGET`、`env-http-proxy-agent`、`channelConnectGrace`、"0 plugins"、……）映射到带有单行修复方案的 F1–F12
- **承载叙述性案例研究**（`examples/incident--.md`），以便未来的 Claude 继承的不仅是*规则*，还有*推理过程* — 错误的假设、豁然开朗的时刻、持久的修复
- **针对已知回归加固冒烟测试** — 在 v4.24 的 `models status --probe` 开始挂起后，T4 已升级为*重启恢复*；F10（镜像延迟）仅在数小时后才会显现，因此 24 小时重新冒烟计时器是 SOP 的一部分
- **自动化重复性操作** — `preflight-snapshot.sh`、`post-smoke.sh`、`scan-broken-deps.sh`（F11 检测器）、`enable-24h-resmoke.sh`
旨在与 [`openclaw-auditor`](https://github.com/Charpup/openclaw-auditor)（静态配置审计 / 代理提案审查）配合使用。此技能 = *主动运维*，另一个 = *静态审查*。
## 安装
```
git clone https://github.com/Charpup/openclaw-upgrade-ops ~/.claude/skills/openclaw-upgrade-ops
```
Claude Code 会自动发现 `~/.claude/skills/` 下的技能。该技能会在出现诸如 `openclaw upgrade`、`npm install -g openclaw`、`openclaw rollback`、`openclaw doctor`、`gateway crash loop`、`0 plugins`、`discord bot offline`、`ETARGET`、"F9 / F10 / F11 / F12"、升级后冒烟测试等关键词时触发。
**要求**主机具备：`npm`、`node`、`jq`、`openclaw` CLI 以及 `systemctl`（此技能围绕用户模式的 `openclaw-gateway.service` 构建）。仅限 Linux + macOS — Windows 主机不在 systemd 下运行 OpenClaw。
脚本遵循 `OPENCLAW_HOME`（默认为 `$HOME/.openclaw`）并将升级日志写入 `$OPENCLAW_HOME/upgrade-logs/` — 非_root_安装开箱即用。
## 包含内容
```
openclaw-upgrade-ops/
├── SKILL.md # Skill entry — decision flow, quick checklist, anti-patterns
├── references/
│ ├── symptom-index.md # Literal log string → F1–F12 → 1-line fix (⌘F lookup)
│ ├── diagnostic-recipes.md # R1–R10 copy-paste fix sequences
│ ├── smoke-tests.md # T1–T10 template (incl. T4-hardened restart-resilience)
│ └── success-patterns.md # S1–S9 (rule + why + when + counter-example)
├── examples/ # Real incidents (timeline + wrong assumptions + fix)
│ ├── incident-2026-04-08-f3-orphan-procs.md # F3 zombie process OOM
│ ├── incident-2026-04-12-f4-schema-renderMode.md # F4 v4.2 → v4.11 schema break
│ ├── incident-2026-04-27-v4.24-upgrade-f9.md # F9 systemd PATH stale, lazy bundled-deps
│ └── incident-2026-04-28-f10-f11-f12-chain.md # F10/F11/F12 cascade (mirror lag → trunc deps → rate limit)
├── scripts/
│ ├── preflight-snapshot.sh # Baseline + backup before upgrade (Step 1+2 of SOP)
│ ├── post-smoke.sh # T1–T10 runner + T4-hardened + F11 prophylactic scan
│ ├── scan-broken-deps.sh # F11 detector — scans node_modules for truncated .js
│ └── enable-24h-resmoke.sh # Install S9 systemd timer for 24h delayed re-smoke
└── evals/
└── evals.json # 5 test prompts (upgrade / F9 vs F10 / F11 / F12 / rollback)
```
目录布局遵循 [skill-creator 标准](https://github.com/anthropics/skills/tree/main/skill-creator)。
## 快速示例
用户询问 *"我可以将 OpenClaw 升级到 v2026.4.24 吗？"*。该技能会引导执行 SOP：
1. **预检** — `bash scripts/preflight-snapshot.sh` 捕获基线 + 9.2 GB 的 `~/.openclaw/` cp -a 备份
2. **安装** — `systemctl --user stop openclaw-gateway && npm install -g openclaw@2026.4.24`
3. **验证并启动** — `openclaw config validate && systemctl --user start openclaw-gateway`
4. **冒烟测试** — `bash scripts/post-smoke.sh`。T4 检测到网关启动时带有 `0 plugins` (阻断)。
5. **诊断** — 在 `references/symptom-index.md` 中 ⌘F 查找 `failed to stage bundled runtime deps` → **F9** (systemd PATH 过时)：v4.24 的 lazy-deps 模式针对 systemd 单元的 `Environment=PATH=` 执行 `spawnSync('npm', …)`，而该路径引用了 `~/.nvm/current/bin` — 但此主机上不存在 nvm 的 `current` 符号链接
6. **修复** — `references/diagnostic-recipes.md` R-F9：置入 `~/.config/systemd/user/openclaw-gateway.service.d/path-fix.conf`，将 `/root/.nvm/versions/node/v22.22.0/bin` 添加到 PATH 中，然后执行 `daemon-reload && restart`
7. **重新冒烟测试** — T4 现在通过，plugins=5
8. **T+24h 重新冒烟测试** — `bash scripts/enable-24h-resmoke.sh` 设置一个一次性计时器，因为 **F10**（Tencent npm 镜像延迟）仅在*下一次*网关重启数小时后才会显现，届时延迟安装器首次向镜像请求一个 npmjs.org 已有但镜像尚未同步的版本
完整的逐分钟跟踪记录位于 [`examples/incident-2026-04-27-v4.24-upgrade-f9.md`](./examples/incident-2026-04-27-v4.24-upgrade-f9.md)，而 F10/F11/F12 的后续连锁反应位于 [`examples/incident-2026-04-28-f10-f11-f12-chain.md`](./examples/incident-2026-04-28-f10-f11-f12-chain.md)。
## 配套技能
[`openclaw-auditor`](https://github.com/Charpup/openclaw-auditor) — 对 `openclaw.json` 和 Galatea 代理提案进行静态审计（5 步框架，通过 `docs.openclaw.ai/llms.txt` 进行 schema-first 获取，Notion 回写）。这两个技能相互交叉引用，并共享一个权威的故障模式分类法。
| 关注点 | 本技能 (upgrade-ops) | auditor |
|---|---|---|
| 主动版本升级编排 | ✅ | ❌ |
| 升级后冒烟测试 (T1–T10) | ✅ | ❌ |
| 实时事件响应（F1–F12 查找、配方、脚本） | ✅ | ❌ |
| 静态审查配置 diff 或代理提案 | ❌ | ✅ |
| 5 步审计框架 + Notion 回写 | ❌ | ✅ |
| 症状 → F 模式查找 | ✅ (运行时角度) | ✅ (审计角度) |
| 事件案例研究 | ✅ (运维时间线) | ✅ (审计推理) |
**权威的 F1–F12 操作手册**独立于这两个技能，位于操作者本地的 `knowledge-base/openclaw/upgrade-runbook.md` — 它是故障模式表 (§2)、冒烟测试方法 (§5)、回滚 SOP (§6) 和变更日志 (§9) 的唯一事实来源。每个技能从各自的角度交叉引用该操作手册：upgrade-ops 重新整理操作手册内容，以便在事件发生时进行快速的基于症状的访问；auditor 重新整理相同的内容，用于审查时的风险分类。
当不确定该调用哪个技能时：您正在*更改*某些内容吗？请使用 upgrade-ops。您正在*审查*其他人提议更改的内容吗？请使用 auditor。
## 积累技能
每当此技能遇到**新**的故障模式（即尚未包含在 F1–F12 中的模式），请按以下顺序更新，以便下一位操作者（或下一个 Claude）能够继承经验教训：
1. 在 `references/symptom-index.md` 中添加一行 — 字面日志字符串 + 单行原因 + 单行修复方案
2. 撰写叙述性案例研究 `examples/incident--.md` — 时间线、*尝试了什么*、错误的假设、豁然开朗的时刻、持久的修复 + 回滚
3. 将该行添加到权威操作手册的第 §2 节（`knowledge-base/openclaw/upgrade-runbook.md`）— 保持两者同步
4. 如果修复方案是一个可复制粘贴的命令序列，请在 `references/diagnostic-recipes.md` 中添加一个 R 小节
5. 如果修复方案是可自动化的，请在 `scripts/` 中添加一个脚本
6. 如果新模式能与相邻模式区分开来，请在 `evals/evals.json` 中添加一个评估行（`F9-vs-F10` 正是出于这个原因的一个真实测试用例）
`examples/` 之所以是叙述性的（而不仅仅是规则），是因为规则本身无法泛化 — *"F11 = rm undici"* 并不能教你如何识别前所未见的 F11 类故障。而时间线可以。请不要跳过错误假设部分。完整指南请参见 [`SKILL.md` 第 "Compounding the skill" 节](./SKILL.md)。
## 关于权威操作手册的说明
`SKILL.md`、`references/symptom-index.md` 和 `references/smoke-tests.md` 将 `~/claude_code_workspace/knowledge-base/openclaw/upgrade-runbook.md` 引用为 F1–F12 表和 SOP 的事实来源。**该文件未打包在本仓库中** — 它是操作者主机上的操作手册，是随着真实事件一起积累成长起来的。
如果您在自己的 OpenClaw 主机上采用此技能：
- 可以选择将操作手册镜像到您自己的知识库中，并在发现新故障模式时保持更新（推荐 — 当*您*将其作为事件后的工件进行维护时，操作手册是最有价值的）
- 或者替换 SKILL.md / 引用中的路径为您自己的等效路径，如果您只打算使用仓库内的材料，也可以完全删除这些引用
仓库内的材料（`SKILL.md` + `references/` + `examples/` + `scripts/`）对于**日常操作是自给自足的**；对操作手册的引用只是指向更深层上下文的指针，而不是硬性依赖。在全新安装时，指向它的链接将会是 404 — 这属于预期情况。
## 贡献
欢迎提交 Issues 和 PR。对于新的故障模式，请包含：
- 字面症状（错误字符串、日志行或用户描述的行为 — 即您会在症状索引中输入并 ⌘F 查找的内容）
- 错误到正确诊断路径的简短时间线
- 持久的修复 + 回滚命令（如果适用，也可注明“无需回滚”）
- 该修复是否可以机械化转化为脚本
## 许可证
[MIT](./LICENSE) © 2026 Charpup
标签：AI助手技能, Claude Code, Discord, GNU通用公共许可证, MIT协议, Node.js, npm, systemd, Telegram, 代理网关, 冒烟测试, 多通道代理网关, 应用安全, 开源, 故障排查, 案例研究, 症状索引, 系统回滚, 系统运维, 自动化升级, 运维自动化, 配置验证, 飞书