Onyx CLI Agent 接入指南：让 AI 智能体检索企业知识库的完整配置与命令手册

onyx-cli 是 Onyx 企业知识平台为 AI Agent 提供的官方命令行接口，它让编码智能体（如 Claude Code、Codex 等）能够直接检索公司文档、已连接数据源（Confluence、Google Drive、Slack 等）中的内部知识，并获取带引用的结构化检索结果或 LLM 综合回答。本文将基于仓库中的官方 Agent 工具说明文档 cli/internal/embedded/SKILL.md，结合 cli/ 目录下的 Go 源码实现，完整讲解安装配置、四个核心命令的用法与全部参数、输出约定、退出码语义，以及底层 API 调用与配置加载机制，帮助你为 Agent 快速接通企业知识库。

onyx-cli 是什么：Agent 访问企业知识的桥梁

onyx-cli 定位非常明确：它是 Agent 访问 Onyx 企业知识平台的接口，连接公司文档、应用与人员信息。当用户提出的问题需要企业内部知识——如公司政策、技术文档、业务流程、已连接数据源中的资料——时，Agent 应当调用它来获取事实依据，而不是凭空猜测。

从源码看，这一接口以 HTTP 客户端的形式与 Onyx 后端通信（见 cli/internal/api/client.go），核心能力分为两类：

• onyx-cli search：执行企业知识检索，返回排序后的带引用文档，适合"找资料、收集上下文"的场景；
• onyx-cli ask：向 Onyx Agent 发送一次性提问，流式输出 LLM 综合答案，适合"直接要结论"的场景。

同时它提供 agents（列出可用 Agent）与 validate-config（校验配置连通性）两个辅助命令，并且整套命令被设计为无状态、可脚本化、输出确定性，天然适配 AI Agent 的非交互式调用。

前置准备：安装、配置与校验

1. 检查是否已安装

which onyx-cli

2. 安装（如未安装）

pip install onyx-cli

仓库 cli/README.md 补充说明：也支持 uv pip install onyx-cli，并且 Linux、macOS、Windows（amd64/arm64）均有随 CLI 版本发布附带的独立二进制。

3. 检查是否已配置

如果人工用户已经运行过 onyx-cli chat（首次运行会引导完成配置），则 CLI 开箱即用，无需额外配置。配置自动从以下路径读取：

• ~/.config/onyx-cli/config.json
• 若设置了 $XDG_CONFIG_HOME，则为 $XDG_CONFIG_HOME/onyx-cli/config.json

从源码 cli/internal/config/config.go 可以看到配置文件结构：

{
  "server_url": "https://your-onyx-server.com",
  "api_key": "your-pat",
  "default_persona_id": 0,
  "features": {
    "stream_markdown": true
  }
}

环境变量会覆盖配置文件，且在没有配置文件时可作为替代方案：

export ONYX_SERVER_URL="https://your-onyx-server.com"  # 默认: https://cloud.onyx.app
export ONYX_PAT="your-pat"

全部环境变量及其语义如下表：

变量	是否必需	说明
ONYX_SERVER_URL	否	服务器源地址，或已含 API 前缀的完整 API 基址（默认：https://cloud.onyx.app）
ONYX_API_PREFIX	否	API 路径前缀（默认：/api）；设为空字符串表示直连后端
ONYX_PAT	是（无配置文件时）	用于认证的个人访问令牌（PAT）
ONYX_PERSONA_ID	否	默认 Agent/Persona ID
ONYX_STREAM_MARKDOWN	否	是否启用流式 Markdown 渲染（true/false）

源码细节：config.Load() 会先读磁盘配置，再用环境变量逐项覆盖（cli/internal/config/config.go）；IsConfigured() 的判定标准是 api_key 非空（同一文件 L55-L58）。此外 ONYX_API_PREFIX 为空时，APIURL() 会返回不含 /api 后缀的基址，用于绕过反向代理直连后端。

若配置文件与环境变量均未设置，应告知用户 onyx-cli 需要配置，并请其选择其一：

• 运行 onyx-cli chat 交互式完成首次配置；或
• 设置 ONYX_SERVER_URL 与 ONYX_PAT 环境变量（ONYX_PAT 存放 PAT）。

4. 校验配置

onyx-cli validate-config

成功时退出码为 0；失败时返回非零退出码并附描述性错误（详见下文退出码表）。从 cli/cmd/validate.go 的实现看，它会依次执行：

1. 检查配置是否存在、PAT 是否设置（缺失则报 NotConfigured）；
2. 打印配置来源（配置文件路径或环境变量）与服务器地址；
3. 调用 TestConnection 验证服务器可达性（先请求根路径检查基础连通性，再请求 /me 端点验证 PAT 有效性，见 cli/internal/api/client.go）；
4. 获取后端版本号，若低于最低要求版本则输出升级警告。

TestConnection 还能识别若干特殊场景：AWS 负载均衡器/WAF 拦截（403）、反向代理返回 HTML（非 Onyx 后端）、PAT 无效（401/403）等，并给出针对性提示。

命令详解

检索文档：onyx-cli search

