Codex CLI教程（一） | 安装指南
Codex CLI教程（二） | 配置指南
Codex CLI教程（三） | 命令指南

一、必看：配置底层核心规则（新手先读，从根源避坑）

Codex CLI的所有配置，均基于2个核心文件和一套官方优先级规则实现，全场景通用，先看懂规则再动手，避免后续配置混乱、不生效。

1.1 2个核心配置文件（唯一核心，全场景通用）

所有配置仅围绕这两个文件展开，无其他额外依赖，格式错误、变量名不匹配是配置不生效的第一高频原因。

文件名	核心作用	格式要求	敏感等级
auth.json	唯一存储API密钥、OAuth登录令牌等敏感凭证，是工具连通服务的核心	严格JSON格式，禁止多余逗号、换行错误、中文引号	极高，绝对禁止泄露、禁止提交Git仓库
config.toml	主配置文件，定义模型服务商、接口地址、模型名称、运行规则、安全权限等所有核心行为	严格TOML格式，缩进规范、键值对完整	中，非敏感内容可做版本管理

📌 新手必记核心规则（90%的401报错都源于此）：
auth.json内的密钥变量名，必须和config.toml中env_key的取值完全一致（大小写、下划线、拼写一个字都不能差），否则工具无法读取到密钥。
大白话解释：你给API Key起一个「变量名」，auth.json里用这个名字存密钥，config.toml里告诉Codex「去这个名字里找密钥」，两个名字必须一模一样。

1.2 配置范围：全局vs项目级（二选一，先做这个选择）

两套配置体系仅文件存放路径不同，配置格式、语法100%通用，你必须先在这里二选一，确定你的配置要作用的范围。

配置类型	全系统对应路径	作用范围	优先级
全局配置	macOS/Linux：~/.codex/ Windows：C:\Users\你的用户名\.codex\	本机所有Codex调用通用，一次配置终身可用	低（可被项目级配置覆盖）
项目级配置	目标项目根目录：./.codex/	仅当前项目目录内生效，完全隔离其他项目	高（无条件覆盖全局配置）

1.3 官方配置优先级黄金法则

当多种配置方式并存时，Codex CLI按以下优先级从高到低读取配置，高优先级会无条件覆盖低优先级的配置：

1. 命令行临时参数（-c key=value）
2. Profile配置档案（--profile xxx启动指定）
3. 项目级配置（./.codex/目录内文件）
4. 全局配置（~/.codex/目录内文件）
5. 系统环境变量
6. 软件内置默认值

简单理解：越靠近执行目录的配置，优先级越高；同一条配置，项目里写了就用项目的，项目没写才用全局的。

1.4 配置安全红线（创建文件前必看）

