Codex

Codex is OpenAI's open-source coding agent for the terminal and IDE. Current versions only use the OpenAI Responses API. SCX.ai serves that API at https://api.scx.ai/v1/responses, so you can add SCX.ai to Codex as a custom model provider and use any chat model on your account.

This guide sets up the provider, then adds a profile so you can switch between a reasoning model and a fast one with a flag.

What you'll connect

ProfileUse it forSCX.ai model
defaultPlanning, refactors, debuggingcoder
fastQuick edits, scripted codex exec runsMiniMax-M2.7

You can use any chat model on your account in place of these IDs. Browse the catalogue. Pick models that support tool calling, because Codex runs shell commands and applies patches through tools.

Prerequisites

  • A SCX.ai API key. Create one in the dashboard under API Keys.
  • macOS, Linux, or Windows (WSL recommended).
  • Node.js 18 or later, only if you install with npm.

Quick connect

Install Codex

npm install -g @openai/codex

Check that it installed:

bash
codex --version

Export your API key

Codex reads the key from the environment variable you name in the provider's env_key. Add the variable to your shell profile so every new terminal has it:

bash
echo 'export SCX_API_KEY="your-scx-api-key"' >> ~/.zshrc
source ~/.zshrc

On bash, use ~/.bashrc instead of ~/.zshrc.

Register SCX.ai as a provider

Create ~/.codex/config.toml, or add these lines to the one you already have:

~/.codex/config.toml
model_provider = "scx"
model = "coder"

[model_providers.scx]
name = "SCX.ai"
base_url = "https://api.scx.ai/v1"
env_key = "SCX_API_KEY"
wire_api = "responses"

Start a session

Open a new terminal, change into a project, and run:

bash
codex

The header at the top of the session shows the active model and provider. Run /status to see them again later.

Full configuration

The quick-connect config is enough to start. The version below adds the model's context window (Codex doesn't know it for models outside OpenAI's catalogue), retry tuning, and the Context7 MCP server for up-to-date library docs.

~/.codex/config.toml
model_provider = "scx"
model = "coder"
model_context_window = 191000

[model_providers.scx]
name = "SCX.ai"
base_url = "https://api.scx.ai/v1"
env_key = "SCX_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
  • model_context_window: tells Codex the model's real context size, so it compacts the conversation before it overflows. Don't add model_max_output_tokens: Codex rejects it as an unknown key.
  • request_max_retries / stream_max_retries: how many times Codex retries a failed request or a dropped stream before giving up.
  • stream_idle_timeout_ms: how long Codex waits on a silent stream. Reasoning models can pause for a while before their first token, so allow a generous value.
  • [mcp_servers.context7]: adds Context7's resolve_library_id and query_docs tools. Run codex mcp list to check that the server shows as enabled, or /mcp inside a session.

Add a fast profile

Each profile is its own file next to config.toml, named <profile>.config.toml. It uses the same top-level keys as config.toml, not a [profiles.…] table, and it overrides only the keys it sets. Create ~/.codex/fast.config.toml:

~/.codex/fast.config.toml
model_provider = "scx"
model = "MiniMax-M2.7"

Select it with --profile fast. Older Codex releases read [profiles.fast] tables inside config.toml instead. If you're on one of those, upgrade rather than mixing the two formats.

Switching models

  • codex --profile fast starts a session with the fast profile's settings.
  • codex -m MiniMax-M2.7 overrides the model for one launch.
  • /model in a session switches the model without restarting.
  • codex -c model=MiniMax-M2.7 overrides any config key from the command line, which helps in scripts.

Non-interactive runs

codex exec runs one task and exits. Use it for CI jobs, git hooks, or batch refactors:

bash
codex exec --profile fast "Add JSDoc comments to every exported function in src/utils"

It uses the same provider, key, and profiles as the interactive CLI.

Approvals and sandboxing

Codex runs commands in a sandbox and asks before it does anything outside that sandbox. Choose how much freedom it has:

FlagBehavior
--sandbox read-onlyReads files and proposes changes. Writes nothing
--sandbox workspace-writeEdits files inside the project. Nothing outside it
--ask-for-approval on-requestThe model asks for your approval when it needs to step outside the sandbox
--ask-for-approval neverNever asks. Failed commands go straight back to the model

For everyday interactive work, let Codex edit the project and ask before anything else:

bash
codex --sandbox workspace-write --ask-for-approval on-request

The --full-auto shortcut from older guides no longer exists. Use the two flags above. codex exec never stops to ask, so it only takes --sandbox.

These settings live on the client, so they work the same with SCX.ai as with any other provider.

Verify the connection

Before relying on Codex, check the key and endpoint directly against the Responses API:

bash
curl -sS "https://api.scx.ai/v1/responses" \
  -H "Authorization: Bearer $SCX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"coder","input":"Say hi."}' \
  | jq '.output[] | select(.type == "message") | .content[0].text'

If you get a normal reply, the same credentials Codex uses are reaching SCX.ai. This only proves the key and endpoint, though. Codex sends a much larger request (its tool definitions, earlier turns), so finish with a real run:

bash
codex exec "Reply with the single word: ok"

If that prints ok, Codex works end to end.

Tips

  • AGENTS.md still works. Codex reads project instructions from AGENTS.md on the client, so it works the same with any backend.
  • Use the fast profile for codex exec. Scripted runs tend to be many small, well-scoped tasks, where a fast model is cheaper and finishes sooner.
  • Ask Codex to verify its work ("run the tests and confirm they pass"). Otherwise it tends to stop once the edit is made.
  • Keep the key in the environment, not in config.toml. env_key names a variable, so the file is safe to share or commit to a dotfiles repo.

Common gotchas

  • `wire_api = "chat"` is no longer supported. The config comes from an older guide. Change it to wire_api = "responses", or delete the line, since responses is the default.
  • 401 Unauthorized. Codex couldn't find a valid key. Check that env_key matches the exported variable's name exactly (SCX_API_KEY), and launch Codex from a shell where echo $SCX_API_KEY prints the key.
  • 404 Not Found. base_url must end in /v1 (https://api.scx.ai/v1). Codex adds /responses itself.
  • "Unknown server tool type". Codex sent a tool type that SCX.ai doesn't run. The error names the type and lists the supported ones. Turn off the Codex feature that adds that tool.
  • "stream disconnected before completion". A network blip or a long silent reasoning phase. Raise stream_idle_timeout_ms and stream_max_retries, then send the message again.
  • "Model metadata for coder not found" warning. Codex prints this for every model outside OpenAI's catalogue, even with model_context_window set. It's harmless.
  • 429 Too Many Requests. You've hit a rate or spend limit. Codex makes one request per step (every command it runs is another round trip), and each request carries its full tool list, so a single task can use up a low per-minute limit. Keep request_max_retries above zero so Codex waits and retries, or check your limits in Endpoints & limits.