自定义模型配置

xopc 通过 ~/.xopc/models.json 支持自定义模型服务商。

内置目录： 与 @earendil-works/pi-ai 的 KnownProvider 一致；CLI 与网关 设置 → 服务商 对内置 id 的密钥、OAuth 与环境变量提示与此对齐。其它厂商（如仅用于文生图/STT/TTS 的 dashscope）在 models.json 里用 providers.<id> 配置 baseUrl、apiKey、api 等。

内置 LLM 服务商（pi-ai）

内置 provider id 与 pi-ai 一致；环境变量名以仓库内 src/providers/env-keys.ts 的 PROVIDER_ENV_MAP 为准。与 xopc.json → providers 对应的汇总表见配置说明 — providers。

默认对话模型：文档与向导里常把 DeepSeek 作为优先推荐；密钥写在 ~/.xopc/xopc.json 的 providers.deepseek 或对应环境变量即可（BYOK，详见配置）。

当前内置覆盖（节选）：DeepSeek、OpenAI、Anthropic、Google / Vertex、Azure OpenAI、AWS Bedrock、Groq、xAI、Mistral、Cerebras、OpenRouter、Vercel AI Gateway、智谱 z.ai、MiniMax（国际/国内）、Kimi Coding、Moonshot（moonshotai / moonshotai-cn）、Hugging Face、Fireworks、Together、OpenCode / OpenCode Go、Cloudflare Workers AI 与 Cloudflare AI Gateway、GitHub Copilot、OpenAI Codex（OAuth）、Google Gemini CLI / Antigravity、小米 MiMo（见下）。dashscope 为 xopc 侧文生图/语音等 HTTP 能力的环境 id，不是 pi-ai 的 LLM KnownProvider。

小米 MiMo（`xiaomi` 与 `xiaomi-token-plan-*`）

小米提供四个内置 id，对应 不同接口与计费产品，并非重复项：

Provider id	用途	接口域（pi-ai 默认）	典型环境变量
`xiaomi`	按量 API 计费	`api.xiaomimimo.com`	`XIAOMI_API_KEY`
`xiaomi-token-plan-cn`	Token 套餐 · 中国	`token-plan-cn.xiaomimimo.com`	`XIAOMI_TOKEN_PLAN_CN_API_KEY`
`xiaomi-token-plan-ams`	Token 套餐 · 阿姆斯特丹	`token-plan-ams.xiaomimimo.com`	`XIAOMI_TOKEN_PLAN_AMS_API_KEY`
`xiaomi-token-plan-sgp`	Token 套餐 · 新加坡	`token-plan-sgp.xiaomimimo.com`	`XIAOMI_TOKEN_PLAN_SGP_API_KEY`

密钥在 MiMo 开放平台 创建；模型引用 provider/model 中的 provider 须与所持有密钥类型一致。

OAuth 与 API Key（LLM）

部分服务商支持 OAuth（浏览器登录，凭据在 ~/.xopc/credentials/oauth/ 或 auth profiles）。openai-codex 正常使用为 仅 OAuth，网关「服务商」里不按静态厂商 API Key 配置。github-copilot 可使用环境变量中的 GitHub 类 token 或 OAuth，详见 PROVIDER_ENV_MAP。

快速开始

创建 ~/.xopc/models.json：

json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

apiKey 是必需的，但 Ollama 会忽略它，所以任意值都可以。

配置

文件位置

~/.xopc/models.json（或通过 XOPC_MODELS_JSON 环境变量设置）

最小配置示例

json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" }
      ]
    }
  }
}

完整配置示例

json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "llama3.1:8b",
          "name": "Llama 3.1 8B (本地)",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 32000,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    },
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "OPENROUTER_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "anthropic/claude-3.5-sonnet",
          "name": "Claude 3.5 Sonnet (OR)",
          "compat": {
            "openRouterRouting": {
              "only": ["anthropic"]
            }
          }
        }
      ]
    }
  }
}

支持的 API

API	说明
`openai-completions`	OpenAI Chat Completions（最兼容）
`openai-responses`	OpenAI Responses API
`anthropic-messages`	Anthropic Messages API
`google-generative-ai`	Google Generative AI
`azure-openai-responses`	Azure OpenAI
`bedrock-converse-stream`	AWS Bedrock
`openai-codex-responses`	OpenAI Codex
`google-gemini-cli`	Google Gemini CLI
`google-vertex`	Google Vertex AI

服务商配置

