四大核心问题

部署 ClawdBot 最常见的障碍集中在四个环节：安装依赖、配置文件、Docker 容器管理、平台集成。以下逐一拆解。

安装篇

"安装好了，下一步怎么做？"

这是出现频率最高的问题。不是因为步骤复杂，而是官方文档默认你已经具备一些前置知识。

API Key 问题（占故障的 99%）

症状：Web 界面正常加载，但发消息后没有任何响应。

排查步骤：

  • 检查日志中是否出现 401、invalid_api_key、insufficient_quota 等关键词
  • 确认 Key 是否正确粘贴——从 Notion 等富文本编辑器复制时，容易带入不可见的 Unicode 字符或多余的空格/换行符
  • 确认 API 额度是否充足

解决方法：用纯文本编辑器重新粘贴 Key，或直接手动输入。有用户为此折腾了两个小时，最终发现就是一个不可见字符的问题。

"npm install 报错"

看到一堆红色报错不要慌，首先确认 Node.js 版本是否为 22 及以上。很多人卡在这一步是因为使用了系统自带的旧版本 Node。

配置篇

配置文件的位置和格式

配置文件路径：~/.clawdbot/clawdbot.json

最常见的错误：层级写错。

  • 错误写法：把 sandbox 放在 agents.defaults.sandbox
  • 正确写法：放在 agents.main.sandbox

这个问题 Crabby 纠正过不下 50 次，表现都一样——"我配置了，但就是不生效。"

使用第三方反向代理

如果使用 Antigravity 或自建代理，注意 baseUrl 结尾不要带斜杠。部分反代服务对此敏感，会导致请求失败。

Docker 篇

"容器里找不到 curl/python 等工具"

症状：Agent 提示"没有权限"或"找不到命令"。

原因：Sandbox 默认使用精简镜像，很多常用工具未预装。需要在配置中指定自定义镜像或安装脚本。

关键操作：改完配置后必须删除旧容器。

不删旧容器等于白改——这条规则每隔几小时就有人重新发现一次。

"改了配置但没生效"

Docker 容器不会自动读取新配置。完整流程：

  1. 修改配置文件
  2. 删除旧容器
  3. 重启服务

简化场景：如果只修改了 AI 参数（不涉及 sandbox），直接执行 clawdbot gateway restart 即可。

平台集成篇

Discord 集成

  1. 前往 Discord Developer Portal，创建 Application
  2. 左侧菜单进入 Bot → Reset Token → 复制 Token
  3. 将 Token 写入 ClawdBot 配置
  4. 左侧 OAuth2 → URL Generator → 勾选 bot 及所需权限 → 复制链接 → 打开完成邀请

必踩坑：忘记开启 Message Content Intent。 在 Bot 页面向下滚动，找到并启用「Message Content Intent」。几乎每个新用户都会漏掉这一步。

Telegram 集成

从 BotFather 获取 Token，写入配置即可。

注意：如果需要 Bot 在群聊中响应消息，必须先通过 BotFather 关闭隐私模式，否则 Bot 只能在被直接提及时才会收到消息。

Gateway 篇

Gateway 启动失败

常见原因：

  • 端口占用（默认 3000）：换用其他端口或终止占用该端口的进程
  • 配置文件语法错误：用 cat ~/.clawdbot/clawdbot.json | jq . 验证 JSON 格式
  • API Key 无效：确认 Key 正确且有可用额度

浏览器控制报错 "Can't reach control server"

在让 Agent 执行浏览器操作时出现此错误，通常是浏览器控制服务未正确启动或网络配置有误，需检查相关服务状态。

实操建议

部署 AI Agent 的大部分问题不在于技术难度，而在于细节遗漏。建议在动手之前通读一遍常见问题清单，比出了问题再逐个排查要高效得多。如果遇到本文未覆盖的新坑，可以到 MoltBot 中文社区反馈——社区共建的排错经验，是个人摸索无法替代的。