轮询 (Polls) - 周期性数据拉取

Polls（轮询）是 OpenClaw 提供的周期性数据拉取机制。与时间驱动的 Cron 不同，Polls 是一种 Pull-Based（拉取式）检查模式——每隔固定间隔主动检查外部数据源是否有新数据或变更，有变更时触发 Agent（智能体）处理。

基本概念

轮询的核心工作流程：

┌─────────┐    间隔触发    ┌──────────┐    有变更?    ┌─────────────┐
│  Timer  │ ──────────── > │  Check   │ ──── Yes ──> │ Agent 处理  │
│  定时器  │               │  数据源   │              │  执行动作    │
└─────────┘               └──────────┘              └─────────────┘
                               │
                            No │
                               ▼
                          等待下一轮

Polls vs Cron

• Cron：时间驱动，到点执行，不关心是否有新数据
• Polls：数据驱动，周期性检查，仅在数据变更时触发操作

适用场景

场景	说明	推荐间隔
邮件监控	检查邮箱是否有新邮件到达	60s - 300s
RSS 订阅	检查 RSS Feed（RSS 订阅源）是否有新文章	300s - 900s
API 变更追踪	监控第三方 API 数据是否发生变化	60s - 600s
文件系统监控	检查目录中是否有新文件出现	10s - 60s
数据库变更	轮询数据库表的最新记录	30s - 300s

配置

在 openclaw.json 中配置 Polls：

{
  "polls": {
    "enabled": true,
    "entries": {
      "email-checker": {
        "enabled": true,
        "interval": 120000,
        "source": {
          "type": "imap",
          "host": "imap.example.com",
          "port": 993,
          "ssl": true,
          "folder": "INBOX"
        },
        "filter": {
          "unseen": true,
          "since": "auto"
        },
        "action": {
          "message": "检查到新邮件，请处理：{subject}",
          "session": "isolated"
        }
      },
      "rss-monitor": {
        "enabled": true,
        "interval": 600000,
        "source": {
          "type": "rss",
          "url": "https://example.com/feed.xml"
        },
        "action": {
          "message": "RSS 有新文章：{title}",
          "delivery": "announce"
        }
      }
    }
  }
}

配置字段说明

字段	类型	说明
enabled	boolean	是否启用此 Poll
interval	number	轮询间隔（毫秒）
source	object	数据源配置
filter	object	数据过滤规则
action	object	变更触发时的动作

数据源类型 (Source Types)

IMAP 邮件

{
  "type": "imap",
  "host": "imap.example.com",
  "port": 993,
  "ssl": true,
  "username": "${IMAP_USER}",
  "password": "${IMAP_PASS}",
  "folder": "INBOX"
}

RSS / Atom Feed

{
  "type": "rss",
  "url": "https://example.com/feed.xml",
  "maxItems": 10
}

HTTP API

{
  "type": "http",
  "url": "https://api.example.com/latest",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  },
  "diffField": "data.updated_at"
}

文件系统

{
  "type": "filesystem",
  "path": "/data/incoming/",
  "pattern": "*.csv",
  "event": "created"
}

CLI 命令

# 查看所有 Polls
openclaw polls list

# 手动触发一次轮询
openclaw polls run --name email-checker

# 查看轮询历史
openclaw polls history --name email-checker --limit 20

# 启用/禁用
openclaw polls enable rss-monitor
openclaw polls disable rss-monitor

状态管理

每个 Poll 维护一个 State（状态），用于记录上次检查的位置，避免重复处理：

{
  "lastCheck": "2026-03-05T10:00:00Z",
  "lastId": "msg-12345",
  "cursor": "eyJwYWdlIjogMn0="
}

状态文件存储在 ~/.openclaw/polls/state/ 目录下。

状态重置

如需从头重新拉取数据，可手动删除状态文件或使用命令：

openclaw polls reset --name email-checker

与 Agent 的集成

当 Poll 检测到变更时，会将数据封装为事件发送给 Agent：

// Poll 触发 Agent 时的上下文
interface PollEvent {
  pollName: string;
  source: string;
  data: any[];       // 变更的数据列表
  timestamp: number;
  metadata: Record<string, any>;
}

Agent 可以根据数据内容执行不同操作，如回复邮件、生成摘要、转发通知等。

最佳实践

开发建议

1. 合理设置间隔：间隔太短增加数据源压力，太长可能错过时效性数据
2. 使用增量查询：利用 since、cursor 等参数只拉取新数据
3. 处理去重：配合 lastId 状态确保同一条数据不被重复处理
4. 设置超时：为 HTTP 数据源设置合理的请求超时时间
5. 错误容忍：单次拉取失败不应中断后续轮询

🇨🇳 中国用户须知

• 轮询国外 RSS 源时可能需要配置代理，在 source 中添加 proxy 字段
• 国内企业邮箱（如腾讯企业邮箱、阿里企业邮箱）的 IMAP 配置需单独开启，参考各服务商文档
• 如果目标 API 在国内有加速节点，优先使用国内端点