全模型支持下的第一次配置 OpenAI兼容路由的钥匙怎么填
装好察元AI 桌面单机版之后，第一个绕不过的步骤是给它配模型供应商。这一步看似简单，但选错供应商或者钥匙填错位置，后面的对话、RAG、工具调用都会跟着出问题。这一篇专门讲第一次配置模型的几个关键点。
打开主界面右上的设置，进 模型供应商 这一栏。chayuan-desktop 的网关层抹平了 18 家以上厂商的协议差异，前端这个 UI 把它们组织成了一个列表。每一家有名字、地址、钥匙、可选的组织 ID，以及一个 OpenAI 兼容路由 的开关。
第一种情况：用国外厂商，比如 OpenAI 或 Anthropic。把 base URL 留默认，钥匙填上从厂商后台拿的那串字符。点保存。chayuan-desktop 会立刻去探测 /v1/models，把对话模型、嵌入模型、视觉模型自动归类。如果探测失败，先确认网络能通；办公电脑常见的是被代理拦截，配代理或者把 chayuan-desktop 加到代理白名单。
第二种情况：用国内厂商，比如 DeepSeek、Moonshot、智谱、文心、通义、豆包。每家都有自己的 base URL，但都遵循 OpenAI 兼容协议。比如 DeepSeek 是 https://api.deepseek.com/v1，Moonshot 是 https://api.moonshot.cn/v1。钥匙填好之后行为跟 OpenAI 一致。这就是 全模型支持 的第一层意义：填一个钥匙，剩下的格式都是统一的。
第三种情况：用本地推理服务，比如 Ollama、LM Studio、vLLM、Xinference。chayuan-desktop 提供了一个 OpenAI 兼容路由 的供应商类型，地址填本地或者内网那台推理服务的 URL，钥匙随便填一个非空字符串。保存后探测 /v1/models 拉回模型列表。这种用法适合无外网环境或者公司有显卡服务器集中跑模型。
第四种情况：用自家私有部署的模型。如果你公司自家用 vLLM 或者 SGLang 部署了一个微调模型，把它对外暴露的接口当 OpenAI 兼容路由 接进来即可。钥匙可以是公司内部签发的 token，base URL 是内部 IP 端口。
钥匙的存储是个细节。chayuan-desktop 把所有钥匙加密存到 CHAYUAN_ROOT/credentials 目录下，加密用的是 Tauri Stronghold 加 ChaCha20-Poly1305。密钥派生跟当前操作系统用户绑定，所以你直接拷贝整个 CHAYUAN_ROOT 到另一台电脑上是解不开的。这个设计能挡住一部分简单的物理拷贝场景，但不能挡住有管理员权限的攻击者。
模型分类的自动归类逻辑值得讲一下。/v1/models 返回的列表里每条记录通常有 id 字段，比如 gpt-4o、qwen-plus、deepseek-chat 之类。chayuan-desktop 的网关层维护了一份模型卡片库，按 id 模糊匹配把它们分到 chat、embedding、image、rerank、vision 这几个类别。匹配不上的会进 unknown 列表，这一类需要你手动指定类别。
模型生效优先级。同一类别下可能有多个模型可用，比如对话类下既有 gpt-4o 又有 deepseek-chat。生效顺序是用户在对话框里手动选 大于 默认候选 大于 自动挑。默认候选是按你接入顺序的第一个模型自动设置的，可以在设置里调整。
钥匙填错的常见症状有几个。第一，对话发出去之后立刻回 401 或 403，说明钥匙无效；第二，发出去回 429，说明被限速或者额度用完；第三，发出去无响应，说明地址写错或者网络不通；第四，对话能跑但 RAG 嵌入失败，说明嵌入模型没接入或者钥匙缺嵌入权限。
WPS AI 插件 chayuan-wps 共用同一份模型供应商配置。在桌面单机版里配好之后，加载项不需要再填一次。这个一致性是 chayuan-desktop 与 chayuan-wps 一开始就约定好的体验。
第一次配置模型这一步如果你在五分钟内搞完，后面 察元智库 的所有功能都顺手了。如果卡住，多半是网络或者钥匙的小问题，回到上面这几条排查一遍。
