跳转到内容
opencodex

工作原理

Codex 使用 OpenAI Responses API。opencodex 接收通过 HTTP 与 Server-Sent Events 发送的 POST /v1/responses，也可选择在同一路径上启用 WebSocket 升级。它会把请求转换为 provider 的 wire 格式，再把响应转换回 Responses 事件，因此 Codex 无需知道自己正在与非 OpenAI 模型通信。

            ┌──────────────────────────── opencodex ────────────────────────────┐
            │                                                                     │
 Codex ──▶  │  parser ──▶ router ──▶ [vision] ──▶ adapter ──▶ provider           │  ──▶ Codex
 (/v1/      │     │          │          │            │           │                │   (SSE / WS)
  responses)│   OcxParsed  provider   describe    buildRequest  parseStream       │
            │   Request    +adapter   images       + fetch      AdapterEvent[]    │
            │                                          │           │              │
            │                                  [web-search loop]  bridge ─▶ SSE   │
            └─────────────────────────────────────────────────────────────────────┘

Sub-agent 模型选择

Section titled “Sub-agent 模型选择”

全新安装会通过 subagentModels 在 Codex 的 sub-agent 选择器中优先显示 gpt-5.5、GPT-5.6 Sol/Terra/Luna 三个模型和 gpt-5.4-mini。仪表盘可以从原生或已路由模型中重新排序或替换最多 五个条目。对于 v1 协作请求，可选的 injectionModel 与 injectionEffort 会添加开发者指令， 告诉 spawn_agent 应使用哪个模型和 reasoning effort；v2 请求保留 Codex 原生的多智能体指引。

生命周期

Section titled “生命周期”

  1. 解析 —— responses/parser.ts 使用 Zod schema(responses/schema.ts)校验请求, 并将其降级为内部的 OcxParsedRequest:系统提示词、一份规范化的消息列表 (文本、图像、工具调用、工具结果)、工具定义、生成选项,以及诸如 _webSearch(请求了托管的网络搜索) 和 _structuredOutput(设置了 JSON schema / JSON 对象的 text.format)等特性标志。图像会被保留为真正的内容部分 —— 绝不会被内联为 base64 文本。

  2. 路由 —— router.ts 按固定的优先级将请求的模型 id 映射到一个已配置的 provider： 显式的 provider/model → provider 的 defaultModel → 内置前缀模式 (claude-、gpt-、o1-/o3-/o4-、llama-/mixtral-/gemma-) → provider 的 models[] → defaultProvider 回退。参见 模型路由。

  3. 认证 —— 对于 oauth 类型的 provider,opencodex 会换入一个全新、自动刷新的 access token 作为 bearer key,从而让现有的 adapter 无需改动即可完成认证。

  4. Vision sidecar(可选) —— 如果已路由的模型被列在 provider.noVisionModels 中,且 请求携带了图像，opencodex 会通过你的 ChatGPT 登录凭据，使用已配置的 vision sidecar 描述 每张图像并将其替换为文本，让纯文本模型仍可对图像进行推理。 参见 Sidecar。

  5. 直通快速路径 —— 对于 Responses 直通 adapter（openai-responses 或 azure-openai）， opencodex 会保留 Responses body，只执行必要的路由与兼容性改写，然后直接转发 provider 响应， 不再转换为 AdapterEvent。

  6. 网络搜索 sidecar(可选) —— 如果 Codex 启用了托管的 web_search,但已路由的模型 并非 OpenAI,opencodex 会暴露一个合成的 web_search 函数工具,并在一个小型 agentic 循环中运行该模型，默认通过你的 ChatGPT 登录凭据调用 gpt-5.6-luna 执行真实搜索， 再将结果作为工具结果注入回去。

  7. 压缩（按需） —— Codex v1 会调用 POST /v1/responses/compact，v2 则在 Responses turn 中 加入 compaction_trigger。原生直通路由会把压缩请求发送到上游；已路由模型则在禁用工具的 情况下执行摘要，并返回 Codex 所需的替代历史记录格式。

  8. 适配 —— 否则,所选 adapter 的 buildRequest() 会以 provider 的原生格式生成上游 HTTP 请求 (URL、headers、body),由 opencodex 对其执行 fetch。

  9. 桥接 —— adapter 的 parseStream()(或 parseResponse())会产出内部的 AdapterEvent (text、reasoning、tool-call start/delta/end、done、error)。bridge.ts 会将该流转换回 Responses SSE 事件 —— response.output_text.delta、response.reasoning_summary_text.delta、 response.function_call_arguments.delta、response.completed 等等。启用 WebSocket 时，同样的 event payload 会作为 text frame 发送。

为什么是代理而不是 fork 一份 Codex?

Section titled “为什么是代理而不是 fork 一份 Codex?”

Codex 把 Responses API 硬编码在内部。通过在协议边界处进行翻译,opencodex 可以与 Codex 的 CLI、App 和 SDK 无改动地协作,能在 Codex 更新后继续工作,并让你能够按请求切换 provider 而无需改动 Codex 本身。这种翻译是双向且忠于 streaming 的: 推理摘要、MCP 工具命名空间、freeform(apply_patch)工具,以及 tool_search 发现 都能正确地往返。关于逐事件的映射,参见 架构参考。