OWL の手動インストール¶
本書は OWL ユーザーを対象に、OWL CLI のインストール前の準備、オンラインインストール、指定バージョンのインストール、オフラインインストール、およびインストール完了後の確認方法について説明します。
owl は OWL CLI のコマンド名です。インストール完了後、ユーザーはローカルで owl を通じてツールカタログを同期し、ツールの説明を参照し、プラットフォームの機能を実行できます。
現在使用している AI ツールがターミナルコマンドの実行をサポートしており、OWL CLI、認証設定、ツールカタログの同期、OWL Skill のインストールを自動で完了したい場合は、自動インストールを使用できます。
インストール前の準備¶
インストール前に以下の情報を準備してください:
| 設定項目 | 説明 |
|---|---|
OWL_INSTALL_BASE_URL |
OWL インストールスクリプトおよびインストールパッケージのダウンロード先 |
OWL_REGISTRY_ENDPOINT |
ワークスペースが属するサイトに対応する OWL CLI Endpoint |
OWL_TEMP_CODE |
Studio のワンタイム一時認証コード。インストールスクリプトおよび owl login --dpop で使用します |
OWL_TOKEN |
API Key モードとの互換用。インストーラーに明示的に指定した場合にこの Key を使用します |
OWL_API_KEY |
API Key モード用の CLI 環境変数。同時に設定した場合は OWL_TOKEN より優先されます |
OWL_REGISTRY_ENDPOINT には、ワークスペースが属するサイトに対応する Guance センターの OWL CLI Endpoint を指定してください。/api/v1 を手動で連結しないでください。
DPoP ログインでは、選択したアカウントおよびワークスペースの権限に従ってリソースにアクセスします。API Key を使用する場合、アクセス範囲はその Key に依存します。いずれの方式でも、対象ツールの読み取りまたは書き込み権限が必要です。
権限要件¶
- 現在のワークスペースにアクセスできること
- OWL CLI Endpoint にアクセスできること
- ツールカタログの同期に必要な基本的なアクセス権限があること
- 対象サイトが DPoP をサポートしているか、現在のアカウントが対象のワークスペースとツールに対する権限を持っているか
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 に従います |
サポートプラットフォーム¶
現在のインストールパッケージは以下のプラットフォームをサポートしています:
| オペレーティングシステム | サポートアーキテクチャ |
|---|---|
| Windows | amd64 |
| Linux | amd64、arm64 |
| macOS | amd64、arm64 |
インストールパッケージのファイル名は owl-cli-* を使用し、インストール後のコマンドは owl に統一されます。
オンラインインストール¶
Linux / macOS¶
OWL_INSTALL_BASE_URL="https://static.guance.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
bash -c "$(curl -fsSL https://static.guance.com/owl/install.sh)" -- --yes
実行前に、システムに以下のコマンドがインストールされていることを確認してください:
- bash
- curl
- tar
Windows¶
$env:OWL_INSTALL_BASE_URL = "https://static.guance.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.com"
Set-ExecutionPolicy Bypass -Scope Process -Force
Import-Module BitsTransfer
Start-BitsTransfer -Source "$env:OWL_INSTALL_BASE_URL/install.ps1" -Destination .\owl-install.ps1
powershell .\owl-install.ps1 -Yes
システムで BitsTransfer が提供されていない場合は、以下のコマンドでスクリプトをダウンロードします:
インストール完了後、owl login --dpop を実行し、Studio の一時認証コードを入力します。インストーラーの起動時に OWL_TEMP_CODE を指定してログインを完了することもできます。API Key モードが必要な場合は、OWL_TOKEN、--token、または -Token を明示的に指定します。他のアカウントを追加する場合は Profile を使用してください。
指定バージョンのインストール¶
指定したバージョンをインストールする場合は、インストールコマンドでバージョン番号を指定できます。
Linux / macOS¶
OWL_INSTALL_BASE_URL="https://static.guance.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://static.guance.com/owl/install.sh)" -- --version "1.3.0" --yes
Windows¶
$env:OWL_INSTALL_BASE_URL = "https://static.guance.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.com"
$env:OWL_TOKEN = "your-token"
Set-ExecutionPolicy Bypass -Scope Process -Force
Import-Module BitsTransfer
Start-BitsTransfer -Source "$env:OWL_INSTALL_BASE_URL/install.ps1" -Destination .\owl-install.ps1
powershell .\owl-install.ps1 -Version "1.3.0" -Yes
オフラインインストール¶
オンラインインストール先にアクセスできない環境では、オフラインインストールを使用できます。
オフラインインストールディレクトリには、以下のファイルが含まれている必要があります:
install.shまたはinstall.ps1versionSHA256SUMS- 現在のシステムに対応するインストールパッケージ
オフラインインストールパッケージのファイル名は以下のとおりです:
| オペレーティングシステム | サポートアーキテクチャ | ファイル名 |
|---|---|---|
| Windows | amd64 |
owl-cli-windows-amd64-<version>.zip |
| Linux | amd64 |
owl-cli-linux-amd64-<version>.tar.gz |
| Linux | arm64 |
owl-cli-linux-arm64-<version>.tar.gz |
| macOS | amd64 |
owl-cli-darwin-amd64-<version>.tar.gz |
| macOS | arm64 |
owl-cli-darwin-arm64-<version>.tar.gz |
Linux / macOS¶
chmod +x ./install.sh
./install.sh \
--local-package \
--registry-endpoint "https://owl-api.guance.com" \
--yes
Windows¶
オフラインインストールはローカルファイルのみをインストールします。サイトの HTTPS Endpoint にアクセスできるようになったら、owl login --dpop を実行してログインを完了してください。
インストール後のデフォルトディレクトリ¶
実行ファイル¶
| オペレーティングシステム | デフォルトパス |
|---|---|
| Windows | %LOCALAPPDATA%\Programs\owl\owl.exe |
| Linux / macOS | 優先的に $HOME/.local/bin/owl にインストールされ、書き込み不可の場合は /usr/local/bin/owl にフォールバックします |
設定ディレクトリ¶
| オペレーティングシステム | デフォルトパス |
|---|---|
| Windows | %USERPROFILE%\.owl |
| Linux / macOS | $HOME/.owl |
設定ディレクトリをカスタマイズする場合は、環境変数 OWL_DIR を設定できます。OWL_DIR が空でない値に設定されている場合、OWL CLI はそのディレクトリを設定ディレクトリとして使用し、上表のデフォルトパスを上書きします。設定されていない場合は、上表のデフォルトパス($HOME/.owl / %USERPROFILE%\.owl)にフォールバックします。
設定ディレクトリは初期化後に以下の内容を含みます:
| パス | 説明 |
|---|---|
config.yaml |
クライアント設定ファイル |
cache/ |
同期後のカテゴリおよびツールキャッシュ |
data/ |
データ型ツールの結果ファイル |
logs/ |
ログディレクトリ |
インストール完了後の確認¶
インストール完了後、ターミナルを開き直してから以下のコマンドを実行します:
コマンドがヘルプ情報と現在の設定を正常に出力できれば、ローカルの実行ファイルと設定ファイルは準備完了です。
現在のターミナルと OWL CLI Endpoint の疎通をさらに確認する場合は、続けて以下を実行します:
owl sync が成功すれば、ツールカタログを取得済みであることを示します。owl config show でログイン状態を確認し、現在のアカウントに権限がある読み取り専用ツールを呼び出してアクセス可能であることを確認してください。
owl sync が認証、権限、またはネットワークのエラーを返す場合は、トラブルシューティングを参照してください。
アップグレード¶
更新チャネルが設定済みの場合は、以下のコマンドでアップグレードします:
owl update はローカルの update.base_url で指定されたチャネルを使用します。通常バージョンはアップグレードのみでダウングレードは行わず、同一バージョンの場合はバイナリを保持します。チャネルのインストールスクリプト更新後は、過去の testing-<SHA> ビルドもそのチャネルの正式バージョンへ移行でき、既存の設定を保持したままダウンロードパッケージの SHA256 を検証します。移行前に、正式バージョンに必要なテスト機能が含まれていることを確認してください。
再インストールする場合はオンラインインストールコマンドを実行してください。指定バージョンをインストールする場合は、指定バージョンのインストールを参照してください。
v1.4.0 にアップグレードした後は、owl sync を実行してツールカタログを全件更新してください。owl.member.list は owl.workspace.member.list に移行され、旧名は呼び出しエイリアスとして保持されます。詳細はクロスワークスペースクエリとメンバーツールの移行を参照してください。
アップグレード前に以下の事項を確認することをお勧めします:
- 現在のターミナルが対象ワークスペースに対応する
OWL_REGISTRY_ENDPOINTを使用していること owl config showにDPoP: configuredが表示されるか。API Key でインストールした場合は、使用している Key が有効かどうか- ローカルのスクリプトや自動化タスクが旧バージョンの動作に依存していないか
アンインストール¶
OWL CLI をアンインストールするには、OWL の実行ファイルとローカルの設定ディレクトリを削除します。
設定ディレクトリを削除すると、ローカルの Token、キャッシュ、データファイル、ログが消去されます。削除前に、これらの内容が不要であることを確認してください。
Agent 用の付属 Skill のインストール(任意)¶
AI Agent で OWL を通じて Guance センターの診断機能を利用する場合は、OWL CLI のインストールを完了して一度 owl sync を実行した後に、Agent 用の owl-diagnostics skill をインストールすることをお勧めします。
owl-diagnostics skill は、ローカルにインストールされ実行可能な owl コマンドに依存します。インストール後、Agent は OWL で同期済みのツールカタログを組み合わせて、ログ、メトリクス、イベント、トレースなどの診断分析をより安定して実行できます。
対応する skill のアドレス:
現時点で OWL CLI を手動で使用するだけであれば、この手順はスキップできます。
Codex、Claude Code、Cursor、Trae、GitHub Copilot(VS Code)、Windsurf など、ターミナルでコマンドを実行できる Agent は、いずれも同じインストール手順を使用できます。CLI は Agent が実際にコマンドを実行する環境にインストールしてください。
現在の Agent の会話で以下のプロンプトを送信すると、対応する Skill をインストールさせることができます:
インストール完了後、現在の Agent の指示に従って Skill を読み込み、必要に応じてセッションを更新または新規作成してから、初回呼び出しの検証を完了してください。自動インストールで付属 Skill のインストールを完了しているユーザーは、本節の手順を繰り返す必要はありません。
ターミナルで owl が見つからないと表示された場合は、以下のように対処します:
- Windows:現在の PowerShell を閉じて、再度開いてから実行します
- Linux / macOS:現在のターミナルウィンドウを閉じて、再度開いてから実行します