9Router 集成 OpenAI Codex CLI：智能路由、模型直连与完整故障排查指南-平芜编程栈

9Router 集成 OpenAI Codex CLI：智能路由、模型直连与完整故障排查指南

【免费下载链接】9routerUnlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40+ providers. Auto-fallback, RTK -40% tokens, never hit limits.项目地址: https://gitcode.com/GitHub_Trending/9r/9router

本文以 9Router 开源仓库中 Codex CLI 集成文档（日文版、英文版、中文版）为主体，讲解如何将 OpenAI Codex CLI 接入 9Router 的智能路由系统：配置环境变量、选择cx/模型、用配置文件固化连接，并结合仓库内 Codex 执行器与提供商注册表的源码，说明请求在 9Router 内部如何被规范化、鉴权与容错。读完本文，你将能够在本地或云端把codex命令稳定接入 9Router，并具备独立排查认证、连接、模型不可用等常见故障的能力。

前置条件

在开始之前，请确认满足以下三点：

已安装 OpenAI Codex CLI：codex命令可正常使用。
9Router 已就绪：本地运行中，或已配置好云端 endpoint。本地启动后仪表盘默认地址为http://localhost:20128（见快速开始文档），启动命令为9router。
拥有 9Router API Key：从 9Router 仪表盘获取，后续作为OPENAI_API_KEY使用。

集成原理：为什么 Codex 能直接指向 9Router

Codex CLI 通过 OpenAI 兼容的 Responses API 与后端通信。9Router 的核心入口正是面向这类 OpenAI 兼容客户端的网关：它接收OPENAI_BASE_URL指向的请求，再由内部的 Codex 执行器（open-sse/executors/codex.js）完成协议适配与上游转发。

从源码看，Codex 提供商在注册表中的定义（open-sse/providers/registry/codex.js）包含几个关键事实：

别名cx：所有 Codex 模型统一以cx/前缀暴露给客户端；
传输格式openai-responses：执行器直接消费 Responses API 格式的请求体；
forceStream: true：上游强制流式输出，执行器在 transformRequest 中会把body.stream固定为true；
store: false：请求默认不持久化，同时执行器会剥离rs_/fc_/resp_/msg_前缀的服务端条目引用，避免store=false时出现 404。

因此，只要把 Codex CLI 的 Base URL 指向 9Router，并传入 9Router 签发的 API Key，所有请求就会进入 9Router 的路由、配额与容错体系。

一、配置环境变量（三步完成）

第 1 步：写入 Shell 配置文件

在 shell 配置文件（~/.bashrc、~/.zshrc或~/.bash_profile）中追加：

# 9Router 的 Base URL export OPENAI_BASE_URL="http://localhost:20128/v1" # 来自 9Router 仪表盘的 API Key export OPENAI_API_KEY="your-9router-api-key"

其中http://localhost:20128是 9Router 本地服务的默认端口，/v1是 OpenAI 兼容 API 的路径前缀。仓库中多个 CLU 工具卡片（如 src/app/(dashboard)/dashboard/cli-tools/components/MitmServerCard.js/dashboard/cli-tools/components/MitmServerCard.js)）都以http://localhost:20128作为默认本地网关地址，与此处一致。

第 2 步：重新加载 Shell 配置

source ~/.zshrc # 或 ~/.bashrc

第 3 步：验证配置

echo $OPENAI_BASE_URL echo $OPENAI_API_KEY

确认两行输出分别为上述 Base URL 与你的 API Key 即配置成功。

二、可用模型：`cx/`模型族

9Router 提供的 Codex 模型统一以cx/前缀标识，集成文档中给出的两个经典模型如下：

模型 ID	说明
`cx/gpt-5.2-codex`	GPT-5.2 Codex - 最新版本
`cx/gpt-5.1-codex-max`	GPT-5.1 Codex Max - 扩展上下文

需要注意的是，模型目录会随上游迭代持续演进。当前仓库的 Codex 注册表（open-sse/providers/registry/codex.js）已登记更新一代的模型（如gpt-5.6-sol、gpt-5.5、gpt-5.4-mini等），并会为每个 LLM 模型自动派生一个-review后缀的 Review 变体（对应独立配额族，逻辑见 open-sse/providers/models/helpers.js）。同时注册表声明了thinkingConfig（auto/none/low/medium/high），执行器会按模型后缀解析思考级别。因此，实践中的准确模型清单请以 9Router 仪表盘当前展示为准；文档与 README 中出现的cx/gpt-5.2-codex、cx/gpt-5.1-codex-max仍可作通用示例。

此外，9Router 会通过 getModelUpstreamId 将cx/虚拟模型映射为上游 Codex 真实模型 ID，客户端无需关心映射细节。

三、使用示例

基础用法

# 使用 GPT-5.2 Codex codex --model cx/gpt-5.2-codex "Write a function to sort an array" # 使用 GPT-5.1 Codex Max codex --model cx/gpt-5.1-codex-max "Explain this complex algorithm"

代码生成

codex --model cx/gpt-5.2-codex "Create a REST API endpoint for user authentication"

代码解释

codex --model cx/gpt-5.1-codex-max "Explain what this code does: $(cat myfile.js)"

执行器会在请求进入上游前完成一系列规范化（详见后文"请求流转"一节），因此这些命令无需关心 9Router 内部如何与 ChatGPT/OpenAI 账号鉴权，直接透传使用即可。

四、使用配置文件固化连接

