企业官网建设流程全解析

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

【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer

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"

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

源码细节：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 参数总表：

源码细节：--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 参数总表：

源码细节：问题的来源有三种且互斥——位置参数、--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 集成时最重要的行为契约。

退出码

源码细节：退出码与 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，将企业知识库变为自身推理的事实底座。

【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer