高级配置

使用 these options 当 you need more control over providers, policies, 和 integrations。For a quick 启动, see Config basics .

For background on project guidance, reusable capabilities, custom slash commands, subagent workflows, 和 integrations, see Customization 。For configuration keys, see Configuration Reference .

Profiles let you save named configuration layers 和 切换 between them 从 the CLI。当 you pass --profile profile-name, Codex loads ~/.codex/config.toml, then overlays ~/.codex/profile-name.config.toml。Profile names can contain letters, numbers, hyphens, 和 underscores.

Create a separate TOML file for each profile。使用 top-level config keys in the profile file；don’t nest them under [profiles.profile-name].

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

Because the profile file is a layer above your base user config 和 below project 和 CLI config, it only needs the values that differ 从 your base config。Profile files can also override model_catalog_json；Codex uses the profile value 当 both files 设置 it.

In Codex 0.134.0 和 later, --profile no longer reads [profiles.profile-name] 从 config.toml, 和 the top-level profile = "profile-name" selector is no longer 支持的。Move legacy profile settings into ~/.codex/profile-name.config.toml, then 移除 the matching [profiles.profile-name] table 和 profile = "profile-name" selector 从 config.toml.

In addition 到 editing ~/.codex/config.toml, you can override configuration for a single 运行 从 the CLI:

Examples:

# Dedicated flag
codex --model gpt-5.4

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Notes:

Codex stores its local state under CODEX_HOME (默认s 到 ~/.codex).

Common files you may see there:

For authentication details (including credential storage modes), see Authentication 。For the full 列出 of configuration keys, see Configuration Reference .

For shared 默认s, rules, 和 skills checked into repos 或 system paths, see Team Config .

如果 you just need 到 point the built-in 打开AI provider at an LLM proxy, router, 或 data-residency enabled project, 设置 openai_base_url in config.toml 而不是 defining a 新的 provider。This changes the base URL for the built-in openai provider 不使用 requiring a separate model_providers.<id> entry.

openai_base_url = "https://us.api.openai.com/v1"

In addition 到 your user config, Codex reads project-scoped overrides 从 .codex/config.toml files inside your repo。Codex walks 从 the project root 到 your 当前 working directory 和 loads every .codex/config.toml it finds。如果 multiple files define the same key, the closest file 到 your working directory wins.

For security, Codex loads project-scoped config files only 当 the project is trusted。如果 the project is untrusted, Codex ignores project .codex/ layers, including .codex/config.toml, project-local hooks, 和 project-local rules。User 和 system layers remain separate 和 still load.

Relative paths inside a project config (例如, model_instructions_file) are resolved relative 到 the .codex/ folder that contains the config.toml.

Project config files can’t override settings that redirect credentials, alter host-owned app request metadata, change provider auth, 选择 config profiles, 或 运行 machine-local notification/telemetry commands。Codex ignores the following keys in project-local .codex/config.toml 和 prints a startup warning 当 it sees them：openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, 和 otel。设置 provider, notification, 和 telemetry keys in your user-level ~/.codex/config.toml；选择 config profiles 使用 --profile profile-name 和 ~/.codex/profile-name.config.toml.

Codex can also load lifecycle hooks 从 either hooks.json files 或 inline [hooks] tables in config.toml files that sit next 到 active config layers.

In practice, the four most useful locations are:

Project-local hooks load only 当 the project .codex/ layer is trusted。User-level hooks remain independent of project trust.

Inline TOML hooks 使用 the same event structure as hooks.json:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

如果 a single layer contains both hooks.json 和 inline [hooks], Codex loads both 和 warns。Prefer one representation per layer.

For the 当前 event 列出, input fields, output behavior, 和 limitations, see Hooks .

For subagent role configuration ([agents] in config.toml), see Subagents .

Codex discovers project configuration (例如, .codex/ layers 和 AGENTS.md) by walking up 从 working directory until it reaches a project root.

By 默认, Codex treats a directory containing .git as the project root. To customize this behavior, 设置 project_root_markers in config.toml:

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

设置 project_root_markers = [] 到 skip searching parent directories 和 treat the 当前 working directory as the project root.

A model provider defines how Codex connects 到 a model (base URL, wire API, authentication, 和 可选 HTTP headers)。Custom providers can’t reuse the reserved built-in provider IDs：openai, ollama, 和 lmstudio.

Define additional providers 和 point model_provider at them:

model = "gpt-5.4"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

