Restore missing Codex tools when GPT-5.6 Sol, Terra, or Luna is used through a custom OpenAI-compatible provider.
简体中文 · Download v0.2.1 · Automated tests
You may need this tool if Codex can still chat, but after selecting one of those models it no longer:
- runs shell/exec commands or code mode;
- calls functions, MCP servers, collaboration, or extension tools;
- exposes another tool that used to be available, such as Web Search.
Codex may describe what it would do but return only text. If the same tools work after switching to another model, and you configured a custom provider, run doctor to check this compatibility issue.
You do not need to inspect traffic, learn a provider protocol, call an API by hand, or edit JSON/TOML. The normal path is:
download and verify -> doctor -> apply -> fully restart Codex -> create a new task
This is an unofficial community project. It is not an OpenAI product and is not endorsed by OpenAI or by any API provider.
This project was created to work around Codex tool-calling compatibility issues that may occur when Responses Lite models are used through certain custom OpenAI-compatible providers.
Since this project was released, several upstream gateways and proxy projects have added compatibility handling or merged fixes for Codex's Responses Lite request format, including support for tool declarations carried through additional_tools.
As a result, this patch should no longer be treated as a default requirement for using a custom provider.
If your local AI assistant can use a terminal, access local files, and download files, you can give it the prompt below. It will inspect and run the tool for you. You only need to approve once before it applies the patch.
Help me safely check and, if applicable, install Codex Provider Compatibility on this computer.
Follow these rules:
1. Use only the official GitHub repository https://github.com/Hyacehila/codex-provider-compat and its latest stable, non-prerelease Release. Do not prefer cloning the source repository, and do not use opaque commands such as curl | sh or irm | iex.
2. Detect whether this computer is running Windows or macOS. Download the matching Release ZIP and SHA256SUMS.txt, verify the ZIP's SHA-256 against the published entry, extract it to a temporary directory, and inspect the included README and script before running anything.
3. Run doctor first. It must be read-only. If the checksum fails, the Release is unsuitable, doctor says the patch is not applicable, versions conflict, recovery is required, or any state is unsafe or ambiguous, stop without applying changes and explain the result simply.
4. If doctor confirms that apply is appropriate, tell me exactly what the script will change and back up, then ask me for one explicit confirmation. Do not apply before I confirm. After confirmation, run apply with --yes so no second confirmation is needed.
5. After apply succeeds, run status and report whether the patch is healthy, together with the generated catalog, configuration backup, cache backup, and state-file locations reported by the script.
6. Do not read auth.json, API keys, tokens, or provider credentials. Do not call a real provider or perform billable model or search requests. Do not print or upload private configuration or diagnostics.
7. Do not modify Codex binaries, application packages, source code, servers, or provider configuration. Do not manually edit JSON or TOML, bypass the script's safety checks, or use the removed --enable-web-search option.
8. If you do not have terminal, local-file, or download access, stop and tell me to follow the manual instructions in the repository README instead. Never claim success without completing the checks.
9. When finished, remind me to fully quit and restart Codex, then create a new task. Reopening an old task is not enough.
The AI must have access to the computer where Codex is installed. A chat-only assistant cannot perform these steps; use the manual method below instead.
The complete manual procedure remains available below.
The patch targets only GPT-5.6 Sol (gpt-5.6-sol), Terra (gpt-5.6-terra), and Luna (gpt-5.6-luna) when used with a custom provider. It is not intended for other models or Codex's built-in OpenAI connection.
Always run doctor first. It checks local versions, configuration, and safety without writing files. If the script cannot prove that a change is safe, it stops and leaves the active configuration alone.
Open the v0.2.1 Release page, then download SHA256SUMS.txt and the ZIP for your platform:
| Platform | File |
|---|---|
| Windows | codex-provider-compat-v0.2.1-windows.zip |
| macOS | codex-provider-compat-v0.2.1-macos.zip |
Verify the Windows ZIP:
(Get-FileHash .\codex-provider-compat-v0.2.1-windows.zip -Algorithm SHA256).Hash.ToLowerInvariant()
Get-Content .\SHA256SUMS.txtVerify the macOS ZIP:
shasum -a 256 ./codex-provider-compat-v0.2.1-macos.zip
cat ./SHA256SUMS.txtThe computed value must match the ZIP's entry in SHA256SUMS.txt. Extract the package and inspect its README and script before running it. Standalone .ps1 and .sh assets are also provided. This project does not recommend opaque curl | sh or irm | iex commands.
Windows PowerShell 5.1 and PowerShell 7.5 or later are supported. No extra runtime is required.
Get-Content .\codex-provider-compat.ps1
.\codex-provider-compat.ps1 doctor
.\codex-provider-compat.ps1 applyIf Windows blocks the verified script, use a process-only execution-policy override:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\codex-provider-compat.ps1 doctor
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\codex-provider-compat.ps1 applyThe script uses only tools included with macOS; Homebrew, Python, Node, and jq are not required.
less ./codex-provider-compat.sh
chmod +x ./codex-provider-compat.sh
./codex-provider-compat.sh doctor
./codex-provider-compat.sh applyAfter apply succeeds, fully quit and restart Codex, then create a new task. Old tasks keep the model and tool snapshot captured when they started, so reopening one is not enough.
This tool does not enable, disable, or otherwise manage individual tools.
.\codex-provider-compat.ps1 status
.\codex-provider-compat.ps1 rollback./codex-provider-compat.sh status
./codex-provider-compat.sh rollbackRollback removes only changes owned by this tool and preserves unrelated edits made after apply. Restart Codex and create a new task after rollback.
If doctor or status reports recovery-required, do not delete lock, transaction, or pending files. Run the intended apply or rollback again so it can recover the interrupted operation. A healthy user-level patch can still be superseded by a selected profile, project configuration, or CLI override.
After a Codex update, run status and doctor again. Do not keep an old catalog override across an unreviewed version change.
If you used the removed v0.1.1 --enable-web-search option and want the tool to stop owning that legacy change, use v0.2.0 or later to run rollback, restart Codex, then run a normal apply and restart into a new task. The new version does not alter your search setting.
| Command | Purpose |
|---|---|
doctor |
Read-only applicability and safety check |
apply |
Validate, back up, and install the patch |
status |
Check the installed patch and version |
rollback |
Undo only changes owned by this tool |
Both scripts accept --yes, --dry-run, --codex-home <absolute-path>, --codex-version <version>, and --catalog-file <absolute-path>. Most users need none of these. Codex home and version are discovered automatically; a version conflict stops apply.
The standalone CLI, Codex Desktop, and app-server components can update independently while sharing one Codex home and model catalog. When different versions are detected, the tool refuses to choose automatically. Use --codex-version only when you know which CLI or Desktop surface you will fully restart and use after applying the patch.
| Exit | Meaning |
|---|---|
| 0 | Success or healthy state |
| 1 | General usage or operation error |
| 2 | Not applicable, not installed, or already fixed upstream |
| 3 | Unsafe, ambiguous, corrupt, drifted, or recovery-required state |
| 4 | Patch or official catalog format is no longer compatible |
| 5 | Official catalog download, HTTP, timeout, or size failure |
Codex's model catalog marks the three target models to use an internal request format called Responses Lite. In this mode, Codex describes client tools through additional_tools instead of the standard top-level tools field used by the public Responses API.
The built-in OpenAI path understands this format. Many custom OpenAI-compatible providers implement the public Responses format but not Codex's extra Lite format. They receive no standard tool definitions, so text can still work while terminal, function, MCP, collaboration, extension, or hosted tools disappear.
target model uses Responses Lite
-> Codex sends internal additional_tools
-> standard top-level tools are absent or null
this patch disables Lite for the three target models
-> Codex sends standard Responses tools again
-> the provider can expose the tools it supports
Lite also changes instructions, parallel tool calls, reasoning context, image detail, and internal headers or metadata. Search is one possible affected tool, but the patch does not configure search or guarantee that a provider implements it.
The patch ID is responses-lite-standard-tools. The script detects the Codex version, obtains the complete model catalog from its matching official openai/codex tag, and changes only use_responses_lite from true to false for Sol, Terra, and Luna. Any missing target, incomplete catalog, duplicate model, wrong field type, or other semantic change stops the operation.
It writes the generated catalog inside the selected Codex home, backs up configuration and model cache files, updates only the user-level model_catalog_json, and records the minimum state needed for status, recovery, and rollback. It does not change the selected model, provider, provider table, individual tool settings, or unrelated configuration.
Persistent Codex changes stay inside the selected Codex home. The scripts validate paths and ownership, reject Windows junction/reparse-point and macOS symlink escapes, preserve unrelated TOML content and permissions, and use locks, backups, atomic replacement, and a transaction journal. Ambiguous or unsafe state fails closed.
The production tool does not read auth.json or API keys, call provider APIs, upload data, collect telemetry, host secrets, modify Codex binaries/source, modify any server, or proxy API traffic.
The patch restores standard tool definitions; it cannot make a provider implement a tool it does not support. Automated tests cover Windows PowerShell 5.1/7, macOS shell/JXA behavior, catalog and TOML integrity, path safety, failure recovery, release packages, and Lite-versus-standard request shapes against localhost.
Real macOS Codex Desktop behavior also remains not-run because this project does not currently have a Mac Desktop test environment. Results from one provider must not be generalized to every OpenAI-compatible service.
The project uses the MIT License. The catalog downloaded at runtime comes from the Apache-2.0 openai/codex repository; see THIRD_PARTY_NOTICES.md.