什么是ClawdBot？——你的本地AI助手，不是云端玩具

ClawdBot 是一个真正属于你自己的个人 AI 助手。它不依赖远程API、不上传隐私数据、不按调用次数收费——所有推理都在你自己的设备上完成。你可以把它理解成“装在你电脑里的 Siri + Copilot + Notion AI 的混合体”，但更自由、更透明、更可控。

它的核心能力由 vLLM 提供支撑。vLLM 是当前最高效的开源大模型推理引擎之一，以极高的吞吐量和极低的显存占用著称。ClawdBot 利用它来加载和运行像 Qwen3-4B-Instruct 这样的轻量级但能力扎实的模型，让你在消费级显卡（甚至带显存的笔记本）上也能获得接近专业服务的响应速度和对话质量。

和那些动辄要填 API Key、绑定手机号、看广告才能用的 Web 应用不同，ClawdBot 的哲学是：“你装，你用，你改，你拥有。”配置文件是纯 JSON，日志清晰可读，出问题时你能看到每一行报错，而不是一句模糊的“服务暂时不可用”。

这正是它和 MoltBot 这类工具形成鲜明对比的地方：MoltBot 是开箱即用的 Telegram 翻译机器人，目标是“5分钟上线一个全能翻译官”；而 ClawdBot 的目标是“5分钟搭建一个完全听你指挥的本地AI大脑”。前者解决的是“我需要什么功能”，后者解决的是“我想怎么用AI”。

所以当你遇到 Gateway not reachable 这个错误时，别慌——这不是服务宕机，也不是网络抽风，而是你的本地AI大脑和控制界面之间，那条本该畅通无阻的“神经通路”暂时断开了。接下来，我们就一条一条地帮你把这条路重新接通。

简单来说，ClawdBot 是一个能替你“动手做事”的 AI 智能体（AI Agent）。它就像一位能通过聊天软件远程遥控的“数字管家”或现实版的“贾维斯”，只要通过日常的聊天软件给它发消息，它就能在你自己的电脑上帮你执行各种具体操作。

它是做什么的？

ClawdBot 的核心是“行动”。与只能提供建议或生成文本的普通聊天机器人不同，它能够直接将你的指令转化为对电脑的操作，实现“所想即所得”。例如：

• 文件管理：根据指令自动整理、归类、重命名文件和文件夹-。
• 信息处理：从多个文档中提取特定信息（如邮箱地址），或总结长篇内容-。
• 邮件与日程：自动管理收件箱、发送邮件、安排日程等。
• 网络浏览：自主访问网页、填写表单、提取数据，甚至可以帮你预订餐厅-。
• 软件与系统控制：操作音乐软件、编辑笔记、编写脚本，甚至在 VS Code 里编写代码。

???? 它如何运作？

ClawdBot 像一个“超级大脑”和“万能手脚”的结合体：

• “大脑”（Agent & Memory）：它利用大模型（如 Claude、Gemini）进行推理，并拥有持久记忆，能记住你过往的偏好，提供个性化服务。
• “耳朵与嘴巴”（Gateway）：它通过一个网关无缝连接到 WhatsApp、Telegram、Discord 等日常聊天软件，让你通过对话进行操控。
• “手脚”（Skills）：这是它真正的执行工具。通过社区贡献的各种“技能”插件，它能像真人一样去操作浏览器、运行脚本或调用系统 API。

2. Gateway not reachable 错误的本质：不是故障，是连接未就绪

在开始排查前，先破除一个常见误解：Gateway not reachable: Error: gateway closed (1006 abnormal closure) 这个报错不是程序崩溃了，也不是模型挂了。它只是告诉你一件事：ClawdBot 的前端控制台（Dashboard）尝试通过 WebSocket 连接到后端网关（Gateway）时失败了。

你可以把整个系统想象成一台老式收音机：

• vLLM 推理服务 是电台发射塔（在后台默默运行）
• ClawdBot Gateway 是收音机的调谐电路（负责接收信号、解码指令）
• Dashboard 前端界面 是喇叭和旋钮（你看到和操作的部分）

Gateway not reachable 意味着旋钮已经拧开，但调谐电路还没收到发射塔的信号——可能是因为发射塔没开机，也可能是中间的天线没接好，还可能是你调错了频率。

这个错误通常出现在以下几种典型场景中：

• 刚启动 ClawdBot，vLLM 服务还在加载模型，网关尚未完全就绪
• 配置文件里指定了错误的网关地址或端口
• vLLM 服务根本没运行，或者运行失败后自动退出
• 网关进程被意外终止，但 Dashboard 还在尝试重连
• 代理或防火墙拦截了本地回环（localhost）的 WebSocket 连接

好消息是：所有这些原因，都不需要重装、不需要删库、不需要查源码。你只需要按顺序执行几个命令，就能定位并修复。

3. 方法一：确认 vLLM 服务是否真正在运行（最常被忽略的一步）

这是 70% 的 Gateway not reachable 问题的根源。很多人以为 clawdbot start 一执行，所有服务就自动拉起来了，其实不然。

ClawdBot 本身是一个控制框架，它不内置模型推理能力。它依赖外部的 vLLM 服务提供“思考”能力。如果你只运行了 ClawdBot，但没启动 vLLM，那么网关就像一个没有发动机的汽车——外观完整，但无法启动。

如何验证？

打开终端，执行：

如果输出中没有任何包含 vllm_entrypoint.py 或 python -m vllm.entrypoints.api_server 的进程，说明 vLLM 根本没在跑。

