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 はサービスアクセストークンです。呼び出し元の ID を識別します。対応する 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.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.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 update を実行します。update.base_url のチャネルを維持し、通常のバージョンはダウングレードせず、同一バージョンは既存バイナリを保持します。チャネルのインストーラースクリプト更新後は、旧 testing-<SHA> ビルドも設定と SHA256 検証を維持したままそのチャネルのリリース版へ移行できます。必要なテスト機能がリリースに含まれることを確認してください。

v1.4.0 への更新後は 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：現在のターミナルウィンドウを閉じて、再度開いてから実行します。