添加 request headers 当 needed:

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

使用 command-backed authentication 当 a provider needs Codex 到 fetch bearer tokens 从 an external credential helper:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

The auth command receives no stdin 和 must 打印 the token 到 stdout。Codex trims surrounding whitespace, treats an empty token as an error, 和 refreshes proactively at refresh_interval_ms；设置 refresh_interval_ms = 0 到 refresh only 之后 an authentication retry。Don’t combine [model_providers.<id>.auth] 使用 env_key, experimental_bearer_token, 或 requires_openai_auth.

Codex includes a built-in amazon-bedrock model provider。设置 it directly as model_provider；unlike custom providers, this built-in provider supports only the nested AWS profile 和 region overrides.

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

如果 you omit profile, Codex uses the standard AWS credential chain。设置 region 到 the 支持的 Bedrock region that should handle requests.

For the full setup flow, authentication options, 支持的 models, 和 feature availability, see 使用 Codex 使用 Amazon Bedrock .

Codex can 运行 against a local “打开 source” provider (例如, Ollama 或 LM Studio) 当 you pass --oss。如果 you pass --oss 不使用 specifying a provider, Codex uses oss_provider as the 默认.

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

To change the base URL for the built-in 打开AI provider, 使用 openai_base_url；don’t create [model_providers.openai], because you can’t override built-in provider IDs.

Projects created 使用 data residency enabled can create a model provider 到 update the base_url 使用 the correct prefix .

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity applies only 到 providers using the Responses API。Chat Completions providers will ignore the setting.

Pick approval strictness (affects 当 Codex pauses) 和 sandbox level (affects file/network access).

For operational details 到 keep in mind while editing config.toml, see Common sandbox 和 approval combinations , Protected paths in writable roots , 和 Network access .

For beta permission profiles that 配置 filesystem 和 network access together, see Permissions .

You can also 使用 a granular approval policy (approval_policy = { granular = { ..。} }) 到 allow 或 auto-reject individual prompt categories。This is useful 当 you want normal interactive approvals for some cases but want others, such as request_permissions 或 skill-script prompts, 到 fail closed 自动.

设置 approvals_reviewer = "auto_review" 到 route eligible interactive approval requests through automatic 检查。This changes the reviewer, not the sandbox boundary.

使用 [auto_review].policy for local reviewer policy instructions。Managed guardian_policy_config takes precedence.

approval_policy = "untrusted"   # Other options: on-request, never, or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

[auto_review]
policy = """
Use your organization's automatic review policy.
"""

For built-in profiles, custom profile syntax, 和 the full filesystem 和 network configuration model, see Permissions .

For the complete key 列出 和 requirements constraints, see Configuration Reference 和 Managed configuration .

In workspace-write mode, some environments keep .git/ 和 .codex/ 读取-only even 当 the rest of workspace is writable。This is why commands like git commit may still require approval to run outside the sandbox. If you want Codex to skip specific commands (例如, block git commit outside the sandbox), 使用 rules .

Disable sandboxing entirely (使用 only 如果 your environment already isolates processes):

sandbox_mode = "danger-full-access"

shell_environment_policy controls which environment variables Codex passes 到 any subprocess it launches (例如, 当 running a tool-command the model proposes)。启动 从 a clean 启动 (inherit = "none") 或 a trimmed 设置 (inherit = "core"), then layer on excludes, includes, 和 overrides 到 avoid leaking secrets while still providing the paths, keys, 或 flags your tasks need.

[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_FLAG = "1" }
ignore_default_excludes = false
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME"]

Patterns are case-insensitive globs (*, ?, [A-Z])；ignore_默认_excludes = false keeps the automatic KEY/SECRET/TOKEN filter 之前 your includes/excludes 运行.

See the dedicated MCP documentation for configuration details.

Enable OpenTelemetry (OTel) log export 到 track Codex runs (API requests, SSE/events, prompts, tool approvals/results)。Disabled by 默认；opt in via [otel]:

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

选择 an exporter:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

如果 exporter = "none" Codex records events but sends nothing。Exporters batch asynchronously 和 flush on shutdown。Event metadata includes service name, CLI version, env tag, conversation id, model, sandbox/approval settings, 和 per-event fields (see Config Reference ).

Codex emits structured log events for runs 和 tool usage。Representative event types include:

当 the OTel metrics pipeline is enabled, Codex emits counters 和 duration histograms for API, stream, 和 tool activity.