1. 绝对禁止将auth.json、包含API Key的配置文件提交到Git、SVN等代码仓库；
2. 所有项目级配置，必须在项目根目录的.gitignore中添加以下规则：

   # Codex 敏感配置禁止提交
   .codex/auth.json
   .codex/*.key
   .env
   

3. 定期轮换API Key，最小化泄露风险；
4. 生产环境优先使用环境变量注入密钥，避免明文写入配置文件。

---

二、第一步：创建你的配置目录（二选一）

根据上一章节的选择，完成对应配置目录的创建，全局配置和项目级配置二选一即可，无需重复创建。

2.1 选择A：全局长效配置（一次配置，本机通用）

适用场景

• 个人单用户使用，所有项目共用同一套配置；
• 无多项目隔离需求，希望一次配置后，所有终端调用都能直接使用。

分步创建流程

1. 打开终端，执行对应系统的命令，创建全局配置目录（目录已存在可直接跳过）：

   # macOS/Linux 执行
   mkdir -p ~/.codex
   
   # Windows PowerShell 执行
   mkdir $env:USERPROFILE\.codex -Force
   

2. 进入刚创建的.codex目录，后续的auth.json和config.toml都将放在这个目录中。

2.2 选择B：项目级独立配置（多项目隔离，互不干扰）

适用场景

• 多项目开发，不同项目需要使用不同的API密钥、模型、接口地址；
• 工作项目与个人项目隔离，避免配置互相影响；
• 团队项目统一配置，确保所有成员使用一致的规则。

分步创建流程

1. 进入你的目标项目根目录：

   # 切换到你的项目根目录
   cd /path/to/your/project
   

2. 创建项目级配置目录：

   # 项目根目录下创建.codex文件夹
   mkdir -p .codex
   

3. 配置.gitignore安全规则，在项目根目录的.gitignore文件中添加以下内容，从根源避免密钥泄露：

   # Codex 敏感配置禁止提交
   .codex/auth.json
   .codex/*.key
   .env
   

4. 后续的auth.json和config.toml都将放在项目根目录的.codex文件夹中。

---

三、第二步：选择你的配置场景（三选一，开箱即用模板）

重要说明：

1. 以下所有配置模板，全局配置和项目级配置100%通用，仅需将文件放入上一步创建的.codex目录中即可；
2. 以下3个场景完全平等，三选一即可，无强制要求必须使用OpenAI官方服务，国内用户优先选场景2/3。

3.1 场景1：OpenAI官方服务配置（直连官方，海外用户首选）

适用条件

• 拥有ChatGPT Plus/Pro/Enterprise订阅账号，或OpenAI官方API Key；
• 网络环境可正常直连OpenAI官方服务。

配置方式二选一

方式A：ChatGPT账号OAuth一键登录（订阅用户首选）

无需手动创建配置文件，全程可视化操作，执行一条命令即可完成配置：

# 启动官方OAuth登录流程
codex login

执行后终端会弹出授权链接，复制到浏览器打开，登录你的ChatGPT订阅账号完成授权，系统会自动在你的配置目录生成auth.json和基础配置文件，无需手动编写。

方式B：API Key稳定配置（开发者首选）

手动创建两个核心配置文件，可控性强、稳定性高：

1. 在.codex目录中新建auth.json文件，写入以下内容：

   {
     "auth_mode": "apikey",
     "OPENAI_API_KEY": "sk-你的OpenAI官方API密钥"
   }
   

2. 同目录下新建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"
   

连通性验证命令

codex "用一句话介绍一下你自己"

✅ 成功标志：终端正常返回AI回复，无401、连接超时报错。

3.2 场景2：第三方API中转服务配置（国内用户首选，无需代理）

适用条件

• 无法直连OpenAI官方服务，使用OneAPI/NewAPI等兼容OpenAI格式的中转服务；
• 已获取中转服务的API地址与API Key。

特别注意:
此处的配置只做参考，中转站有自己的配置方式，就按他们的方式！！！！

完整配置模板

1. 在.codex目录中新建auth.json文件，写入以下内容：

   {
     "auth_mode": "apikey",
     "TRANSIT_API_KEY": "你的中转服务API密钥"
   }
   

2. 同目录下新建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
   

连通性验证命令

codex "输出1+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

通用配置模板（替换对应标识即可，附完整示例）

1. auth.json 通用模板（所有国内服务商通用！）

{
  "auth_mode": "apikey",
  "DOMESTIC_API_KEY": "你的对应服务商API密钥"
}

2. 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"

完整示例：腾讯云混元可直接复制的最终配置

1. auth.json

{
  "auth_mode": "apikey",
  "DOMESTIC_API_KEY": "sk-xxxxxx你的腾讯云混元API密钥"
}

2. 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"

连通性验证命令

codex "写一个最简单的Hello World程序"

✅ 成功标志：终端正常返回代码内容，无报错。

---

四、备查手册：核心配置参数全详解

说明：本章节为所有配置参数的官方完整解释，新手可先跳过，按需查阅；所有参数的默认值均为官方推荐值，无需修改即可正常运行。

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")

5.2 多Profile配置档案（多环境一键切换）

如果你需要在工作、个人、测试等多个环境间快速切换，可使用Profile功能为不同环境创建独立的配置档案，无需手动修改配置文件。

1. 在全局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"

2. Profile快速切换命令

# 切换到工作环境配置
codex config profile use work

# 查看所有已创建的配置档案
codex config profile list

# 启动时直接指定配置档案
codex --profile work

5.3 自定义指令配置

Codex CLI支持通过自定义指令文件，全局约束AI的行为规范、代码风格、输出格式等。

• 全局用户级指令：在全局配置目录创建instructions.md，对本机所有调用生效；
• 项目级指令：在项目根目录创建AGENTS.md，仅对当前项目生效。

---

六、排错指南：配置高频问题全解

6.1 认证类报错（401 Unauthorized/登录失效）

报错现象	核心解决方案（按优先级排序）
API Key模式401报错	1. 【最高频】检查auth.json中密钥变量名与config.toml中env_key是否完全一致，大小写、下划线不能有差异； 2. 检查API Key是否正确、无多余空格、未过期、账户余额充足； 3. 执行codex auth check检查认证状态，确认配置文件路径正确
OAuth登录失效	1. 执行/logout后重新执行codex login授权； 2. 删除配置目录下的auth.json文件后重新授权； 3. 检查网络是否可正常访问OpenAI授权地址

6.2 配置不生效类问题

问题现象	核心解决方案
配置修改后不生效	1. 执行codex config reload重载配置，或关闭重启终端； 2. 校验JSON/TOML格式是否合法，无语法错误、多余逗号
项目级配置无法覆盖全局	1. 确认当前终端工作路径是项目根目录； 2. 确认配置文件放在项目根目录的.codex文件夹中； 3. 检查是否有优先级更高的Profile、环境变量覆盖配置
提示Not a directory (os error 20)	1. .codex路径被错误创建为文件，而非目录； 2. 执行对应系统的删除重建命令即可修复

6.3 网络连接类报错（含URL访问异常专项解决）

报错现象	核心解决方案
连接超时/无法访问接口/link dead	1. 官方服务需确认网络可正常访问OpenAI，国内用户优先使用中转/国内云服务； 2. 检查base_url是否正确，无多余斜杠、拼写错误、结尾缺少/v1； 3. 关闭终端代理、防火墙重试，或配置正确的HTTPS代理； 4. 确认接口地址在浏览器中可正常访问，服务商接口无宕机
link hit security strategy（阿里云等国内接口安全拦截）	1. 确认API Key已开通对应服务的权限，无IP白名单限制； 2. 检查base_url是否为官方合规地址，无拼写错误； 3. 确认账户无欠费、服务无封禁
网页解析失败/接口无响应	1. 【最高频】确认wire_api参数配置正确，第三方/国内服务必须用chat，不能用responses； 2. 检查请求头是否符合服务商要求，可通过http_headers补充必要参数； 3. 确认模型名称与服务商支持的完全一致，无大小写错误
502 Stream Error/流中断	1. 网络波动导致，重试即可； 2. 调整stream_max_retries参数增加重试次数； 3. 中转服务用户检查服务商接口稳定性

6.4 其他常见问题

问题现象	核心解决方案
409 Route Error (Invalid Client)	1. 清除浏览器缓存和Cookie，重新完成OAuth授权； 2. 确认登录账号与注册账号一致，第三方注册账号需用对应方式登录
CLI正常但IDE插件无法工作	1. IDE插件不读取环境变量，需在全局~/.codex/auth.json中配置固定API Key； 2. 重启IDE重新加载配置

---