Codex Manual
配置与登录
大多数 Codex 配置问题,本质上都是改错了 config.toml 或环境变量没有进入当前运行环境。
配置文件在哪里
常见位置:
| 环境 | 配置文件 |
|---|---|
| macOS / Linux | ~/.codex/config.toml |
| Windows 原生 | %USERPROFILE%\.codex\config.toml |
| WSL2 | WSL 内的 ~/.codex/config.toml |
Windows 原生和 WSL2 是两个环境。你在 Windows 里改 %USERPROFILE%\.codex\config.toml,不会自动影响 WSL 内运行的 codex。
CODEX_HOME
如果设置了 CODEX_HOME,Codex 会使用这个目录作为配置和状态目录。
Linux / macOS:
export CODEX_HOME="$HOME/.codex"PowerShell:
$env:CODEX_HOME="$HOME\.codex"普通用户不需要主动设置 CODEX_HOME。只有当你想共享配置、切换多套环境或把 WSL 指向 Windows 配置目录时才需要。
登录方式
Codex 常见登录方式:
- ChatGPT 账号登录(
codex login)。CLI、App 和 IDE 扩展共用同一份登录缓存;Codex Cloud 必须使用这种方式。 - OpenAI API Key 登录:
printenv OPENAI_API_KEY | codex login --with-api-key,按标准 API 价格计费,部分依赖 ChatGPT 的功能受限。 - 设备码登录(beta):
codex login --device-auth,适合远程或无浏览器的机器,需要先在 ChatGPT 安全设置或工作区权限中启用。 - 自定义 provider,例如 XAI Router。
codex login status 查看当前登录方式,codex logout 清除凭据。凭据默认以明文保存在 CODEX_HOME 下的 auth.json 中,请像密码一样保护;可用 cli_auth_credentials_store 改为 keyring(系统凭据库)、auto 或 ephemeral(只在当前进程内存中)。 如果你已经有 ChatGPT Plus / Pro / Business / Edu / Enterprise,通常优先使用 ChatGPT 登录。需要企业统一管理、模型路由或包月额度时,再配置 XAI Router。
常用配置示例
approval_policy = "on-request"
sandbox_mode = "workspace-write"这表示 Codex 默认只在工作区内写文件,需要更高权限时请求确认。登录方式通过 codex login 或自定义 Provider 的鉴权配置决定。
还有几点值得知道:
- 项目内的
.codex/config.toml会忽略model_provider、model_providers、openai_base_url、chatgpt_base_url、profile、profiles、notify和otel,这些设置请写在用户级config.toml里。 - 配置档案现在是与
config.toml同目录的独立文件$CODEX_HOME/档案名.config.toml,用--profile 档案名选择;-c key=value可临时覆盖单个配置。 approval_policy = "untrusted"已不再支持,on-failure已弃用;请改用on-request或never,详见权限与安全。- 联网搜索默认是
cached,可用顶层web_search(disabled、cached、indexed、live)或命令行--search调整。 - 多代理开关请使用
agents.enabled;显式设置features.multi_agent会收到弃用提示。
排查顺序
配置不生效时,按这个顺序检查:
- 当前
codex是在 Windows、WSL、macOS 还是 Linux 里运行。 - 你改的是不是该环境里的
config.toml。 - 环境变量是否在当前 shell 中生效。
- 是否用 CLI 参数或 profile 覆盖了配置。
- 是否需要重启 App 或重新打开终端。