Feishu / Lark の設定

Hermes Agent は、Feishu と Lark に本格的な Bot として組み込めます。つないでしまえば、個別のチャットでもグループチャットでもエージェントと会話でき、定期タスクの結果をホームチャットで受け取り、テキスト・画像・音声・ファイルの添付を通常のゲートウェイの流れでやり取りできます。

接続方式は 2 通りに対応しています。

• websocket — おすすめの方式です。Hermes 側から外向きに接続を張るので、公開された Webhook のエンドポイントを用意する必要がありません
• webhook — Feishu / Lark から HTTP でゲートウェイにイベントを送り込みたいときに使います

Hermes の振る舞い

この共有チャットでの振る舞いは config.yaml で切り替えます。

group_sessions_per_user: true

チャットごとに 1 本の会話を共有したいと明確に決めている場合だけ、false にしてください。

手順 1: Feishu / Lark のアプリを作る

おすすめ: スキャンして作成する（コマンド 1 つ）

hermes gateway setup

Feishu / Lark を選び、Feishu または Lark のスマートフォンアプリで QR コードを読み取ります。Hermes が必要な権限を備えた Bot アプリケーションを自動で作り、認証情報を保存します。

別のやり方: 手動で設定する

スキャンでの作成が使えない場合、ウィザードは手入力に切り替わります。

1. Feishu または Lark の開発者コンソールを開きます。

• Feishu: https://open.feishu.cn/
• Lark: https://open.larksuite.com/

1. 新しいアプリを作ります。
2. Credentials & Basic Info で App ID と App Secret をコピーします。
3. そのアプリで Bot の機能を有効にします。
4. hermes gateway setup を実行し、Feishu / Lark を選んで、聞かれたら認証情報を入力します。

権限を設定する

Feishu の開発者コンソールで Permission Management を開き、次のスコープを追加します。権限のページでまとめて取り込めます。

必須の権限:

おすすめの権限（機能を一通り使う場合）:

イベントを設定する

Events and Callbacks で次のように設定します。

1. 接続方式を Long Connection (WebSocket)（おすすめ）にするか、Webhook の URL を設定します
2. Event Configuration の欄で、次のイベントを購読します。

• im.message.receive_v1 — メッセージを受け取るために必須です

アプリを公開する

権限とイベントを設定したら、Version Management で新しいバージョンを公開します。バージョンが公開されて承認されるまで権限は効きません（企業向けアプリの場合、管理者の承認が要ることがあります）。

手順 2: 接続方式を選ぶ

おすすめ: WebSocket 方式

ノート PC やワークステーション、あるいは外部に公開していないサーバーで Hermes を動かすなら WebSocket 方式を使います。公開 URL は要りません。公式の Lark SDK が外向きの WebSocket 接続を張り続け、切れたら自動でつなぎ直します。

FEISHU_CONNECTION_MODE=websocket

必要なもの: Python パッケージの websockets をインストールしておく必要があります。接続の維持、ハートビート、自動再接続は SDK が内部で面倒を見ます。

仕組み: アダプターは Lark SDK の WebSocket クライアントを、裏側のスレッドで動かします。受け取ったイベント（メッセージ、リアクション、カード操作）は本体の asyncio ループへ渡されます。接続が切れたときは、SDK が自動で再接続を試みます。

任意: Webhook 方式

Webhook 方式は、Hermes をすでに外から到達できる HTTP エンドポイントの後ろで動かしている場合だけ使ってください。

FEISHU_CONNECTION_MODE=webhook

Webhook 方式では、Hermes が（aiohttp を使って）HTTP サーバーを立ち上げ、次の場所で Feishu 向けのエンドポイントを提供します。

/feishu/webhook

必要なもの: Python パッケージの aiohttp をインストールしておく必要があります。

Webhook サーバーの待ち受けアドレスとパスは変更できます。

FEISHU_WEBHOOK_HOST=127.0.0.1   # default: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765         # default: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook  # default: /feishu/webhook

