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

​

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

​

​

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

​

​

​

​

​

codex客户端下载：​

https://codexdown.cn/​

一、Codex 配置文件在哪里？​

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

​

代码块​

Plain Text

~/.codex/config.toml​

​

项目级配置：​

​

代码块​

Plain Text

项目目录/.codex/config.toml​

​

技能配置：​

​

代码块​

Plain Text

SKILL.md​

​

Agent 配置：​

​

代码块​

Plain Text

AGENTS.md​

​

插件配置：​

​

代码块​

Plain Text

hooks.json​

​

配置加载优先级：​

​

代码块​

Plain Text

系统配置​

↓​

用户配置​

↓​

Profile配置​

↓​

项目配置​

↓​

Session配置​

​

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

​

​

二、模型配置​

最常用的一组配置。​

指定模型​

​

代码块​

Plain Text

model = "gpt-5.5"​

​

例如：​

​

代码块​

Plain Text

model = "gpt-5.5"​

​

推理强度​

​

代码块​

Plain Text

model_reasoning_effort = "minimal"​

​

可选值：​

​

​

例如：​

​

代码块​

Plain Text

model_reasoning_effort = "xhigh"​

​

适合复杂代码分析。​

​

​

输出详细程度​

​

代码块​

Plain Text

model_verbosity = "high"​

​

支持：​

​

代码块​

Plain Text

low​

medium​

high​

​

​

​

推理摘要​

​

代码块​

Plain Text

model_reasoning_summary = "detailed"​

​

支持：​

​

代码块​

Plain Text

​

​

​

三、自定义模型供应商​

Codex 不仅支持 OpenAI。​

还支持：​

​

🔖

•

DeepSeek​

•

SiliconFlow​

•

OpenRouter​

•

Ollama​

•

LM Studio​

​

配置示例​

​

代码块​

Plain Text

model_provider = "deepseek"​

​

[model_providers.deepseek]​

name = "DeepSeek"​

base_url = "https://api.deepseek.com"​

env_key = "DEEPSEEK_API_KEY"​

​

启动前：​

​

代码块​

Plain Text

export DEEPSEEK_API_KEY=sk-xxxx​

​

​

​

自定义 Bearer Token​

​

代码块​

Plain Text

[model_providers.custom.auth]​

command = "get-token.sh"​

refresh_interval_ms = 300000​

​

Codex 会自动刷新 Token。​

​

​

四、多智能体配置​

Codex 已经内置 Agent 系统。​

​

最大线程数​

[agents]​

​

max_threads = 10​

一键获取完整项目代码​

toml​

1​

2​

3​

默认：​

​

6​

一键获取完整项目代码​

text​

1​

最大嵌套深度​

[agents]​

max_depth = 3​

一键获取完整项目代码​

toml​

1​

2​

含义：​

​

主Agent​

└ 子Agent​

└ 子Agent​

└ 子Agent​

一键获取完整项目代码​

text​

1​

2​

3​

4​

Worker超时​

[agents]​

job_max_runtime_seconds = 3600​

一键获取完整项目代码​

toml​

1​

2​

默认：​

​

1800秒​

一键获取完整项目代码​

text​

1​

Agent角色​

[agents.reviewer]​

config_file = "reviewer.toml"​

description = "代码审查专家"​

一键获取完整项目代码​

toml​

1​

2​

3​

五、记忆系统配置​

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

​

开启：​

​

[features]​

memories = true​

一键获取完整项目代码​

toml​

1​

2​

是否生成记忆​

[memories]​

generate_memories = true​

一键获取完整项目代码​

toml​

1​

2​

是否使用记忆​

[memories]​

use_memories = true​

一键获取完整项目代码​

toml​

1​

2​

记忆过期时间​

[memories]​

max_unused_days = 60​

一键获取完整项目代码​

toml​

1​

2​

最大保留数量​

[memories]​

max_raw_memories_for_consolidation = 512​

一键获取完整项目代码​

toml​

1​

2​

六、审批策略（Approval）​

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

​

从不审批​

approval_policy = "never"​

一键获取完整项目代码​

toml​

1​

适用于：​

​

自动化脚本​

CI/CD​

请求审批​

approval_policy = "on-request"​

一键获取完整项目代码​

toml​

1​

执行危险操作前弹窗。​

​

细粒度审批​

approval_policy = { granular = {​

sandbox_approval = true,​

rules = true,​

mcp_elicitations = true,​

request_permissions = true,​

skill_approval = true​

}}​

一键获取完整项目代码​

toml​

1​

2​

3​

4​

5​

6​

7​

自动审核​

approvals_reviewer = "auto_review"​

一键获取完整项目代码​

toml​

1​

无需人工确认。​

​

七、Sandbox 沙箱配置​

控制文件系统权限。​

​

只读模式​

sandbox_mode = "read-only"​

一键获取完整项目代码​

toml​

1​

工作区可写​

sandbox_mode = "workspace-write"​

一键获取完整项目代码​

toml​

1​

完全权限​

sandbox_mode = "danger-full-access"​

一键获取完整项目代码​

toml​

1​

工作区联网​

sandbox_workspace_write.network_access = true​

一键获取完整项目代码​

toml​

1​

八、权限系统（Permissions）​

企业级配置核心。​

​

自定义权限​

default_permissions = "dev"​

一键获取完整项目代码​

toml​

1​

[permissions.dev]​

一键获取完整项目代码​

toml​

1​

文件访问​

