AgentHarness 课程

第四课：配置系统详解

1.5万字·38分钟·
config.toml6层优先级Profile管理常用配置项

深入理解 Codex CLI 的配置系统，掌握从基础配置到高级定制的完整知识体系。

1. 配置文件概述

1.1 配置文件位置

Codex CLI 使用 TOML 格式的配置文件，主要配置文件位于：

~/.codex/config.toml

完整路径示例：

  • Linux/macOS: /home/username/.codex/config.toml 或 /Users/username/.codex/config.toml
  • Windows: C:\Users\username\.codex\config.toml

1.2 配置文件结构

配置文件采用 TOML 格式（Tom's Obvious, Minimal Language），具有清晰的层级结构：

# 全局设置
model = "codex-mini-latest"
model_provider = "openai"
sandbox = "workspace-write"
approval_policy = "on-request"

# TUI 界面配置
[tui]
alternate_screen = true
vim_mode_default = false
dark_mode = true
theme = "dark"

# MCP 服务器配置
[mcp_servers]
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

# 环境变量
[env]
NODE_ENV = "development"
DEBUG = "codex:*"

2. 六层配置优先级体系

Codex 采用六层配置优先级系统，从低到高依次为：

2.1 优先级层级（从低到高）

层级配置来源说明示例
1️⃣默认值Codex 内置的基础参数model = "codex-mini-latest"
2️⃣托管配置系统级配置（管理员设置）/etc/codex/config.toml
3️⃣全局用户配置用户级配置~/.codex/config.toml
4️⃣Profile 配置特定场景的配置集~/.codex/profiles/work.toml
5️⃣项目级配置项目目录下的配置.codex/config.toml
6️⃣命令行覆盖运行时参数--model gpt-4

2.2 优先级解析示例

假设以下配置场景：

# 默认值（内置）
model = "codex-mini-latest"

# 用户配置 (~/.codex/config.toml)
model = "gpt-4"

# 项目配置 (.codex/config.toml)
model = "gpt-4-turbo"

# 命令行参数
# codex --model gpt-4o

最终生效的配置：model = "gpt-4o"（命令行覆盖优先级最高）

2.3 配置合并策略

Codex 使用深度合并策略：

# 用户配置
[tui]
theme = "dark"
vim_mode_default = false

# 项目配置
[tui]
alternate_screen = true

合并结果：

[tui]
theme = "dark"          # 来自用户配置
vim_mode_default = false  # 来自用户配置
alternate_screen = true   # 来自项目配置

3. 关键配置项详解

3.1 模型配置

model

指定使用的 AI 模型：

# 推荐模型
model = "codex-mini-latest"    # Codex 专用模型（默认）
model = "gpt-4"                # GPT-4 模型
model = "gpt-4-turbo"          # GPT-4 Turbo 模型
model = "gpt-4o"               # GPT-4o 模型

模型选择建议：

  • 日常开发：codex-mini-latest（性价比最高）
  • 复杂任务：gpt-4 或 gpt-4-turbo
  • 最新能力：gpt-4o

model_provider

指定模型提供商：

model_provider = "openai"      # OpenAI 官方（默认）
model_provider = "azure"       # Azure OpenAI
model_provider = "ollama"      # 本地 Ollama 模型

提供商配置示例：

# OpenAI 配置
[model_providers.openai]
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"

# Azure 配置
[model_providers.azure]
base_url = "https://your-resource.openai.azure.com/"
api_key_env = "AZURE_OPENAI_API_KEY"
api_version = "2024-02-15-preview"

# Ollama 本地模型
[model_providers.ollama]
base_url = "http://localhost:11434/v1"
api_key = "ollama"

3.2 沙箱配置 (sandbox)

沙箱控制 Codex 执行命令的安全边界：

# 三种沙箱模式
sandbox = "read-only"              # 只读模式
sandbox = "workspace-write"        # 工作区写入模式（默认）
sandbox = "danger-full-access"     # 完全访问模式（危险）

沙箱模式详解：

模式文件读取文件写入命令执行网络访问适用场景
read-only✅❌❌❌代码审查、文档生成
workspace-write✅✅（工作区）✅（受限）✅日常开发
danger-full-access✅✅（任意）✅（任意）✅系统管理（慎用）

安全建议：

# 生产环境推荐
sandbox = "read-only"

# 开发环境推荐
sandbox = "workspace-write"

# 仅在明确需要时使用
# sandbox = "danger-full-access"

3.3 审批策略 (approval_policy)

控制何时需要用户确认：

# 三种审批策略
approval_policy = "untrusted"     # 不信任模式
approval_policy = "on-request"    # 按需审批（默认）
approval_policy = "never"         # 从不审批