如何启动？

根据你的部署方式选择：

如果你用 Docker Compose（推荐）： 确保 docker-compose.yml 中已正确定义 vLLM 服务，然后运行：

如果你手动启动 vLLM：

关键检查点：

• --port 8000 必须和 clawdbot.json 中 "baseUrl": "http://localhost:8000/v1" 的端口号完全一致
• 启动后，访问 http://localhost:8000/docs 应该能看到 OpenAPI 文档页面
• 终端日志中出现 INFO: Application startup complete. 即表示服务已就绪

等 vLLM 完全启动（首次加载模型可能需要 1–2 分钟），再执行 clawdbot dashboard，错误通常会立即消失。

4. 方法二：校验配置文件中的网关地址与端口（小数点错一位，全盘皆输）

ClawdBot 的网关（Gateway）和 vLLM 服务是两个独立进程，它们之间的通信靠配置文件 clawdbot.json 中的 models.providers.vllm.baseUrl 字段指定。这个字段写错一个字符，就会导致“鸡同鸭讲”。

常见错误类型：

如何快速修正？

打开配置文件：

找到 models.providers.vllm.baseUrl 这一行，严格对照以下格式修改：

保存后，必须重启 ClawdBot 网关（不是只改配置就完事）：

注意：ClawdBot 不支持热重载配置。改完 JSON 文件后不重启，等于没改。

5. 方法三：检查网关进程状态并强制重启（当“假死”发生时）

有时候，vLLM 服务明明在运行，但 ClawdBot 的网关进程自己卡住了，表现为：

• clawdbot dashboard 能打开页面，但一直转圈
• clawdbot models list 命令卡住或报超时
• 终端里看不到网关相关的日志输出

这就是典型的“网关假死”——进程还在，但内部连接已中断。

三步诊断法：

查看网关是否在运行：

如果有类似 clawdbot-gateway --config /app/clawdbot.json 的进程，说明它在跑；如果没有，则跳到第3步。

查看网关日志（关键！）：

日志中如果出现 Connection refused、timeout、failed to connect to vLLM，就坐实了是网关连不上后端。

暴力但有效：杀死并重启网关

这个方法之所以有效，是因为 ClawdBot 的网关在启动时会创建一个 .gateway.lock 文件防止重复启动。如果上次异常退出，锁文件可能没被清除，导致新进程拒绝启动。手动删除后，就能干净重启。

6. 方法四：绕过网关直连 Dashboard（临时应急，验证前端是否正常）

当你反复尝试前三步仍失败时，可以跳过网关，直接让 Dashboard 连接 vLLM。这能帮你快速判断：问题是出在网关本身，还是网关与 vLLM 的连接上。

操作步骤：

临时修改配置，让 Dashboard 直连 vLLM： 编辑 ~/.clawdbot/clawdbot.json，将 models.providers 部分改为：

关键变化："mode": "direct" 替代了原来的 "merge"，并移除了 models 数组（因为直连模式下不需预注册模型ID）

重启 ClawdBot：

再次访问 Dashboard：

如果这次能正常打开，并且 Models → List 能显示模型列表，那就100%确认：问题出在 ClawdBot 自带的网关模块，而非你的环境或 vLLM 服务。

此时你可以：

• 继续用直连模式工作（适合开发调试）
• 或回到 GitHub 查看 clawdbot-gateway 的 issue，确认是否为已知 bug
• 或降级到上一个稳定版本的 ClawdBot

7. 方法五：检查本地回环（localhost）网络策略（国内用户高频雷区）

在国内网络环境下，某些安全软件、企业防火墙、甚至 Windows 的 Hyper-V 虚拟交换机，会劫持或限制 localhost 的 WebSocket 连接。这会导致 ws://127.0.0.1:18780 这个网关地址无法建立连接，即使所有服务都正常。

如何验证是否是网络策略问题？

执行这个命令，测试本地 WebSocket 是否可达：

• 如果返回 connected，说明网络通畅，问题不在这一层
• 如果卡住几秒后报 Error: connect ECONNREFUSED 127.0.0.1:18780，说明网关进程没起来（回到方法一）
• 如果报 Error: read ECONNRESET 或 Error: socket hang up，大概率是网络策略拦截

解决方案（三选一）：

• 换用 127.0.0.1 替代 localhost（最简单）：
  • 在 clawdbot.json 中，把所有 localhost 改成 127.0.0.1，包括 baseUrl 和网关绑定地址。
• 关闭可能干扰的软件：
  • 临时退出腾讯电脑管家、360安全卫士、Windows Defender 实时防护，再试。
• 强制指定网关监听地址（终极方案）：
  • 启动 ClawdBot 时，显式指定网关绑定到 127.0.0.1：

小技巧：国内用户建议在 ~/.bashrc 中添加别名，避免每次输入长命令：

8. 总结：一张表看清5种方法的适用场景与执行顺序

当你再次看到 Gateway not reachable 时，不要再从头百度。按下面这张表，30秒内定位问题根源：

记住一个原则：ClawdBot 的设计哲学是“可见、可查、可修”。每一个错误背后，都有对应的日志、进程和配置项。你不需要成为系统专家，只需要学会用 ps、grep、cat 这三个命令，就能掌控全局。

最后提醒一句：ClawdBot 的价值，不在于它多酷炫，而在于它把 AI 的控制权，稳稳交还到你手中。那个 Gateway not reachable 的报错，不是障碍，而是系统在对你说：“嘿，我们之间的连接需要你亲手确认一下。”