Codex Environment Variables (Tested on 0.167): Where the API Key Goes, Proxy, CODEX_HOME, CI Injection and Conflicts

Connecting Codex to AI Code With needs no API key environment variable: put the key in the global config.toml with experimental_bearer_token. We tested every case on Codex CLI 0.167.0: the auth.json method, reading the key from an environment variable in CI with auth.command, whether HTTPS_PROXY and NO_PROXY work, switching configs with CODEX_HOME, which wins when environment variables and config.toml conflict, why project-level config is ignored, how to keep your secrets away from commands Codex runs, and fixes for 401 and changes that do not take effect.

12 分钟阅读
Codex Environment Variables (Tested on 0.167): Where the API Key Goes, Proxy, CODEX_HOME, CI Injection and Conflicts

Short answer: to connect Codex to AI Code With, you do not need any API key environment variable. Put the endpoint and the key together in the global config file ~/.codex/config.toml, and it keeps working across terminals, editors and reboots. An old OPENAI_API_KEY or OPENAI_BASE_URL left in your shell will not hijack requests either: in our tests config.toml always won.

Environment variables still matter in Codex: proxies, corporate certificates, injecting the key in CI, switching a whole config directory, and controlling which variables the commands Codex runs can see. This guide gives the direct setup for each job, with the result we actually got for each one.

On November 12, 2026 (Beijing time, UTC+8) we re-ran every scenario with Codex CLI 0.167.0 on Linux x64. Each scenario used a brand-new HOME directory so nothing leaked between runs; request headers and destinations were captured by a local logging server, and real conversations used an AI Code With test key. The Windows commands follow the official PowerShell syntax; the test machine this time was Linux. For every config field, see the Codex config.toml guide.

Create API Key →

Quick answer: what you want to do and what to write

What you wantWrite thisOur result
Everyday Codex on your machineexperimental_bearer_token in config.tomlOK in 5.55 s
Keep the console tutorial's auth.jsonadd requires_openai_auth = true to config.tomlheader carries the auth.json key
CI or a secret manager only gives env varsauth.command reads the key from an env varOK in 4.10 s
Your machine needs a proxyHTTPS_PROXY, exceptions in NO_PROXYproxy log shows api.aicodewith.ai
Two configs on one machinepoint CODEX_HOME to another directoryrequests go to the other config's endpoint
Keep secrets away from commandsshell_environment_policypassed by default, filtered after the change

Recommended: put the key directly in the global config.toml

Step 1: create a key in the AI Code With console (steps in the Create API Key docs).

Step 2: open (or create) ~/.codex/config.toml and paste this complete config, replacing sk-your-key with the key you just created:

toml
model_provider = "aicodewith"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "sk-your-key"

What each field does:

  • model_provider: makes Codex use the aicodewith block below by default. It must be at the very top of the file, not inside any [ ] section.
  • base_url: the dedicated AI Code With endpoint for Codex. It ends with /chatgpt/v1; do not change the path.
  • wire_api = "responses": Codex uses the Responses API.
  • experimental_bearer_token: Codex puts it in the Authorization: Bearer header of every request.

Step 3: run codex in a terminal. If you can chat, you are connected. You can also check with one command:

bash
codex exec --skip-git-repo-check "reply OK"

Result: with a brand-new HOME and only the config above, codex exec took 5.55 seconds and printed OK. The header captured by the logging server was Authorization: Bearer followed by the key from config.toml.

File location: ~/.codex/config.toml on macOS and Linux, %USERPROFILE%\.codex\config.toml on Windows. The key is stored in plain text, so do not commit this file to Git or sync it to public dotfiles. More connection details are in Connect Codex to AICodeWith; if Codex is not installed yet, start with the Codex install guide.

Alternative: put the key in auth.json

If you followed the Codex tutorial in the AI Code With console, you will see another method: the key lives in ~/.codex/auth.json and config.toml has no key. Pick one of the two methods.

Write config.toml like this. Note the extra line requires_openai_auth = true and the absence of experimental_bearer_token:

toml
model_provider = "aicodewith"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
requires_openai_auth = true

Then put the key in ~/.codex/auth.json in the same directory:

json
{
  "OPENAI_API_KEY": "sk-your-key"
}

Do not drop the requires_openai_auth = true line. We ran both variants on 0.167.0: with auth.json alone and no such line, Codex sent requests without any Authorization header and the server returned 401; with the line, the header carried the key from auth.json. For where auth.json lives and its risks, see What is Codex auth.json.

CI or a secret manager: read the key from an env var with auth.command

In GitHub Actions, GitLab CI or Docker, the key usually arrives only as an environment variable and is awkward to write into a file ahead of time. Codex custom providers support an auth setting: when Codex needs a key, it runs a command and uses whatever the command prints as the Bearer key. Make that command read an environment variable and the key never lands in config.toml.

