OpenAI Codex 配置参考大全：config.toml 与 requirements.toml 全配置详解-平芜编程栈

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"

启动前：

exportDEEPSEEK_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

默认：

最大嵌套深度

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