Skip to main content

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.

Configuration Steps​

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

Configuration Field Mapping Table

FieldExplanation
modelThe large model ID. Copy the identifier of an enabled large model from the model list in the AI console and enter it here.
model_providerThe provider ID, which points to the custom [model_providers] configuration.
base_urlThe Base URL for the large model, which is obtained in the AI console.
env_keyThe name of the environment variable corresponding to the API Key.

Method 1: Configuration File, Permanent Effect​

  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
  1. Enter 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"
  1. 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.

  1. Start up the Codex CLI.
codex

Method 2: Command-Line Arguments (Takes Effect Temporarily)​

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 MessageSolution
404 Model Not FoundThe Base URL is entered incorrectly. Go to the AI console to copy the correct Base URL.
401 Credentials are invalidThe API Key is entered incorrectly or may have been deleted.
429 Token usage exceeded quota limitAn incorrect large model name is configured, or the large model is not enabled in the AI console.