《Agent 如何将消息触达到微信》

前段时间，我把 Agent 和几个自动化程序接进了自己的通知系统：任务跑完、网站有新专栏、每天筛出的生财有术内容，都会到微信里提醒我。

前段时间，我把 Agent 和几个自动化程序接进了自己的通知系统：任务跑完、网站有新专栏、每天筛出的生财有术内容，都会到微信里提醒我。发了朋友圈后，很多朋友来问：这个消息到底是怎么触达到微信的？没有服务器能不能做？能不能让自己的 Agent 也接上？

答案是能，而且第一步没有想象中复杂。

这篇文章就带你搭一条“Agent / 程序 → 个人微信”的通知链路。你不需要先有服务器：电脑上装了 Hermes，就可以把触达程序也放在电脑上；以后想让任务每天自动跑、电脑关机也不受影响，再迁到服务器。

先把边界说清楚：这不是登录个人微信、模拟客户端，也不是往普通微信群塞机器人。它走的是企业微信官方能力：企业微信自建应用发消息，你在个人微信里关注微信插件（WeChat Workplace）后接收。它适合给自己和企业成员发提醒，不适合给外部微信用户做批量群发。

读完这篇，你应该能完成两件事：先让一条“测试成功”消息出现在个人微信；再让你的 Agent 或网站在任务完成时主动通知你。你也可以把“第五步：交给 Agent 实现”原样发给自己的 Agent。

先选你的起点：本地电脑，还是服务器？

你的情况	现在怎么做	以后要不要迁移
想先体验，电脑平时会开着	Hermes、通知网关、脚本都装在本地电脑	不一定；电脑关机时任务不会跑
想每天固定时间执行，不依赖电脑	把 Hermes、通知网关和定时程序放到 VPS	推荐；能稳定运行、出口 IP 固定

核心原则很简单：Agent 在哪里运行，通知网关就可以先放在哪里。

本地模式里，Agent 和通知网关走 127.0.0.1 通信，不需要把端口暴露到公网。服务器的价值只是 7×24 在线、固定公网 IP，以及让 GitHub Actions 等外部服务能通过 HTTPS 调用它；不是使用通知系统的前提。

你最终要搭出的东西长什么样？

不要让每个项目各自保存企业微信的密码。你只需要搭一个通知网关，让所有项目调用它：

本地 Hermes / 本地脚本 / GitHub Actions / VPS 上的 Agent
                         │
                POST /v1/notify + API Key
                         │
                         ▼
           Notification Hub（本地或服务器）
                         │
                    企业微信官方 API
                         │
                         ▼
      企业微信自建应用 → 微信插件 → 个人微信

以后新接一个项目，只要让它发一次 HTTP 请求。企业微信的 CorpID、AgentID、Secret 不会散落在 GitHub、Agent 配置和各种脚本里。

第一步：把企业微信和个人微信打通

这一段只需要做一次。打开企业微信管理后台。

跟着下面做：

注册一个企业微信组织，组织里只有你自己也可以。

进入“应用管理”，创建一个自建应用；可见范围选组织里想通知的人。

记下 CorpID、AgentID、Secret：AgentID 和 Secret 就在当前这张“自建应用”页面；CorpID 在左侧“我的企业 / My Company → 企业信息 / Company Info”里，通常以 ww 开头。Secret 相当于应用密码：不要提交到 Git，不要放截图，也不要发到聊天记录。

在“企业可信 IP”里加入实际调用企业微信 API 的机器的公网出口 IP。本地测试时填本地网络当前出口 IP；长期运行时填 VPS 的固定 IP。

在“我的企业”里找到“微信插件 / WeChat Workplace”，用个人微信扫码关注，并打开“接收应用消息”。

做完后先别急着写代码。你要知道一个常见坑：企业微信客户端收得到，不代表个人微信一定收得到。个人微信必须已关注微信插件；同时检查企业微信端没有开启“仅在企业微信中接收”。

这一步的验收标准： 你已经拿到 3 个配置值，个人微信也已经关注微信插件。

第二步：部署一个只干“触达”的 Notification Hub

