Codex

Set up automatically

Run the Gradiated wizard:

npx -y @gradiated/wizard --agent codex

The wizard adds a Gradiated provider and a gradiated profile. It stores the API key outside the Codex configuration and leaves your default profile alone.

Start Codex with the Gradiated profile:

codex --profile gradiated

Set up manually

Use manual setup if you do not want the wizard to change your Codex files.

Set your Gradiated API key in the shell that starts Codex:

export GRADIATED_API_KEY="grad_..."

Add the provider

Add this block to ~/.codex/config.toml:

[model_providers.gradiated]
name = "Gradiated"
base_url = "https://api.gradiated.com/v1"
env_key = "GRADIATED_API_KEY"
wire_api = "responses"

Keep this provider in your user configuration. A project-level Codex file can change the setup for everyone who opens the repository.

Add the profile

Create ~/.codex/gradiated.config.toml:

model_provider = "gradiated"
model = "YOUR_MODEL"

Replace YOUR_MODEL with a model from models and pricing.

Start Codex with this profile:

codex --profile gradiated

Add -m YOUR_MODEL to select another Gradiated model for one run.

Troubleshooting

• Check that GRADIATED_API_KEY is set in the shell that starts Codex.
• Check that the provider base URL is https://api.gradiated.com/v1.
• Check that the model matches the Gradiated catalog.
• Use codex exec --profile gradiated --strict-config to find configuration errors.
• Check that the workspace has billing capacity.

Uninstall

Run the uninstall command:

npx -y @gradiated/wizard uninstall

Select Codex. The wizard removes the provider, profile, and stored credential. It keeps timestamped backups and does not change your default profile.