Each metric below also includes 默认 metadata tags：auth_mode, originator, session_source, model, 和 app.version.

For more security 和 privacy guidance around telemetry, see Security .

By 默认, Codex periodically sends a small amount of anonymous usage 和 health data back 到 打开AI。This helps detect 当 Codex isn’t working correctly 和 shows what features 和 configuration options are being used, so the Codex team can focus on what matters most。These metrics don’t contain any personally identifiable information (PII)。Metrics collection is independent of OTel log/trace export.

如果 you want 到 disable metrics collection entirely across Codex surfaces on a machine, 设置 the analytics flag in your config:

[analytics]
enabled = false

Each metric includes its own fields plus the 默认 context fields below.

Each metric includes the 必需 fields plus the 默认 context fields above。Metric names below omit the codex。prefix。Most metric names are centralized in codex-rs/otel/src/metrics/names.rs；feature-specific metrics emitted outside that file are included here too。如果 a metric includes the tool field, it reflects the internal tool used (例如, apply_patch 或 shell) 和 doesn’t contain the actual shell command 或 patch codex is trying to apply.

The cloud_requirements.fetch_attempt metric includes trigger, attempt, outcome, 和 status_code fields。The cloud_requirements.fetch_final metric includes trigger, outcome, reason, attempt_count, 和 status_code fields.

The mcp.call 和 mcp.call.duration_ms metrics include status；normal tool-call emissions also include tool, plus connector_id 和 connector_name 当 可用。Blocked Codex Apps MCP calls may emit mcp.call 使用 only status.

The shell_snapshot metric includes success 和, on failures, failure_reason.

The external_agent_config.detect 和 external_agent_config.import metrics include migration_type；skills migrations also include skills_count.

The elevated setup failure metrics include code 和 message 当 Windows setup failure details are 可用, 和 may include originator 当 emitted 从 the shared setup path。The windows_sandbox.legacy_setup_preflight_failed metric includes originator 当 emitted 从 the shared setup path, but fallback-prompt preflight failures may not include any fields.

By 默认, Codex lets users send feedback 从 /feedback。To disable feedback collection across Codex surfaces on a machine, update your config:

[feedback]
enabled = false

当 disabled, /feedback shows a disabled message 和 Codex rejects feedback submissions.

如果 you want 到 reduce noisy “reasoning” output (例如 in CI logs), you can suppress it:

hide_agent_reasoning = true

如果 you want 到 surface raw reasoning content 当 a model emits it:

show_raw_agent_reasoning = true

Enable raw reasoning only 如果 it’s acceptable for your workflow。Some models/providers (like gpt-oss) don’t emit raw reasoning；in that case, this setting has no visible effect.

使用 notify 到 trigger an external program whenever Codex emits 支持的 events (currently only agent-turn-complete)。This is handy for desktop toasts, chat webhooks, CI updates, 或 any side-channel alerting that the built-in TUI notifications don’t cover.

notify = ["python3", "/path/to/notify.py"]

Example notify.py (truncated) that reacts 到 agent-turn-complete:

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

The script receives a single JSON argument。Common fields include:

Place the script somewhere on disk 和 point notify 到 it.

In auto mode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) 和 falls back 到 BEL (\x07) otherwise.

See Configuration Reference for the exact keys.

By 默认, Codex saves local session transcripts under CODEX_HOME (例如, ~/.codex/history.jsonl)。To disable local history 持久化ence:

[history]
persistence = "none"

To cap the history file size, 设置 history.max_bytes。当 file exceeds the cap, Codex drops the oldest entries 和 compacts file while keeping the newest records.

[history]
max_bytes = 104857600 # 100 MiB

如果 you 使用 a terminal/editor integration that supports it, Codex can render file citations as clickable links。配置 file_opener 到 pick the URI scheme Codex uses:

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

Example：a citation like /home/user/project/main.py:42 can be rewritten into a clickable vscode://file/...:42 link.

Codex reads AGENTS.md (和 related files) 和 includes a limited amount of project guidance in the first turn of a session。Two knobs control how this works:

For a detailed walkthrough, see Custom instructions 使用 AGENTS.md .

Running codex with no subcommand launches the interactive terminal UI (TUI)。Codex exposes some TUI-specific configuration under [tui], including:

tui.notification_method 默认s 到 auto。In auto mode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) 当 the terminal appears 到 support them, 和 falls back 到 BEL (\x07) otherwise.

See Configuration Reference for the full key 列出.