审批策略详解：

策略说明安全级别适用场景
untrusted所有操作都需要确认🔒🔒🔒 最高生产环境、敏感操作
on-request仅在需要时请求确认🔒🔒 中等日常开发（推荐）
never从不请求确认🔒 最低自动化脚本、测试环境

配置示例：

# 开发环境配置
approval_policy = "on-request"

# 自动化测试配置
approval_policy = "never"

# 生产环境配置
approval_policy = "untrusted"

3.4 TUI 界面配置

Terminal User Interface（终端用户界面）配置：

[tui]
# 是否使用备用屏幕缓冲区
alternate_screen = true

# 是否默认启用 Vim 模式
vim_mode_default = false

# 是否启用深色模式
dark_mode = true

# 主题设置
theme = "dark"  # 可选: "dark", "light", "auto"

# 自动滚动到底部
auto_scroll = true

# 显示行号
show_line_numbers = true

# 语法高亮
syntax_highlighting = true

Vim 模式快捷键：

  • i - 进入插入模式
  • Esc - 返回普通模式
  • dd - 删除当前行
  • yy - 复制当前行
  • p - 粘贴
  • /pattern - 搜索

3.5 MCP 服务器配置

Model Context Protocol（MCP）服务器配置：

[mcp_servers]

# GitHub MCP 服务器
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxxx" }

# 文件系统 MCP 服务器
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

# PostgreSQL MCP 服务器
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgresql://user:pass@localhost/db" }

# 自定义 MCP 服务器
[mcp_servers.custom]
command = "python"
args = ["-m", "my_mcp_server"]
env = { API_KEY = "xxx" }

MCP 服务器管理：

# 列出已配置的 MCP 服务器
codex mcp list

# 测试 MCP 服务器连接
codex mcp test github

# 重启 MCP 服务器
codex mcp restart github

3.6 环境变量配置

[env]
# Node.js 环境
NODE_ENV = "development"
DEBUG = "codex:*"

# Python 环境
PYTHONPATH = "/path/to/modules"
VIRTUAL_ENV = "/path/to/venv"

# 自定义变量
MY_API_KEY = "xxx"
CUSTOM_CONFIG = "value"

3.7 工具权限配置

[tools]
# 允许的工具
allow = ["terminal", "file_editor", "browser"]

# 禁止的工具
deny = ["dangerous_tool"]

# 终端配置
[tools.terminal]
# 允许的命令
allow_commands = ["git", "npm", "python", "pip"]

# 禁止的命令
deny_commands = ["rm -rf", "sudo", "chmod 777"]

# 命令超时时间（秒）
timeout = 300

4. Profile 管理

4.1 Profile 概述

Profile 允许你为不同场景创建独立的配置集：

# 使用 Profile 启动 Codex
codex --profile work
codex --profile personal
codex --profile testing

4.2 Profile 文件位置

~/.codex/profiles/
├── work.toml
├── personal.toml
├── testing.toml
└── production.toml

4.3 创建 Profile

方法一：手动创建

# 创建 Profile 目录
mkdir -p ~/.codex/profiles

# 创建工作 Profile
cat > ~/.codex/profiles/work.toml << EOF
model = "gpt-4"
sandbox = "workspace-write"
approval_policy = "on-request"

[tui]
theme = "dark"
vim_mode_default = true

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
EOF

方法二：从当前配置创建

# 导出当前配置为 Profile
codex config export --profile work

# 编辑 Profile
codex config edit --profile work

4.4 Profile 配置示例

work.toml（工作环境）：

model = "gpt-4"
model_provider = "openai"
sandbox = "workspace-write"
approval_policy = "on-request"

[tui]
theme = "dark"
vim_mode_default = true
auto_scroll = true

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[env]
NODE_ENV = "development"
DEBUG = "codex:*"

testing.toml（测试环境）：

model = "codex-mini-latest"
sandbox = "workspace-write"
approval_policy = "never"

[tui]
theme = "light"
vim_mode_default = false

[env]
NODE_ENV = "test"
CI = "true"

production.toml（生产环境）：

model = "gpt-4"
sandbox = "read-only"
approval_policy = "untrusted"

[tui]
theme = "dark"
vim_mode_default = false

[env]
NODE_ENV = "production"

4.5 Profile 管理命令

# 列出所有 Profile
codex profile list

# 查看 Profile 内容
codex profile show work

# 删除 Profile
codex profile delete testing

# 复制 Profile
codex profile copy work personal

# 设置默认 Profile
codex profile set-default work

5. 项目级配置

5.1 项目配置文件

在项目根目录创建 .codex/config.toml：