Feishu から URL 検証のチャレンジ（type: url_verification）が届くと、Webhook が自動で応答するので、Feishu の開発者コンソールで購読の設定を完了できます。このチャレンジへの応答は FEISHU_VERIFICATION_TOKEN を設定してある場合はその値で守られ、トークンが無いか一致しないチャレンジ要求は拒否されます。認証されていない相手が、攻撃者側が用意したチャレンジの値を返すだけで、エンドポイントを支配していると見せかけられないようにするためです。

手順 3: Hermes を設定する

方法 A: 対話式の設定

hermes gateway setup

Feishu / Lark を選び、聞かれた内容を埋めていきます。

方法 B: 手動で設定する

~/.hermes/.env に次の内容を書き足します。

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

# Optional but strongly recommended
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

FEISHU_DOMAIN に指定できるのは次の値です。

• 中国国内向けの Feishu なら feishu
• 国際版の Lark なら lark

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

hermes gateway

起動したら Feishu / Lark から Bot にメッセージを送り、つながっているか確かめます。

ホームチャット

Feishu / Lark のチャットで /set-home を実行すると、そのチャットが定期タスクの結果やプラットフォームをまたいだ通知の届け先になります。

あらかじめ設定しておくこともできます。

FEISHU_HOME_CHANNEL=oc_xxx

セキュリティ

利用者の許可リスト

実運用では、Feishu の Open ID による許可リストを設定してください。

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

許可リストを空のままにすると、Bot に届く相手なら誰でも使えてしまう可能性があります。グループチャットでは、メッセージを処理する前に送信者の open_id が許可リストと照合されます。

Webhook の暗号化キー

Webhook 方式で動かすときは、受け取った Webhook の中身に対する署名検証を有効にするため、暗号化キーを設定します。

FEISHU_ENCRYPT_KEY=your-encrypt-key

このキーは、Feishu アプリ設定の Event Subscriptions の欄にあります。設定すると、アダプターは届いた Webhook 要求をすべて次の署名アルゴリズムで検証します。

SHA256(timestamp + nonce + encrypt_key + body)

計算したハッシュは x-lark-signature ヘッダーの値と、処理時間の差が出ない方法で突き合わせます。署名が不正か無い要求は HTTP 401 で拒否されます。

検証トークン

Webhook の中身に含まれる token フィールドを確かめる、もう一段の認証です。

FEISHU_VERIFICATION_TOKEN=your-verification-token

このトークンも、Feishu アプリの Event Subscriptions の欄にあります。設定すると、届いた Webhook の中身はすべて header オブジェクトに一致する token を持っている必要があります。一致しないトークンは HTTP 401 で拒否されます。

FEISHU_ENCRYPT_KEY と FEISHU_VERIFICATION_TOKEN は、守りを重ねる目的で両方いっしょに使えます。

グループメッセージの方針

環境変数 FEISHU_GROUP_POLICY は、グループチャットで Hermes が応答するかどうか、どう応答するかを決めます。

FEISHU_GROUP_POLICY=allowlist   # default

どの方式でも、メッセージが処理されるにはグループ内で Bot が明示的に @メンション（または @all）されている必要があります。個別のチャットは、この関門を常に通り抜けます。

FEISHU_REQUIRE_MENTION=false にすると、@メンションを求めずにグループの発言をすべて読むようになります。

FEISHU_REQUIRE_MENTION=false

チャットごとに切り替えたい場合は、group_rules の項目に require_mention を設定します。後述のグループごとのアクセス制御を参照してください。

Bot 自身の識別情報

Hermes は起動時に Bot 自身の open_id と表示名を自動で取得します。手動で設定する必要があるのは、Feishu の API に届かず自動取得ができないときか、アプリがテナント単位の利用者 ID を使っているときだけです。

FEISHU_BOT_OPEN_ID=ou_xxx     # only when auto-detection fails
FEISHU_BOT_USER_ID=xxx        # required if your app uses sender_id_type=user_id
FEISHU_BOT_NAME=MyBot         # only when auto-detection fails

Bot 同士のやり取り

既定では、他の Bot が送ったメッセージは無視します。A2A の連携に Hermes を参加させたいときや、同じグループにいる他の Bot からの通知を受け取りたいときに、Bot 同士のやり取りを有効にしてください。

FEISHU_ALLOW_BOTS=mentions   # default: none

config.yaml の feishu.allow_bots でも設定できます（両方に指定した場合は環境変数が優先します）。

相手の Bot を FEISHU_ALLOWED_USERS に加える必要はありません。この許可リストは人の送信者にだけ適用されます。

相手の Bot の名前を表示するには application:bot.basic_info:read のスコープを与えてください。無くても振り分けは正しく動きますが、相手の Bot は open_id のまま表示されます。

対話型カードの操作

Bot が送った対話型カードのボタンを押すなどの操作があると、アダプターはそれを /card コマンドのイベントに変換して流します。

• ボタンを押すと /card button {"key": "value", ...} になります
• カードの定義にある操作の value の中身が JSON として含まれます
• カードの操作は 15 分の枠で重複を除き、二重に処理されないようにします

ゲートウェイからの更新確認は、素のテキスト返信に落とさず、Feishu の Yes / No カードで出します。hermes update --gateway が確認を求めるとき、アダプターは選ばれた答えを Hermes の .update_response ファイルに記録し、カードをその場で確定後の表示に差し替えます。

カードの操作イベントは MessageType.COMMAND として送られるので、通常のコマンド処理の流れをそのまま通ります。

コマンドの承認もこの仕組みで動きます。エージェントが危険なコマンドを実行しようとすると、Allow Once / Session / Always / Deny のボタンが付いた対話型カードを送ります。利用者がボタンを押すと、カード操作のコールバックが承認の判断をエージェントへ返します。

Feishu アプリ側で必要な設定

対話型カードには、Feishu Developer Console で 3 つの設定が要ります。どれか 1 つでも欠けていると、カードのボタンを押したときにエラー 200340 が出ます。

1. カード操作のイベントを購読する:

Event Subscriptions で、購読するイベントに card.action.trigger を追加します。

1. 対話型カードの機能を有効にする:

App Features > Bot で Interactive Card のスイッチが入っていることを確かめます。これで、アプリがカード操作のコールバックを受け取れると Feishu に伝わります。

1. カードのリクエスト URL を設定する（Webhook 方式のみ）:

App Features > Bot > Message Card Request URL に、イベント用の Webhook と同じエンドポイント（例: https://your-server:8765/feishu/webhook）を設定します。WebSocket 方式では SDK が自動で処理します。

ドキュメントのコメントへの自動返信

チャットだけでなく、Feishu / Lark のドキュメントに付いた @ メンションにも答えられます。利用者がドキュメントにコメントし（本文の一部を選んだコメントでも、ドキュメント全体へのコメントでも）Bot を @ メンションすると、Hermes はドキュメント本体とそのコメントの流れを読み、LLM による返信をそのコメントの中に投稿します。

この機能は drive.notice.comment_add_v1 イベントで動き、処理は次のとおりです。

• ドキュメントの中身とコメントの履歴を並行して取得します（ドキュメント全体へのコメントは 20 件、一部を選んだコメントは 12 件）。
• そのコメントのセッションだけに絞った feishu_doc と feishu_drive のツール群でエージェントを実行します。
• 返信は 4000 文字ごとに区切り、コメントへの返信として投稿します。
• ドキュメントごとのセッションを 1 時間、最大 50 メッセージまで保持するので、同じドキュメントに続けてコメントしても文脈が残ります。

3 段階のアクセス制御

ドキュメントのコメントへの返信は明示的に許可した場合のみ動きます。暗黙に全員を許可する設定はありません。権限は次の順で解決し、項目ごとに最初に一致したものが使われます。

1. 特定のドキュメント — 個別のドキュメントトークンに絞った規則。
2. ワイルドカード — ドキュメントのパターンに一致する規則。
3. 最上位 — ワークスペース全体の既定の規則。

規則ごとに 2 つの方針を選べます。

• allowlist — 固定の利用者 / テナントの一覧。
• pairing — 固定の一覧に、実行中に承認された分を足したもの。管理役がその場で許可を出しながら広げていく展開に向きます。

