我靠！OpenAI 真 Open ！ 官方明确表示：支持使用第三方模型 国产模型的春天来了，正大光明的用！ 恭喜各位 @deepseek_ai @Zai_org @Alibaba_Qwen @XiaomiMiMo @MiniMax_AI @Kimi_Moonshot 传送门：https://developers.openai.com/codex/config-advanced#oss-mode-local-providers…

Advanced Configuration – Codex | OpenAI Developers

Source: https://developers.openai.com/codex/config-advanced Use these options when you need more control over providers, policies, and integrations. For a quick start, seeConfig basics.

For background on project guidance, reusable capabilities, custom slash commands, subagent workflows, and integrations, seeCustomization. For configuration keys, seeConfiguration Reference.

Profiles let you save named configuration layers and switch between them from the CLI. When you pass\-\-profile profile\-name, Codex loads~/\.codex/config\.toml, then overlays~/\.codex/profile\-name\.config\.toml. Profile names can contain letters, numbers, hyphens, and underscores.

Create a separate TOML file for each profile. Use 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 and below project and CLI config, it only needs the values that differ from your base config. Profile files can also overridemodel\_catalog\_json; Codex uses the profile value when both files set it.

In Codex 0.134.0 and later,\-\-profileno longer reads\[profiles\.profile\-name\]fromconfig\.toml, and the top-levelprofile = "profile\-name"selector is no longer supported. Move legacy profile settings into~/\.codex/profile\-name\.config\.toml, then remove the matching\[profiles\.profile\-name\]table andprofile = "profile\-name"selector fromconfig\.toml.

In addition to editing~/\.codex/config\.toml, you can override configuration for a single run from the CLI:

• Prefer dedicated flags when they exist (for example,\-\-model).
• Use\-c/\-\-configwhen you need to override an arbitrary key.

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:

• Keys can use dot notation to set nested values (for example,mcp\_servers\.context7\.enabled=false).
• \-\-configvalues are parsed as TOML. When in doubt, quote the value so your shell doesn’t split it on spaces.
• If the value can’t be parsed as TOML, Codex treats it as a string.

Codex stores its local state underCODEX\_HOME(defaults to~/\.codex).

Common files you may see there:

• config\.toml(your local configuration)
• auth\.json(if you use file-based credential storage) or your OS keychain/keyring
• history\.jsonl(if history persistence is enabled)
• Other per-user state such as logs and caches

For authentication details (including credential storage modes), seeAuthentication. For the full list of configuration keys, seeConfiguration Reference.

For shared defaults, rules, and skills checked into repos or system paths, seeTeam Config.

If you just need to point the built-in OpenAI provider at an LLM proxy, router, or data-residency enabled project, setopenai\_base\_urlinconfig\.tomlinstead of defining a new provider. This changes the base URL for the built-inopenaiprovider without requiring a separatemodel\_providers\.<id\>entry.

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

In addition to your user config, Codex reads project-scoped overrides from\.codex/config\.tomlfiles inside your repo. Codex walks from the project root to your current working directory and loads every\.codex/config\.tomlit finds. If multiple files define the same key, the closest file to your working directory wins.

For security, Codex loads project-scoped config files only when the project is trusted. If the project is untrusted, Codex ignores project\.codex/layers, including\.codex/config\.toml, project-local hooks, and project-local rules. User and system layers remain separate and still load.

Relative paths inside a project config (for example,model\_instructions\_file) are resolved relative to the\.codex/folder that contains theconfig\.toml.

Project config files can’t override settings that redirect credentials, alter host-owned app request metadata, change provider auth, select config profiles, or run machine-local notification/telemetry commands. Codex ignores the following keys in project-local\.codex/config\.tomland prints a startup warning when 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, andotel. Set provider, notification, and telemetry keys in your user-level~/\.codex/config\.toml; select config profiles with\-\-profile profile\-nameand~/\.codex/profile\-name\.config\.toml.

Codex can also load lifecycle hooks from eitherhooks\.jsonfiles or inline\[hooks\]tables inconfig\.tomlfiles that sit next to active config layers.

In practice, the four most useful locations are:

• ~/\.codex/hooks\.json
• ~/\.codex/config\.toml
• <repo\>/\.codex/hooks\.json
• <repo\>/\.codex/config\.toml

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

