Skip to content

0.13.0 - 2026-05-09

Choose a tag to compare

View all tags
@github-actions github-actions released this 10 May 14:14
v0.13.0
587b1d8

Release Notes

重点 / Highlights

  • version = 3 成为默认配置：provider 只定义一次，routing 负责顺序兜底、手动固定和标签优先。旧配置会自动迁移到 config.toml，并在覆盖前保留 config.toml.bak / config.json.bak。
    version = 3 is now the default config model: define providers once and let routing handle ordered fallback, manual pinning, and tag-based preference. Older configs migrate automatically to config.toml, with config.toml.bak / config.json.bak kept before overwrite.
  • 新增更直观的 provider 切换体验：包月中转可以打 billing=monthly 标签，已知耗尽后按策略继续或停止。
    Provider switching is clearer: monthly relays can be tagged with billing=monthly, then known exhaustion can either fall through or stop according to policy.
  • 余额和套餐更可见：会优先尝试 Sub2API、New API 和常见 /user/balance 接口；查询失败显示为 unknown，不会被当作耗尽。
    Balance and plan visibility improved: Sub2API, New API, and common /user/balance endpoints are probed first. Lookup failures show as unknown and do not count as exhaustion.
  • TUI/GUI 更适合日常操作：routing 页面显示 provider 顺序、余额/套餐、tags、启停状态和候选状态；请求视图显示 token、cache token、耗时、速度、重试和估算成本。
    TUI/GUI are more operator-friendly: routing pages show provider order, balances/plans, tags, enabled state, and candidates; request views show tokens, cache tokens, latency, speed, retries, and estimated cost.
  • Codex 配置 patch 更安全：switch on/off 只改本地代理相关片段，不会覆盖 Codex 运行期间写入的其他配置。
    Codex config patching is safer: switch on/off only changes the local proxy section and does not overwrite other Codex edits made during a run.
  • 长时间运行更稳：上游连接增加连接超时、TCP keepalive、空闲连接回收；运行态日志和 TUI/GUI 刷新路径做了有界化处理。
    Long-running proxy stability improved with connect timeouts, TCP keepalive, idle connection cleanup, and bounded TUI/GUI refresh state.

可复制 Routing 示例 / Copyable Routing Examples

先定义 provider，再复制一个 [codex.routing] 策略。Claude 配置同理，把 codex 换成 claude。
Define providers once, then copy one [codex.routing] policy. For Claude, replace codex with claude.

version = 3

[codex.providers.monthly_a]
base_url = "https://monthly-a.example.com/v1"
auth_token_env = "MONTHLY_A_API_KEY"
tags = { billing = "monthly" }

[codex.providers.monthly_b]
base_url = "https://monthly-b.example.com/v1"
auth_token_env = "MONTHLY_B_API_KEY"
tags = { billing = "monthly" }

[codex.providers.paygo]
base_url = "https://api.openai.com/v1"
auth_token_env = "OPENAI_API_KEY"
tags = { billing = "paygo" }

顺序兜底：最直观的优先级链。
Ordered fallback: the clearest priority chain.

[codex.routing]
policy = "ordered-failover"
order = ["monthly_a", "monthly_b", "paygo"]
on_exhausted = "continue"

手动固定：临时强制使用一个 provider。
Manual sticky: force one provider temporarily.

[codex.routing]
policy = "manual-sticky"
target = "monthly_a"
order = ["monthly_a", "monthly_b", "paygo"]
on_exhausted = "continue"

包月优先并保持可用：先用 billing=monthly，已知耗尽后继续兜底。
Monthly first with fallback: prefer billing=monthly, then fall back after known exhaustion.

[codex.routing]
policy = "tag-preferred"
prefer_tags = [{ billing = "monthly" }]
order = ["monthly_a", "monthly_b", "paygo"]
on_exhausted = "continue"

包月严格止损：包月都已知耗尽时停止，不走付费兜底。
Strict monthly budget: stop instead of falling back to pay-as-you-go.

[codex.routing]
policy = "tag-preferred"
prefer_tags = [{ billing = "monthly" }]
order = ["monthly_a", "monthly_b", "paygo"]
on_exhausted = "stop"

更多配置示例见 docs/CONFIGURATION.md。
More config recipes are available in docs/CONFIGURATION.md.

