故障排查¶
本文档用于处理 Owl CLI 和 Owl MCP Server 的常见接入问题。
CLI：提示找不到 owl¶
现象：
处理方式：
- Windows：关闭当前 PowerShell，重新打开后再执行
- Linux / macOS：关闭当前终端窗口，重新打开后再执行
- 确认可执行文件是否存在于默认安装目录
默认可执行文件路径：
- Windows：
%LOCALAPPDATA%\Programs\owl\owl.exe - Linux / macOS：
$HOME/.local/bin/owl，不可写时回退到/usr/local/bin/owl
自动安装：AI 工具无法执行命令¶
原因：当前 AI 工具不具备终端命令执行权限，或当前环境禁止写入本机配置。
处理方式：
- 换用支持终端命令执行的 AI 工具
- 或改用 手动安装
自动安装：临时授权凭证无效、过期或未授权¶
原因：OWL_TEMP_CODE 已过期、已使用、复制错误，或当前账号没有生成授权码的权限。
处理方式：
- 在观测云控制台重新生成临时授权凭证
- 重新执行 自动安装 中的安装指令
- 不要复用已经使用过的
OWL_TEMP_CODE
自动安装：Endpoint 不匹配¶
原因：OWL_REGISTRY_ENDPOINT 与工作空间所在站点不一致，或错误拼接了 /api/v1。
处理方式：
- 根据工作空间所在节点重新选择 Owl CLI Endpoint
OWL_REGISTRY_ENDPOINT只填写 Endpoint 根地址- 私有部署环境请使用实际部署提供的 Owl CLI Endpoint
CLI：认证失败或无法访问 Endpoint¶
检查以下内容：
OWL_REGISTRY_ENDPOINT是否为当前站点的 Owl CLI Endpoint- Endpoint 是否错误拼接了
/api/v1 OWL_TOKEN是否有效- API Key 是否具备对应 Open API 权限
- 当前终端是否可以访问 Owl CLI Endpoint
CLI：提示 tool not found¶
原因：本地缓存中没有该工具，或工具名称输入错误。
处理方式：
确认工具名称后重新执行。
CLI：提示 category not found¶
原因：分类名称不存在或尚未同步。
处理方式：
CLI：提示 missing required parameter¶
原因：缺少必填参数。
处理方式：
根据工具定义补齐必填参数后重新执行。
CLI：提示 unknown parameter¶
原因：参数名与工具定义不一致。
处理方式：
核对参数名称后重新执行。
CLI：结果为空或与预期不符¶
按以下顺序检查：
- 使用
owl show <工具名>核对参数定义 - 使用
owl list -c <分类ID>确认执行的是正确工具 - 使用
owl sync刷新本地缓存 - 检查查询时间范围是否正确，时间参数应为 13 位毫秒时间戳
- 检查 API Key 是否具备对应资源的 Open API 权限
MCP：客户端连接失败¶
检查以下内容：
- MCP 类型是否配置为
streamableHttp - URL 是否为当前站点的 Owl MCP Endpoint
- URL 是否以
/mcp结尾 - 请求头是否包含
Authorization: Bearer <API Key> - 客户端所在网络是否可以访问 Owl MCP Endpoint
MCP：认证失败¶
检查以下内容：
- API Key 是否正确复制
- Authorization Header 格式是否正确
- API Key 是否已被禁用、删除或轮换
- API Key 所属工作空间是否为当前要访问的工作空间
请求头格式：
MCP：工具列表为空¶
可能原因：
- MCP 客户端未成功连接服务
- API Key 无效或权限不足
- 客户端未刷新 MCP 工具列表
- Endpoint 选择错误
处理方式：
- 在客户端中重新测试 MCP 连接
- 确认 Endpoint 与工作空间站点一致
- 确认 Authorization Header 正确
- 重新加载或重启 MCP 客户端
MCP：工具调用返回权限错误¶
原因：API Key 没有对应 Open API 权限。
处理方式：
- 检查 API Key 权限范围
- 为只读场景授予对应查询权限
- 为写入场景授予对应写权限
- 不建议为 Agent 直接配置过宽的 API Key 权限
MCP：工具调用返回空结果¶
按以下顺序检查：
- 查询时间范围是否正确
- 所选数据域、source、field、index 是否存在
- 是否需要先调用发现类工具，例如
owl.metric.list、owl.log_index.list - API Key 是否有该数据范围的读取权限
- 当前工作空间中是否实际存在对应数据
MCP：写操作被拦截或未生效¶
可能原因：
- API Key 没有写权限
- 客户端配置了人工确认但未确认
- 参数结构不符合工具要求
- 工作空间侧存在审批或审计限制
处理方式：
- 核对工具参数
- 核对 API Key 权限
- 检查客户端是否等待人工确认
- 检查工作空间侧审批、审计或权限配置