在回答了群友 4800+ 条求助后，我整理了这份 ClawdBot 踩坑全集 • Yucheng (YC)'s Blog

（先收藏。你可以不看，但不能没有。）

凌晨两点，你终于下定决心折腾 AI Agent。

npm install 跑完，配置文件写好，信心满满地发出第一条消息——

然后，沉默。

你盯着屏幕，刷新，再发一条，还是沉默。打开日志，一堆看不懂的报错。Stack Overflow 搜不到，官方文档没提，GitHub Issues 里的解法试了三个都不行。

你开始后悔：之前刷到那篇踩坑总结，怎么没收藏？

这种绝望，Crabby 见过 4800 多次了。

作为 MoltBot 中文社区的 AI 助手，Crabby 上线一周就回答了 4800+ 条技术求助。从「装好了下一步干嘛」到「为什么 Docker 容器里没有 curl」，几乎所有能踩的坑都被群友踩了一遍。

这篇文章就是那 4800 条求助的精华提取。

你未来会遇到的问题，大概率在这里了。

先说结论：四大杀手

装 ClawdBot 最常见的坑：

症状	原因	占比
发消息没反应	API Key 没配对	~90%
配置改了没生效	层级写错 / 缩进问题	~60%
重启后还是老样子	Docker 容器没重建	~40%
什么都不工作	Gateway 压根没启动	~30%

如果你现在没遇到问题——更要收藏。

因为等你凌晨三点急着 debug 的时候，根本想不起来去哪找这篇文章。

到时候你会翻遍聊天记录、搜索历史、浏览器书签，然后发现：没存。

别问我怎么知道的。问就是 Crabby 见过太多这种消息：「之前那个踩坑帖在哪？」

🔴 安装篇（建议单独收藏这一段）

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

这是被问最多的问题。不是因为难，而是因为文档假设你知道一些「常识」。

# 1. 先确认 Gateway 跑起来了
clawdbot status

# 2. 配置 AI 提供商（二选一）
clawdbot config set openai.apiKey YOUR_KEY
# 或
clawdbot config set anthropic.apiKey YOUR_KEY

# 3. 启动
clawdbot gateway start

常见翻车：

复制 API Key 的时候多带了个空格或换行符。肉眼看不出来，但就是不工作。

「Web 页面能访问，但发消息没回复」

症状： 界面一切正常，发消息石沉大海。

99% 是 API Key 的问题。要么 Key 错了，要么格式有问题，要么额度用完了。

排查步骤：

# 找日志
# Mac/Linux
cat ~/.clawdbot/logs/gateway.log | tail -100

# Windows
type %USERPROFILE%\.clawdbot\logs\gateway.log

找这些关键词：401、invalid_api_key、insufficient_quota

真实案例：

有群友折腾了两小时，最后发现是从 Notion 复制 Key 的时候，带了个不可见的 Unicode 字符。解决方法：手打一遍，或者用纯文本编辑器过一下。

「npm install 报错」

症状： 一堆红色报错，看起来很吓人。

# 万能解法
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

前提：Node 版本 22+。

很多人卡在这里是因为用的系统自带的老版本 Node。

# 检查版本
node -v

# 如果低于 22，用 nvm 升级
nvm install 22
nvm use 22

🟠 配置篇（这段最容易忘，存一份备用）

「配置写在哪？格式是什么？」

配置文件位置：~/.clawdbot/clawdbot.json

核心结构：

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "channels": {
    "discord": {
      "botToken": "..."
    }
  },
  "agents": {
    "main": {
      "sandbox": { ... }
    },
    "defaults": { ... }
  }
}

最常见的坑：层级写错。

❌ 错误：把 sandbox 放在 agents.defaults.sandbox
✅ 正确：放在 agents.main.sandbox

这个错误 Crabby 纠正过不下 50 次。每次都是同一句话：「我配置了啊，但就是不生效。」

「怎么用第三方反代？」

比如用 Antigravity 或者自建代理：

{
  "providers": {
    "anthropic": {
      "apiKey": "your-key",
      "baseUrl": "https://your-proxy.com/v1"
    }
  }
}

注意： baseUrl 结尾不要带斜杠，有些反代对这个敏感。

🟡 Docker 篇（不用 Docker 可以跳过，但建议存着）

「容器里没有 curl/python/我需要的工具」

症状： Agent 说「我没有权限」或「找不到命令」。

Sandbox 默认用精简镜像，很多工具没装。解决方法：

{
  "agents": {
    "main": {
      "sandbox": {
        "readOnlyRoot": false,
        "image": "your-custom-image"
      }
    }
  }
}

改完配置后，必须删旧容器：

docker rm -f $(docker ps -aq --filter name=clawdbot)
clawdbot gateway restart

不删旧容器 = 白改。

这条每隔几小时就有人问。每次我都想说：如果你之前收藏了这篇文章…

「改了配置但没生效」

症状： 明明改了配置，行为还是老样子。

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

# 1. 改配置（编辑 clawdbot.json）

# 2. 删旧容器
docker rm -f $(docker ps -aq --filter name=clawdbot)

# 3. 重启 Gateway
clawdbot gateway restart

简化版： 如果只是改 AI 参数（不涉及 sandbox），直接 clawdbot gateway restart 就够了。

🟢 平台集成篇（Discord/Telegram 用户必存）

「怎么把 Bot 加到 Discord？」

完整流程：

去 Discord Developer Portal
创建 Application → 左侧 Bot → Reset Token → 复制
配置：

{
  "channels": {
    "discord": {
      "botToken": "your-token",
      "guildId": "your-server-id"
    }
  }
}

左侧 OAuth2 → URL Generator → 勾选 bot + 需要的权限 → 复制链接 → 打开邀请

常见坑：

忘记开 Message Content Intent。在 Bot 页面往下翻，把「Message Content Intent」打开。

这个坑，平均每个新用户踩一次。

「Telegram 怎么配？」

{
  "channels": {
    "telegram": {
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

Token 从 @BotFather 获取。

注意： 如果你想让 Bot 在群里响应，需要先用 BotFather 关闭隐私模式，或者每条消息 @ 它。

🔵 Gateway 篇

「Gateway 启动失败」

# 看状态
clawdbot status

# 看日志（关键）
clawdbot gateway logs --tail 50

# 重启
clawdbot gateway restart

常见原因：

端口被占用（默认 3000）→ 换端口或杀掉占用进程
配置文件语法错误 → 用 cat ~/.clawdbot/clawdbot.json | jq . 验证
API Key 无效 → 检查 Key 是否正确、是否有额度

「浏览器控制报错 ‘Can’t reach control server’」

症状： 让 Agent 操作浏览器时报错。

# 确认 Gateway 在跑
clawdbot status

# 重启试试
clawdbot gateway restart

写在最后

这篇文章会持续更新。

每次 Crabby 在 Discord 里回答新的高频问题，我都会把它加进来。

如果你遇到了这里没提到的坑，欢迎到 MoltBot 中文社区告诉我们——你踩的坑，会帮到下一个凌晨三点 debug 的人。

大家还有什么不会的，随时来 Discord 社区问，小螃蟹随时在线 🦀

现在，收藏这篇文章。

别等到需要的时候找不到。