トラブルシューティング¶

このドキュメントでは、OWL CLI および OWL MCP Server の一般的な接続問題について説明します。

CLI：「owl」が見つからないというエラー¶

現象：

command not found: owl

対処方法：

• Windows：現在の PowerShell を閉じて、再度開いてから実行してください。
• Linux / macOS：現在のターミナルウィンドウを閉じて、再度開いてから実行してください。
• 実行ファイルがデフォルトのインストールディレクトリに存在することを確認してください。

デフォルトの実行ファイルパス：

• Windows：%LOCALAPPDATA%\Programs\owl\owl.exe
• Linux / macOS：$HOME/.local/bin/owl。書き込み不可の場合は /usr/local/bin/owl にフォールバックします。

自動インストール：AI ツールがコマンドを実行できない¶

原因：現在の AI ツールにターミナルコマンドの実行権限がない、または現在の環境でローカル構成への書き込みが禁止されている。

対処方法：

• ターミナルコマンドの実行をサポートする AI ツールに切り替えてください。
• または、手動インストール に切り替えてください。

自動インストール：一時認証トークンが無効、期限切れ、または未認証¶

原因：OWL_TEMP_CODE が期限切れまたは既に使用済み、コピーミス、または現在のアカウントに認証コードを生成する権限がない。

対処方法：

• Guance コンソールで一時認証トークンを再生成してください。
• 自動インストール のインストール手順を再実行してください。
• 既に使用した OWL_TEMP_CODE を再利用しないでください。

自動インストール：Endpoint が一致しない¶

原因：OWL_REGISTRY_ENDPOINT がワークスペースが属するサイトと一致していない、または誤って /api/v1 を追加している。

対処方法：

• ワークスペースが属するノードに基づいて OWL CLI Endpoint を再選択してください。
• OWL_REGISTRY_ENDPOINT には Endpoint のルートアドレスのみを入力してください。
• プライベートデプロイメント環境では、実際のデプロイメントで提供される OWL CLI Endpoint を使用してください。

CLI：認証失敗、または Endpoint にアクセスできない¶

以下を確認してください：

• OWL_REGISTRY_ENDPOINT が現在のサイトの OWL CLI Endpoint であるか。
• Endpoint に誤って /api/v1 が追加されていないか。
• アクセストークンが有効か。OWL_API_KEY と OWL_TOKEN はどちらもアクセストークンとして使用できます。両方が設定されている場合は OWL_API_KEY が優先されます。
• API Key に必要な Open API アクセス権限があるか。
• 現在のターミナルから OWL CLI Endpoint にアクセスできるか。

CLI：「tool not found」エラー¶

原因：ローカルキャッシュに対象のツールがない、またはツール名の入力ミス。

対処方法：

owl sync
owl list

ツール名を確認してから再実行してください。

CLI：「category not found」エラー¶

原因：カテゴリ名が存在しない、またはまだ同期されていない。

対処方法：

owl sync
owl category list

CLI：「missing required parameter」エラー¶

原因：必須パラメータが不足している。

対処方法：

owl show <ツール名>

ツールの定義に従って必須パラメータを補完してから再実行してください。

CLI：「unknown parameter」エラー¶

原因：パラメータ名がツールの定義と一致しない。

対処方法：

owl show <ツール名>

パラメータ名を確認してから再実行してください。

CLI：owl validate が検証失敗を返す¶

owl validate は事前チェックのみを実行し、対象のツールは呼び出しません。JSON 結果の request_executed は常に false になります。

検証不合格の結果とコマンド自体の失敗を区別してください：

• JSON に valid: false が含まれている場合は、ツールを実行しないでください。issues の kind と code に従ってパラメータを修正してください。
• コマンドが 0 以外の終了コードで終了した場合、または検証の JSON 結果が出力されなかった場合は、検証が完了していません。ツールを実行しないでください。同期、認証、ネットワーク、Registry の可用性を確認した後、再度検証を実行してください。

valid: false の結果については、issues の kind と code に従って対処してください：

