Codex setup

For the OpenAI Codex VS Code extension (openai.chatgpt), Codex CLI, and compatible clients. Create an API key on the main site and check your balance and key-group access. Copy an available model ID from the Model Plaza.

VS Code: open configuration from the gear

1. Install the OpenAI Codex extension.
2. Open Codex sidebar → gear → Codex Settings → Open config.toml (custom configuration).
3. Back up the file before editing. Preserve unrelated settings and avoid duplicate TOML tables.

Provider settings belong in Codex's config.toml, not VS Code's settings.json. Open the active file through the extension, especially with Remote SSH, rather than assuming a local or remote path.

Option 1: put the API key directly in the configuration

Replace both placeholders with your model ID and API key:

model = "REPLACE_WITH_MODEL_ID"
model_provider = "nekocloud"

[model_providers.nekocloud]
name = "NekoCloud API"
base_url = "https://api.nekocloud.vip/v1"
wire_api = "responses"
experimental_bearer_token = "REPLACE_WITH_API_KEY"

• Enter the key itself in experimental_bearer_token, without a Bearer prefix.
• Remove env_key and requires_openai_auth from this provider. Do not mix authentication methods.
• model and model_provider are top-level fields: place them before table headers. The provider ID must match the table name.
• Do not append /responses to the Base URL. Codex appends the endpoint.
• This configuration uses the Responses API; a Chat Completions-only endpoint is not sufficient.

Plaintext credentials

The key is stored as plaintext. Do not commit the file to Git or share full screenshots/configuration. On Linux/macOS, restrict access to the actual file with chmod 600; for the default path, use chmod 600 ~/.codex/config.toml. Protect configuration backups too. This is an experimental setting: check the official reference if an upgrade changes compatibility, or use environment-variable authentication.

Save your work, run Developer: Reload Window, and start a new Codex conversation. The site operator confirmed this settings entry and direct-key method in a Linux Remote SSH setup. Labels may differ by extension version.

Option 2: use an environment variable

Keep the model, URL and protocol settings, but replace the authentication line with:

# Inside [model_providers.nekocloud]
# Remove experimental_bearer_token; do not keep both methods
env_key = "NEKOCLOUD_API_KEY"

env_key contains the variable name, not the actual API key. Set the secret in the environment of the process running Codex.

Linux / macOS terminal launch

In Bash, hidden input keeps the key out of command history:

read -rsp 'API Key: ' NEKOCLOUD_API_KEY
printf '\n'
export NEKOCLOUD_API_KEY
codex

For local VS Code, fully exit all existing VS Code processes, then run code . from that same terminal. The temporary variable only affects this shell and new child processes. Shell startup files such as .bashrc / .zshrc can persist it, but desktop launchers may not read them. Storing the key in a shell file is also plaintext storage.

Local Windows

Open Edit environment variables for your account. Add the user variable NEKOCLOUD_API_KEY with your actual key as its value. Fully exit VS Code and reopen it. WSL, Remote SSH and containers cannot rely solely on Windows user variables.

Remote SSH: which machine needs the configuration?

For example, a Linux workstation connects to another Linux machine through VS Code Remote SSH. Configuration and environment variables follow the Codex execution environment, not the screen.

1. Run Developer: Show Running Extensions and check whether openai.chatgpt runs in the remote extension host.
2. If remote, use the SSH user's configuration and environment on that host. A separately installed remote desktop VS Code is unrelated to this VS Code Server session.
3. Open the active configuration through the Codex gear. Option 1 needs no environment variable.
4. For option 2, a variable visible in the integrated terminal may still be missing from the running Codex process. Running export, source ~/.bashrc, or opening another terminal cannot update the parent process environment.

For remote Bash, an environment declaration intended for startup must precede any non-interactive early return in .bashrc; whether the file is loaded still depends on the startup path. Only after identifying an environment inheritance problem, save work and finish terminal tasks, then run Remote-SSH: Kill VS Code Server on Host... and reconnect. This disconnects that user's remote VS Code sessions and may affect integrated terminal tasks. It does not reboot Linux or restart SSH. Do not use restarting as a generic 401 fix.

CLI, desktop clients and Codex++

Default CLI configuration paths:

• Linux / macOS: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

A custom CODEX_HOME or client-managed configuration may use another path. The CLI can use either direct-key or environment-variable authentication above.

Some desktop / Codex++ pure-API configurations use auth.json: store OPENAI_API_KEY in the correct configuration directory's auth.json and set requires_openai_auth = true in the matching provider. Remove env_key and experimental_bearer_token for this method. Back up existing login files and do not blindly overwrite OAuth credentials. If the client manages providers, edit and re-save through its UI so generated configuration does not overwrite manual changes.

Older clients may generate providers without explicit authentication. Inspect the active configuration and client release notes; upgrade to a fixed version if needed. Do not delete login files or rotate keys solely because of a 401.

Troubleshooting 401 and other errors

API_KEY_REQUIRED: the server did not recognize a key

Typical response:

401 Unauthorized
API_KEY_REQUIRED
API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header

The request reached the server, but it did not recognize a usable key field. This is not the same as an invalid key. Check in order:

1. Is the file opened through the gear the active configuration? Does top-level model_provider select the intended provider?
2. Does that provider explicitly configure one authentication method, without mixing methods?
3. Did you put the actual key in env_key? Use the variable name there, or switch to experimental_bearer_token.
4. With environment authentication, did the Codex process itself inherit a non-empty variable, rather than just the terminal?
5. If configuration is correct, contact support with the request time, model, error code and request id for a request-path investigation. Never send the key, authentication headers or complete auth.json.

Other errors

Symptom	Check
Other 401 / invalid key	Read the specific error code, then check spelling, revocation and authentication method
404	Base URL and Responses route; do not duplicate /responses
Model not found / not allowed	Exact model ID, key group and model permissions
429	Reduce frequency/concurrency and inspect the response and usage records

Verify the connection

Start a new Codex conversation and send a short prompt (normal usage may incur a charge). Confirm a successful response, then check the request time, model and charge under Usage on the main site. Saving a configuration or confirming a variable in a terminal is not an end-to-end test.

References: Official IDE settings · Official configuration reference · VS Code Remote SSH

Tool-chain verification

In an isolated project, ask the agent to read a non-sensitive file and summarize it. Verify the tool call, result return and final answer. Chat success does not prove tools, images or long contexts work. Keep approval controls enabled; tests may incur charges.