3,561 prompts from top AI collections
← Back to Market
[170-carry/codex-tools] API 反代链路说明
ChatGPT API Leak/ChatGPT
30,019 characters
# API 反代链路说明 本文说明当前项目中的 API 反代实现。目标是让你从入口到上游返回,完整看懂这条链路现在是怎么工作的。 当前版本已经只保留一种反代方式: - 本地对外暴露 OpenAI 兼容接口 - 上游统一转到 Codex 的 `chatgpt.com/backend-api/codex/responses` - 不再保留旧的多模式反代 - Axum 请求体大小上限默认放宽到 `512 MiB` 实现参考了 `CLIProxyAPIPlus` 的 Codex executor 思路,但不是把它整仓搬进来,而是把核心方法收敛到本项目现有架构里。 ## 1. 当前反代的定位 ### 本地入口 - `GET /health` - `GET /v1/models` - `POST /v1/chat/completions` - `POST /v1/responses` - `POST /v1/messages` - `POST /v1/images/generations` - `POST /v1/images/edits` - `POST /v1/images/variations` ### 上游入口 - `POST https://chatgpt.com/backend-api/codex/responses` 也就是说: - 客户端以为自己在调用 OpenAI 风格的 `/v1/*` - 实际上本地代理会把请求转换为 Codex `responses` 协议 - 然后用账号池中的 ChatGPT/Codex 登录态去访问上游 ## 2. 为什么这样设计 之前的问题有两个: - 直接打 `api.openai.com/v1/*` 时,很多导入的账号本质上只有 ChatGPT/Codex 登录态,不一定有公共 OpenAI API scope 或 quota - 旧的 `conversation` 直通方式过于贴近历史接口,不适合作为稳定代理基座 现在的方案本质上是: - 下游维持 `/v1` 兼容,方便接各种现成客户端 - 上游切到 Codex 当前更合适的 `responses` 入口 - 中间由本地代理负责协议转换 ## 3. 整体时序 ```mermaid sequenceDiagram participant UI as "前端面板" participant Tauri as "Tauri Command" participant Local as "本地 Axum 代理" participant Store as "accounts.json / 账号池" participant Upstream as "chatgpt.com/backend-api/codex/responses" UI->>Tauri: start_api_proxy(port) Tauri->>Local: 启动 127.0.0.1:port Local->>Store: 读取账号池 Store-->>Local: 候选账号列表 Note over Local: 等待客户端请求 UI->>Local: POST /v1/chat/completions Local->>Local: 校验 API Key Local->>Local: OpenAI 请求转 Codex responses 请求 Local->>Store: 按排序取候选账号 Local->>Upstream: Bearer access_token + ChatGPT-Account-Id Upstream-->>Local: SSE 响应 Local->>Local: SSE 事件转 OpenAI 响应 Local-->>UI: /v1/chat/completions 响应 ``` ## 4. 入口与生命周期 ### 4.1 前端触发 前端入口在: - `src/components/ApiProxyPanel.tsx` - `src/hooks/useCodexController.ts` 用户在面板点击“启动 API 反代”后: 1. 前端读取端口输入框 2. 调用 Tauri 命令 `start_api_proxy` 3. 成功后显示: - `Base URL` - `API Key` - 当前命中的账号 - 最近错误 ### 4.2 Tauri 命令 Tauri 命令入口在: - `src-tauri/src/lib.rs` 相关命令: - `get_api_proxy_status` - `start_api_proxy` - `stop_api_proxy` ### 4.3 后端运行态 后端运行态在: - `src-tauri/src/state.rs` 这里维护: - 监听端口 - 当前代理 API Key - 运行任务句柄 - 当前命中的账号 ID/标签 - 最近一次错误 ## 5. 启动时到底做了什么 启动逻辑在: - `src-tauri/src/proxy_service.rs` `start_api_proxy_internal(...)` 做的事情是: 1. 检查当前是否已经有代理在运行 2. 从账号池加载可用账号 3. 绑定本地端口,默认 `8787` 4. 生成一个本地代理专用 `sk-...` API Key 5. 创建 `reqwest::Client` 6. 启动一个 `axum` HTTP 服务 7. 注册以下路由: - `/health` - `/v1/models` - `/v1/chat/completions` - `/v1/responses` - `/v1/messages` - `/v1/images/generations` - `/v1/images/edits` - `/v1/images/variations` - 对请求体启用 `512 MiB` 默认上限,可用 `CODEX_TOOLS_PROXY_MAX_BODY_MIB` 覆盖 8. 把运行状态写入全局 `AppState` ## 6. 本地暴露的接口 ### 6.1 `GET /health` 用途: - 用于判断本地代理服务是否活着 返回: ```json { "ok": true } ``` ### 6.2 `GET /v1/models` 用途: - 给兼容客户端一个模型列表 特点: - 这里不是实时问上游拿模型 - 目前返回本地静态模型列表,包含 GPT-6 Astra、GPT-6.1 Sol、GPT-6 Sol/Luna、GPT-5.6、GPT-5.5、GPT-5.4 和 GPT Image 2 - GPT-6 系列启用 Responses Lite;本代理使用与 GPT-6.1 Sol 本机 Codex 模型目录核对的 `0.159.0` 客户端标识。静态列表表示代理支持请求格式,实际可用性仍以上游账号返回为准 - 如果代理 Key 显式限制了模型,升级后需在该 Key 的允许模型中勾选 Sol/Luna;代理不会自动扩大已有 Key 的权限 - `gpt-6.1-sol` 兼容 `gpt6.1-sol`、`gpt-6-1-sol`、`gpt-6.1`、`gpt6.1`、`gpt-6-1` 及日期后缀;别名和日期版本受同一模型开关及 Key 权限控制,`gpt-6-sol` 不会自动映射为新版本 - `gpt-5.6`、`gpt5.6`、`gpt-5-6` 会映射到 `gpt-5.6-sol` - 目的是让大多数依赖 `/v1/models` 的客户端能正常初始化 推理与速度参数: - 推理强度兼容值:`none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max` - 推理速度:`auto`、`default`、`fast`、`flex` - `priority` 是 `fast` 的上游 wire 别名,`standard` 是 `default` 的兼容别名 - 请求未指定时默认使用 `xhigh` 与 `default`;需要快速等级时由客户端显式传 `fast` - `ultra` 属于 Codex 客户端的多代理编排模式;反代收到该兼容值时按实际推理 wire 值 `max` 发送 - GPT-5.6 的官方推理强度为 `none`、`low`、`medium`、`high`、`xhigh`、`max`;`minimal` 仅保留给旧模型兼容,GPT-5.6 请求会明确拒绝 - GPT-6 Sol/Luna 的 Codex 模型目录列出 `low`、`medium`、`high`、`xhigh`、`max`、`ultra`;代理把 `ultra` 映射到 `max`,拒绝 `none` / `minimal` - GPT-6.1 Sol 支持 `low`、`medium`、`high`、`xhigh`、`max`,代理兼容 `ultra` → `max`,在发送上游前拒绝 `none` / `minimal`。其标准短上下文 API 费用估算为输入 $2、缓存输入 $0.10、输出 $10 / 百万 Token,并重建旧费用缓存;不会改变 GPT-6 Sol 的历史费率。参见 [官方 GPT-6.1 Sol 说明](https://developers.openai.com/api/docs/models/gpt-6.1-sol) - 具体模型可用档位仍以上游能力为准;代理会拒绝未知值,不会静默降级 ### 6.3 `POST /v1/chat/completions` 用途: - 兼容绝大多数 OpenAI Chat Completions 客户端 行为: - 本地接收 OpenAI 风格请求 - 转为 Codex `responses` 请求 - 上游始终按 SSE 模式请求 - 如果下游请求 `stream: true`,本地再把上游 SSE 转成 OpenAI ChatCompletions SSE - 如果下游请求 `stream: false`,本地会先收完整个 SSE,再拼成普通 JSON 返回 ### 6.4 `POST /v1/responses` 用途: - 给直接走 OpenAI Responses 风格的客户端使用 行为: - GPT-6 Astra、Sol、Luna 与 GPT-5.6 请求会转换为 Responses Lite 结构;其他模型请求体只做必要归一化 - 上游仍然统一发到 Codex `responses` - `stream: true` 时近似透传 SSE - `stream: false` 时从 SSE 中提取 `response.completed`,返回标准 JSON - Codex 0.144 WebSocket v2 会收到 `426` 并按客户端内置逻辑回退到 HTTP,避免破坏 warmup 和 `previous_response_id` 状态 ### 6.5 `POST /v1/messages` 用途: - 给 Anthropic Messages 兼容客户端使用 行为: - 本地接收 Anthropic 风格请求 - 转为 Codex `responses` 请求 - 流式时转回 Anthropic SSE - 非流式时转回 Anthropic Message JSON - 认证推荐使用 `x-api-key: sk-...` - 需要带 `anthropic-version: 2023-06-01` 当前兼容字段: - `model` - `system` - `messages` - `max_tokens`(接受但不会转发:Codex 上游会拒绝 `max_output_tokens`,而 Anthropic 规范要求客户端必填该字段) - `stream` - `temperature` - `top_p` - `stop_sequences` - `tools` - `tool_choice` - `thinking.type = enabled` 其中 `2023-06-01` 是 Anthropic 当前公开的 API version,不是模型版本日期。Anthropic 官方版本文档目前仍把它作为 Messages API 的最新版本示例与版本历史项。 ### 6.6 `POST /v1/images/*` 用途: - 给 OpenAI 图片兼容客户端使用 行为: - ChatGPT 登录账号:`generations` 直接调用 Codex `/images/generations`,`edits` / `variations` 调用 `/images/edits`,顶层模型为 `gpt-image-2`,不再依赖已退役的 `gpt-5.5` 控制模型或 Responses Lite - API / Relay 账号:继续使用 Responses `image_generation` 工具,控制模型采用账号配置,图片工具模型仍为 `gpt-image-2` - `edits` 和 `variations` 会把上传图片转成原生图片引用或 Responses `input_image`;`mask` 延续“附加遮罩图片 + 提示词”的处理方式,并非原生 mask 参数 - 返回值使用 OpenAI 图片接口常见的 `b64_json` - ChatGPT 原生接口返回完整 JSON;下游 `stream:true` 会收到一条 `image_generation.completed` 和 `[DONE]`,不提供 `partial_images` 中间预览。Relay 保留原有流式行为 - ChatGPT 路径支持 `size`、`quality`、`background`,输出格式目前只接受省略或 `png`;不支持 `output_compression` / `compression`,`input_fidelity` 只接受省略或 `high`。其他格式可使用支持相应参数的 Relay 账号 - `n` 仍由代理逐张请求;账号刷新、失败切换、图片模型权限与用量统计沿用现有逻辑 ChatGPT 原生传输依据 [官方 Codex ImagesClient 实现](https://github.com/openai/codex/blob/8c076942cb70fba8e5c4732c23f1faabc4aed484/codex-rs/codex-api/src/endpoint/images.rs)及其[请求类型](https://github.com/openai/codex/blob/8c076942cb70fba8e5c4732c23f1faabc4aed484/codex-rs/codex-api/src/images.rs)。 ## 7. 鉴权方式 本地代理有自己的一层鉴权,不直接暴露给任意本地程序。 支持两种传法: - `X-API-Key: sk-...` - `x-api-key: sk-...` - `Authorization: Bearer sk-...` 如果调用 `/v1/messages`,还需要带: - `anthropic-version: 2023-06-01` 校验逻辑: - 只认启动代理时生成的那一个本地 `API Key` - 这层 key 只是本地代理的门锁 - 它不是上游 OpenAI API Key - 它也不是账号池里真实的 `access_token` ## 8. 账号池是怎么参与反代的 账号来源: - 应用数据目录下的 `accounts.json` 数据结构定义在: - `src-tauri/src/models.rs` 每个账号核心字段有: - `label` - `account_id` - `auth_json` - `usage` - `plan_type` 代理真正需要的认证信息来自 `extract_auth(...)`: - `access_token` - `account_id` - 可选 `plan_type` ## 9. 账号排序与挑选规则 候选账号在每次请求时重新读取,并重新排序,不做固定缓存。代理运行中新增、删除、禁用账号后,不需要关闭代理进程,下一次请求就会按最新账号池选择。 排序规则: 1. 优先 `free` 账号 2. 再比较 `1week` 剩余额度 3. 再比较 `5h` 剩余额度 4. 最后按标签名排序 也就是: - `free` 计划会优先于其他计划 - 在同一类计划中,优先挑“更有余量”的账号 对应逻辑: - `load_proxy_candidates(...)` - `compare_proxy_candidates(...)` ### 9.1 逐个模式与 session affinity 负载均衡选择“逐个”时,代理会优先复用当前会话已经命中的账号。 会话标识来源: - 请求头:`x-codex-tools-session` - 请求头:`x-codex-session-id` - 请求头:`session_id` - 请求头:`session-id` - 请求头:`x-client-request-id` - 请求头:`openai-conversation-id` - 请求体:`sessionId` - 请求体:`session_id` - 请求体:`conversationId` - 请求体:`conversation_id` - 请求体:`threadId` - 请求体:`thread_id` - 请求体:`previous_response_id` - 请求体:`previousResponseId` 规则: - 同一个会话继续用同一个账号,直到该账号达到 5h 阈值或被上游拒绝 - 不同会话各自绑定账号,互不抢全局当前账号 - 没有会话标识的旧客户端继续走原来的全局逐个模式 - 绑定只保存在内存里,停止代理后会清空 ## 10. 请求发到上游时带了什么 真正向上游发请求时,目标是: - `https://chatgpt.com/backend-api/codex/responses` 关键请求头: - `Authorization: Bearer <candidate.access_token>` - `ChatGPT-Account-Id: <candidate.account_id>` - `Originator: codex_cli_rs` - `Version: 0.144.0` - `Session_id: <uuid>` - `User-Agent: codex_cli_rs/0.144.0` - `Accept: text/event-stream` - `Content-Type: application/json` 这里有几个关键点: - 不是发到 `api.openai.com/v1/*` - 不是发到旧的 `conversation` - 默认模拟的是 Codex CLI 风格头 - 上游固定按 SSE 返回 ## 11. `chat/completions` 到 Codex `responses` 的转换 这是当前链路最核心的一层。 ### 11.1 固定注入字段 本地会补这些字段: - `stream: true` - `store: false` - `reasoning.effort: xhigh` - `reasoning.summary: auto` - `include: ["reasoning.encrypted_content"]` - `service_tier: default`(下游显式写 `fast` 时才映射为上游 `priority`) GPT-5.6 Sol/Terra/Luna 会额外使用 Responses Lite 契约: - 请求头补 `x-openai-internal-codex-responses-lite: true` - 顶层 `tools` 移到 `input` 首项 `additional_tools` - 非空 `instructions` 移到 developer message - 顶层 `tools` 与 `instructions` 不再发送 - `parallel_tool_calls: false` - `reasoning.context: all_turns` 这里 `store: false` 很关键。 实际验证里,上游 `backend-api/codex/responses` 明确要求: - 没带 `store: false` 会报错 ### 11.2 message 角色映射 OpenAI 风格消息会被转换为 Codex `input` 数组。 角色映射: - `system -> developer` - `developer -> developer` - `user -> user` - `assistant -> assistant` - `tool -> function_call_output` ### 11.3 content 映射 文本: - `text -> input_text` 或 `output_text` 图片: - `image_url -> input_image` 文件: - `file -> input_file` ### 11.4 tool 调用映射 OpenAI 里的: - `assistant.tool_calls` - `tool` 消息 会被拆成 Codex 里的: - `function_call` - `function_call_output` ### 11.5 结构化输出映射 如果下游传了: - `response_format` - `text.verbosity` 本地会转换到上游的: - `text.format` - `text.verbosity` ## 12. `/v1/responses` 的归一化 如果下游直接请求 `/v1/responses`,本地不会像 `chat/completions` 那样大幅转换,只做必要补丁: - 强制 `stream: true` - 强制 `store: false` - 缺失时补 `instructions` - 缺失时补 `parallel_tool_calls` - 缺失时补 `reasoning.effort = xhigh` - 缺失时补 `reasoning.summary = auto` - 缺失时补快速档,向上游发送 `service_tier = priority` - 确保 `include` 里有 `reasoning.encrypted_content` - 丢弃上游不接受的 `metadata` 字段,避免 Cursor 等客户端报 `Unsupported parameter: metadata` - GPT-5.6 请求继续转换为 Responses Lite 契约 ## 13. 上游 SSE 是怎么转回 OpenAI 的 ### 13.1 `POST /v1/responses` 如果下游本来就是 Responses 客户端: - `stream: true` 时,基本按 SSE 透回去 - `stream: false` 时,从完整 SSE 中提取 `response.completed` ### 13.2 `POST /v1/chat/completions` 这是转换最多的地方。 上游返回的是 Codex SSE 事件流,本地会把关键事件转成 OpenAI ChatCompletions SSE。 #### 事件映射 | 上游事件 | 本地输出 | | --- | --- | | `response.created` | 初始化状态,不立即输出 | | `response.reasoning_summary_text.delta` | `delta.reasoning_content` | | `response.reasoning_summary_text.done` | 补一个换行分隔 | | `response.output_text.delta` | `delta.content` | | `response.output_item.added` with `function_call` | `delta.tool_calls` 开始事件 | | `response.function_call_arguments.delta` | `delta.tool_calls[].function.arguments` 增量 | | `response.function_call_arguments.done` | 参数结束兜底 | | `response.output_item.done` with `function_call` | 工具调用完成兜底 | | `response.completed` | `finish_reason` + `[DONE]` | #### 非流式时怎么处理 如果下游 `stream: false`: 1. 本地仍然向上游请求 SSE 2. 读完整个 SSE 3. 找到 `response.completed` 4. 从 `response.output` 里提取: - assistant 文本 - reasoning summary - tool calls - usage 5. 拼成一个普通的 OpenAI ChatCompletions JSON ## 14. 失败重试与运行中热切换 每次请求会按候选账号顺序尝试。 对单个账号的流程: 1. 先用当前 token 发上游请求 2. 如果命中“疑似 token 过期/失效”信号,则先 refresh 3. refresh 成功后重试这个账号一次 4. 如果仍失败,再判断是否属于可切下一个账号的错误 这条链路就是 runtime rotation: - 客户端只需要一直请求同一个 `Base URL` - 不需要改写 `~/.codex/auth.json` - 不需要关闭 Codex App/CLI - 不需要重启反代服务 - 代理会在请求发到上游前选择账号,并在收到可轮换错误时换到下一个账号 - 流式请求在开始向下游输出前完成账号选择;已经开始输出的同一个流不会中途换账号 如果你要做 wrapper 或 app bind,推荐方式是让 Codex App/CLI 指向本工具的 `/v1` 反代,并为每个会话透传稳定的 session key。这样官方 App/CLI 进程可以保持打开,账号轮换发生在本地代理层。 ### 14.1 wrapper 接入 wrapper 的职责很简单: 1. 确保本工具 API 反代已经启动 2. 把 Codex 的 provider/base_url 指到本工具显示的 `Base URL` 3. 把本工具显示的 `API Key` 作为下游 key 4. 为同一个 Codex 会话透传稳定 session key 5. 启动官方 Codex CLI/App,不接管官方 `codex` 二进制 ### 14.2 app bind 接入 app bind 不需要 patch 官方 App 文件。 面板已经提供按钮: 1. 先启动 API 反代 2. 点击“切到本机反代” 3. 工具会备份当前 `~/.codex/config.toml` 和 `~/.codex/auth.json` 4. 工具会把 `openai_base_url` 写成当前本机 `Base URL` 5. 工具会把当前反代 `API Key` 写入 `auth.json` 6. 工具会写入独立的 `codex-tools-models.json`,并通过 `model_catalog_json` 指向它 7. 重启 Codex App/CLI,使模型选择器加载新目录;已经绑定时可直接点击“同步模型目录” 8. 点击“恢复正常地址”时,还原到绑定前的配置和认证文件,包括原先的自定义模型目录配置 Codex 的 API Key 接入模式在自定义 `openai_base_url` 下可能跳过远端模型发现,即使 `/v1/models` 包含 GPT-6.1 Sol 也不会显示在选择器中。独立目录保留模型的完整能力和提示词,并按全局模型开关与绑定 Key 的白名单筛选,不覆盖官方 `models_cache.json`。启动本机代理、保存模型开关或修改 Key 权限时会同步已有绑定;目录没有变化时不重复写盘。Key 被禁用或撤销时不展示可选模型,也不扩大旧 Key 的白名单。 本功能使用 Codex 的 [`model_catalog_json` 配置](https://developers.openai.com/codex/config-reference/)。可用 `python3 scripts/check-codex-model-discovery.py --codex /path/to/codex` 对实际客户端做隔离验证;只使用临时目录、测试 Key 和回环接口,不发起推理请求。 这个方式把“账号池 + token refresh + 运行中轮换”留在 codex-tools,把官方 App/CLI 只当普通 OpenAI/Responses 客户端。 ### 14.3 会触发 refresh 的情况 - `401` - 错误体包含: - `token expired` - `jwt expired` - `invalid token` - `session expired` - `login required` ### 14.4 refresh 成功后还会做什么 刷新成功后会把新的认证状态写回两处: - 账号池里的 `accounts.json` - 如果它正好是当前激活账号,也会回写 `~/.codex/auth.json` ## 15. 失败分类 如果某个账号失败,本地会尽量分类,而不是只报一个泛泛的 `429`。 当前分类: - `额度用完` - `频率限制` - `模型受限` - `鉴权失败` - `权限不足` 当所有候选账号都失败时,会返回类似: - 哪一类失败有多少个 - 再附一个示例原因 这样你能更快判断是: - 账号整体没额度 - 当前模型不支持 - 还是登录态坏了 ## 16. 最近错误和当前账号是怎么展示的 运行中的状态会保存在: - `ApiProxyRuntimeSnapshot` 主要字段: - `active_account_id` - `active_account_label` - `sequential_session_affinity` - `last_error` 前端轮询这些状态,所以面板上能看到: - 当前命中的账号 - 最近一次错误 ## 17. Cloudflared 和反代的关系 Cloudflared 不是第二套代理逻辑,它只是把当前本地代理继续暴露到公网。 关系是: 1. 本地 API 反代先启动 2. Cloudflared 再把这个本地端口转出去 所以链路是: ```text 客户端 -> cloudflared 公网地址 -> 本地 127.0.0.1:8787/v1/* -> Codex 上游 ``` Cloudflared 不参与: - 请求协议转换 - 账号挑选 - token refresh - SSE 到 OpenAI 的映射 它只负责公网入口。 ## 18. 远程压缩 `responses/compact` 当前实现支持: - 入站:`POST /v1/responses/compact` - ChatGPT 上游:`{chatgpt}/backend-api/codex/responses/compact` - Relay 上游:`{api_base}/responses/compact` 行为要点: - 上游 compact 走 unary JSON(`Accept: application/json`),不走 SSE - 客户端 `stream: true` 时,把上游 JSON 合成最小 Responses SSE(`output_item.done` + `response.completed`) - `remote_compaction_v2` 的 `compaction_trigger` 保持普通 `/v1/responses` 流式协议,不降级到 unary compact - Responses(HTTP/WebSocket)和 compact 按窄白名单转发 turn-state、beta、turn metadata、window 与 trace 上下文;快速 SSE 响应也保留上游返回的状态头 - 当入站已有 turn-state 且上游等待超过 10 秒时,发送可被客户端消费但忽略的 `response.in_progress` SSE 心跳;没有可安全回显的状态头时等待上游完整响应后再提交响应头 - 心跳已发出后的失败改为流内 `response.failed`,并尽量保留上游 `code/type/message` 等错误字段 - compact body 与 Codex `CompactionInput` 对齐,只保留 `model/input/instructions/tools/parallel_tool_calls/reasoning/service_tier/prompt_cache_key/text`,并统一规范化 service tier - ChatGPT 账号上 GPT-5.6 `reasoning.effort=max` 会降级为 `xhigh` - JSON 请求体支持 gzip、标准 zlib-wrapped deflate(兼容 raw deflate)与 zstd;解压在阻塞线程池执行,解压后仍受请求体上限约束 - Relay 返回 `404/405/501` 时视为不支持 compact,并继续尝试后续候选账号 ## 19. 当前的边界与限制 当前版本不是“完整 OpenAI API 网关”,而是“OpenAI 兼容的 Codex 代理”。 明确限制: - 只支持: - `GET /v1/models` - `POST /v1/chat/completions` - `POST /v1/responses` - `POST /v1/responses/compact` - `GET /v1/responses`(旧版 WebSocket;v2 返回 `426` 触发 HTTP 回退) - `POST /v1/messages` - `POST /v1/images/generations` - `POST /v1/images/edits` - `POST /v1/images/variations` - 其他 `/v1/*` 路径目前直接返回不支持 - 模型列表是本地静态表,不是实时探测 - `/v1/responses` 的流式是近似透传,不额外做深层语义改写 - GPT-5.6 Responses Lite 不接收 hosted `web_search`、`web_search_preview`、`image_generation` 工具;这类请求会明确拒绝,客户端扩展工具仍会透传 - 远程图片 URL 会替换为占位文本,Lite 请求不会发送图片 `detail` - 核心目标是把最常用的聊天链路稳定打通 ## 20. 代码位置索引 如果你要继续看代码,优先看这些文件: - 启动、路由、转换、账号轮换: - `src-tauri/src/proxy_service.rs` - Tauri 命令: - `src-tauri/src/lib.rs` - 运行态: - `src-tauri/src/state.rs` - 账号结构: - `src-tauri/src/models.rs` - 前端面板: - `src/components/ApiProxyPanel.tsx` - 前端控制器: - `src/hooks/useCodexController.ts` ## 21. 一个完整请求示例 以这个调用为例: ```bash curl http://127.0.0.1:8787/v1/chat/completions \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer sk-xxxx' \ -d '{ "model": "gpt-5.6-sol", "reasoning_effort": "xhigh", "service_tier": "fast", "stream": false, "messages": [ { "role": "user", "content": "1+1 等于几?只回答结果。" } ] }' ``` 内部实际流程是: 1. 本地校验 `sk-xxxx` 2. 找到可用账号列表 3. 把请求改写成 Codex `responses` 请求 4. 强制补 `store: false` 5. 带着账号 `access_token + account_id` 去打上游 6. 上游返回 SSE 7. 本地抽取 `response.completed` 8. 转成 OpenAI ChatCompletions JSON 9. 返回类似: ```json { "object": "chat.completion", "choices": [ { "message": { "role": "assistant", "content": "2" }, "finish_reason": "stop" } ] } ``` ## 22. 调试方式 ### 看服务是否起来 ```bash curl http://127.0.0.1:8787/health ``` ### 看模型列表 ```bash npm run test:codex-login-proxy -- --api-key 你的sk ``` ### 看聊天结果 ```bash npm run test:codex-login-proxy -- --api-key 你的sk --prompt '1+1 等于几?只回答结果。' ``` ### 保留原始响应 ```bash npm run test:codex-login-proxy -- --api-key 你的sk --prompt '1+1 等于几?只回答结果。' --raw ``` 这会把: - 响应头 - 原始 body - 请求元数据 都落到本地文件,方便继续排查。 ## 23. 通过 CC Switch 接入 Codex 如果你想把本工具作为“账号池 + OpenAI 兼容反代”,再由 [CC Switch](https://github.com/farion1231/cc-switch) 来统一管理 Codex provider,这条链路是支持的。 原因很简单: - 本工具下游暴露的是 OpenAI 兼容 `/v1` 接口 - CC Switch 给 Codex 写入的自定义 provider 也是 `OPENAI_API_KEY + base_url + wire_api = "responses"` 这套配置 也就是说: - `codex-tools -> CC Switch -> Codex` - 协议层是能对上的 ### 23.1 适用范围 当前这套接入方式,适用于: - CC Switch 中的 **Codex 自定义 provider** - 能按 OpenAI `/v1` 或 Anthropic `/v1/messages` 子集发请求的客户端 不适用于: - 把本工具当成完整 Claude 官方网关 原因是本工具当前只提供这些出口: - `GET /v1/models` - `POST /v1/chat/completions` - `POST /v1/responses` - `GET /v1/responses`(旧版 WebSocket;v2 使用 HTTP 回退) - `POST /v1/messages` - `POST /v1/images/generations` - `POST /v1/images/edits` - `POST /v1/images/variations` 其中 `/v1/messages` 是 Anthropic Messages 兼容子集,最终仍会转到 Codex `responses` 上游。 ### 23.2 推荐配置 在 CC Switch 中新增一个 Codex 自定义 provider,可按下面填写。 `auth.json`: ```json { "OPENAI_API_KEY": "这里填 codex-tools 面板里生成的 sk-..." } ``` `config.toml`: ```toml model_provider = "codex_tools" model = "gpt-5.6-sol" model_reasoning_effort = "xhigh" service_tier = "default" disable_response_storage = true [model_providers.codex_tools] name = "codex_tools" base_url = "http://127.0.0.1:8787/v1" wire_api = "responses" requires_openai_auth = true ``` 如果你不是本机直连,而是通过 cloudflared 公网域名接入,把 `base_url` 改成: ```toml base_url = "https://你的公网域名/v1" ``` ### 23.3 三个最容易配错的点 1. `base_url` 要填到 `/v1` 为止 - 对:`http://127.0.0.1:8787/v1` - 错:`http://127.0.0.1:8787` - 错:`http://127.0.0.1:8787/v1/responses` 2. `OPENAI_API_KEY` 要填本工具生成的代理 key - 也就是面板显示的 `sk-...` - 不是 OpenAI 官方 API Key - 也不是账号池里真实的 `access_token` 3. `wire_api` 要用 `responses` - 因为本工具上游统一走的是 Codex `responses` - CC Switch 的 Codex 自定义 provider 也应使用 `responses` ### 23.4 接不通时先排查什么 先直接测本工具自己的出口: ```bash curl http://127.0.0.1:8787/health curl http://127.0.0.1:8787/v1/models -H 'Authorization: Bearer 你的sk' curl http://127.0.0.1:8787/v1/messages \ -H 'x-api-key: 你的sk' \ -H 'anthropic-version: 2023-06-01' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5.6-sol", "max_tokens": 256, "messages": [{"role": "user", "content": "Say hi in one sentence."}] }' ``` 如果这些请求都正常: - 说明 `codex-tools` 代理本身已经起来了 - 后续问题通常就在 CC Switch 或客户端 provider 配置 如果本机地址可以通,但外网地址不通,优先检查: - cloudflared 是否真的映射到了当前反代端口 - `base_url` 是否写成了公网域名加 `/v1` - OpenAI/Responses 客户端是否带上了 `Authorization: Bearer sk-...` - Anthropic Messages 客户端是否带上了 `x-api-key: sk-...` 和 `anthropic-version: 2023-06-01` ### 23.5 关于 Claude provider 如果你在 CC Switch 里配置的是 Claude provider,而不是 Codex provider,需要注意: - 本工具现在可以直接接收 Anthropic Messages 兼容请求:`POST /v1/messages` - 认证头按 Anthropic 风格填 `x-api-key: sk-...` - 版本头填 `anthropic-version: 2023-06-01` - 这仍然是兼容转换出口,不是完整 Claude 官方网关 - 上游还是 Codex `responses`,不是 Anthropic 官方模型服务 如果某个客户端的 Claude provider 需要填写 base URL: - 客户端会自动拼 `/v1/messages` 时,base URL 填到 `http://127.0.0.1:8787` - 客户端要求完整接口地址时,填 `http://127.0.0.1:8787/v1/messages` - 如果通过公网域名接入,把主机名换成 cloudflared 或远程反代域名 ## 24. 一句话总结 当前反代的本质是: - 本地对客户端说“我是 OpenAI `/v1`,也能接 Anthropic `/v1/messages`” - 对上游实际上说“我是 Codex CLI,在调用 `backend-api/codex/responses`” - 中间靠账号池、协议转换、SSE 事件转换,把两边接起来
Download .txt