跳转到主要内容
Codex CLI 所支持的自定义模型供应商必须依赖 OpenAI 的 Responses API(wire_api = "responses");而 Codex 内置的 Ollama 供应商仅能访问 localhost,无法连接其他机器上的模型。Tokios 则负责提供 /v1/responses 服务,并将其转换为聊天补全格式供后端调用,如此一来任何运行着 Ollama、llama.cpp、vLLM 或 LM Studio 的远程机器均可作为 Codex 的供应商,且只需通过常规的 https 端点即可实现。 本页假设您已让 Tokios 与 Codex 协同运作——请参阅将 OpenAI Codex 与您的本地模型搭配使用获取完整的 config.toml 配置指南。如果您的模型运行在与 Codex 不同的机器上,或者您正在排查无法连接的供应商问题,请继续阅读。

前置条件

  • 在模型所在机器上安装并配置好 连接器——该机器并非运行 Codex 的机器。
  • 为该模型设定一个 已注册的部署名称。
  • 获取 Tokios 的 API 密钥(sk-tok-…)
  • 已安装 Codex CLI,安装位置为运行 codex

配置 Codex

无论模型位于本地还是网络另一端,供应商配置方式均保持一致;正是 Tokios 确保了地理位置不再成为限制因素。在 ~/.codex/config.toml 中:
~/.codex/config.toml
在运行 Codex 之前,请先在环境变量中设置好您的 API 密钥。
请将 gemma-tunnel 替换为您为远程模型所注册的部署名称;该名称并非本地上游模型 ID,也不是 localhost 格式的地址。

为何此方法在本地主机无法奏效

Codex 所使用的自定义提供商必须依赖 wire_api = "responses" 才能运作:Codex 会向所有已配置的提供商发送符合 Responses API 规范的请求;而其内置的 Ollama 提供商则被设定为使用固定的 localhost 基础地址,因此无法指向其他机器上的模型。 要让远程模型顺利充当 Codex 的提供商,需同时满足两个条件:该端点必须支持 Responses API,且该端点地址必须是 Codex 在任何运行环境下都能访问的稳定 https 地址。大多数本地推理服务器——如 Ollama、llama.cpp、vLLM 与 LM Studio——仅支持 Chat Completions 协议而非 Responses API。此时 Tokios 网关便位于您的连接器前端,负责接收 Codex 发来的 /v1/responses 请求并将其转换为 Chat Completions 格式后再转发至后端。如此一来,后端完全无需知晓 Responses API 的存在;Codex 也无需配置 localhost 类型的提供商——无论后端位于哪台机器、处于何种网络环境或使用了何种连接器,Codex 始终能通过 https://api.tokios.com/v1 顺利通信。
disable_response_storage = true 必须与 wire_api = "responses" 配合使用。Tokios 以无状态方式提供 Responses 接口,因此 Codex 不得依赖轮次之间的服务端响应存储。

验证功能是否正常

通过该配置执行一条简短的提示指令即可:
若您希望在不借助 Codex 的情况下直接验证端点可用性,可查阅您所部署模型的 Playground 信息,或直接发送原始请求进行测试。

故障排查

Codex 未发送 Tokios 可识别的密钥。请确认 OPENAI_API_KEY 已设置为您的 sk-tok-… 密钥,且启动 codex 的终端中环境变量已生效,并确认该密钥未在 Keys 选项卡上被轮换或禁用。
其中 model 值(位于 [profiles.tokios] 中)与已注册的部署不匹配。该值必须是您选定的公开名称(可在 Models 选项卡中查看)(例如 gemma-tunnel),而非后端在本地使用的上游模型 ID。
与该部署配对的连接器当前未连接,或已达到其并发上限(connector_unavailable / connector_busy)。请确认连接器进程正在模型所在机器上运行,且状态为 Online(可在 Connectors 选项卡中查看)。
请确认启动时使用了 --profile tokios 参数。若未指定此参数,Codex 将调用默认提供商,而非 [model_providers.tokios] 中指定的提供商。

后续步骤

OpenAI Codex 的基础设置流程

完整的 config.toml 操作指南,包含 OpenAI SDK 的配置方法。

快速入门

完成连接器配对并成功注册首个模型。