OpenAI Codex 配置参考大全：config.toml 与 requirements.toml 全配置详解

在使用 OpenAI Codex 的过程中，很多开发者都会遇到一个问题：配置项太多，不知道每个参数的作用是什么。

本文将带你全面了解 Codex 的 config.toml 和 requirements.toml 配置体系，包括模型配置、权限控制、MCP 服务接入、多智能体协作、Web Search、Sandbox、安全策略等核心内容，帮助你快速搭建一套稳定、可复用的 Codex 开发环境。

---

codex客户端下载：

https://codexdown.cn/

一、Codex 配置文件在哪里？

Codex 主要使用以下配置文件：

~/.codex/config.toml

项目级配置：

项目目录/.codex/config.toml

技能配置：

SKILL.md

Agent 配置：

AGENTS.md

插件配置：

hooks.json

配置加载优先级：

系统配置
↓
用户配置
↓
Profile配置
↓
项目配置
↓
Session配置

后加载的配置会覆盖前面的配置。

---

二、模型配置

最常用的一组配置。

指定模型

model = "gpt-5.5"

例如：

model = "gpt-5.5"
model_reasoning_effort = "high"
model_verbosity = "high"

---

推理强度

model_reasoning_effort = "minimal"

可选值：

值	说明
minimal	最低推理
low	低
medium	中
high	高
xhigh	最高

例如：

model_reasoning_effort = "xhigh"

适合复杂代码分析。

---

输出详细程度

model_verbosity = "high"

支持：

low
medium
high

---

推理摘要

model_reasoning_summary = "detailed"

支持：

auto
concise
detailed
none

---

三、自定义模型供应商

Codex 不仅支持 OpenAI。

还支持：

• DeepSeek
• SiliconFlow
• OpenRouter
• Ollama
• LM Studio
• Azure OpenAI

---

配置示例

model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

启动前：

export DEEPSEEK_API_KEY=sk-xxxx

---

自定义 Bearer Token

[model_providers.custom.auth]
command = "get-token.sh"
refresh_interval_ms = 300000

Codex 会自动刷新 Token。

---

四、多智能体配置

Codex 已经内置 Agent 系统。

---

最大线程数

[agents]

max_threads = 10

默认：

6

---

最大嵌套深度

[agents]
max_depth = 3

含义：

主Agent
 └ 子Agent
    └ 子Agent
       └ 子Agent

---

Worker超时

[agents]
job_max_runtime_seconds = 3600

默认：

1800秒

---

Agent角色

[agents.reviewer]
config_file = "reviewer.toml"
description = "代码审查专家"

---

五、记忆系统配置

记忆功能是 Codex 近期最重要的功能之一。

开启：

[features]
memories = true

---

是否生成记忆

[memories]
generate_memories = true

---

是否使用记忆

[memories]
use_memories = true

---

记忆过期时间

[memories]
max_unused_days = 60

---

最大保留数量

[memories]
max_raw_memories_for_consolidation = 512

---

六、审批策略（Approval）

这是企业环境最常用配置。

---

从不审批

approval_policy = "never"

适用于：

• 自动化脚本
• CI/CD

---

请求审批

approval_policy = "on-request"

执行危险操作前弹窗。

---

细粒度审批

approval_policy = { granular = {
    sandbox_approval = true,
    rules = true,
    mcp_elicitations = true,
    request_permissions = true,
    skill_approval = true
}}

---

自动审核

approvals_reviewer = "auto_review"

无需人工确认。

---

七、Sandbox 沙箱配置

控制文件系统权限。

---

只读模式

sandbox_mode = "read-only"

---

工作区可写

sandbox_mode = "workspace-write"

---

完全权限

sandbox_mode = "danger-full-access"

---

工作区联网

sandbox_workspace_write.network_access = true

---

八、权限系统（Permissions）

企业级配置核心。

---

自定义权限

default_permissions = "dev"

[permissions.dev]

---

文件访问

[permissions.dev.filesystem]

":workspace_roots" = "write"

"/data" = "read"

---

禁止读取密钥

[permissions.dev.filesystem.":workspace_roots"]

"**/*.env" = "deny"

---