規則は ~/.hermes/feishu_comment_rules.json（pairing の許可は ~/.hermes/feishu_comment_pairing.json）に置かれ、更新時刻を見て自動で読み直します。編集した内容は、ゲートウェイを再起動しなくても次のコメントのイベントから効きます。

コマンド:

# Inspect current rules and pairing state
python -m gateway.platforms.feishu_comment_rules status

# Simulate an access check for a specific doc + user
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>

# Manage pairing grants at runtime
python -m gateway.platforms.feishu_comment_rules pairing list
python -m gateway.platforms.feishu_comment_rules pairing add <user_open_id>
python -m gateway.platforms.feishu_comment_rules pairing remove <user_open_id>

Feishu アプリ側で必要な設定

チャットとカードのためにすでに与えた権限に加えて、ドライブのコメントのイベントを足します。

• Event Subscriptions で drive.notice.comment_add_v1 を購読します。
• ドキュメントの中身を読めるように、docs:doc:readonly と drive:drive:readonly のスコープを与えます。

会議への招待イベント

Hermes の Feishu / Lark Bot は、人を招くのと同じやり方でビデオ会議に招待できます。Bot が会議への招待イベントを受け取ると、Hermes は会議に参加しようとするエージェントの処理を自動で始められます。

この機能は vc.bot.meeting_invited_v1 イベントで動き、流れは次のとおりです。

• 利用者が Bot を Feishu / Lark のビデオ会議に招待します。
• Feishu / Lark が Hermes に会議の招待イベントを送ります。
• Hermes が招待した人、会議の題名、会議番号を取り出します。
• 招待した人が通常のゲートウェイの許可リストまたは pairing の方針で認められていれば、エージェントが会議番号を受け取り、自動で参加を試みます。
• 招待の内容が壊れている場合や、エージェントが参加できない場合は、Hermes はそのイベントを捨てるか、招待した人に短く事情を返します。

招待した人と meeting_no の両方が入っていない不正な招待は無視されます。

Feishu アプリ側で必要な設定

チャットとカードのためにすでに与えた権限に加えて、ビデオ会議の招待イベントを足します。

• Event Subscriptions で vc.bot.meeting_invited_v1 を購読します。
• そのイベントに対して Feishu / Lark の開発者コンソールが求めるビデオ会議の権限スコープを有効にします。
• 招待した人に返信できるよう、im:message と im:message:send_as_bot を有効なままにしておきます。
• ゲートウェイの利用者許可リストか pairing の方針で、招待した人が認められていることを確かめます。会議への招待だからといって、通常のゲートウェイのアクセス確認を飛ばすことはありません。

メディアへの対応

受信

アダプターは、利用者から次の種類のメディアを受け取り、手元に保存します。

リッチテキスト（post）メッセージに含まれるメディアも、本文中の画像や添付ファイルを含めて取り出して保存します。

小さなテキスト形式の文書（.txt、.md）については、中身がメッセージ本文へ自動で差し込まれるので、エージェントはツールを使わずそのまま読めます。

送信

ファイルのアップロード方法は、拡張子で自動的に決まります。

• .ogg、.opus → opus の音声としてアップロード
• .mp4、.mov、.avi、.m4v → mp4 のメディアとしてアップロード
• .pdf、.doc(x)、.xls(x)、.ppt(x) → それぞれの文書の種類としてアップロード
• それ以外 → 一般的なストリームのファイルとしてアップロード

マークダウンの表示と post への切り替え

送信するテキストにマークダウンの書式（見出し、太字、箇条書き、コードブロック、リンクなど）が含まれる場合、アダプターは素のテキストではなく、md タグを埋め込んだ Feishu の post メッセージとして自動的に送ります。これで Feishu のクライアント側で見栄えよく表示されます。

Feishu の API が post の中身を受け付けなかった場合（対応していないマークダウンの書き方が原因など）、アダプターはマークダウンを取り除いた素のテキストへ自動的に切り替えて送ります。この二段構えにより、メッセージは必ず届きます。

マークダウンが見つからない素のテキストは、単純な text のメッセージ種別で送ります。

