ClawdBot调试指南：Gateway not reachable错误的5种排查与修复方法

ClawdBot调试指南：Gateway not reachable错误的5种排查与修复方法

ClawdBot 是一个你可以在自己设备上运行的个人 AI 助手，本应用使用 vLLM 提供后端模型能力。它不是云端服务，而是一个真正属于你的本地智能中枢——所有对话、推理、文件处理都在你自己的机器上完成，不上传任何数据，不依赖外部 API 密钥，也不受网络波动影响。但正因为它是本地部署、多进程协同、WebSocket 长连接驱动的架构，当出现 Gateway not reachable 错误时，问题往往藏在“看不见”的连接层、配置层或环境层中。

这个错误提示看似简单，实则像一扇门上的五把锁：可能钥匙没插对，可能门轴生锈了，可能门后根本没人应答，也可能你敲的是隔壁家的门。本文不讲抽象原理，不堆参数文档，而是基于真实部署场景（树莓派4、Ubuntu 22.04、Docker Compose 环境、国内网络），为你梳理出 5 种高频、可验证、有先后顺序的排查与修复路径。每一种都附带一句判断口诀、一条验证命令、一个修复动作，以及为什么这一步最值得先试。

1. 检查 Gateway 进程是否真正启动并监听端口

这是最基础也最容易被忽略的一环。很多用户执行 clawdbot start 后看到控制台输出“Starting gateway…”就以为万事大吉，但实际 gateway 进程可能因模型加载失败、端口被占、内存不足等原因静默退出，只留下一个空壳。

1.1 判断口诀

“看不到日志滚动，大概率没活；端口查不到监听，肯定没跑。”

1.2 验证命令

在终端中运行以下命令，检查 gateway 是否在监听默认端口 18780：

lsof -i :18780 # 或者（无 lsof 时） netstat -tuln | grep :18780 # 或者更直接地查看 gateway 进程是否存在 ps aux | grep gateway | grep -v grep 

如果没有任何输出，说明 gateway 进程未运行。

1.3 修复动作

手动启动 gateway 并观察实时日志：

clawdbot gateway start --verbose 

注意观察输出中是否有类似以下关键行：

• Gateway server started on ws://127.0.0.1:18780
• Loading model vllm/Qwen3-4B-Instruct-2507...
• ✔ Model loaded successfully in X.XX seconds

如果卡在“Loading model”或报错 OSError: CUDA out of memory，说明是模型加载失败（见第3条）；如果报错 Address already in use，说明端口被占（见第2条）。

1.4 补充说明

ClawdBot 的 gateway 是独立于 UI 和模型服务的通信枢纽。它不依赖 clawdbot dashboard 是否能打开，也不依赖 Telegram 通道是否启用。只要 gateway 没起来，整个系统就失去“神经中枢”，所有 status --probe 命令都会返回 Gateway not reachable。

2. 确认 18780 端口未被其他进程占用

ClawdBot 默认使用 18780 作为 WebSocket 网关端口。在国内常见环境中，该端口容易被 Docker 容器、旧版 Node.js 服务、甚至某些国产远程工具意外占用。

2.1 判断口诀

“启动报错 Address already in use，或者 lsof 显示陌生 PID，八成是端口撞车。”

2.2 验证命令

执行以下命令，找出谁占用了 18780：

sudo lsof -i :18780 # 输出示例： # COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME # docker-pr 1234 root 4u IPv4 56789 0t0 TCP *:18780 (LISTEN) 

2.3 修复动作

根据占用进程类型选择处理方式：

若想永久避免冲突：修改 gateway 端口（需同步更新配置）
编辑 /app/clawdbot.json，在顶层添加：

"gateway": { "port": 18781 } 

然后重启：clawdbot gateway restart

若是未知进程（如 python3、node）：直接 kill

sudo kill -9 1234 # 替换为实际 PID 

若是 docker-proxy 或 dockerd 占用：检查是否有旧容器在后台运行

docker ps -a | grep 18780 docker stop $(docker ps -q --filter "expose=18780" --format="{{.ID}}") 

2.4 补充说明

不要试图用 killall -9 python 这类粗暴命令——ClawdBot 自身也是 Python 进程，误杀会导致整个服务中断。精准定位 + 精准清理，才是稳定运维的第一课。

3. 验证 vLLM 模型服务是否就绪且可连通

ClawdBot 的 gateway 本身不执行推理，它只是把请求转发给后端的 vLLM 服务（默认地址 http://localhost:8000/v1）。如果 vLLM 没启动、启动失败、或地址配置错误，gateway 就会因无法建立上游连接而自我关闭，最终表现为 Gateway not reachable。

3.1 判断口诀

“clawdbot models list 能列出模型 ≠ vLLM 在线；能列出 ≠ 能响应；能响应 ≠ 地址配对。”

3.2 验证命令

分三步验证：

① 检查 vLLM 是否监听 8000 端口

curl -s http://localhost:8000/health | jq . 2>/dev/null || echo "❌ vLLM not responding" # 正常应返回 { "model": "Qwen3-4B-Instruct-2507", "version": "..." } 

② 检查 gateway 配置中的 baseUrl 是否匹配

jq '.models.providers.vllm.baseUrl' /app/clawdbot.json # 应输出 "http://localhost:8000/v1" 

③ 手动模拟 gateway 发起一次 OpenAI 兼容请求

curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-local" \ -d '{ "model": "Qwen3-4B-Instruct-2507", "messages": [{"role": "user", "content": "你好"}], "max_tokens": 32 }' | jq .choices[0].message.content 2>/dev/null 

若返回 "你好！" 或类似内容，说明 vLLM 通路完全正常；若超时或报错，则问题在 vLLM 层。

3.3 修复动作

常见原因及对策：

• 模型路径错误：确认 vllm/Qwen3-4B-Instruct-2507 已下载到 ~/.cache/huggingface/hub/ 下对应目录
• GPU 内存不足：树莓派4等设备需改用 CPU 模式，在启动 vLLM 时加参数 --device cpu
• vLLM 版本不兼容：ClawdBot 2026.1.x 要求 vLLM ≥ 0.6.3，执行 pip show vllm 验证

推荐一键重拉 vLLM 服务（假设你用 Docker）：

docker run -d \ --gpus all \ -p 8000:8000 \ --name vllm-server \ -v ~/.cache/huggingface:/root/.cache/huggingface \ ghcr.io/vllm-project/vllm:v0.6.3 \ --model Qwen3-4B-Instruct-2507 \ --host 0.0.0.0 \ --port 8000 \ --api-key sk-local 

3.4 补充说明

很多用户卡在这一步却误以为是 gateway 问题。记住：Gateway not reachable 是结果，不是根因。gateway 只是“信使”，信使找不到收件人（vLLM），就会原地解散。

4. 核查设备配对状态与 Token 有效性

ClawdBot 的 Web UI（Dashboard）和 CLI 命令通过 WebSocket 连接 gateway，而该连接受设备配对机制保护。如果你从未执行过 clawdbot devices approve，或批准后 token 过期/被清空，gateway 会主动拒绝连接，返回 abnormal closure (1006)。

4.1 判断口诀

“UI 打不开 + clawdbot devices list 显示 pending，就是配对没过门。”

4.2 验证命令

执行设备列表命令，观察输出：

clawdbot devices list 

典型输出：

ID Status Last Seen IP User Agent abc123... pending 2026-01-24 10:22 192.168.1.100 Mozilla/5.0... 

若状态为 pending，说明该设备尚未被授权，gateway 会直接断开其 WebSocket 连接。

4.3 修复动作

批准待处理设备（ID 可从上条命令复制）：

clawdbot devices approve abc123... # 成功后会显示： Device abc123... approved 

批准后，必须重启 gateway 才能使新设备生效：

clawdbot gateway restart 

4.4 补充说明

这个机制是 ClawdBot 的安全设计，防止未授权设备接入本地 AI 助手。它与 Telegram Token、API Key 等完全无关，只作用于本地 Web UI 和 CLI 的管理通道。即使你已成功运行 Telegram 机器人，Web UI 仍可能因未配对而无法访问。

5. 检查配置文件语法与结构完整性

JSON 配置文件中一个多余的逗号、少一个引号、或字段嵌套错位，都可能导致 ClawdBot 在加载配置时静默失败，进而导致 gateway 启动流程中断。这类错误不会打印明显报错，只会让 clawdbot gateway start 命令快速退出。

5.1 判断口诀

“启动没日志、clawdbot config validate 报错、或修改配置后突然不行——先查 JSON。”

5.2 验证命令

ClawdBot 自带配置校验工具：

clawdbot config validate 

若输出类似：

❌ Invalid JSON in /app/clawdbot.json: Expecting property name enclosed in double quotes 

说明配置文件存在语法错误。

也可用系统命令快速检测：

jq empty /app/clawdbot.json 2>/dev/null && echo " JSON valid" || echo "❌ JSON invalid" 

5.3 修复动作

使用在线 JSON 校验器（如 https://jsonlint.com）粘贴 /app/clawdbot.json 全文，定位错误位置。常见错误包括：

• 最后一个字段后多了一个逗号（,）
• 使用了中文引号 “” 而非英文双引号 "
• models.providers.vllm 下漏写了 baseUrl 字段
• channels.telegram 块被错误地放在了 models 同级而非顶层

安全修改建议：
先备份原文件 → 用 VS Code 或 Notepad++ 打开（开启 JSON 语法高亮）→ 修改后保存 → 再次 clawdbot config validate → 通过后重启 gateway。

5.4 补充说明

ClawdBot 的配置是“全量加载”模式：任一字段解析失败，整个配置即失效。它不会跳过错误字段继续加载，也不会给出精确到行号的提示。因此，当你不确定哪改错了，最稳妥的方式是——
回退到一个已知可用的配置版本，再逐行对比新增内容。

总结：一张故障决策树，5分钟定位根源

遇到 Gateway not reachable，别急着重装、别盲目搜日志。按以下顺序快速自查，90% 的问题可在 5 分钟内闭环：

这五步不是并列选项，而是递进式诊断链：前一步不通，后一步必然失败。比如第2步端口被占，第1步就不可能看到 gateway 进程；第3步 vLLM 不通，第1步 gateway 即使启动也会很快崩溃。

最后提醒一句：ClawdBot 的设计哲学是「本地优先、隐私至上、开箱即控」。它的调试过程，本质上是在帮你厘清「我的设备、我的模型、我的连接」三者之间的真实关系。每一次 Gateway not reachable，都不是故障，而是系统在诚实地告诉你：“这里，需要你亲手确认一下。”

获取更多AI镜像

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