不想每次设置环境变量，也可以在 Codex CLI 的配置文件中固化连接。创建或编辑~/.codex/config.json：

{ "baseUrl": "http://localhost:20128/v1", "apiKey": "your-9router-api-key", "defaultModel": "cx/gpt-5.2-codex" }

配置完成后，直接运行codex即默认使用cx/gpt-5.2-codex，无需再通过--model指定。

五、故障排查

认证错误

遇到认证错误（如 401/token 类报错）时：

在 9Router 仪表盘中确认 API Key 正确；
检查OPENAI_API_KEY环境变量是否已设置且生效；
确认 API Key 未过期。

从源码看，9Router 对 Codex 账号凭证有完整生命周期管理：执行器通过 refreshCredentials 调用 OAuth 凭证刷新逻辑（open-sse/services/oauthCredentialManager.js），并在检测到需要刷新时自动刷新。同时 buildHeaders 会携带ChatGPT-Account-ID头（取自workspaceId/chatgptAccountId/accountId），确保多账号场景下请求不会错误绑定到其他 OpenAI 账号。若你手动配置的 Key 失效，优先在仪表盘重新生成并更新配置。

连接问题

遇到连接错误时：

确认 9Router 正在运行：curl http://localhost:20128/health；
检查环境变量设置是否正确；
确保防火墙没有阻止 20128 端口。

模型不可用

出现 "model not available" 错误时：

确认模型名与 9Router 配置一致（包括cx/前缀与拼写）；
检查 9Router 仪表盘中 OpenAI/Codex 提供商连接是否激活；
确认所连接的提供商套餐中包含该模型。

值得一提的容错细节：执行器内置了对 200 状态码 SSE 流内错误模式的识别（execute 中的重试循环）。当上游返回server_is_overloaded、service_unavailable_error等瞬时过载信号时，9Router 会按 503 重试配置自动重试；遇到selected model is at capacity/model_at_capacity等容量信号时，则会转换为service_unavailable响应以便上层账号回退机制接管。这也解释了为何有时请求看似失败却能自动恢复——这是 9Router 的预期行为。

六、使用云端 Endpoint

不使用本地 localhost 时，可将 Base URL 指向 9Router 云端：

export OPENAI_BASE_URL="https://9router.com"

注意：使用云端时，需确认已在 9Router 云端仪表盘中配置好 API Key，其余配置（模型前缀、使用方式）与本地一致。

七、高级配置

自定义超时

export OPENAI_TIMEOUT=60 # 秒

Debug 模式

启用 debug 模式查看详细的请求/响应日志：

export CODEX_DEBUG=true codex --model cx/gpt-5.2-codex "Your prompt"

八、深入原理：一次 Codex 请求在 9Router 中的流转

结合 open-sse/executors/codex.js 的transformRequest实现，一次请求在进入上游前会依次经历以下处理，理解这些有助于定位疑难问题：

输入规范化：将字符串 input 转为 Responses API 要求的数组格式；空 input 会被填充占位消息（Codex API 拒绝空输入）；
角色转换：role=system消息转换为role=developer，使其保持在可缓存的提示前缀中；
工具归一化：将 Chat-Completions 形状的 function 工具扁平化为 Responses 格式，过滤不支持的 hosted 工具类型，并删除指向未知函数的tool_choice（对应测试见 tests/unit/codex-tool-normalization.test.js）；
会话与缓存：通过 resolveSessionId 解析稳定的session_id并注入prompt_cache_key，为 Codex 提示缓存提供稳定的缓存键；
指令注入：请求未携带instructions时，自动注入仓库内置的 Codex 默认指令（open-sse/config/codexInstructions.js），其中包含沙箱模式、审批策略、代码编辑约束等完整行为规范；
思考级别映射：按reasoning.effort或模型后缀解析none/low/medium/high/xhigh级别（max会归一化为xhigh），并为思考模型附加include: ["reasoning.encrypted_content"]；
参数裁剪：删除 Codex 不支持的temperature、top_p、max_tokens、seed、metadata等参数，最终按 Responses API 字段白名单（model、input、instructions、tools、tool_choice、stream、store、reasoning、service_tier等）过滤，避免触发上游routing_unsupported错误；
强制流式与不持久化：stream=true、store=false被固定写入；
远程图片预取：若输入包含image_url，执行器会先行抓取并以 base64 data URI 内联（上游 Codex 后端无法直接拉取远程图片），相关行为由 tests/unit/codex-image-fetch.test.js 覆盖。

另外，当上游返回 429 且错误类型为usage_limit_reached时，执行器的 parseError 会解析resets_at或resets_in_seconds精确计算配额重置时间，供配额跟踪与自动切换使用——这正是 9Router"永不触顶"体验的底层机制之一。

结语

通过OPENAI_BASE_URL与OPENAI_API_KEY两个环境变量（或~/.codex/config.json），即可将 Codex CLI 无缝接入 9Router 的智能路由体系。结合仓库源码可以看到，9Router 在协议适配（Responses 格式规范化）、凭证管理（OAuth 刷新与账号绑定）、容错（SSE 过载重试与容量回退）和缓存（prompt cache 会话键）四个层面为 Codex 客户端提供了完整的网关能力。若需进一步了解 9Router 的安装与更多集成方式，可参考快速开始与其他工具集成文档。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

9Router 集成 OpenAI Codex CLI：智能路由、模型直连与完整故障排查指南