Codex: Codex 配置与定制
最后更新：2026-08-31
Codex 提供丰富的配置选项，从基本的 API 设置到高级的审批策略和沙箱配置，都可以根据需求定制。
📋 前置知识：已完成 Codex 安装与基本使用
1. 你将学到
- 配置文件位置与结构
- 基础配置项
- 高级配置选项
- 项目级 vs 全局配置
2. 配置文件位置
| 配置类型 | 路径 | 作用范围 |
|---|---|---|
| 全局配置 | ~/.codex/config.toml |
所有项目 |
| 认证配置 | ~/.codex/auth.json |
API Key 等 |
| 项目配置 | .codex/config.toml |
当前项目 |
| AGENTS.md | AGENTS.md |
项目规则与上下文 |
3. 全局配置 config.toml
(1) 基础配置
TOML
# ~/.codex/config.toml
# 模型设置
model = "gpt-5-codex"
# 审批策略：ask / approve / deny
approval_policy = "ask"
# 沙箱模式：readonly / workspace-write / full-access
sandbox_mode = "workspace-write"
# 上下文窗口大小（tokens）
context_window = 128000
(2) 认证配置 auth.json
JSON
{
"OPENAI_API_KEY": "sk-你的API密钥",
"OPENAI_BASE_URL": "https://api.openai.com/v1"
}
▶ 示例 1: Alice 的配置
TOML
# Alice 的全局配置
model = "gpt-5-codex"
approval_policy = "ask"
sandbox_mode = "workspace-write"
# 自定义提示词前缀
system_prompt_prefix = """
你是一个资深全栈工程师，擅长 TypeScript 和 Python。
代码风格遵循：
- 使用类型注解
- 函数不超过 50 行
- 每个函数都有文档字符串
"""
4. 高级配置
(1) 审批策略详解
| 策略 | 行为 | 适用场景 |
|---|---|---|
ask |
每次敏感操作需确认 | 日常开发（默认） |
approve |
自动批准所有操作 | 受信任的自动化场景 |
deny |
拒绝所有敏感操作 | 只读审查 |
TOML
# 按操作类型设置审批
[approval]
shell_commands = "ask" # shell 命令需确认
file_writes = "approve" # 文件写入自动批准
network_access = "deny" # 禁止网络访问
sensitive_paths = "ask" # 敏感路径需确认
(2) 沙箱配置
TOML
# 沙箱模式
[sandbox]
mode = "workspace-write" # 仅允许写入工作区
allowed_paths = ["src/", "test/"] # 限制可写入路径
blocked_paths = [".env", "secrets/"] # 禁止访问路径
network = false # 禁止网络访问
(3) 上下文管理
TOML
[context]
auto_compact = true # 自动压缩上下文
compact_threshold = 0.8 # 使用 80% 时触发压缩
max_file_size = "100KB" # 单文件最大读取大小
include_patterns = ["*.py", "*.ts", "*.js"] # 包含文件模式
exclude_patterns = ["node_modules/", ".git/"] # 排除模式
5. 项目级配置
在项目根目录创建 .codex/config.toml，覆盖全局配置：
TOML
# .codex/config.toml（项目级）
# 项目特定模型
model = "deepseek-coder"
# 项目特定审批策略
approval_policy = "approve"
# 项目特定沙箱
[sandbox]
allowed_paths = ["src/", "tests/"]
blocked_paths = ["production/", "secrets/"]
▶ 示例 2: Bob 的项目配置
TOML
# Bob 的前端项目配置
# .codex/config.toml
model = "gpt-5-codex"
approval_policy = "ask"
[context]
include_patterns = ["*.tsx", "*.ts", "*.css"]
exclude_patterns = ["node_modules/", "dist/", ".next/"]
[sandbox]
allowed_paths = ["src/", "public/", "styles/"]
blocked_paths = [".env.local", ".env.production"]
6. AGENTS.md 项目规则
AGENTS.md 是项目级规则文件，放在项目根目录，Codex 会自动读取：
MARKDOWN
# AGENTS.md
## 项目规则
- 使用 TypeScript strict 模式
- 所有 API 端点必须有输入验证
- 测试覆盖率不低于 80%
- 提交前运行 npm run lint
## 代码风格
- 使用函数式组件
- 命名：驼峰式
- 文件：kebab-case
## 禁止操作
- 不要修改 .env 文件
- 不要删除测试文件
- 不要安装新依赖（需人工确认）
7. 环境变量配置
| 变量 | 说明 | 示例 |
|---|---|---|
OPENAI_API_KEY |
API 密钥 | sk-xxx |
OPENAI_BASE_URL |
API 端点 | https://api.deepseek.com |
CODEX_MODEL |
默认模型 | gpt-5-codex |
CODEX_SANDBOX |
沙箱模式 | workspace-write |
BASH
# 临时覆盖
CODEX_MODEL=deepseek-coder codex
8. 配置优先级
TEXT
📖 仅展示
命令行参数 > 环境变量 > 项目配置 > 全局配置 > 默认值
▶ 示例 3: 优先级实战
BASH
# 全局配置：model = "gpt-5-codex"
# 项目配置：model = "deepseek-coder"
# 环境变量：CODEX_MODEL="gpt-4o"
# 最终使用：gpt-4o（环境变量 > 项目配置 > 全局配置）
CODEX_MODEL="gpt-4o" codex
# 命令行参数最高优先
codex --model o3
# 最终使用：o3
❓ 常见问题
Q 项目配置和全局配置冲突怎么办？
A 项目配置优先于全局配置。Codex 会先读取全局配置，再用项目配置覆盖。
Q AGENTS.md 和 config.toml 有什么区别？
A config.toml 是技术配置（模型、沙箱、审批策略），AGENTS.md 是自然语言规则（代码风格、禁止操作、项目约定）。两者互补。
Q 可以把 API Key 放在项目配置里吗？
A 不建议。API Key 应放在
~/.codex/auth.json 或环境变量中，避免泄露到 git 仓库。Q 如何查看当前生效的完整配置？
A 运行
codex --show-config 查看合并后的完整配置。Q 配置改错了怎么办？
A 直接编辑配置文件修改，或删除配置文件恢复默认值。Codex 会在下次启动时重新读取。
📖 小节
- 全局配置
~/.codex/config.toml，项目配置.codex/config.toml - 审批策略：ask / approve / deny
- 沙箱模式：readonly / workspace-write / full-access
- AGENTS.md 用自然语言定义项目规则
- 配置优先级：命令行 > 环境变量 > 项目 > 全局 > 默认
📝 作业
- 基础题（难度⭐）：创建全局配置文件，设置默认模型和审批策略。
- 进阶题（难度⭐⭐）：为你的项目创建项目级配置和 AGENTS.md，定义代码风格和禁止操作。
- 挑战题（难度⭐⭐⭐）：设计一个多环境配置方案——开发用 DeepSeek、生产相关任务用 OpenAI，实现自动切换。
