npx vercelai-gatewaysetup--agentcodex

The command configures everything Codex needs to route through the gateway:

• Provisions an AI Gateway API key, or reuses one you pass with --key
• Writes ~/.codex/config.toml with a vercel model provider pointed at the Codex compatibility endpoint ( wire_api = "responses")
• Exports AI_GATEWAY_API_KEY from a managed block in your shell startup file, backed by the macOS Keychain when available so the key stays out of plaintext config
• Copies your existing Codex Desktop sessions across (see session migration)

Every file the command changes is backed up alongside as a .bak file. Pass --dry-run to preview the changes without writing them. For the full command reference, see vercel ai-gateway setup.

To configure every installed supported agent at once, run the command without --agent. It detects and configures each supported agent it finds:

1. Install OpenAI Codex CLIFollow the installation instructions on the OpenAI Codex repository to install the Codex CLI tool.
2. Configure environment variablesSet your AI Gateway API key in your shell configuration file, for example in ~/.zshrc or ~/.bashrc: export AI_GATEWAY_API_KEY="your-ai-gateway-api-key"After adding this, reload your shell configuration:

   source~/.zshrc# or source ~/.bashrc

3. Set up the Codex config fileOpen ~/.codex/config.toml and add the following:

   

   

   model_provider ="vercel"

   model ="openai/gpt-6-astra"

   [model_providers.vercel]

   name ="Vercel AI Gateway"

   base_url ="https://ai-gateway.vercel.sh/codex/v1"

   env_key ="AI_GATEWAY_API_KEY"

   wire_api ="responses"

   The configuration above:
   • Sets up a model provider named vercel that points to the Codex compatibility endpoint
   • References your AI_GATEWAY_API_KEY environment variable
   • Sets the vercel provider as the default for all sessions
   • Uses the Responses API, which is the only wire protocol current Codex versions support
   • Specifies openai/gpt-6-astra as the default model
4. Run CodexStart Codex: codexVercel AI Gateway routes your requests. To confirm, check your AI Gateway Overview in the Vercel dashboard.

Enable WebSocket streaming

Codex can stream Responses API traffic over a persistent WebSocket connection, reducing per-turn latency. This uses AI Gateway's Responses API WebSocket mode. Enable it in your config:

[features]

responses_websockets_v2 =true

[model_providers.vercel]

name ="Vercel AI Gateway"

base_url ="https://ai-gateway.vercel.sh/codex/v1"

env_key ="AI_GATEWAY_API_KEY"

wire_api ="responses"

supports_websockets =true

model ="openai/gpt-5.5-pro"

# Or try other models:

# model = "openai/gpt-5.4-mini"

# model = "openai/gpt-5.4-nano"

Every model in the gateway catalog works here, not only OpenAI ones. The examples stay on OpenAI models because Codex reads their metadata natively.

Define multiple profiles

Profiles let you switch models from the CLI. Create a file named ~/.codex/.config.toml for each profile, using top-level keys for the values that differ from your base config:

[profiles.] tables or the profile selector from config.toml. If you have legacy profile tables, move each one into its own ~/.codex/.config.toml file.

Keeping your Codex Desktop sessions

Codex records each session against the provider that served it, so switching to the gateway hides the sessions you created before the switch. To bring them across, re-run the Vercel CLI setup command:

vercel ai-gatewaysetup--agentcodex

The command copies each rollout file under sessions and archived_sessions to a new deterministic session ID with model_provider set to vercel. Originals are never moved, edited, or deleted, and re-running never duplicates a session it already copied. Pass --no-session-migration to skip the step, and decompress any .jsonl.zst sessions first, since compressed rollouts can't be rewritten. See session migration for details.