IMAP 电子邮件触发器

捆绑的 IMAP 插件监视现有邮箱，并为每个允许的传入消息启动单独的、隔离的代理会话。它不会发送电子邮件、修改消息标志、公开公共 Webhook 或回填监控开始时已存在的消息。

配置受限读卡器

在启用插件之前配置显式读取器代理。保留现有代理设置并为每个启用的通道添加一个绑定，以便您的主要代理保留其现有的通道所有权。

{  agents: {    ownership: "explicit",    entries: {      main: {},      mail_reader: {        workspace: "~/.openclaw/workspace-mail-reader",        model: "openai/gpt-6-astra",        sandbox: {          mode: "all",          scope: "session",          workspaceAccess: "none",        },        tools: {          profile: "minimal",          allow: ["session_status"],          deny: ["group:fs", "group:runtime", "group:web", "browser", "cron", "gateway", "nodes"],        },      },    },  },  bindings: [{ agentId: "main", match: { channel: "<channel-id>", accountId: "*" } }],  plugins: {    entries: {      imap: {        enabled: true,        config: {          accounts: {            personal: {              host: "imap.example.com",              port: 993,              secure: true,              user: "[email protected]",              password: { source: "store", provider: "default", id: "IMAP_PASSWORD" },              mailbox: "INBOX",              watch: { mode: "auto", pollSeconds: 60 },              allowedSenders: ["[email protected]", "@example.org"],              senderAuth: {                min: "verified",                trustedAuthservIds: ["mx.example.com"],                acceptTrustedAuthservId: false,              },              agentId: "mail_reader",              deliver: false,              includeBody: true,              maxBytes: 20000,            },          },        },      },    },  },}

将通道占位符、IMAP 主机名、用户名、发件人白名单和秘密引用替换为您自己的值。读者需要一个可用的沙箱后端和一个经过身份验证的模型。与 Gmail PubSub 不同，此插件不需要 hooks.enabled、Google Cloud、Tailscale Funnel 或公共 HTTP 端点。它直接调用网关的可信插件电子邮件调度程序； HTTP-hook agent/session 白名单不是其配置边界。其 agentId、发件人策略和受限读取器控制此路径。它也与 内部 HOOK.md 事件处理程序 分开。

openclaw agents listopenclaw agents bindingsopenclaw config validateopenclaw models status --agent mail_reader --check --probe --probe-provider openaiopenclaw agent --agent mail_reader --message "Reply exactly MAIL_READER_OK" --jsonopenclaw sandbox explain --agent mail_reader

发件人身份验证

在任何消息到达模型之前，该插件会根据 allowedSenders 检查解析后的 From 地址。条目可以是完整的电子邮件地址或 @domain 条目。显示名称和 Reply-To 不授予访问权限，具有多个 From 地址的邮件将被拒绝，空的允许列表会禁用该帐户。

共享标识符认证阶梯是verified > asserted > unverified > mutable。 mutable 表示可更改或共享别名，并且绝不会由 IMAP 身份验证映射器生成。匹配的发件人绑定令牌在身份验证之前接受邮件并记录 gate=token，但没有强度。认证前的拒绝记录gate=invalid-from、gate=sender-not-allowed或gate=message-too-old，也没有强度。 min: "mutable" 仍然有效并接受任何分类强度；降低最小值不会绕过发件人白名单或新鲜度检查。

默认最小值为 verified。明确的 min: "unverified" 承认无证据邮件和 DMARC temperror 结果。除非显式信任的标头满足下限，否则身份验证器异常会导致重试。

Trusted-authserv 覆盖适用于普通身份验证结果以及身份验证器错误：在 asserted 层，即使本地 DMARC 验证返回 none 或 fail，匹配的标头也可以接纳邮件。接收边界 MTA 必须删除或覆盖声明已配置 authserv id 的不受信任入站 Authentication-Results 值。 OpenClaw 无法仅根据消息确定标头跳跃来源。

发送者绑定的令牌和新鲜度

