12. 进阶（一）：LLM Provider 与模型配置

omicOS 的智能体背后是大语言模型。默认情况下你用 omicOS 云端提供的模型即可，但进阶用户可以自带 API key、指定 provider 和模型。本章讲清楚选择逻辑。

12.1 Provider 选择优先级

omicos 决定"用哪个厂商"时，按以下顺序逐项尝试，命中即止：

聊天请求里的 config.provider（网页端 / API 显式传入）
OMICOS_LLM_PROVIDER 环境变量
OMICOS_PROVIDER 环境变量（旧别名）
从模型名推断（如模型名含 deepseek 就用 deepseek）
从首个可用的 API key 检测（有 DEEPSEEK_API_KEY → deepseek；MINIMAX_API_KEY → minimax；OPENAI_API_KEY → openai）

若全都没命中，报错 no model provider configured。

12.2 Model 选择优先级

决定"用哪个模型"时，类似地：

聊天请求里的 config.model
OMICOS_LLM_MODEL
OMICOS_MODEL（旧别名）
按 provider 取默认：deepseek → deepseek-v4-flash，其余 → gpt-4o-mini

模型名可以带 provider/ 前缀（会被自动剥离），如 deepseek/deepseek-v4-flash。

12.3 支持哪些 provider

类别	示例	说明
OpenAI 兼容（catalog 驱动）	openai、deepseek、qwen、zhipu、moonshot、xai、groq、mistral、ollama、openrouter、together、fireworks、deepinfra、cerebras、perplexity、minimax、siliconflow 等	由云端模型 catalog 动态提供，最常用
OAuth	codex（OpenAI）、gemini-cli（Google）	用第三方账户的 OAuth 凭证，不用 API key
自定义	custom_openai、custom_anthropic	指向你自建 / 私有部署的端点

注意： mock provider 在运行时被显式禁用；原生 anthropic 未实现，需要用 custom_anthropic 兼容端点接入。另外，omicos 不向服务端发送 temperature 参数（部分推理模型会拒绝 temperature≠1）。

12.4 API key 从哪来

omicos 解析某个 provider 的 API key 时，按以下顺序找：

环境变量：<PROVIDER>_API_KEY，其中 provider id 里的连字符转下划线。例如 alibaba-coding-plan 的 key 是 ALIBABA_CODING_PLAN_API_KEY。
auth.json 回退文件，查找顺序为：
- $OMICOS_LOCAL_HOME/auth.json
- $OMICOS_RUNTIME_HOME/auth.json
- <当前目录>/.omicos/auth.json
- ~/.omicos/auth.json

auth.json 是一个简单的 JSON 字典，只有非空值生效：

{
  "DEEPSEEK_API_KEY": "sk-...",
  "OPENAI_API_KEY": "sk-..."
}

Ollama 比较特殊：未设 key 时会自动用占位符 ollama，因为本地 Ollama 不需要真实 key。

12.5 自定义端点（endpoint）

每个 provider 的 endpoint 解析顺序：

<PROVIDER>_API_BASE 环境变量
云端 catalog 里的 api_base（缓存在 ~/.omicos/cloud-models/models.json）

特例：custom_openai 默认端点是 http://127.0.0.1:8000/v1（方便接本地推理服务，如 vLLM）。

完整示例——用自建 vLLM 服务：

export OMICOS_LLM_PROVIDER=custom_openai
export CUSTOM_OPENAI_API_BASE=http://127.0.0.1:8000/v1
export CUSTOM_OPENAI_API_KEY=dummy           # 本地服务通常不校验
export OMICOS_LLM_MODEL=Qwen2.5-72B-Instruct
omicos serve

12.6 云端模型 catalog

omicos 会从 omicos-admin 拉取一份模型 catalog（哪些模型可用、上下文窗口、是否支持 vision / 内联图片等动态标记），缓存在 ~/.omicos/cloud-models/models.json。相关变量：

变量	作用
`OMICOS_MODELS_OFFLINE`	离线，只用本地缓存
`OMICOS_MODELS_CLOUD_URL`	覆盖 catalog 拉取地址
`OMICOS_MODELS_CACHE_DIR`	覆盖缓存目录

12.7 视觉模型（Vision）

如果分析里需要让模型"看图"（如解读生成的图表），可以单独配置一个视觉模型，独立于主聊天模型：

export OMICOS_VISION_MODEL=gpt-4o
export OMICOS_VISION_BASE_URL=https://api.openai.com/v1
export OMICOS_VISION_API_KEY=sk-...

12. 进阶（一）：LLM Provider 与模型