OWL の自動インストール¶
このドキュメントは、AI ツールで OWL を使用する必要があるユーザーを対象に、自動インストール方式で OWL CLI、認証設定、ツールカタログの同期、OWL Skill のインストールを完了する方法を説明します。
OWL Skill は AI ツール向けの付属機能であり、AI ツールがローカルの owl コマンドを認識し、OWL のツールカタログを理解し、ログ、メトリクス、イベント、トレースなどの診断機能をより安定して呼び出せるようにするためのものです。自動インストールの流れでは、OWL CLI のインストール後に、現在の Agent のメカニズムに従って OWL Skill をインストールします。
ターミナルで手動で OWL CLI のみを使用する場合は、OWL Skill をスキップできます。
インストールコマンドを段階的にレビューする場合やオフラインでインストールする場合は、OWL の手動インストールを使用してください。現在の環境から OWL CLI Endpoint にアクセスできない場合は、まずネットワークアクセスの問題を解決する必要があります。インストール方式を変えても、呼び出し時のネットワーク要件は変わりません。
対応 Agent¶
Codex、Claude Code、Cursor、Trae、GitHub Copilot(VS Code)、Windsurf のいずれも、本ページの統一された手順を使用できます。ターミナル実行権限を持つ Agent モードで操作してください。ターミナルコマンドを実行できる他の Agent でも同じ流れで使用でき、特定の製品に変更する必要はありません。
OWL CLI は Agent が実際にコマンドを実行する環境 にインストールする必要があります。ローカルの Agent ではローカルにインストールします。リモート開発、コンテナ、クラウド上の Agent では、それぞれの環境にインストールし、その環境から OWL CLI Endpoint にアクセスできることを確認する必要があります。ローカルへのインストールが成功しても、リモート環境で owl が見つかるとは限りません。
インストール前に、接続方式の説明を参照して選択を確認できます。現在のツールがターミナルコマンドを実行できず、リモート MCP をサポートしている場合は、MCP 接続に切り替えることができます。
ユースケース¶
次のユースケースに適しています:
- AI ツールにターミナルコマンドの実行権限がある
- 現在の環境から OWL CLI Endpoint およびインストールリソースのアドレスにアクセスできる
- 現在の環境で、ローカルユーザーディレクトリ配下の OWL 設定に書き込みが許可されている
- ユーザーがワークスペースに対応する OWL CLI Endpoint と一時認証コードを提供できる
次のユースケースには適していません:
- 現在のツールが純粋なチャットツールであり、ターミナルコマンドを実行できない
- 現在の環境が制限されたネットワークまたはオフライン環境である
- 現在の環境で AI ツールによるローカル設定への書き込みが許可されていない
- インストール過程の各コマンドを人手でレビューしてから実行する必要がある
ステップ 1:CLI と付属 Skill のインストール¶
以下の手順は上記すべての Agent に適用されます。インストール指示を現在の Agent のチャットウィンドウに送信し、表示される案内に従って必要なコマンド実行権限を確認してください。自動インストールには付属 Skill のインストール手順が含まれるため、インストール成功を確認した後に別途インストールする必要はありません。コピーする前に、以下を置き換えてください:
<OWL_REGISTRY_ENDPOINT>を、ワークスペースが属するサイトに対応する OWL CLI Endpoint に置き換えます<YOUR_TEMP_CODE>を、Guance コンソールで生成した一時認証コードに置き換えます
https://static.guance.com/owl/skill.md を読み、ドキュメントに従って現在の環境に OWL CLI と OWL Skill をインストールして設定してください。
インストールパラメータは次のとおりです:
OWL_REGISTRY_ENDPOINT="<OWL_REGISTRY_ENDPOINT>"
OWL_TEMP_CODE="<YOUR_TEMP_CODE>"
公式 Skill ドキュメントには中国語版と英語版の 2 種類があり、skill.md(中国語)と skill.en.md(英語)を AI ツールの言語環境に応じて選択できます。
ステップ 2:インストールの確認と初回呼び出し¶
インストール完了後、同じ Agent の会話で次を送信します:
owl コマンドと owl-diagnostics Skill が使用可能か確認してください。まず owl.metric.list のツール説明を確認し、次に OWL CLI を使用して現在のワークスペースで利用可能なメトリクス source を一覧表示してください。結果ファイルが返された場合は、そのファイルを読み取ってビジネス結果を確認してください。読み取り操作のみを実行し、設定やリソースは変更しないでください。
次の結果を確認します:
- Agent が
owl --helpを実行できる。付属 Skill がインストール済みで、Agent がそのタスク説明を読み取れる。更新または新規セッションの作成を求められた場合は、現在の Agent の指示に従って操作します owl syncが正常に完了している。同期後のツールカタログを確認できる- Agent が実際に OWL CLI のツール呼び出しを実行している。結果ファイルが返された場合はその内容を読み取り、ビジネスエラーがないことを確認し、返されたデータに基づいて回答している
コマンドの終了コードが 0 であることだけでクエリの成功を判断せず、返却内容のビジネスステータスとエラー情報(success、error など)も確認する必要があります。成功時に空のリストが返された場合は、現在のワークスペースのデータと権限を確認してください。障害対応については、Agent の CLI と Skill の問題を参照してください。
Skill のインストールに失敗した場合、または現在の Agent にネイティブな Skill メカニズムがない場合でも、CLI は単独で使用できます。インストール説明の案内に従い、現在の Agent の Skill またはカスタム指示の入口から付属ガイドをインポートし、別途読み取り可能かどうかを確認してください。
CLI を手動でインストール済みのユーザーは、付属 Skill のインストールに従って後続の手順を完了できます。CLI を重複してインストールする必要はありません。
パラメータ説明¶
| パラメータ | 説明 | 入力方法 |
|---|---|---|
OWL_REGISTRY_ENDPOINT |
Guance センターの OWL CLI Endpoint | ワークスペースが存在するサイトに応じて対応する Endpoint を選択します |
OWL_TEMP_CODE |
Studio のワンタイム一時認証コード。インストールスクリプトと owl login --dpop で使用します |
Guance コンソールの個人用 API キーページで生成します |
OWL_REGISTRY_ENDPOINT には Endpoint のルートアドレスのみを入力し、/api/v1 などのパスを手動で連結しないでください。
一時認証コードの取得手順:
- コンソール右上のプロフィール画像をクリックします
- 「個人用 API キー」を選択します
- 「一時認証コードを生成」をクリックします
Endpoint リスト¶
OWL CLI サービスはサイトごとに独立した Endpoint を提供します。ワークスペースが存在するノードに応じて、対応するサービスアドレスを選択してください。
| デプロイタイプ | ノード名 | Endpoint |
|---|---|---|
| SaaS デプロイ | 中国リージョン1(杭州) | https://owl-api.guance.com |
| SaaS デプロイ | 中国リージョン2(寧夏) | https://aws-owl-api.guance.com |
| SaaS デプロイ | 中国リージョン4(広州) | https://cn4-owl-api.guance.com |
| SaaS デプロイ | 中国リージョン6(香港) | https://cn6-owl-api.guance.one |
| SaaS デプロイ | グローバルリージョン1(オレゴン) | https://us1-owl-api.guance.com |
| SaaS デプロイ | ヨーロッパリージョン1(フランクフルト) | https://eu1-owl-api.guance.one |
| SaaS デプロイ | アジアパシフィックリージョン1(シンガポール) | https://ap1-owl-api.guance.one |
| SaaS デプロイ | アジアパシフィックリージョン2(シンガポール) | https://ap2-owl-api.guance.com |
| SaaS デプロイ | アフリカリージョン1(南アフリカ) | https://za1-owl-api.guance.com |
| SaaS デプロイ | インドネシアリージョン1(ジャカルタ) | https://id1-owl-api.guance.com |
| SaaS デプロイ | 無料ゾーン(北京) | https://cn3-owl-api.guance.com |
| プライベートデプロイ版 | プライベートデプロイ版 | 実際のデプロイで提供される OWL CLI Endpoint によります |
実行内容¶
AI ツールはインストール説明に従って、次の操作を自動実行します:
- OWL CLI をダウンロードしてインストールします
- ワークスペースに対応する OWL CLI Endpoint を書き込みます
- インストーラーが
owl login --dpopを呼び出し、OWL_TEMP_CODEから一時コードを読み取ってローカル認証情報を保存します - 認証情報をローカル OWL 設定に書き込みます
owl syncを実行してツールカタログを同期します- OWL Skill をインストールします
owlコマンドの可用性を検証します
CLI と Skill の両方が正常にインストールされると、AI ツールは実行環境の owl コマンドと OWL Skill を組み合わせて Guance の診断機能を利用できます。
セキュリティについて¶
新しい OWL では、一時認証コードを使用して DPoP Access Token を取得し、ローカルで秘密鍵を生成して、ビジネスリクエストに署名します。インストールおよびログイン時には状態のみを表示し、応答、ログ、コマンド出力に一時コード、Token、秘密鍵を表示しません。
OWL_TEMP_CODE は短期間のみ有効で、正常に交換されると無効になります。できるだけ早く使用し、公開の場に貼り付けたり、長期保存のログ、コードリポジトリ、共有ドキュメントに保存したりしないでください。旧バージョンの CLI を指定してインストールする場合、インストーラーは引き続き旧インターフェース経由で一時コードを API Key に交換します。
DPoP ログインでは、選択したアカウントおよびワークスペースの権限に従ってリソースにアクセスします。API Key を使用する場合、アクセス範囲はその Key に依存します。どちらの方式でも、対象ツールの読み取りまたは書き込み権限が必要です。
よくある対処¶
AI ツールがコマンドを実行できない¶
AI ツールがターミナルコマンドを実行できないと表示する場合は、ターミナル実行権限を持つ AI ツールでインストール指示を再実行するか、OWL の手動インストールに切り替えてください。
一時認証コードが無効、期限切れ、または権限がない¶
認証コードが無効、期限切れ、または権限がないと表示される場合は、Guance コンソールで OWL_TEMP_CODE を再生成してから、インストール指示を再度実行してください。
Endpoint にアクセスできない¶
Endpoint にアクセスできないと表示される場合は、以下を確認してください:
- 現在の環境から外部ネットワークまたは企業ネットワーク上の OWL CLI Endpoint にアクセスできる
- ワークスペースが属するノードと
OWL_REGISTRY_ENDPOINTが一致している OWL_REGISTRY_ENDPOINTに/api/v1などのパスが連結されていない
インストール後に owl コマンドが認識されない¶
インストール後に owl コマンドが認識されない場合は、ターミナルを開き直すか、AI ツールに現在のターミナル環境変数を更新させてから再検証してください。
次のコマンドを実行して確認できます:
ツールカタログの同期に失敗する¶
owl sync が認証、権限、またはネットワークエラーを返す場合は、以下を確認してください:
owl config showにDPoP: configuredが表示されるか。API Key でインストールした場合は、使用している Key が有効か確認する- 対象サイトが DPoP をサポートしているか、現在のアカウントに対象ワークスペースおよびツールの権限があるか
- 現在の環境から OWL CLI Endpoint にアクセスできるか
その他の問題については、トラブルシューティングを参照してください。
