ClawdBot故障排查：Gateway not reachable错误定位与修复

ClawdBot故障排查：Gateway not reachable错误定位与修复

1. 问题现象与核心定位

你刚部署好ClawdBot，满怀期待地打开控制台，却在终端里看到这样一行报错：

Gateway not reachable: Error: gateway closed (1006 abnormal closure (no close frame)): no close reason Gateway target: ws://127.0.0.1:18780 

紧接着，clawdbot channels status --probe 命令返回的不是健康状态，而是一片沉默的“Config-only status”——这意味着你的ClawdBot后端网关根本没跑起来，所有通道（Telegram、Web UI、API）都处于断联状态。

这不是配置写错了，也不是Token填漏了，而是网关服务本身没有成功启动或意外崩溃。它就像一栋大楼的总电闸没合上，再漂亮的装修、再齐全的家具，也亮不了灯、开不了门。

这个 Gateway not reachable 错误，是ClawdBot运行中最典型、也最容易被误判的“假性配置失败”。很多人会反复检查 clawdbot.json 里的 botToken、proxy 或模型地址，却忽略了最基础的一环：网关进程是否真实存活？

我们接下来要做的，不是改配置，而是像一位系统医生一样，先确认“心跳”，再查“血压”，最后看“器官功能”。

2. 网关服务状态诊断三步法

2.1 第一步：确认网关进程是否在运行

ClawdBot 的网关（Gateway）是一个独立的后台服务进程，监听 ws://127.0.0.1:18780。它不依赖于Web UI或CLI命令的调用，而是随整个应用启动时自动拉起。

执行以下命令，查看是否有 clawdbot-gateway 进程：

ps aux | grep clawdbot-gateway | grep -v grep 

如果没有任何输出，说明网关根本没启动。这通常发生在：

• 应用首次启动未完成初始化（比如设备配对卡住）
• 后台服务因内存不足被系统 OOM Killer 杀掉
• Docker 容器内未以 --init 模式运行，导致子进程无法正确回收

快速验证：直接手动启动网关（仅用于诊断，非长期方案）：

clawdbot gateway start 

然后立刻再执行 ps aux | grep clawdbot-gateway，应该能看到类似这样的输出：

work 12345 0.2 3.1 2456789 123456 ? S 10:22 0:02 /usr/bin/clawdbot-gateway --port 18780 --config /app/clawdbot.json 

如果此时 clawdbot channels status --probe 仍报错，说明网关虽在运行，但内部初始化失败——进入第二步。

2.2 第二步：检查网关日志中的致命错误

网关启动失败，90% 的原因藏在它的日志里。ClawdBot 默认将网关日志输出到标准错误流，可通过以下方式捕获：

# 如果你用的是 docker run 方式启动 docker logs <container_name_or_id> 2>&1 | grep -A 5 -B 5 "gateway\|error\|failed\|panic" # 如果是本地直接运行 journalctl -u clawdbot --since "1 hour ago" | grep -i "gateway\|error" 

重点关注以下几类高频错误：

实操建议：临时修改 clawdbot.json，将网关日志级别调高，便于定位：

{ "logging": { "level": "debug", "gateway": { "level": "trace" } } } 

然后重启网关：clawdbot gateway restart，再查日志。

2.3 第三步：验证 vLLM 后端连通性（关键！）

ClawdBot 网关本身不运行模型，它只是一个智能代理，把请求转发给真正的推理引擎——vLLM。Gateway not reachable 的深层原因，往往是 vLLM 服务不可用，导致网关在启动阶段就自我终止。

请严格按顺序验证：

检查 vLLM 是否正在运行

# 查看 vLLM 进程（默认监听 8000 端口） ps aux | grep "vllm.entrypoints.api_server" | grep -v grep # 或直接 curl 测试（需安装 curl） curl -s http://localhost:8000/health | jq . # 正常应返回 {"status":"ok"} 

如果返回 curl: (7) Failed to connect to localhost port 8000: Connection refused，说明 vLLM 根本没起来。

检查 vLLM 启动命令是否正确

ClawdBot 文档推荐的 vLLM 启动命令是：

python -m vllm.entrypoints.api_server \ --model Qwen3-4B-Instruct-2507 \ --host 0.0.0.0 \ --port 8000 \ --api-key sk-local \ --enable-auto-tool-choice 

注意两个易错点：

• --host 0.0.0.0（不是 127.0.0.1）：Docker 容器内 localhost 指向容器自身，ClawdBot 需要能从容器内访问到 vLLM，必须绑定到 0.0.0.0
• --api-key sk-local：必须与 clawdbot.json 中 "apiKey": "sk-local" 完全一致，大小写敏感

检查网络连通性（Docker 场景必做）

如果你用 Docker 部署，ClawdBot 和 vLLM 很可能在不同容器中。此时 http://localhost:8000 在 ClawdBot 容器里根本不通。

