Owl 使用指南¶

本文档面向已经完成安装的 Owl 用户，说明首次配置、同步流程、常用命令和日常使用方式。

owl 是面向用户和 Agent 的统一工具入口。用户通过 Owl 从观测云中心同步工具目录，在本地查看工具说明，并以统一命令执行指标、日志、事件、监控、Dashboard、Incident 等平台能力。

使用前准备¶

开始使用前，请确认以下条件已经满足：

1. 本机已经安装 owl
2. 已获取工作空间所属站点的观测云中心 Owl CLI Endpoint
3. 已获取访问令牌 OWL_TOKEN
4. 当前终端可以访问 Owl CLI Endpoint

使用 Owl 时，客户侧只需要配置以下两个核心信息：

1. OWL_REGISTRY_ENDPOINT
2. OWL_TOKEN

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

正确示例：

• https://owl-api.guance.com

错误示例：

• https://owl-api.guance.com/api/v1

首次使用的标准流程¶

首次使用请按以下顺序执行。

第一步：配置 Owl CLI Endpoint 和令牌¶

方式一：环境变量¶

PowerShell：

$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.com"
$env:OWL_TOKEN = "your-token"

bash / zsh：

export OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com"
export OWL_TOKEN="your-token"

方式二：交互式写入配置文件¶

owl init
owl login

执行说明：

• owl init 用于写入 Owl CLI Endpoint
• owl login 用于写入访问令牌

环境变量优先级高于配置文件。当前终端中如果已经设置环境变量，运行时将直接使用环境变量中的值。

第二步：同步工具目录¶

owl sync

这一步会把观测云中心当前可用的分类和工具同步到本地缓存。首次使用必须先执行 owl sync，随后才可以查看工具和执行工具。

如果只同步某一个分类，执行：

owl sync -c metric

第三步：查看分类和工具¶

owl category list
owl list

查看指定分类下的工具：

owl list -c metric

查看某个工具的详细说明和参数定义：

owl show owl.metric.list

第四步：执行工具¶

owl exec owl.metric.list --mode source

这条命令会执行 metric 分类中的 owl.metric.list 工具，并返回当前可用的指标来源信息。

上手示例¶

以下示例展示从配置到执行的完整流程：

export OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com"
export OWL_TOKEN="your-token"

owl sync
owl category list
owl list -c metric
owl show owl.metric.list
owl exec owl.metric.list --mode source

如果需要查看 json 输出，执行：

owl list -f json
owl show owl.metric.list -f json
owl exec owl.metric.list --mode source --format json

常用命令¶

配置与认证¶

owl init
owl login
owl config show
owl config set registry.endpoint "https://owl-api.guance.com"

说明：

• owl init：写入 Owl CLI Endpoint
• owl login：写入访问令牌
• owl config show：查看当前配置
• owl config set：修改指定配置项

分类与工具目录¶

owl category list
owl category show metric
owl list
owl list -c metric
owl show owl.metric.list

说明：

• owl category list：查看所有分类
• owl category show <分类ID>：查看分类详情和分类下工具
• owl list：查看全部工具
• owl list -c <分类ID>：查看某个分类下的工具
• owl show <工具名>：查看工具详情和参数定义

工具执行¶

owl exec 支持四种传参方式。

方式一：--key value¶

owl exec owl.metric.list --mode source

方式二：key=value¶

owl exec owl.metric.list mode=source

方式三：-p 传入 JSON¶

owl exec owl.metric.list -p '{"mode":"source"}'

方式四：从标准输入读取 JSON¶

echo '{"mode":"source"}' | owl exec owl.metric.list --stdin

执行规则如下：

• 工具名必须与 owl list 中显示的名称一致
• 必填参数必须全部提供
• 参数名称必须与工具定义一致
• 参数类型必须与工具定义一致

例如，事件查询工具要求时间范围参数：

owl show owl.event.list
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