my-project/
├── .codex/
│   ├── config.toml      # 项目配置
│   └── prompts/         # 项目提示词
│       └── code-review.md
├── src/
├── tests/
└── README.md

5.2 项目配置示例

# .codex/config.toml
model = "gpt-4-turbo"
sandbox = "workspace-write"
approval_policy = "on-request"

# 项目特定的 MCP 服务器
[mcp_servers]
[mcp_servers.project-db]
command = "python"
args = ["-m", "project_mcp_server"]
env = { DATABASE_URL = "sqlite:///./data/app.db" }

# 项目环境变量
[env]
PROJECT_ENV = "development"
LOG_LEVEL = "debug"

# 项目工具配置
[tools.terminal]
allow_commands = ["npm", "yarn", "git", "python"]
deny_commands = ["rm -rf /", "sudo"]

5.3 多级项目配置

Codex 支持多级项目配置，从当前目录向上查找：

/home/user/projects/
├── .codex/config.toml          # 父项目配置
└── my-app/
    ├── .codex/config.toml      # 子项目配置（优先级更高）
    └── src/

优先级规则：

  • 离当前工作目录最近的配置文件优先级最高
  • 配置项采用深度合并策略

6. 常用配置示例

6.1 开发环境配置

# ~/.codex/config.toml
model = "codex-mini-latest"
model_provider = "openai"
sandbox = "workspace-write"
approval_policy = "on-request"

[tui]
theme = "dark"
vim_mode_default = true
auto_scroll = true
show_line_numbers = true
syntax_highlighting = true

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

[env]
NODE_ENV = "development"
DEBUG = "codex:*"
EDITOR = "vim"

6.2 自动化脚本配置

# ~/.codex/profiles/automation.toml
model = "codex-mini-latest"
sandbox = "workspace-write"
approval_policy = "never"

[tui]
theme = "light"
vim_mode_default = false
auto_scroll = false

[env]
CI = "true"
AUTOMATION = "true"

6.3 代码审查配置

# ~/.codex/profiles/review.toml
model = "gpt-4"
sandbox = "read-only"
approval_policy = "untrusted"

[tui]
theme = "dark"
vim_mode_default = false
show_line_numbers = true

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

6.4 多模型配置

# 支持多模型切换
[model_providers.openai]
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"

[model_providers.anthropic]
base_url = "https://api.anthropic.com"
api_key_env = "ANTHROPIC_API_KEY"

[model_providers.ollama]
base_url = "http://localhost:11434/v1"
api_key = "ollama"

# 默认使用 OpenAI
model = "gpt-4"
model_provider = "openai"

7. 配置调试与诊断

7.1 /debug-config 命令

在 Codex 交互界面中使用 /debug-config 命令查看当前配置：

# 在 Codex 交互界面中输入
/debug-config

输出示例：

📋 Codex Configuration Debug Info
================================

🔧 Model Configuration:
  Model: gpt-4
  Provider: openai
  Base URL: https://api.openai.com/v1

🔒 Security Configuration:
  Sandbox: workspace-write
  Approval Policy: on-request

🖥️ TUI Configuration:
  Theme: dark
  Vim Mode: true
  Auto Scroll: true

🔌 MCP Servers:
  - github: connected
  - filesystem: connected

📁 Config Sources (priority high→low):
  1. CLI args: --model gpt-4
  2. Project: .codex/config.toml
  3. Profile: work
  4. User: ~/.codex/config.toml
  5. System: /etc/codex/config.toml
  6. Default: built-in

🌍 Environment Variables:
  OPENAI_API_KEY: ***
  NODE_ENV: development

7.2 配置验证命令

# 验证配置文件语法
codex config validate

# 检查配置冲突
codex config check

# 显示配置来源
codex config sources

# 导出当前配置
codex config export

7.3 常见配置问题排查

问题 1：配置未生效

# 检查配置优先级
codex config sources

# 查看最终生效的配置
codex config show

问题 2：MCP 服务器连接失败

# 测试 MCP 服务器
codex mcp test github

# 查看 MCP 服务器日志
codex mcp logs github

# 重启 MCP 服务器
codex mcp restart github

问题 3：权限问题

# 检查文件权限
ls -la ~/.codex/config.toml

# 修复权限
chmod 600 ~/.codex/config.toml

# 检查沙箱设置
codex config get sandbox

7.4 配置重置

# 重置为默认配置
codex config reset

# 重置特定配置项
codex config reset model

# 备份当前配置
codex config backup

# 从备份恢复
codex config restore

8. 最佳实践

