メール

インバウンドメッセージの配信方法に応じて、2つのメールチャネルがあります。

エージェントと対話できるユーザー

受信側の送信者は、バインドされたエージェントに対して解決されたピアセットに照らして制御されます。これはエージェントが所属する 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. 上記のシークレットパスを使用して、エージェントのGmailアクセスを承認し、取得したトークンを保存します
4. エージェントは新着メール通知を監視し、バインドされたエージェントへルーティングします

送信は引き続き SMTP 経由で行われます。IMAP+SMTP の [channels.email.<alias>] ブロックを設定してください。

返信スレッド

両方のメールチャネルは、In-Reply-To および References ヘッダーを使用して返信をスレッド化し、送信者が使用するクライアントに応じて会話をグループ化します。

送信ボディ形式

エージェントの返信は、デフォルトでプレーンテキストとHTMLの両方のパートを含むmultipart/alternativeとして送信されます。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送信: 提供業者の1日あたりの送信制限に従う (Gmailの場合: フリーアカウントは1日500通、Workspaceは1日2000通)。

安全性

メールにはSMTPのエンベロープを超えるプロトコルレベルの認証がなく、誰でも誰になりすますことができます。公開メールを受信する受信箱にエージェントを公開する前に、ピアグループ（上記）で受信側の送信者をゲートしてください。