本地目录说明¶

Owl 的默认目录如下。

可执行文件¶

• Windows：%LOCALAPPDATA%\Programs\owl\owl.exe
• Linux / macOS：$HOME/.local/bin/owl，不可写时回退到 /usr/local/bin/owl

配置目录¶

• Windows：%USERPROFILE%\.owl
• Linux / macOS：$HOME/.owl

配置目录中的主要内容¶

• config.yaml：客户端配置
• cache/：同步后的分类与工具缓存
• data/：数据型工具的结果文件
• logs/：日志目录

配置文件与配置优先级¶

默认配置文件路径：

• Windows：%USERPROFILE%\.owl\config.yaml
• Linux / macOS：$HOME/.owl/config.yaml

配置文件示例：

registry:
  endpoint: https://owl-api.guance.com
  sync_interval: 3600

auth:
  token: ""

cache:
  directory: ~/.owl/cache
  ttl: 86400

data:
  directory: ~/.owl/data
  max_age_days: 30

sync:
  parallel: true
  concurrency: 5
  incremental: true

execution:
  default_timeout: 30000
  max_output_size: 10485760

logging:
  level: info
  file: ~/.owl/logs/owl.log

配置优先级：

1. 环境变量
2. config.yaml

因此，当环境变量和配置文件同时存在时，运行时使用环境变量中的值。

缓存与同步¶

owl sync 会将观测云中心中的分类和工具元数据同步到本地缓存目录。
owl category list、owl list、owl show 读取的是本地缓存，因此在以下场景中需要重新执行 owl sync：

• 首次安装完成后
• 平台发布了新的工具
• 平台更新了已有工具的参数或说明
• 需要刷新本地缓存内容

查看缓存状态：

owl cache status

清理缓存：

owl cache clear
owl cache clear -c metric

8. 数据结果文件¶

当工具定义的输出类型为 data 时，Owl 会自动把结果文件保存到本地 data/ 目录，并记录文件索引与结构信息。

查看数据文件列表：

owl data list

查看某个数据文件详情：

owl data show <file-id>

删除数据文件：

owl data rm <file-id>

清理历史文件：

owl data clean --days 30

查看数据文件统计：

owl data stats

面向 Agent 的 Schema 输出¶

如果需要把 Owl 接入大模型 Agent，可直接导出函数调用 Schema：

owl schema

只导出单个分类：

owl schema -c metric

owl schema 的输出包含：

• owl_exec：统一执行任意 Owl 工具
• owl_list_categories：列出分类
• owl_list_tools：列出工具
• 当前已同步的工具定义

在接入 Agent 之前，先执行一次 owl sync，保证本地 Schema 与平台当前工具目录一致。

10. 常见问题处理¶

提示 tool not found¶

原因：本地缓存中没有该工具。
处理方式：

owl sync
owl list

确认工具名称后重新执行。

提示 category not found¶

原因：分类名称不存在或尚未同步。
处理方式：

owl sync
owl category list

提示 missing required parameter¶

原因：缺少必填参数。
处理方式：

owl show <工具名>

根据工具定义补齐必填参数后重新执行。

提示 unknown parameter¶

原因：参数名与工具定义不一致。
处理方式：使用 owl show <工具名> 核对参数名称。

提示认证失败或无法访问 Owl CLI Endpoint¶

检查以下内容：

• OWL_REGISTRY_ENDPOINT 是否为当前站点的 Owl CLI Endpoint
• OWL_TOKEN 是否有效
• 当前终端是否能访问 Owl CLI Endpoint

结果为空或与预期不符¶

按以下顺序检查：

1. 使用 owl show <工具名> 核对参数定义
2. 使用 owl list -c <分类ID> 确认执行的是正确工具
3. 使用 owl sync 刷新本地缓存

帮助命令¶

查看全局帮助：

owl --help

查看某个命令的帮助：

owl help exec
owl help sync
owl help data