v1.1.0 — macOS support, and no console window

What this is

A local retry shim that stops "Selected model is at capacity. Please try a different model." from interrupting your work.

Not a proxy service, not a shared account, not a middleman. It is a single stdlib-only Python file listening on 127.0.0.1 that forwards to the official endpoint using the OAuth token Codex already sent. Delete one line from config.toml and you are back to a direct connection.

Read this first: what this does not fix.

This project cannot fix a degraded model. If the model itself has started answering worse than it used to, nothing here changes that. You can call it drinking poison to quench thirst — it suppresses the symptom, it does not treat the cause.

But be fair about the comparison. Until OpenAI allocates more compute to your account, the real choice in front of you is not "this shim" versus "a model that works properly". It is "this shim" versus "being interrupted every two turns". Between those two, there is no better option available to you.

What's new in v1.1.0

• macOS support. scripts/install-mac.sh registers the relay as a per-user LaunchAgent. No admin rights, no watchdog script, no window to hide — launchd restarts it via KeepAlive. scripts/uninstall-mac.sh undoes it. This path runs end-to-end on a real macOS runner in CI (.github/workflows/macos.yml).
• Console-flash investigation. docs/windows-no-console-window.md and tools/check_console_flash.py document and measure why -WindowStyle Hidden cannot suppress the launcher window, and how to prove it on your own machine.
• .gitattributes, so the shell scripts and the relay ship with LF endings — a CRLF shebang breaks bash on macOS.

Install

Download codex-overload-fix-1.1.0.zip below, unzip it, then:

Windows

powershell -ExecutionPolicy Bypass -File scripts\install.ps1

The installer finds Python (3.9+, no dependencies), registers a hidden launcher and a watchdog, and prints the config.toml snippet to paste. No admin rights, no console window.

macOS

bash scripts/install-mac.sh

Also no admin rights. launchctl loads it now and on every login. --dry-run prints the plist without changing anything; --proxy, --port and --python-path work as you would expect.

Both platforms, then set your provider in ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows):

model_provider = "openai-retry"

[model_providers.openai-retry]
name = "OpenAI (retry)"
base_url = "http://127.0.0.1:8787"
wire_api = "responses"
requires_openai_auth = true
stream_max_retries = 20
request_max_retries = 10

Restart Codex. Undo with scripts\uninstall.ps1 on Windows, or bash scripts/uninstall-mac.sh on macOS (add --purge to delete the log too).

Prefer git clone if you want git pull updates:

git clone https://github.com/NewBeeM4n/codex-overload-fix.git

Why the error happens

The rejection is not a quota problem. server_is_overloaded arrives as an error event inside an HTTP 200 SSE stream, so nothing that retries on status codes ever sees it. And the rejection rate tracks request body size, not model choice:

request body	n	attempts needed (mean)	worst
< 100 KB	20	1.95	5
100–200 KB	24	1.96	9
200–500 KB	23	1.74	4
> 500 KB	4	6.75	9

One 799 KB request failed 8 times in a row and succeeded on the 9th. The user never saw a thing.

What is in the box

file	purpose
relay/relay.py	the shim — recognises the overload, retries only before any token is emitted, stops when you cancel
scripts/install.ps1 / uninstall.ps1	Windows: hidden launcher, watchdog, config snippet
scripts/install-mac.sh / uninstall-mac.sh	macOS: LaunchAgent with KeepAlive
tools/capture_server.py	measures the exact request body your client sends
tools/analyze_log.py	summarises attempts vs. request size from relay.log
tools/check_console_flash.py	Windows: proves a launcher really shows no window
docs/findings.md	the full write-up with the measurements
docs/windows-no-console-window.md	why -WindowStyle Hidden does not work, measured

Verify the download

ca268eaa4ba21a9c4d53a78bd8e74580823955526539963e6b138dff7ded1895  codex-overload-fix-1.1.0.zip

Also attached as .sha256. You can let your shell confirm it instead:

Get-FileHash .\codex-overload-fix-1.1.0.zip -Algorithm SHA256     # Windows

shasum -a 256 codex-overload-fix-1.1.0.zip                        # macOS

Known limitations

• It does not fix a degraded model. If the model itself has started answering worse than it used to, nothing here changes that. The shim only stops the capacity error from interrupting you; it cannot make the model smarter.
• Single machine, single account, small samples. The size correlation is the signal; the specific percentages are noise-prone.
• Whether a retried request can land on a different model than the one requested is not ruled out. The relay logs both model= (what the client sent) and served= (what the server reported), so it can be checked — evidence either way is welcome.
• Launchers ship for Windows and macOS. The relay itself is cross-platform; on anything else run python3 relay/relay.py directly.
• The macOS path is verified on GitHub's macos-latest runner (arm64, current macOS). Intel Macs and older macOS releases are untested — open an issue if it misbehaves.
• It cannot fix a genuinely exhausted quota, an expired login, or a broken network. Those are different errors and pass through unchanged.

MIT. Fork it, vendor it, ship it inside your own tooling.

---

中文说明

这是什么

一个本地重试中继，让 「Selected model is at capacity. Please try a different model.」 不再打断你的工作。

不是反代站、不是共享账号、不是中间人。它是 127.0.0.1 上的一个单文件、纯标准库 Python 脚本，用 Codex 自己发出的 OAuth token 转发到官方端点。从 config.toml 删掉一行就回到直连。

