ClawdBot调试指南里Gateway not reachable错误的5种排查与修复方法该怎么用？
ClawdBot 是一个真正跑在你自己设备上的个人 AI 助手。它用 vLLM 提供后端推理能力，所有对话、文件处理、模型计算都在本地完成，不上传任何数据、不需要云端 API 密钥、不受网络波动影响。正是因为它采用本地多进程 + WebSocket 长连接架构，一旦出现 Gateway not reachable 错误，很多新手都会慌神。
这个错误看似简单，实则卡在“看不见”的连接层、配置层或环境层。本文不讲抽象原理，而是基于真实部署场景（树莓派 4、Ubuntu 22.04、Docker Compose、国内网络），给你 5 种高频、可验证、有先后顺序的排查路径。每一步都配判断口诀、验证命令、修复动作和补充说明，按顺序走，90% 的问题 5 分钟内就能解决。
1. 检查 Gateway 进程是否真正启动并监听端口
这是最基础也最容易忽略的一步。很多用户敲完 clawdbot start 看到“Starting gateway…”就以为好了，但 gateway 进程可能因模型加载失败、端口冲突、内存不足等原因已经静默退出。
判断口诀：
“看不到日志滚动，大概率没活；端口查不到监听，肯定没跑。”
验证命令：
lsof -i :18780
或者（没有 lsof 时）
netstat -tuln | grep :18780
或者直接看进程
ps aux | grep gateway | grep -v grep
没有输出就说明 gateway 没在运行。
修复动作：
clawdbot gateway start --verbose
重点看输出里有没有这两行关键日志：
Gateway server started on ws://127.0.0.1:18780
✔ Model loaded successfully in X.XX seconds
如果卡在“Loading model”或报 CUDA out of memory，就跳到第 3 步；如果报 Address already in use，就跳到第 2 步。
补充说明：
Gateway 是整个 ClawdBot 的“神经中枢”，独立于 Dashboard 和 Telegram。它不起来，status --probe 命令都会直接返回 Gateway not reachable。
2. 确认 18780 端口未被其他进程占用
ClawdBot 默认用 18780 作为 WebSocket 网关端口，在国内环境里很容易被 Docker 容器、旧 Node 服务或国产远程工具占用。
判断口诀：
“启动报 Address already in use，或者 lsof 显示陌生 PID，八成是端口撞车。”
验证命令：
sudo lsof -i :18780
修复动作：
如果是 docker 占用：
docker ps -a | grep 18780
docker stop $(docker ps -q --filter "expose=18780" --format="{{.ID}}")
如果是其他进程，直接 kill 对应 PID：
sudo kill -9 1234 替换成实际 PID
想永久解决冲突，可以改端口：在 /app/clawdbot.json 顶层添加：
"gateway": {
"port": 18781
}
改完后执行 clawdbot gateway restart。
补充说明：
千万别用 killall -9 python，ClawdBot 自己也是 Python 进程，误杀会把整个服务搞崩。精准定位才是正确姿势。
3. 验证 vLLM 模型服务是否就绪且可连通
Gateway 本身不做推理，它只负责把请求转发给 vLLM（默认 http://localhost:8000/v1）。vLLM 没启动或地址配错，gateway 就会自己关闭，表现为 Gateway not reachable。
判断口诀：
“clawdbot models list 能列出模型 ≠ vLLM 在线；能列出 ≠ 能响应；能响应 ≠ 地址配对。”
验证命令（三步走）：
① 检查 vLLM 健康状态
curl -s http://localhost:8000/health | jq . || echo "❌ vLLM not responding"
② 检查配置里的 baseUrl
jq '.models.providers.vllm.baseUrl' /app/clawdbot.json
③ 手动模拟一次请求
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 .choices0.message.content
修复动作：
常见问题及解决：
– 模型路径错 → 确认已下载到 ~/.cache/huggingface/hub
– 树莓派等设备显存不足 → 用 --device cpu 启动 vLLM
– 版本不匹配 → 要求 vLLM ≥ 0.6.3
一键重启 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
补充说明：
很多用户把现象当根因。记住：Gateway not reachable 是结果，vLLM 才是真正“信使”要找的收件人。
4. 核查设备配对状态与 Token 有效性
Web UI 和 CLI 通过 WebSocket 连 gateway，而这个连接受设备配对机制保护。没执行 clawdbot devices approve 或 token 过期，gateway 就会直接拒绝，报 abnormal closure (1006)。
判断口诀：
“UI 打不开 + clawdbot devices list 显示 pending，就是配对没过门。”
验证命令：
clawdbot devices list
修复动作：
clawdbot devices approve abc123... 复制实际 ID
clawdbot gateway restart
补充说明：
这是 ClawdBot 的安全设计，只管本地 Web UI 和 CLI，与 Telegram Token 完全无关。即使 Telegram 机器人能用，Web UI 也可能因为未配对而无法访问。
5. 检查配置文件语法与结构完整性
JSON 里多一个逗号、少一个引号、字段放错层级，都会导致 gateway 启动直接静默失败。
判断口诀：
“启动没日志、config validate 报错、改配置后突然不行——先查 JSON。”
验证命令：
clawdbot config validate
或者系统命令快速检测
jq empty /app/clawdbot.json 2>/dev/null && echo "✅ JSON valid" || echo "❌ JSON invalid"
修复动作：
用 VS Code 或 Notepad++（打开 JSON 高亮）编辑，常见错误有：
– 最后一个字段后多逗号
– 中文引号 “” 而不是英文 ”
– baseUrl 漏写或 channels.telegram 放错层级
改完备份 → 校验通过 → clawdbot gateway restart。
补充说明：
ClawdBot 是全量加载配置，任一字段出错整个配置失效。最稳的办法是回退到已知好用的配置，再逐行对比。
总结：一张故障决策树，5 分钟定位根源
遇到 Gateway not reachable，按下面顺序自查：
| 步骤 | 检查项 | 快速验证命令 | 通过标志 |
|---|---|---|---|
| 1 | Gateway 进程是否存活 | ps aux | grep gateway |
显示 clawdbot-gateway 进程 |
| 2 | 18780 端口是否空闲 | lsof -i :18780 |
无输出 |
| 3 | vLLM 服务是否可达 | curl -s http://localhost:8000/health |
返回 JSON 健康状态 |
| 4 | 设备是否已批准 | clawdbot devices list |
状态为 active |
| 5 | 配置文件是否合法 | clawdbot config validate |
输出 Config is valid |
这五步是递进式诊断链，前一步不通，后一步必然失败。
ClawdBot 的设计哲学就是“本地优先、隐私至上、开箱即控”。每一次 Gateway not reachable，都不是单纯的故障，而是系统在提醒你：“这里，需要你亲手确认一下。”
获取更多AI镜像
想探索更多 AI 镜像和应用场景？访问 CSDN 星图镜像广场，提供丰富的大模型推理、图像生成、视频生成、模型微调预置镜像，支持一键部署，帮你更快搭建本地 AI 环境。