字段	说明
`baseUrl`	API 端点 URL
`api`	API 类型（见上表）
`apiKey`	API Key（见下方解析方式）
`headers`	自定义请求头
`authHeader`	设为 `true` 自动添加 `Authorization: Bearer <apiKey>`
`models`	模型配置数组
`modelOverrides`	覆盖内置模型的配置

模型配置

字段	必需	默认值	说明
`id`	是	-	模型标识符（传给 API 的值）
`name`	否	`id`	显示名称
`api`	否	服务商的 `api`	覆盖服务商的 API
`reasoning`	否	`false`	支持扩展思考能力
`input`	否	`["text"]`	输入类型：`["text"]` 或 `["text", "image"]`
`contextWindow`	否	`128000`	上下文窗口大小
`maxTokens`	否	`16384`	最大输出 Token 数
`cost`	否	全为 0	`{input, output, cacheRead, cacheWrite}` 每百万 token
`headers`	否	-	模型专用的自定义请求头
`compat`	否	-	OpenAI 兼容性设置

覆盖内置服务商

覆盖 Base URL

若需经由自建兼容网关、反向代理或中转服务访问内置服务商，可覆盖其 baseUrl：

json

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://my-proxy.example.com/v1"
    }
  }
}

模型覆盖

自定义特定内置模型：

json

{
  "providers": {
    "openrouter": {
      "modelOverrides": {
        "anthropic/claude-sonnet-4": {
          "name": "Claude Sonnet 4 (Bedrock 路由)",
          "compat": {
            "openRouterRouting": {
              "only": ["amazon-bedrock"]
            }
          }
        }
      }
    }
  }
}

API Key 解析方式

apiKey 字段支持三种格式：

1. Shell 命令

前缀 ! 执行 shell 命令：

json

{
  "apiKey": "!op read 'op://vault/item/credential'"
}

2. 环境变量

使用环境变量名称（全大写）：

json

{
  "apiKey": "ANTHROPIC_API_KEY"
}

3. 字面量值

直接使用值：

json

{
  "apiKey": "sk-..."
}

前端界面

在 Web UI 中访问模型配置：

打开 Web UI（默认 http://localhost:18790）
进入设置 → 模型
使用可视化编辑器配置服务商和模型

服务商管理

添加服务商

点击 "添加服务商" 打开服务商配置对话框：

使用预设快速设置：

Ollama - 本地 LLM (http://localhost:11434/v1)
LM Studio - LM Studio 本地服务器 (http://localhost:1234/v1)
OpenRouter - 聚合多家服务商 API（https://openrouter.ai/api/v1）
Vercel AI Gateway - Vercel AI Gateway (https://ai-gateway.vercel.sh/v1)
vLLM - vLLM 推理服务器 (http://localhost:8000/v1)
自定义 - 手动配置

选择预设会自动填写基础 URL 和 API 类型。

配置字段：

服务商 ID - 唯一标识符（小写字母、数字、连字符，下划线）
API 类型 - API 协议（OpenAI Completions、Anthropic Messages 等）
基础 URL - API 端点 URL（OpenAI 兼容 API 应以 /v1 结尾）
API Key - 支持字面量值、环境变量（大写）或 shell 命令 (!command)

高级选项：

自动添加 Authorization 请求头 - 自动添加 Authorization: Bearer {apiKey}
自定义请求头 - JSON 格式的自定义请求头

模型管理

添加/编辑模型

点击 "添加模型" 或现有模型的编辑图标打开模型编辑器对话框：

基础标签页：

模型 ID - 唯一标识符（如 llama3.1:8b、gpt-4o）
显示名称 - 人类可读的名称
输入类型 - 仅文本或文本+视觉
支持推理 - 启用具有扩展思考能力的模型
上下文窗口 - 最大上下文 token 数（默认：128000）
最大输出 Token - 最大响应 token 数（默认：16384）

高级标签页：

成本配置 - 每百万 token 定价：
- 输入 / 输出 / 缓存读取 / 缓存写入
自定义请求头 - 模型专用的请求头（JSON 格式）

兼容性标签页：

OpenAI Completions 设置：
- 支持 Store
- 支持 Developer Role
- 流式响应中支持 Usage
- Max Tokens 字段（自动检测 / max_completion_tokens / max_tokens）
路由配置（用于 OpenRouter/Vercel）：
- 服务商顺序 - 优先级列表（如 anthropic, openai）
- 允许的服务商 - 白名单（如 amazon-bedrock）

API Key 测试

每个服务商显示 API key 类型标签（literal/env/shell）。点击 "测试" 可以：

验证 key 是否正确解析
查看解析后的值类型
检查错误（如缺少环境变量）

统计信息显示

工具栏显示实时统计：

服务商数量 - 自定义服务商数量（>0 时高亮蓝色）
模型数量 - 所有服务商的模型总数

操作按钮

验证 - 检查配置错误而不保存
保存 - 保存更改到 models.json
重新加载 - 热重载配置无需重启
显示/隐藏 JSON - 查看原始 JSON 配置

热重载

在 UI 中保存更改后会自动重新加载。无需重启。

配置示例

Ollama（本地）

json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

OpenRouter

json

{
  "providers": {
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "OPENROUTER_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "anthropic/claude-3.5-sonnet",
          "compat": {
            "openRouterRouting": {
              "order": ["anthropic", "openai"]
            }
          }
        }
      ]
    }
  }
}

Vercel AI Gateway

json

{
  "providers": {
    "vercel-ai-gateway": {
      "baseUrl": "https://ai-gateway.vercel.sh/v1",
      "apiKey": "AI_GATEWAY_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "moonshotai/kimi-k2.5",
          "name": "Kimi K2.5 (Fireworks via Vercel)",
          "compat": {
            "vercelGatewayRouting": {
              "only": ["fireworks", "novita"]
            }
          }
        }
      ]
    }
  }
}

