ClawdBot从零开始：新手避坑指南——常见connection refused排障

你刚兴冲冲地拉下ClawdBot镜像、跑起容器、打开浏览器，却只看到一个冰冷的错误提示：Connection refused。页面打不开，命令行报错，日志里翻来覆去就那几行“gateway closed”“no close reason”……别急，这不是你的设备不行，也不是模型太娇气——这是ClawdBot新手上路时最常踩的三类连接断点，而且90%的情况，根本不用重装、不用改代码，只需按顺序检查这四个环节。

本文不讲原理堆砌，不列参数大全，只聚焦你此刻最需要的答案：为什么连不上？哪里卡住了？怎么三分钟内让它活过来？ 全程基于真实部署场景，所有命令、路径、配置项均来自你本地终端里正在运行的ClawdBot实例。

---

1. 连接断点定位：先搞清“谁在拒绝谁”

ClawdBot不是单体应用，而是一套协同工作的服务组合。所谓“connection refused”，本质是某两个组件之间握手失败。我们先理清它的最小通信链路：

浏览器（前端）  
    ↓ HTTP 请求  
ClawdBot Gateway（主进程，监听 18780 端口）  
    ↓ WebSocket / HTTP API  
vLLM 推理服务（独立进程，监听 8000 端口）  
    ↓ 模型加载  
Qwen3-4B-Instruct-2507（实际运行的模型）

关键结论：当你在浏览器访问 http://localhost:7860 失败时，问题不一定出在7860端口本身——它可能只是个“前台接待”，真正被拒的是它背后试图连接的 127.0.0.1:18780（Gateway）或 127.0.0.1:8000（vLLM）。
所以第一步，永远不是刷新页面，而是执行这条命令：

clawdbot gateway status

如果返回类似这样的信息：

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

说明问题出在Gateway层；
如果返回 Gateway OK，但你仍打不开UI，那问题大概率在前端代理或端口映射；
如果 clawdbot models list 报错 Failed to connect to http://localhost:8000/v1/models，那根源就在vLLM服务没起来。

记住这个判断树，后面所有操作都围绕它展开。

---

2. 第一类断点：Gateway未启动或崩溃（最常见）

ClawdBot的Gateway是整个系统的“神经中枢”，负责路由请求、管理会话、对接模型。但它不会自动后台常驻——尤其在Docker容器中，若启动脚本没正确守护，它可能一闪而过就退出了。

2.1 快速验证：看它到底在不在

别猜，直接查进程：

ps aux | grep clawdbot | grep -v grep

你应该看到至少两行：

• 一行是 clawdbot gateway start（主服务）
• 一行是 clawdbot models serve（模型服务，可选）

如果只有 clawdbot dashboard 或完全没结果，说明Gateway根本没跑起来。

2.2 根本原因与解法

场景A：容器内未自动启动Gateway

很多ClawdBot镜像默认只启动CLI，不自动拉起Gateway。你需要手动触发：

# 进入容器（假设容器名是 clawdbot）
docker exec -it clawdbot bash

# 启动Gateway（后台运行，避免阻塞）
clawdbot gateway start --daemon

# 验证状态
clawdbot gateway status

成功时会显示 Gateway OK 和监听地址 ws://127.0.0.1:18780。

场景B：端口被占用（尤其18780）

ClawdBot默认用18780，但如果你之前跑过其他服务（比如旧版ClawdBot、自定义WebSocket服务），这个端口可能正被占着。

# 查看谁占了18780
lsof -i :18780
# 或（Linux）
netstat -tuln | grep :18780

如果发现PID，直接杀掉：

kill -9 <PID>
# 再重启Gateway
clawdbot gateway start --daemon

场景C：配置文件损坏导致启动失败

Gateway启动时会读取 ~/.clawdbot/clawdbot.json。如果JSON格式错误（比如多了一个逗号、少了一个引号），它会静默退出。

检查方法：

# 验证JSON语法（Linux/macOS）
jq . ~/.clawdbot/clawdbot.json >/dev/null 2>&1 && echo "OK" || echo "Invalid JSON"

如果报错，用文本编辑器打开该文件，重点检查：

• channels、models、agents 三个大对象是否闭合
• 所有字符串值是否用双引号包裹（"true" 而非 true）
• 删除末尾多余的逗号（JSON标准不允许）

小技巧：把整个文件内容粘贴到 https://jsonlint.com 在线校验，秒出错误位置。

---

3. 第二类断点：vLLM服务未就绪（模型层失联）

ClawdBot自己不推理，它靠vLLM提供能力。如果你修改过模型配置，或首次部署，vLLM很可能压根没启动，或者启动失败后自动退出。

3.1 一眼识别：clawdbot models list 是照妖镜

执行：

clawdbot models list

• 正常：列出模型名称、上下文长度、认证状态（如 vllm/Qwen3-4B-Instruct-2507 行末显示 yes yes）
• ❌ 异常：报错 Failed to connect to http://localhost:8000/v1/models 或直接卡住

这说明ClawdBot找不到vLLM，而vLLM默认监听 http://localhost:8000。

3.2 三步排查vLLM状态

步骤1：确认vLLM进程是否存在

ps aux | grep vllm | grep -v grep

你应该看到类似：

python3 -m vllm.entrypoints.api_server --host 0.0.0.0 --port 8000 ...

如果没有，说明vLLM根本没启动。

步骤2：检查ClawdBot配置中的vLLM地址是否匹配