onyx-cli search "What is our deployment process?"

返回 Onyx 知识库中已排序、带引用的文档，输出为 JSON。默认输出为精简结构：

{"results": [{"title": "...", "url": "...", "source_type": "...", "content": "...", "updated_at": "..."}]}

结果只包含 LLM 判定为相关的文档，按相关度排序；content 为每个结果的完整分块文本。需要完整 API 响应时使用 --raw——单查询时直接裸输出（每个结果额外带 citation_id），多查询时输出为 {"searches": [{"query": "...", "response": ...}, ...]}。

关于性能与批处理（SKILL.md 特别强调，源码 cli/cmd/search.go 也有印证）：

• 每次查询都是一次完整的检索流程，耗时数十秒；
• 单次调用最多传入 3 个查询（超过会被 BadRequest 拒绝），多个查询并发执行——把相互独立的问题合并到一次调用，远快于逐个串行；
• 多查询输出为 {"searches": [{"query": "...", "results": [...]}, ...]}，按参数顺序排列；失败的查询带 error 字段且 results 为 null；
• 部分失败仍会以退出码 0 结束，因此必须逐条检查每个查询的 error 字段；
• 不要把解析脚本直接链在搜索命令之后（例如在 search 后面用 Python heredoc 解析），这可能导致挂起、触发 shell 超时、丢失已完成的搜索结果。正确做法是把搜索输出写入文件，在另一次独立的 shell 调用中解析。

stdout 永远是合法 JSON。当响应超过 --max-output 字节（非 TTY 时默认 50000）时，会按相关度从低到高丢弃结果，并附加一个 truncation 对象：

{
  "truncated": true,
  "total_results": 10,
  "shown_results": 3,
  "total_bytes": 98765,
  "content_truncated": false,
  "full_response_path": "/tmp/onyx-search-xxx.json",
  "hint": "output was reduced to fit the output limit; the complete response is at full_response_path"
}

完整响应（结构与打印输出一致：单查询为 results，多查询为 searches）被保存到 full_response_path 指向的临时文件，被丢弃的结果可从该文件读取。多查询时，各查询的结果数会被统一封顶直到整体输出满足字节限制，因此小的结果集会完整保留（相关算法见 cli/cmd/search.go 的 truncateMultiSearchOutput）。

search 命令示例：

# 批量并发检索多个独立问题
onyx-cli search "Q3 roadmap" "hiring plan" "incident postmortem template"

# 按数据源过滤
onyx-cli search --source slack,google_drive "auth migration status"

# 只看近 30 天结果
onyx-cli search --days 30 "recent production incidents"

# 使用特定 Agent 做限定范围检索
onyx-cli search --agent-id 5 "engineering roadmap"

# 输出完整 API 响应，供程序化使用
onyx-cli search --raw "API documentation" | jq '.results[].title'

# 跳过查询扩展，做精确匹配
onyx-cli search --no-query-expansion "exact error message text"

search 参数总表：

参数	类型	说明
--source	string	按数据源类型过滤（逗号分隔，如 slack,google_drive）
--days	int	只返回最近 N 天的结果（源码限制必须为正整数且不超过 36500，见 cli/cmd/search.go）
--agent-id	int	用于限定范围检索的 Agent ID（继承其过滤条件、文档集）
--raw	bool	输出完整 API 响应（每个结果额外带 citation_id）
--no-query-expansion	bool	跳过 LLM 查询扩展——更快，但仅在查询本身已足够精确时安全（精确名称、标题、带引号的短语）
--max-output	int	打印前最多允许的字节数（0 表示禁用；非 TTY 默认 50000；--raw 时忽略）

源码细节：--days 会在请求体中转换为 time_cutoff（UTC 的 RFC3339 时间戳）；--agent-id 未显式传入时，若配置了默认 ONYX_PERSONA_ID 也会注入请求；--no-query-expansion 对应请求体的 skip_query_expansion 字段（见 cli/cmd/search.go 的 buildSearchRequest）。同时源码提醒：若多个参数都是单单词（如 search foo bar），很可能是用户漏掉了引号，CLI 会在 stderr 打印提示。

提问：onyx-cli ask

onyx-cli ask "What is our company's PTO policy?"

以纯文本流式输出 LLM 生成的答案到 stdout。当需要的是源文档而非综合答案时，应改用 search。

当 stdout 不是 TTY 时，输出被截断为 50000 字节，完整响应保存到临时文件（路径在末尾打印）。用 --max-output 0 可禁用截断。

ask 命令示例：

# 使用特定 Agent
onyx-cli ask --agent-id 5 "Summarize our Q4 roadmap"

# 把上下文通过管道与问题一起传入
cat error.log | onyx-cli ask --prompt "Find the root cause"

# 结构化 NDJSON 输出
onyx-cli ask --json "List all active API integrations"

ask 参数总表：

参数	类型	说明
--agent-id	int	使用的 Agent ID（覆盖默认值）
--json	bool	输出 NDJSON 流事件而非纯文本（绕过截断）
--quiet	bool	缓冲输出，结束时一次性打印（不流式）
--prompt	str	问题文本（配合管道 stdin 上下文使用）
--max-output	int	打印前最多允许的字节数（0 禁用；非 TTY 默认 50000）

