OpenClaw 故障排除指南

状态和诊断

快速分类命令（按顺序）：

命令	说明	何时使用
`openclaw status`	本地摘要：OS + 更新、网关可访问性/模式、服务、代理/会话、提供者配置状态	第一次检查，快速概览
`openclaw status --all`	完整本地诊断（只读，可粘贴，安全）包括日志尾部	需要分享调试报告时
`openclaw status --deep`	运行网关健康检查（包括提供者探测；需要可访问的网关）	“已配置”不意味着”正在工作”时
`openclaw gateway probe`	网关发现 + 可访问性（本地 + 远程目标）	怀疑您正在探测错误的网关时
`openclaw channels status --probe`	询问运行中的网关频道状态（并可选探测）	网关可访问但频道行为异常时
`openclaw gateway status`	监督者状态（launchd/systemd/schtasks）、运行时 PID/退出、最后的网关错误	服务”看起来已加载”但没有任何运行时
`openclaw logs --follow`	实时日志（运行时问题的最佳信号）	需要实际失败原因时

常见问题

找不到提供者 “anthropic” 的 API 密钥

这意味着代理的认证存储为空或缺少 Anthropic 凭据。

修复选项：

重新运行引导并为该代理选择 Anthropic

或在网关主机上粘贴设置令牌：

openclaw models auth setup-token --provider anthropic

或从主代理目录复制 auth-profiles.json 到新代理目录

验证：

openclaw models status

OAuth 令牌刷新失败

这意味着存储的 OAuth 令牌过期且刷新失败。

推荐修复（设置令牌）：

# 在网关主机上运行（粘贴设置令牌）
openclaw models auth setup-token --provider anthropic
openclaw models status

控制 UI 在 HTTP 上失败

如果您通过纯 HTTP 打开仪表板，浏览器在非安全上下文中运行并阻止 WebCrypto，因此无法生成设备身份。

修复：

首选通过 Tailscale Serve 使用 HTTPS
或在网关主机上本地打开: http://127.0.0.1:18789/
如果必须保持在 HTTP 上，启用 gateway.controlUi.allowInsecureAuth: true 并使用网关令牌（仅令牌；无设备身份/配对）

服务已安装但没有任何运行

如果网关服务已安装但进程立即退出，服务可以”已加载”而没有任何运行。

检查：

openclaw gateway status
openclaw doctor

日志：

首选: openclaw logs --follow
文件日志: /tmp/openclaw/openclaw-YYYY-MM-DD.log
macOS LaunchAgent: $OPENCLAW_STATE_DIR/logs/gateway.log
Linux systemd: journalctl --user -u openclaw-gateway

“Gateway 启动被阻止：设置 gateway.mode=local”

这意味着配置存在但 gateway.mode 未设置（或不是 local），因此 Gateway 拒绝启动。

修复（推荐）：

# 运行向导并将 Gateway 运行模式设置为 Local
openclaw configure

# 或直接设置

openclaw config set gateway.mode local

地址已被使用（端口 18789）

这意味着某些东西已经在监听网关端口。

检查：

openclaw gateway status

WhatsApp 断开连接


# 检查本地状态（凭据、会话、排队事件）
openclaw status

# 探测运行中的网关 + 频道（WA 连接 + Telegram + Discord API）
openclaw status --deep

# 查看最近的连接事件
openclaw logs --limit 200 | grep "connection\|disconnect\|logout"

修复: 通常一旦 Gateway 运行就会自动重新连接。如果卡住，重启 Gateway 进程，或带详细输出手动运行：

openclaw gateway --verbose

如果已注销/未关联：

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials"
openclaw channels login --verbose

代理超时

默认超时为 30 分钟。对于长时间任务：

{
  "reply": {
    "timeoutSeconds": 3600
  }
}

或使用 process 工具后台运行长时间命令。

调试模式

获取详细日志记录：

# 在配置中开启跟踪日志记录
# 然后运行详细命令将调试输出镜像到 stdout
openclaw gateway --verbose
openclaw channels login --verbose

日志位置

日志	位置
Gateway 文件日志	`/tmp/openclaw/openclaw-YYYY-MM-DD.log`
macOS LaunchAgent	`~/.openclaw/logs/gateway.log`
Linux systemd	`journalctl --user -u openclaw-gateway`
会话文件	`~/.openclaw/agents/<agentId>/sessions/`
媒体缓存	`~/.openclaw/media/`
凭据	`~/.openclaw/credentials/`

完全重置

核选项：

openclaw gateway stop
openclaw gateway uninstall  # 如需要

trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login     # 重新配对 WhatsApp
openclaw gateway restart

⚠️ 这将丢失所有会话并需要重新配对 WhatsApp。

来源: https://docs.openclaw.ai/gateway/troubleshooting

作者：十一张创建时间：2026-03-08 22:36
最后编辑：十一张更新时间：2026-03-28 11:57

01-故障排除指南