Codex Manual

配置与登录

大多数 Codex 配置问题,本质上都是改错了 config.toml 或环境变量没有进入当前运行环境。

配置文件在哪里

常见位置:

环境配置文件
macOS / Linux~/.codex/config.toml
Windows 原生%USERPROFILE%\.codex\config.toml
WSL2WSL 内的 ~/.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 常见登录方式:

  1. ChatGPT 账号登录(codex login)。CLI、App 和 IDE 扩展共用同一份登录缓存;Codex Cloud 必须使用这种方式。
  2. OpenAI API Key 登录:printenv OPENAI_API_KEY | codex login --with-api-key,按标准 API 价格计费,部分依赖 ChatGPT 的功能受限。
  3. 设备码登录(beta):codex login --device-auth,适合远程或无浏览器的机器,需要先在 ChatGPT 安全设置或工作区权限中启用。
  4. 自定义 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 会收到弃用提示。

排查顺序

配置不生效时,按这个顺序检查:

  1. 当前 codex 是在 Windows、WSL、macOS 还是 Linux 里运行。
  2. 你改的是不是该环境里的 config.toml。
  3. 环境变量是否在当前 shell 中生效。
  4. 是否用 CLI 参数或 profile 覆盖了配置。
  5. 是否需要重启 App 或重新打开终端。