先说清楚它治不了什么。

本项目无法解决模型降智的问题。如果模型本身已经答得不如以前，这里没有任何东西能改变它。你可以认为这是在饮鸩止渴 —— 它压住的是症状，不是病根。

但对比要公平。在 OpenAI 给你的账户分配更多算力之前，真正摆在你面前的不是「这个中继」和「一个好用的模型」，而是「这个中继」和「每两轮被打断一次」。这两者之间，你没有更好的方案。

v1.1.0 更新了什么

• 支持 macOS。 scripts/install-mac.sh 把中继注册成用户级 LaunchAgent。不需要管理员权限，没有看门狗脚本，也没有窗口要藏 —— launchd 靠 KeepAlive 自己重启进程。卸载用 scripts/uninstall-mac.sh。这条路在 CI 里跑在真实的 macOS runner 上（.github/workflows/macos.yml）。
• 控制台闪屏的调查。docs/windows-no-console-window.md 和 tools/check_console_flash.py 记录了为什么 -WindowStyle Hidden 挡不住启动窗口，以及怎么在你自己的机器上测出来。
• 加了 .gitattributes，让 shell 脚本和中继以 LF 换行发布 —— CRLF 的 shebang 会让 macOS 上的 bash 直接失败。

安装

下载下面的 codex-overload-fix-1.1.0.zip，解压后：

Windows

powershell -ExecutionPolicy Bypass -File scripts\install.ps1

安装脚本会找到 Python（3.9+，无依赖）、注册隐藏启动器和看门狗、并打印你要粘贴的 config.toml 片段。不需要管理员权限，不弹控制台窗口。

macOS

bash scripts/install-mac.sh

同样不需要管理员权限。launchctl 现在加载一次，以后每次登录自动起来。--dry-run 只打印 plist 什么都不改；--proxy、--port、--python-path 照常用。

两个平台都一样，然后在 ~/.codex/config.toml（Windows 上是 %USERPROFILE%\.codex\config.toml）里设置 provider：

model_provider = "openai-retry"

[model_providers.openai-retry]
name = "OpenAI (retry)"
base_url = "http://127.0.0.1:8787"
wire_api = "responses"
requires_openai_auth = true
stream_max_retries = 20
request_max_retries = 10

重启 Codex。卸载：Windows 用 scripts\uninstall.ps1，macOS 用 bash scripts/uninstall-mac.sh（加 --purge 连日志一起删）。

想用 git pull 跟进更新的话，就用 git clone：

git clone https://github.com/NewBeeM4n/codex-overload-fix.git

为什么会报这个错

不是额度问题。server_is_overloaded 是HTTP 200 的 SSE 流里的一个 error 事件，所以任何按状态码重试的东西都看不见它。而且拒绝率跟请求体大小相关，跟模型选择无关：

请求体	数量	平均尝试次数	最惨
< 100 KB	20	1.95	5
100–200 KB	24	1.96	9
200–500 KB	23	1.74	4
> 500 KB	4	6.75	9

有一条 799 KB 的请求连续失败 8 次，第 9 次成功。用户全程什么都没看见。

包里面有什么

文件	作用
relay/relay.py	中继本体 —— 认出 overload，只在还没吐出任何 token 时重试，你取消它就停
scripts/install.ps1 / uninstall.ps1	Windows：隐藏启动器、看门狗、配置片段
scripts/install-mac.sh / uninstall-mac.sh	macOS：带 KeepAlive 的 LaunchAgent
tools/capture_server.py	测出你客户端实际发出的请求体大小
tools/analyze_log.py	从 relay.log 汇总尝试次数与体积的关系
tools/check_console_flash.py	Windows：证明启动器真的不闪窗
docs/findings.md	完整的实测记录
docs/windows-no-console-window.md	为什么 -WindowStyle Hidden 不管用，有实测数据

校验下载

ca268eaa4ba21a9c4d53a78bd8e74580823955526539963e6b138dff7ded1895  codex-overload-fix-1.1.0.zip

也作为 .sha256 附件提供。或者让你的 shell 帮你算：

Get-FileHash .\codex-overload-fix-1.1.0.zip -Algorithm SHA256     # Windows

shasum -a 256 codex-overload-fix-1.1.0.zip                        # macOS

已知局限

• 它不是模型降智的解药。 如果模型本身答得不如以前了，这里没有任何东西能改变它。中继只负责让满载报错不再打断你，不能让模型变聪明。
• 单机、单账号、样本小。体积相关性是信号，具体百分比当噪声看。
• 没有排除重试后被路由到其他模型的可能性。中继同时记录了 model=（客户端发的）和 served=（服务端报的），所以可以核对 —— 欢迎提供任何一方的证据。
• 启动脚本提供了 Windows 和 macOS 两份。中继本身跨平台，其他系统直接 python3 relay/relay.py 跑即可。
• macOS 这条路在 GitHub 的 macos-latest runner（arm64、较新 macOS）上验证过。Intel Mac 和更老的系统还没测，出问题请开 issue。
• 治不了额度真正用尽、登录过期、网络不通。那些是不同的错误，会原样透传。

MIT 许可。随便 fork、随便内嵌到你自己工具里。