最后更新 2026年11月6日

向 Codex 添加自定义模型 — user-models.json 与通用供应商

Q: 如何验证自定义模型？

用 ./bin/test-model 'PROVIDER/MODEL' --live --yes 做实时（消耗配额）检查，然后完全退出并重新打开 Codex，让目录刷新。

在 Codex 中使用自定义模型，指的是通过 Codex Router 的 custom 供应商和通用供应商把你自己的端点加入 Codex 选择器。其它每个供应商都拥有一个地址；custom 不拥有任何地址——每个模型都指定自己的端点、认证与元数据。

custom 供应商是什么

一个 custom 供应商可以同时容纳免费的社区端点、朋友的自托管服务器和付费 API Key。需要 Key 的模型会在自己那一行注明。该供应商绝不会替你选择，也从不属于默认集合，因为它容纳的内容完全取决于有人放进了什么。

启用它——不花费任何东西，也不要求任何东西：

./bin/model-router codex providers enable custom

Windows 上用 ./model-router.ps1 codex 加相同命令。

无凭据允许清单边界

无需凭据即可访问的端点是注册表片段唯一无法自行引入的东西。它的地址必须在 src/model-registry.mjs 中加入允许清单，正如匿名供应商一样。否则，在 config/custom/ 下添加一个 JSON 文件就足以把你的提示词发送到互联网上的任意主机，且无从认证。

携带 Key 的端点，或保持在回环地址上的端点，无需允许清单条目——Key 或地址本身就是边界。这是”方便”与”不安全”之间刻意划出的界线。

Control Center 现可直接操作：Models → Custom → Add endpoint。输入名称、基础 URL、Chat Completions 或 Responses 协议及密钥。保存时会检查 GET /models；之后可从该端点的标签添加已发现模型，或用 By name 添加私有 ID，也可编辑端点、删除模型或连同密钥与模型一并删除端点。

现在每个 user-models.json 模型条目都能单独指定 endpoint.protocol：openai 为 Chat Completions（默认）、anthropic 为 Messages、openai-responses 为 Responses。协议和凭据属于该模型端点，而非共享的 custom 容器。若写了 supportedEndpoints，所选 OpenAI 协议必须包含 /chat/completions 或 /responses；Messages 模型不声明 OpenAI 的 supportedEndpoints。

显式配置的端点会保留自己的目标地址，即使某个内置预设使用相同的上游模型 ID，也不会被悄悄改路由到该预设的公共云端点。

可选的逐模型 goalContinuationGuard 标志，会在连续三次已完成的目标回复都很短、内容高度重复且没有工具活动时，本地停止自动续跑。默认关闭；新指令、工具活动或目标变化会重置检查。

另一个逐模型可选项 repetitionGuard: true 能阻止 GLM-5.3 持续重复正文，且不会重发供应商请求。JSON 样例、代码、工具与推理内容不参与该启发式判断；默认关闭。

逐模型的 reasoningTagPolicy 控制可见回答中疑似推理标签的清理。未知路线现在默认为 preserve，保留字面 XML 示例和引用的 <think> 标签。只有确认路线会泄漏内联推理标签时才用 legacy-inline；hy4-nonce 仅限已验证的 Hy4 Preview 路线。已知的 Qwen Plan Flash 与 Hy4 Preview 路线仍保留各自的兼容处理，显式设置 preserve 则会覆盖默认行为。

通用供应商

通用供应商让你把 OpenAI 兼容服务注册为供应商，而无需等待注册表条目。例如一个 Perplexity 搜索 sidecar：

./bin/model-router codex providers generic add perplexity-search \
  --name "Perplexity Search" \
  --base-url https://api.perplexity.ai \
  --adapter openai-chat
./bin/model-router codex providers generic credential perplexity-search set

通用 Responses 供应商可用 --adapter openai-responses --transport websocket 选择复用上游 WebSocket 连接；原生流量默认仍走 HTTP，除非设置 MODEL_ROUTER_NATIVE_TRANSPORT=websocket。发送前失败可回退到 HTTP，但结果不明的进行中转轮不会被重放。

