第四章：Codex CLI配置指南
一、必看：配置底层核心规则
Codex CLI的所有配置，均基于2个核心文件和一套官方优先级规则实现，全场景通用，先看懂规则再动手，避免后续配置混乱、不生效。
1.1 2个核心配置文件（唯一核心，全场景通用）
所有配置仅围绕这两个文件展开，无其他额外依赖，格式错误、变量名不匹配是配置不生效的第一高频原因。
📌 新手必记核心规则（90%的401报错都源于此）：
auth.json内的密钥变量名，必须和config.toml中env_key的取值完全一致（大小写、下划线、拼写一个字都不能差），否则工具无法读取到密钥。
大白话解释：你给API Key起一个「变量名」，auth.json里用这个名字存密钥，config.toml里告诉Codex「去这个名字里找密钥」，两个名字必须一模一样。
1.2 配置范围：全局vs项目级（二选一，先做这个选择）
两套配置体系仅文件存放路径不同，配置格式、语法100%通用，你必须先在这里二选一，确定你的配置要作用的范围。
1.3 官方配置优先级黄金法则
当多种配置方式并存时，Codex CLI按以下优先级从高到低读取配置，高优先级会无条件覆盖低优先级的配置：
命令行临时参数（-c key=value）
Profile配置档案（--profile xxx启动指定）
项目级配置（./.codex/目录内文件）
全局配置（~/.codex/目录内文件）
系统环境变量
软件内置默认值
简单理解：越靠近执行目录的配置，优先级越高；同一条配置，项目里写了就用项目的，项目没写才用全局的。
1.4 配置安全红线（创建文件前必看）
绝对禁止将auth.json、包含API Key的配置文件提交到Git、SVN等代码仓库；
所有项目级配置，必须在项目根目录的.gitignore中添加以下规则：
Codex 敏感配置禁止提交
代码块
Plain Text
.codex/auth.json
.codex/*.key
.env
定期轮换API Key，最小化泄露风险；
生产环境优先使用环境变量注入密钥，避免明文写入配置文件。
二、第一步：创建你的配置目录（二选一）
根据上一章节的选择，完成对应配置目录的创建，全局配置和项目级配置二选一即可，无需重复创建。
2.1 选择A：全局长效配置（一次配置，本机通用）
适用场景
•
个人单用户使用，所有项目共用同一套配置；
•
无多项目隔离需求，希望一次配置后，所有终端调用都能直接使用。
分步创建流程
打开终端，执行对应系统的命令，创建全局配置目录（目录已存在可直接跳过）：
代码块
Plain Text
macOS/Linux 执行
mkdir -p ~/.codex
Windows PowerShell 执行
mkdir $env:USERPROFILE\.codex -Force
进入刚创建的.codex目录，后续的auth.json和config.toml都将放在这个目录中。
2.2 选择B：项目级独立配置（多项目隔离，互不干扰）
适用场景
•
多项目开发，不同项目需要使用不同的API密钥、模型、接口地址；
•
工作项目与个人项目隔离，避免配置互相影响；
•
团队项目统一配置，确保所有成员使用一致的规则。
分步创建流程
进入你的目标项目根目录：
代码块
Plain Text
切换到你的项目根目录
cd /path/to/your/project
创建项目级配置目录：
代码块
Plain Text
项目根目录下创建.codex文件夹
配置.gitignore安全规则，在项目根目录的.gitignore文件中添加以下内容，从根源避免密钥泄露：
代码块
Plain Text
Codex 敏感配置禁止提交
.codex/auth.json
.codex/*.key
.env
后续的auth.json和config.toml都将放在项目根目录的.codex文件夹中。
三、第二步：选择你的配置场景（三选一，开箱即用模板）
重要说明：
以下所有配置模板，全局配置和项目级配置100%通用，仅需将文件放入上一步创建的.codex目录中即可；
以下3个场景完全平等，三选一即可，无强制要求必须使用OpenAI官方服务，国内用户优先选场景2/3。
3.1 场景1：OpenAI官方服务配置（直连官方，海外用户首选）
适用条件
•
拥有ChatGPT Plus/Pro/Enterprise订阅账号，或OpenAI官方API Key；
•
网络环境可正常直连OpenAI官方服务。
配置方式二选一
方式A：ChatGPT账号OAuth一键登录（订阅用户首选）
无需手动创建配置文件，全程可视化操作，执行一条命令即可完成配置：
代码块
Plain Text
启动官方OAuth登录流程
codex login
执行后终端会弹出授权链接，复制到浏览器打开，登录你的ChatGPT订阅账号完成授权，系统会自动在你的配置目录生成auth.json和基础配置文件，无需手动编写。
方式B：API Key稳定配置（开发者首选）
手动创建两个核心配置文件，可控性强、稳定性高：
在.codex目录中新建auth.json文件，写入以下内容：
{
"auth_mode": "apikey",
"OPENAI_API_KEY": "sk-你的OpenAI官方API密钥"
}
运行项目并下载源码
json
1
2
3
4
同目录下新建config.toml文件，写入以下完整模板：
===== 基础必填配置 =====
model_provider = "openai"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
model_verbosity = "medium"
personality = "pragmatic"
web_search = "cached"
===== 安全基础配置（必配） =====
approval_policy = "on-request"
sandbox_mode = "workspace-write"
===== OpenAI官方配置块 =====
[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
运行项目并下载源码
toml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
连通性验证命令
codex "用一句话介绍一下你自己"
运行项目并下载源码
bash
1
✅ 成功标志：终端正常返回AI回复，无401、连接超时报错。
3.2 场景2：第三方API中转服务配置（国内用户首选，无需代理）
适用条件
无法直连OpenAI官方服务，使用OneAPI/NewAPI等兼容OpenAI格式的中转服务；
已获取中转服务的API地址与API Key。
特别注意:
此处的配置只做参考，中转站有自己的配置方式，就按他们的方式！！！！
完整配置模板
在.codex目录中新建auth.json文件，写入以下内容：
{
"auth_mode": "apikey",
"TRANSIT_API_KEY": "你的中转服务API密钥"
}
运行项目并下载源码
json
1
2
3
4
同目录下新建config.toml文件，写入以下完整模板：
===== 基础必填配置 =====
model_provider = "transit"
model = "中转服务支持的模型名称，如gpt-4o"
model_reasoning_effort = "medium"
personality = "pragmatic"
web_search = "disabled"
===== 安全基础配置（必配） =====
approval_policy = "on-request"
sandbox_mode = "workspace-write"
===== 中转服务配置块 =====
[model_providers.transit]
name = "第三方中转服务"
base_url = "你的中转服务接口地址，如https://xxx.xxx/v1"
wire_api = "chat"
env_key = "TRANSIT_API_KEY"
可选：请求重试配置，网络不稳定可适当调大
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000
运行项目并下载源码
toml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
连通性验证命令
codex "输出1+1的结果"
运行项目并下载源码
bash
1
✅ 成功标志：终端正常返回计算结果，无认证、连接报错。
3.3 场景3：国内云服务商配置（国内网络直连，合规稳定）
适用条件
无外网访问环境，仅能使用国内网络；
希望使用国内合规大模型服务，无需备案、无需代理。
特别注意:
此处的配置只做参考，国内主流服务商有自己的配置方式，就按他们的方式！！！！
国内主流服务商核心信息速查表
服务商 核心配置标识 推荐编程模型 官方接口地址
阿里云百炼 dashscope qwen-coder-plus https://dashscope.aliyuncs.com/compatible-mode/v1
腾讯云混元 hunyuan hunyuan-coder https://api.hunyuan.tencent.com/v1
DeepSeek deepseek deepseek-coder-v2 https://api.deepseek.com
智谱AI zhipu glm-4-coder https://open.bigmodel.cn/api/paas/v4
火山引擎方舟 volcengine 你的Endpoint ID https://ark.cn-beijing.volces.com/api/v3
通用配置模板（替换对应标识即可，附完整示例）
auth.json 通用模板（所有国内服务商通用！）
{
"auth_mode": "apikey",
"DOMESTIC_API_KEY": "你的对应服务商API密钥"
}
运行项目并下载源码
json
1
2
3
4
config.toml 通用模板（以阿里云百炼为例，其他服务商仅需替换速查表对应内容）
===== 基础必填配置 =====
model_provider = "dashscope"
model = "qwen-coder-plus"
model_reasoning_effort = "medium"
personality = "pragmatic"
web_search = "disabled"
===== 安全基础配置（必配） =====
approval_policy = "on-request"
sandbox_mode = "workspace-write"
===== 服务商配置块 =====
[model_providers.dashscope]
name = "阿里云百炼"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
wire_api = "chat"
env_key = "DOMESTIC_API_KEY"
运行项目并下载源码
toml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
完整示例：腾讯云混元可直接复制的最终配置
auth.json
{
"auth_mode": "apikey",
"DOMESTIC_API_KEY": "sk-xxxxxx你的腾讯云混元API密钥"
}
运行项目并下载源码
json
1
2
3
4
config.toml
===== 基础必填配置 =====
model_provider = "hunyuan"
model = "hunyuan-coder"
model_reasoning_effort = "medium"
personality = "pragmatic"
web_search = "disabled"
===== 安全基础配置（必配） =====
approval_policy = "on-request"
sandbox_mode = "workspace-write"
===== 腾讯云混元配置块 =====
[model_providers.hunyuan]
name = "腾讯云混元"
base_url = "https://api.hunyuan.tencent.com/v1"
wire_api = "chat"
env_key = "DOMESTIC_API_KEY"
运行项目并下载源码
toml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
连通性验证命令
codex "写一个最简单的Hello World程序"
运行项目并下载源码
bash
1
✅ 成功标志：终端正常返回代码内容，无报错。
四、备查手册：核心配置参数全详解
说明：本章节为所有配置参数的官方完整解释，新手可先跳过，按需查阅；所有参数的默认值均为官方推荐值，无需修改即可正常运行。
4.1 全局基础配置参数
参数名 类型 必填 默认值 官方详细说明
model_provider string 是 openai 模型提供商标识，必须和下方[model_providers.xxx]中的xxx完全一致
model string 是 系统默认 使用的模型名称，需与服务商支持的模型完全匹配
model_reasoning_effort string 否 medium 模型推理强度，可选值：minimal/low/medium/high/xhigh，强度越高推理效果越好，耗时和token消耗也越高
model_verbosity string 否 medium 输出详细程度，可选值：low/medium/high，仅Responses API生效
personality string 否 pragmatic AI回复风格，可选值：none/friendly/pragmatic
web_search string 否 cached 网络搜索模式，可选值：disabled/cached/live，中转/国内云服务通常不支持，建议设为disabled
4.2 模型服务商配置参数（[model_providers.xxx]块）
参数名 类型 必填 默认值 官方详细说明
name string 否 - 提供商显示名称，仅用于界面展示，无实际功能影响
base_url string 是 - API接口请求地址，通常以/v1结尾，结尾不能有多余斜杠
wire_api string 否 chat API协议类型，可选值：chat/responses，选择指南见4.4节
env_key string 是 - 存储API Key的环境变量名，必须和auth.json中的键名完全一致
request_max_retries number 否 4 HTTP请求失败后的最大重试次数
stream_max_retries number 否 5 SSE流中断后的最大重试次数
stream_idle_timeout_ms number 否 300000 流空闲超时时间，单位毫秒，默认5分钟
http_headers object 否 - 额外的静态HTTP请求头，格式为{ "Header-Name" = "value" }
4.3 安全权限配置参数
4.3.1 审批模式 approval_policy
控制Codex执行命令、修改文件前的审批行为，官方默认值on-request，可选值如下：
可选值 官方详细说明 适用场景
untrusted 最严格模式，仅已知安全的只读命令自动执行，其他所有操作均需人工审批 不受信任的第三方项目、开源代码审查
on-failure 命令在沙箱中自动执行，仅在执行失败时请求人工审批 本地个人项目、简单自动化任务
on-request 官方默认值，由模型判断是否需要审批，平衡安全与效率 日常开发、个人常用项目
never 全自动模式，所有操作无需审批直接执行，有安全风险 完全信任的本地项目、隔离的Docker环境
4.3.2 沙箱模式 sandbox_mode
控制Codex对本地文件系统的访问权限，官方默认值read-only，可选值如下：
可选值 官方详细说明 适用场景
read-only 官方默认值，仅允许读取本地文件，禁止任何修改、删除、创建操作 代码审查、项目分析、开源代码学习
workspace-write 仅允许写入当前工作目录（项目根目录），无法修改系统其他文件 日常开发、代码重构、项目文件修改
danger-full-access 完全系统访问权限，可修改/删除系统任意文件，极度危险 仅隔离的Docker/虚拟机环境使用，严禁本地生产环境使用
4.4 关键参数 wire_api 官方选择指南
可选值 适用场景 官方详细说明
chat 第三方中转服务、国内云服务商、所有兼容OpenAI Chat Completions格式的服务 通用兼容格式，绝大多数第三方服务仅支持此格式，填错会导致接口报错
responses OpenAI官方服务 OpenAI专属高级协议，支持更多原生特性，仅官方服务可用，第三方服务使用会报错
五、进阶玩法：配置高阶用法
5.1 环境变量配置方式（服务器/自动化场景首选）
除了配置文件方式，Codex CLI也支持通过系统环境变量读取认证信息，优先级低于项目级/全局配置文件，适合服务器、CI/CD、自动化脚本场景。
macOS/Linux 永久配置（写入~/.bashrc或~/.zshrc）
export OPENAI_API_KEY="你的API Key"
export OPENAI_BASE_URL="你的接口地址"
重载配置生效
source ~/.zshrc
Windows PowerShell 永久配置
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的API Key", "User")
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "你的接口地址", "User")
运行项目并下载源码
bash
1
2
3
4
5
6
7
8
9
10
5.2 多Profile配置档案（多环境一键切换）
如果你需要在工作、个人、测试等多个环境间快速切换，可使用Profile功能为不同环境创建独立的配置档案，无需手动修改配置文件。
在全局config.toml中添加Profile配置
默认配置
model = "gpt-5.3-codex"
工作环境配置档案
[profiles.work]
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
个人环境配置档案
[profiles.personal]
model = "deepseek-coder-v2"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
approval_policy = "never"
运行项目并下载源码
toml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
Profile快速切换命令
切换到工作环境配置
codex config profile use work
查看所有已创建的配置档案
codex config profile list
启动时直接指定配置档案
codex --profile work
运行项目并下载源码
bash
1
2
3
4
5
6
7
8
5.3 自定义指令配置
Codex CLI支持通过自定义指令文件，全局约束AI的行为规范、代码风格、输出格式等。
全局用户级指令：在全局配置目录创建instructions.md，对本机所有调用生效；
项目级指令：在项目根目录创建AGENTS.md，仅对当前项目生效。
六、排错指南：配置高频问题全解
6.1 认证类报错（401 Unauthorized/登录失效）
报错现象 核心解决方案（按优先级排序）
API Key模式401报错 1. 【最高频】检查auth.json中密钥变量名与config.toml中env_key是否完全一致，大小写、下划线不能有差异；
检查API Key是否正确、无多余空格、未过期、账户余额充足；
执行codex auth check检查认证状态，确认配置文件路径正确
OAuth登录失效 1. 执行/logout后重新执行codex login授权；
删除配置目录下的auth.json文件后重新授权；
检查网络是否可正常访问OpenAI授权地址
6.2 配置不生效类问题
问题现象 核心解决方案
配置修改后不生效 1. 执行codex config reload重载配置，或关闭重启终端；
校验JSON/TOML格式是否合法，无语法错误、多余逗号
项目级配置无法覆盖全局 1. 确认当前终端工作路径是项目根目录；
确认配置文件放在项目根目录的.codex文件夹中；
检查是否有优先级更高的Profile、环境变量覆盖配置
提示Not a directory (os error 20) 1. .codex路径被错误创建为文件，而非目录；
执行对应系统的删除重建命令即可修复
6.3 网络连接类报错（含URL访问异常专项解决）
报错现象 核心解决方案
连接超时/无法访问接口/link dead 1. 官方服务需确认网络可正常访问OpenAI，国内用户优先使用中转/国内云服务；
检查base_url是否正确，无多余斜杠、拼写错误、结尾缺少/v1；
关闭终端代理、防火墙重试，或配置正确的HTTPS代理；
确认接口地址在浏览器中可正常访问，服务商接口无宕机
link hit security strategy（阿里云等国内接口安全拦截） 1. 确认API Key已开通对应服务的权限，无IP白名单限制；
检查base_url是否为官方合规地址，无拼写错误；
确认账户无欠费、服务无封禁
网页解析失败/接口无响应 1. 【最高频】确认wire_api参数配置正确，第三方/国内服务必须用chat，不能用responses；
检查请求头是否符合服务商要求，可通过http_headers补充必要参数；
确认模型名称与服务商支持的完全一致，无大小写错误
502 Stream Error/流中断 1. 网络波动导致，重试即可；
调整stream_max_retries参数增加重试次数；
中转服务用户检查服务商接口稳定性
6.4 其他常见问题
问题现象 核心解决方案
409 Route Error (Invalid Client) 1. 清除浏览器缓存和Cookie，重新完成OAuth授权；
确认登录账号与注册账号一致，第三方注册账号需用对应方式登录
CLI正常但IDE插件无法工作 1. IDE插件不读取环境变量，需在全局~/.codex/auth.json中配置固定API Key；
重启IDE重新加载配置