# 配置参考 (Codex config.toml & requirements.toml)

> Source: https://developers.openai.ac.cn/codex/config-reference
> Fetched: 2026-06-07

Codex config.toml 和 requirements.toml 的完整参考

将此页面作为 Codex 配置文件可搜索的参考资料。如需概念性指导和示例，请从配置基础和高级配置开始。

## config.toml

用户级配置位于 `~/.codex/config.toml`。你也可以在 `.codex/config.toml` 文件中添加项目级覆盖。Codex 仅在受信任的项目中加载项目级配置文件。

项目级配置不能覆盖机器本地的提供商、身份验证、通知、配置文件或遥测路由键。当 `openai_base_url`、`chatgpt_base_url`、`model_provider`、`model_providers`、`notify`、`profile`、`profiles`、`experimental_realtime_ws_base_url` 和 `otel` 出现在项目本地的 `.codex/config.toml` 中时，Codex 会忽略它们；请改将这些配置放入用户级配置文件中。

关于沙箱和批准键（`approval_policy`、`sandbox_mode` 和 `sandbox_workspace_write.*`），请将此参考资料与沙箱和批准、可写根路径中的受保护路径以及网络访问一并阅读。关于 Beta 版权限配置，请参阅权限。

| 键 (Key) | 类型 / 值 | 详情 |
|---|---|---|
| `agents.<name>.config_file` | 字符串 (路径) | 该角色 TOML 配置层的路径；相对路径从声明该角色的配置文件开始解析。 |
| `agents.<name>.description` | string | 当 Codex 选择和生成该代理类型时，向其展示的角色引导信息。 |
| `agents.<name>.nickname_candidates` | 字符串数组 (array<string>) | 可选的显示昵称池，用于该角色下生成的代理。 |
| `agents.job_max_runtime_seconds` | number | `spawn_agents_on_csv` 任务的默认每个工作进程超时设置。若未设置，工具默认回退至每个进程 1800 秒。 |
| `agents.max_depth` | number | 允许生成的代理线程的最大嵌套深度（根会话从深度 0 开始；默认值：1）。 |
| `agents.max_threads` | number | 可同时打开的代理线程最大数量。若未设置，默认为 `6`。 |
| `allow_login_shell` | boolean | 允许基于 shell 的工具使用 login-shell 语义。默认为 `true`；当设置为 `false` 时，`login = true` 的请求将被拒绝，且未指定的 `login` 将默认使用非登录 shell。 |
| `analytics.enabled` | boolean | 启用或禁用此机器/配置文件的分析功能。若未设置，则应用客户端默认值。 |
| `approval_policy` | untrusted / on-request / never / { granular = {...} } | 控制 Codex 在执行命令前何时暂停以寻求批准。 |
| `approval_policy.granular.mcp_elicitations` | boolean | 当为 `true` 时，允许 MCP 启发式提示显示，而不是自动拒绝。 |
| `approval_policy.granular.request_permissions` | boolean | 当为 `true` 时，允许显示来自 `request_permissions` 工具的提示。 |
| `approval_policy.granular.rules` | boolean | 当为 `true` 时，允许显示由 execpolicy `prompt` 规则触发的批准请求。 |
| `approval_policy.granular.sandbox_approval` | boolean | 当为 `true` 时，允许显示沙箱提升批准提示。 |
| `approval_policy.granular.skill_approval` | boolean | 当为 `true` 时，允许显示技能脚本批准提示。 |
| `approvals_reviewer` | user / auto_review | 谁来审核 `on-request` 或细粒度批准策略下符合条件的批准提示。|
| `apps._default.destructive_enabled` | boolean | 对于带有 `destructive_hint = true` 的应用工具，默认的允许/拒绝设置。 |
| `apps._default.enabled` | boolean | 所有应用的默认启用状态。 |
| `apps._default.open_world_enabled` | boolean | 对于带有 `open_world_hint = true` 的应用工具，默认的允许/拒绝设置。 |
| `apps.<id>.default_tools_approval_mode` | auto / prompt / approve | 此应用内工具的默认批准行为。 |
| `features.memories` | boolean | 启用记忆 (Memories)（默认关闭）。 |
| `features.multi_agent` | boolean | 启用多代理协作工具（稳定；默认开启）。 |
| `features.network_proxy` | boolean / table | 启用沙箱网络。 |
| `features.web_search` | boolean | 已弃用的旧切换开关；首选顶级 `web_search` 设置。 |
| `hide_agent_reasoning` | boolean | 在 TUI 和 `codex exec` 输出中抑制推理事件。 |
| `log_dir` | 字符串 (路径) | Codex 写入日志文件的目录。 |
| `mcp_servers.<id>.command` | string | 用于 MCP stdio 服务器的启动命令。 |
| `mcp_servers.<id>.url` | string | MCP 可流式 HTTP 服务器的端点。 |
| `model` | string | 默认模型 ID。例如 `model = "gpt-5.5"` |
| `model_reasoning_effort` | string | 推理力度：`"low"` / `"medium"` / `"high"` |
| `personality` | string | 沟通风格：`"friendly"` / `"pragmatic"` / `"none"` |
| `sandbox_mode` | string | 沙盒级别：`"read-only"` / `"workspace-read"` / `"workspace-write"` / `"danger-full-access"` |
| `web_search` | cached / live / disabled | 网页搜索模式。 |
| `[permissions.<name>]` | table | 自定义权限配置文件。 |
| `[tui.keymap]` | table | TUI 快捷键映射。 |