• tool / tool_not_found：最初に owl sync を実行し、owl list の出力とツール名が完全に一致することを確認してください。
• parameter / invalid_arguments：問題リストに基づいて、不足しているパラメータ、誤ったタイプ、不明なパラメータを一度に修正してください。
• dql_syntax / dql.parseError：owl.data.query の query_text を修正してください。
• generated_dql / dql.builderError：simple query の select_clause、where_clause、または group_by_clause を修正してください。同じパラメータで再試行しないでください。

validate コマンドがない場合は、バージョン 1.2.0 以降にアップグレードしてください。simple query による DQL 生成の事前チェックには、バージョン 1.2.1 以降が必要です。

CLI：結果が空、または期待と異なる¶

以下の順序で確認してください：

1. owl show <ツール名> でパラメータ定義を確認する。
2. owl list -c <カテゴリID> で正しいツールを実行していることを確認する。
3. owl sync でローカルキャッシュを更新する。
4. クエリの時間範囲が正しいか確認する。時間パラメータは 13 桁のミリ秒タイムスタンプである必要があります。
5. API Key に対応するリソースの Open API アクセス権限があるか確認する。

MCP：クライアントの接続に失敗する¶

以下を確認してください：

• MCP タイプが streamableHttp に設定されているか。
• URL が現在のサイトの OWL MCP Endpoint であるか。
• URL が /mcp で終わっているか。
• リクエストヘッダーに Authorization: Bearer <API Key> が含まれているか。
• クライアントがいるネットワークから OWL MCP Endpoint にアクセスできるか。

MCP：認証失敗¶

以下を確認してください：

• API Key が正しくコピーされているか。
• Authorization Header の形式が正しいか。
• API Key が無効化、削除、またはローテーションされていないか。
• API Key が属するワークスペースが、現在アクセスしようとしているワークスペースであるか。

リクエストヘッダーの形式：

Authorization: Bearer <API Key>

説明：/mcp エンドポイントは、イベントストリームを確立する前に認証を行います。認証情報がないか無効な場合、text/event-stream イベントストリームは開始されず、HTTP 401 Unauthorized（WWW-Authenticate: Bearer realm="mcp" レスポンスヘッダー付き）が直接返されます。そのため、クライアントが「接続されたがイベントストリームが空である」と報告した場合、実際には 401 を受信していないかどうかを優先的に確認してください。これは通常、空のストリームではなく認証問題です。401 と WWW-Authenticate ヘッダーに基づいて認証情報を修正してから再試行してください。

MCP：ツールリストが空¶

考えられる原因：

• MCP クライアントがサービスに正常に接続できていない。
• API Key が無効、または権限が不足している。
• クライアントが MCP ツールリストを更新していない。
• Endpoint の選択が誤っている。

対処方法：

1. クライアントで MCP 接続を再度テストする。
2. Endpoint がワークスペースのサイトと一致していることを確認する。
3. Authorization Header が正しいことを確認する。
4. MCP クライアントをリロードまたは再起動する。

MCP：ツール呼び出しで権限エラーが返される¶

原因：API Key に対応する Open API アクセス権限がない。

対処方法：

• API Key の権限範囲を確認する。
• 読み取り専用のシナリオには、対応するクエリ権限を付与する。
• 書き込みシナリオには、対応する書き込み権限を付与する。
• Agent に過度に広い API Key 権限を直接設定することは推奨されません。

MCP：ツール呼び出しで空の結果が返される¶

以下の順序で確認してください：

1. クエリの時間範囲は正しいか。
2. 選択したデータドメイン、source、field、index は存在するか。
3. 事前に owl.metric.list、owl.log_index.list などの発見系ツールを呼び出す必要があるか。
4. API Key にそのデータ範囲の読み取り権限があるか。
5. 現在のワークスペースに実際に対応するデータが存在するか。

MCP：書き込み操作がブロックされた、または反映されない¶

考えられる原因：

• API Key に書き込み権限がない。
• クライアントで手動確認が設定されているが、確認されていない。
• パラメータ構造がツールの要件を満たしていない。
• ワークスペース側に承認または監査の制限がある。

対処方法：

1. ツールのパラメータを確認する。
2. API Key の権限を確認する。
3. クライアントが手動確認を待っているかどうかを確認する。
4. ワークスペース側の承認、監査、または権限設定を確認する。