Inline TOML hooks use the same event structure ashooks\.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"

If a single layer contains bothhooks\.jsonand inline\[hooks\], Codex loads both and warns. Prefer one representation per layer.

For the current event list, input fields, output behavior, and limitations, seeHooks.

For subagent role configuration (\[agents\]inconfig\.toml), seeSubagents.

Codex discovers project configuration (for example,\.codex/layers andAGENTS\.md) by walking up from the working directory until it reaches a project root.

By default, Codex treats a directory containing\.gitas the project root. To customize this behavior, setproject\_root\_markersinconfig\.toml:

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

Setproject\_root\_markers = \[\]to skip searching parent directories and treat the current working directory as the project root.

A model provider defines how Codex connects to a model (base URL, wire API, authentication, and optional HTTP headers). Custom providers can’t reuse the reserved built-in provider IDs:openai,ollama, andlmstudio.

Define additional providers and pointmodel\_providerat 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"

Add request headers when needed:

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

Use command-backed authentication when a provider needs Codex to fetch bearer tokens from 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 nostdinand must print the token to stdout. Codex trims surrounding whitespace, treats an empty token as an error, and refreshes proactively atrefresh\_interval\_ms; setrefresh\_interval\_ms = 0to refresh only after an authentication retry. Don’t combine\[model\_providers\.<id\>\.auth\]withenv\_key,experimental\_bearer\_token, orrequires\_openai\_auth.

Amazon Bedrock provider

Codex includes a built-inamazon\-bedrockmodel provider. Set it directly asmodel\_provider; unlike custom providers, this built-in provider supports only the nested AWS profile and region overrides.

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

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

If you omitprofile, Codex uses the standard AWS credential chain. Setregionto the supported Bedrock region that should handle requests.

For the full setup flow, authentication options, supported models, and feature availability, seeUse Codex with Amazon Bedrock.

Codex can run against a local “open source” provider (for example, Ollama or LM Studio) when you pass\-\-oss. If you pass\-\-osswithout specifying a provider, Codex usesoss\_provideras the default.

# 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 OpenAI provider, useopenai\_base\_url; don’t create\[model\_providers\.openai\], because you can’t override built-in provider IDs.

Projects created withdata residencyenabled can create a model provider to update the base_url with thecorrect 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\_verbosityapplies only to providers using the Responses API. Chat Completions providers will ignore the setting.

Pick approval strictness (affects when Codex pauses) and sandbox level (affects file/network access).

For operational details to keep in mind while editingconfig\.toml, seeCommon sandbox and approval combinations,Protected paths in writable roots, andNetwork access.

For beta permission profiles that configure filesystem and network access together, seePermissions.

You can also use a granular approval policy (approval\_policy = \{ granular = \{ \.\.\. \} \}) to allow or auto-reject individual prompt categories. This is useful when you want normal interactive approvals for some cases but want others, such asrequest\_permissionsor skill-script prompts, to fail closed automatically.

Setapprovals\_reviewer = "auto\_review"to route eligible interactive approval requests through automatic review. This changes the reviewer, not the sandbox boundary.

