メールの設定

Hermes は標準の IMAP と SMTP でメールを受け取り、返信できます。エージェントのアドレス宛にメールを送ると、同じスレッドの中で返事が返ってきます。専用のクライアントもボット API も要りません。Gmail、Outlook、Yahoo、Fastmail など、IMAP/SMTP に対応した提供元ならどれでも動きます。

これは同梱の Himalaya メールスキル とは別物です。あちらはエージェントがターミナルのコマンド越しにメールを扱うためのもので、外部の himalaya CLI と Himalaya の設定ファイルが要ります。

事前に用意するもの

• Hermes エージェント専用のメールアカウント（普段使いのメールは使わないでください）
• そのアカウントで IMAP が有効になっていること
• Gmail など二段階認証を使う提供元ならアプリパスワード

Gmail の設定

1. Google アカウントで二段階認証を有効にします
2. アプリパスワード のページを開きます
3. 新しいアプリパスワードを作ります（「メール」か「その他」を選びます）
4. 表示された 16 文字のパスワードを控えます。普段のパスワードの代わりにこれを使います

Outlook / Microsoft 365

1. セキュリティ設定 を開きます
2. 二段階認証がまだなら有効にします
3. 「セキュリティ情報の追加」からアプリパスワードを作ります
4. IMAP のホストは outlook.office365.com、SMTP のホストは smtp.office365.com です

そのほかの提供元

たいていのメール提供元は IMAP/SMTP に対応しています。次の点を提供元の案内で確かめてください。

• IMAP のホストとポート（多くはポート 993 で SSL）
• SMTP のホストとポート（多くはポート 587 で STARTTLS）
• アプリパスワードが必要かどうか

Proton Mail Bridge やローカルの中継

Proton Mail Bridge（自前で立てた MTA のような中継も同じです）は ループバック上で STARTTLS と自己署名証明書を使って待ち受けます。そのため既定値 （IMAP 993 での暗黙の TLS と証明書の検証）のままではつながりません。 ~/.hermes/config.yaml で通信のしかたを上書きします。

platforms:
  email:
    enabled: true
    extra:
      imap_host: 127.0.0.1
      imap_security: starttls     # tls (default) | starttls | plain
      imap_tls_verify: false      # Bridge uses a self-signed cert
      smtp_host: 127.0.0.1
      smtp_security: starttls     # default: tls on port 465, starttls otherwise
      smtp_tls_verify: false

あわせて ~/.hermes/.env に Bridge の認証情報と一緒に EMAIL_IMAP_PORT=1143 と EMAIL_SMTP_PORT=1025 を書きます。*_security に知らない値を書くと警告が出て、 安全な既定値に戻ります。*_tls_verify を切ってよいのはループバックのホストだけです。 それ以外のホストで検証を切ると、Hermes が警告を出します。

手順 1: Hermes を設定する

いちばん簡単なのはこれです。

hermes gateway setup

プラットフォームの一覧から Email を選びます。ウィザードがメールアドレス、パスワード、IMAP/SMTP のホスト、許可する差出人を順に聞いてきます。

手で設定する場合

~/.hermes/.env に次を足します。

# Required
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop    # App password (not your regular password)
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

# Security (recommended)
EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com
# Required: exact authserv-id on your receiving server's topmost
# Authentication-Results header (Gmail: mx.google.com).
# That server must strip inbound headers claiming this id before adding its own.
EMAIL_AUTHSERV_ID=mx.google.com

# Optional
EMAIL_IMAP_PORT=993                    # Default: 993 (IMAP SSL)
EMAIL_SMTP_PORT=587                    # Default: 587 (SMTP STARTTLS)
EMAIL_POLL_INTERVAL=15                 # Seconds between inbox checks (default: 15)
EMAIL_HOME_ADDRESS=your@email.com      # Default delivery target for cron jobs

手順 2: ゲートウェイを起動する

