Configuration Reference

此非核心页面暂未翻译。 正文保留当前快照中的官方英文 Markdown；你也可以访问官方原文。

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with Config basics and Advanced Config.

`config.toml`

User-level configuration lives in ~/.codex/config.toml. You can also add project-scoped overrides in .codex/config.toml files. Codex loads project-scoped config files only when you trust the project.

Project-scoped config can’t override machine-local provider, auth, host-owned app request metadata, notification, configuration profile selection, or telemetry routing keys. Codex ignores openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel when they appear in a project-local .codex/config.toml; put provider, notification, and telemetry keys in user-level config instead. Config profile files live next to config.toml as $CODEX_HOME/profile-name.config.toml; select one with --profile profile-name.

For sandbox and approval keys (approval_policy, sandbox_mode, and sandbox_workspace_write.*), pair this reference with Sandbox and approvals, Protected paths in writable roots, and Network access. For beta permission profiles, see Permissions.

You can find the latest JSON schema for config.toml here.

To get autocompletion and diagnostics when editing config.toml in VS Code or Cursor, you can install the Even Better TOML extension and add this line to the top of your config.toml:

#:schema https://developers.openai.com/codex/config-schema.json

Note: Rename experimental_instructions_file to model_instructions_file. Codex deprecates the old key; update existing configs to the new name.

`requirements.toml`

requirements.toml is an admin-enforced configuration file that constrains security-sensitive settings users can’t override. For details, locations, and examples, see Admin-enforced requirements.

For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched requirements. See the security page for precedence details.

Use [features] in requirements.toml to pin runtime feature flags by the same canonical keys that config.toml uses. Requirements can also include documented app-only keys that don’t belong in config.toml. Omitted keys remain unconstrained.

Some managed requirements enforce an exact configuration value instead of an allowlist. Users can’t override an enforced path, update preference, login-shell policy, feedback setting, or Windows private-desktop setting.

Managed permission-profile allowlists require Codex 0.138.0 or later. Codex 0.137.0 and earlier ignore allowed_permission_profiles and managed default_permissions.

Use allowed_sandbox_modes with sandbox_mode. For permission-profile deployments, use allowed_permission_profiles with managed default_permissions.

The [models.new_thread] table supplies managed defaults, not enforcement. Explicit launch choices from dedicated CLI flags or --config overrides take precedence. An explicit model or reasoning-effort override skips both managed model fields; service_tier is independent.