Codex 默认配置文件在哪里？Windows、Linux、macOS 路径与基础格式说明

无论是在 Windows 的 PowerShell、Linux 服务器的 SSH 终端，还是 macOS 的 Terminal 或 iTerm2 中使用 Codex CLI，配置的核心规律很统一：默认配置根目录在当前用户主目录下的 .codex 文件夹，主配置文件为 config.toml。

本文说明 Windows、Linux、macOS 的默认位置、CODEX_HOME 的覆盖规则，以及可作为起点的基础 TOML 示例。它特别适合需要在宝塔服务器、个人电脑与 macOS 开发机之间切换的使用者。

一条总规则：默认根目录是 ~/.codex

~ 代表启动 Codex 的当前用户主目录，并不是固定系统目录。因此，Linux 中以 root 运行时，~ 是 /root；换成普通用户 deploy，则是 /home/deploy。切换用户，也会切换到另一套 Codex 配置。

Windows：用用户目录定位

Windows 建议用环境变量定位，以免把用户名写死。PowerShell 中可以执行：

echo $env:USERPROFILE
notepad $env:USERPROFILE\.codex\config.toml

如果目录或文件不存在，先创建：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"

注意不要误创建成 config.toml.txt，也不要把用户级配置文件放进项目仓库。

Linux：宝塔服务器重点看当前用户

宝塔面板终端常以 root 登录，此时配置文件实际就是 /root/.codex/config.toml。可执行：

echo $HOME
mkdir -p ~/.codex
nano ~/.codex/config.toml

生产服务器更推荐为 Codex 创建专用普通用户，并仅给站点项目目录必要权限。这样配置会落在该用户的 ~/.codex，避免与 root 配置混用，也降低误操作系统的风险。

macOS：路径与 Linux 一致

macOS 同样使用 POSIX 用户目录，默认路径为 /Users/你的用户名/.codex/config.toml。无论使用 zsh、bash、Terminal 或 iTerm2，规则都不变：

mkdir -p ~/.codex
nano ~/.codex/config.toml

CODEX_HOME：隔离配置的覆盖开关

设置环境变量 CODEX_HOME 后，Codex 改用该目录作为根目录；配置文件路径随之变为 $CODEX_HOME/config.toml。这适合隔离工作账号、个人账号、测试环境或不同权限策略。

Linux / macOS：export CODEX_HOME="$HOME/.codex-work"，然后执行 codex。

Windows PowerShell：$env:CODEX_HOME = "$env:USERPROFILE\.codex-work"，然后执行 codex。

排查“改了配置却没有生效”时，先检查 CODEX_HOME 是否已被 shell、系统服务、宝塔计划任务或部署脚本设置过。

config.toml 的基础格式

config.toml 采用 TOML 格式：键值写成 键 = 值，字符串使用英文双引号，# 开头是注释。下面只放入常见的模型、推理力度、确认策略与沙箱策略；模型名称应按当前账号和版本实际可用项填写。

可先建立一个最小配置：model = "<your-model>"；model_reasoning_effort = "medium"；approval_policy = "on-request"；sandbox_mode = "workspace-write"。其中 # 开头的行可作为注释使用。

model 指定模型；model_reasoning_effort 表达推理深度倾向；approval_policy 与 sandbox_mode 共同决定命令执行边界。日常开发以 on-request 和 workspace-write 作为起点通常较稳妥；生产服务器不建议为省事长期放宽权限。

auth.json：认证凭据文件，不是常规配置文件

与 config.toml 相邻的还有 auth.json。默认情况下，它位于同一个 Codex 根目录：Windows 为 %USERPROFILE%\.codex\auth.json；Linux/macOS 为 ~/.codex/auth.json；设置 CODEX_HOME 后则变为 $CODEX_HOME/auth.json。

它的职责是保存 CLI 已完成登录或已登记的认证凭据，例如通过 codex login 登录后的令牌状态，或使用 API Key 登录后由 CLI 保存的凭据。相对地，模型选择、沙箱、审批策略和服务提供商连接参数属于 config.toml 的职责。

不要手工编造或公开分享 auth.json 的 JSON。它包含敏感凭据，字段结构也可能随 CLI 版本与认证方式变化。排查认证问题时，优先使用 codex login、codex logout 或 codex doctor，不要把该文件贴到工单、聊天群或 Git 仓库。

使用中转 API：地址配置与密钥配置要分开

有些团队会通过兼容 OpenAI API 的内部网关或中转服务访问模型。此时需要区分两件事：中转地址、协议、模型映射属于 provider 配置；访问密钥属于认证凭据。不要因为看到 auth.json 就把中转 URL 与 Key 一起硬写进去。

更稳妥的流程是：先在 config.toml 定义中转服务的 provider（具体字段须以当前 Codex 版本及中转服务协议为准），再把 API Key 通过受控环境变量提供，或使用 codex login --with-api-key 的标准登录路径让 CLI 写入本地凭据。使用命令行覆盖时，也可以用 -c 传入 TOML 配置项做短期验证，而不是直接修改 auth.json。

下面是结构示意，展示配置职责，不应照抄为生产可用配置，也不要将真实密钥写入文件：

config.toml 的结构示意：[model_providers.internal_gateway]；base_url = "https://gateway.example.com/v1"。实际字段必须按当前 CLI 文档与中转协议核对；auth.json 则由 codex login 或受支持的认证流程管理，不手工粘贴真实 API Key 或登录令牌。

在 Linux 宝塔服务器上，环境变量应由专用普通用户的受保护服务配置、Shell 配置或密钥管理系统提供；避免写在网站根目录、前端 JavaScript、公开仓库、Nginx 配置注释或截图中。若不得不落盘，至少限制权限，例如 chmod 600 ~/.codex/auth.json，并确保目录只归该运行用户所有。

配置与认证的安全检查清单

1. 将 ~/.codex/auth.json、config.toml 和包含密钥的 .env 加入私有项目的 .gitignore。

2. 中转 API 应使用 HTTPS、独立可撤销的 Key 和最小权限；怀疑泄露时立即在中转平台轮换密钥，而不是只删除本地文件。

3. 多人共用服务器时，为每个系统用户分别管理 CODEX_HOME 与凭据，禁止共享 root 的 auth.json。

4. 运行 codex doctor 可检查安装、配置与认证健康状态；输出中如含敏感信息，勿直接公开。

文件改了却没生效？按这五步排查

1. Linux/macOS 执行 whoami、echo $HOME；Windows 查看 $env:USERPROFILE。

2. 检查 CODEX_HOME：Linux/macOS 执行 echo $CODEX_HOME，Windows 执行 echo $env:CODEX_HOME。

3. 确认文件名确实为 config.toml。

4. 检查 TOML 语法，不要把 JSON 或 YAML 直接粘贴进去。

5. 修改后重新启动 Codex 会话，长期运行的终端或服务可能保留旧环境变量。

结语

记住三个概念即可：config.toml 管行为与 provider，auth.json 管认证凭据，CODEX_HOME 决定两者所在根目录。Windows 默认根目录是 %USERPROFILE%\.codex，Linux/macOS 是 ~/.codex；当 CODEX_HOME 存在时，两个文件统一改为位于 $CODEX_HOME 下。理解当前用户、配置根目录与凭据边界后，就能更安全地维护本机、Mac 与宝塔 Linux 服务器上的 Codex。