源码细节：问题的来源有三种且互斥——位置参数、--prompt、stdin 管道。参数与 --prompt 同时给出会报 BadRequest；stdin 非空时会被当作上下文拼接到问题后（10MB 上限，见 cli/cmd/ask.go 的 resolveQuestion）。--json 与 --quiet 不能同时使用。ask 底层通过 SendMessageStream 建立一次性聊天会话并消费流事件（SearchStartEvent、SearchQueriesEvent、MessageDeltaEvent、ToolStartEvent、StopEvent、ErrorEvent 等），在 TTY 下会把"正在搜索文档/思考中/正在使用某工具"等进度打到 stderr；--json 模式下每个事件被包装为 {"type": ..., "event": ...} 的 NDJSON 行输出（见 cli/cmd/ask.go）。

列出可用 Agent：onyx-cli agents

onyx-cli agents
onyx-cli agents --json

默认输出包含 Agent ID、名称、描述的表格；--json 输出结构化 JSON。将返回的 Agent ID 用于 search --agent-id 或 ask --agent-id。源码 cli/cmd/agents.go 显示：后端从 /persona 端点获取数据，仅列出 is_visible 的 Agent，表格模式下描述超过 60 字符会被截断。

校验配置：onyx-cli validate-config

onyx-cli validate-config

检查配置是否存在、PAT 是否设置、服务器是否可达、凭据是否有效。在 search、ask、agents 之前使用，可确认 CLI 已正确配置（详见上文"校验配置"一节）。

输出约定

• stdout：仅输出结果（答案文本、Agent 列表、状态）；
• stderr：进度指示、警告、错误；
• 非 TTY：无 ANSI 转义码、无交互式提示；
• 截断：stdout 非 TTY 时，search 与 ask 输出限制为 50000 字节，完整响应保存到临时文件。search 保持合法 JSON——整条结果被丢弃并附加携带临时文件路径的 truncation 对象；ask（纯文本）在字节限制处截断，并在末尾打印临时文件路径。

这套约定在 cli/README.md 的 "Agent / Non-Interactive Use" 一节有完全一致的描述，是 Agent 集成时最重要的行为契约。

退出码

代码	名称	含义
0	Success	命令成功完成
1	General	未知或未分类错误
2	BadRequest	参数无效
3	NotConfigured	缺少配置或 PAT
4	AuthFailure	PAT 无效（401/403）
5	Unreachable	服务器不可达
6	RateLimited	服务器返回 429
7	Timeout	请求超时
8	ServerError	服务器返回 5xx
9	NotAvailable	功能/端点不存在

源码细节：退出码与 HTTP 状态码有明确的映射关系——400/422→BadRequest，401/403→AuthFailure，404→NotAvailable，429→RateLimited，408/504→Timeout，5xx→ServerError（见 cli/internal/exitcodes/codes.go 的 ForHTTPStatus）。common.go 中的 apiErrorToExit 还会把 API 错误、认证错误、网络错误分别归入对应退出码。

无状态性

每次调用相互独立：

• search 不会创建聊天会话；
• ask 创建一次性聊天会话（源码中以 parentID := -1 起始，见 cli/cmd/ask.go）；
• 无法跨多次调用串联上下文——每次调用都是全新开始。

因此 Agent 如果需要多轮上下文，必须自行在问题中携带前文内容。

何时使用（Agent 决策指南）

使用 onyx-cli search 的场景：

• 需要查找特定文档，或为某项任务收集上下文；
• 需要自己基于多个源文档进行推理；
• 用户要求在公司知识库中查找或检索信息；
• 需要带引用的结构化结果（文档 ID、数据源类型、内容）。

使用 onyx-cli ask 的场景：

• 用户想要直接答案、摘要或综合结论；
• 人类可读的响应比原始文档更有用；
• 需要 LLM 跨源推理并产出答案。

两者都不应使用的场景：

• 问题关于通用编程知识（应使用 Agent 自身知识）；
• 用户询问当前仓库中的代码（应使用 grep/read 工具）；
• 用户未提及 Onyx 且问题不涉及企业内部数据。

端到端实战示例

# 检索文档
onyx-cli search "What is our deployment process?"
onyx-cli search --source slack "auth migration status"
onyx-cli search --raw "API documentation" | jq '.results[].title'

# 提问获取答案
onyx-cli ask "What are the steps to deploy to production?"
onyx-cli ask --agent-id 3 "What were the action items from last week's standup?"
cat error.log | onyx-cli ask --prompt "What does this error mean?"

完整的 Agent 接入流程可归纳为：validate-config 确认连通性 → agents 挑选目标 Agent（可选）→ 批量 search 收集资料或 ask 直接作答 → 解析 stdout JSON / 流式文本 → 依据退出码与 error 字段处理异常。配合 cli/internal/embedded/embed.go 中打包的这份 SKILL.md，AI 编码 Agent 即可自动发现并正确使用 onyx-cli，将企业知识库变为自身推理的事实底座。