toml
model_provider = "aicodewith"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
auth = { command = "sh", args = ["-c", "printf %s \"$ACW_API_KEY\""] }

Put the key in ACW_API_KEY before running (any variable name works, as long as it matches the line above):

bash
export ACW_API_KEY="sk-your-key"
codex exec --skip-git-repo-check "reply OK"

Result: no key anywhere in config.toml, only ACW_API_KEY set, and codex exec took 4.10 seconds and printed OK. On the logging server, this method also produced Authorization: Bearer plus the variable's value; after a 401, Codex ran the command again to fetch the key and retried.

In GitHub Actions it looks like this (the key is stored in repository Secrets as ACW_API_KEY):

yaml
- name: Run Codex
  env:
    ACW_API_KEY: ${{ secrets.ACW_API_KEY }}
  run: |
    mkdir -p ~/.codex
    cat > ~/.codex/config.toml <<'TOML'
    model_provider = "aicodewith"

    [model_providers.aicodewith]
    name = "aicodewith"
    base_url = "https://api.aicodewith.ai/chatgpt/v1"
    wire_api = "responses"
    auth = { command = "sh", args = ["-c", "printf %s \"$ACW_API_KEY\""] }
    TOML
    codex exec --skip-git-repo-check "Check the latest commit for obvious problems"

Three things to keep in mind:

  • Per the official config reference, do not combine auth with experimental_bearer_token or requires_openai_auth in the same provider; use exactly one.
  • The command may run for at most 5 seconds by default (timeout_ms) and is re-run every 5 minutes by default (refresh_interval_ms).
  • sh -c works on macOS, Linux and Linux CI runners. For everyday use on a Windows machine, the plain config.toml method above is simpler.

For a full cron + codex exec daily job, see A cron and codex exec GitHub Trending digest; for permissions in automation, see Codex automation permissions.

The environment variables that actually matter

VariableWhat it doesWhen you need it
HTTPS_PROXY / HTTP_PROXYroutes Codex network requests through a proxyyour machine needs a proxy to reach the internet
NO_PROXYhosts that bypass the proxysome hosts must be reached directly
CODEX_CA_CERTIFICATEyour company root certificate (PEM)corporate TLS inspection causes certificate errors
SSL_CERT_FILEgeneric certificate path, used when CODEX_CA_CERTIFICATE is unsetsame as above
CODEX_HOMEdirectory for Codex config and local data, default ~/.codextwo configs on one machine
a key variable you name yourselfgives Codex the key via auth.commandCI, containers, secret managers

OPENAI_API_KEY and OPENAI_BASE_URL are not in this table: with this site you neither need them nor can they change where requests go. The tests are below.

Proxy: HTTPS_PROXY and NO_PROXY

Codex reads HTTPS_PROXY for requests to https://api.aicodewith.ai. We started a local proxy that logs every connection target and ran codex exec twice:

SettingResultapi.aicodewith.ai in the proxy log
HTTPS_PROXY=http://127.0.0.1:18888OK in 3.10 s1 CONNECT
plus NO_PROXY=api.aicodewith.aiOK in 4.23 snone, went direct

Both proxy logs also showed connections to chatgpt.com, ab.chatgpt.com and github.com. Those are not model conversation requests, and NO_PROXY only sends the hosts you list directly. So if your proxy only allows some domains, failures on those hosts do not affect conversations with AI Code With; if the conversation request itself cannot connect, check the proxy address and port first.

Here is how to set it on each OS. Use the address and port shown by your own proxy app; 127.0.0.1:7890 is only an example.

macOS

macOS uses zsh by default. For the current terminal only:

bash
export HTTPS_PROXY="http://127.0.0.1:7890"
codex

To apply it to every new terminal, add it to ~/.zshrc and reload the current terminal:

bash
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.zshrc
source ~/.zshrc

To remove it, clear the value in the current terminal, and also delete the line from ~/.zshrc by hand, or new terminals will load it again:

bash
unset HTTPS_PROXY

Linux

Temporary set and unset commands are the same as on macOS. Most distributions use bash, so persist it in ~/.bashrc:

bash
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.bashrc
source ~/.bashrc

When codex exec runs from systemd or cron, ~/.bashrc may not be read, so set the variable explicitly in the service or script. The connection config lives in config.toml, so these background jobs read it directly without passing the key separately.

Windows

For the current PowerShell window only:

powershell
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
codex

To persist it for the current user (already-open windows will not see it; close PowerShell, VS Code and similar apps and reopen them):

powershell
[Environment]::SetEnvironmentVariable('HTTPS_PROXY', 'http://127.0.0.1:7890', 'User')

