AI Agent通知推送到Slack/Discord/Telegram:agent-notifications Webhook集成完整教程

原创2026-10-26 12:23:031,686 阅读

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 即可:

agent-notifications 通知设置页面:选择 Agent 后按步骤完成安装

安装完成后,用 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 端收到的消息内容与桌面保持一致:

agent-notifications 桌面通知效果:问题待回答、计划待确认、任务完成三种状态

Webhook 端的核心发送逻辑在 internal/webhook/webhook.go,消息排版则由 internal/webhook/formatters.go 中的平台格式化器负责。

三种平台接入步骤

三个平台的差异只在"去哪里拿 Webhook URL",写入配置的步骤完全相同。

Slack:三步创建 Incoming Webhook

  1. 到 Slack 应用后台创建新 App,并启用 Incoming Webhooks;
  2. 添加 Webhook 时选择目标频道(私有频道需先加入),完成授权;
  3. 复制生成的 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

  1. 打开服务器设置 → Integrations → Webhooks,点击 New Webhook;
  2. 设置名称(如 "Agent Notifications")并选择目标频道,可上传自定义头像;
  3. 复制 URL 写入配置:
{
  "notifications": {
    "webhook": {
      "enabled": true,
      "preset": "discord",
      "url": "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
    }
  }
}

Discord 消息以富 Embed 形式展示,标题、正文、页脚、时间戳一应俱全;以后想换频道只需在 Discord 后台修改,URL 不变。

Telegram:三步创建 Bot 推送

  1. 在 Telegram 中找 @BotFather,发送 /newbot 创建 Bot,保存它给出的 API Token;
  2. 先给你的 Bot 发一条消息,再通过 getUpdates 接口查到 chat.id(群聊的 ID 为负数);
  3. 把 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 用加粗标题呈现,效果示例:

agent-notifications 推送的消息类型:任务完成、提问、权限请求与错误提醒

如果只想收桌面通知、不想让某个状态打扰群里,可以在 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。

安全最佳实践 ✅

  1. URL 和 Token 视同密码:只放在配置文件中,绝不写进代码仓库;
  2. 定期轮换:Webhook URL、Bot Token 建议每几个月更换一次;
  3. 专用频道/专用 Bot:为通知单独建频道(如 #agent-notifications),减少干扰也便于限权;
  4. 只使用 HTTPS 端点,异常流量可通过 Webhook 指标及时发现。

延伸阅读

配置完成后,无论是 Slack 频道、Discord 服务器还是 Telegram 私有聊天,你的 AI Agent 都会在最需要你的时刻准时"上线报到"。

登录后查看全文
agent-notifications