---
title: "FAQ とトラブルシューティング"
description: "観察できる症状から、Ankole の deployment、identity、model、Worker、chat channelの障害を特定します。"
url: "https://ankole.agentbull.com/ja-JP/docs/faq/"
lang: "ja-JP"
---

> AI Agent 向けドキュメント索引: https://ankole.agentbull.com/ja-JP/llms.txt

# FAQ とトラブルシューティング

このページは製品概要ではなく、各 Provider のセットアップガイドを繰り返すものでもありません。最初に失敗した境界を見つけ、関連する identity またはチャット Provider を選択してください。インストールと初回セットアップの信頼できる情報源は [Quick start](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md) のままです。

## 失敗した境界を見つける

| 観察されること | 最初に確認すること |
|---|---|
| `/setup` または Console が開かない | デプロイ、control plane、DNS、HTTPS |
| Console は開くが、サインインが失敗するかディレクトリが不完全 | Identity Provider (IdP) |
| Console では Agent が機能するが、ある IM がメッセージを受信しない | その Channel Provider と signal routing rule |
| IM のメッセージは Ankole に入るが、Agent が返信を生成できない | LLM Provider、model profile、Worker |
| 1 つのプラットフォームだけが失敗する | 下の該当 Provider を選択してください。他のプラットフォームの修正を適用しないでください |

## すべてのプラットフォームに共通する問題

### /setup や Console が開かないとき、何を確認すればよいですか？

**症状**

ページがタイムアウトする、接続を拒否される、502 を返す、または空白のままになる。Provider のセットアップはまだ始まっていません。

**原因**

control plane が正常でないか、DNS、リバースプロキシ、Ingress が control plane にトラフィックを送っていません。後続の Provider エラーはたいてい連鎖の結果です。

**対処**

1. control plane、PostgreSQL、リバースプロキシを確認してください。ログの中で最初のエラーを修正します。
2. control plane への直接アクセスが機能するなら、DNS、TLS、プロキシの接続先を確認してください。
3. データベースや永続ボリュームを削除しないでください。起動の失敗はデータの破損を証明しません。

