将此页面用作 Codex 配置文件的可搜索参考。如需概念指导和示例，请先参阅配置基础和高级配置。
config.toml
用户级配置位于 ~/.codex/config.toml。你还可以在 .codex/config.toml 文件中添加项目范围的覆盖配置。只有当你信任项目时，Codex 才会加载项目范围的配置文件。
项目范围的配置不能覆盖计算机本地的提供商、身份验证、
宿主应用拥有的请求元数据、通知、配置档案选择或
遥测路由键。当 openai_base_url、
chatgpt_base_url、apps_mcp_product_sku、model_provider、
model_providers、notify、profile、profiles、
experimental_realtime_ws_base_url 和 otel 出现在项目本地的
.codex/config.toml 中时，Codex 会忽略它们；请改为将提供商、通知和遥测
键放在用户级配置中。配置档案文件以
$CODEX_HOME/profile-name.config.toml 的形式与 config.toml 位于同一位置；使用
--profile profile-name 选择一个档案。
对于沙盒和审批键（approval_policy、sandbox_mode 和 sandbox_workspace_write.*），请将本参考与沙盒和审批、可写根目录中的受保护路径及网络访问配合使用。有关测试版权限档案，请参阅权限。
<ConfigTable
options={[
{
key: "model",
type: "string",
description: "要使用的模型（例如 gpt-5.5）。",
},
{
key: "review_model",
type: "string",
description:
"/review 使用的可选模型覆盖项（默认为当前会话模型）。",
},
{
key: "model_provider",
type: "string",
description: "model_providers 中的提供商 ID（默认值：openai）。",
},
{
key: "openai_base_url",
type: "string",
description:
"覆盖内置 openai 模型提供商的基础 URL。",
},
{
key: "model_context_window",
type: "number",
description: "当前模型可用的上下文窗口 token 数。",
},
{
key: "model_auto_compact_token_limit",
type: "number",
description:
"触发自动压缩历史记录的 token 阈值（未设置时使用模型默认值）。",
},
{
key: "model_auto_compact_token_limit_scope",
type: "total | body_after_prefix",
description:
"控制自动压缩阈值是计算完整的当前上下文（total，默认值），还是仅计算所保留压缩窗口前缀之后的增长量（body_after_prefix）。",
},
{
key: "model_catalog_json",
type: "string (path)",
description:
"启动时加载的 JSON 模型目录的可选路径。所选 $CODEX_HOME/profile-name.config.toml 配置文件可按配置覆盖此设置。",
},
{
key: "oss_provider",
type: "lmstudio | ollama",
description:
"使用 --oss 运行时采用的默认本地提供商（未设置时默认提示选择）。",
},
{
key: "approval_policy",
type: "untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }",
description:
"控制 Codex 在执行命令前何时暂停并请求批准。你还可以使用 approval_policy = { granular = { ... } }，在保持其他提示可交互的同时，允许或自动拒绝特定提示类别。on-failure 已弃用；交互式运行请使用 on-request，非交互式运行请使用 never。",
},
{
key: "approval_policy.granular.sandbox_approval",
type: "boolean",
description:
"设为 true 时，允许显示沙箱权限提升批准提示。",
},
{
key: "approval_policy.granular.rules",
type: "boolean",
description:
"设为 true 时，允许显示由 execpolicy prompt 规则触发的批准提示。",
},
{
key: "approval_policy.granular.mcp_elicitations",
type: "boolean",
description:
"设为 true 时，允许显示 MCP 信息征询提示，而不是自动拒绝。",
},
{
key: "approval_policy.granular.request_permissions",
type: "boolean",
description:
"设为 true 时，允许显示来自 request_permissions 工具的提示。",
},
{
key: "approval_policy.granular.skill_approval",
type: "boolean",
description:
"设为 true 时，允许显示技能脚本批准提示。",
},
{
key: "approvals_reviewer",
type: "user | auto_review",
description:
"指定由谁审核 on-request 或细粒度批准策略下符合条件的批准提示。默认值为 user；auto_review 使用审核子代理。此设置不会改变沙箱机制，也不会改变沙箱内已允许的审核操作。",
},
{
key: "auto_review.policy",
type: "string",
description:
"用于自动审核的本地 Markdown 策略说明。托管的 guardian_policy_config 优先级更高。空值将被忽略。",
},
{
key: "allow_login_shell",
type: "boolean",
description:
"允许基于 shell 的工具使用登录 shell 语义。默认值为 true；设为 false 时，将拒绝 login = true 请求，省略的 login 则默认为非登录 shell。",
},
{
key: "sandbox_mode",
type: "read-only | workspace-write | danger-full-access",
description:
"命令执行期间文件系统和网络访问所采用的沙箱策略。",
},
{
key: "sandbox_workspace_write.writable_roots",
type: "array",
description:
'使用 sandbox_mode = "workspace-write" 时的其他可写根目录。',
},
{
key: "sandbox_workspace_write.network_access",
type: "boolean",
description:
"允许在 workspace-write 沙箱内访问出站网络。",
},
{
key: "sandbox_workspace_write.exclude_tmpdir_env_var",
type: "boolean",
description:
"在 workspace-write 模式下，从可写根目录中排除 $TMPDIR。",
},
{
key: "sandbox_workspace_write.exclude_slash_tmp",
type: "boolean",
description:
"在 workspace-write 模式下，从可写根目录中排除 /tmp。",
},
{
key: "windows.sandbox",
type: "unelevated | elevated",
description:
"在 Windows 上原生运行 Codex 时使用的仅限 Windows 的原生沙箱模式。",
},
{
key: "windows.sandbox_private_desktop",
type: "boolean",
description:
"在原生 Windows 上，默认在专用桌面中运行最终的沙箱子进程。仅为兼容旧版 Winsta0\\\\Default 行为时才设为 false。",
},
{
key: "computer_use.windows.always_allowed_app_ids",
type: "array",
description:
"Computer Use 无需提示即可打开的 Windows 应用标识符。不在列表中的应用需要批准；可从 ChatGPT 桌面应用的 Computer Use 设置中移除已保存的条目。",
},
{
key: "notify",
type: "array",
description:
"通知时调用的命令；该命令会接收来自 Codex 的 JSON 有效载荷。",
},
{
key: "check_for_update_on_startup",
type: "boolean",
description:
"启动时检查 Codex 更新（仅当更新由中央统一管理时才设为 false）。",
},
{
key: "feedback.enabled",
type: "boolean",
description:
"允许在本地客户端中通过 /feedback 提交反馈（默认值：true）。",
},
{
key: "analytics.enabled",
type: "boolean",
description:
"为此计算机/配置启用或禁用分析。未设置时，应用客户端默认值。",
},
{
key: "instructions",
type: "string",
description:
"保留供将来使用；请优先使用 model_instructions_file 或 AGENTS.md。",
},
{
key: "developer_instructions",
type: "string",
description:
"注入会话的其他开发者说明（可选）。",
},
{
key: "log_dir",
type: "string (path)",
description:
"Codex 写入日志文件的目录；默认为 $CODEX_HOME/log。显式设置此项还会在该目录中启用可选的纯文本 TUI 日志 codex-tui.log。",
},
{
key: "sqlite_home",
type: "string (path)",
description:
"Codex 存储由 SQLite 支持的状态数据库的目录，该数据库用于代理作业及其他可恢复的运行时状态。",
},
{
key: "compact_prompt",
type: "string",
description: "对历史记录压缩提示词的内联覆盖。",
},
{
key: "model_instructions_file",
type: "string (path)",
description:
"用于替换内置说明，而不是 AGENTS.md。",
},
{
key: "personality",
type: "none | friendly | pragmatic",
description:
"为声明支持 supportsPersonality 的模型设置默认沟通风格；可按线程/轮次或通过 /personality 覆盖。",
},
{
key: "service_tier",
type: "string",
description:
"新轮次的首选服务层级。使用 fast 或当前模型声明的其他层级；fast 会映射到请求值 priority。",
},
{
key: "experimental_compact_prompt_file",
type: "string (path)",
description:
"从文件加载压缩提示词覆盖项（实验性）。",
},
{
key: "skills.config",
type: "array