[permissions.dev.filesystem]​

​

":workspace_roots" = "write"​

​

"/data" = "read"​

一键获取完整项目代码​

toml​

1​

2​

3​

4​

5​

禁止读取密钥​

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

​

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

一键获取完整项目代码​

toml​

1​

2​

3​

网络权限​

[permissions.dev.network]​

​

enabled = true​

mode = "limited"​

一键获取完整项目代码​

toml​

1​

2​

3​

4​

域名白名单​

[permissions.dev.network.domains]​

​

"api.github.com" = "allow"​

"*.openai.com" = "allow"​

一键获取完整项目代码​

toml​

1​

2​

3​

4​

九、MCP 服务配置​

MCP 是 Codex 的核心扩展能力。​

​

Stdio模式​

[mcp_servers.github]​

​

command = "npx"​

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

一键获取完整项目代码​

toml​

1​

2​

3​

4​

HTTP模式​

[mcp_servers.docs]​

​

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

一键获取完整项目代码​

toml​

1​

2​

3​

超时​

startup_timeout_sec = 30​

tool_timeout_sec = 120​

一键获取完整项目代码​

toml​

1​

2​

指定工具​

enabled_tools = [​

"search_repo",​

"create_issue"​

]​

一键获取完整项目代码​

toml​

1​

2​

3​

4​

禁用工具​

disabled_tools = [​

"delete_repo"​

]​

一键获取完整项目代码​

toml​

1​

2​

3​

十、Web Search 配置​

新版 Codex 已支持 Web Search。​

​

关闭搜索​

web_search = "disabled"​

一键获取完整项目代码​

toml​

1​

索引搜索​

web_search = "cached"​

一键获取完整项目代码​

toml​

1​

速度快。​

​

实时搜索​

web_search = "live"​

一键获取完整项目代码​

toml​

1​

获取最新网页数据。​

​

高级配置​

[tools.web_search]​

​

context_size = "high"​

​

allowed_domains = [​

"github.com",​

"openai.com"​

]​

一键获取完整项目代码​

toml​

1​

2​

3​

4​

5​

6​

7​

8​

十一、Hooks 生命周期钩子​

类似 Git Hook。​

​

启用​

[features]​

​

hooks = true​

一键获取完整项目代码​

toml​

1​

2​

3​

PreToolUse​

[[hooks.PreToolUse]]​

​

matcher = "*"​

一键获取完整项目代码​

toml​

1​

2​

3​

[[hooks.PreToolUse.hooks]]​

​

command = "check.sh"​

一键获取完整项目代码​

toml​

1​

2​

3​

PostToolUse​

[[hooks.PostToolUse.hooks]]​

​

command = "audit.sh"​

一键获取完整项目代码​

toml​

1​

2​

3​

适用场景：​

​

安全审计​

日志记录​

自动通知​

代码扫描​

十二、Git 自动提交​

开启：​

​

[features]​

​

codex_git_commit = true​

一键获取完整项目代码​

toml​

1​

2​

3​

配置作者：​

​

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

一键获取完整项目代码​

toml​

1​

提交记录：​

​

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

一键获取完整项目代码​

text​

1​

十三、网络代理配置​

实验功能。​

​

开启：​

​

[features.network_proxy]​

​

enabled = true​

一键获取完整项目代码​

toml​

1​

2​

3​

允许域名：​

​

[features.network_proxy.domains]​

​

"github.com" = "allow"​

"*.openai.com" = "allow"​

一键获取完整项目代码​

toml​

1​

2​

3​

4​

HTTP代理：​

​

proxy_url = "http://127.0.0.1:3128"​

一键获取完整项目代码​

toml​

1​

SOCKS5：​

​

socks_url = "http://127.0.0.1:8081"​

一键获取完整项目代码​

toml​

1​

十四、Shell 环境控制​

限制环境变量泄露。​

​

仅保留指定变量：​

​

[shell_environment_policy]​

​

include_only = [​

"PATH",​

"HOME"​

]​

一键获取完整项目代码​

toml​

1​

2​

3​

4​

5​

6​

注入变量：​

​

[shell_environment_policy.set]​

​

NODE_ENV = "production"​

一键获取完整项目代码​

toml​

1​

2​

3​

十五、TUI 配置​

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

​

启用 Vim 模式​

​

[tui]​

​

vim_mode_default = true​

一键获取完整项目代码​

toml​

1​

2​

3​

关闭动画​

​

animations = false​

一键获取完整项目代码​

toml​

1​

启用通知​

​

notifications = true​

一键获取完整项目代码​

toml​

1​

使用 Cursor 打开文件​

​

file_opener = "cursor"​

一键获取完整项目代码​

toml​

1​

支持：​

​

vscode​

vscode-insiders​

cursor​

windsurf​

none​

一键获取完整项目代码​

text​

1​

2​

3​

4​

5​

十六、推荐开发配置​

适合个人开发者。​

​

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​

一键获取完整项目代码​

toml​

​

1​

2​

3​

4​

5​

6​

7​

8​

9​

10​

11​

12​

13​

14​

15​

16​

17​

18​

19​

20​

21​

22​

十七、推荐企业配置​

适合团队统一管理。​

​

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

一键获取完整项目代码​

toml​

​

1​

2​

3​

4​

5​

6​

7​

8​

9​

10​

11​

12​

13​

14​

15​

16​

17​

18​

总结​

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 开发平台，实现稳定、安全、可复用的智能协作工作流。​

​