打开你的 ~/.clawdbot/clawdbot.json，找到 models.providers.vllm.baseUrl 字段：

"vllm": {
  "baseUrl": "http://localhost:8000/v1",
  ...
}

常见错误：

• 写成 "http://127.0.0.1:8000/v1"（在Docker容器内，127.0.0.1 指向容器自身，但vLLM可能没绑定到 0.0.0.0）
• 写成 "http://host.docker.internal:8000/v1"（仅Mac/Windows Docker Desktop有效，Linux需额外配置）

正确写法（兼容性最强）：

"baseUrl": "http://localhost:8000/v1"

同时确保vLLM启动时绑定了 0.0.0.0：

# 启动vLLM（在容器内执行）
python3 -m vllm.entrypoints.api_server \
  --host 0.0.0.0 \
  --port 8000 \
  --model vllm/Qwen3-4B-Instruct-2507 \
  --tensor-parallel-size 1

步骤3：验证vLLM是否真能响应

绕过ClawdBot，直接curl测试：

curl http://localhost:8000/v1/models

正常返回JSON列表（含模型ID）
❌ 返回 Connection refused → vLLM没起来或端口不对
❌ 返回 Connection timed out → vLLM在启动，但模型加载慢（Qwen3-4B首次加载约需1-2分钟，耐心等）

提示：如果vLLM启动后长时间无响应，检查GPU显存是否足够（Qwen3-4B需约8GB VRAM），或降低 --tensor-parallel-size 到1。

---

4. 第三类断点：前端访问路径错误（最易忽略）

你以为打开了 http://localhost:7860 就万事大吉？ClawdBot的Web UI其实是个“代理壳”，它需要先连上Gateway（18780），再由Gateway反向代理到实际服务。所以即使Gateway和vLLM都活着，前端URL也可能失效。

4.1 正确访问方式：永远用 clawdbot dashboard 生成的链接

不要手敲 http://localhost:7860！执行：

clawdbot dashboard

你会得到类似输出：

Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762
...
Then open:
http://localhost:7860/
http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762

必须复制带 ?token=xxx 的完整URL，粘贴到浏览器。
❌ 不要省略token，也不要改成 127.0.0.1（除非你在服务器本机访问）。

为什么？因为ClawdBot的Web UI启用了token鉴权，没有token会被直接拒绝，返回 403 Forbidden —— 但浏览器往往只显示空白页或“无法连接”，让你误以为是网络问题。

4.2 如果你在远程服务器部署（如云主机）

http://localhost:7860 在你的本地电脑上打不开！你需要做端口转发：

# 在你的本地电脑终端执行（替换为你的服务器IP）
ssh -N -L 7860:127.0.0.1:7860 user@your-server-ip

然后在本地浏览器打开 http://localhost:7860/?token=xxx 即可。

注意：clawdbot dashboard 输出里的 ssh -N -L ... 命令就是为你生成的，直接复制粘贴即可。

---

5. 终极验证：四步连通性测试清单

当以上步骤都做完，用这个清单快速闭环验证：

步骤	命令	预期结果	不通过怎么办
1. Gateway存活	clawdbot gateway status	显示 Gateway OK 和 ws://127.0.0.1:18780	重启 clawdbot gateway start --daemon，检查端口占用
2. vLLM可达	curl http://localhost:8000/v1/models	返回JSON数组（含模型ID）	检查vLLM是否启动、baseUrl配置、GPU资源
3. 模型注册成功	clawdbot models list	列出模型，末列显示 yes yes	确认vLLM返回正常，且ClawdBot配置中models.mode为merge
4. UI令牌有效	浏览器打开 clawdbot dashboard 输出的完整URL	正常加载UI，左下角显示 Connected	务必用带token的URL，勿手输；远程访问需SSH端口转发

只要这四步全绿，你的ClawdBot就已真正“活”了。此时再点UI左上角的“Chat”标签，输入“你好”，就能看到Qwen3-4B的实时回复——这才是你期待的AI助手。

---

6. 额外提醒：那些看似无关、实则致命的细节

有些问题藏得深，但解决起来就一句话：

• clawdbot devices approve 不是可选项，是必选项
  如你开头看到的截图，clawdbot devices list 会显示 pending 请求。不执行 clawdbot devices approve [request]，Gateway会拒绝所有新连接（包括Web UI）。这是ClawdBot的安全机制，不是bug。

• 配置文件路径必须精准
  ClawdBot默认读取 ~/.clawdbot/clawdbot.json。如果你在Docker中挂载了 -v ./config:/app，请确保容器内 ~/.clawdbot/ 是软链接到 /app，或直接在启动命令中指定：

  clawdbot --config /app/clawdbot.json gateway start
  

• 别信“一键部署”的神话
  MoltBot确实能做到 docker run moltbot 五分钟上线，但ClawdBot更侧重可控性与扩展性。它的“零配置”是指无需申请API Key、无需配云服务，而不是“无需理解服务拓扑”。花10分钟读懂Gateway-vLLM关系，能省下后续3小时盲目重试。

• 日志是你的朋友，不是噪音
  当一切都不对时，看日志：

  # 查看Gateway日志（实时）
  clawdbot gateway logs -f
  # 查看vLLM日志（如果它作为子进程启动）
  tail -f ~/.clawdbot/logs/vllm.log
  

  关键线索往往藏在 OSError: [Errno 98] Address already in use 或 CUDA out of memory 这类直白报错里。

---

获取更多AI镜像

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