Codex Model Router

在 VS Code 中为 Codex 管理模型接入。扩展内置代理默认只监听本机，也可改为局域网监听：Codex 选择稳定的模型别名，Router 将后续请求转发到你配置的供应商和实际模型。更换上游时，可以保留会话正在使用的别名。

Manage Codex model connections inside VS Code. The extension runs a proxy that listens on loopback by default and can optionally listen on the LAN. Codex selects a stable model alias, and Router forwards subsequent requests to your configured provider and actual model. You can change the upstream destination while keeping the alias used by a conversation.

本扩展是独立的社区工具，并非 OpenAI 或 VS Code 官方扩展。需要另行安装 Codex 扩展，并自行准备可用的供应商账号和 API Key。

This is an independent community tool, not an official OpenAI or VS Code extension. Install the Codex extension separately and provide your own supported provider account and API key.

工作方式 / How it works

Router 在 VS Code 扩展主机内提供本地 Responses 代理和图片生成 MCP 工具。配置面板维护供应商、Codex 可见的模型、实际模型映射及图片设置；无需另外启动常驻代理程序。

Router provides a local Responses proxy and an image-generation MCP tool inside the VS Code extension host. Its panel manages providers, Codex-visible models, upstream model mappings, and image settings. No separate background proxy program is required.

                VS Code / extension host
  +--------------------+     +-----------------------------+
  | Codex extension    |     | Codex Model Router          |
  | model picker       |<----| settings -> models.json     |
  | conversations      |     | authenticated proxy + MCP   |
  +---------+----------+     +--------------+--------------+
            |                               ^
            | Responses / compact / MCP     | config.json
            | (alias + Bearer token)        | providers + mappings
            +------------------------------>|
                                            |
                                            +----> Provider A / Model X
                                            +----> Provider B / Model Y
                                            +----> Image API / Model Z

Codex 从本机 models.json 读取模型能力，并把携带模型别名和代理凭证的请求发送给 Router。本机连接使用 127.0.0.1，局域网客户端使用 Router 主机的网卡地址。代理按别名查找映射，替换实际模型 ID 和供应商鉴权，再透传 Responses 请求或流式响应。图片生成走独立的 MCP 工具及供应商 Images API。

Codex reads model capabilities from its local models.json and sends an alias and Router credential to the proxy. Local clients use 127.0.0.1; LAN clients use the Router host's network address. The proxy resolves the alias, substitutes the upstream model ID and provider authentication, and forwards Responses requests or streams. Image generation uses a separate MCP tool and the provider's Images API.

  Live after Save / 保存后作用于后续请求
  Provider URL + API key ---------+
  Alias -> provider -> model -----+--> Router snapshot --> next request
  Image models + storage mode ----+
  Detailed logging toggle --------+
  Router API key ------------------+--> next request (update client credential)

  Codex reload required / 需要重载 Codex
  Alias + display + capabilities --> models.json --> Reload Codex --> picker

  Listener restart / 监听自动重启
  Port or listen mode --> Save --> rebind listener --> update client URL

供应商地址、API Key、“别名 → 供应商 → 实际模型”的映射和详细日志开关保存后，对后续请求生效；已经发出的请求沿用开始时的配置。新增别名、调整显示名称或模型能力会更新 Codex 模型目录，保存后还需重新加载 Codex。改动代理监听端口或监听范围会自动重新绑定监听，并需要同步更新 Codex 的接入地址。

Provider URLs, API keys, alias-to-provider-to-model mappings, and the detailed-logging switch take effect for subsequent requests after saving; in-flight requests keep their original settings. New aliases, display names, and model capabilities update the Codex model catalog and require a Codex reload after saving. Changing the proxy port or listen mode rebinds its listener and requires an updated Codex connection URL.

保存结果会指出本次修改的具体类别。更换映射供应商或实际模型不会改变别名的能力设置，也不需要重载 Codex；模型选择器的供应商标记可在下次重载时刷新。若此前还有模型列表或能力变更待加载，面板会单独说明，运行时路由仍实时生效。

Save feedback identifies the categories changed by that operation. Changing the mapped provider or actual model preserves the alias's capabilities and does not require a Codex reload; supplier labels in the model picker can refresh on the next reload. Earlier pending catalog or capability changes are reported separately and do not prevent live routing updates.

