Codex 是 OpenAI 推出的编程助手工具，核心形态是基于命令行的 Codex CLI，以及配套的 IDE 插件。很多人安装完 Codex 后，第一反应是直接输入需求让它写代码，但对配置文件位置、环境变量优先级、模型供应商、权限沙箱和中文输出控制并不清楚。这篇文章围绕 Codex 的主要设置展开，先讲清楚配置体系，再解释 API Key、模型、中文输出、第三方 OpenAI 兼容服务接入、沙箱与审批策略，最后给出一份可以照着操作的排查清单和使用建议。读完以后，你可以把 Codex 从“能跑起来”调整成“在自己的项目里稳定、安全、可控地工作”。
1. 先理解 Codex 的设置体系，再修改参数
1.1 Codex 由 CLI、配置文件和执行沙箱组成
Codex 不是一个简单的聊天窗口。它由四层组成：
- Codex CLI：负责启动交互界面、接收任务、调用模型、执行命令。
- 配置文件：决定模型名称、模型供应商、沙箱模式和审批策略。
- 指令文件：决定模型如何回复，例如是否使用中文、代码风格、项目约定。
- 执行环境：沙箱和审批机制决定 Codex 能不能写文件、能不能执行命令。
常见的设置问题，几乎都出在这四层中的某一层。比如用户把“模型输出不是中文”理解成“界面没有中文菜单”，把“无法调用第三方模型”理解成“Codex 不支持外部服务”，本质上是没有分清配置文件、环境变量和指令文件的职责。
1.2 配置文件默认位置
Codex CLI 默认从用户目录下的.codex目录读取配置。在 Linux 和 macOS 上是~/.codex，在 Windows 上是C:\Users\<用户名>\.codex。
最关键的三个文件如下：
~/.codex/config.toml：主要配置文件，控制模型、供应商、沙箱、审批策略。~/.codex/AGENTS.md：全局指令文件，凡是 Codex 启动的会话都会读取。- 项目根目录下的
AGENTS.md：项目级指令文件，比全局指令更贴近当前工程。
如果你的目录里没有这些文件，不需要担心。多数情况下，首次运行 Codex 时会自动创建基本配置；如果没自动创建，手动新建同名文件也可以。
1.3 最小配置文件示例与参数含义
先看一个最基础的config.toml：
model = "gpt-5" model_provider = "openai" sandbox_mode = "workspace-write" approval_policy = "on-request"这段配置的含义：
model：Codex 默认使用的大模型名称。不同的账号、不同的模型供应商可用的模型名不一样，不要照搬。model_provider：模型供应商标识。默认情况下是openai，指向 OpenAI 官方服务。sandbox_mode：沙箱模式。workspace-write表示允许 Codex 修改当前工作区文件，但不会随意操作系统其他位置。approval_policy：审批策略。on-request表示遇到敏感操作时先征求用户同意。
这里的字段并不是全部配置项。Codex 还在持续迭代，不同版本支持的可配置项会有差异。落地项目前，先运行codex --help或查看当前版本的官方文档确认字段名。
1.4 参数优先级：命令行参数、环境变量、配置文件
Codex 的参数优先级从高到低通常是这样：
- 命令行参数。
- 环境变量。
- 配置文件。
举例来说，即使config.toml里写了model = "gpt-5"，你仍然可以在启动时临时覆盖：
codex --model "gpt-5" "用中文解释这个项目的结构"这种设计在排查时很有用。比如怀疑配置文件写错了，但又不想立刻改文件，可以通过命令行参数临时指定一个模型或一种沙箱模式验证。等确认之后再回写配置文件。
2. 安装后的基础设置：API Key、模型和可执行文件
2.1 安装 Codex CLI
Codex CLI 最常见的安装方式是通过 npm 全局安装：
npm install -g @openai/codex安装完成后，先验证命令是否能找到：
codex --version如果提示找不到codex，通常有两个原因：一是没有安装成功，二是 npm 的全局 bin 目录不在系统的 PATH 环境变量中。
在 Linux 或 macOS 上，可以用以下命令查看路径：
which codex在 Windows 上使用：
where codex常见路径包括/usr/local/bin/codex和C:\Users\<用户名>\AppData\Roaming\npm\codex.cmd。codex命令能被终端识别，是后续所有设置的前提。
2.2 配置 API Key
Codex 调用模型服务需要认证信息。最直接的方式是设置环境变量OPENAI_API_KEY。
在 Linux 或 macOS 的终端中：
export OPENAI_API_KEY="sk-你的密钥" codex在 Windows PowerShell 中：
$env:OPENAI_API_KEY = "sk-你的密钥" codex在 Windows CMD 中：
set OPENAI_API_KEY=sk-你的密钥 codex注意，不要把 API Key 写进项目代码，也不要提交到 Git 仓库。设置完成后，先确认环境变量是否在当前终端里生效：
echo $OPENAI_API_KEY如果终端已经打开很久，修改环境变量后可能需要重开终端，或者重新加载配置文件。
另外，不同版本可能提供不同的认证方式。有些版本支持codex login子命令，可以通过浏览器登录官方账号。具体以你当前版本的codex --help输出为准。
2.3 设置默认模型与 Model Provider
如果每天固定使用同一个模型，可以在config.toml里设置默认值，避免每次通过命令行手动指定。
model = "gpt-5" model_provider = "openai"这里要注意：模型名必须是你当前账号或服务商真正支持的名称。模型名写错时，Codex 可能返回“模型不存在”或“模型不受支持”的错误。
model_provider也不一定只有openai一个值。如果你接入的是兼容 OpenAI 接口的第三方服务，这里的值要和后面[model_providers.xxx]配置块对应。
2.4 验证基础设置
配置完成后，用一条最简单的任务验证：
codex "请用中文回复一句话：配置成功"正常情况会看到 Codex 用中文回复“配置成功”或类似内容。如果返回 401，说明 API Key 无效；如果返回 404，说明模型名或接口地址有问题。
这一步不要跳过。很多后续问题都能在基础验证阶段提前暴露，比如密钥复制多了空格、模型名写错、环境变量没有在当前终端生效。
3. 把 Codex 的中文输出问题一次说清
3.1 界面语言与模型输出语言要分开看待
很多用户搜索“Codex 设置中文”，本质上有两种需求：
- 让 Codex 的界面变成中文。
- 让 Codex 的回答和注释变成中文。
第一种需求要区分版本。Codex CLI 属于命令行工具，官方界面语言目前以英文为主，通常不会提供“中文菜单”这类设置。真正可控的是第二种：模型输出语言。
也就是说，你想让 Codex 用中文解释代码、用中文写注释、用中文汇报问题，应该在指令文件里写清楚，而不是去翻一个不存在的“语言切换”按钮。
3.2 用 AGENTS.md 设置全局中文约定
AGENTS.md 是 Codex 的指令文件，作用类似于系统提示词。Codex 每次启动会话时都会读取这些约束，并把它作为模型回答的上下文。
创建全局指令文件：
mkdir -p ~/.codex cat >> ~/.codex/AGENTS.md <<'EOF' # 语言约定 - 与用户交流时默认使用简体中文。 - 解释、建议、错误排查步骤均使用中文。 - 代码变量名、函数名、类名保持英文。 - 代码注释可以使用中文，但关键词保持准确。 EOF这样做的好处是全局生效。之后无论你在哪个项目里启动 Codex，它都会尽量使用中文回复。
如果你只想让某个项目使用中文，就把类似内容写到项目根目录的AGENTS.md中。项目级指令文件的优先级通常高于全局文件，适合需要强约束的工程。
3.3 在交互对话中临时指定中文
有些时候你只是临时需要一次中文回复，不想改动全局配置。可以直接在任务描述里写明：
codex "请用中文解释这个函数的作用"或者进入交互会话后直接说：
请用中文回答，并保留代码示例。模型会根据指令内容调整输出语言。这种方式的确定性不如 AGENTS.md，因为每一次新会话都需要重新声明。
3.4 验证中文输出是否生效
设置完成后，用一条简单指令验证：
codex "你当前使用什么语言？请用一句中文回答"如果返回内容是中文，说明指令文件已经生效。如果返回其他语言，按以下顺序检查：
AGENTS.md是否放在正确目录。- 是否新增了不必要的 BOM 或格式错误。
- Codex 会话是否已经重启。指令文件一般在会话启动时读取，正在运行的会话不一定能感知文件变化。
注意：AGENTS.md 是指导性配置，不是强制语法。不同模型遵循指令的稳定性会有差异，工程上不要依赖它 100% 生效，关键结果仍然要人工检查和验证。
4. 接入第三方 OpenAI 兼容模型服务的配置方式
4.1 什么场景需要自定义 Model Provider
并不是所有用户都使用 OpenAI 官方 API。有些团队会使用国内可访问的模型服务，有些会通过兼容 OpenAI 接口的中间层做测试，有些则只是在做模型效果对比。
Codex CLI 支持通过model_providers配置自定义模型供应商。前提是目标服务商提供兼容 OpenAI 的 HTTP 接口，也就是支持/v1/chat/completions或/v1/responses这类请求格式。
在开始配置前，先确认三件事：
- 服务商提供的 API 地址是什么。
- 服务商支持的接口格式是 chat completions 还是 responses。
- 服务商支持哪些模型名。
4.2 以 DeepSeek 为例的 config.toml 配置
以下示例展示如何把 Codex 指向一个 OpenAI 兼容服务。这里以 DeepSeek 为例，因为它提供 OpenAI 兼容接口，并且社区使用比较广泛。
model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"配置字段解释：
model：默认使用的模型名，例如deepseek-chat。model_provider：顶层这里要写你在下方配置块里定义的名字，比如deepseek。name：供应商展示名，便于日志和界面识别。base_url：服务商的 API 地址。这里要注意是否包含/v1路径，写错会直接导致 404。env_key：服务商 API Key 对应的环境变量名。Codex 会读取DEEPSEEK_API_KEY作为认证信息。wire_api：请求协议格式。chat表示使用 chat completions 风格，另一种常见取值是responses，需要根据服务商实际接口决定。
wire_api字段在不同版本里可能叫法不同，或者不被当前版本支持。如果你的 Codex 版本不识别，可以先只保留name、base_url、env_key三个字段，再按官方文档补充。
4.3 第三方 API Key 的环境变量设置
配置好env_key后，需要手动设置对应的环境变量。
在 Linux 或 macOS 终端中：
export DEEPSEEK_API_KEY="你的第三方密钥" codex在 Windows PowerShell 中：
$env:DEEPSEEK_API_KEY = "你的第三方密钥" codex有些服务商还允许通过OPENAI_API_KEY直接传递密钥，但更推荐用独立的env_key，避免把官方密钥和第三方密钥混在一起。
4.4 验证第三方接入是否成功
设置完成后，先测试服务商接口本身是否可用。如果服务商支持chat/completions，可以这样验证：
curl -sS https://api.deepseek.com/v1/chat/completions \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"hello"}]}'实际地址和参数以服务商当前文档为准。接口返回正常后，再启动 Codex：
codex "请用中文说明你当前使用的模型供应商"如果 Codex 报错，常见原因如下：
- 401：API Key 不对，或环境变量没有传入当前终端。
- 404：
base_url的路径不对，模型名错误，或服务商不支持该接口格式。 - 400：请求参数和接口格式不匹配，通常要调整
wire_api。
注意：第三方服务的可用性、模型名和接口格式会随服务商调整而变化。接入前不要只看一篇教程，要以服务商当前发布的接口文档为准。
5. 沙箱、审批策略与安全边界
5.1 sandbox_mode 的三种取值与适用场景
Codex 在执行任务时，可能会读取文件、修改代码、运行构建命令。为了防止它误操作整个系统，Codex 提供了沙箱机制。
常见的sandbox_mode取值如下：
| 模式 | 写文件 | 访问工作区外文件 | 适用场景 |
|---|---|---|---|
read-only | 否 | 否 | 代码审查、解释问题、梳理项目 |
workspace-write | 是 | 否 | 日常编码、修改项目文件 |
danger-full-access | 是 | 是 | 临时容器、完全隔离的测试环境 |
实际使用中，最推荐的是workspace-write。它可以修改当前项目文件，但不会随便操作系统其他位置。
5.2 approval_policy 怎么选择
approval_policy控制的是“敏感操作是否要先经过用户确认”。常见策略包括：
on-request：遇到需要执行命令、修改文件等操作时，先询问你。on-failure：部分操作放行，只有失败或发生异常时再询问。never：不询问，直接执行。
对大多数开发场景，建议使用on-request。这样既能提高效率，又能保留对危险操作的判断权。只有在你完全理解风险时，才考虑放宽审批策略。
配置示例：
sandbox_mode = "workspace-write" approval_policy = "on-request"5.3 最小权限原则
使用 Codex 有一个很实用的原则：先只读，再写文件。
第一次接触新项目时，先用read-only模式让 Codex 分析和解释项目结构；确认它理解正确后，再切换到workspace-write让它修改代码。不要一上来就使用danger-full-access。
验证方法：
codex "列出当前目录的所有文件，并说明项目用途"如果 Codex 能准确描述，说明它读文件没有障碍。之后再让它在工作区内做一个小改动，观察审批策略是否按预期工作。
5.4 使用 Codex 时要注意的安全细节
不要向 Codex 提问时粘贴数据库密码、API Key、私钥等敏感信息。Codex 的请求会发送到模型服务端，敏感信息一旦进入对话，就很难完全清除。
另外，不要把密钥写进config.toml。配置文件可能会被同步工具上传，也可能被其他协作者看到。正确做法是使用环境变量，由部署系统或本地环境注入。
