ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Codex CLI 配置全攻略:从 config.toml 到沙箱与中文输出

Codex CLI 配置全攻略:从 config.toml 到沙箱与中文输出 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.tomlmodel gpt-5 model_provider openai sandbox_mode workspace-write approval_policy on-request这段配置的含义modelCodex 默认使用的大模型名称。不同的账号、不同的模型供应商可用的模型名不一样不要照搬。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 CLICodex 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 KeyCodex 调用模型服务需要认证信息。最直接的方式是设置环境变量OPENAI_API_KEY。在 Linux 或 macOS 的终端中export OPENAI_API_KEYsk-你的密钥 codex在 Windows PowerShell 中$env:OPENAI_API_KEY sk-你的密钥 codex在 Windows CMD 中set OPENAI_API_KEYsk-你的密钥 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}]}实际地址和参数以服务商当前文档为准。接口返回正常后再启动 Codexcodex 请用中文说明你当前使用的模型供应商如果 Codex 报错常见原因如下401API Key 不对或环境变量没有传入当前终端。404base_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-request5.3 最小权限原则使用 Codex 有一个很实用的原则先只读再写文件。第一次接触新项目时先用read-only模式让 Codex 分析和解释项目结构确认它理解正确后再切换到workspace-write让它修改代码。不要一上来就使用danger-full-access。验证方法codex 列出当前目录的所有文件并说明项目用途如果 Codex 能准确描述说明它读文件没有障碍。之后再让它在工作区内做一个小改动观察审批策略是否按预期工作。5.4 使用 Codex 时要注意的安全细节不要向 Codex 提问时粘贴数据库密码、API Key、私钥等敏感信息。Codex 的请求会发送到模型服务端敏感信息一旦进入对话就很难完全清除。另外不要把密钥写进config.toml。配置文件可能会被同步工具上传也可能被其他协作者看到。正确做法是使用环境变量由部署系统或本地环境注入。6. 常见报错与排查链路
返回列表