Codex

Codex is a programming agent provided by OpenAI. You can use the Codex CLI in the terminal or manage projects and tasks within the desktop app. By configuring custom model providers, Codex can use AGTCloud's OpenAI Responses compatible entry.

Different models may support different scope for tool calls, inference, multi-agents, and context lengths. Please select models that are available to the current API Key and support the Responses protocol.

Preparation

Before you start, please confirm that you have:

Prepare the terminal environment and the local project you want to open;
Register and log in to AGTCloud;
Create a token on the API Keys page;
From the Model Marketplace, copy a model ID that is available to the current API Key and supports the Responses protocol.

Install Codex

Choose the installation method that matches your current environment.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

After installation, reopen the terminal and check the version:

codex --version

Configure the API Key

Codex reads API keys from environment variables specified by custom providers. This tutorial uses a separate AGTCLOUD_API_KEY to avoid mixing keys with OpenAI or other platforms.

Temporary configuration

The following configuration only takes effect in the current terminal session.

export AGTCLOUD_API_KEY="your-api-key"

Durable configuration

If you want the variable to take effect automatically every time you open the terminal, you can write it to the shell configuration file or Windows User Environment variable.

Edit ~/.zshrc and add:

export AGTCLOUD_API_KEY="your-api-key"

Load configuration after saving:

source ~/.zshrc

Do not write the API Key into config.toml

Store only the environment variable name in config.toml. The API Key itself is stored as plaintext in the local environment configuration, so use this method only on a trusted personal device.

Configure the AGTCloud Provider

The user-level configuration of Codex is located at ~/.codex/config.toml. If the file already exists, back it up first, then merge AGTCloud Provider into the existing configuration; do not overwrite other settings directly.

mkdir -p ~/.codex

if [[ -f ~/.codex/config.toml ]]; then
    cp ~/.codex/config.toml ~/.codex/config.toml.backup
fi

Add the following to ~/.codex/config.toml:

model_provider = "agtcloud"
model = "MODEL_ID"

[model_providers.agtcloud]
name = "AGTCloud"
base_url = "https://api.agtcloud.cn/v1"
env_key = "AGTCLOUD_API_KEY"
wire_api = "responses"

Configuration item	Purpose
`model_provider`	Switch the default model provider to AGTCloud
`model`	Specify the model ID used by Codex
`base_url`	Send the Responses request to the AGTCloud API address shown on this page
`env_key`	Specify the name of the environment variable where the API Key is stored
`wire_api`	Specify the use of the OpenAI Responses protocol

Provider must be placed in the user-level configuration

A project-level .codex/config.toml can store project settings, but it cannot override model_provider and model_providers. Put the provider configuration above in the user-level ~/.codex/config.toml file.

Choose a model

MODEL_ID is a placeholder, not a real model name. From the Model Marketplace, copy the full ID of a model that is available to the current API Key and supports Responses, then replace MODEL_ID in config.toml.

In the Codex CLI, use /model to view or switch models. The models listed for a custom provider depend on the Codex version and current API Key. If the target model is absent, update the model value in config.toml directly.

Use the Codex CLI

Enter the project directory

cd /path/to/your/project

Start Codex

codex

Check the current configuration

In Codex, run:

/status

Confirm that the current Provider, model, and configuration file are correct. The Base URL should match the /v1 API address shown on this page and must not contain /v1/v1.

Initiate read-only tests

In a test project containing README.md, enter:

Please read the README.md and summarize the purpose of this project in three points. Do not modify any files.

A normal response confirms that the basic connection is working. This step generates normal API usage.

Use the Codex App

Restart the app

After saving the ~/.codex/config.toml and environment variables, completely exit the Codex App and reopen it.

Open the local project

Switch to Codex in the desktop app and select a test project that does not contain sensitive code.

Check the model and validate it

Confirm that the current model matches config.toml, then validate using the same README read-only task as the CLI.

The app's environment variable loading depends on the version and how it is launched

Codex apps reuse Codex's local configuration, but desktop apps may load shell environment variables depending on version and operating system. If the CLI is available but the app cannot read the API key, restart the app completely and then check the user-level configuration and environment variables.

Frequently Asked Questions

Issue	What to check	Resolution
Cannot find the `codex` command	Installation and `PATH`	Reopen the terminal and run `codex --version`; if necessary, run the official installation command again
API Key is not loaded	Whether `AGTCLOUD_API_KEY` is available in the current process	Reopen the terminal or app so it reloads the user environment configuration
Provider configuration is not active	Whether the settings were written to a project-level `.codex/config.toml`	Move `model_provider` and `model_providers` to `~/.codex/config.toml`
The request path contains `/v1/v1`	Whether `base_url` includes an extra version segment	Use `https://api.agtcloud.cn/v1` exactly as shown on this page
Returns `401`	API Key and environment variable configuration	Use a valid API Key and confirm that the `env_key` name matches the environment variable
Returns `403`	Token permissions, model permissions, and account status	Check the token status and the models available to the account in the console
Returns `404`	Base URL, Responses endpoint, and model ID	Verify `base_url` and copy a model ID available to the current API Key again
The model does not exist or is unavailable	Model visibility and Responses protocol support	Copy the full ID from the Model Marketplace and select the model that the current Key can call
The CLI works, but the app does not load the configuration	App version, configuration path, and environment variables	Fully restart the app; first verify the same user-level configuration with the CLI
Some advanced capabilities are unavailable	Target model capabilities and current integration support	Start with a basic read-only task. Advanced capabilities depend on the actual request results

If you encounter issues that cannot be located, record the request time, API Base URL, model ID, HTTP status, and anonymized error messages, then review Error & Troubleshooting. Do not submit the full API Key.

Safety advice

Create a separate API Key for Codex to facilitate permission management and deactivate credentials.
Do not write real keys into config.toml, code, repositories, screenshots, logs, or shared scripts.
In shared devices or team environments, prioritize operating system credential management or organize a unified key distribution scheme.
If an API Key is suspected of leaking, immediately disable or remove it in the console, then create a new Key.

Next, you can read API Key, Base URL & Authentication, OpenAI Responses, and Errors & Troubleshooting.

On this page