电子邮件

两个电子邮件通道，具体取决于您希望如何接收传入消息。

谁可以与代理通信

入站发送方会根据为绑定代理解析出的对等集合进行限制，该集合来自代理所属的 peer_groups 配置。匹配时会去除开头的 @，并对通道的原生发送方标识符执行不区分大小写的比对。空集合会拒绝所有人；包含 "*" 的集合会接受所有人；否则仅接受列出的外部对等方（以及对等代理）。这与网关配对（gateway.require_pairing）不同，后者验证的是 HTTP/WebSocket 客户端，而非聊天通道的发送方。

电子邮件的对等组将 channel 设置为 email，在 external_peers 中列出允许的发件人（对于电子邮件，即发件人的电子邮件地址；["*"] 表示接受任何人），可选择命名用于跨智能体调度的对等 agents、一个 ignore 屏蔽列表，以及一个 output_modality（mirror、voice 或 text）。字段参考请参见 Peer Groups。

在何处设置：

IMAP + SMTP（email_channel）

通用电子邮件通道。轮询 IMAP 以获取新邮件，通过 SMTP 发送。支持 Gmail、Outlook、Fastmail、自托管的 Postfix 以及其他任何支持 IMAP/SMTP 的服务。

zeroclaw config set channels.email.<alias>.default_subject <value>

export ZEROCLAW_channels__email__<alias>__default_subject=

zeroclaw config set channels.email.<alias>.excluded_tools <value>

export ZEROCLAW_channels__email__<alias>__excluded_tools=

zeroclaw config set channels.email.<alias>.from_address <value>

export ZEROCLAW_channels__email__<alias>__from_address=

zeroclaw config set channels.email.<alias>.html_body <value>

export ZEROCLAW_channels__email__<alias>__html_body=

zeroclaw config set channels.email.<alias>.idle_timeout_secs <value>

export ZEROCLAW_channels__email__<alias>__idle_timeout_secs=

zeroclaw config set channels.email.<alias>.imap_folder <value>

export ZEROCLAW_channels__email__<alias>__imap_folder=

zeroclaw config set channels.email.<alias>.imap_host <value>

export ZEROCLAW_channels__email__<alias>__imap_host=

zeroclaw config set channels.email.<alias>.imap_port <value>

export ZEROCLAW_channels__email__<alias>__imap_port=

zeroclaw config set channels.email.<alias>.max_attachment_bytes <value>

export ZEROCLAW_channels__email__<alias>__max_attachment_bytes=

zeroclaw config set channels.email.<alias>.oauth2 <value>

export ZEROCLAW_channels__email__<alias>__oauth2=

zeroclaw config set channels.email.<alias>.observer_mode <value>

export ZEROCLAW_channels__email__<alias>__observer_mode=

zeroclaw config set channels.email.<alias>.password <value>

export ZEROCLAW_channels__email__<alias>__password=

zeroclaw config set channels.email.<alias>.poll_interval_secs <value>

export ZEROCLAW_channels__email__<alias>__poll_interval_secs=

zeroclaw config set channels.email.<alias>.smtp_host <value>

export ZEROCLAW_channels__email__<alias>__smtp_host=

zeroclaw config set channels.email.<alias>.smtp_password <value>

export ZEROCLAW_channels__email__<alias>__smtp_password=

zeroclaw config set channels.email.<alias>.smtp_port <value>

export ZEROCLAW_channels__email__<alias>__smtp_port=

zeroclaw config set channels.email.<alias>.smtp_tls <value>

export ZEROCLAW_channels__email__<alias>__smtp_tls=

zeroclaw config set channels.email.<alias>.smtp_username <value>

export ZEROCLAW_channels__email__<alias>__smtp_username=

zeroclaw config set channels.email.<alias>.username <value>

export ZEROCLAW_channels__email__<alias>__username=

password（以及如果你使用单独的中继时的 smtp_password）属于机密信息：

channels.email.<alias>.password 是机密信息。 以加密形式存储，绝不会以明文形式出现在 config.toml 中。请通过以下方式之一进行设置，它们会在写入时加密：

zeroclaw config set channels.email.<alias>.password    # 提示输入掩码内容，以加密形式存储

Gmail 注意事项

