Best practicesCodex CLI

Codex CLI

Configure Codex CLI as an OpenAI-compatible client and route agent requests through Velrix. This keeps model choice, spend, and fallback behavior in the dashboard instead of scattering provider settings across local projects.

Use a dedicated Velrix API key for each Codex workspace.

Keep provider wiring in Codex config and routing policy in Velrix.

Prefer gpt-5.4 until a workflow needs a pinned catalog model.

Configuration

Configure Codex

Add Velrix as a Codex model provider, then select that provider at the root of the config. Keep root keys before TOML tables.

config.toml

# ~/.codex/config.toml
model_provider = "velrix"
model = "gpt-5.4"

[model_providers.velrix]
name = "Velrix"
base_url = "https://api.velrix.ai/v1"
wire_api = "responses"
env_key = "VELRIX_API_KEY"
env_key_instructions = "Set VELRIX_API_KEY in your shell or secret manager"

Project config.toml

# .codex/config.toml
# Optional project-scoped override for this repository.
model_provider = "velrix"
model = "gpt-5.4"

Keep config stable

Codex supports global config at ~/.codex/config.toml and project-scoped config at .codex/config.toml. Put the provider definition in the global file when multiple repositories use the same Velrix key, and use project config only for local defaults such as model or approval policy.

Secrets

Environment variables

Store the Velrix key in your shell or secret manager. Avoid committing keys into project files or prompt examples.

Shell

export VELRIX_API_KEY="vk_live_..."
codex

# One-off model override when needed:
codex --model gpt-5.4

API key

Read by Codex through env_key.

VELRIX_API_KEY

Base URL

OpenAI-compatible Velrix endpoint.

https://api.velrix.ai/v1

Routing

Model routing

Start with automatic routing, then pin model IDs only when a project needs deterministic behavior or a specific provider capability.

Default policy route

Use gpt-5.4 for most Codex sessions so Velrix can balance capability, health, cost, and latency.

Pinned catalog model

Choose a concrete model from the catalog when tests or review workflows require stable output characteristics.

Research

References

These external references informed the Codex CLI configuration fields shown above.

OpenAI Codex sample configuration

Official config.toml examples for model providers, env_key, base_url, and project-scoped config.

OpenAI Codex configuration reference

Reference for model_provider, provider definitions, profiles, sandboxing, and approval settings.

Operations

Verify traffic

After the first request, confirm the traffic is attributed to the expected key and route.

View request logs Check usage