{"id":"d6118d01-6f22-4554-8aa4-c8f72d92610d","entityType":"agent","slug":"clawhub-tangsuann-oc-upgrade","name":"openclaw-upgrade","canonicalUrl":"https://www.xpersona.co/agent/clawhub-tangsuann-oc-upgrade","canonicalPath":"/agent/clawhub-tangsuann-oc-upgrade","generatedAt":"2026-10-10T10:44:40.574Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T08:38:03.677Z","emptyReason":null},"description":"OpenClaw版本升级标准流程。每次说\"升级openclaw\"、\"openclaw升级\"、\"更新openclaw\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案 Skill: openclaw-upgrade Owner: tangsuann Summary: OpenClaw版本升级标准流程。每次说\"升级openclaw\"、\"openclaw升级\"、\"更新openclaw\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案 Tags: latest:1.9.1 Version history: v1.9.1 | 2026-08-13T08:33:50.197Z | user Windows 升级主入口改为分离式 schtasks 一次性任务；openclaw update 标记为已实测失败（DLL 锁定 + 自杀陷阱，2026-08-13 实测导致 gateway 宕机 3.5h）；失败教训写入 changelog v1.9.0 | 2026-08-13T02:51:13.841Z | user 环境自适应版：合并 Win","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s176dgnza5ckzy094pj10h0xm186axgy:oc-upgrade","sourceUrl":"https://clawhub.ai/tangsuann/oc-upgrade","homepage":"https://clawhub.ai/tangsuann/skills/oc-upgrade","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/tangsuann/oc-upgrade","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/tangsuann/skills/oc-upgrade","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"OpenClaw版本升级标准流程。每次说\"升级openclaw\"、\"openclaw升级\"、\"更新openclaw\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案 Skill: openclaw-upgrade Owner: tangsuann Sum"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T08:38:03.677Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T08:38:03.677Z","emptyReason":null},"stars":null,"forks":null,"downloads":1552,"packageName":null,"latestVersion":"1.9.1","tractionLabel":"1.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T08:38:03.677Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T08:38:03.677Z","lastCrawledAt":"2026-10-10T08:38:03.677Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T08:38:03.677Z","lastVerifiedAt":null,"highlights":[{"version":"1.9.1","createdAt":"2026-08-13T08:33:50.197Z","changelog":"Windows 升级主入口改为分离式 schtasks 一次性任务；openclaw update 标记为已实测失败（DLL 锁定 + 自杀陷阱，2026-08-13 实测导致 gateway 宕机 3.5h）；失败教训写入 changelog","fileCount":3,"zipByteSize":11387},{"version":"1.9.0","createdAt":"2026-08-13T02:51:13.841Z","changelog":"环境自适应版：合并 Windows(schtasks/PowerShell) 与 Linux(systemd/bash) 双分支，第零步环境探测+分类，Windows 分支适配 DLL 锁定+自杀陷阱(openclaw update 主入口)，Linux 分支保留先装后停流程","fileCount":3,"zipByteSize":10925},{"version":"1.7.2","createdAt":"2026-07-27T13:48:06.372Z","changelog":"debug retry test","fileCount":3,"zipByteSize":9721},{"version":"1.7.1","createdAt":"2026-07-27T13:46:54.846Z","changelog":"修复description字段被写成changelog的元问题：description改回带触发关键词的场景描述（每次说升级openclaw时必须执行），历史变更记录移至正文Changelog小节。（补发：1.8.0此前发布返回成功但未真正同步到registry，本次重新发布验证）","fileCount":3,"zipByteSize":9914},{"version":"1.8.0","createdAt":"2026-07-27T13:38:36.199Z","changelog":"修复description字段被写成changelog的元问题：description改回带触发关键词的场景描述（每次说升级openclaw时必须执行），历史变更记录移至正文Changelog小节。根因是description是agent discovery的语义匹配依据，写成changelog会导致agent无法自然语言触发这个skill","fileCount":3,"zipByteSize":10117},{"version":"1.7.0","createdAt":"2026-07-27T10:53:26.613Z","changelog":"第零步新增Node版本检测+IPv4/IPv6速度探测（07-27 NAS欢欢升级事故：Node版本不兼容导致gateway拒绝启动+IPv6比IPv4慢6倍卡住npm install），第一步新增engines.node核对，第六-八步配套处理","fileCount":3,"zipByteSize":10809},{"version":"1.6.0","createdAt":"2026-07-27T09:18:50.598Z","changelog":"第八步重启改用平台gateway工具而非裸调systemctl，避免自身进程树被波及（2026-07-27 NAS欢欢自写脚本从进程内部nohup+systemctl stop把整个进程组一起杀死的教训，同一风险模型也适用于restart）","fileCount":3,"zipByteSize":8609},{"version":"1.5.0","createdAt":"2026-05-19T03:54:39.293Z","changelog":"恢复实战改进版：插件failed自检+自动修复、doctor--fix、多用户/tmp/jiti权限检查、通知cron延至3分钟、brave/feishu/codex实战经验（NAS欢欢版本冲突后重新发布）","fileCount":3,"zipByteSize":6694}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s176dgnza5ckzy094pj10h0xm186axgy:oc-upgrade","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T10:44:40.573Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tangsuann-oc-upgrade/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T08:38:03.677Z","emptyReason":null},"readme":"Skill: openclaw-upgrade\n\nOwner: tangsuann\n\nSummary: OpenClaw版本升级标准流程。每次说\"升级openclaw\"、\"openclaw升级\"、\"更新openclaw\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案\n\nTags: latest:1.9.1\n\nVersion history:\n\nv1.9.1 | 2026-08-13T08:33:50.197Z | user\n\nWindows 升级主入口改为分离式 schtasks 一次性任务；openclaw update 标记为已实测失败（DLL 锁定 + 自杀陷阱，2026-08-13 实测导致 gateway 宕机 3.5h）；失败教训写入 changelog\n\nv1.9.0 | 2026-08-13T02:51:13.841Z | user\n\n环境自适应版：合并 Windows(schtasks/PowerShell) 与 Linux(systemd/bash) 双分支，第零步环境探测+分类，Windows 分支适配 DLL 锁定+自杀陷阱(openclaw update 主入口)，Linux 分支保留先装后停流程\n\nv1.7.2 | 2026-07-27T13:48:06.372Z | user\n\ndebug retry test\n\nv1.7.1 | 2026-07-27T13:46:54.846Z | user\n\n修复description字段被写成changelog的元问题：description改回带触发关键词的场景描述（每次说升级openclaw时必须执行），历史变更记录移至正文Changelog小节。（补发：1.8.0此前发布返回成功但未真正同步到registry，本次重新发布验证）\n\nv1.8.0 | 2026-07-27T13:38:36.199Z | user\n\n修复description字段被写成changelog的元问题：description改回带触发关键词的场景描述（每次说升级openclaw时必须执行），历史变更记录移至正文Changelog小节。根因是description是agent discovery的语义匹配依据，写成changelog会导致agent无法自然语言触发这个skill\n\nv1.7.0 | 2026-07-27T10:53:26.613Z | user\n\n第零步新增Node版本检测+IPv4/IPv6速度探测（07-27 NAS欢欢升级事故：Node版本不兼容导致gateway拒绝启动+IPv6比IPv4慢6倍卡住npm install），第一步新增engines.node核对，第六-八步配套处理\n\nv1.6.0 | 2026-07-27T09:18:50.598Z | user\n\n第八步重启改用平台gateway工具而非裸调systemctl，避免自身进程树被波及（2026-07-27 NAS欢欢自写脚本从进程内部nohup+systemctl stop把整个进程组一起杀死的教训，同一风险模型也适用于restart）\n\nv1.5.0 | 2026-05-19T03:54:39.293Z | user\n\n恢复实战改进版：插件failed自检+自动修复、doctor--fix、多用户/tmp/jiti权限检查、通知cron延至3分钟、brave/feishu/codex实战经验（NAS欢欢版本冲突后重新发布）\n\nv1.3.0 | 2026-05-19T03:43:31.429Z | user\n\n新增第八步：重启前用cron设通知（+90s），确保爸比收到升级完成通知。sleep改为40s修复重启后通知丢失。\n\nv1.2.0 | 2026-05-19T03:24:34.984Z | user\n\n实战改进：加入插件failed自检+自动修复、doctor--fix步骤、多用户/tmp/jiti权限检查、通知cron延至3分钟、补充brave/feishu/codex实战经验\n\nv1.1.0 | 2026-05-18T16:33:26.599Z | user\n\n通用化改造：支持多环境（WSL2/NAS/Linux VM），自动探测代理/lossless-claw/override.conf，缺失组件自动跳过\n\nv1.0.0 | 2026-05-18T15:34:40.782Z | user\n\nOpenClaw 版本升级标准流程：版本确认、插件兼容性检查、5项备份（自适应lossless-claw大小）、升级验证、重启前设通知cron。多机器通用。\n\nArchive index:\n\nArchive v1.9.1: 3 files, 11387 bytes\n\nFiles: _meta.json (129b), skill-card.md (2701b), SKILL.md (25155b)\n\nFile v1.9.1:SKILL.md\n\n---\nname: \"openclaw-upgrade\"\ndescription: \"OpenClaw版本升级标准流程。每次说\\\"升级openclaw\\\"、\\\"openclaw升级\\\"、\\\"更新openclaw\\\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案\"\n---\n\n# OpenClaw 升级技能（环境自适应版）\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n\n> 本版把 Linux 原版（systemd/bash）与 Windows 适配版（schtasks/PowerShell）合并为一个技能：第零步先探测环境并分类，之后每步按 `[Windows]` / `[Linux]` 分支走。只维护一份，不再靠两份文件。\n\n## Changelog\n\n> description 字段只写触发场景，不写变更记录；每次改动的原因/教训记在这里。\n\n- 2026-08-13（实测事故）：`openclaw update`（A 方案）在 Windows 上实测失败——它内部是「先装后停」（Linux 模式），撞 DLL 锁定；且停 gateway 时把自身（gateway 子进程）一起杀死，npm install 根本没执行，gateway 宕机 3.5 小时无人拉起。教训：Windows 主入口改为「分离式 schtasks 一次性任务」，`openclaw update` 在 Windows 上禁用。\n- 2026-08-13：合并 Linux 原版 + Windows 适配版为「环境自适应版」。第零步升级为「环境探测 + 分类」（判定 OS 类型 + 服务托管方式），后续每步给出 `[Windows]`/`[Linux]` 双分支。Windows 分支保留 DLL 锁定 + 自杀陷阱两个硬坑（主入口 `openclaw update --tag`），Linux 分支保留原「先装后停」流程。原两个文件已归档到 `SKILL.linux-original.bak.md`（此版之前的 Windows 版内容见 git/历史）。\n- 2026-08-13：Windows 适配。本机（SCRIPT-S03-04，Windows Server 2016）实测：gateway 由 Windows 任务计划程序（schtasks）托管而非 systemd；gateway 进程加载了 node-pty-win32-x64 / tree-sitter 等原生 .node DLL，Windows 锁定运行中 DLL → 运行时直接 `npm install -g openclaw` 会 EBUSY/EPERM 失败；agent 运行在 gateway 进程内部不能自己 stop 自己。故 Windows 主入口改为 `openclaw update --tag <版本>`，裸 npm install 降级为分离式 schtasks 任务兜底。同时适配：npm registry=npmmirror（无代理）、无 curl.exe（Server 2016）改用 Invoke-WebRequest、.env 无 GITHUB_TOKEN、lossless-claw 是 npm 项目路径、消息通道 POPO 无 feishu。\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n- 2026-07-27：NAS欢欢用自写脚本升级，脚本从gateway进程内部nohup启动，第一步systemctl stop把整个进程组一起杀掉，脚本自己被杀死，npm install根本没跑起来，gateway停了近6小时无人察觉——本skill的流程设计（npm install前不停服务、重启只在最后单独一步、重启前先设好通知cron）天然规避了这个坑，但重启这一步本身如果裸调systemctl也仍有被自身进程树波及的理论风险，已在第八步/回滚方案中改为优先走平台 gateway 工具\n- 2026-07-27（同一事故的第二个坑）：NAS欢欢手动拉起gateway后agent恢复中断会话继续把npm包升到2026.7.1-2，但机器Node还是22.22.1，openclaw 2026.7.1-2要求Node≥22.22.3，gateway直接拒绝启动；且该NAS访问registry.npmjs.org走IPv6比IPv4慢6倍，codex插件依赖安装卡在慢速IPv6上4分半——第零步此前没查Node版本、没做IPv4/IPv6测速，两个真实缺口已补入\n- 2026-07-27（第三个坑，元问题）：description字段被写成changelog摘要，覆盖了触发关键词，导致agent在用户说\"升级openclaw\"时语义匹配不上这个skill。教训：description只写\"什么场景触发\"，绝不写\"这次改了什么\"；changelog一律写在本节。\n\n---\n\n## 环境分类路由表（探测后对照，一眼定位走哪个分支）\n\n| 维度 | [Windows] 分支 | [Linux] 分支 |\n|------|----------------|--------------|\n| 判定 | `$env:OS` = `Windows_NT`（PowerShell） | `uname -s` = `Linux`（bash） |\n| Shell | PowerShell / cmd | bash |\n| Gateway 托管 | 任务计划程序「OpenClaw Gateway」（schtasks） | `systemd --user`（`openclaw-gateway.service`） |\n| 原生 DLL 锁定 | ❗**有**（node-pty-win32-x64、tree-sitter）→ 运行中 `npm install -g` 必 EBUSY | 无（inode 替换，可运行中覆盖） |\n| **主升级入口** | **分离式 schtasks 一次性任务**（第六步 A） | `npm install -g openclaw@<版本>`（先装后停） |\n| 停服方式 | `gateway` 工具 / `schtasks /end`+`/run` | `gateway` 工具 / `systemctl --user restart` |\n| npm registry | npmmirror（无代理，无 IPv6 问题） | registry.npmjs.org（需代理检测 + IPv4/IPv6 测速） |\n| HTTP 探测工具 | `Invoke-WebRequest`（无 curl.exe） | `curl` |\n| 配置/凭证路径 | `$env:USERPROFILE\\.openclaw\\...` | `~/.openclaw/...` |\n| 启动脚本/override | `gateway.cmd` | `override.conf`（systemd drop-in） |\n| lossless-claw 路径 | npm 项目 `~\\.openclaw\\npm\\projects\\martian-engineering-lossless-claw-*` | `~/.openclaw/extensions/lossless-claw` |\n| 消息通道 | POPO（moltbot-popo） | 视部署（feishu 等） |\n| 多用户检测 | `C:\\Users\\*` 其他含 `.openclaw` 的 profile | `/home/*` + WSL 实例 |\n\n---\n\n## 第零步：环境探测 + 分类\n\n先判定平台，再跑对应分支的详细探测，**探测结果汇报给爸比，确认后继续**。\n\n### 0.1 平台判定\n\n```bash\n# 通用快速判定（任一条能出结果即可）\nuname -s          # 返回 \"Linux\" → Linux 分支；命令不存在 → Windows 分支\n```\n\n```powershell\n# Windows 下用这个\n$env:OS           # 返回 \"Windows_NT\" → Windows 分支\n```\n\nmacOS 等 bash 类环境按 `[Linux]` 分支处理（服务管理方式单独确认，见 0.3 末）。\n\n### 0.2 [Windows] 详细探测（PowerShell）\n\n```powershell\nWrite-Host \"=== OpenClaw 环境（Windows） ===\"\nWrite-Host \"用户: $env:USERNAME\"\nWrite-Host \"Home: $env:USERPROFILE\"\nWrite-Host \"npm global: $(npm prefix -g 2>$null)\"\n\n$nodeVer = (node --version 2>$null) -replace '^v',''\nWrite-Host \"\"\nWrite-Host \"=== Node.js 版本 ===\"\nif (-not $nodeVer) { Write-Host \"⚠️ 无法检测 Node 版本\" }\nelse {\n  Write-Host \"当前 Node: v$nodeVer\"\n  $nodeMajor = [int]($nodeVer -split '\\.')[0]\n  if ($nodeMajor -lt 22) { Write-Host \"⚠️ Node 主版本 $nodeMajor 低于 22，多数近期 OpenClaw 会拒绝启动\" }\n  else { Write-Host \"Node 主版本 $nodeMajor ✅（具体最低子版本见第一步核对）\" }\n}\nWrite-Host \"⚠️ 仅确认当前 Node 不够，必须第一步拿到目标版本 engines.node 后对比。\"\n\nWrite-Host \"\"\nWrite-Host \"=== registry 连通性 ===\"\n$reg = npm config get registry\nWrite-Host \"registry: $reg\"\ntry {\n  $r = Invoke-WebRequest -Uri $reg -UseBasicParsing -TimeoutSec 8 -Method Head\n  Write-Host \"连通 ✅ HTTP $($r.StatusCode)\"\n} catch { Write-Host \"⚠️ 访问 $reg 失败: $($_.Exception.Message)\" }\nWrite-Host \"HTTP_PROXY=[$env:HTTP_PROXY] HTTPS_PROXY=[$env:HTTPS_PROXY]（空=直连）\"\n\nWrite-Host \"\"\nWrite-Host \"=== 可选组件 ===\"\n$ll = Get-ChildItem \"$env:USERPROFILE\\.openclaw\\npm\\projects\" -Directory -ErrorAction SilentlyContinue |\n      Where-Object { $_.Name -like '*lossless-claw*' } | Select-Object -First 1\nif ($ll) {\n  $pkg = Get-Content \"$($ll.FullName)\\node_modules\\@martian-engineering\\lossless-claw\\package.json\" -Raw -ErrorAction SilentlyContinue | ConvertFrom-Json -ErrorAction SilentlyContinue\n  Write-Host \"lossless-claw: 已装 ver $($pkg.version)（项目 $($ll.Name)）\"\n} else { Write-Host \"lossless-claw: 未安装 ✅\" }\nWrite-Host \"消息通道: POPO (moltbot-popo)，无 feishu\"\n\nWrite-Host \"\"\nWrite-Host \"=== gateway 托管 ===\"\nschtasks /query /tn \"OpenClaw Gateway\" 2>$null | Select-String -Pattern \"任务名|正在运行|就绪|无法\"\nWrite-Host \"托管: Windows 任务计划程序（schtasks）\"\n\nWrite-Host \"\"\nWrite-Host \"=== 其他用户检测 ===\"\n$others = Get-ChildItem \"C:\\Users\" -Directory -ErrorAction SilentlyContinue |\n          Where-Object { $_.Name -ne $env:USERNAME -and (Test-Path \"$($_.FullName)\\.openclaw\") }\nif ($others) { Write-Host \"⚠️ 发现其他用户含 .openclaw：$($others.Name -join ', ')——npm install -g 影响共享 global 包\" }\nelse { Write-Host \"未发现其他 OpenClaw 用户 ✅（单用户）\" }\n```\n\n### 0.3 [Linux] 详细探测（bash）\n\n```bash\n# === OpenClaw 环境（Linux） ===\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\necho \"\"\necho \"=== Node.js 版本 ===\"\nNODE_VER=$(node --version 2>/dev/null | sed 's/^v//')\necho \"当前 Node: v${NODE_VER:-未知}\"\nif [ -z \"$NODE_VER\" ]; then\n  echo \"⚠️ 无法检测 Node 版本\"\nelse\n  NODE_MAJOR=$(echo \"$NODE_VER\" | cut -d. -f1)\n  [ \"$NODE_MAJOR\" -lt 22 ] && echo \"⚠️ Node 主版本 ${NODE_MAJOR} 低于 22，多数近期 OpenClaw 会拒绝启动\" || echo \"Node 主版本 ${NODE_MAJOR} ✅\"\nfi\necho \"⚠️ 仅确认当前 Node 不够，必须第一步拿到目标版本 engines.node 后对比。\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"; echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"; echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# IPv4/IPv6 速度探测（NAS 坑：IPv6 慢 6 倍会卡死 npm）\necho \"\"\necho \"=== registry IPv4/IPv6 速度探测 ===\"\nIPV4_TIME=$(timeout 5 curl -4 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\nIPV6_TIME=$(timeout 5 curl -6 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\necho \"IPv4: ${IPV4_TIME:-超时/不可用}s\"\necho \"IPv6: ${IPV6_TIME:-超时/不可用}s\"\nif [ -z \"$IPV6_TIME\" ]; then\n  echo \"IPv6 不可用/超时，建议升级/安装步骤强制 --force-ipv4 兜底\"\nelif python3 -c \"exit(0 if float('$IPV6_TIME') > float('${IPV4_TIME:-999}') * 2 else 1)\" 2>/dev/null; then\n  echo \"⚠️ IPv6 明显慢于 IPv4（超2倍），建议 export NODE_OPTIONS=\\\"--dns-result-order=ipv4first\\\" 后再 npm install\"\nelse\n  echo \"IPv4/IPv6 速度接近 ✅\"\nfi\n\n# 可选组件\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\necho \"override.conf: $([ -f \"$OVERRIDE\" ] && echo 存在 || echo 不存在)\"\n\necho \"服务管理: systemd --user\"\n\n# /tmp/jiti 权限（codex EACCES 坑）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /tmp/jiti)\n  [ \"$JITI_PERM\" != \"1777\" ] && echo \"⚠️ /tmp/jiti 权限 $JITI_PERM，建议 sudo chmod 1777 /tmp/jiti\" || echo \"/tmp/jiti: 1777 ✅\"\nelse\n  echo \"/tmp/jiti: 不存在 ✅\"\nfi\n\n# 其他 OpenClaw 用户（同机共享 npm global 风险）\necho \"\"\necho \"=== 其他 OpenClaw 用户检测 ===\"\nSAME_HOST_USERS=\"\"\nfor U in $(ls /home/ 2>/dev/null); do\n  if [ \"$U\" != \"$(whoami)\" ] && [ -d \"/home/$U/.openclaw\" ]; then\n    echo \"用户(同主机): $U\"; SAME_HOST_USERS=\"$SAME_HOST_USERS $U\"\n  fi\ndone\n# WSL 检测（bash 环境可能嵌套 WSL）\nif command -v powershell.exe &>/dev/null; then\n  WSL_LIST=$(powershell.exe -NoProfile -Command \"wsl --list --verbose\" 2>/dev/null | grep -i -v \"NAME\\|Windows\" || true)\n  [ -n \"$WSL_LIST\" ] && echo \"$WSL_LIST\" && echo \"⚠️ 检测到 WSL 实例，注意多实例共享 npm global 风险\"\nfi\n\necho \"npm global path: $(npm root -g 2>/dev/null)\"\nif [ -z \"$SAME_HOST_USERS\" ] && [ -z \"$WSL_LIST\" ]; then echo \"未发现其他 OpenClaw 用户 ✅\"; fi\n\n# 若非 systemd（pm2/docker 等），在此确认实际管理方式\necho \"⚠️ 若本机不是 systemd --user 托管，请在此确认实际服务管理方式，第八步/回滚的重启命令要相应改\"\n```\n\n---\n\n## 第一步：确认目标版本\n\n```powershell\n# [Windows] PowerShell\n$cur = openclaw --version 2>$null\n$target = npm view openclaw version\nWrite-Host \"当前: $cur\"\nWrite-Host \"最新: $target\"\nnpm view \"openclaw@$target\" engines.node\nopenclaw update status\nopenclaw update --dry-run --tag $target\n```\n\n```bash\n# [Linux] bash\nopenclaw --version\nnpm view openclaw version\nnpm view openclaw@${TARGET_VER} engines.node\n# 发行说明（有 GITHUB_TOKEN 时）：\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"import json,sys; print(json.load(sys.stdin).get('body','')[:3000])\"\n```\n\n- **Node 版本核对**：当前 Node 满足 `engines.node` → 继续；不满足 → 必须先升级 Node（Windows 用 nvm-windows/MSI，Linux 用 apt/nvm，同大版本线内，勿跨大版本线），否则升级后 gateway 直接拒绝启动。\n- 向爸比汇报：当前版本、目标版本、release highlights、**Node 是否满足**，等确认（Node 不满足时一并确认是否先升 Node）。\n\n---\n\n## 第二步：检查插件兼容性\n\n```bash\nopenclaw plugins list\n```\n\n只看 `enabled` 插件，**非 stock、手动/第三方安装**的插件重点核对（stock 随主包升级）：\n\n- **[Windows]** `moltbot-popo`（POPO 通道，LobsterAI 第三方扩展）+ `lossless-claw`（npm 项目）\n- **[Linux]** `lossless-claw`（`~/.openclaw/extensions/`）+ `@openclaw/feishu`（如有）等\n\n发行说明里搜关键词（无 GITHUB_TOKEN 时用 `web_fetch` 抓 `https://github.com/openclaw/openclaw/releases/tag/v<版本>`，或 `openclaw update --dry-run` 输出）。有⚠️风险说清楚。\n\n---\n\n## 第三步：记录插件快照\n\n```powershell\n# [Windows]\nopenclaw plugins list > \"$env:TEMP\\plugins-before-$target.txt\"\n```\n\n```bash\n# [Linux]\nopenclaw plugins list > /tmp/plugins-before-${TARGET_VER}.txt\n```\n\n---\n\n## 第四步：备份\n\n```powershell\n# [Windows] PowerShell\n$cur = ([regex]::Match((openclaw --version 2>$null), '(\\d+\\.\\d+\\.\\d+)')).Groups[1].Value\nCopy-Item \"$env:USERPROFILE\\.openclaw\\openclaw.json\" \"$env:USERPROFILE\\.openclaw\\openclaw.json.bak-$cur\" -Force\nCopy-Item \"$env:USERPROFILE\\.openclaw\\.env\"            \"$env:USERPROFILE\\.openclaw\\.env.bak-$cur\" -Force\nCopy-Item \"$env:USERPROFILE\\.openclaw\\gateway.cmd\"     \"$env:USERPROFILE\\.openclaw\\gateway.cmd.bak-$cur\" -Force\n# lossless-claw（npm 项目，只备份 package.json，node_modules 不备份）\n$ll = Get-ChildItem \"$env:USERPROFILE\\.openclaw\\npm\\projects\" -Directory -ErrorAction SilentlyContinue |\n      Where-Object { $_.Name -like '*lossless-claw*' } | Select-Object -First 1\nif ($ll) { Copy-Item \"$($ll.FullName)\\package.json\" \"$($ll.FullName)\\package.json.bak-$cur\" -Force }\nGet-ChildItem \"$env:USERPROFILE\\.openclaw\" -Filter \"*.bak-$cur\" | Select-Object Name\n```\n\n```bash\n# [Linux] bash\nCURRENT_VER=$(openclaw --version 2>/dev/null | grep -oP '[\\d.]+' | head -1)\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nLOSSLESS_DIR=\"$HOME/.openclaw/extensions/lossless-claw\"\n\ncp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-${CURRENT_VER}\ncp ~/.openclaw/.env ~/.openclaw/.env.bak-${CURRENT_VER}\n[ -f \"$OVERRIDE\" ] && cp \"$OVERRIDE\" \"${OVERRIDE}.bak-${CURRENT_VER}\" || echo \"override.conf 不存在，跳过\"\n# lossless-claw：node_modules>500MB 时只备份 package.json/plugin.json/dist\nif [ -d \"$LOSSLESS_DIR\" ]; then\n  LOSSLESS_VER=$(cat \"$LOSSLESS_DIR/package.json\" | python3 -c \"import json,sys;print(json.load(sys.stdin)['version'])\")\n  LOSSLESS_NM_SIZE=$(du -sm \"$LOSSLESS_DIR/node_modules/\" 2>/dev/null | cut -f1)\n  LOSSLESS_BAK=\"$HOME/.openclaw/extensions/lossless-claw.bak-${LOSSLESS_VER}\"\n  mkdir -p \"$LOSSLESS_BAK\"\n  if [ \"${LOSSLESS_NM_SIZE:-0}\" -gt 500 ]; then\n    cp \"$LOSSLESS_DIR/package.json\" \"$LOSSLESS_DIR/openclaw.plugin.json\" \"$LOSSLESS_BAK/\"\n    cp -r \"$LOSSLESS_DIR/dist\" \"$LOSSLESS_BAK/\"\n  else\n    cp -r \"$LOSSLESS_DIR/.\" \"$LOSSLESS_BAK/\"\n  fi\nfi\n# feishu（如有）\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\n[ -d \"$FEISHU_DIR\" ] && mkdir -p \"${FEISHU_DIR}.bak-${CURRENT_VER}\" && cp \"$FEISHU_DIR/package.json\" \"${FEISHU_DIR}.bak-${CURRENT_VER}/\"\n```\n\n确认核心备份（openclaw.json + .env）存在后再继续。\n\n---\n\n## 第五步：设好重启后通知 cron（先于重启执行）\n\n**两个分支共用，升级前必须先设。** gateway 重启会中断当前 session，重启后是全新上下文，不记得升级完成这件事。\n\n用 `cron` 工具创建：\n- `schedule`: `at`，时间 = 当前时间 + 3 分钟\n- `payload.kind`: `systemEvent`\n- `payload.text`: 升级完成通知（含版本号、插件状态、耗时）\n- `sessionTarget`: `main`\n- `deleteAfterRun`: `true`\n\n示例：`🎉 OpenClaw 升级完成！v<旧> → v<新>，插件全部正常（lossless-claw ✅ <通道> ✅），耗时约X分钟。`\n\n> ⚠️ 3分钟是安全值，90秒有时会在 gateway 恢复前触发导致通知失败。\n\n---\n\n## 第六步：执行升级\n\n**等爸比说「执行」才动手。** 若第零步发现其他用户 / 第一步发现 Node 不满足，先解决再继续。\n\n### A. [Windows] 分支（主入口 = 分离式 schtasks 一次性任务）\n\n> ⚠️ **`openclaw update` 在 Windows 上已实测失败（2026-08-13）**：内部是「先装后停」（Linux 模式），撞 DLL 锁定；且停 gateway 时把自身（gateway 子进程）一起杀死，npm install 根本没执行，gateway 宕机 3.5 小时无人拉起。**Windows 禁用 `openclaw update`，直接用下面的分离式任务。**\n> 裸 `npm install -g` 同样不可行（DLL 锁定，见路由表）。\n\n分离式 schtasks 一次性任务——独立进程在 gateway 停止期间完成安装，绕开自杀陷阱 + DLL 锁定：\n\n**1. 写独立升级脚本 `C:\\Users\\n3186\\.openclaw\\upgrade-once.ps1`：**\n\n```powershell\n# C:\\Users\\n3186\\.openclaw\\upgrade-once.ps1\nparam([string]$Version)\n$ErrorActionPreference = 'Continue'\n$log = \"$env:USERPROFILE\\.openclaw\\logs\\upgrade-once.log\"\n\"$(Get-Date -Format o) 开始升级到 $Version\" | Out-File $log -Append\n\n# 等 gateway 完全停止（最多 120s）\n$deadline = (Get-Date).AddSeconds(120)\nwhile ((Get-Date) -lt $deadline) {\n  $p = Get-CimInstance Win32_Process -Filter \"name='node.exe'\" | Where-Object { $_.CommandLine -like '*openclaw*index.js*gateway*' }\n  if (-not $p) { break }\n  Start-Sleep -Seconds 3\n}\n\n# 安装目标版本（gateway 已停，无 DLL 锁定）\nnpm install -g \"openclaw@$Version\" *>> $log\n\n# 重启 gateway 任务\nschtasks /run /tn \"OpenClaw Gateway\" >> $log 2>&1\n\"$(Get-Date -Format o) 完成\" | Out-File $log -Append\n```\n\n**2. 注册一次性任务（now + 2 分钟）：**\n\n```powershell\n$st = (Get-Date).AddMinutes(2).ToString('HH:mm')\nschtasks /create /tn \"OpenClaw Upgrade Once\" `\n  /tr \"powershell -NoProfile -ExecutionPolicy Bypass -File C:\\Users\\n3186\\.openclaw\\upgrade-once.ps1 -Version $target\" `\n  /sc ONCE /st $st /f\n```\n\n**3. 触发 gateway 停**（`gateway` 工具 action=restart 走 supervisor 握手，勿直接 kill）。流程：gateway 停 → 一次性任务到点跑（无锁）→ npm install → `schtasks /run` 拉起 gateway → 第五步通知 cron 触发。\n\n### B. [Linux] 分支（先装后停）\n\n```bash\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\n  echo \"使用代理: 127.0.0.1:7890\"\nelse\n  echo \"直连安装\"\nfi\nif [ \"${IPV6_SLOWER:-0}\" = \"1\" ]; then\n  export NODE_OPTIONS=\"--dns-result-order=ipv4first\"\n  echo \"已强制 DNS 优先 IPv4\"\nfi\nnpm install -g openclaw@${TARGET_VER}\n```\n\n---\n\n## 第七步：验证\n\n```powershell\n# [Windows]\nopenclaw --version; node --version\nopenclaw doctor\nopenclaw plugins list\nif (Test-Path \"$env:TEMP\\plugins-before-$target.txt\") { Compare-Object (Get-Content \"$env:TEMP\\plugins-before-$target.txt\") (openclaw plugins list) }\n```\n\n```bash\n# [Linux]\nopenclaw --version; node --version\nopenclaw doctor --fix 2>&1 | tail -5\nopenclaw doctor\nFAILED=$(openclaw plugins list 2>/dev/null | grep -i \"fail\\|error\" | grep -v \"grep\")\n[ -n \"$FAILED\" ] && echo \"⚠️ 插件加载失败：$FAILED\" || echo \"✅ 所有插件加载正常\"\ndiff /tmp/plugins-before-${TARGET_VER}.txt <(openclaw plugins list 2>/dev/null)\n```\n\n验收标准（全部通过才继续）：版本=目标、Node 满足 engines.node、lossless-claw 仍在 enabled、消息通道（POPO/feishu）仍在 enabled、doctor Errors=0、无插件加载失败。**任一不通过 → 立即回滚，不继续。**\n\n> [Windows] 注意：`plugins list` 可能显示部分 stock 插件 disabled，是默认配置非损坏，对比快照只看 enabled→disabled 的**实际变化**。\n\n---\n\n## 第八步：重启 gateway\n\n**两分支都优先走平台 `gateway` 工具（action=restart），不裸调停服命令。**\n\n```\n优先：gateway 工具，action=restart，note=\"OpenClaw 升级完成，重启生效\"\n```\n\n> [Windows] A 方案 `openclaw update` 已自动重启，本步通常无需手动。只有第七步通过但 gateway 还跑旧版本时才走本步。\n\n无 `gateway` 工具时才退回：\n\n```powershell\n# [Windows]\nschtasks /end /tn \"OpenClaw Gateway\"\nschtasks /run /tn \"OpenClaw Gateway\"\n```\n\n```bash\n# [Linux]\nsystemctl --user restart openclaw-gateway.service\n```\n\n第五步的 cron 会在重启后自动触发，通知爸比升级完成。\n\n---\n\n## ⏪ 回滚方案\n\n任一步骤出问题立即执行。\n\n```powershell\n# [Windows]\n$prev = '<回退版本，如 2026.6.6>'\nnpm install -g \"openclaw@$prev\"   # gateway 需先停，参照第六步 A 兜底分离式任务\nCopy-Item \"$env:USERPROFILE\\.openclaw\\openclaw.json.bak-$prev\" \"$env:USERPROFILE\\.openclaw\\openclaw.json\" -Force\nCopy-Item \"$env:USERPROFILE\\.openclaw\\.env.bak-$prev\"            \"$env:USERPROFILE\\.openclaw\\.env\" -Force\nCopy-Item \"$env:USERPROFILE\\.openclaw\\gateway.cmd.bak-$prev\"     \"$env:USERPROFILE\\.openclaw\\gateway.cmd\" -Force\n# 优先 gateway 工具 action=restart，无工具才：schtasks /run /tn \"OpenClaw Gateway\"\n```\n\n```bash\n# [Linux]\nPREV_VER=<回退版本>\nnpm install -g openclaw@${PREV_VER}\ncp ~/.openclaw/openclaw.json.bak-${PREV_VER} ~/.openclaw/openclaw.json\ncp ~/.openclaw/.env.bak-${PREV_VER} ~/.openclaw/.env\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\n[ -f \"${OVERRIDE}.bak-${PREV_VER}\" ] && cp \"${OVERRIDE}.bak-${PREV_VER}\" \"$OVERRIDE\"\nLOSSLESS_BAK=$(ls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | sort | tail -1)\n[ -n \"$LOSSLESS_BAK\" ] && rm -rf \"$HOME/.openclaw/extensions/lossless-claw\" && cp -r \"$LOSSLESS_BAK\" \"$HOME/.openclaw/extensions/lossless-claw\"\nsystemctl --user daemon-reload\n# 优先 gateway 工具 action=restart，无工具才：systemctl --user restart openclaw-gateway.service\n```\n\n等消息通道收到「重启完毕，在线了」通知，告知爸比回滚完成及原因。\n\n---\n\n## 注意事项\n\n**两分支通用：**\n- 升级前必须核对目标版本 Node 最低要求（`npm view openclaw@<版本> engines.node`），不满足先升 Node。\n- 升级前必须先设通知 cron，否则重启后没人知道结果。\n- 重启一律优先 `gateway` 工具，不裸调停服命令。\n- 不要从 agent 里直接 stop/kill gateway（agent 是 gateway 子进程，会自杀）。\n- skill description 字段只写触发场景，不写变更记录。\n- 升级完成通知 cron 设 3 分钟而非更短。\n- brave 插件外部化（2026.5.12 起）：升级后若遇 \"web_search provider is not available: brave\"，执行 `openclaw plugins install --force @openclaw/brave-plugin` 后重启。\n\n**[Windows] 专属：**\n- 不要裸 `npm install -g openclaw`（DLL 锁定，EBUSY/EPERM）。首选 `openclaw update --tag`。\n- 无 curl.exe（Server 2016），HTTP 探测用 `Invoke-WebRequest`/`Invoke-RestMethod`。\n- .env 无 GITHUB_TOKEN，发行说明用 `npm view`/`openclaw update status`/`--dry-run`/`web_fetch`。\n- lossless-claw 是 npm 项目路径（`~\\.openclaw\\npm\\projects\\*`），不是 `extensions/`。\n- 消息通道是 POPO（moltbot-popo），兼容性检查对象是它，无 feishu。\n- npm registry=npmmirror，无代理、无 IPv6 慢速问题；若改回 registry.npmjs.org 再启用 Linux 的代理/IPv6 测速。\n\n**[Linux] 专属：**\n- 系统访问 registry.npmjs.org，注意代理 + IPv4/IPv6 测速，IPv6 慢就 `NODE_OPTIONS=\"--dns-result-order=ipv4first\"`。\n- `npm install -g` 影响同机所有用户共享的 global 包，先做多用户检测。\n- `/tmp/jiti` 需 1777（codex EACCES 坑，多用户同机）。\n- feishu 插件路径 `~/.openclaw/npm/node_modules/@openclaw/feishu`，升级后注册失败执行 `openclaw plugins install --force @openclaw/feishu` 后重启。\n- systemd service 不读 .bashrc，代理若需在 service 生效要配 override.conf 或 EnvironmentFile。\n- lossless-claw 路径 `~/.openclaw/extensions/lossless-claw`，每次升级必须检查兼容（4.14 踩过坑）。\n- 服务管理默认 systemd --user，pm2/docker 等请相应改第八步/回滚的重启命令。\n\nFile v1.9.1:_meta.json\n\n{\n  \"ownerId\": \"kn79f0shgp6jenfxa0cfqgm25x82m4bq\",\n  \"slug\": \"oc-upgrade\",\n  \"version\": \"1.9.1\",\n  \"publishedAt\": 1786610030197\n}\n\nFile v1.9.1:skill-card.md\n\n## Description:\n\nOpenClaw upgrade procedure that guides an agent through environment detection, Windows schtasks or Linux systemd upgrade paths, backup, verification, gateway restart, and rollback.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tangsuann](https://clawhub.ai/user/tangsuann)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use this skill to perform OpenClaw version upgrades with platform-specific checks for Windows scheduled tasks and Linux systemd environments. It helps sequence compatibility checks, backups, installation, validation, restart, notification, and rollback steps.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can replace a global OpenClaw package, restart the gateway, inspect local account layout, and create temporary scheduled execution artifacts.\n\nMitigation: Use it only in environments where those operations are acceptable, and review the planned commands before execution.\n\nRisk: Target version, package registry, and Node.js compatibility issues can leave the gateway unavailable after upgrade.\n\nMitigation: Pin and verify the target OpenClaw version, registry, and required Node.js engine before installing, then run the documented validation checks before considering the upgrade complete.\n\nRisk: The Windows upgrade path includes a hard-coded user path and temporary scheduled task/script artifacts.\n\nMitigation: Replace the hard-coded path with the target user's actual OpenClaw path and remove the scheduled task and temporary script after the upgrade.\n\nRisk: Backup files may include .env secrets, and broad permission changes such as chmod 1777 can widen exposure.\n\nMitigation: Protect or remove .env backups after rollback risk has passed, and avoid broad permission changes unless they are explicitly required and reviewed.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/tangsuann/skills/oc-upgrade)\n- [Publisher profile](https://clawhub.ai/user/tangsuann)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline shell and PowerShell command blocks]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Includes platform-specific operational steps, validation criteria, and rollback guidance.]\n\n## Skill Version(s):\n\n1.9.1 (source: server-resolved release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.9.0: 3 files, 10925 bytes\n\nFiles: _meta.json (129b), skill-card.md (2418b), SKILL.md (23818b)\n\nFile v1.9.0:SKILL.md\n\n---\nname: \"openclaw-upgrade\"\ndescription: \"OpenClaw版本升级标准流程。每次说\\\"升级openclaw\\\"、\\\"openclaw升级\\\"、\\\"更新openclaw\\\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案\"\n---\n\n# OpenClaw 升级技能（环境自适应版）\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n\n> 本版把 Linux 原版（systemd/bash）与 Windows 适配版（schtasks/PowerShell）合并为一个技能：第零步先探测环境并分类，之后每步按 `[Windows]` / `[Linux]` 分支走。只维护一份，不再靠两份文件。\n\n## Changelog\n\n> description 字段只写触发场景，不写变更记录；每次改动的原因/教训记在这里。\n\n- 2026-08-13：合并 Linux 原版 + Windows 适配版为「环境自适应版」。第零步升级为「环境探测 + 分类」（判定 OS 类型 + 服务托管方式），后续每步给出 `[Windows]`/`[Linux]` 双分支。Windows 分支保留 DLL 锁定 + 自杀陷阱两个硬坑（主入口 `openclaw update --tag`），Linux 分支保留原「先装后停」流程。原两个文件已归档到 `SKILL.linux-original.bak.md`（此版之前的 Windows 版内容见 git/历史）。\n- 2026-08-13：Windows 适配。本机（SCRIPT-S03-04，Windows Server 2016）实测：gateway 由 Windows 任务计划程序（schtasks）托管而非 systemd；gateway 进程加载了 node-pty-win32-x64 / tree-sitter 等原生 .node DLL，Windows 锁定运行中 DLL → 运行时直接 `npm install -g openclaw` 会 EBUSY/EPERM 失败；agent 运行在 gateway 进程内部不能自己 stop 自己。故 Windows 主入口改为 `openclaw update --tag <版本>`，裸 npm install 降级为分离式 schtasks 任务兜底。同时适配：npm registry=npmmirror（无代理）、无 curl.exe（Server 2016）改用 Invoke-WebRequest、.env 无 GITHUB_TOKEN、lossless-claw 是 npm 项目路径、消息通道 POPO 无 feishu。\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n- 2026-07-27：NAS欢欢用自写脚本升级，脚本从gateway进程内部nohup启动，第一步systemctl stop把整个进程组一起杀掉，脚本自己被杀死，npm install根本没跑起来，gateway停了近6小时无人察觉——本skill的流程设计（npm install前不停服务、重启只在最后单独一步、重启前先设好通知cron）天然规避了这个坑，但重启这一步本身如果裸调systemctl也仍有被自身进程树波及的理论风险，已在第八步/回滚方案中改为优先走平台 gateway 工具\n- 2026-07-27（同一事故的第二个坑）：NAS欢欢手动拉起gateway后agent恢复中断会话继续把npm包升到2026.7.1-2，但机器Node还是22.22.1，openclaw 2026.7.1-2要求Node≥22.22.3，gateway直接拒绝启动；且该NAS访问registry.npmjs.org走IPv6比IPv4慢6倍，codex插件依赖安装卡在慢速IPv6上4分半——第零步此前没查Node版本、没做IPv4/IPv6测速，两个真实缺口已补入\n- 2026-07-27（第三个坑，元问题）：description字段被写成changelog摘要，覆盖了触发关键词，导致agent在用户说\"升级openclaw\"时语义匹配不上这个skill。教训：description只写\"什么场景触发\"，绝不写\"这次改了什么\"；changelog一律写在本节。\n\n---\n\n## 环境分类路由表（探测后对照，一眼定位走哪个分支）\n\n| 维度 | [Windows] 分支 | [Linux] 分支 |\n|------|----------------|--------------|\n| 判定 | `$env:OS` = `Windows_NT`（PowerShell） | `uname -s` = `Linux`（bash） |\n| Shell | PowerShell / cmd | bash |\n| Gateway 托管 | 任务计划程序「OpenClaw Gateway」（schtasks） | `systemd --user`（`openclaw-gateway.service`） |\n| 原生 DLL 锁定 | ❗**有**（node-pty-win32-x64、tree-sitter）→ 运行中 `npm install -g` 必 EBUSY | 无（inode 替换，可运行中覆盖） |\n| **主升级入口** | `openclaw update --tag <版本> --yes` | `npm install -g openclaw@<版本>`（先装后停） |\n| 停服方式 | `gateway` 工具 / `schtasks /end`+`/run` | `gateway` 工具 / `systemctl --user restart` |\n| npm registry | npmmirror（无代理，无 IPv6 问题） | registry.npmjs.org（需代理检测 + IPv4/IPv6 测速） |\n| HTTP 探测工具 | `Invoke-WebRequest`（无 curl.exe） | `curl` |\n| 配置/凭证路径 | `$env:USERPROFILE\\.openclaw\\...` | `~/.openclaw/...` |\n| 启动脚本/override | `gateway.cmd` | `override.conf`（systemd drop-in） |\n| lossless-claw 路径 | npm 项目 `~\\.openclaw\\npm\\projects\\martian-engineering-lossless-claw-*` | `~/.openclaw/extensions/lossless-claw` |\n| 消息通道 | POPO（moltbot-popo） | 视部署（feishu 等） |\n| 多用户检测 | `C:\\Users\\*` 其他含 `.openclaw` 的 profile | `/home/*` + WSL 实例 |\n\n---\n\n## 第零步：环境探测 + 分类\n\n先判定平台，再跑对应分支的详细探测，**探测结果汇报给爸比，确认后继续**。\n\n### 0.1 平台判定\n\n```bash\n# 通用快速判定（任一条能出结果即可）\nuname -s          # 返回 \"Linux\" → Linux 分支；命令不存在 → Windows 分支\n```\n\n```powershell\n# Windows 下用这个\n$env:OS           # 返回 \"Windows_NT\" → Windows 分支\n```\n\nmacOS 等 bash 类环境按 `[Linux]` 分支处理（服务管理方式单独确认，见 0.3 末）。\n\n### 0.2 [Windows] 详细探测（PowerShell）\n\n```powershell\nWrite-Host \"=== OpenClaw 环境（Windows） ===\"\nWrite-Host \"用户: $env:USERNAME\"\nWrite-Host \"Home: $env:USERPROFILE\"\nWrite-Host \"npm global: $(npm prefix -g 2>$null)\"\n\n$nodeVer = (node --version 2>$null) -replace '^v',''\nWrite-Host \"\"\nWrite-Host \"=== Node.js 版本 ===\"\nif (-not $nodeVer) { Write-Host \"⚠️ 无法检测 Node 版本\" }\nelse {\n  Write-Host \"当前 Node: v$nodeVer\"\n  $nodeMajor = [int]($nodeVer -split '\\.')[0]\n  if ($nodeMajor -lt 22) { Write-Host \"⚠️ Node 主版本 $nodeMajor 低于 22，多数近期 OpenClaw 会拒绝启动\" }\n  else { Write-Host \"Node 主版本 $nodeMajor ✅（具体最低子版本见第一步核对）\" }\n}\nWrite-Host \"⚠️ 仅确认当前 Node 不够，必须第一步拿到目标版本 engines.node 后对比。\"\n\nWrite-Host \"\"\nWrite-Host \"=== registry 连通性 ===\"\n$reg = npm config get registry\nWrite-Host \"registry: $reg\"\ntry {\n  $r = Invoke-WebRequest -Uri $reg -UseBasicParsing -TimeoutSec 8 -Method Head\n  Write-Host \"连通 ✅ HTTP $($r.StatusCode)\"\n} catch { Write-Host \"⚠️ 访问 $reg 失败: $($_.Exception.Message)\" }\nWrite-Host \"HTTP_PROXY=[$env:HTTP_PROXY] HTTPS_PROXY=[$env:HTTPS_PROXY]（空=直连）\"\n\nWrite-Host \"\"\nWrite-Host \"=== 可选组件 ===\"\n$ll = Get-ChildItem \"$env:USERPROFILE\\.openclaw\\npm\\projects\" -Directory -ErrorAction SilentlyContinue |\n      Where-Object { $_.Name -like '*lossless-claw*' } | Select-Object -First 1\nif ($ll) {\n  $pkg = Get-Content \"$($ll.FullName)\\node_modules\\@martian-engineering\\lossless-claw\\package.json\" -Raw -ErrorAction SilentlyContinue | ConvertFrom-Json -ErrorAction SilentlyContinue\n  Write-Host \"lossless-claw: 已装 ver $($pkg.version)（项目 $($ll.Name)）\"\n} else { Write-Host \"lossless-claw: 未安装 ✅\" }\nWrite-Host \"消息通道: POPO (moltbot-popo)，无 feishu\"\n\nWrite-Host \"\"\nWrite-Host \"=== gateway 托管 ===\"\nschtasks /query /tn \"OpenClaw Gateway\" 2>$null | Select-String -Pattern \"任务名|正在运行|就绪|无法\"\nWrite-Host \"托管: Windows 任务计划程序（schtasks）\"\n\nWrite-Host \"\"\nWrite-Host \"=== 其他用户检测 ===\"\n$others = Get-ChildItem \"C:\\Users\" -Directory -ErrorAction SilentlyContinue |\n          Where-Object { $_.Name -ne $env:USERNAME -and (Test-Path \"$($_.FullName)\\.openclaw\") }\nif ($others) { Write-Host \"⚠️ 发现其他用户含 .openclaw：$($others.Name -join ', ')——npm install -g 影响共享 global 包\" }\nelse { Write-Host \"未发现其他 OpenClaw 用户 ✅（单用户）\" }\n```\n\n### 0.3 [Linux] 详细探测（bash）\n\n```bash\n# === OpenClaw 环境（Linux） ===\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\necho \"\"\necho \"=== Node.js 版本 ===\"\nNODE_VER=$(node --version 2>/dev/null | sed 's/^v//')\necho \"当前 Node: v${NODE_VER:-未知}\"\nif [ -z \"$NODE_VER\" ]; then\n  echo \"⚠️ 无法检测 Node 版本\"\nelse\n  NODE_MAJOR=$(echo \"$NODE_VER\" | cut -d. -f1)\n  [ \"$NODE_MAJOR\" -lt 22 ] && echo \"⚠️ Node 主版本 ${NODE_MAJOR} 低于 22，多数近期 OpenClaw 会拒绝启动\" || echo \"Node 主版本 ${NODE_MAJOR} ✅\"\nfi\necho \"⚠️ 仅确认当前 Node 不够，必须第一步拿到目标版本 engines.node 后对比。\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"; echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"; echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# IPv4/IPv6 速度探测（NAS 坑：IPv6 慢 6 倍会卡死 npm）\necho \"\"\necho \"=== registry IPv4/IPv6 速度探测 ===\"\nIPV4_TIME=$(timeout 5 curl -4 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\nIPV6_TIME=$(timeout 5 curl -6 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\necho \"IPv4: ${IPV4_TIME:-超时/不可用}s\"\necho \"IPv6: ${IPV6_TIME:-超时/不可用}s\"\nif [ -z \"$IPV6_TIME\" ]; then\n  echo \"IPv6 不可用/超时，建议升级/安装步骤强制 --force-ipv4 兜底\"\nelif python3 -c \"exit(0 if float('$IPV6_TIME') > float('${IPV4_TIME:-999}') * 2 else 1)\" 2>/dev/null; then\n  echo \"⚠️ IPv6 明显慢于 IPv4（超2倍），建议 export NODE_OPTIONS=\\\"--dns-result-order=ipv4first\\\" 后再 npm install\"\nelse\n  echo \"IPv4/IPv6 速度接近 ✅\"\nfi\n\n# 可选组件\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\necho \"override.conf: $([ -f \"$OVERRIDE\" ] && echo 存在 || echo 不存在)\"\n\necho \"服务管理: systemd --user\"\n\n# /tmp/jiti 权限（codex EACCES 坑）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /tmp/jiti)\n  [ \"$JITI_PERM\" != \"1777\" ] && echo \"⚠️ /tmp/jiti 权限 $JITI_PERM，建议 sudo chmod 1777 /tmp/jiti\" || echo \"/tmp/jiti: 1777 ✅\"\nelse\n  echo \"/tmp/jiti: 不存在 ✅\"\nfi\n\n# 其他 OpenClaw 用户（同机共享 npm global 风险）\necho \"\"\necho \"=== 其他 OpenClaw 用户检测 ===\"\nSAME_HOST_USERS=\"\"\nfor U in $(ls /home/ 2>/dev/null); do\n  if [ \"$U\" != \"$(whoami)\" ] && [ -d \"/home/$U/.openclaw\" ]; then\n    echo \"用户(同主机): $U\"; SAME_HOST_USERS=\"$SAME_HOST_USERS $U\"\n  fi\ndone\n# WSL 检测（bash 环境可能嵌套 WSL）\nif command -v powershell.exe &>/dev/null; then\n  WSL_LIST=$(powershell.exe -NoProfile -Command \"wsl --list --verbose\" 2>/dev/null | grep -i -v \"NAME\\|Windows\" || true)\n  [ -n \"$WSL_LIST\" ] && echo \"$WSL_LIST\" && echo \"⚠️ 检测到 WSL 实例，注意多实例共享 npm global 风险\"\nfi\n\necho \"npm global path: $(npm root -g 2>/dev/null)\"\nif [ -z \"$SAME_HOST_USERS\" ] && [ -z \"$WSL_LIST\" ]; then echo \"未发现其他 OpenClaw 用户 ✅\"; fi\n\n# 若非 systemd（pm2/docker 等），在此确认实际管理方式\necho \"⚠️ 若本机不是 systemd --user 托管，请在此确认实际服务管理方式，第八步/回滚的重启命令要相应改\"\n```\n\n---\n\n## 第一步：确认目标版本\n\n```powershell\n# [Windows] PowerShell\n$cur = openclaw --version 2>$null\n$target = npm view openclaw version\nWrite-Host \"当前: $cur\"\nWrite-Host \"最新: $target\"\nnpm view \"openclaw@$target\" engines.node\nopenclaw update status\nopenclaw update --dry-run --tag $target\n```\n\n```bash\n# [Linux] bash\nopenclaw --version\nnpm view openclaw version\nnpm view openclaw@${TARGET_VER} engines.node\n# 发行说明（有 GITHUB_TOKEN 时）：\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"import json,sys; print(json.load(sys.stdin).get('body','')[:3000])\"\n```\n\n- **Node 版本核对**：当前 Node 满足 `engines.node` → 继续；不满足 → 必须先升级 Node（Windows 用 nvm-windows/MSI，Linux 用 apt/nvm，同大版本线内，勿跨大版本线），否则升级后 gateway 直接拒绝启动。\n- 向爸比汇报：当前版本、目标版本、release highlights、**Node 是否满足**，等确认（Node 不满足时一并确认是否先升 Node）。\n\n---\n\n## 第二步：检查插件兼容性\n\n```bash\nopenclaw plugins list\n```\n\n只看 `enabled` 插件，**非 stock、手动/第三方安装**的插件重点核对（stock 随主包升级）：\n\n- **[Windows]** `moltbot-popo`（POPO 通道，LobsterAI 第三方扩展）+ `lossless-claw`（npm 项目）\n- **[Linux]** `lossless-claw`（`~/.openclaw/extensions/`）+ `@openclaw/feishu`（如有）等\n\n发行说明里搜关键词（无 GITHUB_TOKEN 时用 `web_fetch` 抓 `https://github.com/openclaw/openclaw/releases/tag/v<版本>`，或 `openclaw update --dry-run` 输出）。有⚠️风险说清楚。\n\n---\n\n## 第三步：记录插件快照\n\n```powershell\n# [Windows]\nopenclaw plugins list > \"$env:TEMP\\plugins-before-$target.txt\"\n```\n\n```bash\n# [Linux]\nopenclaw plugins list > /tmp/plugins-before-${TARGET_VER}.txt\n```\n\n---\n\n## 第四步：备份\n\n```powershell\n# [Windows] PowerShell\n$cur = ([regex]::Match((openclaw --version 2>$null), '(\\d+\\.\\d+\\.\\d+)')).Groups[1].Value\nCopy-Item \"$env:USERPROFILE\\.openclaw\\openclaw.json\" \"$env:USERPROFILE\\.openclaw\\openclaw.json.bak-$cur\" -Force\nCopy-Item \"$env:USERPROFILE\\.openclaw\\.env\"            \"$env:USERPROFILE\\.openclaw\\.env.bak-$cur\" -Force\nCopy-Item \"$env:USERPROFILE\\.openclaw\\gateway.cmd\"     \"$env:USERPROFILE\\.openclaw\\gateway.cmd.bak-$cur\" -Force\n# lossless-claw（npm 项目，只备份 package.json，node_modules 不备份）\n$ll = Get-ChildItem \"$env:USERPROFILE\\.openclaw\\npm\\projects\" -Directory -ErrorAction SilentlyContinue |\n      Where-Object { $_.Name -like '*lossless-claw*' } | Select-Object -First 1\nif ($ll) { Copy-Item \"$($ll.FullName)\\package.json\" \"$($ll.FullName)\\package.json.bak-$cur\" -Force }\nGet-ChildItem \"$env:USERPROFILE\\.openclaw\" -Filter \"*.bak-$cur\" | Select-Object Name\n```\n\n```bash\n# [Linux] bash\nCURRENT_VER=$(openclaw --version 2>/dev/null | grep -oP '[\\d.]+' | head -1)\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nLOSSLESS_DIR=\"$HOME/.openclaw/extensions/lossless-claw\"\n\ncp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-${CURRENT_VER}\ncp ~/.openclaw/.env ~/.openclaw/.env.bak-${CURRENT_VER}\n[ -f \"$OVERRIDE\" ] && cp \"$OVERRIDE\" \"${OVERRIDE}.bak-${CURRENT_VER}\" || echo \"override.conf 不存在，跳过\"\n# lossless-claw：node_modules>500MB 时只备份 package.json/plugin.json/dist\nif [ -d \"$LOSSLESS_DIR\" ]; then\n  LOSSLESS_VER=$(cat \"$LOSSLESS_DIR/package.json\" | python3 -c \"import json,sys;print(json.load(sys.stdin)['version'])\")\n  LOSSLESS_NM_SIZE=$(du -sm \"$LOSSLESS_DIR/node_modules/\" 2>/dev/null | cut -f1)\n  LOSSLESS_BAK=\"$HOME/.openclaw/extensions/lossless-claw.bak-${LOSSLESS_VER}\"\n  mkdir -p \"$LOSSLESS_BAK\"\n  if [ \"${LOSSLESS_NM_SIZE:-0}\" -gt 500 ]; then\n    cp \"$LOSSLESS_DIR/package.json\" \"$LOSSLESS_DIR/openclaw.plugin.json\" \"$LOSSLESS_BAK/\"\n    cp -r \"$LOSSLESS_DIR/dist\" \"$LOSSLESS_BAK/\"\n  else\n    cp -r \"$LOSSLESS_DIR/.\" \"$LOSSLESS_BAK/\"\n  fi\nfi\n# feishu（如有）\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\n[ -d \"$FEISHU_DIR\" ] && mkdir -p \"${FEISHU_DIR}.bak-${CURRENT_VER}\" && cp \"$FEISHU_DIR/package.json\" \"${FEISHU_DIR}.bak-${CURRENT_VER}/\"\n```\n\n确认核心备份（openclaw.json + .env）存在后再继续。\n\n---\n\n## 第五步：设好重启后通知 cron（先于重启执行）\n\n**两个分支共用，升级前必须先设。** gateway 重启会中断当前 session，重启后是全新上下文，不记得升级完成这件事。\n\n用 `cron` 工具创建：\n- `schedule`: `at`，时间 = 当前时间 + 3 分钟\n- `payload.kind`: `systemEvent`\n- `payload.text`: 升级完成通知（含版本号、插件状态、耗时）\n- `sessionTarget`: `main`\n- `deleteAfterRun`: `true`\n\n示例：`🎉 OpenClaw 升级完成！v<旧> → v<新>，插件全部正常（lossless-claw ✅ <通道> ✅），耗时约X分钟。`\n\n> ⚠️ 3分钟是安全值，90秒有时会在 gateway 恢复前触发导致通知失败。\n\n---\n\n## 第六步：执行升级\n\n**等爸比说「执行」才动手。** 若第零步发现其他用户 / 第一步发现 Node 不满足，先解决再继续。\n\n### A. [Windows] 分支（主入口 `openclaw update`）\n\n> 因 DLL 锁定 + 自杀陷阱，**不能**裸 `npm install -g`（见路由表）。\n\n```powershell\nopenclaw update --dry-run --tag $target   # 先干跑确认\nopenclaw update --tag $target --yes       # 爸比确认后正式执行（supervisor 自动停→装→启）\n```\n\n若 `openclaw update` 卡住/在安装步报 EBUSY/EPERM，改用 B 兜底（分离式 schtasks 一次性任务，在 gateway 停止期间安装）：\n\n```powershell\n# 1. 写独立脚本 C:\\Users\\n3186\\.openclaw\\upgrade-once.ps1\n# param([string]$Version)\n# $log = \"$env:USERPROFILE\\.openclaw\\logs\\upgrade-once.log\"\n# ... 等 gateway 停（轮询 Win32_Process）→ npm install -g \"openclaw@$Version\" → schtasks /run /tn \"OpenClaw Gateway\"\n\n# 2. 注册一次性任务（now+2min）\n$st = (Get-Date).AddMinutes(2).ToString('HH:mm')\nschtasks /create /tn \"OpenClaw Upgrade Once\" `\n  /tr \"powershell -NoProfile -ExecutionPolicy Bypass -File C:\\Users\\n3186\\.openclaw\\upgrade-once.ps1 -Version $target\" `\n  /sc ONCE /st $st /f\n\n# 3. 触发 gateway 停：gateway 工具 action=restart（走 supervisor 握手，勿直接 kill）\n```\n\n### B. [Linux] 分支（先装后停）\n\n```bash\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\n  echo \"使用代理: 127.0.0.1:7890\"\nelse\n  echo \"直连安装\"\nfi\nif [ \"${IPV6_SLOWER:-0}\" = \"1\" ]; then\n  export NODE_OPTIONS=\"--dns-result-order=ipv4first\"\n  echo \"已强制 DNS 优先 IPv4\"\nfi\nnpm install -g openclaw@${TARGET_VER}\n```\n\n---\n\n## 第七步：验证\n\n```powershell\n# [Windows]\nopenclaw --version; node --version\nopenclaw doctor\nopenclaw plugins list\nif (Test-Path \"$env:TEMP\\plugins-before-$target.txt\") { Compare-Object (Get-Content \"$env:TEMP\\plugins-before-$target.txt\") (openclaw plugins list) }\n```\n\n```bash\n# [Linux]\nopenclaw --version; node --version\nopenclaw doctor --fix 2>&1 | tail -5\nopenclaw doctor\nFAILED=$(openclaw plugins list 2>/dev/null | grep -i \"fail\\|error\" | grep -v \"grep\")\n[ -n \"$FAILED\" ] && echo \"⚠️ 插件加载失败：$FAILED\" || echo \"✅ 所有插件加载正常\"\ndiff /tmp/plugins-before-${TARGET_VER}.txt <(openclaw plugins list 2>/dev/null)\n```\n\n验收标准（全部通过才继续）：版本=目标、Node 满足 engines.node、lossless-claw 仍在 enabled、消息通道（POPO/feishu）仍在 enabled、doctor Errors=0、无插件加载失败。**任一不通过 → 立即回滚，不继续。**\n\n> [Windows] 注意：`plugins list` 可能显示部分 stock 插件 disabled，是默认配置非损坏，对比快照只看 enabled→disabled 的**实际变化**。\n\n---\n\n## 第八步：重启 gateway\n\n**两分支都优先走平台 `gateway` 工具（action=restart），不裸调停服命令。**\n\n```\n优先：gateway 工具，action=restart，note=\"OpenClaw 升级完成，重启生效\"\n```\n\n> [Windows] A 方案 `openclaw update` 已自动重启，本步通常无需手动。只有第七步通过但 gateway 还跑旧版本时才走本步。\n\n无 `gateway` 工具时才退回：\n\n```powershell\n# [Windows]\nschtasks /end /tn \"OpenClaw Gateway\"\nschtasks /run /tn \"OpenClaw Gateway\"\n```\n\n```bash\n# [Linux]\nsystemctl --user restart openclaw-gateway.service\n```\n\n第五步的 cron 会在重启后自动触发，通知爸比升级完成。\n\n---\n\n## ⏪ 回滚方案\n\n任一步骤出问题立即执行。\n\n```powershell\n# [Windows]\n$prev = '<回退版本，如 2026.6.6>'\nnpm install -g \"openclaw@$prev\"   # gateway 需先停，参照第六步 A 兜底分离式任务\nCopy-Item \"$env:USERPROFILE\\.openclaw\\openclaw.json.bak-$prev\" \"$env:USERPROFILE\\.openclaw\\openclaw.json\" -Force\nCopy-Item \"$env:USERPROFILE\\.openclaw\\.env.bak-$prev\"            \"$env:USERPROFILE\\.openclaw\\.env\" -Force\nCopy-Item \"$env:USERPROFILE\\.openclaw\\gateway.cmd.bak-$prev\"     \"$env:USERPROFILE\\.openclaw\\gateway.cmd\" -Force\n# 优先 gateway 工具 action=restart，无工具才：schtasks /run /tn \"OpenClaw Gateway\"\n```\n\n```bash\n# [Linux]\nPREV_VER=<回退版本>\nnpm install -g openclaw@${PREV_VER}\ncp ~/.openclaw/openclaw.json.bak-${PREV_VER} ~/.openclaw/openclaw.json\ncp ~/.openclaw/.env.bak-${PREV_VER} ~/.openclaw/.env\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\n[ -f \"${OVERRIDE}.bak-${PREV_VER}\" ] && cp \"${OVERRIDE}.bak-${PREV_VER}\" \"$OVERRIDE\"\nLOSSLESS_BAK=$(ls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | sort | tail -1)\n[ -n \"$LOSSLESS_BAK\" ] && rm -rf \"$HOME/.openclaw/extensions/lossless-claw\" && cp -r \"$LOSSLESS_BAK\" \"$HOME/.openclaw/extensions/lossless-claw\"\nsystemctl --user daemon-reload\n# 优先 gateway 工具 action=restart，无工具才：systemctl --user restart openclaw-gateway.service\n```\n\n等消息通道收到「重启完毕，在线了」通知，告知爸比回滚完成及原因。\n\n---\n\n## 注意事项\n\n**两分支通用：**\n- 升级前必须核对目标版本 Node 最低要求（`npm view openclaw@<版本> engines.node`），不满足先升 Node。\n- 升级前必须先设通知 cron，否则重启后没人知道结果。\n- 重启一律优先 `gateway` 工具，不裸调停服命令。\n- 不要从 agent 里直接 stop/kill gateway（agent 是 gateway 子进程，会自杀）。\n- skill description 字段只写触发场景，不写变更记录。\n- 升级完成通知 cron 设 3 分钟而非更短。\n- brave 插件外部化（2026.5.12 起）：升级后若遇 \"web_search provider is not available: brave\"，执行 `openclaw plugins install --force @openclaw/brave-plugin` 后重启。\n\n**[Windows] 专属：**\n- 不要裸 `npm install -g openclaw`（DLL 锁定，EBUSY/EPERM）。首选 `openclaw update --tag`。\n- 无 curl.exe（Server 2016），HTTP 探测用 `Invoke-WebRequest`/`Invoke-RestMethod`。\n- .env 无 GITHUB_TOKEN，发行说明用 `npm view`/`openclaw update status`/`--dry-run`/`web_fetch`。\n- lossless-claw 是 npm 项目路径（`~\\.openclaw\\npm\\projects\\*`），不是 `extensions/`。\n- 消息通道是 POPO（moltbot-popo），兼容性检查对象是它，无 feishu。\n- npm registry=npmmirror，无代理、无 IPv6 慢速问题；若改回 registry.npmjs.org 再启用 Linux 的代理/IPv6 测速。\n\n**[Linux] 专属：**\n- 系统访问 registry.npmjs.org，注意代理 + IPv4/IPv6 测速，IPv6 慢就 `NODE_OPTIONS=\"--dns-result-order=ipv4first\"`。\n- `npm install -g` 影响同机所有用户共享的 global 包，先做多用户检测。\n- `/tmp/jiti` 需 1777（codex EACCES 坑，多用户同机）。\n- feishu 插件路径 `~/.openclaw/npm/node_modules/@openclaw/feishu`，升级后注册失败执行 `openclaw plugins install --force @openclaw/feishu` 后重启。\n- systemd service 不读 .bashrc，代理若需在 service 生效要配 override.conf 或 EnvironmentFile。\n- lossless-claw 路径 `~/.openclaw/extensions/lossless-claw`，每次升级必须检查兼容（4.14 踩过坑）。\n- 服务管理默认 systemd --user，pm2/docker 等请相应改第八步/回滚的重启命令。\n\nFile v1.9.0:_meta.json\n\n{\n  \"ownerId\": \"kn79f0shgp6jenfxa0cfqgm25x82m4bq\",\n  \"slug\": \"oc-upgrade\",\n  \"version\": \"1.9.0\",\n  \"publishedAt\": 1786589473841\n}\n\nFile v1.9.0:skill-card.md\n\n## Description:\n\nOpenClaw version upgrade workflow that guides an agent through environment detection, Windows or Linux upgrade paths, backup, validation, notification, and rollback steps.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tangsuann](https://clawhub.ai/user/tangsuann)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use this skill when upgrading OpenClaw deployments. It helps an agent select the correct Windows or Linux procedure, verify prerequisites, preserve configuration, execute the upgrade, validate service health, and recover if validation fails.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill guides operational upgrade steps that can restart OpenClaw services or interrupt the current agent session.\n\nMitigation: Review every command before execution, set the completion notification before restart, and prefer the platform gateway tool over direct stop or kill commands.\n\nRisk: Upgrade steps can modify global npm packages, scheduled tasks, systemd services, and OpenClaw configuration files.\n\nMitigation: Confirm the target version and Node.js requirement, check plugin compatibility, and back up OpenClaw configuration and environment files before installing.\n\nRisk: Backups may include sensitive .env content or credentials such as GitHub release tokens.\n\nMitigation: Keep backups private, use least-privilege tokens, and remove stale backups when they are no longer needed.\n\n## Reference(s):\n\n- [OpenClaw release notes](https://github.com/openclaw/openclaw/releases/tag/v${TARGET_VER})\n- [OpenClaw release API](https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER})\n- [npm registry](https://registry.npmjs.org/)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration, markdown]\n\n**Output Format:** [Markdown with inline bash and PowerShell code blocks]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Includes operational checklists for Windows schtasks and Linux systemd upgrade paths.]\n\n## Skill Version(s):\n\n1.9.0 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.7.2: 3 files, 9721 bytes\n\nFiles: _meta.json (129b), skill-card.md (2279b), SKILL.md (20894b)\n\nFile v1.7.2:SKILL.md\n\n---\nname: \"openclaw-upgrade\"\ndescription: \"OpenClaw版本升级标准流程。每次说\\\"升级openclaw\\\"、\\\"openclaw升级\\\"、\\\"更新openclaw\\\"时必须执行，含Node版本+IPv4/IPv6探测\"\n---\n\n# OpenClaw 升级技能\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n\n## Changelog\n\n> description字段只写触发场景，不写变更记录；每次改动的原因/教训记在这里。\n\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n- 2026-07-27：NAS欢欢用自写脚本升级，脚本从gateway进程内部nohup启动，第一步systemctl stop把整个进程组一起杀掉，脚本自己被杀死，npm install根本没跑起来，gateway停了近6小时无人察觉——本skill的流程设计（npm install前不停服务、重启只在最后单独一步、重启前先设好通知cron）天然规避了这个坑，但重启这一步本身如果裸调systemctl也仍有被自身进程树波及的理论风险，已在第八步/回滚方案中改为优先走平台 gateway 工具\n- 2026-07-27（同一事故的第二个坑）：NAS欢欢在手动拉起gateway后，agent恢复中断会话继续把npm包升到2026.7.1-2，但机器Node还是22.22.1，openclaw 2026.7.1-2要求Node≥22.22.3，导致gateway直接拒绝启动；排查过程中还发现该NAS访问registry.npmjs.org走IPv6比IPv4慢6倍（4秒 vs 0.66秒），跨版本升级触发的codex插件依赖安装卡在慢速IPv6连接上4分半没有进展——本skill第零步此前完全没有检查Node版本、也没有IPv4/IPv6速度探测，是两个真实缺口，已补入第零步\n- 2026-07-27（第三个坑，元问题）：本skill（ClawHub slug: oc-upgrade）连续几次更新提案时，description字段被写成了\"这次改了什么\"的changelog摘要文风，覆盖掉了原本\"每次说升级openclaw时必须执行\"这类触发关键词描述。根据OpenClaw官方creating-skills文档：\"description is shown to the agent and in slash-command discovery\"——description是agent判断\"该不该调用这个skill\"的唯一语义匹配依据，不是变更记录位置。description被写成changelog后，agent在用户说\"升级openclaw\"时无法语义匹配上这个skill，导致同一台NAS上并存的旧版本`openclaw-upgrade`（本地非ClawHub版本，description里保留了触发关键词）被误当成\"唯一入口\"，而已经更新到最新内容的`oc-upgrade`因description不含触发语义而从未被自然语言调用触发。教训固化为规则：description字段只写\"什么场景触发\"，绝不写\"这次改了什么\"；changelog类内容一律写在本节。\n\n---\n\n## 第零步：环境探测\n\n在任何操作之前，先自动探测并汇报当前环境：\n\n```bash\n# === 环境探测 ===\necho \"=== OpenClaw 环境 ===\"\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\n\n# npm global 路径\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\n# Node.js 版本检测（2026-07-27新增：NAS欢欢升级openclaw到2026.7.1-2后，\n# 因Node版本(22.22.1)低于该版本要求的22.22.3，gateway直接拒绝启动，停机近1小时）\necho \"\"\necho \"=== Node.js 版本 ===\"\nNODE_VER=$(node --version 2>/dev/null | sed 's/^v//')\necho \"当前 Node: v${NODE_VER:-未知}\"\nif [ -z \"$NODE_VER\" ]; then\n  echo \"⚠️ 无法检测 Node 版本，node 命令不可用\"\nelse\n  NODE_MAJOR=$(echo \"$NODE_VER\" | cut -d. -f1)\n  if [ \"$NODE_MAJOR\" -lt 22 ]; then\n    echo \"⚠️ Node 主版本 ${NODE_MAJOR} 低于 22，多数近期 OpenClaw 版本会拒绝启动\"\n  else\n    echo \"Node 主版本 ${NODE_MAJOR} ✅（具体最低子版本要求见第一步「目标版本」核对）\"\n  fi\nfi\necho \"⚠️ 注意：仅确认当前 Node 版本不够，必须在第一步拿到目标版本的具体 Node 最低版本要求后，\n      两者对比才能判断是否需要先升级 Node。不要假设当前版本一定够用。\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"\n  echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"\n  echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# IPv4/IPv6 速度探测（2026-07-27新增：NAS欢欢升级触发的codex插件依赖安装\n# 卡在慢速IPv6连接上4分半没有进展，IPv6访问registry比IPv4慢6倍，是同一次事故的第二个真实缺口）\necho \"\"\necho \"=== registry IPv4/IPv6 速度探测 ===\"\nIPV4_TIME=$(timeout 5 curl -4 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\nIPV6_TIME=$(timeout 5 curl -6 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\necho \"IPv4: ${IPV4_TIME:-超时/不可用}s\"\necho \"IPv6: ${IPV6_TIME:-超时/不可用}s\"\nif [ -z \"$IPV6_TIME\" ]; then\n  echo \"IPv6 不可用或超时，npm install 默认可能仍会尝试 IPv6 优先，建议升级/安装步骤强制 --force-ipv4 兜底\"\nelif python3 -c \"exit(0 if float('$IPV6_TIME') > float('${IPV4_TIME:-999}') * 2 else 1)\" 2>/dev/null; then\n  echo \"⚠️ IPv6 明显慢于 IPv4（超2倍），npm install/npm update 建议强制 IPv4 避免卡顿：\"\n  echo \"   npm config set prefer-ipv4 true   # 或临时: npm install --force-ipv4（部分npm版本可能不支持此flag，改用 NODE_OPTIONS='--dns-result-order=ipv4first'）\"\n  echo \"   推荐：export NODE_OPTIONS=\\\"--dns-result-order=ipv4first\\\" 后再执行 npm install/update\"\nelse\n  echo \"IPv4/IPv6 速度接近，无需特殊处理 ✅\"\nfi\n\n# 可选组件检测\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nHAS_OVERRIDE=false\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\n[ -f \"$OVERRIDE\" ] && HAS_OVERRIDE=true\necho \"override.conf: $HAS_OVERRIDE\"\n\necho \"服务管理: systemd --user\"\n\n# 多用户 /tmp/jiti 权限检查（防止 codex EACCES 问题）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /tmp/jiti)\n  if [ \"$JITI_PERM\" != \"1777\" ]; then\n    echo \"⚠️ /tmp/jiti 权限为 $JITI_PERM，多用户环境可能导致 codex EACCES 错误\"\n    echo \"建议执行: sudo chmod 1777 /tmp/jiti\"\n  else\n    echo \"/tmp/jiti: 1777 ✅\"\n  fi\nelse\n  echo \"/tmp/jiti: 不存在 ✅\"\nfi\n\n# 扫描其他 OpenClaw 用户（同机不同用户共享 npm global 升级风险）\necho \"\"\necho \"=== 其他 OpenClaw 用户检测 ===\"\n\nSAME_HOST_USERS=\"\"\nfor U in $(ls /home/ 2>/dev/null); do\n  if [ \"$U\" != \"$(whoami)\" ] && [ -d \"/home/$U/.openclaw\" ]; then\n    echo \"用户(同主机): $U\"\n    SAME_HOST_USERS=\"$SAME_HOST_USERS $U\"\n  fi\ndone\n\nWSL_INSTANCES=\"\"\nif command -v powershell.exe &>/dev/null; then\n  WSL_LIST=$(powershell.exe -NoProfile -Command \"wsl --list --verbose\" 2>/dev/null | grep -i -v \"NAME\\|Windows\" || true)\n  if [ -n \"$WSL_LIST\" ]; then\n    echo \"$WSL_LIST\" | while read -r INSTANCE; do\n      INSTANCE=$(echo \"$INSTANCE\" | awk '{print $1}')\n      if [ -n \"$INSTANCE\" ] && [ \"$INSTANCE\" != \"$(hostname)\" ]; then\n        WSL_INSTANCES=\"$WSL_INSTANCES $INSTANCE\"\n        echo \"WSL实例: $INSTANCE\"\n        if [ -d \"/mnt/wsl/$INSTANCE/home/\" ]; then\n          for WU in /mnt/wsl/$INSTANCE/home/*/; do\n            WU=$(basename \"$WU\")\n            if [ -d \"/mnt/wsl/$INSTANCE/home/$WU/.openclaw\" ]; then\n              echo \"  → 用户 $WU 有 OpenClaw 安装\"\n              SAME_HOST_USERS=\"$SAME_HOST_USERS $WU@$INSTANCE\"\n            fi\n          done\n        fi\n      fi\n    done\n  else\n    echo \"WSL列表: 无输出（WSL interop 可能不可用，跳过）\"\n  fi\nelse\n  echo \"WSL列表: powershell.exe 不可用，跳过\"\nfi\n\necho \"npm global path: $(npm root -g 2>/dev/null)\"\necho \"npm global openclaw: $(ls -la \"$(npm root -g 2>/dev/null)/openclaw/package.json\" 2>/dev/null | awk '{print $3\":\"$4}')\"\n\nif [ -z \"$SAME_HOST_USERS\" ] && [ -z \"$WSL_INSTANCES\" ]; then\n  echo \"未发现其他 OpenClaw 用户 ✅\"\nelse\n  echo \"\"\n  echo \"⚠️ 发现其他 OpenClaw 用户/实例：$SAME_HOST_USERS $WSL_INSTANCES\"\n  echo \"⚠️ npm install -g openclaw 会影响所有用户共享的 npm global 包\"\n  echo \"⚠️ 升级前必须确认其他用户的 openclaw 和目标版本兼容（特别是插件）\"\n  echo \"⚠️ 如果已知有其他用户但检测未命中（如 raven 在独立的 WSL 实例），请在升级前手动确认对方状态\"\nfi\n```\n\n向爸比汇报环境探测结果，确认后继续。\n\n---\n\n## 第一步：确认目标版本\n\n```bash\nopenclaw --version\nnpm view openclaw version\n\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\nTARGET_VER=<目标版本，如 2026.5.12>\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('body','')[:3000])\"\n```\n\n**Node 版本兼容性核对（2026-07-27新增，与第零步 Node 检测配套）**：\n```bash\nnpm view openclaw@${TARGET_VER} engines.node 2>&1\n```\n把这个结果和第零步检测到的当前 Node 版本对比：\n- 若当前 Node 满足要求 → 正常继续\n- 若不满足 → **必须在第六步执行升级前先升级 Node**（同机器同大版本线内的 apt/nvm 升级即可，不要跨大版本线），否则升级完 openclaw 包后 gateway 会直接拒绝启动\n\n向爸比汇报：当前版本、目标版本、release highlights 摘要、**Node 版本是否满足要求**，等爸比确认目标版本（若 Node 不满足，一并确认是否同意先升级 Node）。\n\n---\n\n## 第二步：检查插件兼容性\n\n```bash\nopenclaw plugins list 2>/dev/null | grep \"enabled\"\n```\n\n针对**每个 enabled 插件**，在 release notes 里搜索对应关键词：\n\n```bash\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"\nimport json,sys\nd=json.load(sys.stdin)\nbody = d.get('body','')\nkeywords = ['feishu', 'lossless', 'minimax', 'anthropic', 'deepseek', 'openai', 'memory-core']\nfor kw in keywords:\n    lines = [l.strip() for l in body.split('\\n') if kw.lower() in l.lower() and l.strip()]\n    if lines:\n        print(f'=== {kw} ===')\n        for l in lines[:5]: print(' ', l)\n\"\n```\n\n重点关注：\n- **lossless-claw**：手动装的 global 插件，历史上踩过坑，必须关注\n- **@openclaw/feishu**：openclaw 自管 npm，升级可能改版本\n- 其余 stock 插件随主包升级，通常无需额外处理\n\n向爸比汇报兼容性评估，有⚠️风险说清楚。\n\n---\n\n## 第三步：记录插件快照\n\n```bash\nopenclaw plugins list 2>/dev/null > /tmp/plugins-before-${TARGET_VER}.txt\necho \"✅ 插件快照已保存 → /tmp/plugins-before-${TARGET_VER}.txt\"\n```\n\n---\n\n## 第四步：备份\n\n```bash\nCURRENT_VER=$(openclaw --version 2>/dev/null | grep -oP '[\\d.]+' | head -1)\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_DIR=\"$HOME/.openclaw/extensions/lossless-claw\"\n\ncp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-${CURRENT_VER}\necho \"1/5 openclaw.json ✅\"\n\nif [ -f \"$OVERRIDE\" ]; then\n  cp \"$OVERRIDE\" \"${OVERRIDE}.bak-${CURRENT_VER}\"\n  echo \"2/5 override.conf ✅\"\nelse\n  echo \"2/5 override.conf 不存在，跳过 ✅\"\nfi\n\ncp ~/.openclaw/.env ~/.openclaw/.env.bak-${CURRENT_VER}\necho \"3/5 .env ✅\"\n\nif [ -d \"$LOSSLESS_DIR\" ]; then\n  LOSSLESS_VER=$(cat \"$LOSSLESS_DIR/package.json\" | \\\n    python3 -c \"import json,sys;print(json.load(sys.stdin)['version'])\")\n  LOSSLESS_NM_SIZE=$(du -sm \"$LOSSLESS_DIR/node_modules/\" 2>/dev/null | cut -f1)\n  LOSSLESS_BAK=\"$HOME/.openclaw/extensions/lossless-claw.bak-${LOSSLESS_VER}\"\n  mkdir -p \"$LOSSLESS_BAK\"\n  if [ \"${LOSSLESS_NM_SIZE:-0}\" -gt 500 ]; then\n    cp \"$LOSSLESS_DIR/package.json\" \"$LOSSLESS_BAK/\"\n    cp \"$LOSSLESS_DIR/openclaw.plugin.json\" \"$LOSSLESS_BAK/\"\n    cp -r \"$LOSSLESS_DIR/dist\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (dist only, node_modules=${LOSSLESS_NM_SIZE}MB 过大跳过) ✅\"\n  else\n    cp -r \"$LOSSLESS_DIR/.\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (完整备份) ✅\"\n  fi\nelse\n  echo \"4/5 lossless-claw 不存在，跳过 ✅\"\nfi\n\nif [ -d \"$FEISHU_DIR\" ]; then\n  mkdir -p \"${FEISHU_DIR}.bak-${CURRENT_VER}\"\n  cp \"$FEISHU_DIR/package.json\" \"${FEISHU_DIR}.bak-${CURRENT_VER}/\"\n  echo \"5/5 feishu ✅\"\nelse\n  echo \"5/5 feishu 插件目录不存在，跳过 ✅\"\nfi\n\necho \"\"\necho \"=== 备份清单 ===\"\nls ~/.openclaw/openclaw.json.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ openclaw.json\"\nls ~/.openclaw/.env.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ .env\"\n[ -f \"${OVERRIDE}.bak-${CURRENT_VER}\" ] && echo \"✅ override.conf\" || echo \"⏭ override.conf (不存在)\"\nls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | tail -1 | xargs -I{} echo \"✅ {}\" || echo \"⏭ lossless-claw (不存在)\"\nls -d \"${FEISHU_DIR}.bak-${CURRENT_VER}\" 2>/dev/null && echo \"✅ feishu\" || echo \"⏭ feishu (不存在)\"\n```\n\n确认核心备份（openclaw.json + .env）存在后再继续。\n\n---\n\n## 第五步：设好重启后通知 cron（先于重启执行）\n\ngateway 重启会中断当前 session，重启后欢欢是全新上下文，不会记得升级完成这件事。\n**必须在重启前设好一次性 systemEvent cron，重启后自动触发通知爸比。**\n\n用 `cron` 工具创建：\n- `schedule`: `at`，时间 = 当前时间 + 3 分钟\n- `payload.kind`: `systemEvent`\n- `payload.text`: 升级完成通知（含版本号、插件状态、耗时）\n- `sessionTarget`: `main`\n- `deleteAfterRun`: `true`\n\n示例通知文本：\n```\n🎉 OpenClaw 升级完成！v<旧版本> → v<新版本>，插件全部正常（lossless-claw ✅ feishu ✅），耗时约X分钟。\n```\n\n> ⚠️ **3分钟是经过实践的安全值**，90秒有时会在 gateway 恢复前触发导致通知失败。\n\ncron 创建成功后，再执行下一步。\n\n---\n\n## 第六步：执行升级\n\n**等爸比说「执行」才动手。**\n\n> ⚠️ 如果第零步检测到其他 OpenClaw 用户，向爸比汇报后再执行。\n> ⚠️ 如果第一步核对发现当前 Node 版本不满足目标版本要求，**必须先升级 Node**，确认 `node --version` 达标后再继续本步骤。\n\n```bash\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\n  echo \"使用代理: 127.0.0.1:7890\"\nelse\n  echo \"直连安装\"\nfi\n\nif [ \"${IPV6_SLOWER:-0}\" = \"1\" ]; then\n  export NODE_OPTIONS=\"--dns-result-order=ipv4first\"\n  echo \"已强制 DNS 优先 IPv4（IPv6 检测偏慢）\"\nfi\n\nnpm install -g openclaw@${TARGET_VER}\n```\n\n---\n\n## 第七步：验证\n\n```bash\nopenclaw --version\nnode --version\n\nopenclaw doctor --fix 2>&1 | tail -5\nopenclaw doctor\n\nFAILED=$(openclaw plugins list 2>/dev/null | grep -i \"fail\\|error\" | grep -v \"grep\")\nif [ -n \"$FAILED\" ]; then\n  echo \"⚠️ 检测到插件加载失败：\"\n  echo \"$FAILED\"\n  if echo \"$FAILED\" | grep -qi \"feishu\"; then\n    echo \"🔧 feishu 插件失败，强制重装...\"\n    openclaw plugins install --force @openclaw/feishu 2>&1\n    echo \"⚠️ 重装后需要重启 gateway\"\n  fi\nelse\n  echo \"✅ 所有插件加载正常\"\nfi\n\ndiff /tmp/plugins-before-${TARGET_VER}.txt <(openclaw plugins list 2>/dev/null)\n```\n\n验收标准（全部通过才继续）：\n- ✅ 版本 = 目标版本\n- ✅ Node 版本满足目标版本 engines.node 要求\n- ✅ lossless-claw（若存在）仍在 enabled 列表\n- ✅ feishu（若存在）仍在 enabled 列表\n- ✅ doctor Errors = 0\n- ✅ 无插件加载失败\n\n有任何一项不通过 → 立即执行回滚，不继续。\n\n---\n\n## 第八步：重启 gateway\n\n**优先用平台 `gateway` 工具（action=restart）执行重启，而不是裸调 `systemctl restart`。**\n\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 升级完成，重启生效\"\n```\n\n若无 `gateway` 工具可用，才退回裸调：\n\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n**重启后如果新版本触发了插件依赖首次安装（如新版 codex 插件），日志会出现类似 `npm install` 子进程且短时间内端口不监听是正常现象**；观察其 node_modules 增长/CPU占用判断是否卡死，若卡在慢速 IPv6 上超过 3 分钟无进展，可参考第零步的 IPv4 强制方案排查，不要贸然 kill 掉该子进程。\n\n第五步设好的 cron 会在重启后 90 秒内自动触发，通知爸比升级完成。\n\n---\n\n## ⏪ 回滚方案\n\n任一步骤出问题立即执行：\n\n```bash\nPREV_VER=<回退版本，如 2026.5.6>\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_BAK=$(ls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | sort | tail -1)\n\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\nfi\nnpm install -g openclaw@${PREV_VER}\n\ncp ~/.openclaw/openclaw.json.bak-${PREV_VER} ~/.openclaw/openclaw.json\ncp ~/.openclaw/.env.bak-${PREV_VER} ~/.openclaw/.env\n\nif [ -f \"${OVERRIDE}.bak-${PREV_VER}\" ]; then\n  cp \"${OVERRIDE}.bak-${PREV_VER}\" \"$OVERRIDE\"\n  echo \"override.conf 已还原 ✅\"\nelse\n  echo \"override.conf 备份不存在，跳过 ✅\"\nfi\n\nif [ -n \"$LOSSLESS_BAK\" ] && [ -d \"$LOSSLESS_BAK\" ]; then\n  rm -rf \"$HOME/.openclaw/extensions/lossless-claw\"\n  cp -r \"$LOSSLESS_BAK\" \"$HOME/.openclaw/extensions/lossless-claw\"\n  echo \"lossless-claw 已还原 ✅\"\nelse\n  echo \"lossless-claw 备份不存在，跳过 ✅\"\nfi\n\nsystemctl --user daemon-reload\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 回滚完成，重启生效\"\n\n若无 gateway 工具可用，才退回：\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n等飞书收到「欢欢重启完毕，在线了 🐾」，告知爸比回滚完成及原因。\n\n---\n\n## 注意事项\n\n- **不要用 `gateway update.run` 升级**，npm 手动指定版本更可控\n- **重启一律优先走平台 `gateway` 工具（action=restart）**，不裸调 systemctl\n- **升级前必须核对目标版本的 Node 最低要求**（`npm view openclaw@<版本> engines.node`），不满足要先升级 Node 再装 openclaw\n- **npm install 卡顿优先排查 IPv4/IPv6 速度差异**（`curl -4`/`curl -6` 对比测速），若 IPv6 明显慢，用 `NODE_OPTIONS=\"--dns-result-order=ipv4first\"` 强制优先 IPv4\n- **skill description字段只写触发场景，不写变更记录**（2026-07-27元教训：description是agent discovery语义匹配依据，写成changelog会导致agent无法自然语言触发这个skill，历史更新记录见上方Changelog小节）\n- **feishu 插件路径**：`~/.openclaw/npm/node_modules/@openclaw/feishu`（openclaw 自管，非 npm global）\n- **lossless-claw 路径**：`~/.openclaw/extensions/lossless-claw`（openclaw 自管）\n- **systemd service 不读 .bashrc**，代理若需在 service 中生效，需配置 override.conf 或 EnvironmentFile\n- **lossless-claw 踩坑**：2026-04-14 升级 4.14 不兼容，回退 4.11 解决，每次升级必须检查\n- **MiniMax 不调用 message 工具**，涉及发消息的 cron 不要用 MiniMax\n- **brave 插件外部化（2026.5.12 起）**：升级后如果遇到 \"web_search provider is not available: brave\"，执行 `openclaw plugins install --force @openclaw/brave-plugin` 后重启\n- **feishu 插件不兼容**：升级后 feishu 注册失败时，执行 `openclaw plugins install --force @openclaw/feishu` 后重启\n- **codex EACCES 错误**：多用户同机时，`/tmp/jiti/` 目录需要 sticky bit（`sudo chmod 1777 /tmp/jiti`），否则不同用户的 codex 会互相冲突\n- **多用户兼容风险**：`npm install -g openclaw` 会覆盖全局包，影响同机所有 OpenClaw 用户\n- **升级完成通知 cron**：设置 3 分钟而非更短，防止 gateway 还未完全恢复时触发\n\n---\n\n## 开源版说明\n\n- 技能适配 OpenClaw 所有标准部署（WSL2/Linux VM/原生 Linux）\n- 如果使用代理，自动检测 127.0.0.1:7890，也可在执行前手动 `export HTTP_PROXY=http://your-proxy:port`\n- lossless-claw / override.conf 均为可选组件，不存在时自动跳过，不会报错中断\n- 服务管理默认 `systemd --user`，如使用其他方式（如 pm2、docker）请修改第八步的重启命令\n- 首次使用前建议先执行第零步（环境探测），确认环境配置正确\n\nFile v1.7.2:_meta.json\n\n{\n  \"ownerId\": \"kn79f0shgp6jenfxa0cfqgm25x82m4bq\",\n  \"slug\": \"oc-upgrade\",\n  \"version\": \"1.7.2\",\n  \"publishedAt\": 1785160086372\n}\n\nFile v1.7.2:skill-card.md\n\n## Description: <br>\nProvides a standard OpenClaw upgrade runbook that checks Node.js compatibility, network behavior, plugin state, backups, notification scheduling, validation, restart, and rollback. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[tangsuann](https://clawhub.ai/user/tangsuann) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and operators use this skill to guide OpenClaw version upgrades with environment checks, compatibility review, backups, post-upgrade validation, gateway restart guidance, and rollback steps. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill can guide broad OpenClaw upgrade actions, including global npm changes and gateway restart. <br>\nMitigation: Confirm the target version, review the exact commands before execution, and use the included validation and rollback steps. <br>\nRisk: The skill includes backup handling for ~/.openclaw/.env and other local configuration files. <br>\nMitigation: Restrict permissions on backups that may contain secrets and remove stale backups after the upgrade is verified. <br>\nRisk: The skill schedules a one-time completion notification and inspects the local OpenClaw environment. <br>\nMitigation: Install only where that local inspection and delayed notification behavior is expected and approved. <br>\n\n\n## Reference(s): <br>\n- [OpenClaw Upgrade on ClawHub](https://clawhub.ai/tangsuann/skills/oc-upgrade) <br>\n- [OpenClaw npm registry](https://registry.npmjs.org/) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [guidance, markdown, shell commands, configuration] <br>\n**Output Format:** [Markdown with inline bash code blocks] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Includes staged operator confirmations, backup and rollback commands, and restart guidance.] <br>\n\n## Skill Version(s): <br>\n1.7.2 (source: server evidence release.version) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.7.1: 3 files, 9914 bytes\n\nFiles: _meta.json (129b), skill-card.md (2667b), SKILL.md (20894b)\n\nFile v1.7.1:SKILL.md\n\n---\nname: \"openclaw-upgrade\"\ndescription: \"OpenClaw版本升级标准流程。每次说\\\"升级openclaw\\\"、\\\"openclaw升级\\\"、\\\"更新openclaw\\\"时必须执行，含Node版本+IPv4/IPv6探测\"\n---\n\n# OpenClaw 升级技能\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n\n## Changelog\n\n> description字段只写触发场景，不写变更记录；每次改动的原因/教训记在这里。\n\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n- 2026-07-27：NAS欢欢用自写脚本升级，脚本从gateway进程内部nohup启动，第一步systemctl stop把整个进程组一起杀掉，脚本自己被杀死，npm install根本没跑起来，gateway停了近6小时无人察觉——本skill的流程设计（npm install前不停服务、重启只在最后单独一步、重启前先设好通知cron）天然规避了这个坑，但重启这一步本身如果裸调systemctl也仍有被自身进程树波及的理论风险，已在第八步/回滚方案中改为优先走平台 gateway 工具\n- 2026-07-27（同一事故的第二个坑）：NAS欢欢在手动拉起gateway后，agent恢复中断会话继续把npm包升到2026.7.1-2，但机器Node还是22.22.1，openclaw 2026.7.1-2要求Node≥22.22.3，导致gateway直接拒绝启动；排查过程中还发现该NAS访问registry.npmjs.org走IPv6比IPv4慢6倍（4秒 vs 0.66秒），跨版本升级触发的codex插件依赖安装卡在慢速IPv6连接上4分半没有进展——本skill第零步此前完全没有检查Node版本、也没有IPv4/IPv6速度探测，是两个真实缺口，已补入第零步\n- 2026-07-27（第三个坑，元问题）：本skill（ClawHub slug: oc-upgrade）连续几次更新提案时，description字段被写成了\"这次改了什么\"的changelog摘要文风，覆盖掉了原本\"每次说升级openclaw时必须执行\"这类触发关键词描述。根据OpenClaw官方creating-skills文档：\"description is shown to the agent and in slash-command discovery\"——description是agent判断\"该不该调用这个skill\"的唯一语义匹配依据，不是变更记录位置。description被写成changelog后，agent在用户说\"升级openclaw\"时无法语义匹配上这个skill，导致同一台NAS上并存的旧版本`openclaw-upgrade`（本地非ClawHub版本，description里保留了触发关键词）被误当成\"唯一入口\"，而已经更新到最新内容的`oc-upgrade`因description不含触发语义而从未被自然语言调用触发。教训固化为规则：description字段只写\"什么场景触发\"，绝不写\"这次改了什么\"；changelog类内容一律写在本节。\n\n---\n\n## 第零步：环境探测\n\n在任何操作之前，先自动探测并汇报当前环境：\n\n```bash\n# === 环境探测 ===\necho \"=== OpenClaw 环境 ===\"\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\n\n# npm global 路径\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\n# Node.js 版本检测（2026-07-27新增：NAS欢欢升级openclaw到2026.7.1-2后，\n# 因Node版本(22.22.1)低于该版本要求的22.22.3，gateway直接拒绝启动，停机近1小时）\necho \"\"\necho \"=== Node.js 版本 ===\"\nNODE_VER=$(node --version 2>/dev/null | sed 's/^v//')\necho \"当前 Node: v${NODE_VER:-未知}\"\nif [ -z \"$NODE_VER\" ]; then\n  echo \"⚠️ 无法检测 Node 版本，node 命令不可用\"\nelse\n  NODE_MAJOR=$(echo \"$NODE_VER\" | cut -d. -f1)\n  if [ \"$NODE_MAJOR\" -lt 22 ]; then\n    echo \"⚠️ Node 主版本 ${NODE_MAJOR} 低于 22，多数近期 OpenClaw 版本会拒绝启动\"\n  else\n    echo \"Node 主版本 ${NODE_MAJOR} ✅（具体最低子版本要求见第一步「目标版本」核对）\"\n  fi\nfi\necho \"⚠️ 注意：仅确认当前 Node 版本不够，必须在第一步拿到目标版本的具体 Node 最低版本要求后，\n      两者对比才能判断是否需要先升级 Node。不要假设当前版本一定够用。\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"\n  echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"\n  echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# IPv4/IPv6 速度探测（2026-07-27新增：NAS欢欢升级触发的codex插件依赖安装\n# 卡在慢速IPv6连接上4分半没有进展，IPv6访问registry比IPv4慢6倍，是同一次事故的第二个真实缺口）\necho \"\"\necho \"=== registry IPv4/IPv6 速度探测 ===\"\nIPV4_TIME=$(timeout 5 curl -4 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\nIPV6_TIME=$(timeout 5 curl -6 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\necho \"IPv4: ${IPV4_TIME:-超时/不可用}s\"\necho \"IPv6: ${IPV6_TIME:-超时/不可用}s\"\nif [ -z \"$IPV6_TIME\" ]; then\n  echo \"IPv6 不可用或超时，npm install 默认可能仍会尝试 IPv6 优先，建议升级/安装步骤强制 --force-ipv4 兜底\"\nelif python3 -c \"exit(0 if float('$IPV6_TIME') > float('${IPV4_TIME:-999}') * 2 else 1)\" 2>/dev/null; then\n  echo \"⚠️ IPv6 明显慢于 IPv4（超2倍），npm install/npm update 建议强制 IPv4 避免卡顿：\"\n  echo \"   npm config set prefer-ipv4 true   # 或临时: npm install --force-ipv4（部分npm版本可能不支持此flag，改用 NODE_OPTIONS='--dns-result-order=ipv4first'）\"\n  echo \"   推荐：export NODE_OPTIONS=\\\"--dns-result-order=ipv4first\\\" 后再执行 npm install/update\"\nelse\n  echo \"IPv4/IPv6 速度接近，无需特殊处理 ✅\"\nfi\n\n# 可选组件检测\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nHAS_OVERRIDE=false\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\n[ -f \"$OVERRIDE\" ] && HAS_OVERRIDE=true\necho \"override.conf: $HAS_OVERRIDE\"\n\necho \"服务管理: systemd --user\"\n\n# 多用户 /tmp/jiti 权限检查（防止 codex EACCES 问题）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /tmp/jiti)\n  if [ \"$JITI_PERM\" != \"1777\" ]; then\n    echo \"⚠️ /tmp/jiti 权限为 $JITI_PERM，多用户环境可能导致 codex EACCES 错误\"\n    echo \"建议执行: sudo chmod 1777 /tmp/jiti\"\n  else\n    echo \"/tmp/jiti: 1777 ✅\"\n  fi\nelse\n  echo \"/tmp/jiti: 不存在 ✅\"\nfi\n\n# 扫描其他 OpenClaw 用户（同机不同用户共享 npm global 升级风险）\necho \"\"\necho \"=== 其他 OpenClaw 用户检测 ===\"\n\nSAME_HOST_USERS=\"\"\nfor U in $(ls /home/ 2>/dev/null); do\n  if [ \"$U\" != \"$(whoami)\" ] && [ -d \"/home/$U/.openclaw\" ]; then\n    echo \"用户(同主机): $U\"\n    SAME_HOST_USERS=\"$SAME_HOST_USERS $U\"\n  fi\ndone\n\nWSL_INSTANCES=\"\"\nif command -v powershell.exe &>/dev/null; then\n  WSL_LIST=$(powershell.exe -NoProfile -Command \"wsl --list --verbose\" 2>/dev/null | grep -i -v \"NAME\\|Windows\" || true)\n  if [ -n \"$WSL_LIST\" ]; then\n    echo \"$WSL_LIST\" | while read -r INSTANCE; do\n      INSTANCE=$(echo \"$INSTANCE\" | awk '{print $1}')\n      if [ -n \"$INSTANCE\" ] && [ \"$INSTANCE\" != \"$(hostname)\" ]; then\n        WSL_INSTANCES=\"$WSL_INSTANCES $INSTANCE\"\n        echo \"WSL实例: $INSTANCE\"\n        if [ -d \"/mnt/wsl/$INSTANCE/home/\" ]; then\n          for WU in /mnt/wsl/$INSTANCE/home/*/; do\n            WU=$(basename \"$WU\")\n            if [ -d \"/mnt/wsl/$INSTANCE/home/$WU/.openclaw\" ]; then\n              echo \"  → 用户 $WU 有 OpenClaw 安装\"\n              SAME_HOST_USERS=\"$SAME_HOST_USERS $WU@$INSTANCE\"\n            fi\n          done\n        fi\n      fi\n    done\n  else\n    echo \"WSL列表: 无输出（WSL interop 可能不可用，跳过）\"\n  fi\nelse\n  echo \"WSL列表: powershell.exe 不可用，跳过\"\nfi\n\necho \"npm global path: $(npm root -g 2>/dev/null)\"\necho \"npm global openclaw: $(ls -la \"$(npm root -g 2>/dev/null)/openclaw/package.json\" 2>/dev/null | awk '{print $3\":\"$4}')\"\n\nif [ -z \"$SAME_HOST_USERS\" ] && [ -z \"$WSL_INSTANCES\" ]; then\n  echo \"未发现其他 OpenClaw 用户 ✅\"\nelse\n  echo \"\"\n  echo \"⚠️ 发现其他 OpenClaw 用户/实例：$SAME_HOST_USERS $WSL_INSTANCES\"\n  echo \"⚠️ npm install -g openclaw 会影响所有用户共享的 npm global 包\"\n  echo \"⚠️ 升级前必须确认其他用户的 openclaw 和目标版本兼容（特别是插件）\"\n  echo \"⚠️ 如果已知有其他用户但检测未命中（如 raven 在独立的 WSL 实例），请在升级前手动确认对方状态\"\nfi\n```\n\n向爸比汇报环境探测结果，确认后继续。\n\n---\n\n## 第一步：确认目标版本\n\n```bash\nopenclaw --version\nnpm view openclaw version\n\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\nTARGET_VER=<目标版本，如 2026.5.12>\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('body','')[:3000])\"\n```\n\n**Node 版本兼容性核对（2026-07-27新增，与第零步 Node 检测配套）**：\n```bash\nnpm view openclaw@${TARGET_VER} engines.node 2>&1\n```\n把这个结果和第零步检测到的当前 Node 版本对比：\n- 若当前 Node 满足要求 → 正常继续\n- 若不满足 → **必须在第六步执行升级前先升级 Node**（同机器同大版本线内的 apt/nvm 升级即可，不要跨大版本线），否则升级完 openclaw 包后 gateway 会直接拒绝启动\n\n向爸比汇报：当前版本、目标版本、release highlights 摘要、**Node 版本是否满足要求**，等爸比确认目标版本（若 Node 不满足，一并确认是否同意先升级 Node）。\n\n---\n\n## 第二步：检查插件兼容性\n\n```bash\nopenclaw plugins list 2>/dev/null | grep \"enabled\"\n```\n\n针对**每个 enabled 插件**，在 release notes 里搜索对应关键词：\n\n```bash\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"\nimport json,sys\nd=json.load(sys.stdin)\nbody = d.get('body','')\nkeywords = ['feishu', 'lossless', 'minimax', 'anthropic', 'deepseek', 'openai', 'memory-core']\nfor kw in keywords:\n    lines = [l.strip() for l in body.split('\\n') if kw.lower() in l.lower() and l.strip()]\n    if lines:\n        print(f'=== {kw} ===')\n        for l in lines[:5]: print(' ', l)\n\"\n```\n\n重点关注：\n- **lossless-claw**：手动装的 global 插件，历史上踩过坑，必须关注\n- **@openclaw/feishu**：openclaw 自管 npm，升级可能改版本\n- 其余 stock 插件随主包升级，通常无需额外处理\n\n向爸比汇报兼容性评估，有⚠️风险说清楚。\n\n---\n\n## 第三步：记录插件快照\n\n```bash\nopenclaw plugins list 2>/dev/null > /tmp/plugins-before-${TARGET_VER}.txt\necho \"✅ 插件快照已保存 → /tmp/plugins-before-${TARGET_VER}.txt\"\n```\n\n---\n\n## 第四步：备份\n\n```bash\nCURRENT_VER=$(openclaw --version 2>/dev/null | grep -oP '[\\d.]+' | head -1)\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_DIR=\"$HOME/.openclaw/extensions/lossless-claw\"\n\ncp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-${CURRENT_VER}\necho \"1/5 openclaw.json ✅\"\n\nif [ -f \"$OVERRIDE\" ]; then\n  cp \"$OVERRIDE\" \"${OVERRIDE}.bak-${CURRENT_VER}\"\n  echo \"2/5 override.conf ✅\"\nelse\n  echo \"2/5 override.conf 不存在，跳过 ✅\"\nfi\n\ncp ~/.openclaw/.env ~/.openclaw/.env.bak-${CURRENT_VER}\necho \"3/5 .env ✅\"\n\nif [ -d \"$LOSSLESS_DIR\" ]; then\n  LOSSLESS_VER=$(cat \"$LOSSLESS_DIR/package.json\" | \\\n    python3 -c \"import json,sys;print(json.load(sys.stdin)['version'])\")\n  LOSSLESS_NM_SIZE=$(du -sm \"$LOSSLESS_DIR/node_modules/\" 2>/dev/null | cut -f1)\n  LOSSLESS_BAK=\"$HOME/.openclaw/extensions/lossless-claw.bak-${LOSSLESS_VER}\"\n  mkdir -p \"$LOSSLESS_BAK\"\n  if [ \"${LOSSLESS_NM_SIZE:-0}\" -gt 500 ]; then\n    cp \"$LOSSLESS_DIR/package.json\" \"$LOSSLESS_BAK/\"\n    cp \"$LOSSLESS_DIR/openclaw.plugin.json\" \"$LOSSLESS_BAK/\"\n    cp -r \"$LOSSLESS_DIR/dist\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (dist only, node_modules=${LOSSLESS_NM_SIZE}MB 过大跳过) ✅\"\n  else\n    cp -r \"$LOSSLESS_DIR/.\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (完整备份) ✅\"\n  fi\nelse\n  echo \"4/5 lossless-claw 不存在，跳过 ✅\"\nfi\n\nif [ -d \"$FEISHU_DIR\" ]; then\n  mkdir -p \"${FEISHU_DIR}.bak-${CURRENT_VER}\"\n  cp \"$FEISHU_DIR/package.json\" \"${FEISHU_DIR}.bak-${CURRENT_VER}/\"\n  echo \"5/5 feishu ✅\"\nelse\n  echo \"5/5 feishu 插件目录不存在，跳过 ✅\"\nfi\n\necho \"\"\necho \"=== 备份清单 ===\"\nls ~/.openclaw/openclaw.json.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ openclaw.json\"\nls ~/.openclaw/.env.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ .env\"\n[ -f \"${OVERRIDE}.bak-${CURRENT_VER}\" ] && echo \"✅ override.conf\" || echo \"⏭ override.conf (不存在)\"\nls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | tail -1 | xargs -I{} echo \"✅ {}\" || echo \"⏭ lossless-claw (不存在)\"\nls -d \"${FEISHU_DIR}.bak-${CURRENT_VER}\" 2>/dev/null && echo \"✅ feishu\" || echo \"⏭ feishu (不存在)\"\n```\n\n确认核心备份（openclaw.json + .env）存在后再继续。\n\n---\n\n## 第五步：设好重启后通知 cron（先于重启执行）\n\ngateway 重启会中断当前 session，重启后欢欢是全新上下文，不会记得升级完成这件事。\n**必须在重启前设好一次性 systemEvent cron，重启后自动触发通知爸比。**\n\n用 `cron` 工具创建：\n- `schedule`: `at`，时间 = 当前时间 + 3 分钟\n- `payload.kind`: `systemEvent`\n- `payload.text`: 升级完成通知（含版本号、插件状态、耗时）\n- `sessionTarget`: `main`\n- `deleteAfterRun`: `true`\n\n示例通知文本：\n```\n🎉 OpenClaw 升级完成！v<旧版本> → v<新版本>，插件全部正常（lossless-claw ✅ feishu ✅），耗时约X分钟。\n```\n\n> ⚠️ **3分钟是经过实践的安全值**，90秒有时会在 gateway 恢复前触发导致通知失败。\n\ncron 创建成功后，再执行下一步。\n\n---\n\n## 第六步：执行升级\n\n**等爸比说「执行」才动手。**\n\n> ⚠️ 如果第零步检测到其他 OpenClaw 用户，向爸比汇报后再执行。\n> ⚠️ 如果第一步核对发现当前 Node 版本不满足目标版本要求，**必须先升级 Node**，确认 `node --version` 达标后再继续本步骤。\n\n```bash\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\n  echo \"使用代理: 127.0.0.1:7890\"\nelse\n  echo \"直连安装\"\nfi\n\nif [ \"${IPV6_SLOWER:-0}\" = \"1\" ]; then\n  export NODE_OPTIONS=\"--dns-result-order=ipv4first\"\n  echo \"已强制 DNS 优先 IPv4（IPv6 检测偏慢）\"\nfi\n\nnpm install -g openclaw@${TARGET_VER}\n```\n\n---\n\n## 第七步：验证\n\n```bash\nopenclaw --version\nnode --version\n\nopenclaw doctor --fix 2>&1 | tail -5\nopenclaw doctor\n\nFAILED=$(openclaw plugins list 2>/dev/null | grep -i \"fail\\|error\" | grep -v \"grep\")\nif [ -n \"$FAILED\" ]; then\n  echo \"⚠️ 检测到插件加载失败：\"\n  echo \"$FAILED\"\n  if echo \"$FAILED\" | grep -qi \"feishu\"; then\n    echo \"🔧 feishu 插件失败，强制重装...\"\n    openclaw plugins install --force @openclaw/feishu 2>&1\n    echo \"⚠️ 重装后需要重启 gateway\"\n  fi\nelse\n  echo \"✅ 所有插件加载正常\"\nfi\n\ndiff /tmp/plugins-before-${TARGET_VER}.txt <(openclaw plugins list 2>/dev/null)\n```\n\n验收标准（全部通过才继续）：\n- ✅ 版本 = 目标版本\n- ✅ Node 版本满足目标版本 engines.node 要求\n- ✅ lossless-claw（若存在）仍在 enabled 列表\n- ✅ feishu（若存在）仍在 enabled 列表\n- ✅ doctor Errors = 0\n- ✅ 无插件加载失败\n\n有任何一项不通过 → 立即执行回滚，不继续。\n\n---\n\n## 第八步：重启 gateway\n\n**优先用平台 `gateway` 工具（action=restart）执行重启，而不是裸调 `systemctl restart`。**\n\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 升级完成，重启生效\"\n```\n\n若无 `gateway` 工具可用，才退回裸调：\n\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n**重启后如果新版本触发了插件依赖首次安装（如新版 codex 插件），日志会出现类似 `npm install` 子进程且短时间内端口不监听是正常现象**；观察其 node_modules 增长/CPU占用判断是否卡死，若卡在慢速 IPv6 上超过 3 分钟无进展，可参考第零步的 IPv4 强制方案排查，不要贸然 kill 掉该子进程。\n\n第五步设好的 cron 会在重启后 90 秒内自动触发，通知爸比升级完成。\n\n---\n\n## ⏪ 回滚方案\n\n任一步骤出问题立即执行：\n\n```bash\nPREV_VER=<回退版本，如 2026.5.6>\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_BAK=$(ls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | sort | tail -1)\n\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\nfi\nnpm install -g openclaw@${PREV_VER}\n\ncp ~/.openclaw/openclaw.json.bak-${PREV_VER} ~/.openclaw/openclaw.json\ncp ~/.openclaw/.env.bak-${PREV_VER} ~/.openclaw/.env\n\nif [ -f \"${OVERRIDE}.bak-${PREV_VER}\" ]; then\n  cp \"${OVERRIDE}.bak-${PREV_VER}\" \"$OVERRIDE\"\n  echo \"override.conf 已还原 ✅\"\nelse\n  echo \"override.conf 备份不存在，跳过 ✅\"\nfi\n\nif [ -n \"$LOSSLESS_BAK\" ] && [ -d \"$LOSSLESS_BAK\" ]; then\n  rm -rf \"$HOME/.openclaw/extensions/lossless-claw\"\n  cp -r \"$LOSSLESS_BAK\" \"$HOME/.openclaw/extensions/lossless-claw\"\n  echo \"lossless-claw 已还原 ✅\"\nelse\n  echo \"lossless-claw 备份不存在，跳过 ✅\"\nfi\n\nsystemctl --user daemon-reload\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 回滚完成，重启生效\"\n\n若无 gateway 工具可用，才退回：\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n等飞书收到「欢欢重启完毕，在线了 🐾」，告知爸比回滚完成及原因。\n\n---\n\n## 注意事项\n\n- **不要用 `gateway update.run` 升级**，npm 手动指定版本更可控\n- **重启一律优先走平台 `gateway` 工具（action=restart）**，不裸调 systemctl\n- **升级前必须核对目标版本的 Node 最低要求**（`npm view openclaw@<版本> engines.node`），不满足要先升级 Node 再装 openclaw\n- **npm install 卡顿优先排查 IPv4/IPv6 速度差异**（`curl -4`/`curl -6` 对比测速），若 IPv6 明显慢，用 `NODE_OPTIONS=\"--dns-result-order=ipv4first\"` 强制优先 IPv4\n- **skill description字段只写触发场景，不写变更记录**（2026-07-27元教训：description是agent discovery语义匹配依据，写成changelog会导致agent无法自然语言触发这个skill，历史更新记录见上方Changelog小节）\n- **feishu 插件路径**：`~/.openclaw/npm/node_modules/@openclaw/feishu`（openclaw 自管，非 npm global）\n- **lossless-claw 路径**：`~/.openclaw/extensions/lossless-claw`（openclaw 自管）\n- **systemd service 不读 .bashrc**，代理若需在 service 中生效，需配置 override.conf 或 EnvironmentFile\n- **lossless-claw 踩坑**：2026-04-14 升级 4.14 不兼容，回退 4.11 解决，每次升级必须检查\n- **MiniMax 不调用 message 工具**，涉及发消息的 cron 不要用 MiniMax\n- **brave 插件外部化（2026.5.12 起）**：升级后如果遇到 \"web_search provider is not available: brave\"，执行 `openclaw plugins install --force @openclaw/brave-plugin` 后重启\n- **feishu 插件不兼容**：升级后 feishu 注册失败时，执行 `openclaw plugins install --force @openclaw/feishu` 后重启\n- **codex EACCES 错误**：多用户同机时，`/tmp/jiti/` 目录需要 sticky bit（`sudo chmod 1777 /tmp/jiti`），否则不同用户的 codex 会互相冲突\n- **多用户兼容风险**：`npm install -g openclaw` 会覆盖全局包，影响同机所有 OpenClaw 用户\n- **升级完成通知 cron**：设置 3 分钟而非更短，防止 gateway 还未完全恢复时触发\n\n---\n\n## 开源版说明\n\n- 技能适配 OpenClaw 所有标准部署（WSL2/Linux VM/原生 Linux）\n- 如果使用代理，自动检测 127.0.0.1:7890，也可在执行前手动 `export HTTP_PROXY=http://your-proxy:port`\n- lossless-claw / override.conf 均为可选组件，不存在时自动跳过，不会报错中断\n- 服务管理默认 `systemd --user`，如使用其他方式（如 pm2、docker）请修改第八步的重启命令\n- 首次使用前建议先执行第零步（环境探测），确认环境配置正确\n\nFile v1.7.1:_meta.json\n\n{\n  \"ownerId\": \"kn79f0shgp6jenfxa0cfqgm25x82m4bq\",\n  \"slug\": \"oc-upgrade\",\n  \"version\": \"1.7.1\",\n  \"publishedAt\": 1785160014846\n}\n\nFile v1.7.1:skill-card.md\n\n## Description: <br>\nProvides a standard OpenClaw upgrade workflow for agents, including environment checks, Node.js compatibility review, IPv4/IPv6 network probing, backups, upgrade validation, gateway restart guidance, and rollback steps. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[tangsuann](https://clawhub.ai/user/tangsuann) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and operators use this skill to guide an agent through a controlled OpenClaw version upgrade. It emphasizes preflight environment checks, plugin compatibility review, backups, validation, restart handling, and rollback readiness. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill guides an agent through actions that can affect global npm state and restart the OpenClaw gateway. <br>\nMitigation: Review the planned target version, plugin compatibility, backup state, validation results, and restart method before executing upgrade steps. <br>\nRisk: The workflow may inspect other local users for OpenClaw installs and copy secret-bearing .env files into backups. <br>\nMitigation: Run in an approved single-user or administrator-reviewed environment, restrict backup access, and verify secret handling before installation. <br>\nRisk: The skill includes administrator-impacting guidance such as chmod changes under /tmp. <br>\nMitigation: Treat privilege-related remediation as an administrator decision and apply it only when the reported condition is confirmed. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/tangsuann/skills/oc-upgrade) <br>\n- [OpenClaw package registry](https://registry.npmjs.org/) <br>\n- [OpenClaw GitHub release API pattern](https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration instructions, Guidance] <br>\n**Output Format:** [Markdown with inline bash code blocks and checklist-style operational guidance] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [May include commands that affect global npm state, gateway service state, local backups, and optional plugin remediation.] <br>\n\n## Skill Version(s): <br>\n1.7.1 (source: evidence.json release.version and target metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.8.0: 3 files, 10117 bytes\n\nFiles: _meta.json (129b), skill-card.md (3248b), SKILL.md (20894b)\n\nFile v1.8.0:SKILL.md\n\n---\nname: \"openclaw-upgrade\"\ndescription: \"OpenClaw版本升级标准流程。每次说\\\"升级openclaw\\\"、\\\"openclaw升级\\\"、\\\"更新openclaw\\\"时必须执行，含Node版本+IPv4/IPv6探测\"\n---\n\n# OpenClaw 升级技能\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n\n## Changelog\n\n> description字段只写触发场景，不写变更记录；每次改动的原因/教训记在这里。\n\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n- 2026-07-27：NAS欢欢用自写脚本升级，脚本从gateway进程内部nohup启动，第一步systemctl stop把整个进程组一起杀掉，脚本自己被杀死，npm install根本没跑起来，gateway停了近6小时无人察觉——本skill的流程设计（npm install前不停服务、重启只在最后单独一步、重启前先设好通知cron）天然规避了这个坑，但重启这一步本身如果裸调systemctl也仍有被自身进程树波及的理论风险，已在第八步/回滚方案中改为优先走平台 gateway 工具\n- 2026-07-27（同一事故的第二个坑）：NAS欢欢在手动拉起gateway后，agent恢复中断会话继续把npm包升到2026.7.1-2，但机器Node还是22.22.1，openclaw 2026.7.1-2要求Node≥22.22.3，导致gateway直接拒绝启动；排查过程中还发现该NAS访问registry.npmjs.org走IPv6比IPv4慢6倍（4秒 vs 0.66秒），跨版本升级触发的codex插件依赖安装卡在慢速IPv6连接上4分半没有进展——本skill第零步此前完全没有检查Node版本、也没有IPv4/IPv6速度探测，是两个真实缺口，已补入第零步\n- 2026-07-27（第三个坑，元问题）：本skill（ClawHub slug: oc-upgrade）连续几次更新提案时，description字段被写成了\"这次改了什么\"的changelog摘要文风，覆盖掉了原本\"每次说升级openclaw时必须执行\"这类触发关键词描述。根据OpenClaw官方creating-skills文档：\"description is shown to the agent and in slash-command discovery\"——description是agent判断\"该不该调用这个skill\"的唯一语义匹配依据，不是变更记录位置。description被写成changelog后，agent在用户说\"升级openclaw\"时无法语义匹配上这个skill，导致同一台NAS上并存的旧版本`openclaw-upgrade`（本地非ClawHub版本，description里保留了触发关键词）被误当成\"唯一入口\"，而已经更新到最新内容的`oc-upgrade`因description不含触发语义而从未被自然语言调用触发。教训固化为规则：description字段只写\"什么场景触发\"，绝不写\"这次改了什么\"；changelog类内容一律写在本节。\n\n---\n\n## 第零步：环境探测\n\n在任何操作之前，先自动探测并汇报当前环境：\n\n```bash\n# === 环境探测 ===\necho \"=== OpenClaw 环境 ===\"\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\n\n# npm global 路径\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\n# Node.js 版本检测（2026-07-27新增：NAS欢欢升级openclaw到2026.7.1-2后，\n# 因Node版本(22.22.1)低于该版本要求的22.22.3，gateway直接拒绝启动，停机近1小时）\necho \"\"\necho \"=== Node.js 版本 ===\"\nNODE_VER=$(node --version 2>/dev/null | sed 's/^v//')\necho \"当前 Node: v${NODE_VER:-未知}\"\nif [ -z \"$NODE_VER\" ]; then\n  echo \"⚠️ 无法检测 Node 版本，node 命令不可用\"\nelse\n  NODE_MAJOR=$(echo \"$NODE_VER\" | cut -d. -f1)\n  if [ \"$NODE_MAJOR\" -lt 22 ]; then\n    echo \"⚠️ Node 主版本 ${NODE_MAJOR} 低于 22，多数近期 OpenClaw 版本会拒绝启动\"\n  else\n    echo \"Node 主版本 ${NODE_MAJOR} ✅（具体最低子版本要求见第一步「目标版本」核对）\"\n  fi\nfi\necho \"⚠️ 注意：仅确认当前 Node 版本不够，必须在第一步拿到目标版本的具体 Node 最低版本要求后，\n      两者对比才能判断是否需要先升级 Node。不要假设当前版本一定够用。\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"\n  echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"\n  echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# IPv4/IPv6 速度探测（2026-07-27新增：NAS欢欢升级触发的codex插件依赖安装\n# 卡在慢速IPv6连接上4分半没有进展，IPv6访问registry比IPv4慢6倍，是同一次事故的第二个真实缺口）\necho \"\"\necho \"=== registry IPv4/IPv6 速度探测 ===\"\nIPV4_TIME=$(timeout 5 curl -4 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\nIPV6_TIME=$(timeout 5 curl -6 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\necho \"IPv4: ${IPV4_TIME:-超时/不可用}s\"\necho \"IPv6: ${IPV6_TIME:-超时/不可用}s\"\nif [ -z \"$IPV6_TIME\" ]; then\n  echo \"IPv6 不可用或超时，npm install 默认可能仍会尝试 IPv6 优先，建议升级/安装步骤强制 --force-ipv4 兜底\"\nelif python3 -c \"exit(0 if float('$IPV6_TIME') > float('${IPV4_TIME:-999}') * 2 else 1)\" 2>/dev/null; then\n  echo \"⚠️ IPv6 明显慢于 IPv4（超2倍），npm install/npm update 建议强制 IPv4 避免卡顿：\"\n  echo \"   npm config set prefer-ipv4 true   # 或临时: npm install --force-ipv4（部分npm版本可能不支持此flag，改用 NODE_OPTIONS='--dns-result-order=ipv4first'）\"\n  echo \"   推荐：export NODE_OPTIONS=\\\"--dns-result-order=ipv4first\\\" 后再执行 npm install/update\"\nelse\n  echo \"IPv4/IPv6 速度接近，无需特殊处理 ✅\"\nfi\n\n# 可选组件检测\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nHAS_OVERRIDE=false\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\n[ -f \"$OVERRIDE\" ] && HAS_OVERRIDE=true\necho \"override.conf: $HAS_OVERRIDE\"\n\necho \"服务管理: systemd --user\"\n\n# 多用户 /tmp/jiti 权限检查（防止 codex EACCES 问题）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /tmp/jiti)\n  if [ \"$JITI_PERM\" != \"1777\" ]; then\n    echo \"⚠️ /tmp/jiti 权限为 $JITI_PERM，多用户环境可能导致 codex EACCES 错误\"\n    echo \"建议执行: sudo chmod 1777 /tmp/jiti\"\n  else\n    echo \"/tmp/jiti: 1777 ✅\"\n  fi\nelse\n  echo \"/tmp/jiti: 不存在 ✅\"\nfi\n\n# 扫描其他 OpenClaw 用户（同机不同用户共享 npm global 升级风险）\necho \"\"\necho \"=== 其他 OpenClaw 用户检测 ===\"\n\nSAME_HOST_USERS=\"\"\nfor U in $(ls /home/ 2>/dev/null); do\n  if [ \"$U\" != \"$(whoami)\" ] && [ -d \"/home/$U/.openclaw\" ]; then\n    echo \"用户(同主机): $U\"\n    SAME_HOST_USERS=\"$SAME_HOST_USERS $U\"\n  fi\ndone\n\nWSL_INSTANCES=\"\"\nif command -v powershell.exe &>/dev/null; then\n  WSL_LIST=$(powershell.exe -NoProfile -Command \"wsl --list --verbose\" 2>/dev/null | grep -i -v \"NAME\\|Windows\" || true)\n  if [ -n \"$WSL_LIST\" ]; then\n    echo \"$WSL_LIST\" | while read -r INSTANCE; do\n      INSTANCE=$(echo \"$INSTANCE\" | awk '{print $1}')\n      if [ -n \"$INSTANCE\" ] && [ \"$INSTANCE\" != \"$(hostname)\" ]; then\n        WSL_INSTANCES=\"$WSL_INSTANCES $INSTANCE\"\n        echo \"WSL实例: $INSTANCE\"\n        if [ -d \"/mnt/wsl/$INSTANCE/home/\" ]; then\n          for WU in /mnt/wsl/$INSTANCE/home/*/; do\n            WU=$(basename \"$WU\")\n            if [ -d \"/mnt/wsl/$INSTANCE/home/$WU/.openclaw\" ]; then\n              echo \"  → 用户 $WU 有 OpenClaw 安装\"\n              SAME_HOST_USERS=\"$SAME_HOST_USERS $WU@$INSTANCE\"\n            fi\n          done\n        fi\n      fi\n    done\n  else\n    echo \"WSL列表: 无输出（WSL interop 可能不可用，跳过）\"\n  fi\nelse\n  echo \"WSL列表: powershell.exe 不可用，跳过\"\nfi\n\necho \"npm global path: $(npm root -g 2>/dev/null)\"\necho \"npm global openclaw: $(ls -la \"$(npm root -g 2>/dev/null)/openclaw/package.json\" 2>/dev/null | awk '{print $3\":\"$4}')\"\n\nif [ -z \"$SAME_HOST_USERS\" ] && [ -z \"$WSL_INSTANCES\" ]; then\n  echo \"未发现其他 OpenClaw 用户 ✅\"\nelse\n  echo \"\"\n  echo \"⚠️ 发现其他 OpenClaw 用户/实例：$SAME_HOST_USERS $WSL_INSTANCES\"\n  echo \"⚠️ npm install -g openclaw 会影响所有用户共享的 npm global 包\"\n  echo \"⚠️ 升级前必须确认其他用户的 openclaw 和目标版本兼容（特别是插件）\"\n  echo \"⚠️ 如果已知有其他用户但检测未命中（如 raven 在独立的 WSL 实例），请在升级前手动确认对方状态\"\nfi\n```\n\n向爸比汇报环境探测结果，确认后继续。\n\n---\n\n## 第一步：确认目标版本\n\n```bash\nopenclaw --version\nnpm view openclaw version\n\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\nTARGET_VER=<目标版本，如 2026.5.12>\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('body','')[:3000])\"\n```\n\n**Node 版本兼容性核对（2026-07-27新增，与第零步 Node 检测配套）**：\n```bash\nnpm view openclaw@${TARGET_VER} engines.node 2>&1\n```\n把这个结果和第零步检测到的当前 Node 版本对比：\n- 若当前 Node 满足要求 → 正常继续\n- 若不满足 → **必须在第六步执行升级前先升级 Node**（同机器同大版本线内的 apt/nvm 升级即可，不要跨大版本线），否则升级完 openclaw 包后 gateway 会直接拒绝启动\n\n向爸比汇报：当前版本、目标版本、release highlights 摘要、**Node 版本是否满足要求**，等爸比确认目标版本（若 Node 不满足，一并确认是否同意先升级 Node）。\n\n---\n\n## 第二步：检查插件兼容性\n\n```bash\nopenclaw plugins list 2>/dev/null | grep \"enabled\"\n```\n\n针对**每个 enabled 插件**，在 release notes 里搜索对应关键词：\n\n```bash\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"\nimport json,sys\nd=json.load(sys.stdin)\nbody = d.get('body','')\nkeywords = ['feishu', 'lossless', 'minimax', 'anthropic', 'deepseek', 'openai', 'memory-core']\nfor kw in keywords:\n    lines = [l.strip() for l in body.split('\\n') if kw.lower() in l.lower() and l.strip()]\n    if lines:\n        print(f'=== {kw} ===')\n        for l in lines[:5]: print(' ', l)\n\"\n```\n\n重点关注：\n- **lossless-claw**：手动装的 global 插件，历史上踩过坑，必须关注\n- **@openclaw/feishu**：openclaw 自管 npm，升级可能改版本\n- 其余 stock 插件随主包升级，通常无需额外处理\n\n向爸比汇报兼容性评估，有⚠️风险说清楚。\n\n---\n\n## 第三步：记录插件快照\n\n```bash\nopenclaw plugins list 2>/dev/null > /tmp/plugins-before-${TARGET_VER}.txt\necho \"✅ 插件快照已保存 → /tmp/plugins-before-${TARGET_VER}.txt\"\n```\n\n---\n\n## 第四步：备份\n\n```bash\nCURRENT_VER=$(openclaw --version 2>/dev/null | grep -oP '[\\d.]+' | head -1)\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_DIR=\"$HOME/.openclaw/extensions/lossless-claw\"\n\ncp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-${CURRENT_VER}\necho \"1/5 openclaw.json ✅\"\n\nif [ -f \"$OVERRIDE\" ]; then\n  cp \"$OVERRIDE\" \"${OVERRIDE}.bak-${CURRENT_VER}\"\n  echo \"2/5 override.conf ✅\"\nelse\n  echo \"2/5 override.conf 不存在，跳过 ✅\"\nfi\n\ncp ~/.openclaw/.env ~/.openclaw/.env.bak-${CURRENT_VER}\necho \"3/5 .env ✅\"\n\nif [ -d \"$LOSSLESS_DIR\" ]; then\n  LOSSLESS_VER=$(cat \"$LOSSLESS_DIR/package.json\" | \\\n    python3 -c \"import json,sys;print(json.load(sys.stdin)['version'])\")\n  LOSSLESS_NM_SIZE=$(du -sm \"$LOSSLESS_DIR/node_modules/\" 2>/dev/null | cut -f1)\n  LOSSLESS_BAK=\"$HOME/.openclaw/extensions/lossless-claw.bak-${LOSSLESS_VER}\"\n  mkdir -p \"$LOSSLESS_BAK\"\n  if [ \"${LOSSLESS_NM_SIZE:-0}\" -gt 500 ]; then\n    cp \"$LOSSLESS_DIR/package.json\" \"$LOSSLESS_BAK/\"\n    cp \"$LOSSLESS_DIR/openclaw.plugin.json\" \"$LOSSLESS_BAK/\"\n    cp -r \"$LOSSLESS_DIR/dist\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (dist only, node_modules=${LOSSLESS_NM_SIZE}MB 过大跳过) ✅\"\n  else\n    cp -r \"$LOSSLESS_DIR/.\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (完整备份) ✅\"\n  fi\nelse\n  echo \"4/5 lossless-claw 不存在，跳过 ✅\"\nfi\n\nif [ -d \"$FEISHU_DIR\" ]; then\n  mkdir -p \"${FEISHU_DIR}.bak-${CURRENT_VER}\"\n  cp \"$FEISHU_DIR/package.json\" \"${FEISHU_DIR}.bak-${CURRENT_VER}/\"\n  echo \"5/5 feishu ✅\"\nelse\n  echo \"5/5 feishu 插件目录不存在，跳过 ✅\"\nfi\n\necho \"\"\necho \"=== 备份清单 ===\"\nls ~/.openclaw/openclaw.json.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ openclaw.json\"\nls ~/.openclaw/.env.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ .env\"\n[ -f \"${OVERRIDE}.bak-${CURRENT_VER}\" ] && echo \"✅ override.conf\" || echo \"⏭ override.conf (不存在)\"\nls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | tail -1 | xargs -I{} echo \"✅ {}\" || echo \"⏭ lossless-claw (不存在)\"\nls -d \"${FEISHU_DIR}.bak-${CURRENT_VER}\" 2>/dev/null && echo \"✅ feishu\" || echo \"⏭ feishu (不存在)\"\n```\n\n确认核心备份（openclaw.json + .env）存在后再继续。\n\n---\n\n## 第五步：设好重启后通知 cron（先于重启执行）\n\ngateway 重启会中断当前 session，重启后欢欢是全新上下文，不会记得升级完成这件事。\n**必须在重启前设好一次性 systemEvent cron，重启后自动触发通知爸比。**\n\n用 `cron` 工具创建：\n- `schedule`: `at`，时间 = 当前时间 + 3 分钟\n- `payload.kind`: `systemEvent`\n- `payload.text`: 升级完成通知（含版本号、插件状态、耗时）\n- `sessionTarget`: `main`\n- `deleteAfterRun`: `true`\n\n示例通知文本：\n```\n🎉 OpenClaw 升级完成！v<旧版本> → v<新版本>，插件全部正常（lossless-claw ✅ feishu ✅），耗时约X分钟。\n```\n\n> ⚠️ **3分钟是经过实践的安全值**，90秒有时会在 gateway 恢复前触发导致通知失败。\n\ncron 创建成功后，再执行下一步。\n\n---\n\n## 第六步：执行升级\n\n**等爸比说「执行」才动手。**\n\n> ⚠️ 如果第零步检测到其他 OpenClaw 用户，向爸比汇报后再执行。\n> ⚠️ 如果第一步核对发现当前 Node 版本不满足目标版本要求，**必须先升级 Node**，确认 `node --version` 达标后再继续本步骤。\n\n```bash\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\n  echo \"使用代理: 127.0.0.1:7890\"\nelse\n  echo \"直连安装\"\nfi\n\nif [ \"${IPV6_SLOWER:-0}\" = \"1\" ]; then\n  export NODE_OPTIONS=\"--dns-result-order=ipv4first\"\n  echo \"已强制 DNS 优先 IPv4（IPv6 检测偏慢）\"\nfi\n\nnpm install -g openclaw@${TARGET_VER}\n```\n\n---\n\n## 第七步：验证\n\n```bash\nopenclaw --version\nnode --version\n\nopenclaw doctor --fix 2>&1 | tail -5\nopenclaw doctor\n\nFAILED=$(openclaw plugins list 2>/dev/null | grep -i \"fail\\|error\" | grep -v \"grep\")\nif [ -n \"$FAILED\" ]; then\n  echo \"⚠️ 检测到插件加载失败：\"\n  echo \"$FAILED\"\n  if echo \"$FAILED\" | grep -qi \"feishu\"; then\n    echo \"🔧 feishu 插件失败，强制重装...\"\n    openclaw plugins install --force @openclaw/feishu 2>&1\n    echo \"⚠️ 重装后需要重启 gateway\"\n  fi\nelse\n  echo \"✅ 所有插件加载正常\"\nfi\n\ndiff /tmp/plugins-before-${TARGET_VER}.txt <(openclaw plugins list 2>/dev/null)\n```\n\n验收标准（全部通过才继续）：\n- ✅ 版本 = 目标版本\n- ✅ Node 版本满足目标版本 engines.node 要求\n- ✅ lossless-claw（若存在）仍在 enabled 列表\n- ✅ feishu（若存在）仍在 enabled 列表\n- ✅ doctor Errors = 0\n- ✅ 无插件加载失败\n\n有任何一项不通过 → 立即执行回滚，不继续。\n\n---\n\n## 第八步：重启 gateway\n\n**优先用平台 `gateway` 工具（action=restart）执行重启，而不是裸调 `systemctl restart`。**\n\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 升级完成，重启生效\"\n```\n\n若无 `gateway` 工具可用，才退回裸调：\n\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n**重启后如果新版本触发了插件依赖首次安装（如新版 codex 插件），日志会出现类似 `npm install` 子进程且短时间内端口不监听是正常现象**；观察其 node_modules 增长/CPU占用判断是否卡死，若卡在慢速 IPv6 上超过 3 分钟无进展，可参考第零步的 IPv4 强制方案排查，不要贸然 kill 掉该子进程。\n\n第五步设好的 cron 会在重启后 90 秒内自动触发，通知爸比升级完成。\n\n---\n\n## ⏪ 回滚方案\n\n任一步骤出问题立即执行：\n\n```bash\nPREV_VER=<回退版本，如 2026.5.6>\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_BAK=$(ls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | sort | tail -1)\n\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\nfi\nnpm install -g openclaw@${PREV_VER}\n\ncp ~/.openclaw/openclaw.json.bak-${PREV_VER} ~/.openclaw/openclaw.json\ncp ~/.openclaw/.env.bak-${PREV_VER} ~/.openclaw/.env\n\nif [ -f \"${OVERRIDE}.bak-${PREV_VER}\" ]; then\n  cp \"${OVERRIDE}.bak-${PREV_VER}\" \"$OVERRIDE\"\n  echo \"override.conf 已还原 ✅\"\nelse\n  echo \"override.conf 备份不存在，跳过 ✅\"\nfi\n\nif [ -n \"$LOSSLESS_BAK\" ] && [ -d \"$LOSSLESS_BAK\" ]; then\n  rm -rf \"$HOME/.openclaw/extensions/lossless-claw\"\n  cp -r \"$LOSSLESS_BAK\" \"$HOME/.openclaw/extensions/lossless-claw\"\n  echo \"lossless-claw 已还原 ✅\"\nelse\n  echo \"lossless-claw 备份不存在，跳过 ✅\"\nfi\n\nsystemctl --user daemon-reload\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 回滚完成，重启生效\"\n\n若无 gateway 工具可用，才退回：\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n等飞书收到「欢欢重启完毕，在线了 🐾」，告知爸比回滚完成及原因。\n\n---\n\n## 注意事项\n\n- **不要用 `gateway update.run` 升级**，npm 手动指定版本更可控\n- **重启一律优先走平台 `gateway` 工具（action=restart）**，不裸调 systemctl\n- **升级前必须核对目标版本的 Node 最低要求**（`npm view openclaw@<版本> engines.node`），不满足要先升级 Node 再装 openclaw\n- **npm install 卡顿优先排查 IPv4/IPv6 速度差异**（`curl -4`/`curl -6` 对比测速），若 IPv6 明显慢，用 `NODE_OPTIONS=\"--dns-result-order=ipv4first\"` 强制优先 IPv4\n- **skill description字段只写触发场景，不写变更记录**（2026-07-27元教训：description是agent discovery语义匹配依据，写成changelog会导致agent无法自然语言触发这个skill，历史更新记录见上方Changelog小节）\n- **feishu 插件路径**：`~/.openclaw/npm/node_modules/@openclaw/feishu`（openclaw 自管，非 npm global）\n- **lossless-claw 路径**：`~/.openclaw/extensions/lossless-claw`（openclaw 自管）\n- **systemd service 不读 .bashrc**，代理若需在 service 中生效，需配置 override.conf 或 EnvironmentFile\n- **lossless-claw 踩坑**：2026-04-14 升级 4.14 不兼容，回退 4.11 解决，每次升级必须检查\n- **MiniMax 不调用 message 工具**，涉及发消息的 cron 不要用 MiniMax\n- **brave 插件外部化（2026.5.12 起）**：升级后如果遇到 \"web_search provider is not available: brave\"，执行 `openclaw plugins install --force @openclaw/brave-plugin` 后重启\n- **feishu 插件不兼容**：升级后 feishu 注册失败时，执行 `openclaw plugins install --force @openclaw/feishu` 后重启\n- **codex EACCES 错误**：多用户同机时，`/tmp/jiti/` 目录需要 sticky bit（`sudo chmod 1777 /tmp/jiti`），否则不同用户的 codex 会互相冲突\n- **多用户兼容风险**：`npm install -g openclaw` 会覆盖全局包，影响同机所有 OpenClaw 用户\n- **升级完成通知 cron**：设置 3 分钟而非更短，防止 gateway 还未完全恢复时触发\n\n---\n\n## 开源版说明\n\n- 技能适配 OpenClaw 所有标准部署（WSL2/Linux VM/原生 Linux）\n- 如果使用代理，自动检测 127.0.0.1:7890，也可在执行前手动 `export HTTP_PROXY=http://your-proxy:port`\n- lossless-claw / override.conf 均为可选组件，不存在时自动跳过，不会报错中断\n- 服务管理默认 `systemd --user`，如使用其他方式（如 pm2、docker）请修改第八步的重启命令\n- 首次使用前建议先执行第零步（环境探测），确认环境配置正确\n\nFile v1.8.0:_meta.json\n\n{\n  \"ownerId\": \"kn79f0shgp6jenfxa0cfqgm25x82m4bq\",\n  \"slug\": \"oc-upgrade\",\n  \"version\": \"1.8.0\",\n  \"publishedAt\": 1785159516199\n}\n\nFile v1.8.0:skill-card.md\n\n## Description: <br>\nOpenClaw Upgrade guides an agent through a standard OpenClaw upgrade workflow, including environment checks, Node compatibility checks, IPv4/IPv6 registry checks, plugin compatibility review, backup, upgrade, validation, restart, and rollback steps. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[tangsuann](https://clawhub.ai/user/tangsuann) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nOpenClaw operators and developers use this skill when upgrading an OpenClaw installation and need a repeatable operational checklist with compatibility checks, backup steps, post-upgrade validation, restart guidance, and rollback instructions. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The workflow reads ~/.openclaw/.env and creates versioned plaintext backups that may contain secrets. <br>\nMitigation: Review the token lookup before installation, restrict permissions on backup files, and delete or encrypt secret-bearing backups after the upgrade is verified. <br>\nRisk: The workflow can upgrade global OpenClaw packages, which may affect other users on the same host. <br>\nMitigation: Run the included same-host and WSL user checks, confirm compatibility with affected users, and require explicit approval before executing the global npm upgrade. <br>\nRisk: The workflow can restart the OpenClaw gateway and interrupt active sessions. <br>\nMitigation: Use the gateway restart path when available, set the one-time completion notification before restart, validate service recovery, and use the documented rollback path if checks fail. <br>\nRisk: Cross-user and WSL discovery can expose local installation details beyond the current user. <br>\nMitigation: Limit discovery to hosts where the operator is authorized to inspect other OpenClaw installs, and remove or narrow cross-user discovery when that scope is not needed. <br>\nRisk: A one-time cron notification is scheduled as part of the restart workflow. <br>\nMitigation: Confirm delete-after-run behavior, review the notification payload for sensitive details, and clean up the scheduled task manually if the upgrade is cancelled. <br>\n\n\n## Reference(s): <br>\n- [ClawHub Skill Page](https://clawhub.ai/tangsuann/skills/oc-upgrade) <br>\n- [OpenClaw Release Notes API](https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}) <br>\n- [npm Registry](https://registry.npmjs.org/) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance] <br>\n**Output Format:** [Markdown guidance with bash command blocks and operational checklists] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Includes pre-upgrade checks, approval gates, backup verification, validation criteria, restart guidance, and rollback commands.] <br>\n\n## Skill Version(s): <br>\n1.8.0 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.7.0: 3 files, 10809 bytes\n\nFiles: _meta.json (129b), skill-card.md (2728b), SKILL.md (23378b)\n\nFile v1.7.0:SKILL.md\n\n---\nname: \"openclaw-upgrade\"\ndescription: \"OpenClaw升级标准流程，第零步新增Node版本检测+IPv4/IPv6速度探测，避免版本不兼容和网络卡顿\"\n---\n\n# OpenClaw 升级技能\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n- 2026-07-27：NAS欢欢用自写脚本升级，脚本从gateway进程内部nohup启动，第一步systemctl stop把整个进程组一起杀掉，脚本自己被杀死，npm install根本没跑起来，gateway停了近6小时无人察觉——本skill的流程设计（npm install前不停服务、重启只在最后单独一步、重启前先设好通知cron）天然规避了这个坑，但重启这一步本身如果裸调systemctl也仍有被自身进程树波及的理论风险，已在第八步/回滚方案中改为优先走平台 gateway 工具\n- 2026-07-27（同一事故的第二个坑）：NAS欢欢在手动拉起gateway后，agent恢复中断会话继续把npm包升到2026.7.1-2，但机器Node还是22.22.1，openclaw 2026.7.1-2要求Node≥22.22.3，导致gateway直接拒绝启动；排查过程中还发现该NAS访问registry.npmjs.org走IPv6比IPv4慢6倍（4秒 vs 0.66秒），跨版本升级触发的codex插件依赖安装卡在慢速IPv6连接上4分半没有进展——本skill第零步此前完全没有检查Node版本、也没有IPv4/IPv6速度探测，是两个真实缺口，已补入第零步\n\n四个教训都已写入流程。\n\n---\n\n## 第零步：环境探测\n\n在任何操作之前，先自动探测并汇报当前环境：\n\n```bash\n# === 环境探测 ===\necho \"=== OpenClaw 环境 ===\"\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\n\n# npm global 路径\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\n# Node.js 版本检测（2026-07-27新增：NAS欢欢升级openclaw到2026.7.1-2后，\n# 因Node版本(22.22.1)低于该版本要求的22.22.3，gateway直接拒绝启动，停机近1小时）\necho \"\"\necho \"=== Node.js 版本 ===\"\nNODE_VER=$(node --version 2>/dev/null | sed 's/^v//')\necho \"当前 Node: v${NODE_VER:-未知}\"\nif [ -z \"$NODE_VER\" ]; then\n  echo \"⚠️ 无法检测 Node 版本，node 命令不可用\"\nelse\n  # 提取主版本号做基础健康检查（22.x线是当前OpenClaw要求的主流线）\n  NODE_MAJOR=$(echo \"$NODE_VER\" | cut -d. -f1)\n  if [ \"$NODE_MAJOR\" -lt 22 ]; then\n    echo \"⚠️ Node 主版本 ${NODE_MAJOR} 低于 22，多数近期 OpenClaw 版本会拒绝启动\"\n  else\n    echo \"Node 主版本 ${NODE_MAJOR} ✅（具体最低子版本要求见第一步「目标版本」核对）\"\n  fi\nfi\necho \"⚠️ 注意：仅确认当前 Node 版本不够，必须在第一步拿到目标版本的具体 Node 最低版本要求后，\n      两者对比才能判断是否需要先升级 Node。不要假设当前版本一定够用。\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"\n  echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"\n  echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# IPv4/IPv6 速度探测（2026-07-27新增：NAS欢欢升级触发的codex插件依赖安装\n# 卡在慢速IPv6连接上4分半没有进展，IPv6访问registry比IPv4慢6倍，是同一次事故的第二个真实缺口）\necho \"\"\necho \"=== registry IPv4/IPv6 速度探测 ===\"\nIPV4_TIME=$(timeout 5 curl -4 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\nIPV6_TIME=$(timeout 5 curl -6 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\necho \"IPv4: ${IPV4_TIME:-超时/不可用}s\"\necho \"IPv6: ${IPV6_TIME:-超时/不可用}s\"\nif [ -z \"$IPV6_TIME\" ]; then\n  echo \"IPv6 不可用或超时，npm install 默认可能仍会尝试 IPv6 优先，建议升级/安装步骤强制 --force-ipv4 兜底\"\nelif python3 -c \"exit(0 if float('$IPV6_TIME') > float('${IPV4_TIME:-999}') * 2 else 1)\" 2>/dev/null; then\n  echo \"⚠️ IPv6 明显慢于 IPv4（超2倍），npm install/npm update 建议强制 IPv4 避免卡顿：\"\n  echo \"   npm config set prefer-ipv4 true   # 或临时: npm install --force-ipv4（部分npm版本可能不支持此flag，改用 NODE_OPTIONS='--dns-result-order=ipv4first'）\"\n  echo \"   推荐：export NODE_OPTIONS=\\\"--dns-result-order=ipv4first\\\" 后再执行 npm install/update\"\nelse\n  echo \"IPv4/IPv6 速度接近，无需特殊处理 ✅\"\nfi\n\n# 可选组件检测\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nHAS_OVERRIDE=false\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\n[ -f \"$OVERRIDE\" ] && HAS_OVERRIDE=true\necho \"override.conf: $HAS_OVERRIDE\"\n\necho \"服务管理: systemd --user\"\n\n# 多用户 /tmp/jiti 权限检查（防止 codex EACCES 问题）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /tmp/jiti)\n  if [ \"$JITI_PERM\" != \"1777\" ]; then\n    echo \"⚠️ /tmp/jiti 权限为 $JITI_PERM，多用户环境可能导致 codex EACCES 错误\"\n    echo \"建议执行: sudo chmod 1777 /tmp/jiti\"\n  else\n    echo \"/tmp/jiti: 1777 ✅\"\n  fi\nelse\n  echo \"/tmp/jiti: 不存在 ✅\"\nfi\n\n# 扫描其他 OpenClaw 用户（同机不同用户共享 npm global 升级风险）\necho \"\"\necho \"=== 其他 OpenClaw 用户检测 ===\"\n\n# 方法1：扫描同系统 Linux 用户（同 WSL 实例）\nSAME_HOST_USERS=\"\"\nfor U in $(ls /home/ 2>/dev/null); do\n  if [ \"$U\" != \"$(whoami)\" ] && [ -d \"/home/$U/.openclaw\" ]; then\n    echo \"用户(同主机): $U\"\n    SAME_HOST_USERS=\"$SAME_HOST_USERS $U\"\n  fi\ndone\n\n# 方法2：通过 Windows 枚举所有 WSL 实例（跨 WSL 实例检测）\nWSL_INSTANCES=\"\"\nif command -v powershell.exe &>/dev/null; then\n  WSL_LIST=$(powershell.exe -NoProfile -Command \"wsl --list --verbose\" 2>/dev/null | grep -i -v \"NAME\\|Windows\" || true)\n  if [ -n \"$WSL_LIST\" ]; then\n    echo \"$WSL_LIST\" | while read -r INSTANCE; do\n      INSTANCE=$(echo \"$INSTANCE\" | awk '{print $1}')\n      if [ -n \"$INSTANCE\" ] && [ \"$INSTANCE\" != \"$(hostname)\" ]; then\n        WSL_INSTANCES=\"$WSL_INSTANCES $INSTANCE\"\n        echo \"WSL实例: $INSTANCE\"\n        # 检查该实例的 ~/.openclaw（通过 /mnt/wsl/ 或 \\\\wsl$ 访问）\n        if [ -d \"/mnt/wsl/$INSTANCE/home/\" ]; then\n          for WU in /mnt/wsl/$INSTANCE/home/*/; do\n            WU=$(basename \"$WU\")\n            if [ -d \"/mnt/wsl/$INSTANCE/home/$WU/.openclaw\" ]; then\n              echo \"  → 用户 $WU 有 OpenClaw 安装\"\n              SAME_HOST_USERS=\"$SAME_HOST_USERS $WU@$INSTANCE\"\n            fi\n          done\n        fi\n      fi\n    done\n  else\n    echo \"WSL列表: 无输出（WSL interop 可能不可用，跳过）\"\n  fi\nelse\n  echo \"WSL列表: powershell.exe 不可用，跳过\"\nfi\n\n# 方法3：检测 npm global openclaw 是否被其他用户注册（通过 audit 记录或已知信息）\necho \"npm global path: $(npm root -g 2>/dev/null)\"\necho \"npm global openclaw: $(ls -la \"$(npm root -g 2>/dev/null)/openclaw/package.json\" 2>/dev/null | awk '{print $3\":\"$4}')\"\n\n# 汇总\nif [ -z \"$SAME_HOST_USERS\" ] && [ -z \"$WSL_INSTANCES\" ]; then\n  echo \"未发现其他 OpenClaw 用户 ✅\"\nelse\n  echo \"\"\n  echo \"⚠️ 发现其他 OpenClaw 用户/实例：$SAME_HOST_USERS $WSL_INSTANCES\"\n  echo \"⚠️ npm install -g openclaw 会影响所有用户共享的 npm global 包\"\n  echo \"⚠️ 升级前必须确认其他用户的 openclaw 和目标版本兼容（特别是插件）\"\n  echo \"⚠️ 如果已知有其他用户但检测未命中（如 raven 在独立的 WSL 实例），请在升级前手动确认对方状态\"\nfi\n```\n\n向爸比汇报环境探测结果，确认后继续。\n\n---\n\n## 第一步：确认目标版本\n\n```bash\n# 查当前版本和 npm 最新版\nopenclaw --version\nnpm view openclaw version\n\n# 查目标版本 release notes\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\nTARGET_VER=<目标版本，如 2026.5.12>\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('body','')[:3000])\"\n```\n\n**Node 版本兼容性核对（2026-07-27新增，与第零步 Node 检测配套）**：\n```bash\n# 查目标版本 package.json 的 engines.node 字段（最准确来源）\nnpm view openclaw@${TARGET_VER} engines.node 2>&1\n```\n把这个结果和第零步检测到的当前 Node 版本对比：\n- 若当前 Node 满足要求 → 正常继续\n- 若不满足 → **必须在第六步执行升级前先升级 Node**（同机器同大版本线内的 apt/nvm 升级即可，不要跨大版本线），否则升级完 openclaw 包后 gateway 会直接拒绝启动\n\n向爸比汇报：当前版本、目标版本、release highlights 摘要、**Node 版本是否满足要求**，等爸比确认目标版本（若 Node 不满足，一并确认是否同意先升级 Node）。\n\n---\n\n## 第二步：检查插件兼容性\n\n```bash\n# 列出当前启用的插件\nopenclaw plugins list 2>/dev/null | grep \"enabled\"\n```\n\n针对**每个 enabled 插件**，在 release notes 里搜索对应关键词：\n\n```bash\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"\nimport json,sys\nd=json.load(sys.stdin)\nbody = d.get('body','')\nkeywords = ['feishu', 'lossless', 'minimax', 'anthropic', 'deepseek', 'openai', 'memory-core']\nfor kw in keywords:\n    lines = [l.strip() for l in body.split('\\n') if kw.lower() in l.lower() and l.strip()]\n    if lines:\n        print(f'=== {kw} ===')\n        for l in lines[:5]: print(' ', l)\n\"\n```\n\n重点关注：\n- **lossless-claw**：手动装的 global 插件，历史上踩过坑，必须关注\n- **@openclaw/feishu**：openclaw 自管 npm，升级可能改版本\n- 其余 stock 插件随主包升级，通常无需额外处理\n\n向爸比汇报兼容性评估，有⚠️风险说清楚。\n\n---\n\n## 第三步：记录插件快照\n\n```bash\nopenclaw plugins list 2>/dev/null > /tmp/plugins-before-${TARGET_VER}.txt\necho \"✅ 插件快照已保存 → /tmp/plugins-before-${TARGET_VER}.txt\"\n```\n\n---\n\n## 第四步：备份\n\n```bash\nCURRENT_VER=$(openclaw --version 2>/dev/null | grep -oP '[\\d.]+' | head -1)\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_DIR=\"$HOME/.openclaw/extensions/lossless-claw\"\n\n# 1. 主配置\ncp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-${CURRENT_VER}\necho \"1/5 openclaw.json ✅\"\n\n# 2. systemd override（含 Token + 代理）—— 可选，如存在才备份\nif [ -f \"$OVERRIDE\" ]; then\n  cp \"$OVERRIDE\" \"${OVERRIDE}.bak-${CURRENT_VER}\"\n  echo \"2/5 override.conf ✅\"\nelse\n  echo \"2/5 override.conf 不存在，跳过 ✅\"\nfi\n\n# 3. 环境变量（含 API Keys）\ncp ~/.openclaw/.env ~/.openclaw/.env.bak-${CURRENT_VER}\necho \"3/5 .env ✅\"\n\n# 4. lossless-claw —— 可选，如存在才备份；自适应大小\n#    node_modules >500MB → 只备份 dist + package.json（避免 SIGKILL）\n#    node_modules ≤500MB → 完整备份\nif [ -d \"$LOSSLESS_DIR\" ]; then\n  LOSSLESS_VER=$(cat \"$LOSSLESS_DIR/package.json\" | \\\n    python3 -c \"import json,sys;print(json.load(sys.stdin)['version'])\")\n  LOSSLESS_NM_SIZE=$(du -sm \"$LOSSLESS_DIR/node_modules/\" 2>/dev/null | cut -f1)\n  LOSSLESS_BAK=\"$HOME/.openclaw/extensions/lossless-claw.bak-${LOSSLESS_VER}\"\n  mkdir -p \"$LOSSLESS_BAK\"\n  if [ \"${LOSSLESS_NM_SIZE:-0}\" -gt 500 ]; then\n    cp \"$LOSSLESS_DIR/package.json\" \"$LOSSLESS_BAK/\"\n    cp \"$LOSSLESS_DIR/openclaw.plugin.json\" \"$LOSSLESS_BAK/\"\n    cp -r \"$LOSSLESS_DIR/dist\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (dist only, node_modules=${LOSSLESS_NM_SIZE}MB 过大跳过) ✅\"\n  else\n    cp -r \"$LOSSLESS_DIR/.\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (完整备份) ✅\"\n  fi\nelse\n  echo \"4/5 lossless-claw 不存在，跳过 ✅\"\nfi\n\n# 5. feishu 插件（只备份 package.json 作版本存档，dist 随 openclaw 安装重建）\nif [ -d \"$FEISHU_DIR\" ]; then\n  mkdir -p \"${FEISHU_DIR}.bak-${CURRENT_VER}\"\n  cp \"$FEISHU_DIR/package.json\" \"${FEISHU_DIR}.bak-${CURRENT_VER}/\"\n  echo \"5/5 feishu ✅\"\nelse\n  echo \"5/5 feishu 插件目录不存在，跳过 ✅\"\nfi\n\necho \"\"\necho \"=== 备份清单 ===\"\nls ~/.openclaw/openclaw.json.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ openclaw.json\"\nls ~/.openclaw/.env.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ .env\"\n[ -f \"${OVERRIDE}.bak-${CURRENT_VER}\" ] && echo \"✅ override.conf\" || echo \"⏭ override.conf (不存在)\"\nls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | tail -1 | xargs -I{} echo \"✅ {}\" || echo \"⏭ lossless-claw (不存在)\"\nls -d \"${FEISHU_DIR}.bak-${CURRENT_VER}\" 2>/dev/null && echo \"✅ feishu\" || echo \"⏭ feishu (不存在)\"\n```\n\n确认核心备份（openclaw.json + .env）存在后再继续。\n\n---\n\n## 第五步：设好重启后通知 cron（先于重启执行）\n\ngateway 重启会中断当前 session，重启后欢欢是全新上下文，不会记得升级完成这件事。\n**必须在重启前设好一次性 systemEvent cron，重启后自动触发通知爸比。**\n\n用 `cron` 工具创建：\n- `schedule`: `at`，时间 = 当前时间 + 3 分钟（180 秒，实践中90秒有时 gateway 还未完全恢复）\n- `payload.kind`: `systemEvent`\n- `payload.text`: 升级完成通知（含版本号、插件状态、耗时）\n- `sessionTarget`: `main`\n- `deleteAfterRun`: `true`\n\n示例通知文本：\n```\n🎉 OpenClaw 升级完成！v<旧版本> → v<新版本>，插件全部正常（lossless-claw ✅ feishu ✅），耗时约X分钟。\n```\n\n> ⚠️ **3分钟是经过实践的安全值**，90秒有时会在 gateway 恢复前触发导致通知失败。\n\ncron 创建成功后，再执行下一步。\n\n---\n\n## 第六步：执行升级\n\n**等爸比说「执行」才动手。**\n\n> ⚠️ 如果第零步检测到其他 OpenClaw 用户，向爸比汇报：「发现用户 [名字]，当前版本/插件如上，升级可能影响对方。是否已确认兼容？」。爸比确认后再执行。\n> ⚠️ 如果第一步核对发现当前 Node 版本不满足目标版本要求，**必须先升级 Node**（apt/nvm 同大版本线升级），确认 `node --version` 达标后再继续本步骤，否则 openclaw 包装上后 gateway 会拒绝启动。\n\n```bash\n# 自动检测代理并安装\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\n  echo \"使用代理: 127.0.0.1:7890\"\nelse\n  echo \"直连安装\"\nfi\n\n# 若第零步检测到 IPv6 明显慢于 IPv4，强制优先走 IPv4，避免卡顿\nif [ \"${IPV6_SLOWER:-0}\" = \"1\" ]; then\n  export NODE_OPTIONS=\"--dns-result-order=ipv4first\"\n  echo \"已强制 DNS 优先 IPv4（IPv6 检测偏慢）\"\nfi\n\nnpm install -g openclaw@${TARGET_VER}\n```\n\n---\n\n## 第七步：验证\n\n```bash\n# 版本确认\nopenclaw --version   # 应为目标版本\n\n# Node 版本再次确认（双保险，防止第六步升级期间 Node 版本被意外改动）\nnode --version\n\n# 自动修复配置问题（如外部化插件导致的 Invalid Config）\nopenclaw doctor --fix 2>&1 | tail -5\n\n# 插件健康检查\nopenclaw doctor      # Errors = 0\n\n# 检查是否有插件加载失败\nFAILED=$(openclaw plugins list 2>/dev/null | grep -i \"fail\\|error\" | grep -v \"grep\")\nif [ -n \"$FAILED\" ]; then\n  echo \"⚠️ 检测到插件加载失败：\"\n  echo \"$FAILED\"\n  echo \"尝试自动修复...\"\n  \n  # feishu 失败 → 强制重装（feishu是最关键通道）\n  if echo \"$FAILED\" | grep -qi \"feishu\"; then\n    echo \"🔧 feishu 插件失败，强制重装...\"\n    openclaw plugins install --force @openclaw/feishu 2>&1\n    echo \"⚠️ 重装后需要重启 gateway\"\n  fi\nelse\n  echo \"✅ 所有插件加载正常\"\nfi\n\n# 插件对比\ndiff /tmp/plugins-before-${TARGET_VER}.txt <(openclaw plugins list 2>/dev/null)\n```\n\n验收标准（全部通过才继续）：\n- ✅ 版本 = 目标版本\n- ✅ Node 版本满足目标版本 engines.node 要求（第一步核对结果仍成立）\n- ✅ lossless-claw（若存在）仍在 enabled 列表\n- ✅ feishu（若存在）仍在 enabled 列表\n- ✅ doctor Errors = 0\n- ✅ 无插件加载失败（`FAILED` 为空）\n\n有任何一项不通过 → 立即执行回滚，不继续。\n\n---\n\n## 第八步：重启 gateway\n\n**优先用平台 `gateway` 工具（action=restart）执行重启，而不是裸调 `systemctl restart`。**\n\n原因：如果当前正在执行这个 skill 的 agent 本身就跑在即将被重启的 gateway 进程内，直接在该进程里 exec 一条 `systemctl restart`，理论上仍有被自身进程树/cgroup 波及、命令没跑完就被回收的风险（2026-07-27 NAS欢欢那次是 `stop` 单独执行时进程组被杀死导致后续步骤全部丢失，同样的风险模型也适用于 restart，只是概率更低）。`gateway` 工具是平台原生的重启入口，设计上会正确处理自重启场景（如脱离父进程生命周期、必要时排队等待写锁释放），比裸调 systemd 更安全。\n\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 升级完成，重启生效\"\n```\n\n若当前环境没有 `gateway` 工具可用（例如纯 CLI 场景无平台层封装），才退回裸调：\n\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n**重启后如果新版本触发了插件依赖首次安装（如新版 codex 插件），日志会出现类似 `npm install` 子进程且短时间内端口不监听是正常现象**（2026-07-27 曾在此环节耗时数分钟）；观察其 node_modules 增长/CPU占用判断是否卡死，若卡在慢速 IPv6 上超过 3 分钟无进展，可参考第零步的 IPv4 强制方案排查，不要贸然 kill 掉该子进程（会导致 gateway 判定插件安装失败退出，虽然 systemd 通常会自动重试）。\n\n第五步设好的 cron 会在重启后 90 秒内自动触发，通知爸比升级完成。\n\n---\n\n## ⏪ 回滚方案\n\n任一步骤出问题立即执行：\n\n```bash\nPREV_VER=<回退版本，如 2026.5.6>\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_BAK=$(ls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | sort | tail -1)\n\n# 1. 回退 openclaw（自动检测代理）\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\nfi\nnpm install -g openclaw@${PREV_VER}\n\n# 2. 还原配置\ncp ~/.openclaw/openclaw.json.bak-${PREV_VER} ~/.openclaw/openclaw.json\ncp ~/.openclaw/.env.bak-${PREV_VER} ~/.openclaw/.env\n\n# 3. 还原 override.conf（可选，如备份存在才还原）\nif [ -f \"${OVERRIDE}.bak-${PREV_VER}\" ]; then\n  cp \"${OVERRIDE}.bak-${PREV_VER}\" \"$OVERRIDE\"\n  echo \"override.conf 已还原 ✅\"\nelse\n  echo \"override.conf 备份不存在，跳过 ✅\"\nfi\n\n# 4. 还原 lossless-claw（可选，如备份存在才还原）\nif [ -n \"$LOSSLESS_BAK\" ] && [ -d \"$LOSSLESS_BAK\" ]; then\n  rm -rf \"$HOME/.openclaw/extensions/lossless-claw\"\n  cp -r \"$LOSSLESS_BAK\" \"$HOME/.openclaw/extensions/lossless-claw\"\n  echo \"lossless-claw 已还原 ✅\"\nelse\n  echo \"lossless-claw 备份不存在，跳过 ✅\"\nfi\n\n# 5. 还原 feishu（package.json 存档，dist 由 openclaw 重建，通常无需手动还原）\n\n# 6. 重启（同第八步：优先用平台 gateway 工具 action=restart，而非裸调 systemctl）\nsystemctl --user daemon-reload\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 回滚完成，重启生效\"\n\n若无 gateway 工具可用，才退回：\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n等飞书收到「欢欢重启完毕，在线了 🐾」，告知爸比回滚完成及原因。\n\n---\n\n## 注意事项\n\n- **不要用 `gateway update.run` 升级**，npm 手动指定版本更可控\n- **重启一律优先走平台 `gateway` 工具（action=restart）**，不裸调 systemctl（2026-07-27 教训：NAS欢欢自写脚本从gateway进程内部nohup后直接systemctl stop，被自身进程组一起杀死，后续步骤全丢；虽然那次是stop不是restart，但同样的\"自身进程树被波及\"风险模型也适用于裸调restart，gateway工具是平台原生入口，更安全）\n- **升级前必须核对目标版本的 Node 最低要求**（`npm view openclaw@<版本> engines.node`），不满足要先升级 Node 再装 openclaw（2026-07-27 教训：NAS欢欢升级到2026.7.1-2但Node停在22.22.1，openclaw要求≥22.22.3，gateway直接拒绝启动，停机近1小时才排查出来）\n- **npm install 卡顿优先排查 IPv4/IPv6 速度差异**（`curl -4`/`curl -6` 对比测速），若 IPv6 明显慢，用 `NODE_OPTIONS=\"--dns-result-order=ipv4first\"` 强制优先 IPv4（2026-07-27 教训：某NAS的IPv6访问registry比IPv4慢6倍，跨版本升级触发的插件依赖安装卡在慢速IPv6连接上数分钟无进展）\n- **feishu 插件路径**：`~/.openclaw/npm/node_modules/@openclaw/feishu`（openclaw 自管，非 npm global）\n- **lossless-claw 路径**：`~/.openclaw/extensions/lossless-claw`（openclaw 自管）\n- **systemd service 不读 .bashrc**，代理若需在 service 中生效，需配置 override.conf 或 EnvironmentFile\n- **lossless-claw 踩坑**：2026-04-14 升级 4.14 不兼容，回退 4.11 解决，每次升级必须检查\n- **MiniMax 不调用 message 工具**，涉及发消息的 cron 不要用 MiniMax\n- **brave 插件外部化（2026.5.12 起）**：升级后如果遇到 \"web_search provider is not available: brave\"，执行 `openclaw plugins install --force @openclaw/brave-plugin` 后重启\n- **feishu 插件不兼容**：升级后 feishu 注册失败时，执行 `openclaw plugins install --force @openclaw/feishu` 后重启\n- **codex EACCES 错误**：多用户同机时，`/tmp/jiti/` 目录需要 sticky bit（`sudo chmod 1777 /tmp/jiti`），否则不同用户的 codex 会互相冲突\n- **多用户兼容风险**：`npm install -g openclaw` 会覆盖全局包，影响同机所有 OpenClaw 用户。第零步多用户检测发现其他用户时，升级前必须确认对方版本兼容、插件正常，否则需协调双方一起升级或分别处理\n- **升级完成通知 cron**：设置 3 分钟而非更短，防止 gateway 还未完全恢复时触发\n\n---\n\n## 开源版说明\n\n- 技能适配 OpenClaw 所有标准部署（WSL2/Linux VM/原生 Linux）\n- 如果使用代理，自动检测 127.0.0.1:7890，也可在执行前手动 `export HTTP_PROXY=http://your-proxy:port`\n- lossless-claw / override.conf 均为可选组件，不存在时自动跳过，不会报错中断\n- 服务管理默认 `systemd --user`，如使用其他方式（如 pm2、docker）请修改第八步的重启命令\n- 首次使用前建议先执行第零步（环境探测），确认环境配置正确\n\nFile v1.7.0:_meta.json\n\n{\n  \"ownerId\": \"kn79f0shgp6jenfxa0cfqgm25x82m4bq\",\n  \"slug\": \"oc-upgrade\",\n  \"version\": \"1.7.0\",\n  \"publishedAt\": 1785149606613\n}\n\nFile v1.7.0:skill-card.md\n\n## Description: <br>\nOpenClaw Upgrade guides agents through a controlled OpenClaw upgrade workflow with Node version checks and IPv4/IPv6 registry speed probes to reduce compatibility and network-stall failures. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[tangsuann](https://clawhub.ai/user/tangsuann) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and operators maintaining OpenClaw installations use this skill to plan and perform controlled upgrades, including environment checks, plugin compatibility review, backups, validation, restart, and rollback guidance. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The upgrade workflow can change global npm packages and restart the OpenClaw gateway. <br>\nMitigation: Review the environment checks, plugin compatibility results, backups, and explicit confirmation gates before executing upgrade commands; use the rollback path if validation fails. <br>\nRisk: Backups may include files containing API keys or service tokens. <br>\nMitigation: Review backup locations and permissions before running the workflow, especially for .env and systemd override backups. <br>\nRisk: The chmod 1777 /tmp/jiti advice changes shared temporary-directory permissions on multi-user systems. <br>\nMitigation: Apply that permission change only after confirming the multi-user implications for the target host. <br>\nRisk: Node version mismatches or slow IPv6 registry access can interrupt an upgrade. <br>\nMitigation: Compare the target OpenClaw engines.node requirement with the installed Node version and use the IPv4/IPv6 probe guidance before package installation. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/tangsuann/skills/oc-upgrade) <br>\n- [OpenClaw npm registry endpoint](https://registry.npmjs.org/) <br>\n- [OpenClaw release notes API pattern](https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Guidance, Markdown, Shell commands, Configuration] <br>\n**Output Format:** [Markdown with bash command blocks and procedural checklists] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Includes confirmation gates, validation checks, restart guidance, and rollback instructions.] <br>\n\n## Skill Version(s): <br>\n1.7.0 (source: server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.6.0: 3 files, 8609 bytes\n\nFiles: _meta.json (129b), skill-card.md (2397b), SKILL.md (17879b)\n\nFile v1.6.0:SKILL.md\n\n---\nname: \"openclaw-upgrade\"\ndescription: \"OpenClaw升级标准流程，重启步骤改用平台gateway工具而非裸调systemctl，避免自身进程树被波及\"\n---\n\n# OpenClaw 升级技能\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n- 2026-07-27：NAS欢欢用自写脚本升级，脚本从gateway进程内部nohup启动，第一步systemctl stop把整个进程组一起杀掉，脚本自己被杀死，npm install根本没跑起来，gateway停了近6小时无人察觉——本skill的流程设计（npm install前不停服务、重启只在最后单独一步、重启前先设好通知cron）天然规避了这个坑，但重启这一步本身如果裸调systemctl也仍有被自身进程树波及的理论风险，已在第八步/回滚方案中改为优先走平台 gateway 工具\n\n三个教训都已写入流程。\n\n---\n\n## 第零步：环境探测\n\n在任何操作之前，先自动探测并汇报当前环境：\n\n```bash\n# === 环境探测 ===\necho \"=== OpenClaw 环境 ===\"\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\n\n# npm global 路径\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"\n  echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"\n  echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# 可选组件检测\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nHAS_OVERRIDE=false\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\n[ -f \"$OVERRIDE\" ] && HAS_OVERRIDE=true\necho \"override.conf: $HAS_OVERRIDE\"\n\necho \"服务管理: systemd --user\"\n\n# 多用户 /tmp/jiti 权限检查（防止 codex EACCES 问题）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /tmp/jiti)\n  if [ \"$JITI_PERM\" != \"1777\" ]; then\n    echo \"⚠️ /tmp/jiti 权限为 $JITI_PERM，多用户环境可能导致 codex EACCES 错误\"\n    echo \"建议执行: sudo chmod 1777 /tmp/jiti\"\n  else\n    echo \"/tmp/jiti: 1777 ✅\"\n  fi\nelse\n  echo \"/tmp/jiti: 不存在 ✅\"\nfi\n\n# 扫描其他 OpenClaw 用户（同机不同用户共享 npm global 升级风险）\necho \"\"\necho \"=== 其他 OpenClaw 用户检测 ===\"\n\n# 方法1：扫描同系统 Linux 用户（同 WSL 实例）\nSAME_HOST_USERS=\"\"\nfor U in $(ls /home/ 2>/dev/null); do\n  if [ \"$U\" != \"$(whoami)\" ] && [ -d \"/home/$U/.openclaw\" ]; then\n    echo \"用户(同主机): $U\"\n    SAME_HOST_USERS=\"$SAME_HOST_USERS $U\"\n  fi\ndone\n\n# 方法2：通过 Windows 枚举所有 WSL 实例（跨 WSL 实例检测）\nWSL_INSTANCES=\"\"\nif command -v powershell.exe &>/dev/null; then\n  WSL_LIST=$(powershell.exe -NoProfile -Command \"wsl --list --verbose\" 2>/dev/null | grep -i -v \"NAME\\|Windows\" || true)\n  if [ -n \"$WSL_LIST\" ]; then\n    echo \"$WSL_LIST\" | while read -r INSTANCE; do\n      INSTANCE=$(echo \"$INSTANCE\" | awk '{print $1}')\n      if [ -n \"$INSTANCE\" ] && [ \"$INSTANCE\" != \"$(hostname)\" ]; then\n        WSL_INSTANCES=\"$WSL_INSTANCES $INSTANCE\"\n        echo \"WSL实例: $INSTANCE\"\n        # 检查该实例的 ~/.openclaw（通过 /mnt/wsl/ 或 \\\\wsl$ 访问）\n        if [ -d \"/mnt/wsl/$INSTANCE/home/\" ]; then\n          for WU in /mnt/wsl/$INSTANCE/home/*/; do\n            WU=$(basename \"$WU\")\n            if [ -d \"/mnt/wsl/$INSTANCE/home/$WU/.openclaw\" ]; then\n              echo \"  → 用户 $WU 有 OpenClaw 安装\"\n              SAME_HOST_USERS=\"$SAME_HOST_USERS $WU@$INSTANCE\"\n            fi\n          done\n        fi\n      fi\n    done\n  else\n    echo \"WSL列表: 无输出（WSL interop 可能不可用，跳过）\"\n  fi\nelse\n  echo \"WSL列表: powershell.exe 不可用，跳过\"\nfi\n\n# 方法3：检测 npm global openclaw 是否被其他用户注册（通过 audit 记录或已知信息）\necho \"npm global path: $(npm root -g 2>/dev/null)\"\necho \"npm global openclaw: $(ls -la \"$(npm root -g 2>/dev/null)/openclaw/package.json\" 2>/dev/null | awk '{print $3\":\"$4}')\"\n\n# 汇总\nif [ -z \"$SAME_HOST_USERS\" ] && [ -z \"$WSL_INSTANCES\" ]; then\n  echo \"未发现其他 OpenClaw 用户 ✅\"\nelse\n  echo \"\"\n  echo \"⚠️ 发现其他 OpenClaw 用户/实例：$SAME_HOST_USERS $WSL_INSTANCES\"\n  echo \"⚠️ npm install -g openclaw 会影响所有用户共享的 npm global 包\"\n  echo \"⚠️ 升级前必须确认其他用户的 openclaw 和目标版本兼容（特别是插件）\"\n  echo \"⚠️ 如果已知有其他用户但检测未命中（如 raven 在独立的 WSL 实例），请在升级前手动确认对方状态\"\nfi\n```\n\n向爸比汇报环境探测结果，确认后继续。\n\n---\n\n## 第一步：确认目标版本\n\n```bash\n# 查当前版本和 npm 最新版\nopenclaw --version\nnpm view openclaw version\n\n# 查目标版本 release notes\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\nTARGET_VER=<目标版本，如 2026.5.12>\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('body','')[:3000])\"\n```\n\n向爸比汇报：当前版本、目标版本、release highlights 摘要，等爸比确认目标版本。\n\n---\n\n## 第二步：检查插件兼容性\n\n```bash\n# 列出当前启用的插件\nopenclaw plugins list 2>/dev/null | grep \"enabled\"\n```\n\n针对**每个 enabled 插件**，在 release notes 里搜索对应关键词：\n\n```bash\nGITHUB_TOKEN=*** GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"\nimport json,sys\nd=json.load(sys.stdin)\nbody = d.get('body','')\nkeywords = ['feishu', 'lossless', 'minimax', 'anthropic', 'deepseek', 'openai', 'memory-core']\nfor kw in keywords:\n    lines = [l.strip() for l in body.split('\\n') if kw.lower() in l.lower() and l.strip()]\n    if lines:\n        print(f'=== {kw} ===')\n        for l in lines[:5]: print(' ', l)\n\"\n```\n\n重点关注：\n- **lossless-claw**：手动装的 global 插件，历史上踩过坑，必须关注\n- **@openclaw/feishu**：openclaw 自管 npm，升级可能改版本\n- 其余 stock 插件随主包升级，通常无需额外处理\n\n向爸比汇报兼容性评估，有⚠️风险说清楚。\n\n---\n\n## 第三步：记录插件快照\n\n```bash\nopenclaw plugins list 2>/dev/null > /tmp/plugins-before-${TARGET_VER}.txt\necho \"✅ 插件快照已保存 → /tmp/plugins-before-${TARGET_VER}.txt\"\n```\n\n---\n\n## 第四步：备份\n\n```bash\nCURRENT_VER=$(openclaw --version 2>/dev/null | grep -oP '[\\d.]+' | head -1)\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_DIR=\"$HOME/.openclaw/extensions/lossless-claw\"\n\n# 1. 主配置\ncp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-${CURRENT_VER}\necho \"1/5 openclaw.json ✅\"\n\n# 2. systemd override（含 Token + 代理）—— 可选，如存在才备份\nif [ -f \"$OVERRIDE\" ]; then\n  cp \"$OVERRIDE\" \"${OVERRIDE}.bak-${CURRENT_VER}\"\n  echo \"2/5 override.conf ✅\"\nelse\n  echo \"2/5 override.conf 不存在，跳过 ✅\"\nfi\n\n# 3. 环境变量（含 API Keys）\ncp ~/.openclaw/.env ~/.openclaw/.env.bak-${CURRENT_VER}\necho \"3/5 .env ✅\"\n\n# 4. lossless-claw —— 可选，如存在才备份；自适应大小\n#    node_modules >500MB → 只备份 dist + package.json（避免 SIGKILL）\n#    node_modules ≤500MB → 完整备份\nif [ -d \"$LOSSLESS_DIR\" ]; then\n  LOSSLESS_VER=$(cat \"$LOSSLESS_DIR/package.json\" | \\\n    python3 -c \"import json,sys;print(json.load(sys.stdin)['version'])\")\n  LOSSLESS_NM_SIZE=$(du -sm \"$LOSSLESS_DIR/node_modules/\" 2>/dev/null | cut -f1)\n  LOSSLESS_BAK=\"$HOME/.openclaw/extensions/lossless-claw.bak-${LOSSLESS_VER}\"\n  mkdir -p \"$LOSSLESS_BAK\"\n  if [ \"${LOSSLESS_NM_SIZE:-0}\" -gt 500 ]; then\n    cp \"$LOSSLESS_DIR/package.json\" \"$LOSSLESS_BAK/\"\n    cp \"$LOSSLESS_DIR/openclaw.plugin.json\" \"$LOSSLESS_BAK/\"\n    cp -r \"$LOSSLESS_DIR/dist\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (dist only, node_modules=${LOSSLESS_NM_SIZE}MB 过大跳过) ✅\"\n  else\n    cp -r \"$LOSSLESS_DIR/.\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (完整备份) ✅\"\n  fi\nelse\n  echo \"4/5 lossless-claw 不存在，跳过 ✅\"\nfi\n\n# 5. feishu 插件（只备份 package.json 作版本存档，dist 随 openclaw 安装重建）\nif [ -d \"$FEISHU_DIR\" ]; then\n  mkdir -p \"${FEISHU_DIR}.bak-${CURRENT_VER}\"\n  cp \"$FEISHU_DIR/package.json\" \"${FEISHU_DIR}.bak-${CURRENT_VER}/\"\n  echo \"5/5 feishu ✅\"\nelse\n  echo \"5/5 feishu 插件目录不存在，跳过 ✅\"\nfi\n\necho \"\"\necho \"=== 备份清单 ===\"\nls ~/.openclaw/openclaw.json.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ openclaw.json\"\nls ~/.openclaw/.env.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ .env\"\n[ -f \"${OVERRIDE}.bak-${CURRENT_VER}\" ] && echo \"✅ override.conf\" || echo \"⏭ override.conf (不存在)\"\nls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | tail -1 | xargs -I{} echo \"✅ {}\" || echo \"⏭ lossless-claw (不存在)\"\nls -d \"${FEISHU_DIR}.bak-${CURRENT_VER}\" 2>/dev/null && echo \"✅ feishu\" || echo \"⏭ feishu (不存在)\"\n```\n\n确认核心备份（openclaw.json + .env）存在后再继续。\n\n---\n\n## 第五步：设好重启后通知 cron（先于重启执行）\n\ngateway 重启会中断当前 session，重启后欢欢是全新上下文，不会记得升级完成这件事。\n**必须在重启前设好一次性 systemEvent cron，重启后自动触发通知爸比。**\n\n用 `cron` 工具创建：\n- `schedule`: `at`，时间 = 当前时间 + 3 分钟（180 秒，实践中90秒有时 gateway 还未完全恢复）\n- `payload.kind`: `systemEvent`\n- `payload.text`: 升级完成通知（含版本号、插件状态、耗时）\n- `sessionTarget`: `main`\n- `deleteAfterRun`: `true`\n\n示例通知文本：\n```\n🎉 OpenClaw 升级完成！v<旧版本> → v<新版本>，插件全部正常（lossless-claw ✅ feishu ✅），耗时约X分钟。\n```\n\n> ⚠️ **3分钟是经过实践的安全值**，90秒有时会在 gateway 恢复前触发导致通知失败。\n\ncron 创建成功后，再执行下一步。\n\n---\n\n## 第六步：执行升级\n\n**等爸比说「执行」才动手。**\n\n> ⚠️ 如果第零步检测到其他 OpenClaw 用户，向爸比汇报：「发现用户 [名字]，当前版本/插件如上，升级可能影响对方。是否已确认兼容？」。爸比确认后再执行。\n\n```bash\n# 自动检测代理并安装\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\n  echo \"使用代理: 127.0.0.1:7890\"\nelse\n  echo \"直连安装\"\nfi\nnpm install -g openclaw@${TARGET_VER}\n```\n\n---\n\n## 第七步：验证\n\n```bash\n# 版本确认\nopenclaw --version   # 应为目标版本\n\n# 自动修复配置问题（如外部化插件导致的 Invalid Config）\nopenclaw doctor --fix 2>&1 | tail -5\n\n# 插件健康检查\nopenclaw doctor      # Errors = 0\n\n# 检查是否有插件加载失败\nFAILED=$(openclaw plugins list 2>/dev/null | grep -i \"fail\\|error\" | grep -v \"grep\")\nif [ -n \"$FAILED\" ]; then\n  echo \"⚠️ 检测到插件加载失败：\"\n  echo \"$FAILED\"\n  echo \"尝试自动修复...\"\n  \n  # feishu 失败 → 强制重装（feishu是最关键通道）\n  if echo \"$FAILED\" | grep -qi \"feishu\"; then\n    echo \"🔧 feishu 插件失败，强制重装...\"\n    openclaw plugins install --force @openclaw/feishu 2>&1\n    echo \"⚠️ 重装后需要重启 gateway\"\n  fi\nelse\n  echo \"✅ 所有插件加载正常\"\nfi\n\n# 插件对比\ndiff /tmp/plugins-before-${TARGET_VER}.txt <(openclaw plugins list 2>/dev/null)\n```\n\n验收标准（全部通过才继续）：\n- ✅ 版本 = 目标版本\n- ✅ lossless-claw（若存在）仍在 enabled 列表\n- ✅ feishu（若存在）仍在 enabled 列表\n- ✅ doctor Errors = 0\n- ✅ 无插件加载失败（`FAILED` 为空）\n\n有任何一项不通过 → 立即执行回滚，不继续。\n\n---\n\n## 第八步：重启 gateway\n\n**优先用平台 `gateway` 工具（action=restart）执行重启，而不是裸调 `systemctl restart`。**\n\n原因：如果当前正在执行这个 skill 的 agent 本身就跑在即将被重启的 gateway 进程内，直接在该进程里 exec 一条 `systemctl restart`，理论上仍有被自身进程树/cgroup 波及、命令没跑完就被回收的风险（2026-07-27 NAS欢欢那次是 `stop` 单独执行时进程组被杀死导致后续步骤全部丢失，同样的风险模型也适用于 restart，只是概率更低）。`gateway` 工具是平台原生的重启入口，设计上会正确处理自重启场景（如脱离父进程生命周期、必要时排队等待写锁释放），比裸调 systemd 更安全。\n\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 升级完成，重启生效\"\n```\n\n若当前环境没有 `gateway` 工具可用（例如纯 CLI 场景无平台层封装），才退回裸调：\n\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n第五步设好的 cron 会在重启后 90 秒内自动触发，通知爸比升级完成。\n\n---\n\n## ⏪ 回滚方案\n\n任一步骤出问题立即执行：\n\n```bash\nPREV_VER=<回退版本，如 2026.5.6>\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_BAK=$(ls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | sort | tail -1)\n\n# 1. 回退 openclaw（自动检测代理）\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\nfi\nnpm install -g openclaw@${PREV_VER}\n\n# 2. 还原配置\ncp ~/.openclaw/openclaw.json.bak-${PREV_VER} ~/.openclaw/openclaw.json\ncp ~/.openclaw/.env.bak-${PREV_VER} ~/.openclaw/.env\n\n# 3. 还原 override.conf（可选，如备份存在才还原）\nif [ -f \"${OVERRIDE}.bak-${PREV_VER}\" ]; then\n  cp \"${OVERRIDE}.bak-${PREV_VER}\" \"$OVERRIDE\"\n  echo \"override.conf 已还原 ✅\"\nelse\n  echo \"override.conf 备份不存在，跳过 ✅\"\nfi\n\n# 4. 还原 lossless-claw（可选，如备份存在才还原）\nif [ -n \"$LOSSLESS_BAK\" ] && [ -d \"$LOSSLESS_BAK\" ]; then\n  rm -rf \"$HOME/.openclaw/extensions/lossless-claw\"\n  cp -r \"$LOSSLESS_BAK\" \"$HOME/.openclaw/extensions/lossless-claw\"\n  echo \"lossless-claw 已还原 ✅\"\nelse\n  echo \"lossless-claw 备份不存在，跳过 ✅\"\nfi\n\n# 5. 还原 feishu（package.json 存档，dist 由 openclaw 重建，通常无需手动还原）\n\n# 6. 重启（同第八步：优先用平台 gateway 工具 action=restart，而非裸调 systemctl）\nsystemctl --user daemon-reload\n```\n优先：gateway 工具，action=restart，并带上 note 说明\"OpenClaw 回滚完成，重启生效\"\n\n若无 gateway 工具可用，才退回：\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n等飞书收到「欢欢重启完毕，在线了 🐾」，告知爸比回滚完成及原因。\n\n---\n\n## 注意事项\n\n- **不要用 `gateway update.run` 升级**，npm 手动指定版本更可控\n- **重启一律优先走平台 `gateway` 工具（action=restart）**，不裸调 systemctl（2026-07-27 教训：NAS欢欢自写脚本从gateway进程内部nohup后直接systemctl stop，被自身进程组一起杀死，后续步骤全丢；虽然那次是stop不是restart，但同样的\"自身进程树被波及\"风险模型也适用于裸调restart，gateway工具是平台原生入口，更安全）\n- **feishu 插件路径**：`~/.openclaw/npm/node_modules/@openclaw/feishu`（openclaw 自管，非 npm global）\n- **lossless-claw 路径**：`~/.openclaw/extensions/lossless-claw`（openclaw 自管）\n- **systemd service 不读 .bashrc**，代理若需在 service 中生效，需配置 override.conf 或 EnvironmentFile\n- **lossless-claw 踩坑**：2026-04-14 升级 4.14 不兼容，回退 4.11 解决，每次升级必须检查\n- **MiniMax 不调用 message 工具**，涉及发消息的 cron 不要用 MiniMax\n- **brave 插件外部化（2026.5.12 起）**：升级后如果遇到 \"web_search provider is not available: brave\"，执行 `openclaw plugins install --force @openclaw/brave-plugin` 后重启\n- **feishu 插件不兼容**：升级后 feishu 注册失败时，执行 `openclaw plugins install --force @openclaw/feishu` 后重启\n- **codex EACCES 错误**：多用户同机时，`/tmp/jiti/` 目录需要 sticky bit（`sudo chmod 1777 /tmp/jiti`），否则不同用户的 codex 会互相冲突\n- **多用户兼容风险**：`npm install -g openclaw` 会覆盖全局包，影响同机所有 OpenClaw 用户。第零步多用户检测发现其他用户时，升级前必须确认对方版本兼容、插件正常，否则需协调双方一起升级或分别处理\n- **升级完成通知 cron**：设置 3 分钟而非更短，防止 gateway 还未完全恢复时触发\n\n---\n\n## 开源版说明\n\n- 技能适配 OpenClaw 所有标准部署（WSL2/Linux VM/原生 Linux）\n- 如果使用代理，自动检测 127.0.0.1:7890，也可在执行前手动 `export HTTP_PROXY=http://your-proxy:port`\n- lossless-claw / override.conf 均为可选组件，不存在时自动跳过，不会报错中断\n- 服务管理默认 `systemd --user`，如使用其他方式（如 pm2、docker）请修改第八步的重启命令\n- 首次使用前建议先执行第零步（环境探测），确认环境配置正确\n\nFile v1.6.0:_meta.json\n\n{\n  \"ownerId\": \"kn79f0shgp6jenfxa0cfqgm25x82m4bq\",\n  \"slug\": \"oc-upgrade\",\n  \"version\": \"1.6.0\",\n  \"publishedAt\": 1785143930598\n}\n\nFile v1.6.0:skill-card.md\n\n## Description: <br>\nGuides agents through a structured OpenClaw upgrade workflow with environment checks, backups, plugin validation, rollback steps, and safer gateway restart handling. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[tangsuann](https://clawhub.ai/user/tangsuann) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and operators use this skill to plan and execute OpenClaw upgrades with preflight environment checks, plugin compatibility review, backup validation, post-upgrade health checks, and rollback guidance. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The workflow can make privileged operational changes, including global npm package updates, plugin repair, and gateway restart. <br>\nMitigation: Require operator confirmation before execution, review multi-user impact, run the documented preflight checks, and verify OpenClaw health before completing the restart. <br>\nRisk: Backup and restore steps may copy files that contain API keys or service tokens. <br>\nMitigation: Sanitize status reports, protect backup files with restrictive permissions, and remove temporary backups after the upgraded system is validated. <br>\nRisk: Restarting the gateway can interrupt the active agent session and leave users without completion status. <br>\nMitigation: Use the platform gateway restart path when available and configure the one-time post-restart notification before restarting. <br>\n\n\n## Reference(s): <br>\n- [OpenClaw Upgrade on ClawHub](https://clawhub.ai/tangsuann/skills/oc-upgrade) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance] <br>\n**Output Format:** [Markdown instructions with bash code blocks and operational checklists] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Includes environment-specific checks, version placeholders, backup and rollback commands, and operator confirmation points.] <br>\n\n## Skill Version(s): <br>\n1.6.0 (source: server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.5.0: 3 files, 6694 bytes\n\nFiles: _meta.json (129b), skill-card.md (2396b), SKILL.md (12979b)\n\nFile v1.5.0:SKILL.md\n\n---\nname: openclaw-upgrade\ndescription: OpenClaw 版本升级标准流程。适用于各类 OpenClaw 部署（WSL2/Linux VM）。自动探测代理、lossless-claw、systemd override 等可选组件，缺失组件自动跳过。每次说\"升级openclaw\"、\"openclaw升级\"、\"更新openclaw\"时必须执行此技能。\n---\n\n# OpenClaw 升级技能\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n\n两个教训都已写入流程。\n\n---\n\n## 第零步：环境探测\n\n在任何操作之前，先自动探测并汇报当前环境：\n\n```bash\n# === 环境探测 ===\necho \"=== OpenClaw 环境 ===\"\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\n\n# npm global 路径\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"\n  echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"\n  echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# 可选组件检测\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nHAS_OVERRIDE=false\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\n[ -f \"$OVERRIDE\" ] && HAS_OVERRIDE=true\necho \"override.conf: $HAS_OVERRIDE\"\n\necho \"服务管理: systemd --user\"\n\n# 多用户 /tmp/jiti 权限检查（防止 codex EACCES 问题）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /tmp/jiti)\n  if [ \"$JITI_PERM\" != \"1777\" ]; then\n    echo \"⚠️ /tmp/jiti 权限为 $JITI_PERM，多用户环境可能导致 codex EACCES 错误\"\n    echo \"建议执行: sudo chmod 1777 /tmp/jiti\"\n  else\n    echo \"/tmp/jiti: 1777 ✅\"\n  fi\nelse\n  echo \"/tmp/jiti: 不存在 ✅\"\nfi\n```\n\n向爸比汇报环境探测结果，确认后继续。\n\n---\n\n## 第一步：确认目标版本\n\n```bash\n# 查当前版本和 npm 最新版\nopenclaw --version\nnpm view openclaw version\n\n# 查目标版本 release notes\nGITHUB_TOKEN=$(grep GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\nTARGET_VER=<目标版本，如 2026.5.12>\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('body','')[:3000])\"\n```\n\n向爸比汇报：当前版本、目标版本、release highlights 摘要，等爸比确认目标版本。\n\n---\n\n## 第二步：检查插件兼容性\n\n```bash\n# 列出当前启用的插件\nopenclaw plugins list 2>/dev/null | grep \"enabled\"\n```\n\n针对**每个 enabled 插件**，在 release notes 里搜索对应关键词：\n\n```bash\nGITHUB_TOKEN=$(grep GITHUB_TOKEN ~/.openclaw/.env | cut -d= -f2)\ncurl -s -H \"Authorization: token $GITHUB_TOKEN\" \\\n  \"https://api.github.com/repos/openclaw/openclaw/releases/tags/v${TARGET_VER}\" | \\\n  python3 -c \"\nimport json,sys\nd=json.load(sys.stdin)\nbody = d.get('body','')\nkeywords = ['feishu', 'lossless', 'minimax', 'anthropic', 'deepseek', 'openai', 'memory-core']\nfor kw in keywords:\n    lines = [l.strip() for l in body.split('\\n') if kw.lower() in l.lower() and l.strip()]\n    if lines:\n        print(f'=== {kw} ===')\n        for l in lines[:5]: print(' ', l)\n\"\n```\n\n重点关注：\n- **lossless-claw**：手动装的 global 插件，历史上踩过坑，必须关注\n- **@openclaw/feishu**：openclaw 自管 npm，升级可能改版本\n- 其余 stock 插件随主包升级，通常无需额外处理\n\n向爸比汇报兼容性评估，有⚠️风险说清楚。\n\n---\n\n## 第三步：记录插件快照\n\n```bash\nopenclaw plugins list 2>/dev/null > /tmp/plugins-before-${TARGET_VER}.txt\necho \"✅ 插件快照已保存 → /tmp/plugins-before-${TARGET_VER}.txt\"\n```\n\n---\n\n## 第四步：备份\n\n```bash\nCURRENT_VER=$(openclaw --version 2>/dev/null | grep -oP '[\\d.]+' | head -1)\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_DIR=\"$HOME/.openclaw/extensions/lossless-claw\"\n\n# 1. 主配置\ncp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-${CURRENT_VER}\necho \"1/5 openclaw.json ✅\"\n\n# 2. systemd override（含 Token + 代理）—— 可选，如存在才备份\nif [ -f \"$OVERRIDE\" ]; then\n  cp \"$OVERRIDE\" \"${OVERRIDE}.bak-${CURRENT_VER}\"\n  echo \"2/5 override.conf ✅\"\nelse\n  echo \"2/5 override.conf 不存在，跳过 ✅\"\nfi\n\n# 3. 环境变量（含 API Keys）\ncp ~/.openclaw/.env ~/.openclaw/.env.bak-${CURRENT_VER}\necho \"3/5 .env ✅\"\n\n# 4. lossless-claw —— 可选，如存在才备份；自适应大小\n#    node_modules >500MB → 只备份 dist + package.json（避免 SIGKILL）\n#    node_modules ≤500MB → 完整备份\nif [ -d \"$LOSSLESS_DIR\" ]; then\n  LOSSLESS_VER=$(cat \"$LOSSLESS_DIR/package.json\" | \\\n    python3 -c \"import json,sys;print(json.load(sys.stdin)['version'])\")\n  LOSSLESS_NM_SIZE=$(du -sm \"$LOSSLESS_DIR/node_modules/\" 2>/dev/null | cut -f1)\n  LOSSLESS_BAK=\"$HOME/.openclaw/extensions/lossless-claw.bak-${LOSSLESS_VER}\"\n  mkdir -p \"$LOSSLESS_BAK\"\n  if [ \"${LOSSLESS_NM_SIZE:-0}\" -gt 500 ]; then\n    cp \"$LOSSLESS_DIR/package.json\" \"$LOSSLESS_BAK/\"\n    cp \"$LOSSLESS_DIR/openclaw.plugin.json\" \"$LOSSLESS_BAK/\"\n    cp -r \"$LOSSLESS_DIR/dist\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (dist only, node_modules=${LOSSLESS_NM_SIZE}MB 过大跳过) ✅\"\n  else\n    cp -r \"$LOSSLESS_DIR/.\" \"$LOSSLESS_BAK/\"\n    echo \"4/5 lossless-claw (完整备份) ✅\"\n  fi\nelse\n  echo \"4/5 lossless-claw 不存在，跳过 ✅\"\nfi\n\n# 5. feishu 插件（只备份 package.json 作版本存档，dist 随 openclaw 安装重建）\nif [ -d \"$FEISHU_DIR\" ]; then\n  mkdir -p \"${FEISHU_DIR}.bak-${CURRENT_VER}\"\n  cp \"$FEISHU_DIR/package.json\" \"${FEISHU_DIR}.bak-${CURRENT_VER}/\"\n  echo \"5/5 feishu ✅\"\nelse\n  echo \"5/5 feishu 插件目录不存在，跳过 ✅\"\nfi\n\necho \"\"\necho \"=== 备份清单 ===\"\nls ~/.openclaw/openclaw.json.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ openclaw.json\"\nls ~/.openclaw/.env.bak-${CURRENT_VER} 2>/dev/null && echo \"✅ .env\"\n[ -f \"${OVERRIDE}.bak-${CURRENT_VER}\" ] && echo \"✅ override.conf\" || echo \"⏭ override.conf (不存在)\"\nls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | tail -1 | xargs -I{} echo \"✅ {}\" || echo \"⏭ lossless-claw (不存在)\"\nls -d \"${FEISHU_DIR}.bak-${CURRENT_VER}\" 2>/dev/null && echo \"✅ feishu\" || echo \"⏭ feishu (不存在)\"\n```\n\n确认核心备份（openclaw.json + .env）存在后再继续。\n\n---\n\n## 第五步：设好重启后通知 cron（先于重启执行）\n\ngateway 重启会中断当前 session，重启后欢欢是全新上下文，不会记得升级完成这件事。\n**必须在重启前设好一次性 systemEvent cron，重启后自动触发通知爸比。**\n\n用 `cron` 工具创建：\n- `schedule`: `at`，时间 = 当前时间 + 3 分钟（180 秒，实践中90秒有时 gateway 还未完全恢复）\n- `payload.kind`: `systemEvent`\n- `payload.text`: 升级完成通知（含版本号、插件状态、耗时）\n- `sessionTarget`: `main`\n- `deleteAfterRun`: `true`\n\n示例通知文本：\n```\n🎉 OpenClaw 升级完成！v<旧版本> → v<新版本>，插件全部正常（lossless-claw ✅ feishu ✅），耗时约X分钟。\n```\n\n> ⚠️ **3分钟是经过实践的安全值**，90秒有时会在 gateway 恢复前触发导致通知失败。\n\ncron 创建成功后，再执行下一步。\n\n---\n\n## 第六步：执行升级\n\n**等爸比说「执行」才动手。**\n\n```bash\n# 自动检测代理并安装\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\n  echo \"使用代理: 127.0.0.1:7890\"\nelse\n  echo \"直连安装\"\nfi\nnpm install -g openclaw@${TARGET_VER}\n```\n\n---\n\n## 第七步：验证\n\n```bash\n# 版本确认\nopenclaw --version   # 应为目标版本\n\n# 自动修复配置问题（如外部化插件导致的 Invalid Config）\nopenclaw doctor --fix 2>&1 | tail -5\n\n# 插件健康检查\nopenclaw doctor      # Errors = 0\n\n# 检查是否有插件加载失败\nFAILED=$(openclaw plugins list 2>/dev/null | grep -i \"fail\\|error\" | grep -v \"grep\")\nif [ -n \"$FAILED\" ]; then\n  echo \"⚠️ 检测到插件加载失败：\"\n  echo \"$FAILED\"\n  echo \"尝试自动修复...\"\n  \n  # feishu 失败 → 强制重装（feishu是最关键通道）\n  if echo \"$FAILED\" | grep -qi \"feishu\"; then\n    echo \"🔧 feishu 插件失败，强制重装...\"\n    openclaw plugins install --force @openclaw/feishu 2>&1\n    echo \"⚠️ 重装后需要重启 gateway\"\n  fi\nelse\n  echo \"✅ 所有插件加载正常\"\nfi\n\n# 插件对比\ndiff /tmp/plugins-before-${TARGET_VER}.txt <(openclaw plugins list 2>/dev/null)\n```\n\n验收标准（全部通过才继续）：\n- ✅ 版本 = 目标版本\n- ✅ lossless-claw（若存在）仍在 enabled 列表\n- ✅ feishu（若存在）仍在 enabled 列表\n- ✅ doctor Errors = 0\n- ✅ 无插件加载失败（`FAILED` 为空）\n\n有任何一项不通过 → 立即执行回滚，不继续。\n\n---\n\n## 第八步：重启 gateway\n\n```bash\nsystemctl --user restart openclaw-gateway.service\n```\n\n第五步设好的 cron 会在重启后 90 秒内自动触发，通知爸比升级完成。\n\n---\n\n## ⏪ 回滚方案\n\n任一步骤出问题立即执行：\n\n```bash\nPREV_VER=<回退版本，如 2026.5.6>\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\nFEISHU_DIR=\"$HOME/.openclaw/npm/node_modules/@openclaw/feishu\"\nLOSSLESS_BAK=$(ls -d \"$HOME/.openclaw/extensions/lossless-claw.bak-\"* 2>/dev/null | sort | tail -1)\n\n# 1. 回退 openclaw（自动检测代理）\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  export HTTP_PROXY=http://127.0.0.1:7890\n  export HTTPS_PROXY=http://127.0.0.1:7890\nfi\nnpm install -g openclaw@${PREV_VER}\n\n# 2. 还原配置\ncp ~/.openclaw/openclaw.json.bak-${PREV_VER} ~/.openclaw/openclaw.json\ncp ~/.openclaw/.env.bak-${PREV_VER} ~/.openclaw/.env\n\n# 3. 还原 override.conf（可选，如备份存在才还原）\nif [ -f \"${OVERRIDE}.bak-${PREV_VER}\" ]; then\n  cp \"${OVERRIDE}.bak-${PREV_VER}\" \"$OVERRIDE\"\n  echo \"override.conf 已还原 ✅\"\nelse\n  echo \"override.conf 备份不存在，跳过 ✅\"\nfi\n\n# 4. 还原 lossless-claw（可选，如备份存在才还原\n\nArchive v1.3.0: 2 files, 3649 bytes\n\nFiles: SKILL.md (7673b), _meta.json (129b)\n\nArchive v1.2.0: 2 files, 5449 bytes\n\nFiles: _meta.json (129b), SKILL.md (12979b)","readmeExcerpt":"Skill: openclaw-upgrade Owner: tangsuann Summary: OpenClaw版本升级标准流程。每次说\"升级openclaw\"、\"openclaw升级\"、\"更新openclaw\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案 Tags: latest:1.9.1 Version history: v1.9.1 | 2026-08-13T08:33:50.197Z | user Windows 升级主入口改为分离式 schtasks 一次性任务；openclaw update 标记为已实测失败（DLL 锁定 + 自杀陷阱，2026-08-13 实测导致 gateway 宕机 3.5h）；失败教训写入 changelog v1.9.0 | 2026-08-13T02:51:13.841Z | user 环境自适应版：合并 Win","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# 通用快速判定（任一条能出结果即可）\nuname -s          # 返回 \"Linux\" → Linux 分支；命令不存在 → Windows 分支"},{"language":"powershell","snippet":"# Windows 下用这个\n$env:OS           # 返回 \"Windows_NT\" → Windows 分支"},{"language":"powershell","snippet":"Write-Host \"=== OpenClaw 环境（Windows） ===\"\nWrite-Host \"用户: $env:USERNAME\"\nWrite-Host \"Home: $env:USERPROFILE\"\nWrite-Host \"npm global: $(npm prefix -g 2>$null)\"\n\n$nodeVer = (node --version 2>$null) -replace '^v',''\nWrite-Host \"\"\nWrite-Host \"=== Node.js 版本 ===\"\nif (-not $nodeVer) { Write-Host \"⚠️ 无法检测 Node 版本\" }\nelse {\n  Write-Host \"当前 Node: v$nodeVer\"\n  $nodeMajor = [int]($nodeVer -split '\\.')[0]\n  if ($nodeMajor -lt 22) { Write-Host \"⚠️ Node 主版本 $nodeMajor 低于 22，多数近期 OpenClaw 会拒绝启动\" }\n  else { Write-Host \"Node 主版本 $nodeMajor ✅（具体最低子版本见第一步核对）\" }\n}\nWrite-Host \"⚠️ 仅确认当前 Node 不够，必须第一步拿到目标版本 engines.node 后对比。\"\n\nWrite-Host \"\"\nWrite-Host \"=== registry 连通性 ===\"\n$reg = npm config get registry\nWrite-Host \"registry: $reg\"\ntry {\n  $r = Invoke-WebRequest -Uri $reg -UseBasicParsing -TimeoutSec 8 -Method Head\n  Write-Host \"连通 ✅ HTTP $($r.StatusCode)\"\n} catch { Write-Host \"⚠️ 访问 $reg 失败: $($_.Exception.Message)\" }\nWrite-Host \"HTTP_PROXY=[$env:HTTP_PROXY] HTTPS_PROXY=[$env:HTTPS_PROXY]（空=直连）\"\n\nWrite-Host \"\"\nWrite-Host \"=== 可选组件 ===\"\n$ll = Get-ChildItem \"$env:USERPROFILE\\.openclaw\\npm\\projects\" -Directory -ErrorAction SilentlyContinue |\n      Where-Object { $_.Name -like '*lossless-claw*' } | Select-Object -First 1\nif ($ll) {\n  $pkg = Get-Content \"$($ll.FullName)\\node_modules\\@martian-engineering\\lossless-claw\\package.json\" -Raw -ErrorAction SilentlyContinue | ConvertFrom-Json -ErrorAction SilentlyContinue\n  Write-Host \"lossless-claw: 已装 ver $($pkg.version)（项目 $($ll.Name)）\"\n} else { Write-Host \"lossless-claw: 未安装 ✅\" }\nWrite-Host \"消息通道: POPO (moltbot-popo)，无 feishu\"\n\nWrite-Host \"\"\nWrite-Host \"=== gateway 托管 ===\"\nschtasks /query /tn \"OpenClaw Gateway\" 2>$null | Select-String -Pattern \"任务名|正在运行|就绪|无法\"\nWrite-Host \"托管: Windows 任务计划程序（schtasks）\"\n\nWrite-Host \"\"\nWrite-Host \"=== 其他用户检测 ===\"\n$others = Get-ChildItem \"C:\\Users\" -Directory -ErrorAction SilentlyContinue |\n          Where-Object { $_.Name -ne $env:USERNAME -and (Test-Path \"$($_.FullName)\\.openclaw\") }\nif ($others) { Write-Host \"⚠️ 发"},{"language":"bash","snippet":"# === OpenClaw 环境（Linux） ===\necho \"用户: $(whoami)\"\necho \"Home: $HOME\"\nNPM_PREFIX=$(npm prefix -g 2>/dev/null || echo \"unknown\")\necho \"npm global: $NPM_PREFIX\"\n\necho \"\"\necho \"=== Node.js 版本 ===\"\nNODE_VER=$(node --version 2>/dev/null | sed 's/^v//')\necho \"当前 Node: v${NODE_VER:-未知}\"\nif [ -z \"$NODE_VER\" ]; then\n  echo \"⚠️ 无法检测 Node 版本\"\nelse\n  NODE_MAJOR=$(echo \"$NODE_VER\" | cut -d. -f1)\n  [ \"$NODE_MAJOR\" -lt 22 ] && echo \"⚠️ Node 主版本 ${NODE_MAJOR} 低于 22，多数近期 OpenClaw 会拒绝启动\" || echo \"Node 主版本 ${NODE_MAJOR} ✅\"\nfi\necho \"⚠️ 仅确认当前 Node 不够，必须第一步拿到目标版本 engines.node 后对比。\"\n\n# 代理检测\nif curl -s --connect-timeout 3 -x \"http://127.0.0.1:7890\" https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"--proxy http://127.0.0.1:7890\"; echo \"代理: 127.0.0.1:7890 ✅\"\nelif curl -s --connect-timeout 3 https://registry.npmjs.org/ > /dev/null 2>&1; then\n  PROXY_OPT=\"\"; echo \"代理: 直连 ✅\"\nelse\n  echo \"⚠️ npm 网络不通，请检查代理\"\nfi\n\n# IPv4/IPv6 速度探测（NAS 坑：IPv6 慢 6 倍会卡死 npm）\necho \"\"\necho \"=== registry IPv4/IPv6 速度探测 ===\"\nIPV4_TIME=$(timeout 5 curl -4 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\nIPV6_TIME=$(timeout 5 curl -6 -s -o /dev/null -w '%{time_total}' https://registry.npmjs.org/ 2>/dev/null)\necho \"IPv4: ${IPV4_TIME:-超时/不可用}s\"\necho \"IPv6: ${IPV6_TIME:-超时/不可用}s\"\nif [ -z \"$IPV6_TIME\" ]; then\n  echo \"IPv6 不可用/超时，建议升级/安装步骤强制 --force-ipv4 兜底\"\nelif python3 -c \"exit(0 if float('$IPV6_TIME') > float('${IPV4_TIME:-999}') * 2 else 1)\" 2>/dev/null; then\n  echo \"⚠️ IPv6 明显慢于 IPv4（超2倍），建议 export NODE_OPTIONS=\\\"--dns-result-order=ipv4first\\\" 后再 npm install\"\nelse\n  echo \"IPv4/IPv6 速度接近 ✅\"\nfi\n\n# 可选组件\nHAS_LOSSLESS=false\n[ -d \"$HOME/.openclaw/extensions/lossless-claw\" ] && HAS_LOSSLESS=true\necho \"lossless-claw: $HAS_LOSSLESS\"\n\nOVERRIDE=\"$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf\"\necho \"override.conf: $([ -f \"$OVERRIDE\" ] && echo 存在 || echo 不存在)\"\n\necho \"服务管理: systemd --user\"\n\n# /tmp/jiti 权限（codex EACCES 坑）\nif [ -d \"/tmp/jiti\" ]; then\n  JITI_PERM=$(stat -c \"%a\" /t"},{"language":"powershell","snippet":"# [Windows] PowerShell\n$cur = openclaw --version 2>$null\n$target = npm view openclaw version\nWrite-Host \"当前: $cur\"\nWrite-Host \"最新: $target\"\nnpm view \"openclaw@$target\" engines.node\nopenclaw update status\nopenclaw update --dry-run --tag $target"},{"language":"bash","snippet":"curl -s -H \"Authorization: token $GITHUB_TOKEN\" \\"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: \"openclaw-upgrade\"\ndescription: \"OpenClaw版本升级标准流程。每次说\\\"升级openclaw\\\"、\\\"openclaw升级\\\"、\\\"更新openclaw\\\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案\"\n---\n\n# OpenClaw 升级技能（环境自适应版）\n\n每次升级 OpenClaw 都必须严格按此流程执行，不能省步骤。\n\n> 本版把 Linux 原版（systemd/bash）与 Windows 适配版（schtasks/PowerShell）合并为一个技能：第零步先探测环境并分类，之后每步按 `[Windows]` / `[Linux]` 分支走。只维护一份，不再靠两份文件。\n\n## Changelog\n\n> description 字段只写触发场景，不写变更记录；每次改动的原因/教训记在这里。\n\n- 2026-08-13（实测事故）：`openclaw update`（A 方案）在 Windows 上实测失败——它内部是「先装后停」（Linux 模式），撞 DLL 锁定；且停 gateway 时把自身（gateway 子进程）一起杀死，npm install 根本没执行，gateway 宕机 3.5 小时无人拉起。教训：Windows 主入口改为「分离式 schtasks 一次性任务」，`openclaw update` 在 Windows 上禁用。\n- 2026-08-13：合并 Linux 原版 + Windows 适配版为「环境自适应版」。第零步升级为「环境探测 + 分类」（判定 OS 类型 + 服务托管方式），后续每步给出 `[Windows]`/`[Linux]` 双分支。Windows 分支保留 DLL 锁定 + 自杀陷阱两个硬坑（主入口 `openclaw update --tag`），Linux 分支保留原「先装后停」流程。原两个文件已归档到 `SKILL.linux-original.bak.md`（此版之前的 Windows 版内容见 git/历史）。\n- 2026-08-13：Windows 适配。本机（SCRIPT-S03-04，Windows Server 2016）实测：gateway 由 Windows 任务计划程序（schtasks）托管而非 systemd；gateway 进程加载了 node-pty-win32-x64 / tree-sitter 等原生 .node DLL，Windows 锁定运行中 DLL → 运行时直接 `npm install -g openclaw` 会 EBUSY/EPERM 失败；agent 运行在 gateway 进程内部不能自己 stop 自己。故 Windows 主入口改为 `openclaw update --tag <版本>`，裸 npm install 降级为分离式 schtasks 任务兜底。同时适配：npm registry=npmmirror（无代理）、无 curl.exe（Server 2016）改用 Invoke-WebRequest、.env 无 GITHUB_TOKEN、lossless-claw 是 npm 项目路径、消息通道 POPO 无 feishu。\n- 上次（4.14版本）因为没检查 lossless-claw 兼容性踩过坑\n- 上次升级后忘记发完成通知，爸比等了7小时不知道结果\n- 2026-07-27：NAS欢欢用自写脚本升级，脚本从gateway进程内部nohup启动，第一步systemctl stop把整个进程组一起杀掉，脚本自己被杀死，npm install根本没跑起来，gateway停了近6小时无人察觉——本skill的流程设计（npm install前不停服务、重启只在最后单独一步、重启前先设好通知cron）天然规避了这个坑，但重启这一步本身如果裸调systemctl也仍有被自身进程树波及的理论风险，已在第八步/回滚方案中改为优先走平台 gateway 工具\n- 2026-07-27（同一事故的第二个坑）：NAS欢欢手动拉起gateway后agent恢复中断会话继续把npm包升到2026.7.1-2，但机器Node还是22.22.1，openclaw 2026.7.1-2要求Node≥22.22.3，gateway直接拒绝启动；且该NAS访问registry.npmjs.org走IPv6比IPv4慢6倍，codex插件依赖安装卡在慢速IPv6上4分半——第零步此前没查Node版本、没做IPv4/IPv6测速，两个真实缺口已补入\n- 2026-07-27（第三个坑，元问题）：description字段被写成changelog摘要，覆盖了触发关键词，导致agent在用户说\"升级openclaw\"时语义匹配不上这个skill。教训：description只写\"什么场景触发\"，绝不写\"这次改了什么\"；changelog一律写在本节。\n\n---\n\n## 环境分类路由表（探测后对照，一眼定位走哪个分支）\n\n| 维度 | [Windows] 分支 | [Linux] 分支 |\n|------|----------------|--------------|\n| 判定 | `$env:OS` = `Windows_NT`（PowerShell） | `uname -s` = `Linux`（bash） |\n| Shell | PowerShell / cmd | bash |\n| Gateway 托管 | 任务计划程序「OpenClaw Gateway」（schtasks） | `systemd --user`（`openclaw-gateway.service`） |\n| 原生 DLL 锁定 | ❗**有**（node-pty-win32-x64、tree-sitter）→ 运行中 `npm install -g` 必 EBUSY | 无（inode 替换，可运行中覆盖） |\n| **主升级入口** | **分离式 schtasks 一次性任务**（第六步 A） | `npm install -g openclaw@<版本>`（先装后停） |\n| 停服方式 | `gateway` 工具 / `schtasks /end`+`/run` | `gateway` 工具 / `systemctl --user restart` |\n| npm registry | npmmirror（无代理，无 IPv6 问题） | registry.npmjs.org（需代理检测 + IPv4/IPv6 测速） |\n| HTTP 探测工具 | `Invoke-WebRequest`（无 curl.exe） | `curl` |\n| 配置/凭证路径 | `$env:USERPROFILE\\.openclaw\\...` | `~/.openclaw/...` |\n| 启动脚本/override | `gateway.cmd` | `override.conf`（system"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn79f0shgp6jenfxa0cfqgm25x82m4bq\",\n  \"slug\": \"oc-upgrade\",\n  \"version\": \"1.9.1\",\n  \"publishedAt\": 1786610030197\n}"},{"path":"skill-card.md","content":"## Description:\n\nOpenClaw upgrade procedure that guides an agent through environment detection, Windows schtasks or Linux systemd upgrade paths, backup, verification, gateway restart, and rollback.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tangsuann](https://clawhub.ai/user/tangsuann)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use this skill to perform OpenClaw version upgrades with platform-specific checks for Windows scheduled tasks and Linux systemd environments. It helps sequence compatibility checks, backups, installation, validation, restart, notification, and rollback steps.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can replace a global OpenClaw package, restart the gateway, inspect local account layout, and create temporary scheduled execution artifacts.\n\nMitigation: Use it only in environments where those operations are acceptable, and review the planned commands before execution.\n\nRisk: Target version, package registry, and Node.js compatibility issues can leave the gateway unavailable after upgrade.\n\nMitigation: Pin and verify the target OpenClaw version, registry, and required Node.js engine before installing, then run the documented validation checks before considering the upgrade complete.\n\nRisk: The Windows upgrade path includes a hard-coded user path and temporary scheduled task/script artifacts.\n\nMitigation: Replace the hard-coded path with the target user's actual OpenClaw path and remove the scheduled task and temporary script after the upgrade.\n\nRisk: Backup files may include .env secrets, and broad permission changes such as chmod 1777 can widen exposure.\n\nMitigation: Protect or remove .env backups after rollback risk has passed, and avoid broad permission changes unless they are explicitly required and reviewed.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/tangsuann/skills/oc-upgrade)\n- [Publisher profile](https://clawhub.ai/user/tangsuann)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline shell and PowerShell command blocks]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Includes platform-specific operational steps, validation criteria, and rollback guidance.]\n\n## Skill Version(s):\n\n1.9.1 (source: server-resolved release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"OpenClaw版本升级标准流程。每次说\"升级openclaw\"、\"openclaw升级\"、\"更新openclaw\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案 Skill: openclaw-upgrade Owner: tangsuann Summary: OpenClaw版本升级标准流程。每次说\"升级openclaw\"、\"openclaw升级\"、\"更新openclaw\"时必须执行，先做环境探测+分类，再按Windows/schtasks或Linux/systemd分支走对应升级方案 Tags: latest:1.9.1 Version history: v1.9.1 | 2026-08-13T08:33:50.197Z | user Windows 升级主入口改为分离式 schtasks 一次性任务；openclaw update 标记为已实测失败（DLL 锁定 + 自杀陷阱，2026-08-13 实测导致 gateway 宕机 3.5h）；失败教训写入 changelog v1.9.0 | 2026-08-13T02:51:13.841Z | user 环境自适应版：合并 Win","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1035,"uniquenessScore":48,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T08:38:03.677Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T08:38:03.677Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T10:44:40.574Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}