OpenClaw 网关运维总入口

本机（Windows + Git Bash）OpenClaw 网关的排障与恢复。先读第 1 节做分诊，再按需打开对应 references 分册，不要一次读全部。

1. 症状分诊表（第一步永远看这里）

2. 三条铁律（违反任一条，后面全是白干）

铁律一：网关必须跑在沙箱外。
从 WorkBuddy Bash 工具（含 run_in_background）拉起的网关会继承沙箱限制，表现为 health 正常但全面带病：EPERM: open AGENTS.md、attempt to write a readonly database、模型请求 network connection error（还会被误记为 billing 熔断）。
唯一可靠常驻手段 = Windows 计划任务（拉起后进程 ppid=1，脱离一切会话）。详见 references/lifecycle.md。

铁律二：换模型/换 provider 必须查三层，少一层就复发。
① 全局 openclaw.json → agents.defaults.model.primary/fallbacks
② 会话 agents/main/sessions/sessions.json 的 model / modelProvider / authProfileOverride
③ transcript sessions/<uuid>.jsonl 的 {"type":"model_change"} 事件
会话层会压过全局配置，而 cron 会话（agent:main:cron:<jobId>）最容易被钉死。详见 references/models-billing.md。

铁律三：cron agentTurn 对工具错误零容忍。
运行中任何一次 source=tool, severity=error（哪怕只是某个 curl exit 1）都会让整次 run 判定失败并丢弃已生成的正文、不投递。所以要保证 agent 全程零工具错误 —— 给足配套工具（exec 必须配 process），并在 prompt 里明令禁止容易失败的动作。详见 references/cron.md。

3. 标准恢复流程（网关整体死亡）

# 1) 确认死透了 + 死了多久
netstat -ano | grep LISTENING | grep -E ":18789|:18888|:18899"
ls -t /c/Users/Administrator/AppData/Local/Temp/openclaw/*.log | head -3   # 日志日期 = 死亡时间
tail -20 /c/Users/Administrator/AppData/Local/Temp/openclaw/gateway_wrapper.log   # 找 ^C

# 2) 查守护任务——State=Ready 不代表在干活！

Get-ScheduledTaskInfo -TaskName 'OpenClawGatewayGuard' | Select LastRunTime,LastTaskResult
# 0            = 正常
# 2147942402   = 0x80070002 可执行文件不存在 ← 最常见，见下
Start-ScheduledTask -TaskName 'OpenClawGatewayGuard'   # 立即重建全部服务

LastTaskResult = 2147942402 的经典成因：WorkBuddy 的 PortableGit 升级会删除旧版本目录，而任务动作硬编码了旧 versions/<old>/bin/bash.exe。修动作：

$act = New-ScheduledTaskAction -Execute 'D:\Program Files\新建文件夹\WorkBuddy\resources\vendor\PortableGit\bin\bash.exe' -Argument 'C:\Users\Administrator\.openclaw\gateway-guard.sh'
Set-ScheduledTask -TaskName 'OpenClawGatewayGuard' -Action $act
Start-ScheduledTask -TaskName 'OpenClawGatewayGuard'
Get-ScheduledTaskInfo -TaskName 'OpenClawGatewayGuard'   # 必须回到 0

> schtasks.exe 在本机黑名单里，但 PS 原生命令 Get/Set/Start-ScheduledTask 不走 schtasks.exe，沙箱不拦。

恢复验证记分卡：三端口 LISTENING → curl /health {"ok":true} → 日志 gateway ready + weixin monitor started → cron 会自动补偿漏掉的运行 → next_run 回归正常时刻。
一键检查：bash scripts/oc_health.sh

4. 会话写锁 / 上下文溢出

错误类型直接决定调参方向：

上下文窗口速查：deepseek-v4-flash/pro = 131072；kimi-k3 / k2.7-code-highspeed / k2.7-code / k2.6 = 256000。
补丁与重建流程：references/locks.md

5. cron 故障

先判断是哪一层失败：

node scripts/cron_status.js            # 最近 10 次 run + job 状态一览

改 cron 任务配置的唯一正确姿势：权威源是 sqlite state/openclaw.sqlite 的 cron_jobs 表（cron/jobs.json 是迁移残留，不要改）。改 payload_message 时必须同步改 job_json 里的嵌套副本，然后重启 gateway（内存调度器不热读 sqlite）。
测试触发：UPDATE cron_jobs SET next_run_at_ms = Date.now()+75000，然后重启。

全谱案例与判据：references/cron.md

6. 模型 / 计费

看到"候选数少于全局配置的 provider 数"就立刻怀疑会话覆盖 —— All models failed (2) 里的 2 是会话生效的候选数，不是全局候选数。

node scripts/check_model_pins.js       # 扫出所有被钉死在某个 provider 的会话

• 查余额：curl -s https://api.deepseek.com/user/balance -H "Authorization: Bearer <DK>"
• 凭据位置：agents/main/agent/openclaw-agent.sqlite → 表 auth_profile_store（store_key=primary，store_json.profiles.<provider>:manual）
• 熔断（cooldown）状态：同库 auth_profile_state → usageStats.<profile>.disabledUntil
• 清 provider 熔断 ≠ 清会话覆盖，两件事都要做（10/15→10/16 连续两天在同一坑复发过）

三层修复步骤与验证记分卡：references/models-billing.md

7. 微信投递

成功与失败的响应格式完全不同，写判定脚本时极易搞反：

ret=-2 的唯一根因 = context_token 陈旧（openclaw-weixin/accounts/<bot>.context-tokens.json 的 mtime 停更）。
解锁方式只有一种：用户主动在微信给 bot 发一条消息，上游才会下发新 token。ilink/bot/getconfig 返回的 typing_ticket 不能替代（实测仍 ret=-2）。

# 轮询等 token 刷新，检测到即自动补发
node scripts/send_weixin.js                      # 自动读最新 token + sync.json 的 userId
node scripts/send_weixin.js --watch --text-file briefing.txt

细节、sendmessage 协议字段、历史踩坑：references/weixin-delivery.md

8. 目录 / 端口速查

本机被安全策略拦掉的启动通道（别浪费时间试）：schtasks.exe、Start-Process、Invoke-CimMethod Win32_Process Create、wmic、reg.exe、explorer.exe <cmd>（2026-10 起失效）、沙箱内 nohup（调用结束即回收）。可用：PS 原生 *-ScheduledTask、run_in_background（仅过渡）。

9. 参考分册索引

10. 脚本索引

> 脚本里的 node 一律用绝对路径 C:/Users/Administrator/.workbuddy/binaries/node/versions/22.22.3/node.exe（PATH 里没有）。