开始使用 / Get started

安装桌面版 VS Code 1.95 或更新版本及 Codex 扩展，然后安装 Codex Model Router。在活动栏打开 Codex Router。首次启动会创建本地配置，默认没有预置供应商、个人代理地址或 API Key。

Install desktop VS Code 1.95 or later and the Codex extension, then install Codex Model Router. Open Codex Router from the Activity Bar. The first launch creates local configuration without preconfigured providers, private proxy URLs, or API keys.

先在 设置 页填写并保存对外代理 API Key；允许 2–256 位大小写字母、数字和 -._~+/。未设置有效密钥时代理不会监听，复制配置按钮也不可用。监听范围 默认是仅本机；切换局域网监听时，代理会绑定所有 IPv4 网卡。再在 供应商 页添加接口名称、Base URL 和 API Key。Base URL 应是供应商的接口前缀，不包含末尾的 /responses；例如阿里云百炼可使用 https://dashscope.aliyuncs.com/compatible-mode/v1。

First set and save the Router API key in Settings using 2–256 ASCII letters, digits, or -._~+/. Until a valid key is set, the proxy does not listen and the copy buttons remain disabled. Listening defaults to loopback; LAN mode binds all IPv4 interfaces. Then add the provider name, Base URL, and API key in Providers. The Base URL is the provider's API prefix, without a trailing /responses; for example, Alibaba Cloud Model Studio uses https://dashscope.aliyuncs.com/compatible-mode/v1.

在 Codex加载模型 页建立 Codex 可见的模型别名并填写模型能力；在 模型映射 页把别名关联到供应商和实际模型 ID。点击底部的 保存配置。对话模型能力包括上下文窗口、图片输入及可选推理强度，应按实际供应商能力填写；Router 不会自动检测这些规格。

In Codex models, create a model alias visible to Codex and enter its capabilities. In Model mappings, connect that alias to a provider and an actual upstream model ID. Click Save configuration at the bottom. Enter conversation-model capabilities such as context window, image input, and reasoning levels according to your provider; Router does not discover those specifications automatically.

在 设置 页点击 复制接入配置，再点击旁边的 打开 Codex 配置文件，把片段合并到 ~/.codex/config.toml。片段包含与输入框完全相同的代理 Key；若已启用图片模型，还会一并包含图片 MCP 的认证配置。复制的片段使用当前保存的端口、模型目录路径和第一个对话模型别名；若本机已有 Codex model_provider，会尝试复用其 ID 和名称。根级 model_provider、model 和 model_catalog_json 要放在 TOML 表之前；已有同名字段时请修改原值，避免重复定义。

In Settings, select Copy Codex configuration, then Open Codex config file, and merge the snippet into ~/.codex/config.toml. Its Router key is identical to the value entered in Settings. When image models are enabled, it includes the authenticated image MCP settings. The snippet uses the saved port, catalog path, and first conversation-model alias. When an active Codex model_provider already exists, Router tries to reuse its ID and name. Put root-level model_provider, model, and model_catalog_json before TOML tables, and edit existing keys instead of duplicating them.

下列内容仅说明接入形状；example-router、example-model 和模型文件绝对路径都是占位值。实际使用时以 复制接入配置 生成的内容为准。

The following shows the connection shape only; example-router, example-model, and the absolute catalog path are placeholders. Use the snippet generated by Copy Codex configuration for your installation.

model_provider = "example-router"
model = "example-model"
model_catalog_json = "/ABSOLUTE/PATH/TO/.codex-model-router/models.json"

[model_providers."example-router"]
name = "Example Router"
base_url = "http://127.0.0.1:18765/v1"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

[model_providers."example-router".http_headers]
Authorization = "Bearer example-key"

局域网客户端请在 Router 主机的 模型文件 区点击 打开模型文件目录，把 models.json 复制到客户端，再将客户端 model_catalog_json 改为当地文件的绝对路径。此后修改模型列表或能力时，需要重新复制该文件并重载客户端 Codex；只修改供应商或映射则不需要。复制局域网接入配置 会让你选择主机网卡地址，并复制包含对话代理与图片 MCP 的认证片段。Codex 当前不会从自定义供应商的 /v1/models 自动建立模型目录，也不接受把 model_catalog_json 指向 HTTP URL。

