Codex clients (desktop app / IDE extension)

AI Agents overview: tools, API base URLs and FAQs

For terminal setup, see Codex CLI. Find model names in All model IDs; the Codex catalog is at GET https://modelfold.ai/openai/v1/models.

Agent requests spend credits

System instructions, tool definitions and project context can make the first request larger than an ordinary chat. Verify the connection with a short message first.

Download and choose a client

Official entry points checked on November 10, 2026:

Client	Installation and scope
Codex on desktop	The official desktop entry currently redirects to ChatGPT desktop documentation. Follow its macOS / Windows download and choose Codex. Existing standalone Codex installations use the local provider configuration below; menus depend on your version. The page also links Linux instructions.
VS Code / Cursor / Windsurf	Choose your editor on the official IDE page, install the official extension and open the Codex sidebar. Cursor's own model settings do not configure this extension.
Terminal	Follow Codex CLI.

This guide configures local Codex inference, not ordinary ChatGPT chats or cloud tasks. JetBrains and Xcode have separate integrations; the VS Code steps here do not cover them.

Shared configuration

The official gateway guide directs desktop users to local configuration. The configuration guide confirms that CLI and IDE share configuration layers.

Environment	User configuration
macOS / Linux	~/.codex/config.toml
Windows	%USERPROFILE%\.codex\config.toml
WSL / remote development	Configure the environment actually running Codex.

Check the effective directory if you set CODEX_HOME. Back up existing settings and merge fields without duplicate keys or tables.

In the IDE, use the gear icon → Codex Settings → Open config.toml. Desktop has Settings, but the official settings page reviewed here does not document a third-party Base URL / Key form. Follow the file-based gateway setup; ChatGPT sign-in alone does not select ModelFold.

Configure ModelFold

Create a key in Console → API Keys. We recommend GPT‑6.1 Sol, verified below. Its current Codex catalog ID is gpt-6.1-sol; responses report gpt-6-1-sol. Configure the catalog ID. Check All model IDs and the Codex catalog for future changes instead of changing punctuation yourself.

Keep the first three settings above all TOML table headers:

model = "gpt-6.1-sol"
model_provider = "ModelFold"
web_search = "disabled"

[model_providers.ModelFold]
name = "ModelFold"
base_url = "https://modelfold.ai/openai/v1"
env_key = "MODELFOLD_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
model_catalog_url = "https://modelfold.ai/openai/v1/models"

Codex appends /responses. env_key names a variable containing your raw ModelFold key, sent with Bearer authentication. This setup uses HTTP/SSE without ChatGPT authentication or web search. WebSocket and hosted tools were not tested.

The catalog URL supplies Codex metadata. An existing model_catalog_json overrides it; check for stale local catalogs. A list containing only .data[].id is insufficient for custom aliases. See the official catalog guide.

Pass the key to the client process

A terminal variable may not reach an app opened from the Dock or Start menu. Keep real keys out of repositories.

macOS

Replace the placeholder with your key:

export MODELFOLD_API_KEY="mf-your-key"
launchctl setenv MODELFOLD_API_KEY "$MODELFOLD_API_KEY"

Fully quit and reopen the app or editor. This variable lasts for the current user login session; set it again after logout or reboot. Closing a window is not quitting. The command passes a variable to GUI processes without editing Codex configuration.

Windows (PowerShell)

$env:MODELFOLD_API_KEY = "mf-your-key"
[Environment]::SetEnvironmentVariable("MODELFOLD_API_KEY", $env:MODELFOLD_API_KEY, "User")

The first line affects this terminal; the second saves a user variable. Fully quit and reopen the client. If the variable is still missing, sign out of Windows and back in. Configure WSL separately inside WSL.

Linux / launching an IDE from a terminal

export MODELFOLD_API_KEY="mf-your-key"
code .
# For Cursor, use cursor . instead.

Quit existing editor processes first to avoid reusing one with the old environment. Desktop launcher behavior varies by distribution; ensure the client receives the variable.

Verify the connection

Restart the client, open a new conversation and ask it to reply with gateway-ok. Confirm the time and model in Console → Request logs. A reply alone does not identify the provider. This check spends credits.

API verification on November 10, 2026: a dedicated test key, the configured model and Bearer authentication were used against https://modelfold.ai/openai/v1/responses.

Check	Result
Non-streaming	HTTP 200, status: completed
HTTP/SSE streaming	HTTP 200, text deltas and response.completed
Tool call	function_call with valid JSON arguments
Tool-result round trip	function_call_output accepted; HTTP 200 and completed response

These were API/configuration simulations. No desktop or IDE GUI was launched; this is not UI verification for every client version. The test tool returned fixed text without executing project commands.

Common problems

Symptom	Check
Missing MODELFOLD_API_KEY	Pass the variable to the client process and fully restart it.
401	Check the key; do not include Bearer in its value.
404 / unavailable model	Keep the base URL at /openai/v1, use the catalog ID and check for stale catalog overrides.
Still using OpenAI / requesting sign-in	Check the loaded file, provider name, top-level settings and project or managed overrides.
402 / insufficient credits	Add ModelFold credits.
An old conversation retains its model	Restart and create a new conversation; check request logs.
Tools or plugins unavailable	MCP, plugins, cloud tasks and other services need their own setup and authorization.

Next: Codex CLI · All model IDs · Troubleshooting.