用途：onyx-cli 是智能体访问 Onyx 企业知识平台的接口，连接公司文档、应用与人员，用于回答需要内部知识的问题，例如政策、文档、流程以及 Confluence、Google Drive、Slack 等已连接来源的数据。
安装与配置：先检查 which onyx-cli，未安装则 pip install onyx-cli。若已有人运行过 onyx-cli chat（含首次设置），则无需额外配置，会自动读取 ~/.config/onyx-cli/config.json（或 $XDG_CONFIG_HOME/onyx-cli/config.json）。环境变量可覆盖配置文件：ONYX_SERVER_URL（默认 https://cloud.onyx.app）、ONYX_API_PREFIX（默认 /api）、ONYX_PAT（必需，个人访问令牌）、ONYX_PERSONA_ID、ONYX_STREAM_MARKDOWN。两者都未设置时，需运行 onyx-cli chat 交互式设置，或设置 ONYX_SERVER_URL 与 ONYX_PAT。用 onyx-cli validate-config 校验，成功退出码 0。
主要能力：onyx-cli search "查询" 返回带引用的排序文档 JSON，默认精简结构含 title、url、source_type、content、updated_at；--raw 输出完整 API 响应。支持 --source 按来源筛选、--days 限定天数、--agent-id 指定智能体、--no-query-expansion 跳过查询扩展、--max-output 控制截断。单次最多 3 个查询并发执行。onyx-cli ask "问题" 以纯文本流式输出 LLM 生成的答案，支持 --agent-id、--json（NDJSON）、--quiet、--prompt（配合管道输入上下文）、--max-output 0 关闭截断。onyx-cli agents 列出智能体 ID、名称与描述，--json 输出结构化结果。
输出与限制：stdout 输出结果，stderr 输出进度与错误；非 TTY 下无 ANSI 转义与交互提示，输出限 50000 字节，完整响应存入临时文件（路径末尾打印）。退出码涵盖 0 成功、2 参数错误、3 未配置、4 认证失败、5 不可达、6 限流、7 超时、8 服务端错误、9 功能不存在。每次调用相互独立无状态：search 不创建会话，ask 创建一次性会话，无法跨调用串联上下文。
适用场景：需要查找文档或收集任务上下文、自行推理多个文档、用户要求查询公司知识、需要带引用的结构化结果时用 search；用户想要直接答案、摘要或综合时用 ask。通用编程知识、当前仓库代码或未涉及内部公司数据的问题不应使用。搜索建议将输出写入文件后另行解析，避免链式脚本挂起。