DingTalk の設定

Hermes Agent は DingTalk（钉钉）とチャットボットとして連携し、ダイレクトメッセージやグループチャットから AI アシスタントと話せるようにします。ボットがつながるのは DingTalk の Stream Mode で、これは長くつなぎっぱなしにする WebSocket の接続です。公開 URL も webhook 用のサーバーも要りません。返事は DingTalk のセッション webhook API を通して、markdown で整形されたメッセージとして届きます。

設定に入る前に、たいていの人がまず知りたいところから見ていきます。DingTalk のワークスペースに入れたあと、Hermes がどう振る舞うかです。

Hermes の振る舞い

場面	挙動
DM（1 対 1 のチャット）	すべてのメッセージに応答します。`@mention` は不要です。DM ごとに別々のセッションになります。
グループチャット	`@mention` されたときに応答します。メンションがなければ、そのメッセージは無視します。
複数の人がいる共有グループ	既定では、グループの中でも利用者ごとにセッション履歴を分けます。同じグループで話している 2 人の会話記録は、明示的に切らないかぎり混ざりません。

DingTalk でのセッションの考え方

既定では次のようになります。

DM ごとに専用のセッションが作られます
共有グループチャットでは、その中で利用者ごとに専用のセッションが作られます

この挙動は config.yaml で決まります。

group_sessions_per_user: true

グループ全体でひとつの会話にまとめたいと自分ではっきり決めたときだけ、false にしてください。

group_sessions_per_user: false

このガイドでは、DingTalk のボットを作るところから最初のメッセージを送るところまで、設定の全体を順に見ていきます。

前提条件

必要な Python パッケージをインストールします。

cd ~/.hermes/hermes-agent && uv pip install -e ".[dingtalk]"

個別に入れる場合は次のとおりです。

pip install dingtalk-stream httpx alibabacloud-dingtalk

dingtalk-stream — Stream Mode（WebSocket によるリアルタイムのやり取り）のための DingTalk 公式 SDK
httpx — セッション webhook 経由で返信を送るために使う、非同期の HTTP クライアント
alibabacloud-dingtalk — AI カード、絵文字リアクション、メディアのダウンロードに使う DingTalk OpenAPI の SDK

ステップ 1: DingTalk のアプリを作成する

DingTalk 開発者コンソールを開きます。
DingTalk の管理者アカウントでログインします。
Application Development → Custom Apps → Create App via H5 Micro-App（コンソールの版によっては Robot）をクリックします。
次を入力します。

App Name: 例として Hermes Agent
Description: 任意です

作成が終わったら Credentials & Basic Info へ進み、Client ID（AppKey）と Client Secret（AppSecret）を見つけます。両方をコピーしておきます。

ステップ 2: ロボット機能を有効にする

アプリの設定ページで Add Capability → Robot へ進みます。
ロボット機能を有効にします。
Message Reception Mode で Stream Mode を選びます（公開 URL が要らないので、こちらがおすすめです）。

ステップ 3: 自分の DingTalk ユーザー ID を調べる

Hermes Agent は、誰がボットを使えるかを DingTalk のユーザー ID で管理します。DingTalk のユーザー ID は、組織の管理者が決める英数字の文字列です。

自分の ID を調べるには次のようにします。

DingTalk の組織管理者に尋ねます。ユーザー ID は DingTalk の管理コンソールの Contacts → Members で設定されています。
あるいは、ボットは受信したメッセージごとに sender_id をログに残します。ゲートウェイを起動してボットにメッセージを送り、ログから自分の ID を探してください。

ステップ 4: Hermes Agent を設定する

方法 A: 対話式のセットアップ（おすすめ）

案内付きのセットアップコマンドを実行します。

hermes gateway setup

聞かれたら DingTalk を選びます。セットアップウィザードでは、2 つの経路のどちらかで認可できます。

QR コードによるデバイスフロー（おすすめ）。 端末に表示される QR を DingTalk のモバイルアプリで読み取ると、Client ID と Client Secret が自動で返ってきて ~/.hermes/.env に書き込まれます。開発者コンソールへ行く必要はありません。
手で貼り付ける。 すでに認証情報がある場合や、QR を読み取るのが面倒な場合は、Client ID、Client Secret、許可するユーザー ID を聞かれた順に貼り付けます。

方法 B: 手で設定する

~/.hermes/.env ファイルに次を追記します。

# Required
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret

# Security: restrict who can interact with the bot
DINGTALK_ALLOWED_USERS=user-id-1

# Multiple allowed users (comma-separated)
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

# Optional: group-chat gating (mirrors Slack/Telegram/Discord/WhatsApp)
# DINGTALK_REQUIRE_MENTION=true
# DINGTALK_FREE_RESPONSE_CHATS=cidABC==,cidDEF==
# DINGTALK_MENTION_PATTERNS=^小马
# DINGTALK_HOME_CHANNEL=cidXXXX==
# DINGTALK_ALLOW_ALL_USERS=true

~/.hermes/config.yaml で設定できる、任意の振る舞いの調整は次のとおりです。

group_sessions_per_user: true

gateway:
  platforms:
    dingtalk:
      extra:
        # Require @mention in groups before the bot replies (parity with Slack/Telegram/Discord).
        # DMs ignore this — the bot always replies in 1:1 chats.
        require_mention: true

        # Per-platform allowlist. When set, only these DingTalk user IDs can interact with the bot
        # (same semantics as DINGTALK_ALLOWED_USERS, but scoped here instead of in .env).
        allowed_users:
          - user-id-1
          - user-id-2

