agent-proactive-ping

Agent 主动推送（Agent Proactive Ping）

1. 定义

“Agent 主动 ping 你” = agent 在你没有当轮提问的情况下，主动向你推送一条消息。它是 push（推送） 模式；相对的是 turn-based 的 pull（你问它答）。

类比 ping.md：ICMP 里是你发 Echo Request、对方回 Reply（你主动 probe 它）；agent 主动 ping 你正好反过来——是对方（或外部事件）主动 echo 给你，你没发请求。所以”agent 主动 ping”本质是”反向的、unsolicited 的推送”。

2. 什么情况会主动 ping（排除 cron 与轮次对话）

把”主动”拆成触发源。除了你已知的两种——cron（时间到点触发） 和 轮次对话（你发消息它回）——剩下的是：

触发源	机制	例子
外部事件 / Webhook	系统外事件发生，经回调唤醒 agent → 转述给你	GitHub 有 PR 评论、收到邮件、支付到账、监控告警
状态/文件监听 (Watcher)	agent 盯着文件/目录/DB/队列，变化即 ping	”下午 6 点前检查某文件是否存在，缺失则提醒”
阈值/告警 (Alerting)	指标越过边界 → 推送	服务器宕、错误率飙升、余额不足、CPU 满载
长任务完成回调	你发起异步任务，后台跑完回报	构建/抓取/训练/批量处理完成
HITL 审批请求	agent 执行中需权限/人工把关 → 找你确认	发帖前确认、删除前确认
入站消息路由	别人在 agent 监控的渠道发消息 → agent 作为事件处理/转述给你	他人在 Telegram/Slack @ 它，它转告你

注意：没有”agent 凭空想起来找你”。每一次主动 ping 背后都是上表里某一种明确的触发器；若不是事件/监听/阈值/完成/HITL，那基本就是 cron（你已排除）或轮次对话。

3. 工作原理（agent 怎么做到”主动”）

外部事件 / 状态变化
   │  (webhook 回调 / 文件变更 inotify / 指标越界 / 任务完成)
   ▼
  监听器（agent 常驻进程里的"耳朵"）
   │  事件 → Gateway 路由
   ▼
  Agent 构造消息（可能再调一次模型决定怎么说）
   │
   ▼
  IM 渠道推送 → 你的微信 / Telegram / Slack

• 前提：agent 必须 7×24 常驻（呼应 vps-vpn.md 的”为什么 VPS 能让服务常驻”）。事件来了若进程没在听，就丢了。
• 监听器是核心：webhook 接收器、文件 watcher（inotify/chokidar）、短周期轮询状态——它们让 agent 从”被动等问”变成”一直在听”。
• 渠道（Telegram/Slack 等）只提供”耳朵和嘴”；是否主动取决于有没有挂监听器/事件订阅。

4. Push vs Pull 辨析

维度	Pull（轮次对话，你问它答）	Push（agent 主动 ping）
触发方	你	agent / 外部事件
网络类比	你 ping 它（ICMP Echo）	它（或事件）ping 你
依赖	你在场发起	agent 常驻 + 监听器
典型内容	问答、生成	告警、提醒、完成回报、审批
cron	—	时间触发（本题已排除）

5. 典型场景

• 你发起一个长抓取任务去睡觉，凌晨跑完 → agent 主动发”抓取完成，共 1234 条”。
• 服务器监控指标越界 → agent 推”API 错误率 12%，已超阈值”。
• 别人在你监控的 Slack 频道 @ agent → agent 转述”小明问你 PR 啥时候合”。
• agent 要删库前 → 主动找你”确认删除 production.db？[允许/拒绝]“（HITL）。

6. 常见误区

• ❌ “agent 会自动想起来找我” → 没有自由意志；每次主动 ping 都有明确触发器（事件/监听/阈值/完成/HITL），否则就是 cron 或轮次对话。
• ❌ “主动 ping 不需要 agent 常驻” → 必须 7×24 在线 + 有监听器（呼应 vps-vpn.md），否则事件来了没人接。
• ❌ “webhook 和 cron 一样” → cron=时间驱动（到点就发，不依赖外部）；webhook=事件驱动（发生了才发，依赖外部事件源）。
• ❌ “HITL 确认算我主动” → 是 agent 执行卡住来找你批准，方向 agent→你，属主动 push。
• ❌ “只要接了渠道就会主动 ping” → 渠道只是耳朵和嘴；主动与否看有没有监听器/事件订阅。

7. 延伸阅读 / 关联概念

• ping.md — ICMP Echo：你主动 probe 对方；agent 主动 ping 你是其反向 / unsolicited 版
• vps-vpn.md — 7×24 常驻是”能主动 ping”的前提（为什么 VPS 能让服务在线）
• ../ai-agent-guide/openclaw.md — Gateway 聚合渠道 + cron Skill + 文件检查提醒，是上述触发器的具体落地
• ../ai-agent-guide/agent_harness.md — 常驻运行时 / 事件循环如何承载监听器
• ../ai-agent-guide/mcp.md — 外部系统（事件源）通过 MCP 接进来，成为 webhook / 状态监听的来源