8.1 配置管理原则

  1. 最小权限原则：只授予必要的权限
  2. 环境隔离：为不同环境使用不同配置
  3. 版本控制：将项目配置纳入版本控制
  4. 定期审查：定期审查和更新配置

8.2 安全配置建议

# 生产环境安全配置
sandbox = "read-only"
approval_policy = "untrusted"

# 限制工具权限
[tools.terminal]
deny_commands = ["rm -rf", "sudo", "chmod", "chown"]

# 敏感信息使用环境变量
[env]
API_KEY = "${OPENAI_API_KEY}"  # 从环境变量读取

8.3 团队协作配置

# .codex/config.toml（提交到版本控制）
model = "gpt-4"
sandbox = "workspace-write"
approval_policy = "on-request"

# 团队共享的 MCP 服务器
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

# 个人配置使用 Profile
codex --profile personal

8.4 性能优化配置

# 性能优化配置
model = "codex-mini-latest"  # 使用更快的模型

[tui]
auto_scroll = false          # 禁用自动滚动
syntax_highlighting = false  # 禁用语法高亮（可选）

# 限制 MCP 服务器数量
[mcp_servers]
# 只启用必要的 MCP 服务器

9. 高级配置技巧

9.1 条件配置

# 根据环境变量动态配置
[model_providers]
[model_providers.openai]
base_url = "${OPENAI_BASE_URL:-https://api.openai.com/v1}"
api_key_env = "OPENAI_API_KEY"

9.2 配置继承

# 基础配置
[base]
model = "gpt-4"
sandbox = "workspace-write"

# 继承并覆盖
[work : base]
approval_policy = "on-request"

[production : base]
sandbox = "read-only"
approval_policy = "untrusted"

9.3 配置模板

# 使用模板变量
[template]
project_name = "my-project"
environment = "development"

# 应用模板
[env]
PROJECT_NAME = "${template.project_name}"
NODE_ENV = "${template.environment}"

10. 总结

10.1 关键要点

  1. 配置文件位置：~/.codex/config.toml
  2. 六层优先级：默认值 → 托管配置 → 全局用户配置 → Profile 配置 → 项目级配置 → 命令行覆盖
  3. 关键配置项：model、sandbox、approval_policy、tui、mcp_servers
  4. Profile 管理：为不同场景创建独立配置集
  5. 调试命令：/debug-config 查看当前配置

10.2 配置检查清单

  • 配置文件语法正确
  • 安全设置符合要求
  • MCP 服务器连接正常
  • 环境变量配置正确
  • Profile 配置完整
  • 项目配置已版本控制

10.3 下一步学习

  • 第 104 课：安全模型与权限管理
  • 第 105 课：MCP 服务器高级配置
  • 第 106 课：自定义工具开发
  • 第 107 课：性能调优与监控

附录

A. 配置项完整参考

配置项类型默认值说明
modelstringcodex-mini-latestAI 模型名称
model_providerstringopenai模型提供商
sandboxstringworkspace-write沙箱模式
approval_policystringon-request审批策略
tui.themestringdark界面主题
tui.vim_mode_defaultbooleanfalseVim 模式默认状态
tui.auto_scrollbooleantrue自动滚动

B. 常用命令速查

# 配置管理
codex config show              # 显示当前配置
codex config validate          # 验证配置
codex config reset             # 重置配置

# Profile 管理
codex profile list             # 列出 Profile
codex profile show <name>      # 查看 Profile
codex --profile <name>         # 使用 Profile

# MCP 服务器
codex mcp list                 # 列出 MCP 服务器
codex mcp test <name>          # 测试连接
codex mcp restart <name>       # 重启服务器

# 调试命令
/debug-config                  # 查看配置详情
/debug-mcp                     # 查看 MCP 状态
/debug-tools                   # 查看工具状态

C. 配置文件模板

# Codex 配置文件模板
# 复制到 ~/.codex/config.toml 并根据需要修改

# 模型配置
model = "codex-mini-latest"
model_provider = "openai"

# 安全配置
sandbox = "workspace-write"
approval_policy = "on-request"

# 界面配置
[tui]
theme = "dark"
vim_mode_default = false
auto_scroll = true
show_line_numbers = true
syntax_highlighting = true

# MCP 服务器
[mcp_servers]
# [mcp_servers.github]
# command = "npx"
# args = ["-y", "@modelcontextprotocol/server-github"]

# 环境变量
[env]
NODE_ENV = "development"
# OPENAI_API_KEY = "your-api-key"

💡 提示：配置系统是 Codex CLI 的核心，合理的配置可以显著提升开发效率和安全性。建议从默认配置开始，逐步根据实际需求进行调整。

⚠️ 注意：修改配置后，建议使用 /debug-config 命令验证配置是否生效。