Codex WebSocket validation

Install and check Codex

Use the installation instructions for your operating system in the official Codex CLI guide. Run codex --version to confirm your terminal can find it.

Official Codex CLI installation

Create and copy an API key

If key editing is unavailable, use an existing active key or contact support. Creating a key does not add account balance. The rolling 5-hour, 1-day and 7-day limits are spend limits in USD, not requests per minute.

1. Sign in to the console with your account email and password. Complete the authenticator challenge if your account requires it.
2. Open API Keys and choose Create API key. Give the key a name you will recognize in Usage.
3. Choose an available group if you need a specific model route. Otherwise keep the default assignment.
4. Set a USD quota and optional expiry or IP restrictions, then create the key. A blank or zero quota means unlimited key spend, subject to your account limits.
5. Use Copy API key to copy the complete value. You can also reveal an existing key. Store it in a server-side environment variable.

API KeysPlaygroundUsage

Set your key and choose a model

Replace the key placeholder with the complete key you copied. Choose an exact model ID available to that key; the public catalog is a reference and does not establish account access. These variables last for the current terminal session.

Copy$env:KINETICROUTER_API_KEY = "YOUR_API_KEY"
$env:KINETICROUTER_MODEL = "YOUR_AVAILABLE_MODEL_ID"

Copyexport KINETICROUTER_API_KEY="YOUR_API_KEY"
export KINETICROUTER_MODEL="YOUR_AVAILABLE_MODEL_ID"

Add the kineticRouter provider

Back up ~/.codex/config.toml before editing it. Add the provider below without replacing unrelated settings or defining the same table twice. Keep the API key in the environment variable rather than in the config file.

Copy# Add this provider alongside your existing configuration.
[model_providers.kineticrouter]
name = "kineticRouter"
base_url = "https://api.kineticrouter.com/v1"
env_key = "KINETICROUTER_API_KEY"
wire_api = "responses"

Official custom-provider configuration

Test the provider in a project

Choose a model that your key can access through the Responses protocol. Start Codex with the explicit provider and model below. Review the response and check Usage; do not assume every model supports every protocol.

Copycodex -c model_provider="kineticrouter" -m "YOUR_AVAILABLE_MODEL_ID"

Validate optional WebSocket support

First confirm a normal Responses request works for this key and model. WebSocket behavior depends on the installed client and gateway route. Follow the client’s supported configuration and test it with your account before relying on it. A provider setting alone does not prove transport availability. CC Switch is optional; the manual provider configuration above does not require it.

Troubleshooting

For support, include the time, model, request ID if supplied, and error status. Never send your API key, session cookie, or password. Error details vary by endpoint; use the returned status and message rather than assuming one universal error shape.

1. Authentication failed: copy the complete key again, remove extra whitespace, and check its active status and expiry. Custom keys do not necessarily begin with sk-.
2. Model unavailable or access denied: verify the selected key’s group and available model list. Check IP restrictions and provider route availability.
3. Quota or balance exhausted: inspect the key’s quota and rolling USD limits, then the account balance or subscription usage. Changing a key quota does not fund the account.
4. Request URL not found: use /v1 as the SDK base URL, and /v1/chat/completions for a direct Chat Completions request. Use the protocol supported by your chosen model.
5. Rate-limited or temporarily unavailable: wait before trying again and check service status. Avoid repeatedly resending a request that may already have been processed.
6. Stream stopped: keep the partial answer and check Usage. Start another request only when you want to retry.
7. Playground with an IP-restricted key: the gateway sees the console server’s connection. A key that works from your application may not permit that connection. Keep the restriction unless you intend to change it.