部署AI Agent踩了25个坑，帮你省3天时间

结论先行：把AI团队搬进Telegram群，文档上说"简单配置即可"，实际踩了25个坑才跑通。这篇把最疼的10个坑拎出来，你照着避就行了。

上周搭了一套多Agent系统——5个AI Bot在Telegram群里协作工作。看文档觉得不难，实际一动手，断断续续搞了快3天。

不是技术难，是细节多。而且文档不会告诉你这些坑。

直接上干货。

坑1：模型名不对，403报了一天

症状： API Key明明是对的，但Bot一直报 HTTP 403: This token has no access to model

根因： OpenClaw配置里写的模型名和API供应商支持的模型名不一致。

比如你在供应商后台买的是"Claude Sonnet"，但OpenClaw里填的是"claude-sonnet-4-20250514"——名字差一个字就报403。

解决： 先问API供应商他们支持哪些模型名，再填到配置里。不要猜。

坑2：groups配置放错位置，所有Bot抢着回复同一条消息

症状： 你在选题话题里发消息，写手Bot、编辑Bot、分发Bot全部跳出来回复

根因： groups配置写在了 telegram 顶层，而不是放在每个account内部。

解决： groups必须放在每个Bot自己的账号配置里。每个Bot只在自己的话题 requireMention: false（自由回复），其他话题全部设 groupPolicy: disabled。

// 正确写法：每个account自己管自己的"accounts":{"steward":{"botToken":"...","groups":{"-100123456":{"topics":{"管家话题ID":{"requireMention":false},"写手话题ID":{"requireMention":true,"groupPolicy":"disabled"}}}}}}

坑3：Bot加进群了但不说话

症状： Bot在私聊能正常回复，拉进群就装死，日志还没报错

根因： 两个原因，按顺序查：

1. Privacy Mode没关 — 去BotFather发 /setprivacy，选你的Bot，点Disable
2. Bot不是管理员 — 群管理员把Bot设为管理员

解决： 两个都做一遍，然后发消息测试。

坑4：换API后Bot继续报401

症状： API供应商的Key过期了，换了新的，改了环境变量，重启了Gateway，Bot还是报401

根因： API配置在OpenClaw里分散在三个地方，你只改了其中一个。

最害人的是第三个 — models.json里硬编码了API Key和地址，Gateway实际请求时以它为准。你改了一万遍环境变量都没用。

解决： 用一个脚本批量更新所有Agent的models.json，三处改完再重启。

坑5：Bot在群里不回，私聊正常

症状： 跟坑3类似但更隐蔽——Privacy Mode关了，也是管理员，还是不理群消息

根因： account配置里缺了 groupPolicy 字段。OpenClaw默认行为是没有groupPolicy就拒收所有群消息。

解决： 检查每个account配置，补上 "groupPolicy": "allowlist"。

# 一键检查哪些Bot漏了import jsond = json.load(open("/root/.openclaw/openclaw.json"))for k, v in d["channels"]["telegram"]["accounts"].items():if"groupPolicy"notin v:print(f"❌ {k}: 缺groupPolicy")

坑6：BotFather限流，一次只能建5个Bot

症状： 建了5个Bot后BotFather不理你了

根因： BotFather有频率限制，一次最多创建5个Bot，超了等24小时。

解决： 分两批创建。第一天建5个，第二天建剩下的。或者一开始就别搞太多，先2-3个核心角色跑起来，够了再扩展。

坑7：中文内容写入服务器报bash语法错误

症状： 在终端里用heredoc写入中文配置文件，报各种奇怪的语法错误

根因： Shell把中文引号、括号等特殊字符当成自己的语法了。

解决： 别用bash heredoc写中文。改成用Python脚本写文件，干干净净。

# 不要这样cat > file.md << 'EOF'【管家】负责「协调」工作EOF# 改成这样python3 -c "content = '''【管家】负责「协调」工作'''with open('file.md', 'w') as f:    f.write(content)"

坑8：groups写成了数组而不是对象

症状： Gateway启动报schema校验错误

根因： 看文档不仔细。groups必须是对象（key是群组ID字符串），不是数组。

// ❌ 错误"groups":[{"id":"-100xxx", ... }]// ✅ 正确"groups":{"-100xxx":{ ... }}

坑9：用户白名单格式写错

症状： 明明在白名单里加了你的用户ID，Bot还是不理你

根因： 白名单格式要求 "tg:你的用户ID"，不是纯数字。

// ❌ 错误"allowFrom":[7825541463]// ✅ 正确"allowFrom":["tg:7825541463"]

坑10：新增Bot忘了配AgentToAgent通信

症状： 新Bot加进来后，管家@不到它，其他Bot也调不动它

根因： 新增Agent时，tools.agentToAgent.allow 数组里没加新Bot的ID。

解决： 每次新增Bot，同步更新 openclaw.json 里的 tools.agentToAgent.allow 数组。

总结：避坑清单

如果你想自己搭一套，把这份清单打印出来，按顺序过：

部署前：

•  确认API供应商支持的模型名
•  先建2-3个Bot测试，别一次性搞5个

配置中：

•  groups在每个account内部配置
•  每个Bot只在自已的话题自由回复
•  白名单格式是 "tg:用户ID"
•  groups是对象不是数组
•  缺groupPolicy → Bot在群里不说话

换API时：

•  .bashrc
•  systemd服务文件
•  每个Agent的models.json
•  重启Gateway

新增Bot时：

•  关Privacy Mode
•  设为群管理员
•  配groupPolicy
•  更新agentToAgent.allow

技术这东西，踩坑才是最快的自学方式。但有些坑没必要自己踩一遍。

这篇收藏好，部署前过一遍清单，至少省3天。