12. 进阶（一）：LLM Provider 与模型配置
omicOS 智能体背后是大语言模型。默认用 omicOS 云端模型。本章讲进阶用法：自带 API key、指定 provider 和模型。
12.1 Provider 选择优先级
omicos 决定「用哪个厂商」时，按以下顺序逐项尝试，命中即止：
- 聊天请求里显式指定的 provider（网页端设置里选的，或调用接口时传的）
OMICOS_LLM_PROVIDER环境变量OMICOS_PROVIDER环境变量（旧别名）- 从模型名推断（如模型名里含
deepseek就用 deepseek） - 从第一个能找到的 API key 推断，顺序固定为：
DEEPSEEK_API_KEY→MINIMAX_API_KEY→OPENAI_API_KEY
全都没命中就报错：
Error: no model provider configured
mock provider 被显式禁用；指定它（或用 mock/ 前缀的模型名）会直接报错：
Error: mock provider is disabled; configure a real model provider
12.2 Model 选择优先级
- 聊天请求里显式指定的 model
OMICOS_LLM_MODELOMICOS_MODEL（旧别名）- 按 provider 取默认：deepseek →
deepseek-v4-flash，其余 →gpt-4o-mini
模型名可以带 provider/ 前缀，会被自动剥离，如 deepseek/deepseek-v4-flash 等价于 deepseek-v4-flash。
12.3 支持哪些 provider
| 类别 | 示例 | 说明 |
|---|---|---|
| OpenAI 兼容（由云端目录驱动） | openai、deepseek、qwen、zhipu、moonshot、xai、groq、mistral、ollama、openrouter、together、fireworks、deepinfra、cerebras、perplexity、minimax、siliconflow 等 | 最常用，由云端模型目录动态提供 |
| Anthropic | anthropic | 走 Anthropic Messages 协议；key 从 ANTHROPIC_API_KEY 取，也支持 OAuth 登录 |
| OAuth | codex（OpenAI）、gemini-cli（Google）、anthropic-oauth、xai-oauth | 用第三方账户的 OAuth 凭证，不需要 API key |
| 自定义 | custom_openai、custom_anthropic | 指向你自建 / 私有部署的端点 |
omicos 不向服务端发送
temperature参数——部分推理模型会拒绝temperature ≠ 1，索性一律不发。
12.4 API key 从哪来
解析某个 provider 的 API key 时，按以下顺序找：
- 环境变量
<PROVIDER>_API_KEY，provider id 里的连字符转下划线。例如alibaba-coding-plan对应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。
配好后跑一句确认。把 provider / model 换成你自己的值：
export DEEPSEEK_API_KEY=sk-your-key
export OMICOS_LLM_PROVIDER=deepseek
omicos serve --no-browser 2>&1 | head -3
预期输出：
[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] listening: http://127.0.0.1:5055
key 配错不会让启动失败。provider 在你发第一条消息时才解析，错了会在聊天里报出来。
12.5 自定义端点
每个 provider 的端点解析顺序：
<PROVIDER>_API_BASE环境变量- 云端模型目录里的
api_base（缓存在~/.omicos/cloud-models/models.json）
特例：custom_openai 默认端点是 http://127.0.0.1:8000/v1，方便接本地推理服务（如 vLLM）。key 从 CUSTOM_OPENAI_API_KEY 取，取不到时回退 OPENAI_API_KEY。
完整示例——接自建的 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 --no-browser 2>&1 | head -3
预期输出：
[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] listening: http://127.0.0.1:5055
custom_anthropic 同理。端点用 CUSTOM_ANTHROPIC_API_BASE，key 用 CUSTOM_ANTHROPIC_API_KEY（回退 ANTHROPIC_API_KEY）。它没有默认端点，不配就报错，提示缺少什么。
12.6 云端模型目录
omicos 从云端拉取模型目录（含模型、上下文窗口、是否支持视觉等），缓存在 ~/.omicos/cloud-models/models.json。相关变量：
| 变量 | 作用 |
|---|---|
OMICOS_MODELS_OFFLINE |
离线，只用本地缓存 |
OMICOS_MODELS_CLOUD_URL |
覆盖目录拉取地址 |
OMICOS_MODELS_CACHE_DIR |
覆盖缓存目录 |
确认缓存内容：
python3 -c "import json;d=json.load(open('$HOME/.omicos/cloud-models/models.json'));print(len(d['providers']),'providers; first:',d['providers'][0]['id'])"
预期输出（provider 数量取决于云端目录当时的内容）：
23 providers; first: omicos-cloud
排第一位的 omicos-cloud 是内置云端 provider。无论目录内容如何，它总在第一位。
12.7 视觉模型
需要模型「看图」（如解读生成的图表）时，单独配一个视觉模型，独立于主聊天模型：
export OMICOS_VISION_MODEL=gpt-4o
export OMICOS_VISION_BASE_URL=https://api.openai.com/v1
export OMICOS_VISION_API_KEY=sk-...
omicos serve --no-browser 2>&1 | head -2
预期输出：
[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] listening: http://127.0.0.1:5055