hermes gateway              # Run in foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

起動すると、アダプターは次の順に動きます。

1. IMAP と SMTP の接続を試します
2. 受信箱にある既存のメールをすべて「既読」にします（以後は新着だけを扱います）
3. 新着メールの巡回を始めます

しくみ

メールを受け取る

アダプターは IMAP の受信箱を決まった間隔（既定は 15 秒）で見に行き、未読のメールを拾います。新しいメール 1 通ごとに次のように扱われます。

• 件名が文脈として添えられます（例: [Subject: Deploy to production]）
• 返信メール（件名が Re: で始まるもの）では件名の頭書きを省きます。スレッドの文脈はもう伝わっているからです
• 添付ファイルは手元に控えられます:
  • 画像（JPEG、PNG、GIF、WebP）→ 画像を見る道具から使えます
  • 書類（PDF、ZIP など）→ ファイルとして開けます
• HTML だけのメールはタグを取り除いて本文を取り出します
• 自分宛のメールは返信の堂々巡りを防ぐために除かれます
• 自動送信や返信不要の差出人は黙って無視されます。noreply@、mailer-daemon@、bounce@、no-reply@ のほか、Auto-Submitted、Precedence: bulk、List-Unsubscribe のヘッダーが付いたメールが該当します

返信を送る

返信は SMTP で送られ、スレッドがきちんとつながるようになっています。

• In-Reply-To と References のヘッダーでスレッドを保ちます
• 件名は Re: を付けて引き継ぎます（Re: Re: と重なることはありません）
• Message-ID はエージェントのドメインで作られます
• 返信はプレーンテキスト（UTF-8）で送られます

ファイルを添付する

エージェントは返信にファイルを添付できます。返答の中に MEDIA:/path/to/file と書けば、そのファイルが送信するメールに添付されます。

添付を受け取らない

届いた添付をすべて無視したいとき（不正なファイルを避けたい、通信量を抑えたいなど）は、config.yaml に次を足します。

platforms:
  email:
    skip_attachments: true

有効にすると、添付と本文に埋め込まれた部分は中身を読み解く前に飛ばされます。メール本文の文章はこれまでどおり処理されます。

誰に応じるかを決める

メールの応対範囲は、チャット系のプラットフォームより既定で厳しめです。

1. EMAIL_ALLOWED_USERS を設定した場合 → そのアドレス（と、GATEWAY_ALLOWED_USERS に入っているアドレスや承認済みのペアリング）から届いたメールだけを処理します
2. 許可リストを設定しない場合 → 見知らぬ差出人は黙って無視されます
3. EMAIL_ALLOW_ALL_USERS=true → どんな差出人でも受け付けます（気をつけて使ってください）
4. platforms.email.unauthorized_dm_behavior: pair → 見知らぬ差出人にはペアリング用のコードが届きます
5. platforms.email.unauthorized_dm_behavior: decline → 見知らぬ差出人には丁寧なお断りを1通だけ送り、その後24時間は何も送りません

許可リストの項目はアドレス全体で照合します。alice のようにドメインのない項目（たとえば GATEWAY_ALLOWED_USERS に書いたチャットのユーザー名）は、どのドメインの alice@ も通しません。そうしたアドレスからのメールは、ペアリングやお断りの対象にもならず、そのまま捨てられます。