For a LAN client, use Open model-file directory on the Router host, copy models.json to the client, and set the client's model_catalog_json to that file's absolute path. After changing the model list or capabilities, copy the file again and reload Codex on the client; provider and mapping changes need no file transfer. Copy LAN configuration lets you choose the host address and copies authenticated chat and image MCP settings. Codex currently does not build its catalog automatically from a custom provider's /v1/models, and model_catalog_json does not accept an HTTP URL.

首次接入或修改模型目录后重新加载 Codex，然后在 Codex 的模型选择器中选择别名。Router 不会自动改写 Codex 的 TOML 文件；更换已有别名的上游映射时，则只需在 Router 中保存。

Reload Codex after initial connection or a catalog change, then select an alias in the Codex model picker. Router does not edit Codex's TOML file automatically. To change the upstream destination of an existing alias, save the mapping in Router.

配置页面 / Configuration pages

Codex加载模型 管理别名、用途和能力；供应商 管理 API 地址及密钥；模型映射 管理实际模型的去向。这三页把 Codex 所见的名字、访问凭证和上游模型分开，因此同一个实际模型可以由多个别名引用。

Codex models manages aliases, purpose, and capabilities; Providers manages API endpoints and keys; Model mappings manages upstream destinations. These pages keep the name visible to Codex, credentials, and actual model ID separate, so several aliases may use one upstream model.

图片MCP 管理可用图片模型、默认模型和图片保存模式；设置 管理监听范围、端口、入口密钥、日志开关、Codex 接入片段、重载入口以及配置备份。多窗口同时编辑时，旧版本配置不会覆盖另一窗口的新保存；需要加载最新配置再继续编辑。

Image MCP manages available image models, the default model, and image storage mode. Settings provides the listener mode and port, ingress key, logging switch, Codex connection snippet, reload action, and configuration backup. When multiple windows edit the same files, an older draft cannot overwrite a newer save from another window; reload the latest configuration before continuing.

图片生成 / Image generation

图片生成模型与对话模型分别配置。把图片别名映射到支持 /images/generations 的供应商后，在 图片MCP 页启用它并复制图片工具配置到 ~/.codex/config.toml。重新加载 Codex 后，继续使用普通对话模型，由会话调用 Router 的 list_image_models 和 generate_image 工具；可用模型、默认模型和保存模式的后续变更保存后实时生效。

Configure image-generation models separately from conversation models. Map an image alias to a provider supporting /images/generations, enable it in Image MCP, and copy the image-tool configuration into ~/.codex/config.toml. After reloading Codex, keep using a normal conversation model and let the session call Router's list_image_models and generate_image tools. Later changes to available image models, the default model, or storage mode take effect after saving.

内存模式默认不在本地生成图片副本；文件模式或单次工具调用的 save=true 会把图片写入 ~/.codex-model-router/generated-images/。图片MCP 页提供打开保存目录的入口。是否能在 Codex 中直接预览内存图片还受 Codex 当前 MCP 客户端能力影响；需要稳定取得文件路径时可选文件模式。

Memory mode does not save a local copy by default. File mode, or save=true on an individual tool call, writes the image to ~/.codex-model-router/generated-images/. The Image MCP page includes an action to open that directory. Inline display of in-memory images also depends on the current Codex MCP client; use file mode when you need a reliable file path.

备份与迁移 / Backup and migration

Router 把用户设置保存在 ~/.codex-model-router/config.json，把 Codex 模型能力保存在同目录的 models.json。随扩展版本更新的 model-sample.json 只是生成和更新模型目录的样板，不存放你的个人设置。Codex 的 config.toml 仍由你自行维护。

Router stores user settings in ~/.codex-model-router/config.json and Codex model capabilities in the neighboring models.json. The version-managed model-sample.json is a template for creating and updating the catalog, not a store for your personal settings. You continue to manage Codex's config.toml yourself.

设置 页可以把 config.json 与 models.json 导出为一份 JSON 备份，并从该备份导入。导入前会显示模型和供应商数量，确认后覆盖本机两份配置；导入后重新加载 Codex 以读取模型目录。备份包含明文 API Key，请按凭证文件保管；model-sample.json 随已安装的扩展提供，无需打包进备份。迁移到另一台机器后，还要核对 Codex 的接入配置、监听端口和供应商可达性。

