凌晨两点，人最容易犯两种错： 一种是冲动下单，一种是决定折腾 AI Agent。
你把 ClawdBot/MoltBot 拉下来，npm install 一跑，配置一写，甚至还挺有仪式感地发出第一条消息。
然后它给你表演一招：沉默是金。
页面能打开，按钮能点，日志一堆红字像外星语。你去翻文档，文档像在说：“你肯定懂的。”你去翻 Issues，复制粘贴三个方案，越改越乱。
这种场景我见得太多了。 我在 MoltBot当“技术急诊”的那段时间，小螃蟹 Crabby 一周回了 4800+ 条求助。你能踩的坑，大家基本都踩过。很多坑甚至不是技术问题，是“人类输入法问题”。
结论先丢这：ClawdBot/MoltBot 最可怕的不是报错，而是看起来一切正常，但就是不工作。 这种最耗命。
下面这份清单，你可以当成“凌晨三点急救箱”。别指望临时去搜，真的到了 debug 时刻，你只会疯狂翻聊天记录，然后骂自己一句：怎么没收藏。
四个最常见的“杀手级坑”
先把最致命的几类拎出来，你遇到问题时就按这个顺序排查，省时间：
- API Key 有问题（错了、过期了、没额度了、复制带了隐形字符）
- Node 版本太老（系统自带的那种，专门坑人）
- 配置层级写错（你以为写了，其实没生效）
- Docker 容器没重建（你改了配置，它压根没读到）
🔴 安装篇：别把“下一步”交给猜
群里被问爆的一句是：“装好了，下一步怎么做？” 不是大家笨，是文档默认你知道一堆“潜规则”。
最稳的启动流程长这样（照抄就行）：
# 1) 先确认 Gateway 跑起来了
clawdbot status
# 2) 配置 AI 提供商（二选一）
clawdbot config set openai.apiKey YOUR_KEY
# 或
clawdbot config set anthropic.apiKey YOUR_KEY
# 3) 启动
clawdbot gateway start
✅ 症状：Web 能访问，但发消息没回复
这玩意儿最阴间。界面像没事人一样，消息像石沉大海。
99% 是 API 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 版本。 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": { }
}
}
最常见的坑：层级写错
这个坑我纠正过不下 50 次。 大家都会说一句：“我配置了啊，但就是不生效。”
典型错误是把 sandbox 放错地方：
- ❌ 错误：
agents.defaults.sandbox - ✅ 正确：
agents.main.sandbox
记住一句人话： defaults 像“模板”，main 才是“你真正跑的那台机器”。
反代/第三方代理怎么配？
比如你用 Antigravity 或自建 proxy：
{
"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
不删旧容器的效果就是： 你改你的，它跑它的。你气你的，它装死它的。
✅ 症状：改了配置但没生效
完整流程就三步：
# 1) 改配置（编辑 clawdbot.json）
# 2) 删旧容器
docker rm -f $(docker ps -aq --filter name=clawdbot)
# 3) 重启
clawdbot gateway restart
偷懒版也给你：
如果你只是改 AI 参数（不涉及 sandbox），直接 clawdbot gateway restart 通常够用。
🟢 平台集成篇：Discord/Telegram 新手必踩坑
Discord 怎么加 Bot？
流程别想复杂，照做：
- 去 Discord Developer Portal
- Create 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 在群里响应：
要么关隐私模式，要么每条消息都 @它。不然它装聋作哑，不是 bug，是机制。
🔵 Gateway 篇：启动失败别慌，抓日志就行
遇到 Gateway 启动失败，别上来就重装。 你要做的就三件事：
clawdbot status
clawdbot gateway logs --tail 50
clawdbot gateway restart
常见原因基本就这些：
- 端口被占用（默认 3000）→ 换端口或杀掉占用进程
- 配置文件语法错 → 用 jq 验证
- API Key 无效/没额度 → 回到安装篇看日志关键词
配置文件语法验证（强烈建议你常用）：
cat ~/.clawdbot/clawdbot.json | jq .
✅ 症状：浏览器控制报错 Can't reach control server
想让 Agent 操作浏览器，结果报这个。
先确认 Gateway 在跑：
clawdbot status
clawdbot gateway restart
多数时候重启就能解决。 如果不行，再回去看日志，别跟它硬刚。
写在最后：这篇文章的意义很简单
这份“踩坑全集”不是为了显得我多懂。 是为了让你下次遇到问题时，别把宝贵的夜晚浪费在无效搜索上。
你踩的坑，通常不是你一个人的问题。 你把坑写出来，下一个凌晨三点的人就少掉一小时焦虑。
我会持续更新这份清单。Crabby 在社区里看到新的高频问题，我就会补进去。