正确做法是：

• 使用 Docker 自定义网络，让两容器通过服务名通信
• 修改 clawdbot.json 中的 baseUrl 为 http://vllm-service:8000/v1（假设你的 vLLM 容器名为 vllm-service）
• 在 docker-compose.yml 中确保两者共用同一网络

# docker-compose.yml 片段 services: clawdbot: # ... 其他配置 depends_on: - vllm-service networks: - ai-net vllm-service: image: vllm/vllm-openai:latest # ... 启动参数 networks: - ai-net 

3. 设备配对阻塞：被忽略的“第一道门”

即使网关和 vLLM 都正常，你依然可能看到 Gateway not reachable。这是因为 ClawdBot 有一个安全机制：所有新设备首次访问 Web 控制台前，必须完成人工审批。这个审批流程会阻塞整个网关的初始化。

你执行 clawdbot devices list 后看到 pending 请求，就是这个原因。

3.1 为什么设备配对会阻塞网关？

ClawdBot 的设计哲学是“零信任”。当它检测到一个从未见过的 IP（比如你第一次用浏览器打开 http://localhost:7860），它不会直接放行，而是：

• 暂停网关的完整初始化
• 将该连接挂起，等待管理员在 CLI 中显式批准
• 此期间，ws://127.0.0.1:18780 会返回 1006 异常关闭，因为网关尚未进入“可服务”状态

3.2 如何确认是设备配对问题？

执行这条命令：

clawdbot devices list --pending 

如果输出类似：

ID: 7f8a2b1c-d3e4-5f6a-8b9c-0d1e2f3a4b5c IP: 192.168.1.100 User Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36... Status: pending 

那么答案就明确了：先批准设备，再查网关。

3.3 一键批准并重启网关

# 批准所有 pending 设备（生产环境慎用，此处为快速恢复） clawdbot devices approve --all # 或批准指定 ID clawdbot devices approve 7f8a2b1c-d3e4-5f6a-8b9c-0d1e2f3a4b5c # 强制重启网关，加载新状态 clawdbot gateway restart 

完成后，立刻执行 clawdbot channels status --probe，你应该看到：

✓ Gateway reachable: ws://127.0.0.1:18780 (latency: 12ms) ✓ Telegram: enabled, configured, mode:polling, token:*** (valid) 

4. 配置文件深度校验：JSON 结构与字段语义

很多用户以为改了 clawdbot.json 就万事大吉，却忽略了 JSON 的两个隐形杀手：格式合法但语义错误。

4.1 必须存在的顶层字段

ClawdBot 启动时会校验 clawdbot.json 是否包含以下字段，缺一不可：

{ "agents": { ... }, // 不能为空对象 "models": { ... }, // 必须有 "mode" 和 "providers" "channels": { ... }, // 即使全 disabled，也必须存在 "logging": { ... } // 推荐显式声明，避免默认行为异常 } 

❌ 常见错误：删除了 "channels": {}，认为“我不用 Telegram 就删掉它”，结果网关启动时直接 panic。

4.2 models.providers 的精确写法

这是 Gateway not reachable 最隐蔽的诱因。请严格对照以下结构：

{ "models": { "mode": "merge", "providers": { "vllm": { "baseUrl": "http://vllm-service:8000/v1", // 末尾必须有 /v1 "apiKey": "sk-local", // 必须与 vLLM 启动参数一致 "api": "openai-responses", // 固定值，不能写 openai 或 vllm "models": [ { "id": "Qwen3-4B-Instruct-2507", // id 必须与 vLLM 加载的模型名完全一致 "name": "Qwen3-4B-Instruct-2507" } ] } } } } 

高频错误：

• baseUrl 写成 http://localhost:8000 → 容器内不通
• id 写成 vllm/Qwen3-4B-Instruct-2507 → vLLM 不认带前缀的 ID
• api 写成 "openai" → ClawdBot 会尝试调用 OpenAI 官方 API，而非本地 vLLM

4.3 用工具自动校验配置

别靠肉眼检查。用内置命令一键验证：

# 检查配置语法是否合法（JSON 格式） clawdbot config validate --syntax # 检查配置语义是否完整（字段、类型、依赖） clawdbot config validate --semantic # 输出当前生效的完整配置（含默认值），用于比对 clawdbot config show --resolved 

如果 --semantic 报错，它会明确告诉你哪一行、哪个字段缺失或类型错误，比读日志高效十倍。

5. 终极修复清单：5 分钟闭环操作

当你被 Gateway not reachable 卡住时，按此清单逐项执行，无需思考，5 分钟内必解：

执行完第⑤步，95% 的问题已解决。如果仍未恢复，请复制第⑥步的最后 20 行日志，重点查找 FATAL、PANIC、CRITICAL 字样——那才是真正的病因。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 ZEEKLOG星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。