通知网关不需要很复杂。它只要提供两个接口：

GET  /healthz       # 查看服务是否活着
POST /v1/notify    # 发送一条通知

如果你在本地使用，让它监听 127.0.0.1:8080 即可；Hermes、Python 脚本或其他本地程序都调用 http://127.0.0.1:8080/v1/notify。如果你在 VPS 部署，也建议服务仍只监听 127.0.0.1:8080，再由 Nginx 提供 HTTPS 给 GitHub Actions 或其他外部调用方。

给通知网关准备一份只保存在部署机器上的配置：

LISTEN_ADDR=127.0.0.1:8080
NOTIFY_API_KEY=换成随机生成的长字符串
NOTIFY_RATE_LIMIT_PER_MINUTE=5
WECOM_CORP_ID=你的企业ID
WECOM_AGENT_ID=你的应用AgentID
WECOM_SECRET=你的应用Secret
WECOM_TO_USER=自己的企业微信成员账号

一条通知能发给多个人吗？

可以。WECOM_TO_USER 填的是企业微信成员账号，多个成员用 | 分隔：

WECOM_TO_USER=zhangsan|lisi|wangwu

这样每次通知都会同时发给这三个人。若填写 @all，则会发送给这个自建应用可见范围内的全部成员。企业微信应用消息的单次成员接收者最多支持 1000 人。

但它不是“给任意微信号群发”的通道：收件人必须是你的企业微信成员，并且在该自建应用的可见范围内；想在个人微信收到消息的人，还需要各自关注微信插件。

它收到请求后应当做 5 件事：校验 Bearer Token；校验标题、正文和 URL；限制消息长度；获取并缓存企业微信 access_token；调用企业微信的应用消息接口。Token 失效时，清缓存、重新获取并重试一次。

Notification Hub 是怎样调用企业微信 API 的？

关键不在 Agent。Agent 只请求你的 /v1/notify；真正持有企业微信凭据、并调用企业微信 API 的，是 Notification Hub。完整链路是：

Agent / 定时程序
  └─ POST /v1/notify（携带你的 NOTIFY_API_KEY）
       └─ Notification Hub
            ├─ GET  https://qyapi.weixin.qq.com/cgi-bin/gettoken
            │       ?corpid=WECOM_CORP_ID&corpsecret=WECOM_SECRET
            └─ POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=...
                 └─ 企业微信自建应用 → 微信插件 → 个人微信

拿到 access_token 后，网关发送的核心请求就是下面这样（值都从服务器环境变量读取，不要把 Secret 写进 Agent 提示词或代码仓库）：

{
  "touser": "你的企业微信成员账号",
  "msgtype": "text",
  "agentid": 1000003,
  "text": {
    "content": "《测试成功》\n这条消息已经从程序触达到个人微信。"
  }
}

也就是说，CorpID + Secret 用来换取短期的 access_token，AgentID 标识由哪个自建应用发出，touser 决定发给谁。你自己的程序只需要认识 Notification Hub 的地址和 NOTIFY_API_KEY，不应该直接接触企业微信 Secret。

别省掉安全措施：API Key 应当只交给调用方，企业微信 Secret 只留在网关；服务日志不要记录 Secret、Authorization 和通知正文；本地端口不要暴露公网；服务器模式再加 HTTPS 和限流。你会不断给它接入新项目，边界要先划好。

这一步的验收标准： 访问 /healthz 返回正常；企业微信 Secret 只存在网关配置里。

第三步：发出第一条测试消息

不管你后面要接 Agent 还是网站，先用这一条请求验证整条链路。把域名、API Key 和链接替换成自己的：

curl --fail-with-body -X POST "https://你的域名/v1/notify" \
  -H "Authorization: Bearer $NOTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "title": "测试成功",
    "content": "这条消息已经从程序触达到个人微信。",
    "url": "https://example.com"
  }'

本地部署时，把 URL 换成 http://127.0.0.1:8080/v1/notify。成功响应应包含 status=delivered 和 request_id；个人微信会收到同一条消息。