新增 / Added

  • provider / routing 命令与 API：新增 provider、调整 fallback 顺序、pin provider、启停 provider、编辑标签、解释当前 routing。
    provider / routing commands and APIs: add providers, reorder fallback, pin, enable/disable, edit tags, and explain routing.
  • 余额适配与自动探测：Sub2API /v1/usage、Sub2API dashboard /api/v1/auth/me、New API /api/user/self、通用 /user/balance。
    Balance adapters and auto-probing for Sub2API /v1/usage, Sub2API dashboard /api/v1/auth/me, New API /api/user/self, and generic /user/balance.
  • 价格目录刷新与请求成本估算：可同步外部价格目录，不需要把模型价格写死在主配置里。
    Pricing catalog refresh and request cost estimates: sync external price catalogs instead of hardcoding model prices in the main config.

改进 / Improved

  • TUI 的 routing/provider 视图更接近真实用户心智：显示 policy、顺序、余额、套餐、tags、启停状态和候选状态。
    TUI routing/provider views now match the user mental model better: policy, order, balance, plan, tags, enabled state, and candidate status.
  • GUI 可以编辑常见单 endpoint provider 和 routing；复杂 provider 保持只读，避免 UI 保存时丢掉高级字段。
    GUI can edit common single-endpoint providers and routing; complex providers remain read-only to avoid dropping advanced fields.
  • 请求日志和统计更有用：provider、model、input/output token、cache token、TTFB、总耗时、输出速度、重试链和估算成本会尽量进入 ledger/UI。
    Request logs and stats now include provider, model, input/output tokens, cache tokens, TTFB, total duration, output speed, retry chain, and estimated cost where available.
  • README 和配置文档已重写为首页 + recipes + reference 的结构，新用户更容易复制可用配置。
    README and configuration docs now follow a homepage + recipes + reference structure for easier onboarding.

修复 / Fixed

  • 修复退出 codex-helper 后用旧快照覆盖 ~/.codex/config.toml 的问题，Codex 自动写入的 project trust 等配置会保留。
    Fixed old snapshot restore overwriting ~/.codex/config.toml; Codex-written project trust and similar entries are preserved.
  • 修复 TUI provider 列表重复行、顶部状态栏和底部快捷键在窄终端下显示不稳的问题。
    Fixed TUI provider-list duplicate rows plus top-status/footer layout issues in narrow terminals.
  • 修复 GUI 手动切换、重载或探测后，旧的后台刷新结果可能短暂覆盖新状态的问题。
    Fixed stale GUI background refresh results briefly overriding newer state after manual switching, reloads, or probes.
  • 修复 GUI 在持久化配置保存或运行态重载后，界面有时还会沿用旧配置快照的问题。
    Fixed GUI cases where the UI could keep showing an old config snapshot after persisted saves or runtime reloads.
  • 修复 v3 provider/routing 保存后可能丢失 provider tags、endpoint tags、模型支持和 model mapping 的问题。
    Fixed v3 provider/routing saves potentially losing provider tags, endpoint tags, model support, and model mappings.
  • 修复余额查询失败残留旧耗尽状态的问题；HTTP 404 等失败现在显示为 unknown，不会影响 routing。
    Fixed failed balance lookups leaving stale exhaustion state; failures such as HTTP 404 now show as unknown and do not affect routing.

升级说明 / Upgrade Notes

  • 正常升级不需要手动重写配置。启动 CLI、TUI、GUI 或代理时会自动迁移旧配置。
    Normal upgrades do not require manual config rewrites. CLI, TUI, GUI, and proxy startup migrate old configs automatically.
  • 想先查看迁移结果，可以运行：
    To preview migration first, run:
codex-helper config migrate --dry-run
codex-helper config migrate --write --yes
  • 新版本下 provider 选择统一由 routing 负责。外部脚本如果还在写旧 station/active 字段，建议改用 provider / routing 命令、API 或 v3 TOML。
    Provider selection now belongs to routing. External scripts that still write old station/active fields should move to provider / routing commands, APIs, or v3 TOML.
  • 余额查询失败不再意味着不可用；只有可信的已耗尽快照才会参与 routing 降级。
    Balance lookup failure no longer means unavailable; only trusted exhausted snapshots can demote routing.

Install codex-helper 0.13.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Latias94/codex-helper/releases/download/v0.13.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.13.0/codex-helper-installer.ps1 | iex"

Download codex-helper 0.13.0

File Platform Checksum
codex-helper-aarch64-apple-darwin.tar.xz Apple Silicon macOS checksum
codex-helper-x86_64-apple-darwin.tar.xz Intel macOS checksum
codex-helper-x86_64-pc-windows-msvc.zip x64 Windows checksum
codex-helper-x86_64-unknown-linux-gnu.tar.xz x64 Linux checksum
Assets 16
Loading