FAQ とトラブルシューティング
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/faq/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
このページは製品概要やセットアップ手順を一から繰り返すものではありません。まずどの境界で失敗しているかを切り分け、該当する Identity Provider またはチャットプラットフォームの項目を確認してください。インストールと初回セットアップの正規手順については Quick start を参照してください。
失敗した境界を見つける
| 観察される症状 | 最初に確認する箇所 |
|---|---|
/setup または Console が開かない |
デプロイ環境、control-plane、function-runtime、PostgreSQL、DNS、HTTPS |
| Console や Pod は開くが、サインインに失敗するかディレクトリが不完全 | エンタープライズ IdP SSO、パスワードレスのメール OTP(authn.email.mail による SiteCredential)、principals.pod_login_policy、および siteadmin / pod_admin メンバーシップ |
| Console 上では Agent と会話できるが、特定の IM でメッセージが処理されない | 該当する Channel Provider と signal routing rule |
| IM のメッセージは Ankole に届いているが、Agent が返信を生成できない | LLM Provider、Agent の model profile、Worker |
| 1 つのプラットフォームだけで問題が起きている | 下のタブから該当 Provider のみを確認する(他プラットフォーム向けの対処を混ぜて適用しない) |
すべてのプラットフォームに共通する問題
/setup や Console が開かないとき、何を確認すればよいですか?
- 症状
- ページがタイムアウトする、接続が拒否される、502 が返る、または画面が真っ白なままになる(Provider のセットアップにまだ到達していない状態)。
- 原因
- control plane が正常に稼働していないか、DNS・リバースプロキシ・Ingress から control plane へトラフィックが転送されていません。これ以降に出る Provider 関連のエラーも、多くはこの疎通不良が連鎖したものです。
- 対処
- control-plane、function-runtime、PostgreSQL、およびリバースプロキシの状態を確認し、ログに記録された最初のエラーから順に解消してください。
- control plane へ直接アクセスできる場合は、DNS、TLS 証明書、およびプロキシの転送先設定を確認してください。
- データベースや永続ボリュームを安易に削除しないでください。起動に失敗したからといって、データが破損しているとは限りません。
初回セットアップの activation code はどこにありますか?
- 症状
- /setup で activation code の入力を求められたが、起動時のターミナルをすでに閉じており、ログにもコードが見当たらない。
- 原因
- activation code が使われるのは初回セットアップ時のみです。最初の siteadmin 管理者がサインインを完了した時点で失効します。
- 対処
- まだセットアップが完了していない場合は、Quick start でお使いのデプロイ方式のタブを開き、そこに記載されているログ確認コマンドを実行してください。
- ログから SETUP ACTIVATION CODE を検索してください。ブラウザのストレージやデータベースの行から推測しようとしないでください。
- すでに siteadmin(または Pod の pod_admin)管理者が作成済みの場合は、再アクティベートは不要です。パスワードレスのメール OTP(authn.email.mail による SiteCredential)または設定済みのエンタープライズ IdP SSO でそのままサインインしてください。
選択したアダプターが Provider リストに表示されないのはなぜですか?
- 症状
- プラグインを有効化して保存したはずなのに、セットアップ画面や identity・signal-routing の設定画面に選択肢として出てこない。
- 原因
- 初回セットアップ画面ではコンパイル済みの全プラグインを選択できますが、それ以降の設定画面では保存済みの有効プラグインだけが表示されます。また、セットアップ完了後に Console で保存したプラグイン変更は、次回の control plane 起動時に反映されます。
- 対処
- まだ /setup の途中であれば、Plugins ステップに戻って選択を保存し直し、管理者サインイン画面を開き直してください(再起動は不要です)。
- すでにセットアップが完了している場合は、control plane のみを再起動してください(データの削除や PostgreSQL の再起動は行わないでください)。プラグインが有効になったことを確認してから Provider 設定画面を開き直します。
- control plane が起動しなくなった場合は、ログに出力されている最初のプラグイン初期化エラーを確認して修正してください。
どのチャットプラットフォームからも返信が返ってきません。channel 側の問題でしょうか?
- 症状
- グループ channel、DM、別のチャットアプリのすべてで応答がなく、Console 上で Agent に直接話しかけても失敗する。
- 原因
- Console での直接会話まで失敗する場合は、特定のチャットプラットフォームのイベント権限ではなく、共通の下流経路(LLM Provider、Agent の model profile、または Worker)に原因がある可能性が高いです。
- 対処
- LLM Provider が有効化されており、認証情報とモデル名が正しく機能するか確認してください。
- 対象 Agent の primary profile が有効で、利用する profile が正しく解決できることを確認してください。Console → Workers で、その Agent の Worker にエラーが出ていないかも確認します。
- まず Console 上で実際のモデルとの会話を 1 往復成功させてから、チャットプラットフォーム側の確認に戻ってください。
スケジュールが予定時刻に実行されませんでした。最初に何を確認すべきですか?
- 症状
- スケジュール自体は登録されているのに、想定した時刻に起動しない、または次回実行予定時刻が想定とずれている。
- 原因
- スケジュールが無効になっているか、スケジュールのタイムゾーンや cron 式の指定が誤っているか、あるいはトリガー時刻に control plane が停止していた可能性があります。
- 対処
- 対象のスケジュールを開き、有効になっていることと、画面に表示されている次回実行時刻を確認してください。
- スケジュールのタイムゾーンと cron 式を見直してください。cron 式を頭の中で計算するのではなく、Console が算出して表示している次回時刻を基準に確認します。
- [Run now] を実行してみてください。これで正常に動けば時刻・cron 設定の問題であり、失敗する場合は実行記録(run record)を確認します。
スケジュール自体は実行されたのに、チャットに結果が届かないのはなぜですか?
- 症状
- 実行記録は残っているが、宛先のチャットや会話に Agent からのメッセージが投稿されない。
- 原因
- スケジュールのトリガー自体は正常に動作しています。原因はその後の配信・実行経路(宛先ルート、Channel Provider、Agent の model、または Worker の稼働状態)にあります。
- 対処
- 実行記録を開いて結果ステータスを確認し、記録されている最初のエラー内容を読んでください。
- 対象 Agent、送信先の会話・チャット、および対応する signal routing rule の設定を確認してください。
- Agent の model profile が正常に機能していること、また Console → Workers で Worker にエラーが出ていないことを確認してください。
Identity Provider のトラブルシューティング
IdP はサインイン認証と連絡先・組織構造の同期を担います。組織で利用している identity ソースを選択してください。Slack の Socket Mode、Entra ID の Graph サブスクリプション、Google Workspace の定期フル同期はそれぞれ仕組みが異なるため、確認ポイントも異なります。
認可リダイレクト時に Slack サインインが失敗する
- 症状
- Ankole に戻る前に Slack 側で redirect_uri の不一致エラーが出る、または認可後に想定外のページへ遷移してしまう。
- 原因
- Slack アプリに登録した Redirect URL が /setup に表示されているコールバック URL と完全一致していないか、Ankole 側に別の Slack アプリの Client ID が入力されています。
- 対処
- /setup に表示されている完全なコールバック URL をコピーし、Slack アプリの OAuth & Permissions → Redirect URLs にそのまま登録してください。
- スキーム、ホスト、ポート、パス、Provider ID を 1 文字ずつ照合してください。
- Slack アプリの設定を保存したら、古い認可画面は閉じ、Ankole から新しくサインインをやり直してください。
Slack サインインは成功するが、メンバーやユーザーグループが同期されない
- 症状
- 管理者は Console にサインインできるものの、Principal や権限グループが空のままか、最近追加したメンバーが見当たらない。
- 原因
- IdP 用アプリに users:read、users:read.email、usergroups:read(または team:read)が不足しているか、scope 追加後にアプリを再インストールしておらず古い Bot User OAuth Token を使っているか、まだフル同期を実行していません。
- 対処
- Quick start に記載されている identity 用の scope をすべて追加してください。
- scope を変更した後は必ずアプリをワークスペースへ再インストールし、再発行された Bot User OAuth Token を Ankole の IdP 設定に保存してください。
- リアルタイム同期を調べる前に、まず手動でフル同期を実行して結果を確認してください。
フル同期は完了するのに、その後のディレクトリ変更が反映されない
- 症状
- 初回のフル同期ではデータが入るが、後からメンバーやユーザーグループを変更してもすぐには反映されない。
- 原因
- リアルタイム同期には 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 側の値も更新し、実際にディレクトリを変更して反映をテストしてください。
chat channel のトラブルシューティング
chat channel は IM メッセージの受信と Agent からの返信送信を担います。ルーティングルールで使用しているチャットプラットフォームを選択してください(IdP 側でどのプラットフォームを使っているかは関係ありません)。
Slack のルーティングルール保存時に token プレフィックスエラーが出る
- 症状
- channel 設定の保存時、接続を開始する前の段階で invalid_token_prefix が返される。
- 原因
- Bot Token と App Token を取り違えて入力しているか、別の種類の Slack token を貼り付けています。
- 対処
- Bot Token には、OAuth & Permissions で取得した xoxb- で始まるトークンを指定してください。
- App Token には、connections:write スコープを持つ xapp- で始まるトークンを指定してください。
- 正しい値に入れ替えて保存し直してください。認証情報の検証に通る前にイベント設定側を調査する必要はありません。
Slack の DM は届くのに、channel での @メンションが反応しない
- 症状
- ボットは DM には応答するが、channel 内で明示的に @メンションしても Ankole に届かない。
- 原因
- ボットが対象 channel に招待されていないか、Slack アプリ側で app_mention イベントの購読または app_mentions:read スコープが不足しています。
- 対処
- テスト対象の channel にボットを招待してください。
- Event Subscriptions に app_mention を追加し、Bot Token Scopes に app_mentions:read を付与してください。
- スコープを変更した後はアプリをワークスペースへ再インストールし、Ankole 側の Bot Token も更新してください。
Slack で @メンションは届くが、通常の channel メッセージが届かない
- 症状
- addressed_only は動作するが、observe_all や may_intervene に切り替えても明示的なメンションしか認識されない。
- 原因
- ルーティングルールで処理モードを変えても、Slack アプリ側に対象の会話種別に対応する message イベント購読と history スコープがなければ、メッセージ自体が Ankole に配信されません。
- 対処
- まずは addressed_only で一連の送受信が正常に動くことを確認してください。
- Quick start の手順に従い、対象の会話種別に対応する message イベントと history スコープを追加してください。
- アプリを再インストールして Bot Token を更新してから、グループメッセージモードを変更してください。
失敗した境界がまだ不明な場合
問題を 1 回だけ再現させ、正確な発生時刻、Agent UID、ルーティングルール名、Provider 名、および画面に表示されたエラーメッセージ全文を控えてください。そのうえで、発生時刻前後の control plane と Worker のログだけを抽出し、イベント名を手がかりに最初のエラーを特定します。
なお、サポートや Issue で報告する際は、Client Secret、Bot Token、App Token、モデルの API key、環境変数の一括ダンプ、マスクしていない設定ファイルを絶対に含めないでください。ログ一式の丸ごと添付は避け、秘密情報をマスクした該当箇所のログと正確な再現手順を添えて共有してください。