To clear it: the first line clears the current window only, the second removes the persisted value:

powershell
Remove-Item Env:HTTPS_PROXY
[Environment]::SetEnvironmentVariable('HTTPS_PROXY', $null, 'User')

Windows users of the Codex extension in VS Code can find proxy and sign-in fixes in the Codex VS Code guide.

CODEX_HOME: two configs on one machine

CODEX_HOME decides which directory Codex reads config.toml, auth.json and local history from. The default is ~/.codex. For everyday AI Code With use you do not need to change it.

It is useful when one machine must keep two fully separate configs, for example personal and work, or when CI should keep the config inside the workspace. Point it to another directory before starting:

bash
mkdir -p ~/codex-work
# write the second config in ~/codex-work/config.toml
CODEX_HOME=~/codex-work codex

Result: ~/.codex/config.toml pointed to logging server A and the config.toml in the CODEX_HOME directory pointed to logging server B. With CODEX_HOME set, every request went to B with the key from B's config, and the config in ~/.codex was not read at all.

The flip side is one of the most common reasons why "I edited config.toml and nothing changed": a leftover CODEX_HOME in the terminal means Codex never read the file you edited. Check with echo $CODEX_HOME; empty means the default directory. If you only want to switch models or keys within one directory, profiles are lighter; see Managing Codex across projects.

Environment variables vs config.toml: which one wins

Many people set OPENAI_API_KEY or OPENAI_BASE_URL in the past and worry they will clash with the config.toml method. On 0.167.0 we set both at once and looked at the requests Codex actually sent:

Both presentWhat actually applies
env OPENAI_API_KEY + experimental_bearer_token in config.tomlthe key in config.toml; the env var is ignored
env OPENAI_BASE_URL + base_url in config.tomlthe endpoint in config.toml; the env endpoint receives nothing
key in auth.json without requires_openai_auth = trueneither; the request carries no key
env CODEX_HOME + ~/.codex/config.tomlthe config in the CODEX_HOME directory
model_providers in a project .codex/config.tomlignored; the global config is used

Bottom line: when model_provider points to aicodewith, the global config.toml decides. A leftover OPENAI_API_KEY or OPENAI_BASE_URL will not interfere, but clearing them makes future troubleshooting easier.

The last row deserves a note. Many people want "one key per project" and put a .codex/config.toml in the repository to change the provider. Codex 0.167.0 skips that part and prints:

text
warning: Ignored unsupported project-local config keys in /path/to/repo/.codex/config.toml: model_providers. If you want these settings to apply, manually set them in your user-level config.toml.

Marking the project as trusted does not change this. The endpoint and key can only live in the global config.toml (or the directory CODEX_HOME points to); project config is for settings such as model and reasoning effort. That also keeps keys out of your repository.

Create API Key →

Keep your secrets away from commands Codex runs

When Codex runs commands, it passes environment variables to them. Many people assume variables with KEY, SECRET or TOKEN in the name are filtered automatically. On 0.167.0 they are not, by default. We set DEMO_API_KEY, DEMO_SECRET, DEMO_TOKEN and DEMO_COLOR in the terminal and had Codex run env | grep '^DEMO_':

shell_environment_policy settingVariables the command could see
not set (default)all four
ignore_default_excludes = falseonly DEMO_COLOR
inherit = "core" + ignore_default_excludes = falsenone

To filter variables whose names contain KEY, SECRET or TOKEN, add this to config.toml:

toml
[shell_environment_policy]
ignore_default_excludes = false

To tighten further, give commands only a basic set of variables (such as PATH and HOME) and add what you need:

