Codex CLI

Codex CLI is an AI programming agent launched by OpenAI that runs in the terminal. It can read local codebases and complete development tasks such as code writing, file operations, and command execution through natural language interaction.

Prerequisites

• You have activated a TCB environment and obtained the environment ID cloudBaseEnvID
• Enable the required model in the AI console
• Obtain the Base URL and API Key in the AI console

Base URLhttps://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase

Configuration Steps

Codex CLI supports connecting to custom models through the config.toml configuration file.

Configuration Field Mapping Table

Field	Explanation
model	The large model ID. Copy the identifier of an enabled large model from the model list in the AI console and enter it here.
model_provider	The provider ID, which points to the custom [model_providers] configuration.
base_url	The Base URL for the large model, which is obtained in the AI console.
env_key	The name of the environment variable corresponding to the API Key.

Configuration via CC Switch

CC Switch is an open-source desktop application for centrally managing provider configurations for multiple AI coding tools. For installation instructions, refer to the CC Switch configuration guide.

1. Open CC Switch and add CloudBase as a provider

Field	Description
API Key	Obtained from the AI console
Base URL	https://{{cloudBaseEnvID}}.api.tcloudbasegateway.com/v1/ai/cloudbase
API Format	Chat Completions (requires local routing)

2. Enable local route mapping in advanced options and enter the model ID

3. Switch to the CloudBase provider and start Codex CLI

Configuration File (Permanent)

1. Open or create the Codex CLI configuration file.

note

If you use your file browser to locate files, note that the file browser hides files with names starting with a period (.) by default. You may need to enable the hidden files option in your file browser to view them.

On macOS, use the Finder shortcut Command + Shift + . to show hidden files. On Windows, you can show hidden items by selecting "File Explorer - View - Show - Hidden items".

• Configuration Path for Mac/Linux

~/.codex/config.toml

• Configuration Path for Windows

C:\Users\<YourUsername>\.codex\config.toml

2. Add or modify the following configuration.

model = "hy3-preview"
model_provider = "cloudbase"

[model_providers.cloudbase]
name = "CloudBase"
base_url = "https://{{cloudBaseEnvID}}.api.tcloudbasegateway.com/v1/ai/cloudbase"
env_key = "CLOUDBASE_API_KEY"

3. Set the API Key environment variable.

Mac/Linux (valid for the current terminal window)

export CLOUDBASE_API_KEY="eyJhbGciOiJSUzI1N..."

Windows CMD (valid for the current terminal window)

set CLOUDBASE_API_KEY=eyJhbGciOiJSUzI1N...

Windows PowerShell (valid for the current terminal window)

$env:CLOUDBASE_API_KEY = "eyJhbGciOiJSUzI1N..."

note

The environment variables above take effect temporarily and become invalid after you close the terminal. To make them permanent, you can write the environment variables into a Shell configuration file, such as ~/.zshrc or ~/.bashrc.

4. Start up the Codex CLI.

codex

Command-Line Arguments (Temporary)

Without modifying the configuration file, override it directly via the command line:

export CLOUDBASE_API_KEY="eyJhbGciOiJSUzI1N..."

codex --config model='"hy3-preview"' \
      --config model_provider='"cloudbase"' \
      --config 'model_providers.cloudbase.base_url="https://{{cloudBaseEnvID}}.api.tcloudbasegateway.com/v1/ai/cloudbase"' \
      --config 'model_providers.cloudbase.env_key="CLOUDBASE_API_KEY"'

Common Error Troubleshooting

Error Message	Solution
404 Model Not Found	The Base URL is entered incorrectly. Go to the AI console to copy the correct Base URL.
401 Credentials are invalid	The API Key is entered incorrectly or may have been deleted.
429 Token usage exceeded quota limit	An incorrect large model name is configured, or the large model is not enabled in the AI console.