Onyx CLI 完整使用指南从安装配置到 search/ask/agents 实战含源码级原理【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswerOnyxdanswer是一个开源的 AI 知识平台而onyx-cli是它面向终端与 AI Agent 的命令行接口既能以交互式 TUI 与人类对话也能以无状态、纯 JSON 输出的非交互模式被脚本和 AI 编码 Agent 调用。本文以仓库内 .cursor/skills/onyx-cli/SKILL.md 为骨架结合 cli/ 目录下真实 Go 源码完整讲解安装、配置、search、ask、agents、validate-config等核心命令的用法、输出约定、退出码与底层实现帮助你或你的 Agent安全、高效地检索企业内部知识库。一、onyx-cli 是什么onyx-cli是 Agent 访问 Onyx 企业知识平台的接口它把企业文档、应用和人员连接起来用于回答需要内部知识的提问——包括公司政策、文档、流程以及来自 Confluence、Google Drive、Slack 等已连接数据源的内容。它有两个使用面向人类用户通过onyx-cli chat启动交互式聊天 TUIAI Agent / 脚本通过onyx-cli search检索带引用的文档与onyx-cli ask让 LLM 直接生成答案以非交互方式取回知识。从源码看CLI 基于 Cobra 构建根命令注册了chat、ask、search、image、agents、validate-config、serve、install-skill、experiments、deploy、install-onyx等子命令见 cli/cmd/root.go并提供了--version/-v同时打印客户端与服务端版本若服务端低于最低要求会给出升级警告与--debug全局标志。二、前置条件安装与配置1. 检查是否已安装which onyx-cli2. 安装如未安装pip install onyx-cli3. 检查是否已配置如果人类用户已经运行过onyx-cli chat首次运行会引导完成配置CLI 即开箱即用无需额外设置。配置文件位于~/.config/onyx-cli/config.json若设置了$XDG_CONFIG_HOME则为$XDG_CONFIG_HOME/onyx-cli/config.json会自动读取。环境变量可以覆盖配置文件也可以在无配置文件时作为替代方案export ONYX_SERVER_URLhttps://your-onyx-server.com # 默认: https://cloud.onyx.app export ONYX_PATyour-pat配置优先级为环境变量 配置文件 内置默认值。这一点在源码中有明确实现——cli/internal/config/config.go 的Load()函数先从磁盘读取配置再逐个应用ONYX_SERVER_URL、ONYX_PAT、ONYX_PERSONA_ID、ONYX_STREAM_MARKDOWN环境变量覆盖。其中ONYX_STREAM_MARKDOWN控制流式输出时的渐进式 Markdown 渲染未显式设置时默认启用StreamMarkdownEnabled()默认返回true见 config.go。变量必填说明ONYX_SERVER_URL否服务器 origin 或已带前缀的 API base默认https://cloud.onyx.appONYX_API_PREFIX否API 路径前缀默认/api设为空字符串表示直连后端ONYX_PAT是用于认证的个人访问令牌除非存在配置文件ONYX_PERSONA_ID否默认 agent/persona IDONYX_STREAM_MARKDOWN否启用/禁用渐进式 Markdown 渲染true/false关于ONYX_API_PREFIX的细节源码APIURL()会先对 server URL 去掉尾部/再拼接/api前缀并且会检测 URL 是否已包含该后缀以避免重复见 config.go。因此你可以直接设置ONYX_SERVER_URLhttps://your-onyx-server.com/api已带前缀也可以设置ONYX_API_PREFIX来实现直连后端不经代理路径。配置文件的持久化由Save()完成以0600权限写入config.json见 config.go确保 PAT 不泄露。若既无配置文件也未设置环境变量请告知用户onyx-cli需要配置并让其二选一运行onyx-cli chat交互式完成首次配置或设置ONYX_SERVER_URL与ONYX_PAT环境变量ONYX_PAT存放 PAT。4. 验证配置onyx-cli validate-config成功时退出码为 0失败时以非零退出码返回并附描述性错误信息详见下方退出码一节。源码中该命令会依次检查配置文件或环境变量是否存在、PAT 是否已设置、服务器是否可达、凭据是否有效并在通过后打印Status: connected and authenticated与服务端版本见 cli/cmd/validate.go。它还会比对服务端版本与最低要求版本若过低会给出please upgrade警告。三、核心命令1.search检索文档onyx-cli search What is our deployment process?返回 Onyx 知识库中经过排序、带引用的文档以 JSON 输出。默认输出为精简结构{results: [{title, url, source_type, content, updated_at}, ...]}。结果只包含 LLM 判定为相关的文档按相关性排序content是每条结果的完整 chunk 文本。使用--raw可获取完整 API 响应——单查询时直接打印额外附带每条结果的citation_id多查询时以{searches: [{query, response}, ...]}输出。关于查询成本与批量并发每次查询都是一次完整的检索流程LLM 查询扩展 → 混合检索 → 文档筛选 → 上下文扩展与 Onyx 聊天界面同款检索质量耗时可达数十秒。单次调用最多可传入 3 个查询且并发执行——把相互独立的问题批量放入一次调用远比逐个串行调用快。这一上限maxSearchQueries 3定义于 cli/cmd/search.go。多查询输出为{searches: [{query, results}, ...]}按参数顺序排列失败查询带有error字段且results为 null部分失败时退出码仍为 0所以必须逐条检查每个查询的error字段。关于 Agent 的实用建议把检索输出写入文件再用单独的 shell 调用去解析——如果在搜索命令后直接链式拼接解析脚本例如 Python heredoc脚本可能挂起、触发 shell 超时从而丢掉已经完成的检索结果。stdout 永远是合法 JSON。若响应超过--max-output字节非 TTY 默认 50000会丢弃相关性最低的结果并附加truncation对象{truncated, total_results, shown_results, total_bytes, content_truncated, full_response_path, hint}。完整响应结构与打印输出一致——单查询为results多查询为searches保存在full_response_path指向的临时文件中需要被丢弃的结果就去读那个文件。多查询场景下各查询的结果数会被统一压缩直到合并输出满足字节限制因此小结果集可以完整通过。这一整条结果丢弃、绝不让 stdout 变成非法 JSON的策略在 cli/cmd/search.go 的writeJSONReduced与truncateSearchOutput中有完整实现即使连第一条结果都塞不下时还会做 rune 边界上的内容裁剪。常用示例# 批量提交独立问题并发执行 onyx-cli search Q3 roadmap hiring plan incident postmortem template # 按来源过滤 onyx-cli search --source slack,google_drive auth migration status # 只返回最近结果 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 textsearch参数表标志类型说明--sourcestring按来源类型过滤逗号分隔slack,google_drive--daysint只返回最近 N 天的结果--agent-idint用于范围化搜索的 agent ID继承其过滤器、文档集--rawbool输出完整 API 响应附带每条结果的 citation_id--no-query-expansionbool跳过 LLM 查询扩展——更快但仅在查询已足够精确时安全精确名称、标题、带引号的短语--max-outputint打印前允许的最大字节数0 表示禁用非 TTY 默认 50000--raw时忽略底层实现要点cli/cmd/search.gobuildSearchRequest把--days转换为 UTC 时间戳写入time_cutoff把--agent-id显式传入时写入persona_id未显式传入则回退到配置里的默认DefaultAgentID--no-query-expansion置为skip_query_expansion: true。另外若一次传入多个全是单词、不含空格的参数CLI 会向 stderr 提示每个参数都会被独立检索——多词查询请加引号这是对 shell 剥引号导致查询被拆散的常见陷阱的贴心提醒。2.ask提问并获取答案onyx-cli ask What is our companys PTO policy?以纯文本流式输出 LLM 生成的答案。当你需要源文档而非合成答案时请改用search。当 stdout 不是 TTY 时输出被截断为 50000 字节完整响应保存到临时文件路径会在末尾打印。使用--max-output 0可禁用截断。# 使用指定 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 integrationsask参数表标志类型说明--agent-idint使用的 agent ID覆盖默认值--jsonbool输出 NDJSON 流事件而非纯文本绕过截断--quietbool缓冲输出结束时一次性打印不流式--promptstr问题文本与管道输入的 stdin 上下文配合使用--max-outputint打印前允许的最大字节数0 表示禁用非 TTY 默认 50000问题来源的解析逻辑cli/cmd/ask.go位置参数、--prompt与 stdin 三者按规则组合——位置参数或--prompt提供问题、stdin 提供上下文时二者会以\n\n拼接仅 stdin 有内容时直接作为问题同时给出位置参数和--prompt会报错BadRequeststdin 读取上限为 10MB。ask是一次性会话源码通过SendMessageStream向服务端流式拉取事件TTY 下会把检索过程Searching documents... / → 具体查询 / Found N documents / Thinking... / Using tool...以灰色进度打到 stderr正文走 stdout见 cli/cmd/ask.go。--json模式则把每个流事件包成{type: ..., event: ...}的 NDJSON 行输出供程序化消费。3.agents列出可用 agentonyx-cli agents onyx-cli agents --json打印 agent ID、名称和描述的表格--json输出结构化 JSON。用返回的 agent ID 配合search --agent-id或ask --agent-id使用。实现上表格模式用 tabwriter 对齐描述超 60 字符会截断见 cli/cmd/agents.go。4.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纯文本在字节上限处截断末尾打印临时文件路径这套约定对 AI Agent 尤其重要结果与进度/错误严格分离让 Agent 可以放心地把 stdout 当作纯数据管道。CLI 会通过iostreams.IsStdoutTTY自动探测 TTY 环境并调整行为无 TTY 时还会避免打印任何交互式提示。五、退出码onyx-cli使用语义化退出码便于脚本与 Agent 精确分支处理。源码定义于 cli/internal/exitcodes/codes.go并将 HTTP 状态码自动映射为退出码ForHTTPStatus见 codes.go401/403 → AuthFailure、429 → RateLimited、408/504 → Timeout、5xx → ServerError 等。码名称含义0Success命令成功完成1General未知或未分类错误2BadRequest参数无效3NotConfigured缺少配置或 PAT4AuthFailurePAT 无效401/4035Unreachable服务器不可达6RateLimited服务器返回 4297Timeout请求超时8ServerError服务器返回 5xx9NotAvailable功能/端点不存在六、无状态性每次调用相互独立search不会创建聊天会话ask创建一个一次性聊天会话无法在多次调用之间串联上下文——每次调用都从零开始。这也意味着你或你的 Agent应当把获取上下文 → 生成回答拆成明确的两步先用search拿到带引用的文档片段再由自己或ask做综合。七、何时使用使用onyx-cli search当你需要找到特定文档或为任务收集上下文想自己基于多个源文档进行推理用户让你在公司知识库中查找或检索信息需要带引用、结构化的结果文档 ID、来源类型、内容。使用onyx-cli ask当你用户想要直接答案、摘要或综合结论人类可读的回复比原始文档更有用需要 LLM 跨多个来源推理并产出答案。两者都不要用当问题是通用编程知识请用你自己的知识用户询问当前仓库中的代码请用 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 weeks standup? cat error.log | onyx-cli ask --prompt What does this error mean?九、与 Agent 生态的衔接onyx-cli的设计从一开始就面向 AI 编码 Agent本仓库的 .cursor/skills/onyx-cli/SKILL.md 正是这样一份Agent 技能文件它描述了何时用search、何时用ask、何时完全不用以及非 TTY 下的全部行为约定。CLI 还提供了onyx-cli install-skill命令可将 SKILL.md 安装到项目或用户目录支持--global、--copy、--agent claude-code等参数让主流编码 Agent 自动发现该工具。这种机器可读的技能清单 纯 JSON 的 stdout 契约 语义化退出码的组合正是它为 LLM 与 Agent 场景而生的最佳证明。十、延伸阅读Agent 技能文件本文骨架.cursor/skills/onyx-cli/SKILL.mdCLI 完整文档与安装说明cli/README.md命令注册与全局标志cli/cmd/root.go配置加载与环境变量覆盖cli/internal/config/config.gosearch命令实现并发、截断、输出形状cli/cmd/search.goask命令实现流式、NDJSON、问题解析cli/cmd/ask.go退出码定义与 HTTP 映射cli/internal/exitcodes/codes.go命令测试用例cli/cmd/ask_test.go、cli/cmd/search_test.go、cli/cmd/common_test.go【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考