Codex CLI: API key and custom provider setup

Use this guide to connect local Codex CLI work to AI Prime Tech. You need a gateway account, an active key in the intended Codex group and a model available to that key. Start with the Codex API overview if you are still choosing an access type.

1. Check the key and group

Create a key in the dashboard. Prepaid GPT access uses the Codex group. If timed Codex access is offered, use the group and terms shown for that plan; Claude access is separate. Confirm the model list for the key you will use.

Set the key in the current terminal. Replace the placeholder locally; do not commit the key to a repository.

PowerShell

$env:AIPRIMETECH_API_KEY = "YOUR_GATEWAY_KEY"

bash or zsh

export AIPRIMETECH_API_KEY="YOUR_GATEWAY_KEY"

Restart a terminal or editor launched before you set its environment if it cannot see the variable. These examples set it for the current process and its children.

2. Configure the provider

Merge this into your user-level ~/.codex/config.toml. On Windows, the equivalent path is %USERPROFILE%\.codex\config.toml. Provider credentials belong in user configuration, not a repository's .codex/config.toml.

model_provider = "aiprimetech"
model = "gpt-6.1-sol"

[model_providers.aiprimetech]
name = "AI Prime Tech"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIMETECH_API_KEY"
wire_api = "responses"
supports_websockets = false

Use a provider ID such as aiprimetech and keep model_provider matched to its table. Current Codex uses the Responses protocol. The base URL is the gateway's /v1 root; Codex adds the request path. This configuration uses HTTP/SSE transport.

3. Verify the connection

Run codex doctor to inspect your CLI configuration. Start codex, then use /status to confirm the provider and model. Ask for a short answer before allowing a larger repository task. Check that the request appears in your AI Prime Tech usage page.

You can inspect the key's model list independently of Codex:

Invoke-RestMethod -Uri "https://aiprimetech.io/v1/models" -Headers @{Authorization="Bearer $env:AIPRIMETECH_API_KEY"}

curl --fail-with-body https://aiprimetech.io/v1/models \
  -H "Authorization: Bearer $AIPRIMETECH_API_KEY"

If the returned catalogue includes your model but the request fails, check the actual error and current group availability. A listed ID alone is not a successful inference test.

Keep an optional CLI profile

To select this provider only for particular CLI sessions, put the configuration above in ~/.codex/aiprimetech.config.toml and launch:

codex --profile aiprimetech

In Codex 0.134.0 and later, CLI profiles use separate files. Older [profiles.aiprimetech] examples are not the current profile format. The IDE extension uses user-level configuration; verify its active provider after restarting it rather than assuming the CLI profile switch applied there.

Choose a model

Use gpt-6.1-sol as a starting point for coding, gpt-6-astra for demanding tasks, or gpt-6-luna for focused work. gpt-6-sol is a separate ID for existing Sol workflows. See model details and how to compare them.

Troubleshooting

Symptom	Check
Missing environment variable	Set `AIPRIMETECH_API_KEY` in the process that launches Codex.
401 authentication error	Confirm the key is active, copied completely and issued by this gateway.
403 or unavailable model	Confirm key group, plan access and the exact model ID.
404 or an HTML response	Use `https://aiprimetech.io/v1`; remove duplicate `/v1` or an appended `/responses`.
`wire_api` rejected	Use `responses`; old `chat` provider examples are obsolete.
Balance, plan or rate-limit error	Read the error, check your account and reduce concurrent work before retrying.
Connection ends mid-response	Try one short request, check network/proxy connectivity and capture the request ID for support.

Claude and hosted Codex features

For Claude through the gateway's Responses translation, follow Claude with Codex using a compatible Claude-group key. The GPT example above is for Codex-group access.

Gateway access does not supply ChatGPT workspace entitlements or Codex cloud access. See the sign-in comparison for the product boundary.