Hermes がメッセージに応じるのは、受信側のメールサーバーが付けた Authentication-Results ヘッダーで From: のドメインが認証されている場合（DMARC、または整合した SPF/DKIM）だけです。これは誰でも受け付ける設定（EMAIL_ALLOW_ALL_USERS / GATEWAY_ALLOW_ALL_USERS）でも同じです。誰でも受け付ける設定はどの差出人も通しますが、会話もすべての返信も From: をもとに振り分けられるので、From: が偽装されていると、攻撃者の書いた文面がそのアドレスのセッションに入り、Hermes がそれをメールで送ってしまうからです。ペアリング用のコードとお断りのメールも同じく認証済みの From: が必要なので、偽装されたアドレスには送られません。お使いのメールサーバーがこのヘッダーを付けない場合は、危険を承知のうえで platforms.email.require_authenticated_sender: false（または EMAIL_TRUST_FROM_HEADER=true）を設定してください。設定しないと、受け付ける差出人からのメールでもこのヘッダーがなければ破棄され、ゲートウェイのログに Dropping sender with unauthenticated From の警告が出ます。いちばん上の Authentication-Results ヘッダー（お使いのサーバーが先頭に付けるもの。それより下のヘッダーは一切参照しません）に、固定した authserv_id がそのとおりに書かれていない場合も、同じ警告が出ます。このときは platforms.email.authserv_id（EMAIL_AUTHSERV_ID）を見直すよう示されます。authserv_id は、そのヘッダーの最初の ; より前にサーバーが書き込む authserv-id と完全に一致させる必要があります。EMAIL_ALLOWED_USERS / GATEWAY_ALLOWED_USERS に載っているアドレスからのメールが、それ以外の理由で認証に失敗した場合（たとえば差出人の DKIM が壊れている、転送サービスが整合を崩しているなど）も、同じ警告とその判定結果を添えて破棄されます。この場合、無効にする方法の案内は出ません。それ以外の差出人の認証に失敗したメール（誰でも受け付ける設定での偽装された From: など）は、何も知らせずに破棄され、debug レベルのログにだけ記録されます。

送信者の認証を有効にしている間は、authserv_id の固定が必須です。 platforms.email.authserv_id（EMAIL_AUTHSERV_ID）がないと、Hermes はお使いのサーバーの Authentication-Results ヘッダーと、差出人が書いたヘッダーとを見分けられません（自分ではヘッダーを付けない自前の MTA だと、差出人のヘッダーがいちばん上に残ります）。そのため、どのヘッダーも信用しません。認証済みの From: が必要なメッセージはすべて破棄され、ゲートウェイのログにはその旨が直し方とともに一度だけ出ます。設定する値は、サーバーが届けたメッセージを1通開き（「メッセージのソースを表示」や「原文を表示」など）、いちばん上の Authentication-Results ヘッダーで最初の ; より前にある文字列を写して調べます。Gmail なら mx.google.com のようになります。この文字列がメッセージごとに変わるように見える場合、それは authserv-id ではなく、中継サーバーごとのホスト名です。RFC 8601 は authserv-id を管理ドメインを表す変わらない名前と定めているので、MTA 側で決まった名前を付けるように設定し（たとえば OpenDKIM / OpenDMARC の AuthservID）、その名前を固定してください。id が一致しても、それは固定であって出どころの証明ではありません。お使いの MTA が、自分のヘッダーを先頭に付ける前に、その id を名乗る受信済みの Authentication-Results ヘッダーを取り除いているかを確かめてください。変わらない id を固定できない場合は、platforms.email.require_authenticated_sender: false（または EMAIL_TRUST_FROM_HEADER=true）で明示的に無効にし、From: が書かれたとおりに信用されることを受け入れてください。

うまくいかないとき

安全に使うために

• 主なパスワードではなくアプリパスワードを使います（二段階認証を使う Gmail では必須です）
• EMAIL_ALLOWED_USERS を設定して、エージェントとやりとりできる相手を絞ります
• EMAIL_AUTHSERV_ID に、受信側 MTA がいちばん上の Authentication-Results に付ける id をそのまま設定し、その MTA がこの id を名乗る受信済みのヘッダーを取り除いていることを確かめます
• パスワードは ~/.hermes/.env に保存されます。このファイルは守ってください（chmod 600）
• 既定では IMAP が SSL（ポート 993）、SMTP が STARTTLS（ポート 587）を使います。通信は暗号化されます

環境変数の一覧