ClawdBot部署教程：解决Gateway not reachable常见连接问题

1. ClawdBot是什么：你的本地AI助手，不是云端玩具

ClawdBot 是一个真正属于你自己的个人 AI 助手——它不依赖远程服务器，不把你的对话发到别人家的机房，所有推理都在你自己的设备上完成。它不像那些点开网页就跑、关掉页面就消失的“云服务”，而是一个可以装在笔记本、台式机甚至家用 NAS 上的实体程序。

它的后端由 vLLM 驱动，这意味着你能享受到接近工业级的推理吞吐和极低的首字延迟。vLLM 不是噱头，它是实打实让 Qwen3-4B 这类模型跑得又快又稳的核心引擎。你输入一句话，它几乎不用等，就能开始输出；你连续追问三次，它不会卡顿、不会超时、不会突然断连——因为整个链路都在你本地闭环。

很多人第一次听说 ClawdBot，会下意识把它和 Telegram 机器人 MoltBot 混在一起。这里要划清界限：MoltBot 是 2025 年开源的「多语言、多平台、零配置」Telegram 翻译机器人，主打语音转写、图片 OCR、汇率天气查询，一条 docker run moltbot 就能上线，树莓派 4 都能扛住 15 人并发。但它和 ClawdBot 完全无关——MoltBot 是面向群聊场景的轻量工具，ClawdBot 是面向深度交互的本地智能体平台。两者技术栈不同、定位不同、部署方式也不同。本教程只聚焦 ClawdBot，不涉及 MoltBot 的任何配置或联动。

2. 部署第一步：别急着打开网页，先搞定“网关不可达”

很多用户卡在第一步：安装完 ClawdBot，浏览器打开 http://localhost:7860，页面空白，或者提示“无法连接”；终端里执行 clawdbot channels status --probe，直接报错：

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

这个错误不是模型没起来，也不是端口被占，而是 ClawdBot 的核心通信机制——网关（Gateway）尚未完成身份绑定。它就像一扇上了锁的门，钥匙还没交到你手上，门自然打不开。

ClawdBot 采用设备配对机制（device pairing），首次启动后，它会生成一个待审批的设备请求，必须手动批准，网关才会建立稳定 WebSocket 连接。这是安全设计，不是 bug。

2.1 查看待处理的设备请求

打开终端，执行：

clawdbot devices list

你会看到类似这样的输出：

ID                                    Status     Created At           Last Seen
a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8  pending    2026-01-24 14:22:18  -

只要状态是 pending，就说明网关还在等待你的确认。此时前端页面必然无法加载，所有 API 调用都会失败。

2.2 批准设备，激活网关

复制上面输出中的 ID（整段长字符串），执行批准命令：

clawdbot devices approve a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8

批准成功后，终端会返回 Approved，同时网关服务会自动重连。几秒后，再次运行：

clawdbot devices list

状态应变为 active，且 Last Seen 时间不断更新。

小贴士：如果你在远程服务器（比如云主机或 NAS）上部署，clawdbot devices list 可能看不到 pending 请求——因为默认只显示本地 GUI 设备。这时请改用 clawdbot devices list --all 查看全部设备记录。

2.3 如果还是打不开？试试 Dashboard 直连链接

即使设备已批准，有些环境（如无桌面 GUI 的 Linux 服务器、WSL2、Docker 容器）仍无法直接访问 http://localhost:7860。这时别折腾反向代理，直接用 ClawdBot 自带的 Dashboard 命令：

clawdbot dashboard

你会看到类似输出：

Dashboard URL: http://127.0.0.1:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762
No GUI detected. Open from your computer:
ssh -N -L 7860:127.0.0.1:7860 root@100.64.232.100
Then open:
http://localhost:7860/
http://localhost:7860/?token=23588143fd1588692851f6cbe9218ec6b874bb859e775762

关键信息有两个：

• ?token= 后面的长字符串是临时访问凭证，每次重启都会变；
• ssh -N -L ... 是给 Windows/macOS 用户准备的端口转发命令——把它复制进你的本地终端（不是服务器终端！），回车执行，然后在本地浏览器打开 http://localhost:7860 即可。

这一步绕过了所有网络策略限制，是远程部署最可靠的访问方式。

3. 模型配置实战：从默认Qwen3到你想要的任意vLLM模型

ClawdBot 默认内置了 Qwen3-4B-Instruct 模型，但它的真正价值在于灵活支持你本地已有的 vLLM 服务。你不必被绑死在一个模型上，完全可以换成 Llama-3.2-3B、Phi-3.5-mini 或你自己微调过的版本。

3.1 修改配置文件：精准控制模型来源

ClawdBot 的核心配置统一存放在 /app/clawdbot.json（容器内路径）或 ~/.clawdbot/clawdbot.json（宿主机路径）。打开它，找到 models 区块，按如下结构修改：

{
  "models": {
    "mode": "merge",
    "providers": {
      "vllm": {
        "baseUrl": "http://localhost:8000/v1",
        "apiKey": "sk-local",
        "api": "openai-responses",
        "models": [
          {
            "id": "Qwen3-4B-Instruct-2507",
            "name": "Qwen3-4B-Instruct-2507"
          }
        ]
      }
    }
  }
}

重点说明三个字段：

• baseUrl：指向你本地 vLLM 服务的地址。如果你用 vllm serve --model Qwen3-4B-Instruct 启动，默认就是 http://localhost:8000/v1；如果 vLLM 在另一台机器，改成 http://192.168.1.100:8000/v1；
• apiKey：vLLM 默认不校验 key，填 "sk-local" 即可（ClawdBot 会自动带上）；
• models.id：必须和 vLLM 启动时指定的 --model 名称完全一致，包括大小写和中横线。