LM Studio

json

{
  "providers": {
    "lmstudio": {
      "baseUrl": "http://localhost:1234/v1",
      "api": "openai-completions",
      "apiKey": "lmstudio",
      "models": [
        { "id": "local-model" }
      ]
    }
  }
}

API 端点

方法	端点	说明
GET	`/api/models-json`	获取 models.json 配置
POST	`/api/models-json/validate`	验证 models.json 配置
PATCH	`/api/models-json`	保存 models.json
POST	`/api/models-json/reload`	热重载
POST	`/api/models-json/test-api-key`	测试 API key 解析

故障排除

模型未显示

检查浏览器控制台是否有错误
验证 models.json 语法是否为有效 JSON
检查设置 → 模型页面是否有验证错误
确保 API Key 正确解析（使用测试按钮）

API Key 不生效

使用"测试"按钮验证解析
检查环境变量是否设置
对于 shell 命令，确保手动运行时有效
检查日志中的命令执行错误

更改未生效

点击 UI 中的"重新加载"强制刷新
检查 models.json 文件是否正确保存
如需可重启网关

与 config.json 分离

注意： models.json 与 config.json 是分开的：

config.json 包含内置服务商的 API keys（简单字符串格式）
models.json 包含自定义服务商配置（带模型）

这种分离允许：

不同的文件权限来保护敏感的 API keys
更方便管理自定义模型配置
热重载模型而不影响其他设置

自定义模型配置 ​

内置 LLM 服务商（pi-ai） ​

小米 MiMo（xiaomi 与 xiaomi-token-plan-*） ​

OAuth 与 API Key（LLM） ​

目录 ​

快速开始 ​

配置 ​

文件位置 ​

最小配置示例 ​

完整配置示例 ​

支持的 API ​

服务商配置 ​

模型配置 ​

覆盖内置服务商 ​

覆盖 Base URL ​

模型覆盖 ​

API Key 解析方式 ​

1. Shell 命令 ​

2. 环境变量 ​

3. 字面量值 ​

前端界面 ​

服务商管理 ​

添加服务商 ​

模型管理 ​

添加/编辑模型 ​

API Key 测试 ​

统计信息显示 ​

操作按钮 ​

热重载 ​

配置示例 ​

Ollama（本地） ​

OpenRouter ​

Vercel AI Gateway ​

LM Studio ​

API 端点 ​

故障排除 ​

模型未显示 ​

API Key 不生效 ​

更改未生效 ​

与 config.json 分离 ​

自定义模型配置

内置 LLM 服务商（pi-ai）

小米 MiMo（`xiaomi` 与 `xiaomi-token-plan-*`）

OAuth 与 API Key（LLM）

目录

快速开始

配置

文件位置

最小配置示例

完整配置示例

支持的 API

服务商配置

模型配置

覆盖内置服务商

覆盖 Base URL

模型覆盖

API Key 解析方式

1. Shell 命令

2. 环境变量

3. 字面量值

前端界面

服务商管理

添加服务商

模型管理

添加/编辑模型

API Key 测试

统计信息显示

操作按钮

热重载

配置示例

Ollama（本地）

OpenRouter

Vercel AI Gateway

LM Studio

API 端点

故障排除

模型未显示

API Key 不生效

更改未生效

与 config.json 分离