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.
Quick answer: what you want to do and what to write
| What you want | Write this | Our result |
|---|---|---|
| Everyday Codex on your machine | experimental_bearer_token in config.toml | OK in 5.55 s |
| Keep the console tutorial's auth.json | add requires_openai_auth = true to config.toml | header carries the auth.json key |
| CI or a secret manager only gives env vars | auth.command reads the key from an env var | OK in 4.10 s |
| Your machine needs a proxy | HTTPS_PROXY, exceptions in NO_PROXY | proxy log shows api.aicodewith.ai |
| Two configs on one machine | point CODEX_HOME to another directory | requests go to the other config's endpoint |
| Keep secrets away from commands | shell_environment_policy | passed 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:
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 theAuthorization: Bearerheader of every request.
Step 3: run codex in a terminal. If you can chat, you are connected. You can also check with one command:
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:
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:
{
"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.
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):
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):
- 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
authwithexperimental_bearer_tokenorrequires_openai_authin 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 -cworks 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
| Variable | What it does | When you need it |
|---|---|---|
| HTTPS_PROXY / HTTP_PROXY | routes Codex network requests through a proxy | your machine needs a proxy to reach the internet |
| NO_PROXY | hosts that bypass the proxy | some hosts must be reached directly |
| CODEX_CA_CERTIFICATE | your company root certificate (PEM) | corporate TLS inspection causes certificate errors |
| SSL_CERT_FILE | generic certificate path, used when CODEX_CA_CERTIFICATE is unset | same as above |
| CODEX_HOME | directory for Codex config and local data, default ~/.codex | two configs on one machine |
| a key variable you name yourself | gives Codex the key via auth.command | CI, 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:
| Setting | Result | api.aicodewith.ai in the proxy log |
|---|---|---|
| HTTPS_PROXY=http://127.0.0.1:18888 | OK in 3.10 s | 1 CONNECT |
| plus NO_PROXY=api.aicodewith.ai | OK in 4.23 s | none, 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:
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:
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:
unset HTTPS_PROXY
Linux
Temporary set and unset commands are the same as on macOS. Most distributions use bash, so persist it in ~/.bashrc:
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:
$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):
[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:
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:
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 present | What actually applies |
|---|---|
| env OPENAI_API_KEY + experimental_bearer_token in config.toml | the key in config.toml; the env var is ignored |
| env OPENAI_BASE_URL + base_url in config.toml | the endpoint in config.toml; the env endpoint receives nothing |
| key in auth.json without requires_openai_auth = true | neither; the request carries no key |
| env CODEX_HOME + ~/.codex/config.toml | the config in the CODEX_HOME directory |
| model_providers in a project .codex/config.toml | ignored; 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:
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.
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 setting | Variables the command could see |
|---|---|
| not set (default) | all four |
| ignore_default_excludes = false | only DEMO_COLOR |
| inherit = "core" + ignore_default_excludes = false | none |
To filter variables whose names contain KEY, SECRET or TOKEN, add this to config.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:
[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:
- With
experimental_bearer_token, make sure the quotes contain the complete key with no spaces before or after. - With auth.json, make sure config.toml contains
requires_openai_auth = true. - Make sure
model_provider = "aicodewith"is at the top of the file, not under any[ ]section. - 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:
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
- Reopen the terminal: environment variables are read once at startup. After editing
~/.zshrc,~/.bashrcor 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. - Check CODEX_HOME:
echo $CODEX_HOME(PowerShell:$env:CODEX_HOME). If it has a value, Codex reads the config.toml in that directory. - Check whether the config is in the project: provider settings in a repository
.codex/config.tomlare ignored; look for theIgnored unsupported project-local config keysmessage at startup.
One command shows the Codex-related variables in the current terminal:
env | grep -iE 'proxy|codex|openai|ssl_cert'
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:
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:
Related reading
- Codex config.toml guide
- How to configure a Codex API key
- What is Codex auth.json
- How to fix Codex 401 Unauthorized
- Connect Codex to AICodeWith
- Using Codex in China: connection problems and no overseas credit card