• 如果启用了双因素身份验证（2FA），则必须使用应用专用密码。常规账户密码将被拒绝。
• “安全性较低的应用的访问权限”已被移除：应用专用密码是唯一的可用方式。
• 考虑使用下面的 Gmail Push 通道进行实时投递，而不是轮询。

Outlook / Office 365

password（以及 smtp_password）属于机密信息：

channels.email.<alias>.password 是机密信息。 以加密形式存储，绝不会以明文形式出现在 config.toml 中。请通过以下方式之一进行设置，它们会在写入时加密：

zeroclaw config set channels.email.<alias>.password    # 提示输入掩码内容，以加密形式存储

Gmail Push（gmail_push）

通过 Google Cloud Pub/Sub 实时投递，无需轮询。

zeroclaw config set channels.gmail_push.<alias>.excluded_tools <value>

export ZEROCLAW_channels__gmail_push__<alias>__excluded_tools=

zeroclaw config set channels.gmail_push.<alias>.label_filter <value>

export ZEROCLAW_channels__gmail_push__<alias>__label_filter=

zeroclaw config set channels.gmail_push.<alias>.oauth_token <value>

export ZEROCLAW_channels__gmail_push__<alias>__oauth_token=

zeroclaw config set channels.gmail_push.<alias>.topic <value>

export ZEROCLAW_channels__gmail_push__<alias>__topic=

zeroclaw config set channels.gmail_push.<alias>.webhook_secret <value>

export ZEROCLAW_channels__gmail_push__<alias>__webhook_secret=

zeroclaw config set channels.gmail_push.<alias>.webhook_url <value>

export ZEROCLAW_channels__gmail_push__<alias>__webhook_url=

oauth_token 和 webhook_secret 是密钥：

channels.gmail_push.<alias>.oauth_token 是机密信息。 以加密形式存储，绝不会以明文保存在 config.toml 中。请通过以下方式之一进行设置，它们会在写入时加密：

zeroclaw config set channels.gmail_push.<alias>.oauth_token    # 提示输入掩码内容，以加密形式存储

设置

1. 创建 Google Cloud 项目，启用 Gmail API 和 Pub/Sub API
2. 创建一个 Gmail 服务可以发布到的 Pub/Sub 主题，并将其设置为 topic
3. 通过上述密钥路径授权该 agent 的 Gmail 访问权限并存储生成的令牌
4. 代理监视新邮件通知并将其路由到绑定的代理

出站发送仍通过 SMTP 进行：请配置一个 IMAP+SMTP 的 [channels.email.<alias>] 配置块。

回复线程

两个电子邮件通道均使用 In-Reply-To 和 References 标头来线程化回复，以便在发件人使用的任何客户端中保持对话分组。

出站消息体格式

默认情况下，Agent 回复以 multipart/alternative 格式发送，同时包含纯文本和 HTML 两部分。HTML 部分是经 Markdown 渲染后的正文；纯文本部分是原始正文文本。偏好纯文本的邮件客户端会自动选择纯文本版本。

若仅发送纯文本（不含 HTML 部分，适用于偏好此方式的客户端或配置），请将通道的 html_body 字段设置为 false。

当存在附件时，正文的各替代版本会被封装在外层的 multipart/mixed 中。

附件处理

入站附件存储在 <workspace>/attachments/<conversation>/ 下。代理会在其上下文中获取文件路径，并可通过 file_read 工具读取这些文件。文件名首先取自 Content-Disposition 标头；如果没有，则回退到 Content-Type 的 name 参数。

出站附件会根据每个附件提供的字节数据发送。Email 通道将附件文件名视为显示元数据，而不是本地路径。需要有意发送本地文件的集成必须验证或限制该路径，并在发送前使用 MediaAttachment::from_file 显式加载文件。

速率和体积限制

电子邮件并不适合对话式延迟。预期：

• IMAP 轮询延迟：poll_interval_secs（默认 60 秒）。降低该值会增加服务器负载；部分提供商会对过于频繁的轮询进行速率限制。
• SMTP 发送：受限于您的提供商的每日发送配额（Gmail：免费账户每天 500 封，Workspace 账户每天 2000 封）。

安全

电子邮件在协议层面除了 SMTP 的信封之外没有任何身份认证；任何人都可以冒充任何人。在将代理暴露给接收公共邮件的收件箱之前，请先用对等组（如上所述）对入站发件人进行限制。