Use\[auto\_review\]\.policyfor local reviewer policy instructions. Managedguardian\_policy\_configtakes 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.
"""

Named permission profiles

For built-in profiles, custom profile syntax, and the full filesystem and network configuration model, seePermissions.

For the complete key list and requirements constraints, seeConfiguration ReferenceandManaged configuration.

In workspace-write mode, some environments keep\.git/and\.codex/read-only even when the rest of the workspace is writable. This is why commands likegit commitmay still require approval to run outside the sandbox. If you want Codex to skip specific commands (for example, blockgit commitoutside the sandbox), userules.

Disable sandboxing entirely (use only if your environment already isolates processes):

sandbox_mode = "danger-full-access"

shell\_environment\_policycontrols which environment variables Codex passes to any subprocess it launches (for example, when running a tool-command the model proposes). Start from a clean start (inherit = "none") or a trimmed set (inherit = "core"), then layer on excludes, includes, and overrides to avoid leaking secrets while still providing the paths, keys, or 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\_default\_excludes = falsekeeps the automatic KEY/SECRET/TOKEN filter before your includes/excludes run.

See the dedicatedMCP documentationfor configuration details.

Enable OpenTelemetry (OTel) log export to track Codex runs (API requests, SSE/events, prompts, tool approvals/results). Disabled by default; 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

Choose 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" }
}}

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

What gets emitted

Codex emits structured log events for runs and tool usage. Representative event types include:

• codex\.conversation\_starts(model, reasoning settings, sandbox/approval policy)
• codex\.api\_request(attempt, status/success, duration, and error details)
• codex\.sse\_event(stream event kind, success/failure, duration, plus token counts onresponse\.completed)
• codex\.websocket\_requestandcodex\.websocket\_event(request duration plus per-message kind/success/error)
• codex\.user\_prompt(length; content redacted unless explicitly enabled)
• codex\.tool\_decision(approved/denied and whether the decision came from config vs user)
• codex\.tool\_result(duration, success, output snippet)

OTel metrics emitted

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

Each metric below also includes default metadata tags:auth\_mode,originator,session\_source,model, andapp\.version.

MetricTypeFieldsDescriptioncodex\.api\_requestcounterstatus,successAPI request count by HTTP status and success/failure.codex\.api\_request\.duration\_mshistogramstatus,successAPI request duration in milliseconds.codex\.sse\_eventcounterkind,successSSE event count by event kind and success/failure.codex\.sse\_event\.duration\_mshistogramkind,successSSE event processing duration in milliseconds.codex\.websocket\.requestcountersuccessWebSocket request count by success/failure.codex\.websocket\.request\.duration\_mshistogramsuccessWebSocket request duration in milliseconds.codex\.websocket\.eventcounterkind,successWebSocket message/event count by type and success/failure.codex\.websocket\.event\.duration\_mshistogramkind,successWebSocket message/event processing duration in milliseconds.codex\.tool\.callcountertool,successTool invocation count by tool name and success/failure.codex\.tool\.call\.duration\_mshistogramtool,successTool execution duration in milliseconds by tool name and outcome. For more security and privacy guidance around telemetry, seeSecurity.

Metrics

By default, Codex periodically sends a small amount of anonymous usage and health data back to OpenAI. This helps detect when Codex isn’t working correctly and shows what features and 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.

If you want to disable metrics collection entirely across Codex surfaces on a machine, set the analytics flag in your config:

[analytics]
enabled = false

Each metric includes its own fields plus the default context fields below.

Default context fields (applies to every event/metric)

• auth\_mode:swic|api|unknown.
• model: name of the model used.
• app\.version: Codex version.

Metrics catalog

Each metric includes the required fields plus the default context fields above. Metric names below omit thecodex\.prefix. Most metric names are centralized incodex\-rs/otel/src/metrics/names\.rs; feature-specific metrics emitted outside that file are included here too. If a metric includes thetoolfield, it reflects the internal tool used (for example,apply\_patchorshell) and doesn’t contain the actual shell command or patchcodexis trying to apply.

Runtime and model transport

MetricTypeFieldsDescriptionapi\_requestcounterstatus,successAPI request count by HTTP status and success/failure.api\_request\.duration\_mshistogramstatus,successAPI request duration in milliseconds.sse\_eventcounterkind,successSSE event count by event kind and success/failure.sse\_event\.duration\_mshistogramkind,successSSE event processing duration in milliseconds.websocket\.requestcountersuccessWebSocket request count by success/failure.websocket\.request\.duration\_mshistogramsuccessWebSocket request duration in milliseconds.websocket\.eventcounterkind,successWebSocket message/event count by type and success/failure.websocket\.event\.duration\_mshistogramkind,successWebSocket message/event processing duration in milliseconds.responses\_api\_overhead\.duration\_mshistogramResponses API overhead timing from WebSocket responses.responses\_api\_inference\_time\.duration\_mshistogramResponses API inference timing from WebSocket responses.responses\_api\_engine\_iapi\_ttft\.duration\_mshistogramResponses API engine IAPI time-to-first-token timing.responses\_api\_engine\_service\_ttft\.duration\_mshistogramResponses API engine service time-to-first-token timing.responses\_api\_engine\_iapi\_tbt\.duration\_mshistogramResponses API engine IAPI time-between-token timing.responses\_api\_engine\_service\_tbt\.duration\_mshistogramResponses API engine service time-between-token timing.transport\.fallback\_to\_httpcounterfrom\_wire\_apiWebSocket-to-HTTP fallback count.remote\_models\.fetch\_update\.duration\_mshistogramTime to fetch remote model definitions.remote\_models\.load\_cache\.duration\_mshistogramTime to load the remote model cache.startup\_prewarm\.duration\_mshistogramstatusStartup prewarm duration by outcome.startup\_prewarm\.age\_at\_first\_turn\_mshistogramstatusStartup prewarm age when the first real turn resolves it.cloud\_requirements\.fetch\.duration\_mshistogramWorkspace-managed cloud requirements fetch duration.cloud\_requirements\.fetch\_attemptcounterSee noteWorkspace-managed cloud requirements fetch attempts.cloud\_requirements\.fetch\_finalcounterSee noteFinal workspace-managed cloud requirements fetch outcome.cloud\_requirements\.loadcountertrigger,outcomeWorkspace-managed cloud requirements load outcome. Thecloud\_requirements\.fetch\_attemptmetric includestrigger,attempt,outcome, andstatus\_codefields. Thecloud\_requirements\.fetch\_finalmetric includestrigger,outcome,reason,attempt\_count, andstatus\_codefields.

Turn and tool activity

MetricTypeFieldsDescriptionturn\.e2e\_duration\_mshistogramEnd-to-end time for a full turn.turn\.ttft\.duration\_mshistogramTime to first token for a turn.turn\.ttfm\.duration\_mshistogramTime to first model output item for a turn.turn\.network\_proxycounteractive,tmp\_mem\_enabledWhether the managed network proxy was active for the turn.turn\.memorycounterread\_allowed,feature\_enabled,config\_use\_memories,has\_citationsPer-turn memory read availability and memory citation usage.turn\.tool\.callhistogramtmp\_mem\_enabledNumber of tool calls in the turn.turn\.token\_usagehistogramtoken\_type,tmp\_mem\_enabledPer-turn token usage by token type (total,input,cached\_input,output, orreasoning\_output).tool\.callcountertool,successTool invocation count by tool name and success/failure.tool\.call\.duration\_mshistogramtool,successTool execution duration in milliseconds by tool name and outcome.tool\.unified\_execcounterttyUnified exec tool calls by TTY mode.approval\.requestedcountertool,approvedTool approval request result (approved,approved\_with\_amendment,approved\_for\_session,denied,abort).mcp\.callcounterSee noteMCP tool invocation result.mcp\.call\.duration\_mshistogramSee noteMCP tool invocation duration.mcp\.tools\.list\.duration\_mshistogramcacheMCP tool-list duration, including cache hit/miss state.mcp\.tools\.fetch\_uncached\.duration\_mshistogramDuration of MCP tool fetches that miss the cache.mcp\.tools\.cache\_write\.duration\_mshistogramDuration of Codex Apps MCP tool-cache writes.hooks\.runcounterhook\_name,source,statusHook run count by hook name, source, and status.hooks\.run\.duration\_mshistogramhook\_name,source,statusHook run duration in milliseconds. Themcp\.callandmcp\.call\.duration\_msmetrics includestatus; normal tool-call emissions also includetool, plusconnector\_idandconnector\_namewhen available. Blocked Codex Apps MCP calls may emitmcp\.callwith onlystatus.

Threads, tasks, and features

MetricTypeFieldsDescriptionfeature\.statecounterfeature,valueFeature values that differ from defaults (emit one row per non-default).status\_linecounterSession started with a configured status line.model\_warningcounterWarning sent to the model.thread\.startedcounteris\_gitNew thread created, tagged by whether the working directory is in a Git repo.conversation\.turn\.countcounterUser/assistant turns per thread, recorded at the end of the thread.thread\.forkcountersourceNew thread created by forking an existing thread.thread\.renamecounterThread renamed.thread\.sidecountersourceSide conversation created.thread\.skills\.enabled\_totalhistogramNumber of skills enabled for a new thread.thread\.skills\.kept\_totalhistogramNumber of enabled skills kept after prompt rendering.thread\.skills\.truncatedhistogramWhether skill rendering truncated the enabled skills list (1or0).task\.compactcountertypeNumber of compactions per type (remoteorlocal), including manual and auto.task\.reviewcounterNumber of reviews triggered.task\.undocounterNumber of undo actions triggered.task\.user\_shellcounterNumber of user shell actions (\!in the TUI for example).shell\_snapshotcounterSee noteWhether taking a shell snapshot succeeded.shell\_snapshot\.duration\_mshistogramsuccessTime to take a shell snapshot.skill\.injectedcounterstatus,skillSkill injection outcomes by skill.plugins\.startup\_synccountertransport,statusCurated plugin startup sync attempts.plugins\.startup\_sync\.finalcountertransport,statusFinal curated plugin startup sync outcome.multi\_agent\.spawncounterroleAgent spawns by role.multi\_agent\.resumecounterAgent resumes.multi\_agent\.nickname\_pool\_resetcounterAgent nickname pool resets. Theshell\_snapshotmetric includessuccessand, on failures,failure\_reason.

Memory and local state

MetricTypeFieldsDescriptionmemory\.phase1counterstatusMemory phase 1 job counts by status.memory\.phase1\.e2e\_mshistogramEnd-to-end duration for memory phase 1.memory\.phase1\.outputcounterMemory phase 1 outputs written.memory\.phase1\.token\_usagehistogramtoken\_typeMemory phase 1 token usage by token type.memory\.phase2counterstatusMemory phase 2 job counts by status.memory\.phase2\.e2e\_mshistogramEnd-to-end duration for memory phase 2.memory\.phase2\.inputcounterMemory phase 2 input count.memory\.phase2\.token\_usagehistogramtoken\_typeMemory phase 2 token usage by token type.memories\.usagecounterkind,tool,successMemory usage by kind, tool, and success/failure.external\_agent\_config\.detectcounterSee noteExternal agent config detections by migration item type.external\_agent\_config\.importcounterSee noteExternal agent config imports by migration item type.db\.backfillcounterstatusInitial state DB backfill results (upserted,failed).db\.backfill\.duration\_mshistogramstatusDuration of the initial state DB backfill.db\.errorcounterstageErrors during state DB operations. Theexternal\_agent\_config\.detectandexternal\_agent\_config\.importmetrics includemigration\_type; skills migrations also includeskills\_count.

Windows sandbox

MetricTypeFieldsDescriptionwindows\_sandbox\.setup\_successcounteroriginator,modeWindows sandbox setup successes.windows\_sandbox\.setup\_failurecounteroriginator,modeWindows sandbox setup failures.windows\_sandbox\.setup\_duration\_mshistogramresult,originator,modeWindows sandbox setup duration.windows\_sandbox\.elevated\_setup\_successcounterElevated Windows sandbox setup successes.windows\_sandbox\.elevated\_setup\_failurecounterSee noteElevated Windows sandbox setup failures.windows\_sandbox\.elevated\_setup\_canceledcounterSee noteCanceled elevated Windows sandbox setup attempts.windows\_sandbox\.elevated\_setup\_duration\_mshistogramresultElevated Windows sandbox setup duration.windows\_sandbox\.elevated\_prompt\_showncounterElevated sandbox setup prompt shown.windows\_sandbox\.elevated\_prompt\_acceptcounterElevated sandbox setup prompt accepted.windows\_sandbox\.elevated\_prompt\_use\_legacycounterUser chose legacy sandbox from the elevated prompt.windows\_sandbox\.elevated\_prompt\_quitcounterUser quit from the elevated prompt.windows\_sandbox\.fallback\_prompt\_showncounterFallback sandbox prompt shown.windows\_sandbox\.fallback\_retry\_elevatedcounterUser retried elevated setup from the fallback prompt.windows\_sandbox\.fallback\_use\_legacycounterUser chose legacy sandbox from the fallback prompt.windows\_sandbox\.fallback\_prompt\_quitcounterUser quit from the fallback prompt.windows\_sandbox\.legacy\_setup\_preflight\_failedcounterSee noteLegacy Windows sandbox setup preflight failure.windows\_sandbox\.setup\_elevated\_sandbox\_commandcounterElevated sandbox setup command invoked.windows\_sandbox\.createprocessasuserw\_failedcountererror\_code,path\_kind,exe,levelWindowsCreateProcessAsUserWfailures. The elevated setup failure metrics includecodeandmessagewhen Windows setup failure details are available, and may includeoriginatorwhen emitted from the shared setup path. Thewindows\_sandbox\.legacy\_setup\_preflight\_failedmetric includesoriginatorwhen emitted from the shared setup path, but fallback-prompt preflight failures may not include any fields.

Feedback controls

By default, Codex lets users send feedback from/feedback. To disable feedback collection across Codex surfaces on a machine, update your config:

[feedback]
enabled = false

When disabled,/feedbackshows a disabled message and Codex rejects feedback submissions.

Hide or surface reasoning events

If you want to reduce noisy “reasoning” output (for example in CI logs), you can suppress it:

hide_agent_reasoning = true

If you want to surface raw reasoning content when a model emits it:

show_raw_agent_reasoning = true

Enable raw reasoning only if it’s acceptable for your workflow. Some models/providers (likegpt\-oss) don’t emit raw reasoning; in that case, this setting has no visible effect.

Usenotifyto trigger an external program whenever Codex emits supported events (currently onlyagent\-turn\-complete). This is handy for desktop toasts, chat webhooks, CI updates, or any side-channel alerting that the built-in TUI notifications don’t cover.

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

Examplenotify\.py(truncated) that reacts toagent\-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:

• type(currentlyagent\-turn\-complete)
• thread\-id(session identifier)
• turn\-id(turn identifier)
• cwd(working directory)
• input\-messages(user messages that led to the turn)
• last\-assistant\-message(last assistant message text)

Place the script somewhere on disk and pointnotifyto it.

notifyvstui\.notifications

• notifyruns an external program (good for webhooks, desktop notifiers, CI hooks).
• tui\.notificationsis built in to the TUI and can optionally filter by event type (for example,agent\-turn\-completeandapproval\-requested).
• tui\.notification\_methodcontrols how the TUI emits terminal notifications (auto,osc9, orbel).
• tui\.notification\_conditioncontrols whether TUI notifications fire only when the terminal isunfocusedoralways.

Inautomode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) and falls back to BEL (\\x07) otherwise.

SeeConfiguration Referencefor the exact keys.

History persistence

By default, Codex saves local session transcripts underCODEX\_HOME(for example,~/\.codex/history\.jsonl). To disable local history persistence:

[history]
persistence = "none"

To cap the history file size, sethistory\.max\_bytes. When the file exceeds the cap, Codex drops the oldest entries and compacts the file while keeping the newest records.

[history]
max_bytes = 104857600 # 100 MiB

If you use a terminal/editor integration that supports it, Codex can render file citations as clickable links. Configurefile\_openerto pick the URI scheme Codex uses:

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

Example: a citation like/home/user/project/main\.py:42can be rewritten into a clickablevscode://file/\.\.\.:42link.

Codex readsAGENTS\.md(and related files) and includes a limited amount of project guidance in the first turn of a session. Two knobs control how this works:

• project\_doc\_max\_bytes: how much to read from eachAGENTS\.mdfile
• project\_doc\_fallback\_filenames: additional filenames to try whenAGENTS\.mdis missing at a directory level

For a detailed walkthrough, seeCustom instructions with AGENTS.md.

Runningcodexwith no subcommand launches the interactive terminal UI (TUI). Codex exposes some TUI-specific configuration under\[tui\], including:

• tui\.notifications: enable/disable notifications (or restrict to specific types)
• tui\.notification\_method: chooseauto,osc9, orbelfor terminal notifications
• tui\.notification\_condition: chooseunfocusedoralwaysfor when notifications fire
• tui\.animations: enable/disable ASCII animations and shimmer effects
• tui\.alternate\_screen: control alternate screen usage (set toneverto keep terminal scrollback)
• tui\.show\_tooltips: show or hide onboarding tooltips on the welcome screen

tui\.notification\_methoddefaults toauto. Inautomode, Codex prefers OSC 9 notifications (a terminal escape sequence some terminals interpret as a desktop notification) when the terminal appears to support them, and falls back to BEL (\\x07) otherwise.

SeeConfiguration Referencefor the full key list.

Tibo (@thsottiaux): Reminder that you can use the Codex App, CLI and SDK with any open source model, not just with OpenAI models.