OWL の自動インストール¶

本ドキュメントは、AI ツールで OWL を利用するユーザーを対象に、自動インストール方式による OWL CLI、認証設定、ツールディレクトリの同期、および OWL Skill のインストール方法を説明します。

OWL Skill は AI ツール向けの付随機能であり、AI ツールがローカルの owl コマンドを認識し、OWL ツールディレクトリを理解し、ログ、メトリクス、イベント、トレースなどの診断機能をより安定して呼び出せるようにします。自動インストールでは、OWL CLI のインストール後に、あわせて OWL Skill もインストールします。

ターミナルで手動で OWL CLI のみを使用する場合は、OWL Skill をスキップしても問題ありません。

現在の環境でターミナルコマンドを実行できない、外部ネットワークや企業ネットワーク内の OWL CLI Endpoint にアクセスできない、またはオフラインインストールが必要な場合は、OWL の手動インストールを参照してください。

ユースケース¶

以下のようなユースケースに適しています。

AI ツールがターミナルコマンドの実行権限を持っている
現在の環境から OWL CLI Endpoint およびインストールリソースの URL にアクセスできる
現在の環境でローカルユーザーディレクトリ下への OWL 設定の書き込みが許可されている
ユーザーがワークスペースに対応する OWL CLI Endpoint と一時認証コードを提供できる

以下のようなユースケースには適していません。

現在のツールが純粋なチャットツールであり、ターミナルコマンドを実行できない
現在の環境が制限されたネットワーク環境またはオフライン環境である
現在の環境で AI ツールによるローカル設定の書き込みが許可されていない
インストールプロセスの各コマンドを人手で確認してから実行する必要がある

インストール手順¶

以下の内容を AI ツールのダイアログウィンドウにコピーして実行してください。コピーする前に、以下の置き換えを行ってください。

<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 ドキュメントは、中国語版（skill.md）と英語版（skill.en.md）の2種類を提供しています。AI ツールの言語環境に応じて選択してください。

パラメータ説明¶

パラメータ	説明	入力方法
`OWL_REGISTRY_ENDPOINT`	Guance センター OWL CLI Endpoint	ワークスペースが属するサイトに応じて対応する Endpoint を選択
`OWL_TEMP_CODE`	短期間有効な一時認証コード	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 デプロイメント	アフリカリージョン1（南アフリカ）	`https://za1-owl-api.guance.com`
SaaS デプロイメント	インドネシリージョン1（ジャカルタ）	`https://id1-owl-api.guance.com`
SaaS デプロイメント	中東リージョン1（UAE）	`https://me1-owl-api.guance.com`
SaaS デプロイメント	無料トライアルリージョン（北京）	`https://cn3-owl-api.guance.com`
プライベートデプロイメント版	プライベートデプロイメント版	実際のデプロイメントで提供される OWL CLI Endpoint に従う

実行内容¶

AI ツールはインストール手順に従い、以下の操作を自動的に実行します。

OWL CLI のダウンロードとインストール
ワークスペースに対応する OWL CLI Endpoint の書き込み
OWL_TEMP_CODE を使用した API Key との交換
認証情報のローカル OWL 設定への書き込み
owl sync の実行によるツールディレクトリの同期
OWL Skill のインストール
owl コマンドの可用性確認

インストールが完了すると、AI ツールはローカルの owl コマンドと OWL Skill を組み合わせて、Guance の診断機能を使用できるようになります。

セキュリティについて¶

自動インストールでは、AI ツールに API Key の平文を提供する必要はありません。AI ツールは OWL_TEMP_CODE を使用して API Key と交換し、認証情報をローカルの OWL 設定に書き込みます。インストール中に、返信、ログ、またはコマンド出力に API Key の平文が表示されないようにしてください。

OWL_TEMP_CODE は短期間有効な一時認証トークンであり、インストールフェーズで API Key と交換するためにのみ使用されます。このトークンは直接インターフェースを呼び出すことはできませんが、有効期限内は機密情報として扱う必要があります。公開の場に貼り付けたり、長期保存のログに書き込んだり、コードリポジトリや共有ドキュメントにコミットしたりしないでください。

自動インストール完了後、OWL がアクセスできるリソースと実行できる操作は、交換された API Key によって決定され、Guance ワークスペースの権限設定に従います。

よくある質問¶

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 --help
owl config show

ツールディレクトリの同期に失敗する場合¶

owl sync が認証、権限、またはネットワークエラーを返す場合は、以下を確認してください。

OWL_TEMP_CODE が API Key との交換に成功しているか
現在の API Key がツールディレクトリの同期に必要な権限を持っているか
現在の環境が OWL CLI Endpoint にアクセスできるか

その他の問題については、トラブルシューティングを参照してください。