1. Codex 桌面版为什么要接本地 LLM api 网关Codex 桌面版本身是一个编码 Agent 客户端它默认会走官方账号体系去调用模型。但很多开发者的真实需求是模型调用要统一收口Key 只放一份模型可以随时切换日志和用量能在一个地方看。这时候「本地 LLM api 网关」就成了一个很自然的中间层——Codex 桌面版把请求发给本机的http://localhost:8787/v1网关再按你配置的通道转发到真正的模型服务。这样做的好处很直接。第一Codex 桌面版不再关心上游是哪家模型它只认一个 base_url 和一个 Key。第二你可以在网关侧做协议适配比如 Codex 桌面版走的是 OpenAI Responses API 协议而上游模型可能只提供 Chat Completions网关帮你转。第三本地统一管理模型调用后换模型只需要改配置文件不用动客户端。这篇面向的是需要在本地统一管理模型调用的开发者目标是一次性跑通「Codex 桌面版 → 本地网关 → TaoToken 统一 Key/API 通道 → 模型」这条链路。我会给出可复制的config.toml骨架、models.json模型目录写法、auth.json认证配置以及启动验证和请求排查的具体动作。如果你还没拿到统一 Key可以先到 TaoToken API Keys 生成一个后面配置里会用到。需要提前说明一点Codex 桌面版接入本地网关不需要 Codex 官方账号。它的认证方式可以切成 apikey 模式直接读你配置文件里的 bearer token。这也是为什么很多人愿意走网关这条路——认证链路完全掌握在自己手里。2. TaoToken 前置准备统一 Key 与 API 通道在动 Codex 配置文件之前先把上游通道准备好。TaoToken 在这里扮演的是统一 Key/API 通道的角色你拿到一个 Key配一个 base_url就能在网关里调用多个模型不用为每个模型单独维护一套凭证。第一步是拿 Key。打开 TaoToken API Keys创建一个 API Key形如sk-xxxx。这个 Key 后面会写进本地网关的配置也会写进 Codex 的experimental_bearer_token字段。注意Key 只存在本地配置文件里不要提交到 Git 仓库。第二步是确认 API 通道地址。TaoToken 的 API 入口是https://taotoken.net/api这个地址不加任何查询参数。在本地网关里你会把它作为上游 base_url。Codex 桌面版本身不直接连这个地址它连的是本地网关的http://localhost:8787/v1由网关转发到 TaoToken。第三步是确认你要用的模型 ID。Codex 桌面版的config.toml里有一个model字段models.json里也要有对应 slug两边大小写必须一致。比如你打算用GLM-5.2那 config 里写model GLM-5.2models.json 里的 slug 也必须是GLM-5.2。这一点后面排障章节会重点讲因为大小写不一致是最高频的报错来源。如果你只是想先验证模型通道是否通可以到 TaoToken 模型对话 里直接发一条消息确认 Key 和模型都可用再回来配 Codex。这样能把「上游通道问题」和「本地配置问题」分开定位。3. 可复制配置config.toml / models.json / auth.jsonCodex 桌面版的配置目录在 Windows 下是C:\Users\用户名\.codex\里面有三个关键文件C:\Users\用户名\.codex\ ├── config.toml # 主配置模型、Provider、认证方式 ├── models.json # 模型目录声明模型元数据 └── auth.json # API Key 认证信息3.1 auth.json切换成 apikey 登录这个文件最简单作用就是告诉 Codex 桌面版用 apikey 模式认证而不是走官方账号登录{ auth_mode: apikey }保存后Codex 桌面版启动时会读这个文件走experimental_bearer_token里配置的 Key。3.2 config.toml主配置骨架下面是可复制的最小骨架。核心是model_provider指向本地网关base_url指向http://localhost:8787/v1wire_api用responses因为 Codex 桌面版走的是 Responses API 协议# Codex 用户配置 # 默认模型提供商localgateway model GLM-5.2 model_provider localgateway preferred_auth_method apikey forced_login_method api model_reasoning_effort high model_catalog_json C:/Users/admin/.codex/models.json [model_providers.localgateway] name localgateway base_url http://localhost:8787/v1 wire_api responses experimental_bearer_token sk-aaabbb这里有几个字段值得单独说。model_reasoning_effort high控制推理深度可选low/high/max复杂任务建议high起步。model_catalog_json指向你的models.json绝对路径Windows 下用正斜杠/更稳反斜杠容易在 TOML 里被转义。experimental_bearer_token填你本地网关接受的 Key如果你网关直接透传 TaoToken 的 Key这里就填 TaoToken 的sk-xxxx。如果你的 config.toml 里还有桌面版自己的配置段比如[desktop]、[windows]、[projects....]那些可以保留不影响网关接入。关键是model、model_provider、[model_providers.localgateway]这三块要对。3.3 models.json模型目录models.json是模型目录文件Codex 桌面版会从这里读模型的上下文窗口、推理等级、工具支持等元数据。注意 slug 必须和 config.toml 里的model完全一致大小写敏感{ models: [ { slug: GLM-5.2, prefer_websockets: false, support_verbosity: true, default_verbosity: low, apply_patch_tool_type: freeform, web_search_tool_type: text, input_modalities: [text], supports_image_detail_original: false, truncation_policy: { mode: tokens, limit: 10000 }, supports_parallel_tool_calls: true, tool_mode: null, multi_agent_version: v2, use_responses_lite: false, include_skills_usage_instructions: false, auto_review_model_override: null, context_window: 128000, max_context_window: 128000, effective_context_window_percent: 95, auto_compact_token_limit: null, comp_hash: 3000, reasoning_summary_format: experimental, default_reasoning_summary: none, display_name: GLM-5.2, description: Zhipu AI GLM-5.2 frontier agentic coding model., default_reasoning_level: high, supported_reasoning_levels: [ { effort: low, description: Fast responses with lighter reasoning }, { effort: high, description: Extra high reasoning depth for complex problems }, { effort: max, description: Maximum reasoning depth for the hardest problems } ], shell_type: shell_command, visibility: list, minimal_client_version: 0.144.0, supported_in_api: true, availability_nux: null, upgrade: null, priority: 3 } ] }context_window和max_context_window按你实际模型的窗口填填大了会导致 Codex 发超长请求被上游拒绝填小了会浪费上下文。supported_reasoning_levels里的 effort 要和 config.toml 的model_reasoning_effort对得上否则可能被忽略。3.4 本地网关侧配置本地网关需要支持 OpenAI Responses API 协议因为 Codex 桌面版wire_api responses。网关的上游指向 TaoToken上游 base_url: https://taotoken.net/api 上游 Key: sk-xxxxTaoToken 统一 Key 监听地址: http://localhost:8787 协议: Responses API/v1/responses如果你的网关只支持 Chat Completions那就需要做协议转换把 Responses 请求转成 Chat Completions 再转发。这一步是很多人在本地网关链路上卡住的地方下一节会给出检测方法。4. 验证请求从网关到 Codex 桌面版配置写完后不要急着开 Codex先分层验证。先验网关再验 Codex这样出问题能快速定位是哪一层。4.1 验证网关是否支持 Responses API用 curl 直接打本地网关的/v1/responsescurl --location http://localhost:8787/v1/responses \ --header Authorization: Bearer sk-aaabbb \ --header Content-Type: application/json \ --data { model: GLM-5.2, input: [ { role: user, content: hello } ], temperature: 0.2, top_p: 0.9 }如果网关支持 Responses API你会拿到类似这样的返回{ id: a41ed83f-354a-43be-b58c-b4bbd51240a4, object: response, created_at: 1786497107, model: glm-5.2, status: completed, output: [ { type: message, id: msg_1504b29c329946edb3cb889fff9c320f, role: assistant, status: completed, content: [ { type: output_text, text: Hello! Im GLM, trained by Z.ai. How can I assist you today?, annotations: [] } ] } ], usage: { input_tokens: 13, output_tokens: 214, total_tokens: 227 } }看到object: response和status: completed说明网关的 Responses 协议是通的。如果返回的是object: chat.completion说明网关只支持 Chat Completions需要加一层协议转换。4.2 验证 Codex 桌面版能否连上网关网关通了之后启动 Codex 桌面版。它启动时会读config.toml按model_provider localgateway去找[model_providers.localgateway]然后用base_url发请求。你可以在 Codex 里发一条最简单的消息比如「列出当前目录的文件」观察两件事一是 Codex 界面是否正常返回没有卡在 loading。二是本地网关的日志里是否出现了/v1/responses的请求记录并且状态码是 200。如果 Codex 报认证错误检查auth.json是不是apikey模式以及experimental_bearer_token是否和网关期望的 Key 一致。4.3 验证模型 ID 是否被正确识别在 Codex 里让它执行一个需要工具调用的任务比如「读取 package.json 并告诉我依赖数量」。如果模型 ID 配错Codex 会在启动阶段就报「model not found」或者直接回退到默认模型。你可以在 Codex 的设置界面看当前生效的模型名确认是GLM-5.2而不是别的。5. 本篇常见错排查5.1 模型 ID 大小写不一致这是最高频的坑。config.toml里写model GLM-5.2models.json里 slug 写成glm-5.2Codex 就找不到模型目录表现为启动后模型列表为空或者请求发出去但上游返回 model not found。解决办法是两边严格一致建议统一用你 TaoToken 通道里显示的模型 ID 原样复制。5.2 wire_api 和网关协议不匹配Codex 桌面版wire_api responses但你的本地网关只实现了/v1/chat/completions。这时候 curl 打/v1/responses会返回 404 或者协议错误。解决办法有两个一是换一个支持 Responses API 的网关二是在网关里加协议转换层把 Responses 请求映射成 Chat Completions。判断方法就是 4.1 节的 curl看返回的object字段。5.3 base_url 结尾多了或少了 /v1base_url http://localhost:8787/v1是对的Codex 会在这个基础上拼/responses。如果你写成http://localhost:8787请求会打到http://localhost:8787/responses网关可能没这个路由。反过来如果你写成http://localhost:8787/v1/responsesCodex 会拼成.../v1/responses/responses同样 404。统一用http://localhost:8787/v1。5.4 model_catalog_json 路径转义问题Windows 路径在 TOML 里用反斜杠会被当转义字符。C:\Users\admin\.codex\models.json里的\U、\.都可能出问题。建议用正斜杠C:/Users/admin/.codex/models.json或者用单引号字面量C:\Users\admin\.codex\models.json。路径错了 Codex 读不到模型目录表现和 5.1 类似。5.5 认证模式没切到 apikeyauth.json里如果还是默认的账号模式Codex 会尝试走官方登录而不是读experimental_bearer_token。确认auth.json内容是{auth_mode: apikey}并且config.toml里preferred_auth_method apikey、forced_login_method api都配上了。5.6 网关监听地址和 Codex 不在同一台机器localhost:8787只在网关和 Codex 同机时有效。如果你把网关跑在另一台机器或容器里Codex 的base_url要改成网关的实际可达地址同时确认防火墙放行。这种情况在本地开发机上一般不会遇到但用 Docker 跑网关时要注意端口映射。6. 后续长期编码与 Agent 场景的通道选择链路跑通之后如果你只是偶尔用 Codex 桌面版做点小任务当前配置就够了。但如果你打算把 Codex 桌面版当成日常编码 Agent 长期用或者要接多个 Agent 客户端共享同一套模型通道那统一 Key 和通道的稳定性就变得重要。这时候可以看一下 TaoToken Coding Plan它面向的就是长期编码和 Agent 场景的通道管理。接入过程中如果遇到认证或协议层面的报错优先查 TaoToken 接入文档里面有针对 Responses API 和统一 Key 的说明。需要管理多个 Key 或查看用量去 TaoToken Console。如果你用的是 Claude Code 这类 Anthropic 协议的客户端可以参考 ClaudeCodeAnthropic 接入说明协议适配思路和这篇是相通的。最后留一个实操建议把config.toml、models.json、auth.json三个文件在本地做个备份换模型或换网关时直接替换比每次手改字段稳。模型 ID 建议单独记一个清单config 和 models.json 两边对照着改能省掉大部分大小写不一致的排查时间。