group_sessions_per_user: true にすると、共有グループチャットの中でも参加者ごとに文脈が分かれたままになります
require_mention: true にすると、ボットがグループのすべてのメッセージに反応しなくなり、@ で名前を呼ばれたときだけ答えます
dingtalk.extra の下の allowed_users は DINGTALK_ALLOWED_USERS の代わりに使えます。どちらか一方を設定してください（両方を設定した場合、認可されるのは両方の一覧に入っている利用者だけです）

ゲートウェイを起動する

設定が終わったら、DingTalk のゲートウェイを起動します。

hermes gateway

数秒のうちに DingTalk の Stream Mode へつながるはずです。DM か、ボットを追加したグループでメッセージを送って試してみてください。

機能

AI カード

Hermes は素の markdown メッセージの代わりに、DingTalk の AI カードで返事をすることもできます。カードは表示が豊かで構造も整っていて、エージェントが答えを組み立てていく途中の更新も流せます。

AI カードを使うには、config.yaml にカードテンプレートの ID を設定します。

platforms:
  dingtalk:
    enabled: true
    extra:
      card_template_id: "your-card-template-id"

カードテンプレートの ID は、DingTalk 開発者コンソールのアプリの AI カード設定にあります。AI カードを有効にすると、すべての返信がカードとして送られ、本文が少しずつ更新されていきます。

絵文字リアクション

Hermes は処理の状況を示すために、あなたのメッセージへ自動で絵文字リアクションを付けます。

🤔Thinking — ボットがメッセージの処理を始めたときに付きます
🥳Done — 返答が終わったときに付きます（Thinking のリアクションと入れ替わります）

このリアクションは DM でもグループチャットでも働きます。

表示の設定

DingTalk の表示のしかたは、ほかのプラットフォームとは切り離して調整できます。

display:
  platforms:
    dingtalk:
      show_reasoning: false   # Show model reasoning/thinking in replies
      streaming: true         # Enable streaming responses (works with AI Cards)
      tool_progress: all      # Show tool execution progress (all/new/off)
      interim_assistant_messages: true  # Show intermediate commentary messages

ツールの進捗や途中のメッセージを消して、すっきり見せたい場合は次のようにします。

display:
  platforms:
    dingtalk:
      tool_progress: off
      interim_assistant_messages: false

困ったときは

ボットがメッセージに応答しない

原因: ロボット機能が有効になっていないか、DINGTALK_ALLOWED_USERS に自分のユーザー ID が入っていません。

対処: アプリの設定でロボット機能が有効か、Stream Mode が選ばれているかを確かめます。自分のユーザー ID が DINGTALK_ALLOWED_USERS にあるかも確認して、ゲートウェイを再起動してください。

「dingtalk-stream not installed」というエラー

原因: Python パッケージの dingtalk-stream が入っていません。

対処: インストールします。

pip install dingtalk-stream httpx

「DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required」

原因: 認証情報が環境や .env ファイルに設定されていません。

対処: ~/.hermes/.env の DINGTALK_CLIENT_ID と DINGTALK_CLIENT_SECRET が正しく設定されているか確かめます。Client ID は DingTalk 開発者コンソールの AppKey、Client Secret は AppSecret です。

接続が切れる / 再接続を繰り返す

原因: ネットワークが不安定、DingTalk 側のメンテナンス、あるいは認証情報の問題です。

対処: アダプターは待ち時間を延ばしながら自動で再接続します（2 秒 → 5 秒 → 10 秒 → 30 秒 → 60 秒）。認証情報が有効か、アプリが無効化されていないかを確かめてください。外向きの WebSocket 接続がネットワークで許可されているかも見ておきます。

ボットがオフラインになっている

原因: Hermes のゲートウェイが動いていないか、接続に失敗しています。

対処: hermes gateway が動いているか確かめ、端末の出力にエラーが出ていないか見てください。よくある原因は、認証情報の誤り、アプリの無効化、dingtalk-stream や httpx の入れ忘れです。

「No session_webhook available」

原因: ボットが返事をしようとしたのに、セッション webhook の URL を持っていません。webhook の有効期限が切れたときや、メッセージを受け取ってから返事を送るまでの間にボットが再起動したときに起こりがちです。

対処: ボットにもう一度メッセージを送ってください。受信するメッセージごとに、返信用の新しいセッション webhook が渡されます。これは DingTalk の仕様上の制約で、ボットは最近受け取ったメッセージにしか返事ができません。

セキュリティ

Hermes Agent の運用を安全にする方法については、セキュリティガイドを見てください。

補足

Stream Mode: 公開 URL もドメイン名も webhook サーバーも要りません。接続は自分のマシンから WebSocket で張るので、NAT やファイアウォールの内側でも動きます。
AI カード: 素の markdown の代わりに、内容の豊かな AI カードで返すこともできます。card_template_id で設定します。
絵文字リアクション: 処理の状況を示す 🤔Thinking / 🥳Done のリアクションが自動で付きます。
markdown の返答: 返信は DingTalk の markdown 形式で整形され、装飾付きで表示されます。
メディアへの対応: 受信したメッセージの画像やファイルは自動で解決され、画像を扱うツールで処理できます。
メッセージの重複排除: アダプターは 5 分間の窓で重複を判定し、同じメッセージを二重に処理しないようにします。
自動再接続: 接続が切れた場合、アダプターは待ち時間を延ばしながら自動で再接続します。
メッセージの長さの上限: 返答は 1 通あたり 20,000 文字までです。それより長い場合は切り詰められます。