トラブルシューティング¶
本ドキュメントでは、OWL CLI および OWL MCP Server の一般的な接続問題について説明します。
CLI：owl が見つからない¶
現象：
対処方法：
- Windows：現在の PowerShell を閉じて、再度開いてから実行してください。
- Linux / macOS：現在のターミナルウィンドウを閉じて、再度開いてから実行してください。
- 実行ファイルがデフォルトのインストールディレクトリに存在するか確認してください。
デフォルトの実行ファイルパス：
- Windows：
%LOCALAPPDATA%\Programs\owl\owl.exe - Linux / macOS：
$HOME/.local/bin/owl、書き込み不可の場合は/usr/local/bin/owlにフォールバックします。
CLI：旧 testing ビルドをアップグレードできない¶
owl --version が testing-<SHA> を表示する場合、現在のチャネルのインストーラースクリプトが更新済みであることを確認し、owl update を実行します。CLI の先行置換やチャネル変更は不要です。
failed to parse local owl version または failed to read local owl version が出る場合、owl --version が正常に実行でき、対応するリリース版または testing- に続く 7～40 桁の 16 進 Git SHA を返すか確認します。不明・破損・実行失敗のバージョンを旧版とみなして上書きしません。原因を確認してから手動インストールを使用してください。
自動インストール：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：HTTPS 証明書検証失敗¶
ローカル開発環境やプライベートテスト環境で自己署名証明書を使用している場合、CLI が x509: certificate signed by unknown authority を返す可能性があります。システムに信頼できる CA をインストールすることを優先してください。どうしてもインストールできない場合は、一時的に以下を実行できます：
この設定により Registry の ID 検証が無効になり、中間者攻撃を受ける可能性があります。制御された開発環境でのみ使用し、本番環境では絶対に有効にしないでください。検証を復元するには owl config set registry.insecure_skip_verify false を実行してください。
CLI：長時間クエリがタイムアウトする¶
データクエリが context deadline exceeded を返す場合は、まずネットワークと Registry の状態を確認し、次に registry.request_timeout を確認してください。この値の単位はミリ秒で、デフォルトは 150000 です。データクエリツールのサーバー側期限は 130 秒であるため、クライアント側の合計タイムアウトをこれより短く設定することは推奨されません。
クライアント側のタイムアウトを増やしても、サーバー側のクエリ期限は延長されません。クエリが引き続き失敗する場合は、時間範囲を狭めたり、返却量を減らしたり、クエリ条件を簡略化してください。
CLI：tool not found が表示される¶
原因：ローカルキャッシュに対象のツールがない、またはツール名の入力が誤っている。
対処方法：
ツール名を確認してから再実行してください。
CLI：category not found が表示される¶
原因：カテゴリ名が存在しない、またはまだ同期されていない。
対処方法：
CLI：missing required parameter が表示される¶
原因：必須パラメータが不足している。
対処方法：
ツール定義に従って必須パラメータを補完してから再実行してください。
CLI：unknown parameter が表示される¶
原因：パラメータ名がツール定義と一致していない。
対処方法：
パラメータ名を確認してから再実行してください。
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：結果が空、または期待と異なる¶
以下の順序で確認してください：
owl show <ツール名>を使用してパラメータ定義を確認するowl list -c <カテゴリID>を使用して、正しいツールが実行されているか確認するowl syncを使用してローカルキャッシュを更新する- クエリの時間範囲が正しいか確認する。時間パラメータは 13 桁のミリ秒タイムスタンプである必要があります。
- 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 が所属するワークスペースが、現在アクセスしようとしているワークスペースであるか。
リクエストヘッダー形式：
説明：
/mcpエンドポイントは、イベントストリームを確立する前に認証を行います。認証情報が不足しているか無効な場合、HTTP401 Unauthorized（およびWWW-Authenticate: Bearer realm="mcp"レスポンスヘッダー）が直接返され、text/event-streamイベントストリームは開始されません。そのため、クライアントが「接続されたがイベントストリームが空」と報告した場合、実際には 401 を受信している可能性が高いです。これは空のストリームではなく認証の問題である可能性が高いため、401 とWWW-Authenticateヘッダーに基づいて認証情報を修正し、再試行してください。
MCP：ツールリストが空¶
考えられる原因：
- MCP クライアントがサービスに正常に接続できていない。
- API Key が無効か、権限が不足している。
- クライアントが MCP ツールリストを更新していない。
- Endpoint の選択が誤っている。
対処方法：
- クライアントで MCP 接続を再度テストする
- Endpoint がワークスペースのサイトと一致しているか確認する
- Authorization Header が正しいか確認する
- MCP クライアントを再読み込みまたは再起動する
MCP：ツール呼び出しで権限エラーが返る¶
原因：API Key に対応する Open API 権限がない。
対処方法：
- API Key の権限範囲を確認する
- 読み取り専用のシナリオには、対応する参照権限を付与する
- 書き込みシナリオには、対応する書き込み権限を付与する
- Agent に過度に広い API Key 権限を直接設定することは推奨されません。
MCP：ツール呼び出しで空の結果が返る¶
以下の順序で確認してください：
- クエリの時間範囲は正しいか。
- 選択したデータドメイン、source、field、index は存在するか。
- 先に発見系ツール（例：
owl.metric.list、owl.log_index.list）を呼び出す必要があるか。 - API Key にそのデータ範囲の読み取り権限があるか。
- 現在のワークスペースに実際に対応するデータが存在するか。
MCP：書き込み操作がブロックされる、または反映されない¶
考えられる原因：
- API Key に書き込み権限がない。
- クライアントで手動確認が設定されているが、確認されていない。
- パラメータ構造がツールの要件を満たしていない。
- ワークスペース側に承認または監査の制限がある。
対処方法：
- ツールパラメータを確認する
- API Key の権限を確認する
- クライアントが手動確認を待っているか確認する
- ワークスペース側の承認、監査、または権限設定を確認する