Codex CLI Configuration

This skill explains how to view and modify Codex CLI settings stored in ~/.cursor/cli-config.json.

Config File Location

The config file is ~/.cursor/cli-config.json.

Projects can layer overrides via .cursor/cli.json files. The CLI walks from the git root to the current working directory and merges each .cursor/cli.json it finds (deeper files take precedence). Project overrides only affect the current session; they are not written back to the home config.

How to Modify

Read ~/.cursor/cli-config.json, apply changes, and write it back. The file is standard JSON. Changes take effect after restarting the CLI.

Available Settings

permissions (required)

Tool permission rules. Each entry is a string pattern.

• allow: string[] — patterns for allowed tool calls (e.g. "Shell(**)", "Mcp(server-name, tool-name)")
• deny: string[] — patterns for denied tool calls

editor

• vimMode: boolean — enable vim keybindings in the CLI input
• defaultBehavior: "ide" | "agent" — default behavior mode

display (optional)

• showLineNumbers: boolean (default: false) — show line numbers in code output
• showThinkingBlocks: boolean (default: false) — show model thinking/reasoning blocks
• showStatusIndicators: boolean (default: false) — show status indicators in the UI

channel (optional)

Release channel: "prod" | "lab" | "static"

maxMode (optional)

boolean (default: false) — enable max mode for higher-quality model responses

subagentModels (optional)

Per-subagent model settings.

• explore: "default" | "inherit" | "disabled" or { "modelId": string, "parameters"?: [{ "id": string, "value": string }], "maxMode"?: boolean } — use Codex's default Explore model, inherit the parent agent's model, disable the Explore subagent, or pin a specific model. When parameters is omitted, saved per-model parameter preferences apply; when maxMode is omitted, the parent conversation's max mode applies.

exploreSubagentModel (optional, legacy)

"default" | "inherit" (default: "default") — legacy Explore model setting. subagentModels.explore wins when both are set; keep this in sync ("inherit" when explore inherits, otherwise "default") so older CLI versions reading the same config behave sensibly.

approvalMode (optional)

Controls tool approval behavior:

• "allowlist" (default) — require approval for tools not in the allow list
• Run Everything — auto-approve all tool calls (same as --force / --yolo; set approval mode to the non-allowlist value)

sandbox (optional)

Sandbox execution environment settings:

• mode: "disabled" | "enabled" (default: "disabled")
• networkAccess: "user_config_only" | "user_config_with_defaults" | "allow_all" — controls network access from sandbox
• networkAllowlist: string[] — domains the sandbox is allowed to reach

network (optional)

• useHttp1ForAgent: boolean (default: false) — use HTTP/1.1 instead of HTTP/2 for agent connections (enables SSE-based streaming)

bedrock (optional)

AWS Bedrock integration settings:

• enabled: boolean (default: false)
• mode: "access-key" | "team-role" (default: "access-key")
• region: string — AWS region
• testModel: string — model to use for testing
• teamRoleArn: string — IAM role ARN for team mode
• teamExternalId: string — external ID for STS assume-role

attribution (optional)

Controls how agent work is attributed in git:

• attributeCommitsToAgent: boolean (default: true) — attribute commits to the agent
• attributePRsToAgent: boolean (default: true) — attribute PRs to the agent

webFetchDomainAllowlist (optional)

string[] — domains the web fetch tool is allowed to access (e.g. "docs.github.com", "*.example.com", "*")

Fields You Should NOT Modify

These are internal/cached state and should not be edited manually:

• version — config schema version
• model / selectedModel / modelParameters / hasChangedDefaultModel — managed by the model picker
• privacyCache — cached privacy mode state
• authInfo — cached authentication info
• showSandboxIntro — one-time UI flag
• conversationClassificationScoredConversations — internal cache