Settings can export config.json and models.json as one JSON backup and import that backup later. Before import, Router shows the model and provider counts; confirmation replaces both local files. Reload Codex afterward to read the catalog. The backup contains API keys in plain text, so handle it as a credential file. model-sample.json comes with the installed extension and is not part of the backup. On another machine, verify the Codex connection settings, listener port, and provider reachability.

适用场景 / When to use it

当多个供应商提供兼容的 Responses 接口，或者同一模型有不同上游渠道时，Router 可以让 Codex 使用固定别名，在配置面板里切换后续请求的目标。它也适合保留备用别名，以便给不同会话选择不同映射；修改一个共享别名会影响所有使用它的会话后续请求。

Router is useful when several providers offer compatible Responses APIs, or when the same model is available through several upstream channels. Codex can keep a stable alias while you change the destination for later requests. Reserve aliases can give different conversations different mappings; changing a shared alias affects future requests from every conversation using it.

Router 不会把 Chat Completions 接口转换为 Responses，也不会替供应商补齐不支持的工具调用、压缩或图片能力。上游报错会返回给 Codex，代理不会自动换供应商重试。模型目录中填写的能力应与实际模型匹配，尤其是上下文、图片输入和推理档位。

Router does not convert Chat Completions to Responses or add tool calling, compaction, or image features missing from a provider. Upstream errors go back to Codex; the proxy does not automatically retry with another provider. Catalog capabilities should match the actual model, especially context size, image input, and reasoning levels.

隐私与运行边界 / Privacy and runtime boundaries

API Key 按本扩展的设计明文保存在本机 config.json，配置页可以显示它，复制的接入片段也包含原样的 Bearer 凭证。请限制配置文件和导出备份的访问权限。代理默认只监听 127.0.0.1；局域网模式绑定 0.0.0.0，覆盖所有 IPv4 网卡，若主机有公网接口也可能对公网开放。HTTP 请求仍是明文传输。短密钥无法抵御猜测，Bearer 认证也不能防止同一网络中能监听流量的人读取请求；请仅在可信局域网使用，并检查防火墙。关闭详细日志时只记录别名、供应商、实际模型、状态和耗时；开启后才旁路解析上游返回的 token 用量。日志不记录请求正文、图片内容或 API Key。

By design, API keys are stored in plain text in the local config.json; copied connection snippets contain the same literal Bearer key. Restrict access to the configuration and exported backups. The proxy listens on 127.0.0.1 by default. LAN mode binds 0.0.0.0, covering every IPv4 interface and potentially exposing the port through a public interface. HTTP traffic is unencrypted, short keys are easy to guess, and Bearer authentication does not protect traffic from someone who can observe the network. Use LAN mode only on trusted networks and check your firewall. With detailed logging off, logs contain only aliases, providers, actual models, status, and duration; when enabled, Router also parses upstream token usage. Request bodies, image contents, and API keys are not logged.

详细日志开启后，Responses 和压缩接口的 token 统计由旁路解析，不会改动或等待客户端响应。当前支持未压缩的 JSON 与 SSE；HTTP 内容编码为 gzip 或 br 时仍原样透传，用量显示为 n/a。

With detailed logging enabled, Responses and compaction token statistics are parsed separately without modifying or holding back client responses. Uncompressed JSON and SSE are supported; HTTP bodies encoded with gzip or br are forwarded unchanged and their usage is shown as n/a.

代理随 VS Code 扩展主机运行；关闭全部相关窗口或停用扩展会停止监听。多个窗口可以复用同一配置、密钥、端口和监听范围，但正在进行的请求不会在宿主窗口退出时迁移。Remote SSH、WSL 或容器环境中，Codex 进程必须能访问运行 Router 的主机地址；远程场景需要自行核对连通性。

The proxy runs with the VS Code extension host; closing all relevant windows or disabling the extension stops its listener. Multiple windows can share the same configuration, key, port, and listen mode, but in-flight requests do not migrate if the host window exits. Under Remote SSH, WSL, or containers, the Codex process must be able to reach the Router host; verify connectivity in your remote setup.

本项目使用 MIT 许可证。版本变更见扩展详情页的 Changelog。

This project is licensed under MIT. See the extension's Changelog page for release notes.