配置项速查
按主题分组的常用 config.toml 配置项，列出键名、类型、默认值与作用（基于 Codex CLI v0.158.0）
作者 David·更新于 ·第 4 篇（共 22 篇） 本页挑出日常最常用的配置项并按主题分组，键名、取值与默认值以 v0.158.0 源码为准。完整清单（含 MCP、插件、浏览器、遥测等数百项）见官方 Configuration Reference 与 JSON Schema；文件位置与优先级见配置文件。
表中“—”表示默认不设置；a.b 形式的键在文件里写作 [a] 表下的 b。
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
model | 字符串 | 模型目录的默认模型 | 默认使用的模型 |
review_model | 字符串 | 当前会话模型 | /review 使用的模型 |
model_reasoning_effort | low、medium、high、xhigh、max、ultra 等 | 模型默认 | 推理强度，可用档位由模型决定 |
plan_mode_reasoning_effort | 同上 | 计划模式预设 | 计划模式专用的推理强度 |
model_reasoning_summary | auto、concise、detailed、none | 模型默认 | 推理摘要的详细程度；本地 TUI 新会话未设置时按 none 请求，TUI 状态行的实时推理摘要（v0.155.0 起）要设成其他值才会出现 |
model_verbosity | low、medium、high | 模型默认 | 回答详略 |
model_context_window | 整数 | 模型默认 | 上下文窗口 token 数 |
model_auto_compact_token_limit | 整数 | 模型默认 | 触发自动压缩的 token 阈值 |
model_post_turn_compact_threshold_percent | 整数 0～100 | — | 一轮结束后，上下文用量达到可用窗口的这个百分比就先压缩；省略或设为 0 表示不启用（v0.156.0 起） |
service_tier | 字符串 | — | 服务档位，如 fast（即 priority）、flex、default |
personality | none、friendly、pragmatic | — | 已弃用：v0.156.0 起 friendly、pragmatic 不再改变回复风格，/personality 也已移除；none 仍会去掉模型指令里的 Personality 小节 |
hide_agent_reasoning | 布尔 | false | 隐藏推理事件（TUI 与 codex exec） |
show_raw_agent_reasoning | 布尔 | false | 显示模型输出的原始推理内容 |
model_catalog_json | 路径 | — | 启动时加载的自定义模型目录 |
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
model_provider | 字符串 | openai | 使用哪个提供方 |
openai_base_url | 字符串 | — | 改写内置 openai 提供方的地址（代理、数据驻留） |
oss_provider | ollama、lmstudio | — | --oss 的默认本地提供方，未设时交互询问 |
model_providers.<id>.base_url | 字符串 | — | 提供方 API 地址 |
model_providers.<id>.env_key | 字符串 | — | 存放 API Key 的环境变量名 |
model_providers.<id>.wire_api | responses | responses | 协议，chat 已不再支持 |
model_providers.<id>.query_params | 表 | — | 追加到请求 URL 的查询参数 |
model_providers.<id>.http_headers | 表 | — | 固定请求头；env_http_headers 则从环境变量取值 |
model_providers.<id>.request_max_retries | 整数 | 4 | HTTP 请求重试次数 |
model_providers.<id>.stream_max_retries | 整数 | 5 | 流式响应中断后的重连次数 |
model_providers.<id>.stream_idle_timeout_ms | 整数 | 300000 | 流式响应空闲超时（毫秒） |
model_providers.<id>.requires_openai_auth | 布尔 | false | 使用 OpenAI 登录凭证 |
model_providers.<id>.auth.command | 字符串 | — | 通过外部命令获取 bearer token |
model_providers.<id>.model_catalog_url | 字符串 | — | Codex 格式模型目录的完整地址，获取时带上该提供方的认证、请求头与查询参数（v0.156.0 起） |
model_providers.<id>.gateway_oauth | 表（authorization_url、token_url、client_id、delivery 等） | — | 提供方网关额外要求的 OAuth 凭据：浏览器登录后按 delivery 放进请求头或 cookie，与主认证一起发送（v0.156.0 起） |
model_providers.amazon-bedrock.aws.credential_export | 表（command、args、timeout_ms） | — | 用外部命令导出 Bedrock 签名所需的 AWS 凭据，timeout_ms 默认 30000，不能与 aws.profile 同用（v0.155.0 起） |
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
approval_policy | on-request、never、{ granular = { ... } } | on-request | 何时暂停请求审批；untrusted 已不支持 |
approval_policy.granular.* | 布尔 | — | sandbox_approval、rules、mcp_elicitations、request_permissions、skill_approval，为 false 的类别自动拒绝 |
approvals_reviewer | user、auto_review | user | 审批请求交给谁审 |
auto_review.policy | 字符串 | — | 自动审查的本地策略，托管的 guardian_policy_config 优先 |
auto_review.extra_policy | 字符串 | — | 追加给自动审查的策略文本，托管的 guardian_extra_policy 优先（v0.157.0 起） |
sandbox_mode | read-only、workspace-write、danger-full-access | 见下方说明 | 执行命令时的沙箱模式 |
sandbox_workspace_write.writable_roots | 路径数组 | [] | 额外的可写目录 |
sandbox_workspace_write.network_access | 布尔 | false | 允许沙箱内命令联网 |
sandbox_workspace_write.exclude_tmpdir_env_var | 布尔 | false | 不把 $TMPDIR 视为可写 |
sandbox_workspace_write.exclude_slash_tmp | 布尔 | false | 不把 /tmp 视为可写 |
default_permissions | 字符串 | — | 默认权限配置档（beta），如 :workspace |
permissions.<name>.* | 表 | — | 自定义权限配置档，不可与 sandbox_mode 混用 |
allow_login_shell | 布尔 | true | 是否允许 shell 工具使用登录 shell |
projects.<path>.trust_level | trusted、untrusted | — | 项目信任状态 |
windows.sandbox | elevated、unelevated、mxc | — | 原生 Windows 沙箱实现；mxc 使用微软的 MXC 容器，需要系统支持（v0.156.0 起） |
web_search | disabled、cached、indexed、live | cached | 网页搜索模式，完全访问时默认为 live |
sandbox_mode 未设置时：已有信任决定（trusted 或 untrusted）的目录默认 workspace-write，其余目录默认 read-only；原生 Windows 未配置沙箱时，workspace-write 会降为 read-only。原来的 windows.sandbox_private_desktop 已在 v0.156.0 移除，elevated 与 unelevated 沙箱一律在私有桌面上运行。
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
shell_environment_policy.inherit | all、core、none | all | 子进程环境变量的初始集合 |
shell_environment_policy.ignore_default_excludes | 布尔 | true | 为 true 时不自动剔除名含 KEY、SECRET、TOKEN 的变量 |
shell_environment_policy.set | 表 | — | 强制设置的变量 |
shell_environment_policy.filters | 表（include / exclude） | — | 按模式过滤变量，不区分大小写 |
shell_environment_policy.exclude | 数组 | — | 旧写法（另有 include_only），不能与 filters 同层混用 |
shell_environment_policy.experimental_use_profile | 布尔 | false | 用用户的 shell profile 启动子进程 |
background_terminal_max_timeout | 整数（毫秒） | 300000 | 轮询后台终端输出的最长等待 |
tool_output_token_limit | 整数 | — | 单个工具输出存入历史的 token 预算 |
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
project_doc_max_bytes | 整数 | 32768 | 项目级 AGENTS.md 合计读取上限（字节） |
project_doc_fallback_filenames | 字符串数组 | [] | AGENTS.md 缺失时尝试的备用文件名 |
project_root_markers | 字符串数组 | [".git"] | 判定项目根的标记，[] 表示只看当前目录；写在项目配置里不影响查找 |
developer_instructions | 字符串 | — | 额外注入的开发者指令 |
model_instructions_file | 路径 | — | 替换内置模型指令（官方不建议） |
compact_prompt | 字符串 | — | 自定义历史压缩提示词；只用于本地压缩，OpenAI、Azure、Amazon Bedrock 等走服务端压缩的提供方不使用它 |
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
notify | 字符串数组 | — | 回合结束时调用的外部程序 |
tui.notifications | 布尔或字符串数组 | true | 开关 TUI 通知，或只保留指定事件 |
tui.notification_method | auto、osc9、bel | auto | 终端通知方式 |
tui.notification_condition | unfocused、always | unfocused | 仅在终端失焦时通知，还是始终通知 |
tui.animations | 布尔 | true | 动画总开关；v0.156.0 起，首次启动检测到屏幕阅读器、而你又没设置过这一项时，会写入 false，系统开启“减少动态效果”时也不播放动画 |
tui.effects.<效果> | 布尔 | true | 分别开关 starfield、shimmer、welcome、effort、progress、title 六种效果，受 tui.animations 约束；v0.156.0 起取代 tui.whimsy。v0.158.0 起旧键 tui.whimsy 作为 tui.effects.starfield 的别名重新生效，同一文件里两者都写时以 tui.effects.starfield 为准 |
tui.alternate_screen | auto、always、never | auto | 是否使用终端备用屏幕；v0.157.0 起，auto 在通过 SSH 使用 macOS Terminal.app 时改用内联模式 |
tui.fullscreen_transcript | 布尔 | true | 全屏对话记录，由 Codex 接管滚动、选择与搜索；v0.156.0 新增时默认 false，v0.157.0 起默认 true。不使用备用屏幕时不生效，可用 /tui 切换 |
tui.copy_on_select | auto、always、never | auto | 在 Codex 接管的对话记录里（全屏对话记录与 Ctrl+T 记录视图）用鼠标选中文字、松开鼠标时是否自动复制；auto 在已知会自行转发复制快捷键的终端（Ghostty 1.2 及以上、macOS 上的 Kitty、Windows Terminal、Windows 上的 VS Code）里不自动复制，其他终端以及 tmux、Zellij 里照常复制（v0.158.0 起） |
tui.right_click_paste | auto、on、off | auto | 全屏模式下没有选中文字时，右键把剪贴板文本粘贴进输入框；auto 只在 Windows、WSL、Linux 上启用，on 连 macOS 也启用，SSH 会话和 VS Code 终端里一律不启用（v0.158.0 起） |
tui.rendering.<类型> | 布尔 | true | 分别开关 mermaid（图表）、math（公式）、tables（表格）与 lists（列表符号，v0.157.0 起）的渲染，关闭后显示原文（v0.156.0 起） |
tui.show_tooltips | 布尔 | true | 启动时的使用提示；v0.158.0 起全屏对话记录不再在开头显示，改为在回合运行超过 30 秒时或回合结束后偶尔显示一条，同样由它开关 |
tui.show_server_version_notice | 布尔 | true | 连接的 app server 与 CLI 版本不同时显示提示，不影响兼容性报错（v0.155.0 起；v0.156.0 起预发布版与本地构建也会提示） |
tui.theme | 字符串 | 自动 | 语法高亮主题；v0.156.0 起内置 ada、babbage、curie、cushman、dali、davinci 等主题 |
tui.status_line | 字符串数组 | model-with-reasoning、current-dir、thread-name | 状态栏显示项 |
tui.terminal_title | 字符串数组 | activity、thread-name、project-name | 终端标题显示项 |
tui.vim_mode_default | 布尔 | false | 输入框默认进入 Vim 模式 |
tui.raw_output_mode | 布尔 | false | 以便于复制的原始回滚模式启动 |
tui.keymap.<context>.<action> | 字符串或数组 | — | 自定义快捷键，空数组表示解绑。v0.156.0 起新增 chat.toggle_voice（默认 f8）、global.find_transcript（f3）、global.focus_activity（f4）、pager.find（f3 与 /）以及代理总览的 agents.new_worktree（w），代理总览各操作的默认键也改成了单个按键 |
realtime.voice | 字符串 | 服务端默认 | 语音对话使用的声音，如 marin、cedar；/voice settings 会写入它（v0.156.0 起） |
file_opener | vscode、vscode-insiders、windsurf、cursor、none | vscode | 文件引用链接使用的 URI 方案 |
check_for_update_on_startup | 布尔 | true | 启动时检查更新 |
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
history.persistence | save-all、none | save-all | 是否写入 history.jsonl |
history.max_bytes | 整数 | — | 历史文件大小上限，超出丢弃最旧记录 |
log_dir | 路径 | $CODEX_HOME/log | 日志目录，显式设置时额外写 codex-tui.log |
sqlite_home | 路径 | CODEX_SQLITE_HOME 或 CODEX_HOME | SQLite 状态库位置 |
cli_auth_credentials_store | file、keyring、auto、ephemeral | file | CLI 登录凭证存放方式 |
mcp_oauth_credentials_store | auto、file、keyring | auto | MCP OAuth 凭证存放方式 |
forced_login_method | chatgpt、api | — | 限定登录方式 |
analytics.enabled | 布尔 | true | 匿名使用与健康数据上报 |
feedback.enabled | 布尔 | true | 是否允许 /feedback |
[features] 表中的常用键，codex features list 可列出全部：
| 键 | 默认 | 成熟度 | 作用 |
|---|
hooks | true | 稳定 | 生命周期 hooks |
multi_agent | true | 稳定 | 子代理协作工具 |
goals | true | 稳定 | 持久化目标与自动续跑 |
fast_mode | true | 稳定 | Fast 等服务档位选择 |
apps | true | 稳定 | App（连接器）集成 |
plugins | true | 稳定 | 插件 |
shell_snapshot | true | 稳定 | 快照 shell 环境以加速重复命令 |
memories | false | 稳定 | 记忆功能 |
network_proxy | false | 实验 | 按域名策略约束已联网的沙箱命令 |
worktrees | true | 稳定 | 托管 Git worktree（v0.156.0 起默认开启） |
prevent_idle_sleep | false | 实验 | 运行期间阻止系统休眠 |
realtime_conversation | true | 稳定 | 语音对话 /voice（v0.155.0 起；v0.156.0 起默认开启） |
daemon_auto_start | true | 稳定 | 交互式启动时自动拉起共享的后台服务（v0.156.0 为默认关闭的实验功能，v0.157.0 起默认开启） |
system_proxy_fallback | true | 稳定 | 登录与启动阶段的请求直连失败时，改走系统代理重试（v0.156.0 起） |
write_stdin_approval | true | 稳定 | 模型向已在运行的终端写入输入时，若该终端是在沙箱外启动的、带着额外授予的权限，或沙箱设置已与当前权限不一致，要先经过审批（v0.158.0 起转为稳定并默认开启） |
analytics_plan_history | false | 实验 | 在用量分析面板里预览个人套餐的五小时与每周额度历史（v0.156.0 起） |
web_search_cached | false | 已弃用 | 与 web_search_request 一样，请改用顶层 web_search |
transcript_v2 | false | 已弃用 | 已不起作用，请改用 tui.fullscreen_transcript |
功能开关 personality 已在 v0.156.0 移除，配置里残留也会被忽略。v0.158.0 起 [features.guardianv2] 下的 thread_context 也已移除：自动审查始终使用线程自身的上下文，这一项会被忽略，启动时提示把它从配置里删掉。
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
mcp_servers.<id>.command | 字符串 | — | stdio 服务器的启动命令（配合 args、env、cwd） |
mcp_servers.<id>.url | 字符串 | — | 可流式 HTTP 服务器地址 |
mcp_servers.<id>.bearer_token_env_var | 字符串 | — | 从环境变量读取 bearer token |
mcp_servers.<id>.enabled | 布尔 | — | 设为 false 可停用而不删除配置 |
mcp_servers.<id>.required | 布尔 | — | 为 true 时初始化失败会让启动失败 |
mcp_servers.<id>.startup_timeout_sec | 数字 | 30 | 启动超时（秒）；官方文档写作 10 |
mcp_servers.<id>.startup_readiness | connection、catalog | connection | 启动时是否必须等实时连接就绪；设为 catalog 时可先用有效的缓存工具清单把工具提供给模型，真正调用工具仍需实时连接。与 required = true 同用时，有效的缓存也算启动成功，连接失败要到调用工具时才报错（v0.158.0 起） |
mcp_servers.<id>.tool_timeout_sec | 数字 | 300 | 单次工具调用超时（秒）；官方文档写作 60 |
mcp_servers.<id>.enabled_tools | 数组 | — | 工具白名单，另有黑名单 disabled_tools |
mcp_servers.<id>.tool_input_schema_max_bytes | 整数（字节） | 5000 | 单个工具的输入 schema 超过这个大小时逐步压缩（先删参数说明，再删定义等），调大可保留更多参数说明（v0.158.0 起） |
mcp_servers.<id>.oauth.client_secret | 字符串 | — | 预注册 OAuth 客户端的密钥，换取令牌时使用，必须同时设置 oauth.client_id；也可用 codex mcp add --oauth-client-secret 写入（v0.158.0 起） |
完整字段与用法见 MCP 集成。
| 键 | 类型 / 取值 | 默认 | 作用 |
|---|
agents.max_concurrent_threads_per_session | 整数 | 由 Codex 决定 | 同时打开的子代理线程上限 |
agents.default_subagent_model | 字符串 | — | 子代理默认模型，见子代理 |
hooks.<Event> | 表数组 | — | 内联 hooks，见 Hooks |
memories.version | v1、v2 | v1 | 记忆管线版本，v2 的数据单独存放（v0.155.0 起） |
memories.dual_write | 布尔 | false | 两个版本的记忆同时生成，上下文仍取 memories.version 选中的版本（v0.155.0 起） |
otel.exporter | none、otlp-http、otlp-grpc | none | OpenTelemetry 日志导出 |
otel.log_user_prompt | 布尔 | false | 导出时是否包含用户提示原文 |
otel.log_agent_responses | 布尔 | false | 把主代理与子代理的最终回复写入 OTLP 日志，只在 otel.exporter 为 otlp-http 或 otlp-grpc 时生效；内容可能敏感，每条最多 64 KiB（v0.158.0 起） |
otel.log_guardian_assessments | 布尔 | false | 把自动审查完成的评估（含理由）写入 OTLP 日志，生效条件同上，理由最多 64 KiB（v0.158.0 起） |
以下键只在管理员下发的 requirements.toml 中有意义，用户与项目配置无法越过：
| 键 | 作用 |
|---|
allowed_approval_policies | 允许的 approval_policy；列入 untrusted 表示允许不信任项目派生出的严格策略 |
allowed_approvals_reviewers | 允许的 approvals_reviewer |
allowed_sandbox_modes | 允许的 sandbox_mode |
allowed_permission_profiles | 允许的权限配置档，未列出的一律禁止 |
allowed_web_search_modes | 允许的 web_search 模式，disabled 始终允许 |
guardian_policy_config | 托管的自动审查策略，优先于本地 auto_review.policy |
guardian_extra_policy | 托管的附加审查策略，优先于本地 auto_review.extra_policy（v0.157.0 起） |
model_provider、model_providers | 强制选用的提供方，以及整体替换本地同名条目的提供方定义（v0.156.0 起） |
features.<name> | 锁定某个功能开关的取值 |
windows.allowed_sandbox_implementations | 允许的原生 Windows 沙箱实现 |
models.new_thread.model | 新会话的托管默认模型，显式指定模型或推理强度时失效 |