手动安装 Owl¶

本文档面向 Owl 用户，介绍 Owl CLI 的安装前准备、在线安装、指定版本安装、离线安装，以及安装完成后的检查方式。

owl 是 Owl CLI 的命令名称。安装完成后，用户可以在本地通过 owl 同步工具目录、查看工具说明，并执行平台能力。

如果当前使用的 AI 工具支持执行终端命令，并且希望自动完成 Owl CLI、认证配置、工具目录同步和 Owl Skill 安装，可使用自动安装。

安装前准备¶

安装前请准备以下信息：

OWL_REGISTRY_ENDPOINT 必须填写工作空间所属站点对应的 观测云 中心 Owl CLI Endpoint，不要手动拼接 /api/v1。

• OWL_INSTALL_BASE_URL 用于下载安装脚本和安装包
• OWL_REGISTRY_ENDPOINT 用于 CLI 访问观测云中心的 Owl 服务
• OWL_TOKEN 服务访问令牌，用于标识调用方身份，对应 DF-API-KEY

权限要求¶

OWL_TOKEN 使用观测云 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 --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 使用观测云中心的诊断能力，建议在完成 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 中执行与观测云诊断相关的任务时，Codex 即可结合本机 owl 命令和该 skill 配合使用。

当终端提示找不到 owl 时，按以下方式处理：

• Windows：关闭当前 PowerShell，重新打开后再执行
• Linux / macOS：关闭当前终端窗口，重新打开后再执行