Codex 0.147 Breaks Custom Providers? Pin 0.146.0

If Codex CLI 0.147.0 suddenly fails through LiteLLM, Azure OpenAI, or another custom Responses provider, preserve the provider configuration and compare versions before changing credentials. Fresh upstream reports show two failures introduced after upgrading from 0.146.0: a misleading high-demand message after repeated stream disconnects, and an Azure validation error for an empty tool-namespace description. Both reporters restored the same provider path by returning to 0.146.0.

These reports do not prove that every custom provider is broken. They do establish a narrow, reversible diagnostic: hold the endpoint, model, credentials, prompt, and configuration constant; compare 0.147.0 with 0.146.0; and stay on the working version until an upstream release passes the same canary.

Match the Failure Before You Roll Back

This guide applies when all of these are true:

• codex --version reports 0.147.0.

• Codex uses a custom provider with wire_api = "responses".

• The provider worked before the Codex upgrade.

• The same endpoint still works through another approved client, or Codex 0.146.0 succeeds without a provider-side change.

The current reports show two signatures:

Do not assume that every 429, 400, or disconnected stream is this regression. A real provider outage, an expired credential, a bad deployment name, a proxy policy, or a model routing change can produce adjacent symptoms.

Record the exact error, UTC time, codex --version, provider name, model name, operating system, installation method, and whether a sanctioned non-Codex client still succeeds. Redact tokens, gateway hostnames, request headers, tenant IDs, and proprietary prompts before sharing logs.

Prove the Version Boundary

First save your work and let active Codex turns finish. Then record which executable is running:

codex --version
command -v codex

On PowerShell:

codex --version
Get-Command codex

Run one disposable canary on 0.147.0:

codex exec --ephemeral --skip-git-repo-check "Reply with exactly: OK"

Expected failure evidence is one of the two signatures above. Stop after one bounded attempt. Repeated retries add noise and can consume provider capacity without distinguishing a Codex regression from an upstream outage.

If the custom provider is centrally managed, ask its owner to confirm only whether the same model and endpoint work through another approved client. Do not ask for the gateway credential or copy it into a diagnostic chat.

Pin the Confirmed Working Version

Use the same installer that owns the current Codex executable. Do not mix a package-manager installation with a release binary or leave multiple codex commands on PATH.

For a pnpm-managed global installation, pin the version used in the upstream reproductions:

pnpm add --global @openai/codex@0.146.0
hash -r
codex --version

Expected result: the final command reports codex-cli 0.146.0 or the equivalent 0.146.0 version string.

If your executable came from another manager or an official release archive, install the matching 0.146.0 artifact through that same path. Do not download a binary from an unofficial mirror. The official Codex release history is the source of truth for versioned assets.

This is a temporary compatibility pin, not a permanent security policy. Keep the change scoped to the Codex executable. Do not rewrite ~/.codex/config.toml, rotate API keys, change the provider URL, disable TLS verification, or add a proxy mutation that fills the empty description unless your gateway owner has reviewed that change.

Repeat the Same Canary

Run the identical prompt with the identical provider configuration:

codex exec --ephemeral --skip-git-repo-check "Reply with exactly: OK"

The version comparison is meaningful only if you change one variable. Success means all of the following are true:

• Codex returns OK on 0.146.0.

• The LiteLLM path does not exhaust stream retries.

• The Azure path does not reject an empty tool description.

• The provider endpoint, model, credential, and prompt are unchanged.

• No repository file changes.

If 0.146.0 fails with the same symptom, the version boundary is not confirmed. Restore the version you are meant to run, then investigate provider health, authentication, deployment routing, proxy transformations, and model availability with the provider owner.

Why Disabling One Tool Feature Is Not Enough

The Azure report isolated a request-shape error: Codex 0.147.0 wrapped default tools in a functions namespace whose description was empty, while Azure requires at least one character. Replaying the request with a non-empty description succeeded. The reporter also found that disabling only code_mode_host did not remove the empty namespace.

That evidence makes random feature toggles a poor first response. A local flag can hide a symptom without proving compatibility, and a proxy rewrite can alter requests for every caller. The clean comparison is still the same request through 0.147.0 and 0.146.0.

The LiteLLM report has a different visible error, so do not claim that the empty namespace is its confirmed root cause. Its strongest evidence is the controlled version comparison: 0.147.0 failed after repeated stream reconnects, while 0.146.0 succeeded with the same gateway, models, and configuration.

Know When to Stop

Stop the rollback path and escalate when any of these are true:

• your organization requires 0.147.0 for a security or compliance reason;

• the same provider fails in approved non-Codex clients;

• 0.146.0 fails the identical canary;

• the only available workaround requires changing shared gateway traffic;

• logs cannot be sanitized without exposing confidential infrastructure.

When reporting upstream, add a redacted reproduction to the matching issue instead of opening a duplicate. Include the two-version matrix, exact error, provider class, operating system, installation method, and whether the direct or alternative-client check passed. Never attach credentials or an unredacted serialized request.

Retest the Next Stable Release

Do not remain pinned silently. Watch the upstream issues and Codex releases. When a stable release claims or appears to include a provider-compatibility fix, install it through the same manager and run two identical canaries before resuming normal work.

The first canary should use no agent-facing tools beyond the default request. The second should exercise one harmless read-only tool call through the same provider. Keep 0.146.0 available until both pass without the high-demand retry loop or Azure validation error.

Monitor the Regression Without Exposing Provider Secrets

After the provider path works again, use typed read-only Actions instead of pasting gateway credentials into prompts. Aident Loadout can check account and Vault status, discover the current GitHub issue-search Action, inspect its schema, and estimate cost before execution.

Give Codex the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then use this prompt:

Check my Aident Loadout account authentication and Vault status. Search the staging capability catalog for a connected read-only GitHub issue-search Action, inspect its current schema, and preflight it. If the estimate is free, search the openai/codex repository for issues 37425, 37380, and 37432 and return only their state, updated time, title, and URL. Do not comment, edit, close, label, publish, install, change files, start OAuth, or ask me for a provider credential.

Success is measurable: account and Vault checks complete; discovery, schema inspection, and preflight succeed; the read-only search returns the three tracked reports; no GitHub write occurs; and no provider secret enters the prompt or output. Set up Aident Loadout and monitor the regression.

Sources

• OpenAI Codex issue 37425: LiteLLM streaming regression in 0.147.0

• OpenAI Codex issue 37380: Azure rejects the empty functions namespace description

• OpenAI Codex issue 37432: independent Azure 0.147.0 regression report

• Official OpenAI Codex releases

• Official OpenAI Codex configuration documentation

• Microsoft Foundry documentation for Codex with Azure OpenAI

Refresh this guide when the tracked issues change state, OpenAI publishes a confirmed cause, a stable Codex release passes both provider canaries, or the custom-provider configuration contract changes.