故障卡片

Gateway 宕机：消息不投递，status 无响应

典型表现
Gateway 进程崩溃或被杀，systemd 未自动拉起
判断标准
解决方向
检查进程 → 检查端口 → 查日志 → 强制重启。systemctl --user status openclaw-gateway.service 确认进程状态，ss -tlnp | grep 18789 确认端口。最后 systemctl --user restart openclaw-gateway.service

Provider 进入 cooldown 状态

典型表现
正常 rate limit 触发，Provider 被暂时标记为不可用
判断标准
解决方向
等几分钟。cooldown 是正常行为，不是故障。用 openclaw status --json 检查 unusableProfiles，确认 cooldown 时间。不要反复重启，重启不会清除 cooldown 计时器。

HTTP 200 返回但实际失败

典型表现
部分公益站点认证失效后仍返回 HTTP 200，body 里带错误信息
判断标准
解决方向
HTTP 状态码不可信。用 ./manage.sh errors 做站点探活，检查响应 body 内容。黑名单及时更新：./manage.sh blacklist add "站点名"

supervised 错误

典型表现
systemd 托管和手动启动同时存在，两套进程抢端口或资源
判断标准
解决方向
先杀掉手动启动的进程，再用 systemd 统一管理。ps aux | grep cliproxy 找残留进程，kill <pid> 清理。选一种方式，不要混用。

配置改了不生效

典型表现
没重启 Gateway。Gateway 启动时缓存配置到内存，运行期间不热加载
判断标准
解决方向
systemctl --user restart openclaw-gateway.service。没有例外，没有捷径。改完配置重启是唯一让配置生效的方式。

Provider 注册了两道门

典型表现
OpenClaw 有两道注册关卡：providers.models（全局注册）+ agents.defaults.models（白名单）
判断标准
解决方向
两道都过了才能用模型。providers.models 在全局 openclaw.json 声明，agents.defaults.models 在 agent 级别配置。两处都要写，缺一不可。

远端 IP 被限流（本地同 Key 可用）

典型表现
部分 provider 的 rate limit 是 IP 级别，不是 Key 级别。远端 VPS 的 IP 被限流，本地同 Key 不受影响
判断标准
解决方向
确认是 IP 限流后：切换到其他 provider、等 cooldown 结束、或用 foxcode 等独立 rate limit 的直连 provider。

OAuth Token 过期

典型表现
openai-codex OAuth token 从本地复制到远端，token 有过期时间
判断标准
解决方向
从本地 ~/.openclaw/agents/main/agent/auth-profiles.json 复制 openai-codex:default 到远端同路径。放进 crontab 定期同步，不要等过期了再处理。

排查流程

# 一键诊断（按顺序跑）
# 1. Gateway 状态
systemctl --user status openclaw-gateway.service --no-pager

# 2. OpenClaw 状态
openclaw status --json

# 3. 日志
openclaw logs --limit 200 --plain --local-time

# 4. 站点探活
./manage.sh errors

# 5. 端口检查
ss -tlnp | grep 18789

# 6. 万能重启
systemctl --user restart openclaw-gateway.service

高频踩坑 Top 3

改完配置没重启 Gateway —— 占所有故障报告的 40%。

HTTP 200 不代表成功 —— 公益站的坑，浪费了 3 个小时 排查。

Provider 两道注册门 —— providers.models 和 agents.defaults.models 都要写，漏一个 静默失败不报错。