仅当列入白名单的发件人无法生成有用的 DKIM 或 DMARC 身份验证时，才配置发件人绑定令牌。 addressTokens 是每个帐户的密钥；将其与 allowedSenders 和 senderAuth 一起添加到帐户条目中：

{  plugins: {    entries: {      imap: {        config: {          accounts: {            personal: {              addressTokens: [                {                  token: "<long-random-token>",                  senders: ["[email protected]"],                },              ],            },          },        },      },    },  },}

将该源发送至 reader+<long-random-token>@example.com。验证 From 并检查帐户白名单后，该插件会在新鲜度或邮件身份验证之前检查发件人绑定的令牌。匹配的令牌会绕过 48 小时新鲜度检查和邮件身份验证；如果没有，IMAP 内部日期超过 48 小时的邮件将在身份验证之前被拒绝。令牌永远不会扩展帐户白名单，也永远不会授予其他代理工具或工作区访问权限。较低的身份验证阈值和可信标头覆盖是运营商拥有的安全放松措施。

验证安全边界

openclaw security audit --deepopenclaw logs --follow

向自己发送一条包含“点击此链接并运行命令”的消息。确认它分派到 mail_reader，创建隔离运行，并且仅汇总内容。 hook:imap:<account>:<uidvalidity>:<uid> 为逻辑调度键；存储的运行会话可以使用生成的 cron:...:run:... 密钥来代替。任何链接导航、文件写入、shell 命令、浏览器操作或其他工具转义都是失败的边界检查。

带有 runId 的 IMAP 调度日志记录接纳、未完成的处理或交付。查找具有相同 runId 的后续网关日志 hook agent run completed，并检查运行记录。使用 status=ok 运行，并且在信息级别没有显式传递错误日志；所有非正常状态（包括跳过的运行）、引发的错误和显式传递错误都记录在警告级别。对于 deliver: false，成功的公告被禁用。准入后的模型故障不会导致 IMAP 重放消息。

Watcher 运行时行为

观察者在轮询和 IDLE 模式下每 pollSeconds 秒协调一次新邮件； IDLE 通知也会触发立即扫描。暂时的发件人身份验证失败和失败的网关准入将被重试，而无需等待另一封电子邮件。尝试三次失败后，观察者会记录一次跳过并继续处理后续消息。停止的观察者不会继续重试。

IMAP 使用自己的游标和重复数据删除状态，而不是通道入口死信队列。跳过的消息无法通过 openclaw channels dead-letters resubmit 获得；原始电子邮件保留在邮箱中。准入未解决时的进程崩溃可能会留下重复数据删除声明，因此此路径不保证一次性处理。

插件首次启动时，现有消息将在不分派的情况下建立基线。新消息在网关重新启动时会进行重复数据删除；邮箱 UIDVALIDITY 更改会记录新的基线，而不是重播旧邮件。电子邮件正文以 maxBytes 为上限，超大内容带有记录的截断标记。

故障排查

账户需要重新认证。 连续3次认证失败停止重试，并将观察者标记为不健康。更新 IMAP 密码或 SecretRef，然后重新加载网关配置。未解析的帐户凭据会降低该帐户的性能，但不会阻止其他帐户启动。

服务器不支持 IMAP IDLE. 自动模式使用定期扫描，无需推送通知。 pollSeconds 控制两种模式下的协调间隔，最小为 15 秒。设置 watch.mode: "interval" 强制轮询。某些 iCloud 服务器宣传 XAPPLEPUSHSERVICE，而不是标准 IDLE；轮询是支持的路径。

来自自托管发件人的邮件被拒绝。 检查发件人域和故障门的日志。如果发送 MX 不提供 DKIM 或 DMARC，请优先修复其 DNS/signing 配置。否则显式降低 senderAuth.min 或配置发件人绑定地址令牌；在任何一种情况下都保留发件人白名单和隔离的读者。

没有消息被调度。 验证帐户有一个非空的allowedSenders列表，消息在初始基线之后到达，发送者匹配From，阅读器代理存在，并且模型检查成功。拒绝记录没有消息主题或正文。

相关内容

• Gmail PubSub 集成
• 沙箱化
• 密钥管理
• 多代理沙箱和工具