Release Notes
中文
Codex 中转和 ChatGPT 原生体验
- Codex 本地代理现在会默认归一化请求体
Content-Encoding（zstd、gzip / x-gzip、br、deflate），在路由、model override 和转发前得到普通 JSON，并移除过期的 Content-Encoding / Content-Length；极少数需要原始压缩体的中转可用 CODEX_HELPER_REQUEST_BODY_ENCODING=passthrough 启动 helper 作为逃生口。
- 当请求缺少
session_id / session-id / conversation_id / thread-id 这类强 session header 时，helper 会把已解码 JSON 的 prompt_cache_key 作为 session affinity 兜底，让 /responses 与 /responses/compact 在多中转路由下保持 sub2api 风格粘性。
- 新增 Codex client preset 体系，用来处理“Codex 客户端想要官方/ChatGPT 形态，但模型流量要走中转”的场景。用户侧推荐使用
[codex.client_patch].preset = "..." 和 codex-helper switch on --preset ...；旧配置 mode = "..." 和 CLI --mode ... 仍兼容读取，但 helper 保存/生成配置时统一写 preset。
chatgpt-bridge 适合已经在官方 Codex 登录 ChatGPT 的用户。Codex 仍看到 ChatGPT 登录态，桌面端和手机端账号能力可以继续按官方路径判断；模型请求由 codex-helper 路由到你的 relay。imagegen-bridge 适合 relay 不支持 official provider 身份，但你想让 Codex 暴露 hosted image_generation 的场景。它会写入 {} auth facade，真实上游密钥仍来自 codex-helper 配置。official-relay 适合能转发 OpenAI Responses 语义的中转，尤其是支持 /responses/compact 的 sub2api 或类似服务。它让 Codex 尝试 remote compaction v1。official-imagegen 适合背后确实是官方订阅账号、同时支持 /responses/compact 和 hosted image generation 的 relay。它同时给 Codex official provider 身份和 imagegen facade。- 旧 preset 名称
official-relay-bridge / official-imagegen-bridge 仍作为 alias 接受，但不再作为推荐写法；未发布过的旧 official-ws-* 组合已删除。
- 新增独立传输开关
responses_websocket = true / --responses-websocket。它不是新的 preset，只允许搭配 official-relay 或 official-imagegen，启用后 helper 会写入 supports_websockets = true 并代理 Responses WebSocket v2。
- bridge 模式不会把 Codex 的 ChatGPT token 透传给没有 helper 侧密钥的第三方 relay。上游应配置自己的
auth_token_env、auth_token、api_key_env 或 api_key。
中转能力诊断
- 新增 Codex relay 能力诊断，可从 TUI Settings、admin API 或 CLI 运行。常用 CLI：
codex-helper codex relay-capabilities --preset official-imagegen --model gpt-5.5。
- 诊断会检查 relay 的
/models、/responses、/responses/compact，然后给出更适合的 preset。它不会自动切换配置。
- 诊断和 live smoke 支持 provider/endpoint 定向：CLI 可用
--provider <ID>、--endpoint <ID>，便于直接验证某个中转，而不是只测当前路由首选项。
- 如果 relay 返回 OpenAI 风格的
/models（data: [...]），codex-helper 会翻译成 Codex 需要的 models: [...] catalog，避免 Codex 因模型 metadata 形态不对而看不到 image/search/apply_patch 等能力。
- 新增需要明确确认的 live smoke：
codex-helper codex relay-live-smoke --acknowledgement run-live-codex-relay-smoke --model gpt-5.5。默认只测 /responses/compact；加 --image 只测 hosted image generation，加 --websocket 只测 Responses WebSocket v2，同时传多个可选 case 时只跑显式指定的 case。这个命令会打真实上游，可能消耗额度、生成图片或建立 WebSocket 会话。
- 诊断和 live smoke 会写入
~/.codex-helper/logs/codex_relay_evidence.jsonl。这是给人看的本地证据，不参与 routing、affinity、health、余额、retry 或自动切换 preset。
多中转路由和余额
- Codex 多中转默认更偏向“稳定粘住当前可用上游”。对 official relay、remote compaction 这类可能带上游账号绑定状态的请求，建议使用
[codex.routing].affinity_policy = "fallback-sticky"。
- 当所有候选都因为可信余额耗尽或 cooldown 被挡住时，Codex streaming 请求会收到可重试的
response.failed，helper 会排队一次受节流的余额刷新，而不是每秒反复打同一个已耗尽上游。
- 如果某个中转余额接口经常把可用账号报成 0，把对应 usage provider 的
trust_exhaustion_for_routing 设为 false，让余额只作为提示，不再驱动路由降级。
- 请求触发的余额刷新现在按 provider/endpoint 去重和延迟刷新；手动刷新也能命中自动探测到的 sub2api provider id。
TUI/GUI 可见变化
- TUI 的
Stats 改为 Usage，集中看 provider 用量、余额/配额、刷新结果、endpoint 最近样本和费用估算。
Usage 页面可以按 g 刷新余额，按 a 只看需要处理的 provider；provider 很多时详情页支持 PgUp / PgDn 滚动 endpoint。- 窄终端下 Routing/Usage 的余额显示更稳，不再容易出现
$0/$ 这类半截金额。Routing 页保留紧凑余额，详细分析放在 Usage/Balance。
- GUI 的余额状态和 core 语义对齐，
unknown、stale、exhausted、error、unlimited 不再由不同 UI 各算一套。
- Usage 的 burn forecast 现在会合并请求 ledger tail 和 recent samples，并在请求日志里补充 model / route decision 信息，避免高频请求场景下 burn rate 和到 0 点预估明显偏低。
升级时关注
- README 现在把 cargo-dist 生成的预编译 shell / PowerShell installer 作为推荐安装入口；
cargo-binstall 仍保留给 Rust 用户。
- 常用 client preset 放在
[codex.client_patch] preset = "..."，也可以用 codex-helper switch on --preset ... 显式切换。旧的 mode / --mode 仍可读，但建议迁移到 preset。改完后需要完整重启 Codex App、TUI 或 codex exec。
- route graph 的默认 affinity policy 回到
fallback-sticky，新配置会倾向同一 session 粘住已成功的 fallback provider。若你更希望故障恢复后尽快回到最高优先级 provider，请显式设置 [codex.routing].affinity_policy = "preferred-group"。
- 启动时会先加载并规范化
~/.codex-helper/config.toml，再 patch Codex；如果 ~/.codex/config.toml 还保留旧的本地代理但缺少 switch state，会以 codex-helper 配置里的 preset 为准重新 patch。
- 如果想启用 Responses WebSocket，请额外设置
responses_websocket = true 或传 --responses-websocket；它不是 preset，只建议在已验证支持 WebSocket 的上游上开启。例如实测 input8 支持，ciii 的 HTTP endpoints 可用但 WebSocket upstream/proxy 失败，应保持关闭。
- relay 要求模型名前缀时，用
provider add --model-map FROM=TO 或 provider 级 model_mapping，例如 gpt-5.5 -> openai/gpt-5.5。
- 不确定 relay 是否支持 compact/imagegen 时，先跑
codex-helper codex relay-capabilities；只有要真实验证上游链路时再跑 live smoke。
- 手机远程控制仍走
codex-helper switch remote-control ...，它和 chatgpt-bridge 是两条路径。
English summary
Codex relays and native ChatGPT behavior
- The local Codex proxy now normalizes request-body
Content-Encoding by default (zstd, gzip / x-gzip, br, and deflate) before routing, model overrides, and forwarding, then removes stale Content-Encoding / Content-Length; rare relays that require the original compressed body can start helper with CODEX_HELPER_REQUEST_BODY_ENCODING=passthrough.
- When no stronger session header is present (
session_id, session-id, conversation_id, or thread-id), helper uses decoded JSON prompt_cache_key as the session-affinity fallback so /responses and /responses/compact keep sub2api-style stickiness across relay routing.
- Added Codex client presets for setups where Codex should keep an official or ChatGPT-like client shape while model traffic goes through codex-helper relays. Use
[codex.client_patch].preset = "..." and codex-helper switch on --preset ...; legacy mode = "..." and CLI --mode ... are still accepted, but helper writes saved/generated config as preset.
chatgpt-bridge is for users already signed in to ChatGPT in official Codex. Codex keeps seeing ChatGPT account state, while model requests are routed through codex-helper.imagegen-bridge exposes hosted image_generation for relays that do not support official provider identity. It writes the empty {} auth facade; real upstream credentials still come from helper config.official-relay is for relays that forward OpenAI Responses semantics, especially /responses/compact. It lets Codex try remote compaction v1.official-imagegen is for official-subscription-backed relays that support both /responses/compact and hosted image generation.- Legacy preset names
official-relay-bridge / official-imagegen-bridge remain accepted as aliases, but are no longer the recommended spelling; unpublished official-ws-* combinations were removed.
- Added the separate transport switch
responses_websocket = true / --responses-websocket. It is not a new preset, is only valid with official-relay or official-imagegen, and makes helper advertise supports_websockets = true while proxying Responses WebSocket v2.
- Bridge modes do not forward Codex ChatGPT tokens to third-party relays without helper-side credentials. Configure upstream secrets with
auth_token_env, auth_token, api_key_env, or api_key.
Relay diagnostics
- Added Codex relay capability diagnostics in TUI Settings, admin API, and CLI. Common CLI:
codex-helper codex relay-capabilities --preset official-imagegen --model gpt-5.5.
- Diagnostics check
/models, /responses, and /responses/compact, then recommend a preset. They do not switch presets automatically.
- Diagnostics and live smoke can target a specific provider/endpoint with
--provider <ID> and --endpoint <ID>, making it possible to verify one relay directly instead of only the current routing preference.
- OpenAI-style
/models responses (data: [...]) are translated into the Codex models: [...] catalog so Codex can see model metadata such as image/search/apply_patch support.
- Added explicit live smoke:
codex-helper codex relay-live-smoke --acknowledgement run-live-codex-relay-smoke --model gpt-5.5. It checks compact by default; --image tests only hosted image generation, --websocket tests only Responses WebSocket v2, and multiple optional cases run only the explicitly requested cases. This sends real upstream requests and may spend quota, create an image, or open a WebSocket session.
- Diagnostics and live smoke append sanitized records to
~/.codex-helper/logs/codex_relay_evidence.jsonl. That file is local diagnostic evidence only; it does not affect routing, affinity, health, balance, retry, or automatic preset switching.
Multi-relay routing and balance
- Codex multi-relay routing now favors keeping a viable selected upstream stable. For official relay and remote compaction setups, use
[codex.routing].affinity_policy = "fallback-sticky" when upstream-account continuity matters.
- When every candidate is blocked by trusted balance exhaustion or cooldown, Codex streaming gets a retryable
response.failed and helper queues a throttled balance refresh instead of hammering the same exhausted upstream.
- If a relay balance API reports false zero balance, set that usage provider's
trust_exhaustion_for_routing to false so balance stays informational and no longer demotes routing.
- Request-triggered balance refreshes are deduplicated by provider/endpoint and delayed; manual refresh can also target auto-discovered sub2api provider ids.
TUI and GUI
- TUI
Stats is now Usage, focused on provider usage, balance/quota state, refresh results, recent endpoint samples, and cost estimates.
- On
Usage, press g to refresh balances and a to show only providers that need attention. Large endpoint lists can be scrolled with PgUp / PgDn.
- Narrow Routing/Usage views keep balance amounts readable instead of showing partial values like
$0/$. Routing keeps compact balance context; detailed inspection lives in Usage/Balance.
- GUI balance state now uses the same core semantics as TUI, keeping
unknown, stale, exhausted, error, and unlimited distinct.
- Usage burn forecasts now merge request ledger tail data with recent samples and include model / route-decision context in request logs, avoiding undercounted burn rate and midnight projections during high-volume Codex sessions.
Upgrade notes
- README now recommends the prebuilt shell / PowerShell installers generated by cargo-dist;
cargo-binstall remains documented for Rust users.
- Set the usual client preset with
[codex.client_patch] preset = "..." or codex-helper switch on --preset .... Legacy mode / --mode are still accepted, but preset is the recommended spelling. Restart Codex App, TUI, or codex exec after changing it.
- The route-graph default affinity policy is back to
fallback-sticky, so new configs keep a session on a successful fallback provider. If you prefer returning to the highest-priority provider as soon as it recovers, set [codex.routing].affinity_policy = "preferred-group" explicitly.
- Startup now loads and normalizes
~/.codex-helper/config.toml before patching Codex; if ~/.codex/config.toml still points at the local proxy but the switch state is missing, helper re-patches from the configured preset instead of trusting stale inferred state.
- To enable Responses WebSocket, set
responses_websocket = true or pass --responses-websocket; it is not a preset and should only be enabled for upstream relays verified to support WebSocket. For example, input8 was verified to support it, while ciii supports the HTTP endpoints but fails the WebSocket upstream/proxy path and should keep it disabled.
- If a relay requires provider-prefixed model names, use
provider add --model-map FROM=TO or provider-level model_mapping, for example gpt-5.5 -> openai/gpt-5.5.
- If you are unsure whether a relay supports compact or imagegen, run
codex-helper codex relay-capabilities first. Use live smoke only when you want a real upstream test.
- Mobile remote control still uses
codex-helper switch remote-control ...; it is separate from chatgpt-bridge.
Install codex-helper 0.16.0
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Latias94/codex-helper/releases/download/v0.16.0/codex-helper-installer.sh | sh
Install prebuilt binaries via powershell script
powershell -ExecutionPolicy Bypass -c "irm https://github.com/Latias94/codex-helper/releases/download/v0.16.0/codex-helper-installer.ps1 | iex"
Download codex-helper 0.16.0