改完保存，重启 ClawdBot（或执行 clawdbot restart），配置立即生效。

3.2 UI界面快速切换：不用碰JSON也能换模型

如果你更习惯图形化操作，进入前端界面后：

• 左侧导航栏点击 Config → Models → Providers；
• 在 vllm 提供商下，点击右上角 + Add Model；
• 填入 Model ID（如 Llama-3.2-3B-Instruct）和 Display Name（如 “Llama3.2 3B”）；
• 点击 Save，无需重启，新模型立刻出现在模型选择下拉框中。

这种方式适合快速测试多个模型，但生产环境建议优先用 JSON 配置，更稳定、可备份、易版本管理。

3.3 验证模型是否真正就位

别信界面显示，用命令行验证最可靠：

clawdbot models list

正常输出应类似：

Model                                      Input      Ctx      Local Auth  Tags
vllm/Qwen3-4B-Instruct-2507                text       195k     yes   yes   default
vllm/Llama-3.2-3B-Instruct                 text       8k       yes   yes   -

关键看三列：

• Local Auth 为 yes，说明 ClawdBot 能直连 vLLM；
• Ctx 显示上下文长度（如 195k），证明模型能力被正确识别；
• 如果某模型显示 no 或为空，说明 baseUrl 地址不通，或模型 ID 不匹配。

避坑提醒：vLLM 启动时若加了 --served-model-name my-custom-qwen，则 clawdbot.json 中的 id 必须填 my-custom-qwen，而不是原始模型名。这是新手最常踩的坑。

4. 为什么Telegram频道配置会触发Gateway报错？真相在这里

文档里提到的 channel-telegram 配置，看似只是加个 botToken，实则暗藏玄机。当你在 clawdbot.json 中启用 Telegram 通道：

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "xxx"
  }
}

ClawdBot 会尝试同时启动两个独立服务：

• 主网关（WebSocket）：负责前端 UI 和本地 Agent 通信；
• Telegram 网关（HTTP polling / Webhook）：负责和 Telegram 服务器对接。

而 Gateway not reachable 错误，往往不是主网关挂了，而是 Telegram 网关启动失败，导致整个 Gateway 管理器崩溃重启。尤其在国内网络环境下，Telegram 的域名（api.telegram.org）默认无法直连，即使加了 proxy 字段，ClawdBot 的 Telegram 模块对代理协议兼容性有限，极易触发 1006 abnormal closure。

所以，除非你有稳定、低延迟、支持 HTTP CONNECT 的 SOCKS5 代理（且已全局配置到系统），否则强烈不建议在初次部署阶段开启 Telegram 频道。先确保主网关、模型、UI 全部跑通，再单独调试 Telegram 模块。

验证方法很简单：注释掉整个 channels.telegram 区块，或设 "enabled": false，然后重启 ClawdBot。如果 clawdbot channels status --probe 不再报错，且 clawdbot devices list 显示 active，那就坐实了问题根源。

5. 界面体验与日常维护：让ClawdBot真正好用起来

ClawdBot 的前端不是花架子，它把复杂功能做了分层封装，日常使用只需关注三个核心区域：

5.1 左侧导航：你的操作中枢

• Chat：主对话区，支持多轮上下文、文件上传（PDF/DOCX/TXT）、代码高亮；
• Agents：创建和管理智能体，比如“周报生成助手”、“会议纪要整理员”，每个 Agent 可绑定不同模型和提示词；
• Config：全局配置入口，模型、日志、安全策略都在这里调整；
• Logs：实时查看服务日志，比翻 journalctl 直观十倍，错误行自动标红。

5.2 日常维护三板斧

• 查状态：clawdbot status —— 一眼看清 vLLM 是否在线、网关是否活跃、磁盘空间是否充足；
• 看日志：clawdbot logs --tail 100 —— 实时追踪最后 100 行日志，定位卡顿或报错；
• 强制重启：clawdbot restart —— 比 kill -9 安全，会优雅关闭所有子进程。

5.3 一个真实可用的小技巧：让模型响应更快

如果你发现 Qwen3-4B 输入后首字延迟偏高（>800ms），不是模型问题，而是默认启用了 flash-attn 但未编译适配。在 vLLM 启动命令中加入：

vllm serve --model Qwen3-4B-Instruct --enable-prefix-caching --gpu-memory-utilization 0.9

--enable-prefix-caching 能显著提升多轮对话的 token 生成速度，--gpu-memory-utilization 0.9 防止显存爆满导致 OOM。这两个参数对 8GB 显存的 RTX 4070/4080 用户特别友好。

6. 总结：Gateway问题的本质，是信任链的建立过程

ClawdBot 的 Gateway not reachable 报错，从来不是技术故障，而是一次安全握手的必经流程。它提醒你：这不是一个“装完就用”的黑盒软件，而是一个需要你亲手建立信任关系的本地智能体。

回顾整个部署链条：

• 第一步 devices list 是发现请求；
• 第二步 devices approve 是签署信任证书；
• 第三步 dashboard 是获取访问密钥；
• 后续的模型配置、日志排查，都是在加固这条本地信任链。

当你不再把它当成“又要配端口又要改配置”的麻烦事，而是理解成“我在给自己建一座私有AI城堡”，那些报错就不再是障碍，而是城堡大门缓缓开启时，门轴转动发出的、让人安心的声响。

现在，你已经掌握了从零部署、排障、换模型、保稳定的全流程。接下来，是时候让它为你写第一份周报、整理会议录音、或是帮你读完那篇 30 页的技术白皮书了。

---

获取更多AI镜像

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