処理状況を表すリアクション

エージェントが作業している間、Bot はあなたのメッセージに Typing のリアクションを付けます。返信が届くと消え、処理に失敗した場合は CrossMark に置き換わります。

止めたいときは FEISHU_REACTIONS=false を設定します。

連投への備えとまとめ処理

エージェントに負荷が集中しないよう、アダプターは短時間に連続したメッセージをまとめて扱います。

テキストのまとめ

利用者が短い間隔でテキストを何通も送った場合、1 つのイベントに束ねてから処理へ渡します。

メディアのまとめ

短い間隔で送られた複数の添付メディア（画像を何枚もドラッグした場合など）も、1 つのイベントに束ねます。

チャットごとの順番待ち

同じチャットの中のメッセージは、会話の筋を保つために 1 通ずつ順番に処理します。チャットごとに別の錠を持つので、違うチャットのメッセージは同時に処理されます。

流量の制限（Webhook 方式）

Webhook 方式では、悪用を防ぐために送信元 IP ごとの流量制限をかけます。

• 区間: 60 秒のスライディングウィンドウ
• 上限: （app_id、パス、IP）の組み合わせごとに 1 区間あたり 120 回
• 追跡の上限: 最大 4096 個の組み合わせまで追跡します（メモリが際限なく増えるのを防ぎます）

上限を超えた要求には HTTP 429（Too Many Requests）を返します。

Webhook の異常の追跡

アダプターは、IP アドレスごとに連続したエラー応答を数えています。同じ IP から 6 時間のうちに 25 回続けてエラーが出ると、警告をログに残します。設定を誤ったクライアントや、探りを入れる動きに気づく助けになります。

Webhook にはほかにも次の備えがあります。

• 本文の大きさの上限: 最大 1 MB
• 本文の読み取りの制限時間: 30 秒
• Content-Type の強制: application/json だけを受け付けます

WebSocket の調整

websocket 方式を使うときは、再接続と ping の動きを変えられます。

platforms:
  feishu:
    extra:
      ws_reconnect_interval: 120   # Seconds between reconnect attempts (default: 120)
      ws_ping_interval: 30         # Seconds between WebSocket pings (optional; SDK default if unset)

グループごとのアクセス制御

全体に効く FEISHU_GROUP_POLICY とは別に、config.yaml の group_rules でグループチャットごとに細かい規則を決められます。

platforms:
  feishu:
    extra:
      default_group_policy: "open"     # Default for groups not in group_rules
      admins:                          # Users who can manage bot settings
        - "ou_admin_open_id"
      group_rules:
        "oc_group_chat_id_1":
          policy: "allowlist"          # open | allowlist | blacklist | admin_only | disabled
          allowlist:
            - "ou_user_open_id_1"
            - "ou_user_open_id_2"
        "oc_group_chat_id_2":
          policy: "admin_only"
        "oc_group_chat_id_3":
          policy: "blacklist"
          blacklist:
            - "ou_blocked_user"
        "oc_free_chat":
          policy: "open"
          require_mention: false       # overrides FEISHU_REQUIRE_MENTION for this chat

group_rules の項目に require_mention: false を設定すると、そのチャットだけ @ メンションを求めなくなります。書かなかった場合は、全体の FEISHU_REQUIRE_MENTION の値を引き継ぎます。

group_rules に載っていないグループは default_group_policy に従います（既定値は FEISHU_GROUP_POLICY の値です）。

重複の除去

受け取ったメッセージは、メッセージ ID をもとに 24 時間の保持期間で重複を除きます。この重複除去の状態は ~/.hermes/feishu_seen_message_ids.json に保存され、再起動しても引き継がれます。

環境変数の一覧

WebSocket とグループごとのアクセス制御の設定は、config.yaml の platforms.feishu.extra の下で行います（上の WebSocket の調整 とグループごとのアクセス制御を参照してください）。

困ったときは

ツール群

Feishu / Lark は hermes-feishu のプラットフォーム設定を使います。ここには、Telegram をはじめとするゲートウェイ経由の他のメッセージングプラットフォームと同じ中核のツールが含まれます。