网络权限

[permissions.dev.network]

enabled = true
mode = "limited"

---

域名白名单

[permissions.dev.network.domains]

"api.github.com" = "allow"
"*.openai.com" = "allow"

---

九、MCP 服务配置

MCP 是 Codex 的核心扩展能力。

---

Stdio模式

[mcp_servers.github]

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

---

HTTP模式

[mcp_servers.docs]

url = "https://mcp.example.com"

---

超时

startup_timeout_sec = 30
tool_timeout_sec = 120

---

指定工具

enabled_tools = [
    "search_repo",
    "create_issue"
]

---

禁用工具

disabled_tools = [
    "delete_repo"
]

---

十、Web Search 配置

新版 Codex 已支持 Web Search。

---

关闭搜索

web_search = "disabled"

---

索引搜索

web_search = "cached"

速度快。

---

实时搜索

web_search = "live"

获取最新网页数据。

---

高级配置

[tools.web_search]

context_size = "high"

allowed_domains = [
    "github.com",
    "openai.com"
]

---

十一、Hooks 生命周期钩子

类似 Git Hook。

---

启用

[features]

hooks = true

---

PreToolUse

[[hooks.PreToolUse]]

matcher = "*"

[[hooks.PreToolUse.hooks]]

command = "check.sh"

---

PostToolUse

[[hooks.PostToolUse.hooks]]

command = "audit.sh"

---

适用场景：

• 安全审计
• 日志记录
• 自动通知
• 代码扫描

---

十二、Git 自动提交

开启：

[features]

codex_git_commit = true

配置作者：

commit_attribution = "Codex <noreply@openai.com>"

提交记录：

Co-authored-by: Codex <noreply@openai.com>

---

十三、网络代理配置

实验功能。

---

开启：

[features.network_proxy]

enabled = true

---

允许域名：

[features.network_proxy.domains]

"github.com" = "allow"
"*.openai.com" = "allow"

---

HTTP代理：

proxy_url = "http://127.0.0.1:3128"

---

SOCKS5：

socks_url = "http://127.0.0.1:8081"

---

十四、Shell 环境控制

限制环境变量泄露。

---

仅保留指定变量：

[shell_environment_policy]

include_only = [
    "PATH",
    "HOME"
]

---

注入变量：

[shell_environment_policy.set]

NODE_ENV = "production"

---

十五、TUI 配置

终端用户最常修改的配置。

---

启用 Vim 模式

[tui]

vim_mode_default = true

---

关闭动画

animations = false

---

启用通知

notifications = true

---

使用 Cursor 打开文件

file_opener = "cursor"

支持：

vscode
vscode-insiders
cursor
windsurf
none

---

十六、推荐开发配置

适合个人开发者。

model = "gpt-5.5"

approval_policy = "on-request"

sandbox_mode = "workspace-write"

web_search = "cached"

[features]

multi_agent = true
memories = true
hooks = true
shell_tool = true

[tui]

vim_mode_default = true

[file_opener]

cursor

---

十七、推荐企业配置

适合团队统一管理。

approval_policy = "on-request"

sandbox_mode = "read-only"

default_permissions = "corp"

[permissions.corp.filesystem]

":workspace_roots" = "read"

[permissions.corp.network]

enabled = true

[permissions.corp.network.domains]

"*.github.com" = "allow"
"*.openai.com" = "allow"

---

总结

Codex 的配置体系已经非常完善，几乎覆盖了 AI 编程助手在企业和个人开发中的全部场景：

• 模型管理
• MCP扩展
• 多智能体协作
• Web Search
• Memory记忆系统
• Hooks自动化
• Sandbox安全隔离
• 权限控制
• 网络代理
• Git自动提交
• TUI终端体验

对于个人开发者，重点关注：

• model
• approval_policy
• sandbox_mode
• web_search
• memories
• mcp_servers

对于企业团队，重点关注：

• permissions
• approval_policy
• hooks
• network_proxy
• projects.trust_level
• sandbox_mode

掌握这些核心配置后，基本可以把 Codex 打造成符合团队规范的 AI 开发平台，实现稳定、安全、可复用的智能协作工作流。

---