Release Notes
中文
Codex 请求/响应语义增强
- 本地代理新增 OpenAI Images 兼容入口
POST /v1/images/generations / /images/generations，会把 model、prompt、size、output_format、quality 等字段转成 /v1/responses hosted image_generation 请求，并继续复用既有 provider routing、重试、fallback、auth 注入和请求日志。成功响应会转换为 data[0].b64_json，当前仅支持单图 n=1。
- Codex
/responses、/responses/compact 和 Responses WebSocket 请求现在会从已有请求证据补齐缺失的 session_id、x-session-id、官方 session-id / thread-id 和 prompt_cache_key；来源包括 header session、body session_id、prompt_cache_key 和 metadata.session_id。previous_response_id 只用于 stale-response 修复，不再作为 session completion 或 session identity 来源。helper 不会凭空生成 session id，也不会覆盖客户端已发送的 session 字段。
- Codex
/responses/compact 现在会先尝试已存在的 session affinity；在单 provider endpoint 或 fallback-sticky route graph 下，state-bound compact 不再仅因为缺少既有 route affinity 被本地 503 拦截，helper 会按配置尝试可用 provider endpoint，并在成功后记录 session affinity。如果 affinity 账号不可用，fallback-sticky 可继续按路由策略尝试其它可用账号；hard affinity 和 legacy 多 upstream 仍保持 fail-closed，避免盲目跨账号搬迁 compact state。
- Codex
/responses/compact 现在会保留官方 compaction 输入里的 service_tier 和 prompt_cache_key，转发体会去掉 previous_response_id 以贴近官方 compact 形状；如果请求体里带有 encrypted_content 或 previous_response_id 这类状态字段，就会把 compact 视为 state-bound 请求，避免跨账号兜底把 502 误变成上游状态错误。
- Session route affinity 现在会以 provider endpoint identity 形式持久化到 helper state。helper 重启后，Codex remote compaction 会继续使用之前已证明的 provider endpoint；如果当前策略要求已知 affinity 但 state-bound compact 缺少可恢复 affinity，会返回明确连续性错误，而不是静默切到另一个 provider。
- Codex remote compaction v2 现在会在普通
POST /responses 请求里识别结构化 compaction_trigger，并在日志中写入 codex_bridge.remote_compaction_v2_request。v2 compact 会按 provider-state-bound 处理，并遵守和 v1 compact 相同的 route affinity policy：fallback-sticky 可引导或更新 affinity，hard 会限制在 affinity continuity domain 内。helper 不会假设背后 relay 是 sub2api、OpenAI、New API 或其它实现。
- 新增显式
continuity_domain 连续性边界，可配置在 provider 或 endpoint 上，并会出现在 relay capability diagnostics 和桌面 provider 编辑里；普通 provider 编辑也会保留已有 continuity_domain，不会因为改 base URL 或启停状态而意外清空。只有显式共享同一个 continuity_domain 的 endpoints，才允许 state-bound compact 在已有 affinity 后跨 endpoint failover；helper 不会再根据相同 base_url、host 或 provider 名推断共享状态。
- Responses WebSocket 的 state-bound compact 选路现在和 HTTP compact 对齐：
fallback-sticky 可以引导 affinity；hard 会限制在 affinity continuity domain 内，并且只在显式共享 continuity_domain 的 endpoints 之间故障切换。
- Relay live smoke 新增显式
remote_compaction_v2 / --compact-v2 case：会发送真实 /responses stream 请求、带 compaction_trigger 和 x-codex-beta-features: remote_compaction_v2，只有看到一个 compaction output item 和 response.completed 才算通过；默认 live smoke 仍只测 /responses/compact。
- Control trace 新增 provider-opaque 的连续性诊断字段：continuity class、affinity source、provider failover 是否允许、阻断原因，以及余额信号是否对该连续性决策具有权威性。helper 不会从这些信号推断 relay 背后是 OpenAI、sub2api、New API 或其它实现。
- Codex routing explain 现在会和实际执行路径一致：HTTP、Responses WebSocket 和 legacy 路径都会应用同一套 session route affinity，legacy explain 不再因为遗漏 session affinity 而和真实路由结果不一致。
- 如果上游 400/404 明确表示
previous_response_id 对应 response 不存在，helper 会移除 previous_response_id 并对同一个上游重试一次，同时在 route attempts 中记录 codex_stale_previous_response_id，方便排查 relay 状态不同步。
- Codex 非流式响应新增受控 gzip JSON 修复：当 relay 无视
Accept-Encoding: identity 返回 gzip JSON 时，helper 会解压后转发普通 JSON，并继续复用现有响应头过滤去掉过期的 Content-Encoding / Content-Length。
- 当 Codex stream 请求在选路前失败（例如所有候选都因余额耗尽、cooldown 或无可路由目标被阻断）时，helper 会返回 Codex 可解析的
response.failed SSE，而不是裸 HTTP 错误，避免客户端流式解析卡在异常形态上。
service_tier 观测补齐代理级回归测试：请求日志会保留 requested / effective / actual 三段，确认 fast mode 仍只由客户端或显式 override 决定，不由 helper 默认配置偷偷改写。- OpenAI 风格
/models 到 Codex models catalog 的翻译改为显式 translate_models = true 开关；启用时会补充 image/search/apply_patch、context window 和 fast service_tier 等 metadata，并可叠加 Basellm 模型 metadata，但默认不再把合成目录当作权威返回给 Codex。
- OpenAI Images 兼容入口现在会在转发 hosted image generation 请求前去掉客户端
User-Agent，避免部分上游把本地脚本或 Codex 客户端 UA 当成能力/风控信号。
- 新增仓库分发的
ch-imagegen skill：通过本地 /v1/images/generations 入口生成图片，自动计算 gpt-image-2 的 2K/4K 尺寸，保存并校验新生成的文件。
Codex 客户端与 TUI
codex-helper switch on 不带显式 preset 时现在会读取 [codex.client_patch] 配置，正确应用配置中的 preset、responses_websocket 等选项；显式 --preset 仍可覆盖配置。- TUI transcript 弹窗现在可以按实际换行后的内容滚动，长消息折行后不再出现无法滚到被包裹行的问题。
Codex 中转请求字段覆盖
- 修复自动
default_profile 会把客户端请求体里的 model、reasoning.effort 和 service_tier 改成 profile 默认值的问题；现在只有显式 session override 或手动 apply 到 session 的 profile binding 才会改写这些请求字段。
- Codex 本地 fast mode 发出的
service_tier: "priority" 不会再被中转的默认 profile 覆盖成 default。自动 default profile 仍可用于 session binding 和 station 路由，但不再冒充用户请求字段 override。
发布包
- cargo-dist release 包现在只包含
codex-helper CLI package，避免把 desktop package 混入命令行发行物。
English summary
Codex request/response semantics
- Added an OpenAI Images-compatible local proxy entrypoint:
POST /v1/images/generations / /images/generations. It maps model, prompt, size, output_format, quality, and related fields into a /v1/responses hosted image_generation request while preserving existing provider routing, retry, fallback, auth injection, and request logging. Successful responses are converted to data[0].b64_json; the first version supports single-image n=1 only.
- Codex
/responses, /responses/compact, and Responses WebSocket requests now complete missing session_id, x-session-id, official session-id / thread-id, and prompt_cache_key fields from existing request evidence: header session ids, body session_id, prompt_cache_key, or metadata.session_id. previous_response_id is only used for stale-response repair, not as a session completion or session identity source. Helper does not invent synthetic session ids or overwrite client-provided session fields.
- Codex
/responses/compact now tries existing session affinity first. With a single provider endpoint or a fallback-sticky route graph, state-bound compact is no longer blocked locally with a 503 solely because no prior route affinity exists; helper tries the configured provider endpoint path and records session affinity after success. If the affinity account is unavailable, fallback-sticky can continue through other available accounts according to routing policy; hard affinity and legacy multi-upstream routing remain fail-closed to avoid blindly moving compact state across accounts.
- Codex
/responses/compact now preserves the official input fields service_tier and prompt_cache_key, strips previous_response_id from the forwarded payload to match the official compact shape, and treats requests carrying encrypted_content or previous_response_id as state-bound so compact fallback does not cross accounts when upstream state might be pinned to one relay identity.
- Session route affinity is now persisted by provider endpoint identity under helper state. After a helper restart, Codex remote compaction keeps using the previously proven provider endpoint; when the active policy requires known affinity and a state-bound compact request has no restorable affinity, helper returns an explicit continuity error instead of silently moving to another provider.
- Codex remote compaction v2 is now recognized on ordinary
POST /responses requests with a structured compaction_trigger input item and logged as codex_bridge.remote_compaction_v2_request. V2 compact is treated as provider-state-bound and follows the same route affinity policy as v1 compact: fallback-sticky can bootstrap or update affinity, while hard stays inside the affinity continuity domain. Helper does not infer whether the relay backend is sub2api, OpenAI, New API, or something else.
- Added an explicit
continuity_domain boundary on providers and endpoints, surfaced in relay capability diagnostics and desktop provider editing; ordinary provider edits also preserve existing continuity_domain values instead of clearing them while changing base URLs or enabled state. State-bound compact can fail over across endpoints after known affinity only when those endpoints explicitly share the same continuity_domain; helper does not infer shared state from matching base_url, host, or provider names.
- Responses WebSocket state-bound compact routing now matches HTTP compact routing:
fallback-sticky can bootstrap affinity, while hard stays inside the affinity continuity domain and only fails over across endpoints with an explicit shared continuity_domain.
- Relay live smoke now has an explicit
remote_compaction_v2 / --compact-v2 case. It sends a real streaming /responses request with compaction_trigger and x-codex-beta-features: remote_compaction_v2, and only passes after one compaction output item plus response.completed; the default live smoke still checks only /responses/compact.
- Control trace now includes provider-opaque continuity diagnostics: continuity class, affinity source, whether provider failover is allowed, the blocked reason, and whether balance signals are authoritative for that continuity decision. Helper does not infer whether the relay backend is OpenAI, sub2api, New API, or something else.
- Codex routing explain now matches the actual execution path: HTTP, Responses WebSocket, and legacy paths all apply the same session route affinity, so legacy explain no longer diverges from the real route selection.
- If an upstream 400/404 explicitly says the
previous_response_id response no longer exists, helper removes previous_response_id and retries the same upstream once. Route attempts record codex_stale_previous_response_id for relay-state debugging.
- Added bounded gzip JSON repair for non-streaming Codex responses. If a relay ignores
Accept-Encoding: identity and returns gzip JSON, helper decodes it before forwarding plain JSON and keeps filtering stale Content-Encoding / Content-Length.
- When Codex streaming requests fail before an upstream is selected, such as all candidates being blocked by trusted balance exhaustion, cooldown, or no routable target, helper now returns a Codex-parseable
response.failed SSE instead of a bare HTTP error.
- Added proxy-level regression coverage for
service_tier attribution: request logs preserve requested / effective / actual values, confirming fast mode is driven by the client or explicit overrides, not by helper defaults.
- OpenAI-style
/models to Codex models catalog translation is now behind the explicit translate_models = true switch. When enabled, helper adds metadata such as image/search/apply_patch support, context windows, and fast service_tier, with optional Basellm metadata overlay, but it no longer treats synthesized catalogs as authoritative by default.
- The OpenAI Images-compatible entrypoint now strips the client
User-Agent before forwarding hosted image generation requests, avoiding relays that treat local script or Codex client UAs as capability or policy signals.
- Added the repository-distributed
ch-imagegen skill. It calls the local /v1/images/generations entrypoint, computes valid gpt-image-2 2K/4K sizes, saves the generated file, and validates only the new output.
Codex client and TUI
codex-helper switch on without an explicit preset now reads [codex.client_patch] and applies configured preset, responses_websocket, and related options; explicit --preset still overrides config.- TUI transcript modals now scroll by rendered wrapped lines, so long wrapped messages no longer hide unreachable content.
Codex relay request-field overrides
- Fixed automatic
default_profile bindings rewriting client request-body model, reasoning.effort, and service_tier; only explicit session overrides or manually applied session profile bindings now patch those fields.
- Codex local fast mode requests with
service_tier: "priority" are no longer overwritten to default by relay default profiles. Automatic default profiles can still bind sessions and station routing, but no longer act as request-field overrides.
Release packaging
- cargo-dist release artifacts now include only the
codex-helper CLI package, avoiding accidental desktop package inclusion in the command-line distribution.
Install codex-helper 0.17.0
Install prebuilt binaries via shell script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Latias94/codex-helper/releases/download/v0.17.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.17.0/codex-helper-installer.ps1 | iex"
Download codex-helper 0.17.0