- [デプロイを確認する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#deployment)
- [ログを読む](https://ankole.agentbull.com/ja-JP/docs/log-reading/index.md)

### 初回セットアップの activation code はどこにありますか？

**症状**

/setup が activation code を要求するが、起動ターミナルは閉じられており、ログの中にコードが見つからない。

**原因**

control plane がこの code を使うのは初回セットアップのときだけです。最初の管理者がサインインすると期限切れになります。

**対処**

1. セットアップが完了していなければ、Quick start で自分のデプロイ方法を選び、そのタブのログコマンドを使ってください。
2. SETUP ACTIVATION CODE を検索してください。ブラウザのストレージやデータベースの行から code を推測しないでください。
3. インスタンスにすでに root 管理者がいる場合は、再アクティベートせずに、設定済みの IdP からサインインしてください。

- [activation code を読む](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#deployment)

### 選択したアダプターが Provider リストに表示されないのはなぜですか？

**症状**

プラグインが有効として保存されているのに、セットアップや identity、signal-routing のページにそのオプションが現れない。

**原因**

初回セットアップはコンパイル済みの全プラグインを利用可能に保ち、後続の設定を現在保存されている選択でフィルタリングします。セットアップ後、Console で保存したプラグイン変更は、次回の control plane 起動時に適用されます。

**対処**

1. まだ /setup にいるなら、Plugins に戻って選択を保存し、管理者サインインを開き直してください。再起動は不要です。
2. セットアップが完了しているなら、control plane だけを再起動してください。データを削除したり、PostgreSQL を再起動したりしないでください。プラグインがアクティブであることを確認し、Provider ページに戻ります。
3. control plane が起動しない場合は、ログにある最初のプラグイン初期化エラーを修正してください。

- [Agent Library で Plugin を有効化する](https://ankole.agentbull.com/ja-JP/docs/skills/index.md)

### どのチャットプラットフォームも返信しません。これはまだ channel の問題ですか？

**症状**

channel、DM、別のチャットアプリのすべてが失敗する。Console での Agent との直接の会話も失敗する。

**原因**

Console の経路も失敗する場合、共通の下流経路が原因の可能性が高いです。すなわち、LLM Provider、Agent の model profile、Worker であって、あるプラットフォームのイベント権限ではありません。

**対処**

1. LLM Provider が有効で、その credential と model 名が機能することを確認してください。
2. Agent に primary、light、heavy の profile があり、Worker が少なくとも 1 台 ready であることを確認してください。
3. Console で実際の model 会話を 1 回完了してから、選択したチャットプラットフォームのタブに戻ってください。

- [LLM Provider と Agent を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#llm-providers)
- [Worker fleet](https://ankole.agentbull.com/ja-JP/docs/worker-management/index.md)

### スケジュールが時間通りに実行されませんでした。最初に何を確認すべきですか？

**症状**

スケジュールは存在するが、期待した時刻に開始しない、または次の実行が期待と一致しない。

**原因**

スケジュールが無効になっている、インスタンスのタイムゾーンや cron 式が誤っている、またはトリガー時刻に control plane が稼働していなかった可能性があります。

**対処**

1. スケジュールを開き、有効であることを確認し、表示されている次の実行時刻を確認してください。
2. インスタンスのタイムゾーンと cron 式を確認してください。式から推測せず、Console が表示する時刻を使ってください。
3. [Run now] を選択してください。機能すれば時刻設定の問題です。失敗したら実行記録を確認してください。

- [スケジュールの設定と確認](https://ankole.agentbull.com/ja-JP/docs/schedules/index.md)

### スケジュールは実行されました。なぜチャットに結果が届かないのですか？

**症状**

実行記録は存在するが、対象のチャットや会話に Agent のメッセージが届かない。

**原因**

トリガーは機能しました。問題は後続の経路にあります。対象ルート、Channel Provider、Agent の model、または利用可能な Worker です。

**対処**

1. 実行記録を開き、その結果を確認し、最初のエラーを読んでください。
2. 対象の Agent、会話やチャットの宛先、その signal routing rule を確認してください。
3. Agent の model profile が機能し、Worker が少なくとも 1 台 ready であることを確認してください。

- [スケジュールの実行を確認する](https://ankole.agentbull.com/ja-JP/docs/schedules/index.md)
- [signal routing rule を確認する](https://ankole.agentbull.com/ja-JP/docs/signal-bindings/index.md)

## Identity Provider のトラブルシューティング

IdP はサインイン、連絡先、組織の同期を所有します。エンタープライズが使う identity ソースを選択してください。Slack の Socket Mode、Entra ID の Graph サブスクリプション、Google Workspace のフル同期は異なるメカニズムであり、異なるチェックが必要です。

**Choose an identity provider**

- Slack
- Microsoft Entra ID
- Google Workspace
- Lark / Feishu
- DingTalk
- WeCom

### Slack

#### 承認リダイレクト時に Slack サインインが失敗する

**症状**

Ankole に戻る前に Slack が redirect_uri の不一致を報告する、または承認が誤ったページに戻る。

**原因**

Slack Redirect URL が /setup が表示するコールバックと厳密に一致しないか、Ankole に別のアプリの Client ID が入っている。

**対処**

1. /setup から完全なコールバックを OAuth & Permissions → Redirect URLs にコピーしてください。
2. スキーム、ホスト、ポート、パス、Provider ID を 1 文字ごとに比較してください。
3. Slack アプリを保存し、Ankole から新しいサインインを開始してください。古い承認ページを使い回さないでください。

#### Slack サインインは機能するが、メンバーやユーザーグループが欠けている

**症状**

管理者は Console に入れるが、Principal や権限グループが空、または最近のメンバーが含まれていない。

**原因**

identity アプリに users:read、users:read.email、team:read がない、Bot User OAuth Token が新しい scope より古い、またはフル同期がまだ実行されていない。

**対処**

1. Quick start に記載された identity scope を追加してください。
2. scope の変更後、アプリを workspace に再度インストールし、新しい Bot User OAuth Token を IdP に保存してください。
3. リアルタイム同期を調べる前に、フル同期を検証してください。

#### Slack は完全なディレクトリ同期を完了するが、その後の変更が古いまま

**症状**

最初の同期にはデータがあるが、メンバーやユーザーグループの変更がすぐに反映されない。

**原因**

リアルタイム同期は Socket Mode を使います。App-Level Token がない、プレフィックスが誤っている、Socket Mode がオフ、または control plane が Slack に到達できない。

**対処**

1. IdP で Sync directory changes をオンにし、有効な App-Level Token を指定してください。
2. Slack で Socket Mode を有効にし、control plane からの送信インターネットアクセスを許可してください。
3. App-Level Token のローテーション後、Ankole の値を更新し、新しいディレクトリ変更でテストしてください。

- [Quick start で Slack IdP を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#identity-providers)

### Microsoft Entra ID

#### Microsoft サインインが AADSTS50011 を報告する

**症状**

Microsoft の承認ページが reply URL の不一致を報告する。通常はエラー AADSTS50011。

**原因**

Entra のアプリ登録にある Web Redirect URI が、/setup が表示する Ankole コールバックと厳密に一致しない。

**対処**

1. /setup のコールバックを Web Redirect URI としてアプリ登録にコピーしてください。
2. スキーム、ホスト、ポート、パス、Provider ID を確認してください。ここに Teams の messaging endpoint は使わないでください。
3. ポータルの変更が反映されるのを待ってから、Ankole から新しいサインインを開始してください。

#### Entra ID サインインは機能するが、ディレクトリ同期が空または 403 を返す

**症状**

管理者はサインインできるが、Ankole にユーザーや権限グループがない。ログに Graph 403 が表示されることがある。

**原因**

アプリに Group.Read.All または User.Read.All がないか、権限はあるがテナント管理者が同意 (consent) を行っていない。

**対処**

1. 必要な Microsoft Graph Application permissions を追加してください。
2. テナント管理者に Grant admin consent を選択してもらってください。権限を追加するだけでは不十分です。
3. 同意の後にフル同期を実行し、Principal と権限グループを確認してください。

#### Entra ID のフル同期は機能するが、リアルタイムの変更が届かない

**症状**

後続のフル同期がデータを修復するが、メンバーシップの変更が数分以内に反映されない。

**原因**

Graph は公開 HTTPS の directory webhook に到達する必要があります。Ankole の公開 URL が誤っている、Ingress が利用できない、証明書が信頼されていない、といった場合に配信できません。

**対処**

1. 公開 HTTPS アドレスがインターネットから到達可能で、信頼された証明書を使っていることを確認してください。
2. Ankole の公開 URL が実際のエントリポイントと一致することを確認してください。これが Graph の通知 URL を決めます。
3. サブスクリプションの reconciliation ログを確認し、エントリポイントが機能した後、control plane にサブスクリプションを再構築させてください。

- [Quick start で Entra ID を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#identity-providers)

### Google Workspace

#### Ankole が有効な Google アカウントを拒否するのはなぜですか？

**症状**

Google の承認は成功するが、Ankole が login_domain_not_allowed を返す。

**原因**

アカウントのドメインが Allowed Workspace domains にない、メールが未検証、またはユーザーが hd claim のない個人の Gmail アカウントを使っている。

**対処**

1. 個人の gmail.com アカウントではなく、エンタープライズの Google Workspace アカウントを使ってください。
2. 正確なアカウントドメインが Allowed Workspace domains にあることを確認してください。
3. エンタープライズが複数ドメインの Workspace を運用している場合にだけ、複数のドメインを追加してください。

#### Google サインインは機能するが、ディレクトリ同期が空または 403 を返す

**症状**

管理者は Console に入れるが、メンバーや権限グループが同期されない。

**原因**

ディレクトリ同期は OAuth Client ではなく Service Account を使います。ドメイン全体の委任、委任された scope、または Delegated administrator email が通常は誤っています。

**対処**

1. Service Account の Domain-wide delegation を有効にしてください。
2. Workspace の管理コンソールで、Quick start に記載された Directory API scopes を許可してください。
3. Delegated administrator email と Service account JSON key を確認し、フル同期を実行してください。

#### Google Workspace のメンバー変更がすぐに反映されないのはなぜですか？

**症状**

Workspace のユーザーやグループの変更後、Ankole が少し遅れて更新する。

**原因**

Google Workspace IdP は現在フル同期のみをサポートします。リアルタイムのディレクトリサブスクリプションはありません。この遅延は想定内です。

**対処**

1. 次のフル同期を待ってください。この Provider に webhook を公開しないでください。
2. 次の同期でも変更が反映されない場合は、委任、scope、Delegated administrator email を確認してください。
3. 迅速な更新が業務上必要な場合は、リアルタイムのディレクトリ同期を持つ IdP を使ってください。

- [Quick start で Google Workspace を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#identity-providers)

### Lark / Feishu

#### Lark または Feishu がサインイン中にコールバック不一致を報告する

**症状**

承認ページが開かない、または承認が Ankole に戻れない。

**原因**

Lark は redirect_uri を厳密に一致させます。localhost と 127.0.0.1、異なるポート、異なる Provider ID は異なる URL を生成します。

**対処**

1. /setup でこの IdP に表示される完全なコールバックをコピーしてください。
2. アプリのセキュリティ設定に追加し、ホストやパスを書き換えないでください。
3. 新しい設定でバージョンを公開し、テストユーザーを可用範囲に含めてください。

#### Lark または Feishu のサインインは機能するが、従業員や部署が欠けている

**症状**

管理者は Console に入れるが、Principal と権限グループが不完全。

**原因**

ディレクトリ権限が不完全、アプリの可用範囲が従業員を含まない、または新しい権限が公開されたバージョンにない。

**対処**

1. Quick start の一括権限リストを使って、すべてのディレクトリ読み取り権限を追加してください。
2. 必要な部署と従業員をアプリの可用範囲に含めてください。
3. 新しいバージョンを公開し、リアルタイム同期を確認する前にフル同期を検証してください。

#### Lark または Feishu のフル同期は機能するが、従業員の変更が古いまま

**症状**

最初の同期にはデータがあるが、その後の従業員の追加、異動、削除がすぐに反映されない。

**原因**

リアルタイム同期は Lark の長連接 (long connection) とディレクトリイベントを使います。接続、サブスクリプション、公開バージョンがないと、フル同期だけが残ります。

**対処**

1. control plane を稼働させ続け、Events and callbacks で long connection を選択してください。
2. Quick start からユーザーと部署の変更イベントを購読し、アプリを公開してください。
3. control plane からの送信アクセスを許可してください。長連接は公的な ingress を必要としません。

- [Quick start で Lark または Feishu IdP を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#identity-providers)

### DingTalk

#### DingTalk サインインが「アプリケーションが存在しません」(900103) を報告する

**症状**

DingTalk が承認ページが開いた直後に 900103 を報告する。コードスキャン後のコールバックより前。

**原因**

DingTalk はこの Client ID に対して利用可能な内部アプリを見つけられません。値が AgentId や robotCode であるか、アプリの設定が未公開の場合があります。

**対処**

1. AgentId、robotCode、グループロボットの webhook token ではなく、Credentials and basic information の Client ID を使ってください。
2. アプリがこのエンタープライズに属し、必要なサインイン権限とディレクトリ権限を持つことを確認してください。
3. 新しいバージョンを公開し、Ankole から新しい承認ページを開いてください。

#### DingTalk がコードスキャン後にのみコールバックエラーを報告する

**症状**

承認ページは開き、コードスキャンを受け入れるが、同意後に redirect_uri が失敗する。

**原因**

DingTalk は同意後にコールバックを確認します。登録した URL が Ankole が送る URL と厳密に一致しません。

**対処**

1. /setup から完全なコールバック URL をコピーしてください。
2. Development configuration → Security settings → Redirect URL に登録してください。
3. バージョンを公開し、新しいコードスキャンを開始してください。古い承認ページを使い回さないでください。

#### DingTalk のディレクトリ同期が 60011 を報告するか、従業員が欠ける

**症状**

サインインは機能するが、ディレクトリ読み取りが失敗するかメンバーが抜ける。ログにサブコード 60011 が含まれることがある。

**原因**

ユーザー、部署、またはフィールドの読み取り権限がないか、アプリの承認範囲が組織の一部を含まない。

**対処**

1. エラーの付与リンクと Quick start のリストを使って、すべてのディレクトリ権限を追加してください。
2. 必要な部署と従業員をアプリの承認範囲に含めてください。
3. 新しいバージョンを公開し、フル同期を実行してください。ページサイズを変えて権限エラーを隠さないでください。

- [Quick start で DingTalk IdP を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#identity-providers)

### WeCom

#### WeCom のサインインまたは API 呼び出しがエラー 60020 を報告する

**症状**

QR スキャンが Ankole に戻らない、または設定保存時にコード 60020 の無信頼 IP が報告される。

**原因**

WeCom はサーバー呼び出しが登録済みの信頼 IP から来ることを要求します。自社ビルドアプリと Contacts 同期はそれぞれ独自の信頼 IP リストを持ち、egress IP が欠けていると拒否されます。

**対処**

1. Ankole のデプロイに固定の egress IP を与え、自社ビルドアプリの信頼 IP リストに追加してください。
2. 同じ IP を別の Contacts 同期用の信頼 IP リストにも追加してください。
3. サインインのリダイレクトドメインが自社ビルドアプリの信頼ドメインであることを確認してください。

#### WeCom のサインインは機能するが、名前やディレクトリ全体が欠ける

**症状**

メンバーは Console に入れるが、Principal に名前がない、またはディレクトリ同期が空のまま。

**原因**

2022 年 6 月以降、通常のアプリ secret はメンバー名などのプロフィールフィールドを返しません。同期には Management tools → Contacts sync の専用 secret が必要です。

**対処**

1. WeCom コンソールで Contacts API sync を有効にし、Identity Provider に専用 secret を入力してください。
2. その secret にも信頼 IP を登録してください。
3. WeCom はリアルタイムのディレクトリイベントを送りません。変更後はフル同期を実行するか、定期同期を待ってください。

- [Quick start で WeCom IdP を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#identity-providers)

## chat channelのトラブルシューティング

chat channelは IM メッセージを受信し、Agent の返信を送ります。ルーティングルールで使うプラットフォームを選択してください。IdP で使うプラットフォームはこの選択を変えません。

**Choose a chat platform**

- Slack
- Microsoft Teams
- Lark / Feishu
- DingTalk
- WeCom

### Slack

#### Slack のルーティングルールが token のプレフィックスを拒否する

**症状**

channel 保存時に、接続が開く前に invalid_token_prefix が返る。

**原因**

Bot Token と App Token が入れ替わっているか、どちらかの値が別の Slack token タイプ。

**対処**

1. Bot Token は xoxb- で始まり、OAuth & Permissions から取得する必要があります。
2. App Token は xapp- で始まり、connections:write を含む必要があります。
3. 値を修正して保存し直してください。credential の検証が通るまでイベントを調べないでください。

#### Slack の DM は機能するが、channel でのメンションが機能しない

**症状**

ボットは DM に答えるが、channel での明示的な @メンションが Ankole に届かない。

**原因**

ボットが channel のメンバーでないか、アプリが app_mentions:read 付きで app_mention を購読していない。

**対処**

1. テスト channel にボットを招待してください。
2. Event Subscriptions に app_mention を追加し、app_mentions:read を付与してください。
3. scope の変更後、アプリを再インストールし、Ankole の Bot Token を更新してください。

#### Slack は @メンションを配信するが、通常の channel メッセージは配信しない

**症状**

addressed_only は機能するが、observe_all や may_intervene でも明示的なメンションしか見えない。

**原因**

ルーティングルールは Ankole が受信するメッセージを制御します。Slack アプリには、その会話タイプに対する一致する message イベントや history scope がまだありません。

**対処**

1. 最初に addressed_only の完全な経路を検証してください。
2. 対象の会話タイプに、Quick start のとおり message イベントと history scope を追加してください。
3. アプリを再インストールし、token を更新してから、グループメッセージモードを変更してください。

- [Quick start で Slack channel を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#chat-channels)

### Microsoft Teams

#### Teams がメッセージを送るが、Ankole は何も受信しない

**症状**

Teams は返信を表示せず、control plane に一致するインバウンドの activity がない。

**原因**

Teams は Bot Framework の webhook で配信します。プライベートエンドポイント、信頼されない証明書、誤ったパスがあると、リクエストが Ankole に届きません。

**対処**

1. インスタンスに、信頼された証明書を持つ公開 HTTPS アドレスを与えてください。
2. Bot Framework の Messaging endpoint を、Quick start の正確な Teams webhook URL に設定してください。
3. ボットアプリがテストユーザー、チーム、channel にインストールされていることを確認してください。

#### Teams は Ankole に到達するが、返信の送信で認証に失敗する

**症状**

control plane は activity を受信した後、返信を送るときに 401、403、またはボット token エラーを返す。

**原因**

appID、appPassword、tenantID、botTenancy のいずれかが Azure Bot の登録と一致しない。

**対処**

1. appID がアプリケーションの GUID で、appPassword が有効期限切れでない Client Secret の値であることを確認してください。
2. シングルテナントアプリには single_tenant とエンタープライズの tenantID を使ってください。
3. Azure Bot の登録が対応している場合にのみ multi_tenant を使ってください。

#### Teams の個人チャットは機能するが、channel の @メンションは機能しない

**症状**

同じボットが個人チャットでは回答するが、channel メッセージを受信しない。

**原因**

アプリがそのチームや channel にインストールされていないか、メッセージが Teams の期待どおりにボットをメンションしていない。

**対処**

1. 対象チームにアプリをインストールし、対象 channel で許可してください。
2. 最初のテストには明示的な @メンションを使ってください。
3. ルーティングルールが有効で、意図した Agent を対象にしていることを確認してください。

- [Quick start で Teams channel を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#chat-channels)

### Lark / Feishu

#### Lark / Feishu のボットは存在するが、どのメッセージにも返信しない

**症状**

DM もグループの @メンションも Ankole に届かない。

**原因**

ボット機能、公開バージョン、可用範囲、長連接 (long connection)、im.message.receive_v1 のいずれかがアクティブでない。

**対処**

1. ボットを有効にし、テストユーザーをアプリの範囲に含め、最新バージョンを公開してください。
2. Events and callbacks で長連接を選択し、im.message.receive_v1 を購読してください。
3. 送信アクセス付きで control plane を稼働させ続けてください。この接続は公開 webhook を必要としません。

#### Lark / Feishu は @メンションを配信するが、通常のグループメッセージは配信しない

**症状**

addressed_only は機能するが、observe_all や may_intervene ではボットをメンションしないメッセージを見られない。

**原因**

アプリに im:message.group_msg がありません。ルーティングルールは、プラットフォームが配信しないメッセージを読めません。

**対処**

1. 最初に addressed_only の経路を検証してください。
2. Permissions に im:message.group_msg を追加し、新しいバージョンを公開してください。
3. アプリの範囲がグループメンバーをカバーすることを確認してから、グループメッセージモードを変更してください。

#### Lark / Feishu はメッセージを受信するが、返信またはカード更新が失敗する

**症状**

Agent は作業を開始するが、IM に最終返信がない、またはカードが古い状態のまま。

**原因**

チャットアプリにメッセージ送信、更新、メッセージリソース読み取りの権限がないか、新しい権限が未公開。

**対処**

1. Quick start から送信、更新、リソースの権限を追加してください。
2. アプリを公開し、ボットが会話に残っていることを確認してください。
3. 同じ会話で新しいメッセージを送ってください。新しい権限をテストするのに、古い失敗ターンを使わないでください。

- [Quick start で Lark / Feishu channel を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#chat-channels)

### DingTalk

#### DingTalk が @メンションのないグループメッセージを無視するのは障害ですか？

**症状**

DM と明示的な @メンションは Agent を開始できるが、通常のグループメッセージは Ankole に入らない。

**原因**

いいえ。2026 年 7 月時点で、DingTalk はボットを明示的にメンションしたグループメッセージのみを配信し、完全なグループ履歴を Agent に公開しません。

**対処**

1. グループテストのたびに明示的な @メンションを使い、モードを addressed_only に保ってください。
2. Agent が継続的なグループコンテキストを必要とする場合は、Slack、Teams、または Lark/Feishu を使ってください。
3. observe_all を選択しないでください。DingTalk が配信しないメッセージを Ankole は回復できません。

#### DingTalk の返信がプレーンな Markdown のままです。ストリーミングカードにするには？

**症状**

Agent は返信するが、すべてのメッセージがストリーミング AI カードのないプレーンテキスト。

**原因**

DingTalk のカードはテンプレートでホストされます。ルーティングルールの cardTemplateId が空、テンプレートがロボットを所有するアプリに公開されていない、または DingTalk がカードコンテンツを拒否した場合、返信はプレーンな Markdown のままになります。

**対処**

1. Quick start の DingTalk タブの高度なセクションのとおりに AI カードテンプレートを作成し、その id をルーティングルールの cardTemplateId に貼り付けてください。
2. カードが空白の場合は、現在の入力中、完了、または失敗レイアウトに answer にバインドした Markdown コンポーネントがあることを確認し、テンプレートを再公開してください。flowStatus や flowStatusVar は作成しないでください。
3. 一度カードとして届き、その後プレーンテキストになる返信は、恒久的な拒否後の意図したフォールバックです。返信は依然として配信されます。param.contentUnsafe や param.cardNotExist を control plane のログで確認してください。

- [Quick start で DingTalk AI カードテンプレートを作成する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#chat-channels)

#### DingTalk Stream 接続がメッセージを受信しない

**症状**

ルーティングルールは有効だが、DM も明示的な @メンションも Ankole に届かない。

**原因**

不一致の credential、未公開のボット、またはテストユーザーを除外するアプリ範囲は、Stream 接続や配信を停止させることがあります。

**対処**

1. チャットアプリの Client ID と Client Secret を確認してください。うっかり IdP アプリの credential を使い回さないでください。
2. ボットを有効にして公開し、テストユーザーをその範囲に含めてください。
3. control plane からの送信アクセスを許可してください。Stream 接続は公開 webhook を必要としません。

#### 同じ DingTalk アプリを 2 番目の Agent に接続できないのはなぜですか？

**症状**

2 番目のルーティングルールが拒否されるか、別の Agent がすでに同じ Client ID を使っている。

**原因**

現在のアダプターは、1 つの Client ID につき 1 つの Agent を許可します。各 Agent も有効な DingTalk ルートを 1 つだけ持てます。

**対処**

1. 2 番目の Agent が別のボット ID を必要とする場合は、別の内部 DingTalk アプリを作成してください。
2. 新しいルーティングルールに、その新しい Client ID と Client Secret を使ってください。
3. 対象の Agent を変えたいだけなら、新しいルートを有効にする前に古いルートを無効にしてください。

### WeCom

#### WeCom が @メンションのないグループメッセージを無視するのは障害ですか？

**症状**

DM と明示的な @メンションは Agent を開始できるが、通常のグループメッセージ、グループ画像、グループファイルは Ankole に入らない。

**原因**

いいえ。WeCom は DM と、AI ボットを明示的に @メンションしたグループメッセージのみを配信し、グループの @メッセージにはテキストと、テキスト＋画像の混合コンテンツしか含まれません。

**対処**

1. グループテストのたびに明示的な @メンションを使ってください。グループモードは addressed_only だけです。
2. Agent が完全なグループコンテキストやグループで共有されたファイルを必要とする場合は、Lark/Feishu、Slack、または Teams を使ってください。

#### 予定されたリマインダーが WeCom に届かない

**症状**

ユーザーが最初にメッセージを書けば Agent は返信するが、スケジュールの結果のようなプロアクティブなメッセージは配信されない。

**原因**

WeCom は、ユーザーがその会話で最初にボットへメッセージを送ることを要求します。Agent は新しい会話を開始できません。

**対処**

1. 各受信者に最初にボットへ 1 通メッセージを送ってもらい、その会話のプロアクティブ配信を解放してください。
2. インバウンドメッセージ後の返信ウィンドウは 24 時間です。それ以降はプロアクティブな経路だけが残ります。

#### WeCom の接続が切れ続ける、またはチャット ID がディレクトリと一致しない

**症状**

接続が開いてから落ちる、またはチャットユーザーがディレクトリやサインイン ID に統合できない。

**原因**

プラットフォームはボットごとに 1 つの長連接を許可するため、同じ Bot ID を使う別のプログラムが接続を奪います。corp のスーパー管理者が作成していないボットは、暗号化されたユーザー ID を配信します。

**対処**

1. 同じ Bot ID を使う他のプログラムがないことを確認してください。Ankole は奪われた場合、回線を取り合わずに停止して待機します。
2. ボットは corp のスーパー管理者が作成する必要があります。そうでない場合は削除し、スーパー管理者アカウントで再作成してください。

- [Quick start で WeCom channel を設定する](https://ankole.agentbull.com/ja-JP/docs/quickstart/index.md#chat-channels)

## 失敗した境界がまだ不明な場合

障害を 1 回再現してください。正確な時刻、Agent UID、ルーティングルール名、Provider、インターフェースが表示する完全なエラーを記録します。次に、その時刻の前後の control plane と Worker のログだけを収集し、イベント名で最初のエラーを探します。

Client Secret、Bot Token、App Token、model の API key、完全な環境ダンプ、またはマスクされていない設定ファイルは送らないでください。問題を報告するときは、完全なログアーカイブではなく、マスクしたログと正確な再現手順を含めてください。

- [Ankole のログを読む](https://ankole.agentbull.com/ja-JP/docs/log-reading/index.md)