OWL の手動インストール¶

本ドキュメントは OWL ユーザーを対象に、OWL CLI のインストール前準備、オンラインインストール、指定バージョンインストール、オフラインインストール、およびインストール完了後の確認方法を説明します。

owl は OWL CLI のコマンド名です。インストール完了後、ユーザーはローカルで owl を使用してツールディレクトリの同期、ツールの説明の確認、およびプラットフォーム機能の実行が可能です。

現在利用中の AI ツールがターミナルコマンドの実行をサポートしており、OWL CLI、認証構成、ツールディレクトリの同期、および OWL Skill のインストールを自動で完了させたい場合は、自動インストール を参照してください。

インストール前準備¶

インストール前に以下の情報を準備してください。

OWL_REGISTRY_ENDPOINT には、ワークスペースが所属するサイトに対応する Guance センターの OWL CLI Endpoint を入力してください。/api/v1 を手動で拼接しないでください。

• OWL_INSTALL_BASE_URL はインストールスクリプトとインストールパッケージのダウンロードに使用されます。
• OWL_REGISTRY_ENDPOINT は CLI が Guance センターの OWL サービスにアクセスするために使用されます。
• OWL_TOKEN はサービスアクセストークンであり、呼び出し元の識別に使用され、DF-API-KEY に対応します。
• OWL_API_KEY は OWL_TOKEN のエイリアス環境変数であり、両方が設定されている場合は OWL_API_KEY が優先されます。

権限要件¶

OWL_TOKEN は Guance API Key を使用します。OWL CLI がアクセス可能なリソースと実行可能な操作は、この API Key の Open API 権限に依存します。

インストールと初回検証には、少なくとも以下の条件を満たす必要があります。

• 現在のワークスペースにアクセス可能であること
• OWL CLI Endpoint にアクセス可能であること
• ツールディレクトリの同期に必要な基本アクセス権限を有していること
• 特定のツールを実行する場合、API Key は対応する Open API の読み取りまたは書き込み権限を必要とします。

Endpoint 一覧¶

OWL CLI サービスはサイトごとに独立した Endpoint を提供します。ワークスペースが所属するサイトに応じて、対応するサービスアドレスを選択してください。

サポートプラットフォーム¶

現在のインストールパッケージは以下のプラットフォームをサポートしています。

インストールパッケージのファイル名は owl-cli-* を使用し、インストール後のコマンドは統一して owl となります。

オンラインインストール¶

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)" -- --yes

実行前に、システムに以下のコマンドがインストールされていることを確認してください。

• bash
• curl
• tar

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 -Yes

システムで BitsTransfer が利用できない場合は、以下のコマンドでスクリプトをダウンロードしてください。

Invoke-WebRequest -Uri "$env:OWL_INSTALL_BASE_URL/install.ps1" -OutFile .\owl-install.ps1

指定バージョンインストール¶

特定のバージョンをインストールする必要がある場合は、インストールコマンドでバージョン番号を指定できます。

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.0.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.0.0" -Yes

オフラインインストール¶

オンラインインストールアドレスにアクセスできない環境では、オフラインインストール方式を使用できます。

オフラインインストールディレクトリには、以下のファイルが含まれている必要があります。

• install.sh または install.ps1
• version
• SHA256SUMS
• 現在のシステムに対応するインストールパッケージ

オフラインインストールパッケージのファイル名は以下の通りです。

Linux / macOS¶

chmod +x ./install.sh
./install.sh \
  --local-package \
  --registry-endpoint "https://owl-api.guance.com" \
  --token "your-token" \
  --yes

Windows¶

powershell .\install.ps1 `
  -LocalPackage `
  -RegistryEndpoint "https://owl-api.guance.com" `
  -Token "your-token" `
  -Yes

インストール後のデフォルトディレクトリ¶

実行可能ファイル¶

設定ディレクトリ¶

設定ディレクトリをカスタマイズするには、環境変数 OWL_DIR を設定します。OWL_DIR が空でない値に設定されている場合、OWL CLI はそのディレクトリを設定ディレクトリとして使用し、上表のデフォルトパスを上書きします。設定されていない場合は、上表のデフォルトパス（$HOME/.owl / %USERPROFILE%\.owl）にフォールバックします。

設定ディレクトリの初期化後、以下の内容が含まれます。

インストール完了後の確認¶

インストール完了後、ターミナルを開き直してから以下のコマンドを実行してください。

owl --help
owl config show

コマンドが正常にヘルプ情報と現在の設定を出力する場合、ローカルの実行可能ファイルと設定ファイルが準備完了です。

さらに、現在のターミナルと OWL CLI Endpoint の接続性を確認するには、以下のコマンドを実行します。

owl sync

owl sync が正常に完了する場合、現在のターミナルが OWL CLI Endpoint にアクセス可能であり、OWL_TOKEN がツールディレクトリの同期に使用可能であることを示します。

owl sync が認証、権限、またはネットワークエラーを返す場合は、トラブルシューティング を参照してください。

アップグレード¶

新しいバージョンにアップグレードするには、オンラインインストールコマンドを再実行してください。特定のバージョンにアップグレードする場合は、指定バージョンインストール を参照してください。

アップグレード前に、以下の点を確認することを推奨します。

• 現在のターミナルが対象のワークスペースに対応する OWL_REGISTRY_ENDPOINT を使用していること
• 現在の OWL_TOKEN が有効であること
• ローカルスクリプトまたは自動化タスクが旧バージョンの動作に依存していないこと

アンインストール¶

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 のアドレスは以下の通りです。

https://github.com/GuanceCloud/ai-skills/tree/main/owl-diagnostics

現在、手動で OWL CLI を使用するだけの場合は、この手順をスキップできます。

Codex を例に

Codex では、以下のプロンプトで owl-diagnostics skill をインストールできます。

この skill をインストールしてください：https://github.com/GuanceCloud/ai-skills/tree/main/owl-diagnostics

インストール完了後、Codex を再起動して、新しくインストールした skill を有効にします。その後、Codex で Guance の診断に関連するタスクを実行する際に、Codex はローカルの owl コマンドとこの skill を組み合わせて使用できるようになります。

ターミナルで owl が見つからないと表示された場合は、以下の方法で対処してください。

• Windows：現在の PowerShell を閉じて、再度開き直してから実行してください。
• Linux / macOS：現在のターミナルウィンドウを閉じて、再度開き直してから実行してください。