AI Agent通知推送到Slack/Discord/Telegram:agent-notifications Webhook集成完整教程
AI Agent通知推送到Slack/Discord/Telegram:agent-notifications Webhook集成完整教程
agent-notifications 是一款面向 Claude Code、Codex、OpenCode、Cursor、Gemini CLI 等 AI 编程助手的跨平台通知工具,除了桌面通知和提示音,它的 Webhook 集成可以把 AI Agent 的状态实时推送到 Slack、Discord、Telegram(还支持 Lark/飞书和自定义端点)。按照本教程,新手约 10 分钟即可完成配置,人不在电脑旁时也不会错过 Agent 的"任务完成"和"需要回答"信号。
安装工具并确认生效
如果还没有安装 agent-notifications,先通过安装向导把桌面通知配好,Webhook 是在同一份共享配置上追加的能力。安装页面会引导你选择 Agent(Claude Code 或 Codex CLI),复制安装命令到终端执行,然后重启 CLI 即可:
安装完成后,用 config path 可以定位共享配置文件的位置,用 config inspect 可以查看当前生效的设置。所有 Webhook 选项都写在同一份 config/config.json 的 notifications.webhook 节点下:
{
"notifications": {
"webhook": {
"enabled": false,
"preset": "slack",
"url": ""
}
}
}
配置完成后你能得到什么 📬
开启 Webhook 后,Agent 的每个关键状态都会同时走两条通道:
- 桌面通道:弹窗 + 提示音,点击通知可直接聚焦回终端;
- IM 通道:按平台格式推送到 Slack/Discord/Telegram,带颜色标识、会话名和时间戳,团队群里一目了然。
macOS 上的桌面效果如下,IM 端收到的消息内容与桌面保持一致:
Webhook 端的核心发送逻辑在 internal/webhook/webhook.go,消息排版则由 internal/webhook/formatters.go 中的平台格式化器负责。
三种平台接入步骤
三个平台的差异只在"去哪里拿 Webhook URL",写入配置的步骤完全相同。
Slack:三步创建 Incoming Webhook
- 到 Slack 应用后台创建新 App,并启用 Incoming Webhooks;
- 添加 Webhook 时选择目标频道(私有频道需先加入),完成授权;
- 复制生成的 URL(形如
https://hooks.slack.com/services/...),写入配置:
{
"notifications": {
"webhook": {
"enabled": true,
"preset": "slack",
"url": "https://hooks.slack.com/services/T00000000/B00000000/XXXX"
}
}
}
⚠️ Webhook URL 相当于频道发帖凭证,拿到后请妥善保管,不要提交到 git。
Discord:三步创建 Webhook
- 打开服务器设置 → Integrations → Webhooks,点击 New Webhook;
- 设置名称(如 "Agent Notifications")并选择目标频道,可上传自定义头像;
- 复制 URL 写入配置:
{
"notifications": {
"webhook": {
"enabled": true,
"preset": "discord",
"url": "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
}
}
}
Discord 消息以富 Embed 形式展示,标题、正文、页脚、时间戳一应俱全;以后想换频道只需在 Discord 后台修改,URL 不变。
Telegram:三步创建 Bot 推送
- 在 Telegram 中找 @BotFather,发送
/newbot创建 Bot,保存它给出的 API Token; - 先给你的 Bot 发一条消息,再通过
getUpdates接口查到chat.id(群聊的 ID 为负数); - 把 Bot API 的
sendMessage地址和chat_id一起写入配置:
{
"notifications": {
"webhook": {
"enabled": true,
"preset": "telegram",
"url": "https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage",
"chat_id": "123456789"
}
}
}
注意 Telegram 比前两者多一个必填项 chat_id;Bot 必须先被用户发起过对话,否则会被拒绝发送(403)。
快速验证是否打通
配置保存后,用项目文档给出的最小测试事件发一条通知,几秒内 IM 频道就会出现测试消息:
echo '{"session_id":"test","tool_name":"ExitPlanMode"}' | \
bin/claude-notifications handle-hook PreToolUse
详细步骤可对照官方分平台指南:Slack、Discord、Telegram。
可靠性配置:重试、熔断器与限流 🔧
agent-notifications 的 Webhook 内置了生产级可靠性机制,对应源码分别在 internal/webhook/retry.go、internal/webhook/circuitbreaker.go 和 internal/webhook/ratelimiter.go:
| 机制 | 作用 | 关键参数 |
|---|---|---|
| 指数退避重试 | 5xx / 429 / 网络错误自动重试 | maxAttempts(默认 3)、initialBackoff、maxBackoff |
| 熔断器 | 连续失败自动"断开",防止级联故障 | failureThreshold、successThreshold、timeout |
| 令牌桶限流 | 避免超过平台 API 限额 | requestsPerMinute |
一份兼顾可靠与性能的推荐配置(详见 docs/webhooks/configuration.md):
{
"notifications": {
"webhook": {
"enabled": true,
"preset": "slack",
"url": "https://hooks.slack.com/services/...",
"retry": { "enabled": true, "maxAttempts": 3, "initialBackoff": "1s", "maxBackoff": "10s" },
"circuitBreaker": { "enabled": true, "failureThreshold": 5, "successThreshold": 2, "timeout": "30s" },
"rateLimit": { "enabled": true, "requestsPerMinute": 20 }
}
}
}
限流数值建议贴合平台限额:Slack 约 20/分钟、Discord 约 30/分钟、Telegram 可到 60/分钟。
5 种通知状态与颜色编码 🎨
系统会自动识别 Agent 的运行状态并格式化推送,桌面与 IM 共用同一套语义:
| 状态 | 标题 | 标识 |
|---|---|---|
task_complete |
✅ Task Completed | 绿色 |
plan_ready |
📋 Plan Ready | 蓝色 |
question |
❓ Has Questions | 黄色 |
review_complete |
🔍 Review Complete | 青色 |
session_limit_reached |
⏱️ Session Limit Reached | 橙色 |
Slack 用左侧色条区分、Discord 用 Embed 颜色、Telegram 用加粗标题呈现,效果示例:
如果只想收桌面通知、不想让某个状态打扰群里,可以在 statuses.<name>.webhook 下单独关闭该状态的 webhook 通道,桌面通知不受影响。
常见问题排查清单 🛠
| 症状 | 优先检查 |
|---|---|
| IM 完全收不到 | enabled 是否为 true;用 curl 手动 POST 测试 URL 是否可用;看日志 tail -f notification-debug.log | grep webhook |
| Discord 返回 404 | Webhook 被删除或 URL 拼错,到后台重新复制 |
| Telegram 返回 401 | Bot Token 不完整或已失效,确认包含 数字:字母 两段 |
| Telegram 返回 403 | 未先给 Bot 发过消息,Bot 不能主动发起会话 |
| 频繁 429 | 触发平台限流,调低 requestsPerMinute |
每条请求都带有 X-Request-ID,可在本地日志与服务端日志间关联排查。完整故障树与监控指标说明见 docs/webhooks/troubleshooting.md 与 docs/webhooks/monitoring.md。
安全最佳实践 ✅
- URL 和 Token 视同密码:只放在配置文件中,绝不写进代码仓库;
- 定期轮换:Webhook URL、Bot Token 建议每几个月更换一次;
- 专用频道/专用 Bot:为通知单独建频道(如
#agent-notifications),减少干扰也便于限权; - 只使用 HTTPS 端点,异常流量可通过 Webhook 指标及时发现。
延伸阅读
- Webhook 总览与功能清单:docs/webhooks/README.md
- 重试/熔断/限流参数参考:docs/webhooks/configuration.md
- 自定义端点与模板变量(
${{git.branch}}、${{env.TOKEN}}等):docs/webhooks/custom.md - 推送载荷的 JSON Schema:docs/webhooks/payload-schema.json
- Webhook 发送器源码:internal/webhook/
配置完成后,无论是 Slack 频道、Discord 服务器还是 Telegram 私有聊天,你的 AI Agent 都会在最需要你的时刻准时"上线报到"。


