自动安装 Owl¶
本文档面向需要在 AI 工具中使用 Owl 的用户，介绍如何通过自动安装方式完成 Owl CLI、认证配置、工具目录同步和 Owl Skill 安装。
Owl Skill 是面向 AI 工具的配套能力，用于帮助 AI 工具识别本机 owl 命令、理解 Owl 工具目录，并更稳定地调用日志、指标、事件、链路等诊断能力。自动安装会在安装 Owl CLI 后一并安装 Owl Skill。
如果只需要在终端中手动使用 Owl CLI，可以跳过 Owl Skill。
如果当前环境不能执行终端命令、不能访问外网或企业网络中的 Owl CLI Endpoint，或者需要离线安装，请使用手动安装 Owl。
适用场景¶
适用于以下场景：
- AI 工具具备终端命令执行权限
- 当前环境可以访问 Owl CLI Endpoint 和安装资源地址
- 当前环境允许写入本机用户目录下的 Owl 配置
- 用户可以提供工作空间对应的 Owl CLI Endpoint 和临时授权码
不适用于以下场景：
- 当前工具是纯聊天工具，无法执行终端命令
- 当前环境为受限网络或离线环境
- 当前环境不允许 AI 工具写入本机配置
- 安装过程中的每一步命令都需要人工审查后再执行
安装指令¶
将以下内容复制到 AI 工具的对话窗口中执行。复制前，请完成以下替换：
- 将
<OWL_REGISTRY_ENDPOINT>替换为工作空间所属站点对应的 Owl CLI Endpoint - 将
<YOUR_TEMP_CODE>替换为观测云控制台生成的临时授权码
阅读 https://static.guance.com/owl/skill.md ，按照文档在当前环境中安装并配置 Owl CLI 和 Owl Skill。
安装参数如下：
OWL_REGISTRY_ENDPOINT="<OWL_REGISTRY_ENDPOINT>"
OWL_TEMP_CODE="<YOUR_TEMP_CODE>"
参数说明¶
| 参数 | 说明 | 填写方式 |
|---|---|---|
OWL_REGISTRY_ENDPOINT |
观测云中心 Owl CLI Endpoint | 根据工作空间所在站点选择对应 Endpoint |
OWL_TEMP_CODE |
短期有效的临时授权码 | 在观测云控制台的个人 API 密钥页面生成 |
OWL_REGISTRY_ENDPOINT 只填写 Endpoint 根地址，不要手动拼接 /api/v1 或其他路径。
临时授权码获取路径：
- 点击控制台右上角的个人头像
- 选择“个人 API 密钥”
- 点击“生成临时授权码”
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 部署 | 非洲区1（南非） | https://za1-owl-api.guance.com |
| SaaS 部署 | 印尼区1（雅加达） | https://id1-owl-api.guance.com |
| SaaS 部署 | 中东区1（阿联酋） | https://me1-owl-api.guance.com |
| SaaS 部署 | 免费专区（北京） | https://cn3-owl-api.guance.com |
| 私有部署版 | 私有部署版 | 以实际部署提供的 Owl CLI Endpoint 为准 |
执行内容¶
AI 工具将根据安装说明自动执行以下操作：
- 下载并安装 Owl CLI
- 写入工作空间对应的 Owl CLI Endpoint
- 使用
OWL_TEMP_CODE换取 API Key - 将认证信息写入本机 Owl 配置
- 执行
owl sync同步工具目录 - 安装 Owl Skill
- 验证
owl命令可用性
安装完成后，AI 工具即可结合本机 owl 命令和 Owl Skill 使用 观测云 的诊断能力。
安全说明¶
自动安装不需要向 AI 工具提供 API Key 明文。AI 工具会使用 OWL_TEMP_CODE 换取 API Key 并将认证信息写入本机 Owl 配置。安装过程中不应在回复、日志或命令输出中展示 API Key 明文。
OWL_TEMP_CODE 是短期有效的临时授权凭证，仅用于安装阶段换取 API Key。该凭证不能直接调用接口，但在有效期内仍应按敏感信息处理。请勿将其公开粘贴、写入长期日志、提交到代码仓库或共享文档。
自动安装完成后，Owl 可访问的资源和可执行的操作，仍由换取到的 API Key 决定，并遵循 观测云 工作空间中的权限配置。
常见处理¶
AI 工具无法执行命令¶
如果 AI 工具提示无法执行终端命令，请在具备终端执行权限的 AI 工具中重新执行安装指令，或改用手动安装 Owl。
临时授权码无效、过期或未授权¶
如果提示授权码无效、过期或未授权，请在 观测云 控制台重新生成 OWL_TEMP_CODE 后再次执行安装指令。
Endpoint 无法访问¶
如果提示 Endpoint 无法访问，请确认以下内容：
- 当前环境可以访问外网或企业网络中的 Owl CLI Endpoint
- 工作空间所属节点与
OWL_REGISTRY_ENDPOINT匹配 OWL_REGISTRY_ENDPOINT未拼接/api/v1或其他路径
安装完成后无法识别 owl 命令¶
如果安装完成后无法识别 owl 命令，请重新打开终端，或让 AI 工具刷新当前终端环境变量后再次验证。
可执行以下命令检查：
工具目录同步失败¶
如果 owl sync 返回认证、权限或网络错误，请确认：
OWL_TEMP_CODE是否已成功换取 API Key- 当前 API Key 是否具备同步工具目录所需权限
- 当前环境是否可以访问 Owl CLI Endpoint
更多问题请参考故障排查。