如果接口成功但微信没有消息，按这个顺序排查：个人微信是否关注微信插件 → 企业微信是否允许接收应用消息 → 应用可见范围里是否包含你 → 可信 IP 是否是当前出口 IP。不要一上来怀疑 Agent。

这一步的验收标准： 你在个人微信里看到《测试成功》。

第四步：让消息值得被打扰

通知系统不是“什么都发”。先接这三类高价值、低频事件：

失败提醒：部署失败、备份失败、定时任务异常。
结果提醒：日报生成、数据同步完成、Agent 任务完成。
机会提醒：出现新订单、新内容、新课程或任何需要你现在处理的变化。

每条消息都尽量回答：发生了什么？为什么我现在要看？下一步点哪里？少发“系统正常运行”，多发真正需要你行动的结果。我的网关将最终消息控制在 2000 UTF-8 字节内，长内容放到网页或报告，把链接放进通知。

第五步：把这一段发给 Agent，让它替你接入

如果你已经有 Hermes、Codex 或其他 Agent，直接把下面这段需求发给它即可：

请为我部署一个个人微信通知网关。

部署位置：本地电脑 / 我的 VPS（二选一）。
目标：提供 GET /healthz 和 POST /v1/notify；调用企业微信自建应用，最终让我在个人微信的微信插件里收到消息。

安全要求：
1. 企业微信 CorpID、AgentID、Secret 只放在部署机器的受限环境文件，绝不写入 Git、日志或命令输出。
2. 调用方只使用独立的 NOTIFY_API_KEY；网关校验 Bearer Token、限制消息长度和频率。
3. 本地模式只监听 127.0.0.1；VPS 模式也只监听 127.0.0.1，由 Nginx 提供 HTTPS。
4. 缓存企业微信 access_token；失效后重新获取并重试一次。
5. 实现后用 curl 发送《测试成功》，并告诉我健康检查、接口调用和个人微信三处的验证结果。

接口 JSON：{"title":"必填","content":"可选","url":"可选的 HTTP/HTTPS 链接"}。

把第 1 步拿到的企业微信配置，按 Agent 要求在部署机器上填写即可。不要把 Secret 直接贴进 Agent 对话；更稳妥的做法是自己在服务器或本地的环境文件里填写，再让 Agent 读取变量名。

两个已经接入的真实场景

1. 生财有术 MCP：把“该看什么”送到微信

我的 Hermes 放在北京服务器上，调用生财有术 MCP 检索全站帖子。任务会按主题去重，补上阅读、点赞、评论数据，整理成“3 篇必读 + 2 篇扩展阅读”，再由触达程序推到微信。亦仁、刘小排这类重点作者也可以单列观察。

结果不是“今天有几篇新帖”，而是标题、数据、推荐理由和生财链接都在一条消息里，我能直接判断要不要点开。

说明：文中的帖子数据通过生财有术面向圈友开放的 MCP 获取；亦仁已邀请圈友使用，该能力目前仍处于内测阶段。

下面两张图分别展示 MCP 的接入入口和它能做的事情：

2. 极客时间网站：专栏上新时提醒我

我的极客时间网站是 geektime.baiyalab.com。它会同步可推广课程、价格、返现金额和专属推广链接。当同步程序发现有新专栏、并且已经拿到有效推广短链时，才会发一条微信：课程名、作者、售价、返现金额和进入网站的链接一次给全。

网站负责展示和跳转；同步程序负责发现“真的有变化”；Notification Hub 只负责把结果送到微信。你也可以照这个分工，把自己的博客、订单站、内容站或数据看板接进来。

最后记住两条边界

第一，终点是企业微信应用消息在个人微信里的微信插件入口，不是普通个人微信 API。请不要承诺任意微信用户都能收到，也不要把它当营销群发工具。

第二，Secret 永远只留在网关。GitHub Actions、Agent 和其他项目只保存它们各自的通知 API Key；某个 Key 泄露时单独轮换，不会牵连整个企业微信应用。

你现在最该做的，不是一次接十个系统。先让《测试成功》到微信；再挑一个你每天都会漏看的任务接进来。通知系统真正的价值，不是让你收到更多消息，而是让重要的结果能及时找到你。