凭据命令绝不接受把 Key 作为参数；它会提示输入。描述符、凭据引用以及任何按模型的绑定都是私有的原子状态。

聊天模型与工具 API

Models 选择器添加的是对话模型；选择后会更换 Codex 中的助手。工具 API 则需要自己的客户端。例如连接 OpenRouter 后，本地 /v1/decisions 端点可提供隐藏路线 openrouter-decisions/jev-latest，但仍需单独配置调用它的 Decisions 客户端。把 OpenRouter 的聊天模型 typesafe/jev-router 加入选择器，既不会启用隐藏路线，也不会安装 Codex 工具输出裁剪钩子。如果配置后 Router 离线，在 Control Center 使用 Status → Service health → Fix，检查健康状态，再切回已知可用的聊天模型。Fix 会修复并重启已安装的 Router，可能中断路由对话，但不会启用 Decisions 客户端。

搜索 sidecar

对于没有已验证搜索的路由模型，Codex 可以使用显式的搜索 sidecar。该绑定指定一个确切的路由模型和一个供应商，且对已经具备搜索能力的模型会被拒绝：

./bin/model-router codex search-sidecar set PROVIDER/MODEL perplexity-search
./bin/model-router codex search-sidecar status PROVIDER/MODEL

更改绑定后完全退出并重新打开 Codex，让其模型目录刷新。移除通用供应商也会移除其凭据以及所有依赖的 sidecar 绑定。

定制与验证命令

发现、定制与验证都建立在同一份受保护的用户模型状态之上：

命令	用途
`./bin/discover-models <provider>`	列出某供应商实时目录暴露的内容
`./bin/curate-models <provider>`	选择要发布的模型与元数据
`./bin/test-model 'PROVIDER/MODEL' --live --yes`	实时（消耗配额）检查
`./bin/refresh-catalog`	重建 Codex 读取的合并目录

实时测试现在只有在分帧的助手输出中出现预期标记，且响应报告成功完成时，才会判定流式兼容。回显的输入、引用的完成词、仅含推理的文本或失败的终止事件都不能通过流式测试。

定制条目保存在 user-models.json 中，更新后仍然保留，可原地编辑，也可通过重新运行定制并取消选择来移除。

交互式定制现在会遵守你明确选择的“不支持图片”，即使供应商目录声明了图片输入。发现模型时，路由器采用供应商公布的最小实际服务上下文上限，而不是更大的能力数值。目录发现与额度读取使用已配置的 API Key 池；若池不可用，不会悄悄回退到另一个旧账户。

一个免费自定义模型示例

注册表发布了一个免费的 custom 示例：共享 Hugging Face Inference Endpoint 上的 Qwen3.8-27-free-victor。它提供 262,144 token 上下文、图像输入、工具调用，以及每个 IP 每分钟约 30 次请求。其所有者表示，一旦上线热度消退就会将其退役，因此请把它当作尝鲜模型而非依赖对象。

该端点不携带凭据。使用这些免费路线风险自负：没有人承诺为你提供服务，访问是一种公开的例外而非权益，且它可能被收紧、限流或在不通知的情况下撤回。

常见问题

Codex Router 中的 custom 供应商是什么？ custom 供应商不拥有固定地址。它的每个模型都指定自己的端点、认证与元数据，因此一个供应商可以同时容纳免费的社区端点、自托管服务器和付费 API Key。

为什么有些自定义端点需要允许清单？ 无需凭据即可访问的端点必须在 src/model-registry.mjs 中加入允许清单。否则添加一个 JSON 文件就可能把提示词发送到任意主机，且无从认证。携带 Key 或走回环地址的端点无需允许清单条目。

如何验证自定义模型？ 用 ./bin/test-model ‘PROVIDER/MODEL’ —live —yes 做实时（消耗配额）检查，然后完全退出并重新打开 Codex，让目录刷新。

相关：模型总览、安装、工作原理、选择器故障排查。