排错手册

OpenClaw 常见报错排查 — 超时、代理、MCP、连接失败完整指南

这是一份按错误类型组织的 OpenClaw 中文排错手册，覆盖 MCP 超时、Gemini 调用超时、模型连不上、容器无限重启、代理生效失败等高频问题。每一条都给出可直接执行的修复步骤。

排错前的基本动作

看日志：docker logs openclaw --tail 200 — 80% 的问题在日志里直接写明
看健康检查：docker ps | grep openclaw — 确认状态是 Up 而不是 Restarting
进容器：docker exec -it openclaw sh — 在容器内 ping、curl 测网络
验配置：docker exec openclaw cat /home/node/.openclaw/openclaw.json

1. MCP 超时设置（mcp 调用超时）

MCP Server 默认调用超时是 30 秒，Tavily 搜索、Playwright 抓页面这类工具经常会超过。在 tools.mcp 配置里给单个 MCP 加 timeoutMs：

{
  "tools": {
    "mcp": [
      {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-tavily"],
        "env": { "TAVILY_API_KEY": "tvly-..." },
        "timeoutMs": 60000,
        "startupTimeoutMs": 20000
      }
    ]
  }
}

timeoutMs — 单次工具调用超时（默认 30000）
startupTimeoutMs — MCP Server 启动超时，npx 第一次拉包慢就调大它（默认 10000）

修改后 docker restart openclaw 才生效。详见 MCP 配置指南。

2. 开了代理还是连不上 Gemini / Claude

典型现象：宿主机能 ping 通 google.com，容器里却报 ETIMEDOUT。三个最常见原因：

没设 HTTPS_PROXY — 只设 HTTP_PROXY 对 https 请求无效，必须同时设置 HTTPS_PROXY
代理在宿主机 127.0.0.1 — 容器里访问宿主机要用 host.docker.internal（Linux 需要加 --add-host=host.docker.internal:host-gateway）
代理未允许 LAN — Clash / Surge 默认只监听 127.0.0.1，需要打开「Allow LAN」让容器 IP 能访问

正确示例（容器跑在 Docker bridge，代理跑在宿主机 7890）：

docker run -d \
  -e HTTP_PROXY=http://host.docker.internal:7890 \
  -e HTTPS_PROXY=http://host.docker.internal:7890 \
  -e NO_PROXY=localhost,127.0.0.1,*.openclaw.local \
  --add-host=host.docker.internal:host-gateway \
  ...

详见代理设置教程中的「容器代理」一节。

3. ENOTFOUND xxx.com

DNS 解析失败。两种修法：

给 docker run 加 --dns 8.8.8.8 --dns 223.5.5.5
编辑 /etc/docker/daemon.json 加 "dns": ["8.8.8.8", "223.5.5.5"]，重启 Docker 服务

4. ECONNRESET / socket hang up

连接被中间设备主动 reset，常见于走 GFW、走某些公司网关。修法按优先级：

换代理节点（机房 IP 命中率高，住宅 IP 更稳）
给所有 fetch 加自动重试："network": { "retries": 3, "retryDelayMs": 2000 }
切到国内可直连的模型（DeepSeek、Qwen），见替代模型方案

5. 429 Too Many Requests

触发了模型 provider 的限流。三种情况分别处理：

免费额度耗尽（如 Gemini 免费 OAuth）— 升级付费 tier 或换 provider
并发过高 — 在 OpenClaw 里减少 multi-agent 并发数
账号被风控 — 暂停几小时再试，或换账号

注意：付费订阅用户不要配 fallback 数组（参见订阅说明），让付费模型直接报 429 比静默 fallback 到便宜模型更可控。

6. 容器无限重启（restart loop）

docker ps 显示 STATUS 一直是 Restarting。排查顺序：

docker logs openclaw --tail 100 看启动报错
常见原因 1：openclaw.json 配置 JSON 语法错误 → 进容器 cat openclaw.json | jq . 验证
常见原因 2：端口 3210 被占用 → 改成 -p 3211:3210
常见原因 3：volume 挂载目录权限不对 → chown -R 1000:1000 /your/data/dir
常见原因 4：内存不够（OOM）→ docker stats 看占用，给容器加 --memory=2g

7. 模型连不上 / no provider configured

检查 models.providers.X.apiKey 是否填了
检查 models.default 的 ID 是否带正确前缀（openrouter/anthropic/claude-sonnet-4.6 不是 anthropic/...）
看启动日志中有没有 X provider ready 一行 — 没出现说明 provider 没加载
用 curl 直接测 provider：curl -H "Authorization: Bearer $KEY" https://api.deepseek.com/v1/models

8. WeChat / Telegram 收不到消息

检查 channels.X.enabled = true 同时 plugins.entries.X.enabled = true — 两个开关都要
Telegram dmPolicy 必须是 pairing 或 open，pairing 要求 ~/.openclaw/credentials/ 目录存在（不存在的话 Telegram 会静默丢消息）
dmPolicy: "open" 必须配 allowFrom: ["*"]，否则配置校验失败
看日志关键字：docker logs openclaw 2>&1 | grep -i telegram

9. 升级镜像后配置丢了

通常是没把 ~/.openclaw 挂载成 volume。正确做法：

docker run -d \
  -v /opt/openclaw/data:/home/node/.openclaw \
  ghcr.io/openclaw/openclaw:2026.4.14

这样 docker rm + 升级镜像 + 重新 docker run 配置全部保留。

10. 不知道是哪一层的问题？

按这个顺序排查能定位 95% 的问题：

宿主机能 ping 通目标域名吗？
容器里能 ping 通吗？（docker exec openclaw ping api.openai.com）
容器里能 curl 通吗？（带 HTTPS_PROXY 环境变量）
OpenClaw 启动日志里 provider 加载成功了吗？
用 OpenClaw 的 chat playground 直接测模型，绕过所有 channel
能用 playground，channel 收不到 → channel 配置问题

上面 10 类问题覆盖了 OpenClaw 90%+ 的报错。还有解决不了的，建议直接换托管版 — OpenClaw Launch 把代理、模型、配置、健康检查都帮你处理好。