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

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

失敗した境界を見つける

観察されること	最初に確認すること
`/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 エラーはたいてい連鎖の結果です。

対処

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

デプロイを確認するログを読む

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

症状

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

原因

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

対処

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

activation code を読む

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

症状

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

原因

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

対処

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

Agent Library で Plugin を有効化する

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

症状

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

原因

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

対処

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

LLM Provider と Agent を設定する Worker fleet

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

症状

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

原因

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

対処

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

スケジュールの設定と確認

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

症状

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

原因

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

対処

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

スケジュールの実行を確認する signal routing rule を確認する

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

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

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

症状

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

原因

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

対処

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

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

症状

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

原因

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

対処

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

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

症状

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

原因

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

対処

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

Quick start で Slack IdP を設定する

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

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

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

症状

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

原因

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

対処

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

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

症状

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

原因

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

対処

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

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

症状

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

原因

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

対処

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

Quick start で Slack channel を設定する

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

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

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

Ankole のログを読む