toml
[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false
set = { NODE_ENV = "development" }

[shell_environment_policy.filters]
"AWS_*" = "exclude"

filters patterns are case-insensitive and support * and ?. This only filters what the commands Codex runs can see; it does not affect Codex itself reading HTTPS_PROXY or CODEX_HOME, nor auth.command reading the key. For more safety settings, see Codex sandbox and permissions.

Troubleshooting

401: "请在请求中提供有效的 API Key" (please provide a valid API key)

Check these four items in order; the first two fix most cases:

  1. With experimental_bearer_token, make sure the quotes contain the complete key with no spaces before or after.
  2. With auth.json, make sure config.toml contains requires_openai_auth = true.
  3. Make sure model_provider = "aicodewith" is at the top of the file, not under any [ ] section.
  4. If the key was deleted or is no longer valid, create a new one in the console.

This time on 0.167.0, using auth.json without requires_openai_auth = true, Codex reconnected 5 times (about 7 seconds) and then printed:

text
ERROR: unexpected status 401 Unauthorized: {"error":"请在请求中提供有效的 API Key。"}, url: https://api.aicodewith.ai/chatgpt/v1/responses

A wrong or invalid key produces the same error. More 401 cases are in How to fix Codex 401 Unauthorized; for 429, see How to fix Codex 429 Too Many Requests.

Changes do not take effect: check three things

  1. Reopen the terminal: environment variables are read once at startup. After editing ~/.zshrc, ~/.bashrc or Windows user variables, already-open terminals and editors do not see the new value. If you use Codex inside VS Code or another editor, quit the editor completely and reopen it; closing the built-in terminal is not enough.
  2. Check CODEX_HOME: echo $CODEX_HOME (PowerShell: $env:CODEX_HOME). If it has a value, Codex reads the config.toml in that directory.
  3. Check whether the config is in the project: provider settings in a repository .codex/config.toml are ignored; look for the Ignored unsupported project-local config keys message at startup.

One command shows the Codex-related variables in the current terminal:

bash
env | grep -iE 'proxy|codex|openai|ssl_cert'
powershell
Get-ChildItem Env: | Where-Object Name -match 'PROXY|CODEX|OPENAI|SSL_CERT'

Certificate errors on a corporate network

Set CODEX_CA_CERTIFICATE to the PEM root certificate from your company, then start codex:

bash
export CODEX_CA_CERTIFICATE="/path/to/company-root.pem"

On Windows use $env:CODEX_CA_CERTIFICATE = 'C:\path\company-root.pem'. When it is not set, Codex uses SSL_CERT_FILE.

Cannot connect, or no response for a long time

First confirm that the HTTPS_PROXY address and port match your proxy app, then use NO_PROXY to exclude hosts that should not go through it. Timeouts come in several kinds; see How to troubleshoot Codex timeouts. For network issues in mainland China, see Using Codex in China.

FAQ

Do I still need an OPENAI_API_KEY environment variable with AI Code With?

No. Put the key in experimental_bearer_token in config.toml, or in auth.json together with requires_openai_auth = true; pick one. In our tests, with model_provider pointing to aicodewith, the OPENAI_API_KEY environment variable was ignored.

I only want the key in an environment variable. Is that possible?

Yes. Use auth.command so Codex runs printf %s "$ACW_API_KEY" to get the key. No key appears in config.toml, which suits CI and containers.

experimental_bearer_token or auth.json?

We recommend experimental_bearer_token: endpoint and key are in one file, so there is one less place to get wrong. If you already use auth.json from the console tutorial, keep it, but make sure config.toml has requires_openai_auth = true.

Will OPENAI_BASE_URL send requests somewhere else?

No. In our tests, when config.toml set base_url, the endpoint in OPENAI_BASE_URL received zero requests.

Can each project use a different key?

Not through a project .codex/config.toml; provider settings there are ignored. Point CODEX_HOME to different directories, or switch with profiles in the global config; see Managing Codex across projects.

Can commands Codex runs read the secrets in my terminal?

By default, yes. Add [shell_environment_policy] with ignore_default_excludes = false to config.toml and variables with KEY, SECRET or TOKEN in the name are no longer passed to commands.

I changed the key, so why is the old one still used?

First check that config.toml or auth.json really contains the new key, then check whether CODEX_HOME points somewhere else, and finally reopen the terminal or editor and restart codex.

Codex, Claude Code and Cursor can all use the same AI Code With account. Get a key and set it up as shown above:

Create API Key →

Related reading

Sources

相关文章

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

The UI SDK is Vercel's behavior library for agents, released on 12 November 2026 as 0.1.0-beta.1. Behaviors live in the framework-free @ui-sdk/core package and are rendered by adapters for React, Vue, Svelte, Solid, and Web Components. This guide follows the official docs on what it is, how to install it, and how to add the skill for Claude Code, Codex, and Cursor, and it records the commands, timings, and output from our test machine.

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

AWS Emulator is AWS's official local emulator of its service APIs, generally available since November 11, 2026 (US time). It has no additional service fee, its source is open, it needs no AWS account, and it covers more than 200 services. We tested version 1.0.322 on Debian 13. This guide covers the install commands, pointing the AWS CLI at the local endpoint to create an S3 bucket and a DynamoDB table, the errors we hit, and how to let Claude Code, Codex and Cursor write and test code against the emulator.

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

T3 Code is pingdotgg's open-source control surface for coding agents. It ships no model of its own; it drives the Claude Code, Codex, Cursor and other CLIs already on your machine. We tested T3 Code 0.1.9 on Linux. This guide covers the install commands, how to point Claude Code and Codex at an AICodeWith API Key so T3 Code can drive them, a full run of both agents with the t3 thread command, and the errors we hit along the way with their fixes.