把本页当成 Codex 配置文件的可检索参考手册来使用。若你想先看概念解释和典型示例，请从 配置基础 和 高级配置 开始。
config.toml
用户级配置位于 ~/.codex/config.toml。你也可以在 .codex/config.toml 中添加项目级覆盖配置。Codex 只会在你信任该项目时加载项目级 .codex/ 配置层。
项目级配置不能覆盖机器本地的 provider、认证、host-owned app request metadata、通知、配置档案选择或 telemetry 路由键。Codex 会忽略项目本地 .codex/config.toml 中的 openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url 和 otel；provider、通知和 telemetry 键应放在用户级配置中。配置档案文件与 config.toml 放在同一目录，格式为 $CODEX_HOME/profile-name.config.toml，并通过 --profile profile-name 选择。
对于和沙箱、审批有关的配置键，例如 approval_policy、sandbox_mode 和 sandbox_workspace_write.*，建议把本页与 沙箱与审批、可写根目录中的受保护路径 以及 网络访问 搭配阅读。关于 beta 权限配置档案，请参见权限。
| 键 | 类型 / 可选值 | 说明 |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- | --- | ---------------- | ------ | ---------------------------------------- | --- | --------------------------- | ------- | ------------------------------------------------------------------------------- | --- | -------------------------- | ---- | ------- | ---- | ----------------------------------------------------------------------- | --- | ------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -------------- | ------ | ---------------------------- | --- | ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ---------------------- | ------ | -------------------------------------- | --- | ------------------- | ------- | -------------------------------- | --- | -------------------------------- | ------------- | ------------------------------------------ | --- | ---------------------------------- | ------- | --------------------------------------------------------------------------------------------- | --- | ------------- | ------- | ------------------------------------------ | --- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | --- | -------------- | ------- | ---------------------------------------------------------------------------------------------- | --- | ----- | ----- | ---------------------------------------------------------------------------------------------------------- | --- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -------------- | -------------------------------------------------------------------------------------------------------- | --- | ------------------------------- | ------ | -------------------------------------------------------------------------- | --- | ----------------------------------- | ------- | ------------------------------------------------------ | --- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------- | --- | ----------------- | ------- | ----------------------- | --- | -------------------- | ------- | --------------------------------------------------------------------------------------------------------------- | --- | -------------------- | ------- | ----------------------------------------------- | --- | ---------------------- | ------- | ----- | ---------------------------------------------------------------------------------- | --- | ------------------------------ | ------- | ---------------------------- | --- | ------------------------------ | ----------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ----------------------------------- | ----------------- | ----- | ---------------------------------------------------------------------------- | --- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------ | --- | ------------------------------------ | ------- | ----------------------------- | --- | ---------------------------------------- | ------- | ------------------------------------- | --- | ------------------------------------------- | ------- | ------------------------------------------------- | --- | ----------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- | --- | --------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ | --- | -------------------------------- | ------ | ------------------------------------------------------------------------------------------------- | --- | -------------------------------- | ------ | -------------------------------------------------------------------------------------- | --- | --------------------------- | ------- | ---------------------------------------------------------- | --- | ----------------------- | ------- | ----------------------------------------------------- | --- | ------------------- | ------- | --------------------------------------------------- | --- | ------------------------------------- | ------- | --------------------------------------------------------------- | --- | ------------- | ------- | ------------------------------------ | --- | --------------------- | ------- | ---------------------------------------------------------------- | --- | ------------------- | ------- | ------------------------------------------------ | --- | -------------------------- | ------- | ----------------------------------------------------------------------------- | --- | --------------------------- | ------- | --------------------------------------------------------------------------- | --- | ---------------- | ------- | ------------------------------------------------------------- | --- | ----------- | ------ | --------------- | -------- | ------ | ---- | ---------------------------------------------------------------- | --- | --------------------------- | ------------- | ---------------------------------------------------- | --- | ------------------- | ------- | --- | ------------------------------- | --- | -------------------- | ------- | ------------------------------------------------ | --- | ----------------- | ------ | ----------------------------------------------------------- | --- | ------------------- | -------- | ---- | --------------------------------------------------------------- | --- | ------------ | ------ | --------------------------------------------------------------------- | --- | ------- | ------------- | ---------------------------------------------------------------------- | --- | ----------------------- | ------- | ------------------------------------------------------------------------------------------ | --- | ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --- | --------------------------- | ---- | ---- | ------- | ------------------------------ | --- | ----------------- | ----- | -------------------------------------- | --- | --------------------------------- | ------ | ---------------------------------------------------- | --- | -------------------- | ------ | ----------------------------- | --- | ---------------- | ------ | --------------------------------- | --- | --------------------------- | ----- | ------------------------------------------------------ | --- | ---------------------------------------- | ---- | ------ | ------- | ------------------------------------------------------ | --- | -------------------- | ------- | ----------------------------------------- | --- | -------------------------- | ----- | ------------------------------ | --- | ---------------- | ------------------ | ------------------------------------ | --- | ----------------------------- | ------------------ | ------------------------------------------------------- | --- | --------------------- | ------------ | --------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------------------------- | ------------------ | --------------------------------------------- | --- | --------------------------- | ------ | ----------------------------------------------------- | --- | ------------------------------------- | ----- | ------ | ----------------------------------------------------------------------------------------------------------------------------- | --- | --------------------- | ------- | ------------------------------------------------------------------- | --- | ------------------- | ----- | ----------------------------------------------- | --- | ------------------------------- | ------ | -------------------------------- | --- | -------------------------------- | ------ | -------------------------------------- | --- | ----------------------------- | ------ | ---------------------------------------- | --- | ---------------- | ------ | ---------------------------------------- | --- | --------------------------------- | ---- | ------ | ------- | ------------------------------------------ | --- | ----- | ------ | ---------------------------- | --- | ------------------------------ | ------ | --------------------------------------------------------- | --- | ------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------- | --- | -------------------- | ------ | -------------------------------------------- | --- | ----------------------- | ------------- | -------------------------------------------------------- | --- | -------------- | ------ | -------------------------------------------------------- | --- | ------------------------- | ------ | ----------------------------------- | --- | --------------------------------- | ------------------ | --------------------------------------------------- | --- | ------------------------ | ------ | -------------------------------------- | --- | ------------------------------------- | ------ | -------------------------------------- | --- | ------------------------------------------ | ------ | ---------------------------------------------------------------------- | --- | ----------------------------- | ------------------ | ------------------------------------------- | --- | --------------------- | ------ | ---------------------------------- | --- | ----------------------------- | ------------------ | ----------------------------------------- | --- | ------------------------------------ | ------ | ---------------------------------------------------- | --- | ------------------------------------- | ------- | ------------------------------------------------ | --- | --------------------------------------- | ------ | -------------------------------------------- | --- | ----------------------------------- | ------ | ---------------------------------- | --- | ------------------------------------ | ------- | ----------------------------------------------------------- | --- | --------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------ | --- | ----------------------------- | ------ | ----------------------------------------------------------------------------- | --- | -------------------------- | ----- | ----------------------- | --- | -------------------------------- | ------ | --------------------------------------------- | --- | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------- | --- | ------------------------- | ------------- | --------------------------------- | --- | ------------------------------------------ | ------ | ------------------------------------------------------ | --- | ----------------------------------------- | ------ | ------------------------------------------------ | --- | ------------------------- | --------- | -------------------------------------------------------------------------- | --- | ---------------------- | ------- | --- | ------ | ---- | ----- | -------------------------------------------------------------------------- | --- | ----------------------- | ---- | ------- | -------- | ---- | ------------------------------------------------------- | --- | ---------------------------------- | ------- | -------------------------------------------- | --- | --------------- | --- | ------ | ---- | ------------------------------------------------------------------------------ | --- | ------------------------------- | ------- | ----------------------------------------- | --- | ---------------------------------------------- | ------- | ------------------------------------------- | --- | ----------------------------------- | ------- | --------------------------------- | --- | ---------------------------------- | ------- | ---------------------------------------------- | --- | ---------------------------------- | ------- | ------------------------------------------------ | --- | ----------------------- | ------------------ | ------------------------------------------ | --- | ------ | ----- | --------------------------------------------------- | --- | --------------- | ------ | ----------------------------------------------- | --- | ------------ | -------- | ------ | ---------------------------------------------------------------- | --- | ---------------- | ------ | ------------------------------------------------- | --- | ------------- | ---- | --------- | --------- | --------------------------------------------------------- | --- | ----------------------- | ------ | -------------------------------- | --- | ---------------------- | ------------------ | -------------------------------------- | --- | ----------------------- | ------ | ---- | ------------------------------- | --- | --------------------------------- | ------ | -------------------------------------- | --- | ------------------------------------- | ------ | ---------------------------------------- | --- | ------------------------------------- | ------ | ---------------------------------------- | --- | -------------------- | ------- | ----------------------------------------------------- | --- | --------------------- | ---- | ------- | --------- | --------- | ----------------------------------------------------- | --- | ------------------- | ---- | --------- | --------- | --------------------------------------------------------------- | --- | ----------------------------- | ------ | --------------------------------- | --- | ---------------------------- | ------------------ | -------------------------------------------- | --- | ----------------------------- | ------ | ---- | ------------------------------------- | --- | --------------------------------------- | ------ | -------------------------------------------- | --- | ------------------------------------------- | ------ | ---------------------------------------------- | --- | ------------------------------------------- | ------ | ---------------------------------------------- | --- | ------------------------ | ------ | --------------------------------------------------------------------------------- | --- | -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ---------------------------- | ----- | ------------------------------------------------------------------------------------------------------ | --- | ----------------------------- | ------- | -------------------------------------------------------------------------------- | --- | ----------------------- | ----- | ----------------------------------------------------------------------------------------------- | --- | ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------- | --- | ------------------------ | ------ | ------- | ------ | ----- | --------------------------------------------------------------------------------------------------------- | --- | ------------------------------------------- | ------ | ------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | --- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | --- | ----------------------------------------- | ------- | ------------------------------------------- | --- | ------------------------------------------------------- | ------- | --------------------------------------------------------------------------- | --- | --------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- | --- | ---------------------------------- | ------- | ---------------------------------------------------- | --- | -------------------------------------- | ------- | -------------------------------- | --- | ---------------------------- | ------- | ------------------------------------------------------------------------------------ | --- | ------------------------------ | ------ | -------------------------------------------------------- | --- | ------------------------------ | ------ | -------------------------------------- | --- | ------------------------- | ------- | ---- | ------------------------------ | --- | ---------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ----------------------------- | ----- | ---- | ---------------------------------------------------------------------------- | --- | --------------------------------- | ----- | ------------------------------------------------------------------------------------------------ | --- | ---------------------------------- | ----- | ---- | ----------------------------------------------------------------------------------------------------------------- | --- | ----------- | ---- | -------- | --------- | ---------------------------------------------------------------------------------------------------- | --- | -------------------------- | ---- | ------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------- | --- | ------------------------------ | ----- | --------------------------------------- | --- | --------------------- | ------ | ----------------------------------------------- | --- | -------------------- | ----- | ---------------------------------------------- | --- | --------------------- | ------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------ | --- | ------------ | ------ | ----------------------------------------------------------- | --- | ------------ | --------- | --------------- | ------------------ | ------------------------------------------ | --- | ----------------------------------------- | ------- | ----------------------------------------------------- | --- | ---------------------------------------------- | ------- | -------------------------------------------------------- | --- | -------------------------------------- | ------- | ------------------------------------------- | --- | -------------------------------------- | ----- | -------------------------------------------------------- | --- | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | --- | -------------------------------- | ----- | ---------------------------------------------------- | --- | ------------------------------------------------- | ------- | ------------------------------------- | --- | ------------------------------------------------ | ------- | ---------------------------------------------------------- | --- | ------------------------------------- | ----- | ---------------------------------------- | --- | -------------------------------- | --- | ---- | ---- | -------------------------------- | --- | ---------------------------- | ------------------ | -------------------------------------- | --- | ------------------------ | ------- | --------------------------------------------------- | --- | ------------- | ----- | ------------------------------------------- | --- | ---------------------- | ------- | -------------------- | --- | ------------------- | ------------- | ------------------------------------------------- | --- | ----------- | ------------- | -------------------------------------------------------------------------------- | --- | ---------------------------------- | ------- | -------------------------------------- | --- | ----------------------- | ------ | ------------------------------------------------------------ | --- | ---------------- | ------- | --------------------------------- | --- | ---------------- | ------- | --------------------- | ------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --- | ----------------------------- | ------- | ----------------------------------------------------------------------- | --- | ------------------------------------------------- | ---- | ------ | ------- | -------------------------------------------- | --- | ----------------------------------- | ----- | ---------------------------------------- | --- | ------------------------------------ | ----- | ----------------------------------------------------------------- | --- | ------------------------------------------ | ---- | ------ | ------- | ------------------------------------------- | --- | --- | ----- | ---------------------------------------- | --- | -------------------- | ---- | ------ | ----- | -------------------------------------------------------------------------------------------- | --- | -------------- | ------- | ------------------------------------------------------------------ | --- | -------------------- | ------- | ------------------------------------------------------------------------------------------------ | --- | ------------------- | ------- | -------------------------------------------------------------------------------------------------------------- | --- | --------------------------- | ------- | --------------------------------------- | --- | ----------------------- | ---- | ---- | --- | --------------------------------- | --- | -------------------------- | --------- | ------ | ------------------------------------------------------------------------- | --- | ----------------- | ------- | ----- | --------------------------------------- | --- | ----------------- | ------- | ------------------------------------------------------------------- | --- | --------------- | ----- | ---- | ------------------------------------------------- | --- | ------------------ | ----- | ---- | --------------------------------------------------------------------------------------- | --- | --------- | ------ | ----------------------------------------- | --- | ------------ | ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------- | --- | ---------- | -------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------------------------------ | ------- | -------------------------------------------------- | --- | --------------- | ---------- | -------- | ------------------------------------------------------------------------- | --- | ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | ------------- | ---- | --- | --- | --- | --- | --- | ------------------------- | ----- | ----------------------------------------------------------------------------- | --- | --------------------------- | ----- | ----------------------------------------------------------- | --- | ---------------------- | ------ | ---------------------------------------------------------------------------------------------- | --- | --------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --- | ------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ----------------- | ------ | ------------------------------------------------------ | --- | ----------- | ----- | ----------------------------------------------------------------------------------- | --- | ------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | --------------------- | ----- | --------------------------- | --- | ------- | ----- | ------------------------------- | --- | --------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------- | --- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ----------------------------------------- | ----- | ------------------------------------------------------------------------- | --- | --------------------------------------------- | ----- | ---------------------------------------------- | --- | ------------------------ | ----- | ----------------------------------------------------------------------------------------------------------- | --- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------- | --- | -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | --- | ----------------------- | ------- | -------------------------------------------------------------------------------- | --- | -------- | ----- | --------------------------------------------------------------- | --- | --------- | ------- | --------------------------------------------------- | --- | ------------- | ------- | ---------------------------------- | --- | ----------------------- | ------- | ----------------------------------------------------------- | --- | -------------------- | ------- | ------------------------------------------------------------------------------ | --- | ----------------------------- | ------- | ----------------------------------------------------------------------- | --- | ------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------------------ | ------- | ----------------------------------------------- | --- | -------------------------- | ------- | ------------------------------------------- | --- | ----------------- | ------- | ---------------------------------- | --- | -------------------- | ------- | ------------------------------------- | --- | ---------------- | ------- | ---------------------------- | --- | --------------------- | ------- | ---------------------------------------------------------------------------------- | --- | ------------------------------- | ------- | -------------------------------------------------------------- | --- | ------------ | ----- | ----------------------------------------------------------- | --- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- | --- | -------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------- | --- | ---------------------------- | ------- | ------------------------------------------------------------------------ | --- | ------------------------------ | ------- | ------------------------------------------------------------- | --- | ------------------------------- | ------- | --------------------------------------------------------------- | --- | ----------------------------------------- | ------- | ------------------------------------------- | --- | --------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------ | --- | ------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- | --- | ---------------------------- | ----------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------------------------------------ | ----- | ----------------------------------------------------------------------- | --- | ----------------------------------- | ----- | ---------------------------------------------------------------------- | --- | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | --------------------------------- | ----------------- | ----- | ----------------------------------------------- | --- | ---------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | --- | ----- | ----- | --------------------------------------------------------------------------------------------------------- | --- | ----------------- | ---------------------- | ------------------------------------------------------------------------------------------- | --- | ------------------------- | ---------------------- | ------------------------------------------------------------------------------------ | --- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -------------- | -------------------------------------------------------------------------------------------------------- | --- | ------------------------------- | ------ | -------------------------------------------------------------------------- | --- | ----------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | --------------------- | ----- | ---------------------------------------------------------------------------------- | --- | ----------------------------- | ------ | --------------------------------------------------------------- | --- | ------------------------- | ------ | --------------------------------------------------------------------- | --- | ------- | ----- | ---------------------------------------------- | --- | -------------------------------------- | ------ | ----------------------------------------------------------------- | --- | ---------------------------------- | ------ | ---------------------------------------------------------------------------- | --- | ---- | ----- | ------------------------------------------------------------------------------------------------- | --- | ------------- | ------- | ------------------------------------------------------------------------------- | --- | -------------------------- | ---- | ------ | ------- | --------------------------------- | --- | -------------------------------- | ----- | ------------------------------------------------------------------------------------------------- | --- | ----- | ----- | ---------------------------------------------------------------------------------- | --- | ------------------ | ---------------------------------------------------------------------------- | --- | ----------------------------- | ------ | --------- | --------------------------------------------------------------------- | --- | ---------------------------------- | ------ | ---------------------------------------------------- | --- | ---------------------------- | -------------------------------------------------------------------------------- | --- | ------------------------------------- | ----- | ---------------------------- | --- | ------------------------------------ | ------ | -------------------------------- | ----------------------------------------------------------------------------------- | --- | --- | --- | --- | --- | --- | --- | --- |
| agents..config_file | string (path) | 该角色使用的 TOML 配置层路径；相对路径相对于声明该角色的配置文件解析。 |
| agents..description | string | 当 Codex 选择并生成该智能体类型时展示给它的角色说明。 |
| agents..nickname_candidates | array | 可选的显示昵称候选池，用于该角色生成的智能体。 |
| agents.job_max_runtime_seconds | number | spawn_agents_on_csv 任务中每个 worker 的默认超时时间。未设置时回退到每个 worker 1800 秒。 |
| agents.max_depth | number | 允许的智能体线程最大嵌套深度（根会话深度为 0；默认 1）。 |
| agents.max_threads | number | 允许同时打开的智能体线程最大数量。未设置时默认 6。 |
| memories.generate_memories | boolean | 为 false 时，新创建的线程不会作为记忆生成输入保存。默认 true。 |
| memories.use_memories | boolean | 为 false 时，Codex 不会把现有记忆注入到后续会话中。默认 true。 |
| memories.disable_on_external_context | boolean | 为 true 时，使用 MCP 工具调用、Web 搜索或工具搜索等外部上下文的线程不会进入记忆生成。默认 false。旧别名：memories.no_memories_if_mcp_or_web_search。 |
| memories.max_raw_memories_for_consolidation | number | 全局记忆合并保留的近期原始记忆最大数量。默认 256，上限 4096。 |
| memories.max_unused_days | number | 记忆距离上次使用超过多少天后不再参与记忆合并。默认 30，范围限制为 0-365。 |
| memories.max_rollout_age_days | number | 参与记忆生成的线程最大年龄。默认 30，范围限制为 0-90。 |
| memories.max_rollouts_per_startup | number | 每次启动处理的 rollout 候选最大数量。默认 16，上限 128。 |
| memories.min_rollout_idle_hours | number | 线程进入记忆生成前需要空闲的最短时间。默认 6，范围限制为 1-48。 |
| memories.min_rate_limit_remaining_percent | number | Codex 速率限制窗口剩余百分比达到该阈值后，才会开始记忆生成。默认 25，范围限制为 0-100。 |
| memories.extract_model | string | 针对单线程记忆提取使用的可选模型覆盖。 |
| memories.consolidation_model | string | 针对全局记忆合并使用的可选模型覆盖。 |
| allow_login_shell | boolean | 是否允许基于 shell 的工具使用 login-shell 语义。默认 true；若设为 false，则 login = true 的请求会被拒绝，未显式设置 login 时默认使用非 login shell。 |
| analytics.enabled | boolean | 为当前机器 / 配置档案启用或关闭分析数据上报。未设置时使用客户端默认值。 |
| approval_policy | untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } } | 控制 Codex 在执行命令前何时暂停并请求审批。你也可以使用细粒度策略 approval_policy = { granular = {... } }，在保留其他交互提示的同时，让某些提示类别自动允许或自动拒绝。on-failure 已弃用；交互式场景请使用 on-request，非交互场景请使用 never。 |
| approval_policy.granular.mcp_elicitations | boolean | 为 true 时，允许 MCP elicitation 提示真正显示出来，而不是被自动拒绝。 |
| approval_policy.granular.request_permissions | boolean | 为 true 时，允许 request_permissions 工具触发的提示显示出来。 |
| approval_policy.granular.rules | boolean | 为 true 时，允许由 execpolicy 提示词规则触发的审批提示显示出来。 |
| approval_policy.granular.sandbox_approval | boolean | 为 true 时，允许沙箱升级时的审批提示显示出来。 |
| approval_policy.granular.skill_approval | boolean | 为 true 时，允许技能脚本触发的审批提示显示出来。 |
| approvals_reviewer | user | auto_review | 在 on-request 或细粒度审批策略下，指定由谁审核符合条件的审批提示。默认是 user；设为 auto_review 时，会由评审子智能体自动审核。这不会改变沙箱边界，也不会影响原本已在沙箱内允许执行的动作。 |
| auto_review.policy | string | 自动评审使用的本地 Markdown 策略指令。若管理员下发了 guardian_policy_config，则以托管配置为准；空值会被忽略。 |
| apps._default.destructive_enabled | boolean | 默认是否允许带 destructive_hint = true 的 app 工具。 |
| apps._default.enabled | boolean | 对所有 app 生效的默认启用状态，除非被单个 app 覆盖。 |
| apps._default.open_world_enabled | boolean | 默认是否允许带 open_world_hint = true 的 app 工具。 |
| apps..default_tools_approval_mode | auto | prompt | approve | 该 app 中工具的默认 approval 行为，除非单个工具另有覆盖。 |
| apps..default_tools_enabled | boolean | 该 app 中工具的默认启用状态，除非单个工具另有覆盖。 |
| apps..destructive_enabled | boolean | 是否允许该 app 中声明了 destructive_hint = true 的工具。 |
| apps..enabled | boolean | 启用或禁用某个具体 app / connector（默认 true）。 |
| apps..open_world_enabled | boolean | 是否允许该 app 中声明了 open_world_hint = true 的工具。 |
| apps..tools..approval_mode | auto | prompt | approve | 对单个 app 工具的 approval 行为覆盖。 |
| apps..tools..enabled | boolean | 对单个 app 工具的启用状态覆盖，例如 repos/list。 |
| tool_suggest.discoverables | array 允许对额外的可发现连接器或插件给出工具建议。每一项都应包含 type = "connector" 或 "plugin"，以及对应的 id。 | | tool_suggest.disabled_tools | array 禁用特定可发现连接器或插件的工具建议。每一项都应包含 type = "connector" 或 "plugin"，以及对应的 id。 | | background_terminal_max_timeout | number | 后台终端空 write_stdin 轮询的最大等待窗口（毫秒）。默认 300000（5 分钟）。替代旧键 background_terminal_timeout。 | | chatgpt_base_url | string | 覆盖 ChatGPT 登录流程所使用的 base URL。 | | check_for_update_on_startup | boolean | 启动时是否检查 Codex 更新（只有在更新由中心化方式统一管理时才建议设为 false）。 | | cli_auth_credentials_store | file | keyring | auto | 控制 CLI 把缓存凭据保存在何处（文件型 auth.json 或操作系统 keychain）。 | | commit_attribution | string | 在 [features].codex_git_commit 启用时使用的 commit co-author trailer。默认是 Codex [email protected]；设为 "" 可禁用。 | | compact_prompt | string | 对历史压缩提示词的内联覆盖。 | | default_permissions | string | 应用于沙箱化工具调用的默认权限配置档案名称。内建值为 :read-only、:workspace 和 :danger-full-access；自定义配置档案名称必须有对应的 [permissions.] 表。不要和 sandbox_mode 或 [sandbox_workspace_write] 混用。 | | developer_instructions | string | 注入到会话中的额外开发者指令（可选）。 | | disable_paste_burst | boolean | 关闭 TUI 中的 burst-paste 检测。 | | experimental_compact_prompt_file | string (path) | 从文件加载历史压缩提示词覆盖值（实验性）。 | | experimental_use_unified_exec_tool | boolean | 启用 unified exec 的旧键名；优先使用 [features].unified_exec 或 codex --enable unified_exec。 | | features.apps | boolean | 启用 ChatGPT Apps / 连接器支持（实验性）。 | | features.codex_git_commit | boolean | 启用由 Codex 生成 git commit。启用后，Codex 会使用 commit_attribution 在生成的 commit message 中追加 Co-authored-by: trailer。 | | features.hooks | boolean | 启用从 hooks.json 或内联 [hooks] 配置加载的生命周期钩子。features.codex_hooks 是已弃用 alias。 | | hooks | table | 在 config.toml 中内联配置的生命周期钩子。使用与 hooks.json 相同的事件 schema；示例和支持事件请参见 Hooks。 | | hooks. | array 某个钩子事件的 matcher 分组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。 | | hooks.[].hooks | array matcher 分组下的钩子处理器。当前支持 command hooks；prompt 和 agent hook handlers 会被解析但跳过。 | | hooks.[].hooks[].commandWindows | string | command hooks 的 Windows 专用命令覆盖。也接受 TOML alias command_windows。 | | features.enable_request_compression | boolean | 在支持时使用 zstd 压缩流式请求体（Stable；默认开启）。 | | features.fast_mode | boolean | 启用 TUI 中基于模型目录的 service tier 选择；当当前模型声明 Fast tier 时，也会启用对应命令（Stable；默认开启）。 | | features.memories | boolean | 启用 记忆（默认关闭）。 | | features.multi_agent | boolean | 启用多智能体协作工具，例如 spawn_agent、send_input、resume_agent、wait_agent、close_agent（Stable；默认开启）。 | | features.personality | boolean | 启用 personality 选择控件（Stable；默认开启）。 | | features.network_proxy | boolean | table | 启用沙箱化网络。设置 domains 等网络策略选项时使用 table 形式（实验性；默认关闭）。 | | features.network_proxy.enabled | boolean | 启用沙箱化网络。默认 false。 | | features.network_proxy.domains | map<string, allow | deny> | 沙箱化网络的域名策略。默认未设置，表示在添加 allow 规则前不允许外部目的地。支持精确主机、只匹配子域名的 *.example.com、同时匹配 apex 和子域名的 **.example.com，以及全局 * allow 规则；* 会宽泛打开公共出站访问，应优先使用更窄规则。添加 deny 规则可阻止目的地，冲突时 deny 优先。 | | features.network_proxy.unix_sockets | map<string, allow | deny> | 沙箱化网络的 Unix socket 策略。默认未设置；为允许的 socket 添加 allow 条目。 | | features.network_proxy.allow_local_binding | boolean | 允许更宽的本地 / 私有网络访问。默认 false；精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。 | | features.network_proxy.enable_socks5 | boolean | 暴露 SOCKS5 支持。默认 true。 | | features.network_proxy.enable_socks5_udp | boolean | 允许通过 SOCKS5 使用 UDP。默认 true。 | | features.network_proxy.allow_upstream_proxy | boolean | 允许通过环境中的 upstream proxy 级联。默认 true。 | | features.network_proxy.dangerously_allow_non_loopback_proxy | boolean | 允许非 loopback 监听器地址。默认 false；启用后可能把代理监听器暴露到 localhost 之外。 | | features.network_proxy.dangerously_allow_all_unix_sockets | boolean | 允许任意 Unix socket 目的地，而不是只允许 allowlist 条目。默认 false；只能在严格受控环境中使用。 | | features.network_proxy.proxy_url | string | 沙箱化网络的 HTTP 监听器 URL。默认 "http://127.0.0.1:3128"。 | | features.network_proxy.socks_url | string | SOCKS5 监听器 URL。默认 "http://127.0.0.1:8081"。 | | features.prevent_idle_sleep | boolean | 在 turn 正在运行时阻止机器休眠（Experimental；默认关闭）。 | | features.shell_snapshot | boolean | 快照 shell 环境，以加快重复命令（Stable；默认开启）。 | | features.shell_tool | boolean | 启用默认 shell 工具来运行命令（Stable；默认开启）。 | | features.skill_mcp_dependency_install | boolean | 允许针对技能缺失的 MCP 依赖进行提示并安装（Stable；默认开启）。 | | features.undo | boolean | 启用 undo 支持（Stable；默认关闭）。 | | features.unified_exec | boolean | 使用统一的 PTY 支撑 exec 工具（Stable；除 Windows 外默认开启）。 | | features.web_search | boolean | 已弃用的旧版开关；优先使用顶层 web_search 设置。 | | features.web_search_cached | boolean | 已弃用的旧版开关。若 web_search 未设置，true 会映射到 web_search = "cached"。 | | features.web_search_request | boolean | 已弃用的旧版开关。若 web_search 未设置，true 会映射到 web_search = "live"。 | | feedback.enabled | boolean | 在各个 Codex 界面中启用通过 /feedback 提交反馈（默认 true）。 | | file_opener | vscode | vscode-insiders | windsurf | cursor | none | Codex 输出中的 citation 打开时使用的 URI scheme（默认 vscode）。 | | forced_chatgpt_workspace_id | string (uuid) | 将 ChatGPT 登录限制在某个特定 workspace identifier。 | | forced_login_method | chatgpt | api | 将 Codex 限制为某一种认证方式。 | | hide_agent_reasoning | boolean | 在 TUI 与 codex exec 输出中压制 reasoning 事件。 | | history.max_bytes | number | 若设置，则通过丢弃最旧条目来限制 history 文件的最大字节数。 | | history.persistence | save-all | none | 控制 Codex 是否把 session transcript 持久保存到 history.jsonl。 | | instructions | string | 预留给未来使用；当前请优先使用 model_instructions_file 或 AGENTS.md。 | | log_dir | string (path) | Codex 写日志文件的目录，例如 codex-tui.log；默认值是 $CODEX_HOME/log。 | | mcp_oauth_callback_port | integer | MCP OAuth 登录时本地 HTTP callback server 使用的固定端口。未设置时由操作系统分配临时端口。 | | mcp_oauth_callback_url | string | MCP OAuth 登录的可选 redirect URI 覆盖值，例如 devbox ingress URL。mcp_oauth_callback_port 仍然控制回调监听端口。 | | mcp_oauth_credentials_store | auto | file | keyring | MCP OAuth 凭据的首选存储位置。 | | mcp_servers..args | array | 传给 MCP stdio server 启动命令的参数。 | | mcp_servers..bearer_token_env_var | string | 作为 MCP HTTP server bearer token 来源的环境变量名。 | | mcp_servers..command | string | MCP stdio server 的启动命令。 | | mcp_servers..cwd | string | MCP stdio server 进程的工作目录。 | | mcp_servers..disabled_tools | array | MCP server 的 deny list；会在 enabled_tools 之后应用。 | | mcp_servers..default_tools_approval_mode | auto | prompt | approve | 该 MCP server 中工具的默认审批行为，除非有单工具覆盖。 | | mcp_servers..enabled | boolean | 在不删除配置的前提下禁用一个 MCP server。 | | mcp_servers..enabled_tools | array | MCP 服务端暴露的工具允许列表。 | | mcp_servers..env | map<string,string> | 转发给 MCP stdio server 的环境变量。 | | mcp_servers..env_http_headers | map<string,string> | 对 MCP HTTP server，从环境变量填充出来的 HTTP headers。 | | mcp_servers..env_vars | array<string | { name = string, source = "local" | "remote" }> | 额外允许转发给 MCP stdio server 的环境变量。字符串条目默认使用 source = "local"；只有在 executor-backed remote stdio 场景下才使用 source = "remote"。 | | mcp_servers..http_headers | map<string,string> | 每次 MCP HTTP 请求都携带的静态 HTTP headers。 | | mcp_servers..oauth_resource | string | MCP 登录期间附带的可选 RFC 8707 OAuth resource 参数。 | | mcp_servers..experimental_environment | local | remote | MCP server 的实验性运行位置。remote 会通过远程 executor 环境启动 stdio server；streamable HTTP 的 remote placement 尚未实现。 | | mcp_servers..required | boolean | 为 true 时，若该已启用 MCP server 无法初始化，则启动 / 恢复会失败。 | | mcp_servers..scopes | array | 对该 MCP server 进行认证时请求的 OAuth scopes。 | | mcp_servers..startup_timeout_ms | number | startup_timeout_sec 的毫秒别名。 | | mcp_servers..startup_timeout_sec | number | 覆盖 MCP server 默认 10 秒的启动超时。 | | mcp_servers..tool_timeout_sec | number | 覆盖 MCP server 默认 60 秒的单工具超时。 | | mcp_servers..url | string | MCP streamable HTTP server 的 endpoint。 | | mcp_servers..tools..approval_mode | auto | prompt | approve | 对该 MCP server 中单个工具的审批行为覆盖。 | | model | string | 要使用的模型，例如 gpt-5.5。 | | model_auto_compact_token_limit | number | 触发自动历史压缩的 token 阈值（未设置时使用模型默认值）。 | | model_catalog_json | string (path) | 启动时加载的可选 JSON model catalog 路径。选中的 $CODEX_HOME/profile-name.config.toml 配置档案文件可以覆盖该值。 | | model_context_window | number | 当前激活模型可用的 context window token 数。 | | model_instructions_file | string (path) | 用于替代内建 instructions 的文件，而不是使用 AGENTS.md。 | | model_provider | string | 从 model_providers 中选择的 provider id（默认 openai）。 | | model_providers..base_url | string | 该 model provider 的 API base URL。 | | model_providers..env_http_headers | map<string,string> | 仅在环境变量存在时，从环境变量填充的 HTTP headers。 | | model_providers..env_key | string | 提供该 provider API key 的环境变量名。 | | model_providers..env_key_instructions | string | 关于 provider API key 的可选配置提示。 | | model_providers..experimental_bearer_token | string | 直接写在配置里的 provider bearer token（不推荐；应优先使用 env_key）。 | | model_providers..http_headers | map<string,string> | 附加到 provider 请求上的静态 HTTP headers。 | | model_providers..name | string | 自定义 model provider 的显示名称。 | | model_providers..query_params | map<string,string> | 附加到 provider 请求上的额外 query 参数。 | | model_providers..request_max_retries | number | 向该 provider 发起 HTTP 请求时的重试次数（默认 4）。 | | model_providers..requires_openai_auth | boolean | 该 provider 是否使用 OpenAI 认证（默认 false）。 | | model_providers..stream_idle_timeout_ms | number | SSE stream 的空闲超时（毫秒，默认 300000）。 | | model_providers..stream_max_retries | number | SSE 流中断时的重试次数（默认 5）。 | | model_providers..supports_websockets | boolean | 该 provider 是否支持 Responses API 的 WebSocket transport。 | | model_providers..auth | table | 针对自定义 provider 的命令式 bearer token 配置。不要与 env_key、experimental_bearer_token 或 requires_openai_auth 混用。 | | model_providers..auth.command | string | 当 Codex 需要 bearer token 时要执行的命令。该命令必须把 token 打印到 stdout。 | | model_providers..auth.args | array | 传给 token 命令的参数。 | | model_providers..auth.timeout_ms | number | token 命令的最长运行时间（毫秒，默认 5000）。 | | model_providers..auth.refresh_interval_ms | number | Codex 主动刷新的 token 周期（毫秒，默认 300000）。设为 0 时，只会在认证重试后刷新。 | | model_providers..auth.cwd | string (path) | 执行 token 命令时使用的工作目录。 | | model_providers.amazon-bedrock.aws.profile | string | 内建 amazon-bedrock provider 使用的 AWS profile 名称。 | | model_providers.amazon-bedrock.aws.region | string | 内建 amazon-bedrock provider 使用的 AWS region。 | | model_providers..wire_api | responses | 该 provider 使用的协议。当前唯一支持值是 responses，且省略时默认即为此值。 | | model_reasoning_effort | minimal | low | medium | high | xhigh | 在支持的模型上调整推理强度（仅 Responses API；xhigh 是否可用取决于模型）。 | | model_reasoning_summary | auto | concise | detailed | none | 选择 reasoning summary 的详细程度，或彻底关闭 summary。 | | model_supports_reasoning_summaries | boolean | 强制 Codex 发送或不发送 reasoning metadata。 | | model_verbosity | low | medium | high | 可选的 GPT-5 Responses API 输出详细程度覆盖值；未设置时使用模型 / 预设默认值。 | | notice.hide_full_access_warning | boolean | 记录是否已确认 full access warning 提示。 | | notice.hide_gpt-5.1-codex-max_migration_prompt | boolean | 记录是否已确认 gpt-5.1-codex-max 迁移提示。 | | notice.hide_gpt5_1_migration_prompt | boolean | 记录是否已确认 GPT-5.1 迁移提示。 | | notice.hide_rate_limit_model_nudge | boolean | 记录是否选择不再看到 rate limit 模型切换提醒。 | | notice.hide_world_writable_warning | boolean | 记录是否已确认 Windows world-writable 目录警告。 | | notice.model_migrations | map<string,string> | 以 old->new 映射方式记录已确认的模型迁移。 | | notify | array | 用于通知的命令；Codex 会向其传入一个 JSON payload。 | | openai_base_url | string | 内建 openai model provider 的 base URL 覆盖值。 | | oss_provider | lmstudio | ollama | 运行 --oss 时使用的默认本地 provider（未设置时会提示用户选择）。 | | otel.environment | string | 应用于 OpenTelemetry 事件的环境标签（默认 dev）。 | | otel.exporter | none | otlp-http | otlp-grpc | 选择 OpenTelemetry exporter，并提供相应 endpoint 元数据。 | | otel.exporter..endpoint | string | OTEL logs exporter 的 endpoint。 | | otel.exporter..headers | map<string,string> | OTEL exporter 请求所带的静态 headers。 | | otel.exporter..protocol | binary | json | OTLP/HTTP exporter 使用的协议。 | | otel.exporter..tls.ca-certificate | string | OTEL exporter TLS 使用的 CA 证书路径。 | | otel.exporter..tls.client-certificate | string | OTEL exporter TLS 使用的客户端证书路径。 | | otel.exporter..tls.client-private-key | string | OTEL exporter TLS 使用的客户端私钥路径。 | | otel.log_user_prompt | boolean | 是否把原始用户 prompt 一并导出到 OpenTelemetry logs。 | | otel.metrics_exporter | none | statsig | otlp-http | otlp-grpc | 选择 OpenTelemetry metrics exporter（默认 statsig）。 | | otel.trace_exporter | none | otlp-http | otlp-grpc | 选择 OpenTelemetry trace exporter，并提供相应 endpoint 元数据。 | | otel.trace_exporter..endpoint | string | OTEL trace exporter 的 endpoint。 | | otel.trace_exporter..headers | map<string,string> | OTEL trace exporter 请求所带的静态 headers。 | | otel.trace_exporter..protocol | binary | json | OTLP/HTTP trace exporter 使用的协议。 | | otel.trace_exporter..tls.ca-certificate | string | OTEL trace exporter TLS 使用的 CA 证书路径。 | | otel.trace_exporter..tls.client-certificate | string | OTEL trace exporter TLS 使用的客户端证书路径。 | | otel.trace_exporter..tls.client-private-key | string | OTEL trace exporter TLS 使用的客户端私钥路径。 | | permissions..description | string | 这个具名配置档案的人类可读说明。配置档案不会通过 extends 继承父级的 description。 | | permissions..extends | string | 可选父级配置档案，会先于当前具名配置档案应用。可以设为另一个具名配置档案、:read-only 或 :workspace；:danger-full-access、未定义父级和继承循环会被拒绝。 | | permissions..workspace_roots | table | 由配置档案定义的工作区根目录，会和当前会话的运行时工作区根目录一起接收 :workspace_roots 文件系统规则。 | | permissions..workspace_roots. | boolean | 值为 true 时，把该路径加入这个配置档案的工作区根目录集合；禁用的条目保持不生效。 | | permissions..filesystem | table | 命名的文件系统权限配置档案。每个 key 可以是绝对路径，或 :minimal、:workspace_roots 等特殊标记。 | | permissions..filesystem.glob_scan_max_depth | number | 在某些需要在沙箱启动前快照匹配结果的平台上，展开 deny-read glob pattern 的最大深度。设置时必须至少为 1。 | | permissions..filesystem. | "read" | "write" | "deny" | table | 对某个路径、glob pattern 或特殊标记直接赋权，或在该根下继续做嵌套授权。使用 "deny" 可以拒绝读取匹配路径。 | | permissions..filesystem.":workspace_roots". | "read" | "write" | "deny" | 相对于每个有效工作区根目录配置访问权限。用 "." 表示根目录本身；可用 "**/*.env" 这类 glob 子路径配合 "deny" 拒绝读取。 | | permissions..network.allow_local_binding | boolean | 允许通过沙箱化网络进行更宽的本地 / 私有网络访问。当它保持 false 时，精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。 | | permissions..network.allow_upstream_proxy | boolean | 允许沙箱化网络级联到另一个 upstream proxy。 | | permissions..network.dangerously_allow_all_unix_sockets | boolean | 允许任意 Unix socket 目的地，而不是默认受限集合。只能在严格受控环境中使用。 | | permissions..network.dangerously_allow_non_loopback_proxy | boolean | 允许沙箱化网络监听器绑定非 loopback 地址。启用后可能把监听器暴露到 localhost 之外。 | | permissions..network.enable_socks5 | boolean | 当该权限配置档案启用沙箱化网络时，暴露 SOCKS5 支持。 | | permissions..network.enable_socks5_udp | boolean | 在启用 SOCKS5 监听器时允许 UDP。 | | permissions..network.enabled | boolean | 是否为该命名权限配置档案启用网络访问。这会改变沙箱网络策略，但不会自行启动网络代理。 | | permissions..network.proxy_url | string | 当该权限配置档案启用沙箱化网络时使用的 HTTP 监听器 URL。 | | permissions..network.socks_url | string | 该权限配置档案使用的 SOCKS5 代理端点。 | | permissions..network.mode | limited | full | 子进程流量使用的网络代理模式。 | | permissions..network.domains | table | 沙箱化网络的域名规则。支持精确主机、只匹配子域名的 *.example.com、同时匹配 apex 和子域名的 **.example.com，以及全局 * allow 规则。冲突时 deny 优先。 | | permissions..network.domains. | allow | deny | 允许或拒绝精确主机，或 *.example.com、**.example.com 这类限定通配符模式。 | | permissions..network.unix_sockets | table | 沙箱化网络的 Unix socket allowlist 覆盖。键为 socket 路径；allow 会加入路径，deny 会拒绝该路径。 | | permissions..network.unix_sockets. | allow | deny | 用 allow 把绝对 Unix socket 路径加入有效 allowlist，或用 deny 拒绝该路径。被拒绝的条目会从有效 allowlist 中省略。 | | personality | none | friendly | pragmatic | 对支持 supportsPersonality 的模型设置默认沟通风格；可在 thread / turn 级别或通过 /personality 覆盖。 | | plan_mode_reasoning_effort | none | minimal | low | medium | high | xhigh | 计划模式专用的 reasoning 覆盖值。未设置时，计划模式使用其内建预设默认值。 | | project_doc_fallback_filenames | array | 当 AGENTS.md 缺失时要尝试的额外文件名。 | | project_doc_max_bytes | number | 构建项目指令时，从 AGENTS.md 最多读取的字节数。 | | project_root_markers | array | 项目根标记文件名列表；用于向父目录搜索项目根。 | | projects..trust_level | string | 将某个项目或工作树标记为可信或不可信（"trusted" | "untrusted"）。不可信项目会跳过项目作用域的 .codex/ 配置层，包括项目本地配置、钩子和规则。 | | review_model | string | /review 使用的可选模型覆盖值（默认使用当前 session 模型）。 | | sandbox_mode | read-only | workspace-write | danger-full-access | 命令执行期间的文件系统与网络访问沙箱策略。 | | sandbox_workspace_write.exclude_slash_tmp | boolean | 在 workspace-write 模式下，将 /tmp 排除出可写根目录。 | | sandbox_workspace_write.exclude_tmpdir_env_var | boolean | 在 workspace-write 模式下，将 $TMPDIR 排除出可写根目录。 | | sandbox_workspace_write.network_access | boolean | 在 workspace-write sandbox 中允许向外联网。 | | sandbox_workspace_write.writable_roots | array | 当 sandbox_mode = "workspace-write" 时的额外可写根目录。 | | service_tier | string | 新 turn 的 service tier 偏好。内建值包括 flex 和 fast；旧版 fast 配置会映射为请求值 priority，模型目录提供的 tier ID 也可以存储在这里。 | | shell_environment_policy.exclude | array | 在默认过滤之后继续移除环境变量的 glob pattern 列表。 | | shell_environment_policy.experimental_use_profile | boolean | 让子进程通过用户 shell profile 运行。 | | shell_environment_policy.ignore_default_excludes | boolean | 在其他过滤之前，保留包含 KEY / SECRET / TOKEN 的环境变量。 | | shell_environment_policy.include_only | array | 白名单 pattern；设置后只保留匹配的变量。 | | shell_environment_policy.inherit | all | core | none | 启动子进程时的基础环境继承策略。 | | shell_environment_policy.set | map<string,string> | 注入到每个子进程里的显式环境变量覆盖。 | | show_raw_agent_reasoning | boolean | 当当前模型会发出 raw reasoning 时，直接显示该内容。 | | skills.config | array | 保存在 config.toml 中的按技能启用覆盖配置。 | | skills.config..enabled | boolean | 启用或禁用对应技能。 | | skills.config..path | string (path) | 指向技能文件夹的路径，该文件夹内应包含 SKILL.md。 | | sqlite_home | string (path) | Codex 存放基于 SQLite 的状态数据库目录，供智能体作业与其他可恢复运行时状态使用。 | | suppress_unstable_features_warning | boolean | 压制开启“开发中”功能开关时显示的警告。 | | tool_output_token_limit | number | 在历史中保存单次 tool / function 输出时可使用的 token 预算。 | | tools.view_image | boolean | 启用本地图片附件工具 view_image。 | | tools.web_search | boolean | { context_size = "low | medium | high", allowed_domains = [string], location = { country, region, city, timezone } } | 可选的 web search 工具配置。旧版布尔写法仍被接受，但对象写法可额外设置搜索上下文大小、允许域名，以及近似用户位置。 | | plugins..mcp_servers..enabled | boolean | 在不修改插件 manifest 的前提下，启用或禁用已安装插件打包的 MCP server。 | | plugins..mcp_servers..default_tools_approval_mode | auto | prompt | approve | 插件提供的 MCP server 中工具的默认审批行为。 | | plugins..mcp_servers..enabled_tools | array | 插件提供的 MCP server 暴露工具允许列表。 | | plugins..mcp_servers..disabled_tools | array | 插件提供的 MCP server 的 deny list，会在 enabled_tools 之后应用。 | | plugins..mcp_servers..tools..approval_mode | auto | prompt | approve | 对插件提供的 MCP 工具的单工具审批行为覆盖。 | | tui | table | TUI 专属选项，例如是否启用内联桌面通知。 | | tui.alternate_screen | auto | always | never | 控制 TUI 是否使用 alternate screen（默认 auto；在 Zellij 中会自动跳过，以保留 scrollback）。 | | tui.animations | boolean | 启用终端动画，例如 welcome screen、shimmer、spinner（默认 true）。 | | tui.vim_mode_default | boolean | 启动时让输入框进入 Vim normal mode，而不是 insert mode（默认 false）。仍可在会话中用 /vim 切换。 | | tui.raw_output_mode | boolean | 启动 TUI 时使用 raw scrollback mode，便于在终端中选择和复制（默认 false）。可通过 /raw 或默认 alt-r 绑定切换。 | | tui.model_availability_nux. | integer | 以模型 slug 为 key 的内部启动提示状态。 | | tui.notification_method | auto | osc9 | bel | 终端通知使用的方法（默认 auto）。 | | tui.notification_condition | unfocused | always | 控制 TUI 通知只在终端失焦时触发，还是无论焦点状态都触发。默认 unfocused。 | | tui.notifications | boolean | array | 启用 TUI 通知；也可限制为特定事件类型。 | | tui.show_tooltips | boolean | 是否在 TUI welcome screen 中显示 onboarding tooltips（默认 true）。 | | tui.status_line | array | null | TUI 底部状态栏项的有序列表。null 表示禁用状态栏。 | | tui.terminal_title | array | null | 终端窗口 / 标签标题项的有序列表。默认是 ["spinner", "project"]；null 表示禁用标题更新。 | | tui.theme | string | 语法高亮主题覆盖值（kebab-case 主题名）。 | | tui.keymap.. | string | array | TUI 动作的快捷键绑定。支持的 context 包括 global、chat、composer、editor、vim_normal、vim_operator、vim_text_object、pager、list 和 approval。部分 composer 动作会回退到匹配的 tui.keymap.global 绑定；支持特定 context 绑定时，该 context 会优先生效。 | | tui.keymap.. = [] | empty array | 在对应 keymap context 中解除该动作绑定。按键名使用 ctrl-a、shift-enter、page-down 或 minus 这类规范化字符串。 | | web_search | disabled | cached | live | Web search 模式（默认 "cached"；cached 使用 OpenAI 维护的索引，不会抓取实时页面；若使用 --yolo 或其他 full access sandbox 设置，则默认切到 "live"）。"live" 会抓取最新网页数据，"disabled" 会移除该工具。 | | windows_wsl_setup_acknowledged | boolean | 记录 Windows onboarding 是否已确认（仅 Windows）。 | | windows.sandbox | unelevated | elevated | 在 Windows 原生模式下运行 Codex 时使用的原生 sandbox 模式（仅 Windows）。 | | windows.sandbox_private_desktop | boolean | 在原生 Windows 上，默认让最终 sandboxed 子进程运行在私有桌面中。只有为兼容旧版 Winsta0\Default 行为时才应设为 false。 | 你可以在 这里 找到最新的 config.toml JSON schema。 如果你想在 VS Code 或 Cursor 中编辑 config.toml 时获得自动补全和诊断提示，可以安装 Even Better TOML 扩展，并在 config.toml 顶部加入这一行： #:schema https://developers.openai.com/codex/config-schema.json 注意：请把旧键 experimental_instructions_file 重命名为 model_instructions_file。Codex 已弃用旧键，现有配置应更新到新名称。 requirements.toml requirements.toml 是管理员强制执行的配置文件，用来限制那些用户不能覆盖的安全相关设置。关于它的用途、存放位置和示例，请参见 管理员强制规则。 对于使用 ChatGPT Business 或 Enterprise 的用户，Codex 还可以应用从云端获取的 requirements 强制规则。具体优先级请参见 托管配置。 你也可以在 requirements.toml 中使用 [features]，按与 config.toml 相同的标准键名固定功能开关。没有写出的键不会受到限制。 托管的权限配置档案允许列表要求 Codex 0.138.0 或更新版本。Codex 0.137.0 及更早版本会忽略 allowed_permission_profiles 和托管的 default_permissions。 allowed_sandbox_modes 应与 sandbox_mode 搭配使用。对于权限配置档案部署，请使用 allowed_permission_profiles 搭配托管的 default_permissions。 | 键 | 类型 / 可选值 | 说明 | | --- | --- | --- | | allowed_approval_policies | array | approval_policy 允许使用的值，例如 untrusted、on-request、never 和 granular。 | | allowed_approvals_reviewers | array | approvals_reviewer 允许使用的值，例如 user 和 auto_review。 | | guardian_policy_config | string | 自动评审使用的托管 Markdown 策略指令。它的优先级高于本地 [auto_review].policy；空值会被忽略。 | | allowed_permission_profiles | table | 完整的权限配置档案允许列表。设为 true 的配置档案会被允许；省略或设为 false 的配置档案会被拒绝，包括未来版本新增的配置档案。合并多个 requirements 来源时，会按配置档案名称匹配条目。 | | allowed_permission_profiles. | boolean | 允许或拒绝某个已加载配置或 requirements 来源中定义的内建 / 自定义权限配置档案。较早的 requirements 来源可以用 false 关闭较晚来源允许的配置档案。 | | default_permissions | string | 托管默认权限配置档案。该配置档案必须被 allowed_permission_profiles 允许。请显式设置它，以获得可预测行为；如果省略，只有在 :workspace 和 :read-only 都被显式允许时，Codex 才会默认使用 :workspace。 | | enforce_residency | string | 要求 Codex 服务流量使用受支持的数据驻留。目前接受 us。 | | permissions | table | 按配置档案名称组织的管理员定义权限配置档案。使用与 config.toml 相同的配置档案字段。 | | permissions. | table | 管理员定义的权限配置档案。名称不能以 : 开头，不能使用保留名称 filesystem，也不能和已加载配置中的配置档案重名。使用与 config.toml 相同的配置档案字段；完整 schema 见权限。 | | allowed_sandbox_modes | array | sandbox_mode 允许使用的值。 | | windows | table | Windows 原生沙箱 requirements。 | | windows.allowed_sandbox_implementations | array | windows.sandbox 允许使用的原生 Windows 沙箱实现（elevated 和 unelevated）。列表不能为空。两者都允许且未选择模式时，Codex 优先使用 elevated。 | | remote_sandbox_config | array 针对特定主机的沙箱强制要求。第一个 hostname_patterns 匹配解析后主机名的条目，会覆盖该 requirements 来源顶层的 allowed_sandbox_modes。当前主机级条目只会覆盖沙箱模式。 | | remote_sandbox_config[].hostname_patterns | array | 不区分大小写的主机名模式。支持用 * 匹配任意字符序列，用 ? 匹配单个字符。 | | remote_sandbox_config[].allowed_sandbox_modes | array | 当该主机级条目命中时要应用的沙箱模式允许列表。 | | allowed_web_search_modes | array | web_search 允许使用的值（disabled、cached、live）。disabled 永远允许；若为空数组，则效果上只允许 disabled。 | | allow_managed_hooks_only | boolean | 为 true 时，Codex 会跳过用户、项目、会话和插件 hooks，但仍允许 requirements.toml 与其他托管配置层提供的托管 hooks。 | | allow_appshots | boolean | 设为 false 可为受管理用户禁用 Appshots。如果省略，Appshots 不会受到 requirements 约束，仍按正常产品可用性决定。 | | allow_remote_control | boolean | 设为 false 可为受管理用户禁用设备远程控制。如果省略，设备远程控制不会受到 requirements 约束，仍按正常产品可用性决定。 | | features.plugin_sharing | boolean | 在 cloud-managed requirements.toml 中设为 false 可禁用本地构建插件的工作区共享。 | | features | table | 按 config.toml 中 [features] 的 canonical key 固定 feature 值。 | | features. | boolean | 要求某个 canonical feature key 必须保持启用或禁用。 | | features.apps | boolean | 固定受管理用户的 Apps 集成可用性。 | | features.in_app_browser | boolean | 在 requirements.toml 中设为 false 可禁用 app 内浏览器面板。 | | features.browser_use | boolean | 在 requirements.toml 中设为 false 可禁用 Browser Use 和 Browser Agent 可用性。 | | features.browser_use_external | boolean | 在 requirements.toml 中设为 false 可禁用外部浏览器 Browser Use 可用性。 | | features.browser_use_full_cdp_access | boolean | 在 requirements.toml 中设为 false 可阻止用户在 Browser Developer mode 中启用完整 Chrome DevTools Protocol 访问。如果省略，仍按正常产品可用性决定。 | | features.fast_mode | boolean | 固定受管理用户的 canonical fast_mode 功能开关。 | | features.guardian_approval | boolean | 固定受管理用户的 Guardian approval 可用性。 | | features.memories | boolean | 固定受管理用户的 Memories 可用性。 | | features.multi_agent | boolean | 固定受管理用户的 multi-agent 可用性。 | | features.plugins | boolean | 固定受管理用户的插件可用性。 | | features.computer_use | boolean | 在 requirements.toml 中设为 false 可禁用 Computer Use 可用性及相关安装或设置流程。 | | features.workspace_dependencies | boolean | 固定受管理用户的 bundled workspace-dependency runtime 可用性。 | | computer_use | table | 从 requirements.toml 强制执行的 Computer Use requirements。 | | computer_use.allow_locked_computer_use | boolean | 设为 false 可阻止 Computer Use 在托管 macOS 设备锁定后继续操作。如果省略，锁定状态使用不会被 requirements 约束。 | | experimental_network | table | 从 requirements.toml 强制执行的网络访问要求。这些约束与 features.network_proxy 相互独立，可以在没有用户功能开关的情况下配置沙箱化网络。 | | experimental_network.enabled | boolean | 启用沙箱化网络要求。如果当前激活的沙箱关闭命令联网，这不会授予网络访问。 | | experimental_network.http_port | integer | [experimental_network] 要求使用的 loopback HTTP 监听器端口。 | | experimental_network.socks_port | integer | [experimental_network] 要求使用的 loopback SOCKS5 监听器端口。 | | experimental_network.allow_upstream_proxy | boolean | 允许沙箱化网络使用环境中的 upstream proxy。 | | experimental_network.dangerously_allow_non_loopback_proxy | boolean | 允许 [experimental_network] 要求使用非 loopback 监听器地址。启用后可能把监听器暴露到 localhost 之外。 | | experimental_network.dangerously_allow_all_unix_sockets | boolean | 允许任意 Unix socket 目的地，而不是 allowlist-only 访问。只能在严格受控环境中使用。 | | experimental_network.domains | map<string, allow | deny> | 管理员域名策略。支持精确主机、*.example.com、**.example.com 和全局 * allow 规则；应优先使用更窄规则。冲突时 deny 优先。不要与 experimental_network.allowed_domains 或 experimental_network.denied_domains 混用。 | | experimental_network.allowed_domains | array | 列表形式的管理员 allow 规则。不要与 experimental_network.domains 混用。 | | experimental_network.denied_domains | array | 列表形式的管理员 deny 规则。不要与 experimental_network.domains 混用。 | | experimental_network.managed_allowed_domains_only | boolean | 为 true 时，在沙箱化网络要求生效期间，只有管理员管理的 allow 规则继续有效；用户新增的 allowlist 条目会被忽略。若没有托管 allow 规则，用户新增的域名 allow 规则也不会继续有效。 | | experimental_network.unix_sockets | map<string, allow | deny> | 管理员管理的 Unix socket 策略，用于沙箱化网络。 | | experimental_network.allow_local_binding | boolean | 允许沙箱化网络进行更宽的本地 / 私有网络访问。当它保持 false 时，精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。 | | hooks | table | 管理员强制的托管生命周期钩子。需要配置托管钩子目录，并使用与 config.toml 内联 [hooks] 相同的事件 schema。 | | hooks.managed_dir | string (absolute path) | macOS 和 Linux 上存放托管钩子脚本的目录。Codex 会在加载托管钩子前校验它是绝对路径且已存在。 | | hooks.windows_managed_dir | string (absolute path) | Windows 上存放托管钩子脚本的目录。Codex 会在加载托管钩子前校验它是绝对路径且已存在。 | | hooks. | array 某个钩子事件的 matcher 分组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。 | | hooks.[].hooks | array matcher 分组下的钩子处理器。当前支持 command hooks；prompt 和 agent hook handlers 会被解析但跳过。 | | hooks.[].hooks[].commandWindows | string | command hooks 的 Windows 专用命令覆盖。也接受 TOML alias command_windows。 | | mcp_servers | table | 允许启用的 MCP 服务端允许列表。只有当服务端名称（）和身份信息都匹配时，该 MCP 服务端才能启用。凡是不在允许列表中，或身份不匹配的 MCP 服务端，都会被禁用。 | | mcp_servers..identity | table | 单个 MCP server 的身份规则。可设置 command（stdio）或 url（streamable HTTP）之一。 | | mcp_servers..identity.command | string | 当 mcp_servers..command 与该值匹配时，允许该 MCP stdio server。 | | mcp_servers..identity.url | string | 当 mcp_servers..url 与该值匹配时，允许该 MCP streamable HTTP server。 | | plugins | table | 按插件标识组织的插件专属 MCP server 允许列表。 | | plugins..mcp_servers..identity.command | string | 当插件 stdio MCP server 的已配置命令与该值匹配时，允许该 server。 | | plugins..mcp_servers..identity.url | string | 当插件 streamable HTTP MCP server 的已配置 URL 与该值匹配时，允许该 server。 | | apps | table | 按 app 标识组织的托管 app requirements。Requirements 可以禁用某个 app，或约束单个工具的审批行为。 | | apps..enabled | boolean | 设为 false 可禁用某个 app。合并多个 requirements 来源时，禁用要求仍会保持收紧。 | | apps..tools..approval_mode | auto | prompt | approve | 设置某个 app 工具的托管审批模式。 | | permissions.filesystem.deny_read | array | 管理员强制的文件系统读拒绝规则。条目可以是路径或 glob pattern，用户不能通过本地配置放宽这些规则。 | | rules | table | 与 .rules 文件合并的管理员强制命令规则。requirements 中的 rules 必须是收紧型限制。 | | rules.prefix_rules | array 强制生效的 prefix rules 列表。每条规则都必须包含 pattern 和 decision。 | | rules.prefix_rules[].decision | prompt | forbidden | 必填。requirements 中的规则只能是 prompt 或 forbidden，不能是 allow。 | | rules.prefix_rules[].justification | string | 可选的非空说明，会显示在 approval 提示或拒绝消息中。 | | rules.prefix_rules[].pattern | array 以前缀 token 形式表达的命令模式。每个 token 位置都要设置 token 或 any_of。 | | rules.prefix_rules[].pattern[].any_of | array | 该位置允许的多个备选 token。 | | rules.prefix_rules[].pattern[].token | string | 该位置必须匹配的单个字面 token。 | © 2026 Codex 中文站 · @字节笔记本 最后部署 2026/06/23 05:55 | | | | | | | | |