Codex | Vtrix API Docs

Overview

Codex is OpenAI’s command-line AI coding assistant. It can read code, edit files, run commands, and help complete development tasks in a local project. By configuring Codex to use Vtrix, you can access GPT series models through one gateway.

Prerequisites

Node.js 18 or higher
Codex CLI
A Vtrix API key, created in Settings

Configuration Steps

Install Codex

• Using npm

npm install -g @openai/codex

After installation, run:

codex --version

Confirm that Codex is installed correctly.

Configure Vtrix API

Codex reads model service settings from ~/.codex/config.toml. Switch the default model provider to vtrix, and let Codex read the API key from the VTRIX_API_KEY environment variable.

• Create config directory

mkdir -p ~/.codex

• Set API Key

Add the following to ~/.bashrc or ~/.zshrc:

export VTRIX_API_KEY="sk-xxxxxxx"

After updating the file, restart your terminal or run:

source ~/.zshrc

• Configure Codex

Edit ~/.codex/config.toml:

vim ~/.codex/config.toml

Add or update the following configuration:

model_provider = "vtrix"
model = "gpt-5.5"
model_reasoning_effort = "medium"
preferred_auth_method = "apikey"

[model_providers.vtrix]
name = "vtrix"
base_url = "https://cloud.vtrix.ai/llm/openai/v1"
env_key = "VTRIX_API_KEY"
wire_api = "responses"

Fields to note:

model = "gpt-5.5" sets the default model used by Codex
model_reasoning_effort = "medium" sets the default reasoning effort, which can be changed to low, high, or xhigh
base_url = "https://cloud.vtrix.ai/llm/openai/v1" is the OpenAI Responses-compatible endpoint
env_key = "VTRIX_API_KEY" tells Codex to read the API key from that environment variable

Tip

env_key is the environment variable name. Configure your actual API key in the corresponding environment variable.

Switch models

To switch models, change only the model value.

Type	Recommended model	Description
Agentic coding	`gpt-5.3-codex`	Optimized for Codex and agentic coding tasks
High performance	`gpt-5.5`	Strong reasoning, suitable for complex development tasks
Standard	`gpt-5.4`	Balanced for everyday development

Tip

View all models, capabilities, and pricing on the Models page. Prefer models that support tool calling and long context.

Start a session

Go to your project directory and start Codex:

cd /path/to/your/project
codex

After the configuration takes effect, Codex requests will be routed through Vtrix.

• Verify configuration

Run a simple task to confirm the connection:

codex "Summarize this project in one sentence"

If Codex responds normally, the model and API key are working.

You can also check usage or billing in Vtrix Settings to confirm that requests are reaching your account.

Troubleshooting

Error: 401 Unauthorized

Cause: The API key is missing, incorrect, or not loaded in the current terminal session.

Fix:

echo $VTRIX_API_KEY

Confirm that your API key is printed. If it is empty, check ~/.zshrc or ~/.bashrc, then reopen your terminal.

Error: 404 Not Found or model not found

Cause: The model value is incorrect, or the model ID does not exist.

Fix: Open the Models page, copy the correct model ID, and update ~/.codex/config.toml.

Error: Connection error or request timeout

Cause: The task is too large, the network is unstable, or the model response takes too long.

Fix: Split the task into smaller steps, for example:

First inspect the project structure. Do not modify files. Summarize your findings and wait for confirmation.

Or:

Modify only one file at a time. Explain the plan before making changes.

Codex does not pick up the new configuration

Cause: Codex reads configuration when the session starts. Changes to config.toml or environment variables may not refresh in the current session.

Fix: Exit Codex completely, reopen your terminal, and start it again:

codex

Other configuration issues

Confirm that model_provider in ~/.codex/config.toml matches [model_providers.vtrix]
Confirm that base_url is https://cloud.vtrix.ai/llm/openai/v1
Confirm that the environment variable referenced by env_key is set
Confirm that the API key is valid
Confirm account balance: Check balance
Confirm that the selected model is suitable for Codex, preferably with tool calling support

For more help, see the rest of the documentation or contact Vtrix support.