URL: https://developers.openai.com/codex/config-schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"definitions": {
"AbsolutePathBuf": {
"description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
"type": "string"
},
"AgentRoleToml": {
"additionalProperties": false,
"properties": {
"config_file": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Path to a role-specific config layer. Relative paths are resolved relative to the `config.toml` that defines them."
},
"description": {
"description": "Human-facing role documentation used in spawn tool guidance. Required unless supplied by the referenced agent role file.",
"type": "string"
},
"nickname_candidates": {
"description": "Candidate nicknames for agents spawned with this role.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"AgentsToml": {
"additionalProperties": {
"$ref": "#/definitions/AgentRoleToml"
},
"properties": {
"interrupt_message": {
"description": "Whether to record a model-visible message when an agent turn is interrupted. Defaults to true.",
"type": "boolean"
},
"job_max_runtime_seconds": {
"description": "Default maximum runtime in seconds for agent job workers.",
"format": "uint64",
"minimum": 1.0,
"type": "integer"
},
"max_depth": {
"description": "Maximum nesting depth allowed for spawned agent threads. Root sessions start at depth 0.",
"format": "int32",
"minimum": 1.0,
"type": "integer"
},
"max_threads": {
"description": "Maximum number of agent threads that can be open concurrently. When unset, no limit is enforced.",
"format": "uint",
"minimum": 1.0,
"type": "integer"
}
},
"type": "object"
},
"AltScreenMode": {
"description": "Controls whether the TUI uses the terminal's alternate screen buffer.\n\n- `auto` (default): Use alternate screen mode. - `always`: Always use alternate screen mode. - `never`: Never use alternate screen mode. Runs in inline mode, preserving scrollback.\n\nThe CLI flag `--no-alt-screen` can override this setting at runtime.",
"oneOf": [
{
"description": "Use alternate screen mode.",
"enum": [
"auto"
],
"type": "string"
},
{
"description": "Always use alternate screen mode.",
"enum": [
"always"
],
"type": "string"
},
{
"description": "Never use alternate screen (inline mode only).",
"enum": [
"never"
],
"type": "string"
}
]
},
"AnalyticsConfigToml": {
"additionalProperties": false,
"description": "Analytics settings loaded from config.toml. Fields are optional so we can apply defaults.",
"properties": {
"enabled": {
"description": "When `false`, disables analytics across Codex product surfaces in this profile.",
"type": "boolean"
}
},
"type": "object"
},
"AppConfig": {
"additionalProperties": false,
"description": "Config values for a single app/connector.",
"properties": {
"approvals_reviewer": {
"allOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
}
],
"description": "Reviewer for approval prompts from this app, overriding the thread default."
},
"default_tools_approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"description": "Approval mode for tools in this app unless a tool override exists."
},
"default_tools_enabled": {
"description": "Whether tools are enabled by default for this app.",
"type": "boolean"
},
"destructive_enabled": {
"description": "Whether tools with `destructive_hint = true` are allowed for this app.",
"type": "boolean"
},
"enabled": {
"default": true,
"description": "When `false`, Codex does not surface this app.",
"type": "boolean"
},
"open_world_enabled": {
"description": "Whether tools with `open_world_hint = true` are allowed for this app.",
"type": "boolean"
},
"tools": {
"allOf": [
{
"$ref": "#/definitions/AppToolsConfig"
}
],
"description": "Per-tool settings for this app."
}
},
"type": "object"
},
"AppToolApproval": {
"enum": [
"auto",
"prompt",
"approve"
],
"type": "string"
},
"AppToolConfig": {
"additionalProperties": false,
"description": "Per-tool settings for a single app tool.",
"properties": {
"approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"description": "Approval mode for this tool."
},
"enabled": {
"description": "Whether this tool is enabled. `Some(true)` explicitly allows this tool.",
"type": "boolean"
}
},
"type": "object"
},
"AppToolsConfig": {
"additionalProperties": {
"$ref": "#/definitions/AppToolConfig"
},
"description": "Tool settings for a single app.",
"type": "object"
},
"ApprovalsReviewer": {
"description": "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
"enum": [
"user",
"auto_review",
"guardian_subagent"
],
"type": "string"
},
"AppsConfigToml": {
"additionalProperties": {
"$ref": "#/definitions/AppConfig"
},
"description": "App/connector settings loaded from `config.toml`.",
"properties": {
"_default": {
"allOf": [
{
"$ref": "#/definitions/AppsDefaultConfig"
}
],
"description": "Default settings for all apps."
}
},
"type": "object"
},
"AppsDefaultConfig": {
"additionalProperties": false,
"description": "Default settings that apply to all apps.",
"properties": {
"approvals_reviewer": {
"allOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
}
],
"description": "Reviewer for approval prompts unless overridden by per-app settings."
},
"destructive_enabled": {
"description": "Whether tools with `destructive_hint = true` are allowed by default.",
"type": "boolean"
},
"enabled": {
"default": true,
"description": "When `false`, apps are disabled unless overridden by per-app settings.",
"type": "boolean"
},
"open_world_enabled": {
"description": "Whether tools with `open_world_hint = true` are allowed by default.",
"type": "boolean"
}
},
"type": "object"
},
"AskForApproval": {
"description": "Determines the conditions under which the user is consulted to approve running the command proposed by Codex.",
"oneOf": [
{
"description": "Under this policy, only \"known safe\" commands—as determined by `is_safe_command()`—that **only read files** are auto‑approved. Everything else will ask the user to approve.",
"enum": [
"untrusted"
],
"type": "string"
},
{
"description": "DEPRECATED: *All* commands are auto‑approved, but they are expected to run inside a sandbox where network access is disabled and writes are confined to a specific set of paths. If the command fails, it will be escalated to the user to approve execution without a sandbox. Prefer `OnRequest` for interactive runs or `Never` for non-interactive runs.",
"enum": [
"on-failure"
],
"type": "string"
},
{
"description": "The model decides when to ask the user for approval.",
"enum": [
"on-request"
],
"type": "string"
},
{
"additionalProperties": false,
"description": "Fine-grained controls for individual approval flows.\n\nWhen a field is `true`, commands in that category are allowed. When it is `false`, those requests are automatically rejected instead of shown to the user.",
"properties": {
"granular": {
"$ref": "#/definitions/GranularApprovalConfig"
}
},
"required": [
"granular"
],
"type": "object"
},
{
"description": "Never ask the user to approve commands. Failures are immediately returned to the model, and never escalated to the user for approval.",
"enum": [
"never"
],
"type": "string"
}
]
},
"AuthCredentialsStoreMode": {
"description": "Determine where Codex should store CLI auth credentials.",
"oneOf": [
{
"description": "Persist credentials in CODEX_HOME/auth.json.",
"enum": [
"file"
],
"type": "string"
},
{
"description": "Persist credentials in the keyring. Fail if unavailable.",
"enum": [
"keyring"
],
"type": "string"
},
{
"description": "Use keyring when available; otherwise, fall back to a file in CODEX_HOME.",
"enum": [
"auto"
],
"type": "string"
},
{
"description": "Store credentials in memory only for the current process.",
"enum": [
"ephemeral"
],
"type": "string"
}
]
},
"AutoCompactTokenLimitScope": {
"description": "Selects which part of the active context is charged against `model_auto_compact_token_limit`.",
"oneOf": [
{
"description": "Count the full active context against the limit.",
"enum": [
"total"
],
"type": "string"
},
{
"description": "Count sampled output and later growth after the carried window prefix.",
"enum": [
"body_after_prefix"
],
"type": "string"
}
]
},
"AutoReviewToml": {
"properties": {
"policy": {
"description": "Additional policy instructions inserted into the guardian prompt.",
"type": "string"
}
},
"type": "object"
},
"BundledSkillsConfig": {
"additionalProperties": false,
"properties": {
"enabled": {
"default": true,
"type": "boolean"
}
},
"type": "object"
},
"CodeModeConfigToml": {
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"excluded_tool_namespaces": {
"description": "Exact tool namespaces to omit from the code-mode nested tool surface.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"ConfigProfile": {
"additionalProperties": false,
"description": "Collection of common configuration options that a user can define as a unit in `config.toml`.",
"properties": {
"analytics": {
"$ref": "#/definitions/AnalyticsConfigToml"
},
"approval_policy": {
"$ref": "#/definitions/AskForApproval"
},
"approvals_reviewer": {
"$ref": "#/definitions/ApprovalsReviewer"
},
"chatgpt_base_url": {
"type": "string"
},
"experimental_compact_prompt_file": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"experimental_use_unified_exec_tool": {
"type": "boolean"
},
"features": {
"additionalProperties": false,
"default": null,
"description": "Optional feature toggles scoped to this profile.",
"properties": {
"apply_patch_freeform": {
"type": "boolean"
},
"apply_patch_streaming_events": {
"type": "boolean"
},
"apps": {
"type": "boolean"
},
"apps_mcp_path_override": {
"anyOf": [
{
"type": "boolean"
},
{
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"path": {
"type": "string"
}
},
"type": "object"
}
]
},
"auth_elicitation": {
"type": "boolean"
},
"browser_use": {
"type": "boolean"
},
"browser_use_external": {
"type": "boolean"
},
"child_agents_md": {
"type": "boolean"
},
"chronicle": {
"type": "boolean"
},
"code_mode": {
"$ref": "#/definitions/FeatureToml_for_CodeModeConfigToml"
},
"code_mode_only": {
"type": "boolean"
},
"codex_git_commit": {
"type": "boolean"
},
"codex_hooks": {
"type": "boolean"
},
"collab": {
"type": "boolean"
},
"collaboration_modes": {
"type": "boolean"
},
"computer_use": {
"type": "boolean"
},
"connectors": {
"type": "boolean"
},
"default_mode_request_user_input": {
"type": "boolean"
},
"elevated_windows_sandbox": {
"type": "boolean"
},
"enable_experimental_windows_sandbox": {
"type": "boolean"
},
"enable_fanout": {
"type": "boolean"
},
"enable_mcp_apps": {
"type": "boolean"
},
"enable_request_compression": {
"type": "boolean"
},
"exec_permission_approvals": {
"type": "boolean"
},
"experimental_use_unified_exec_tool": {
"type": "boolean"
},
"experimental_windows_sandbox": {
"type": "boolean"
},
"external_migration": {
"type": "boolean"
},
"fast_mode": {
"type": "boolean"
},
"goals": {
"type": "boolean"
},
"guardian_approval": {
"type": "boolean"
},
"hooks": {
"type": "boolean"
},
"image_detail_original": {
"type": "boolean"
},
"image_generation": {
"type": "boolean"
},
"imagegenext": {
"type": "boolean"
},
"in_app_browser": {
"type": "boolean"
},
"js_repl": {
"type": "boolean"
},
"js_repl_tools_only": {
"type": "boolean"
},
"local_thread_store_compression": {
"type": "boolean"
},
"memories": {
"type": "boolean"
},
"memory_tool": {
"type": "boolean"
},
"mentions_v2": {
"type": "boolean"
},
"multi_agent": {
"type": "boolean"
},
"multi_agent_v2": {
"$ref": "#/definitions/FeatureToml_for_MultiAgentV2ConfigToml"
},
"network_proxy": {
"$ref": "#/definitions/FeatureToml_for_NetworkProxyConfigToml"
},
"non_prefixed_mcp_tool_names": {
"type": "boolean"
},
"personality": {
"type": "boolean"
},
"plugin_hooks": {
"type": "boolean"
},
"plugin_sharing": {
"type": "boolean"
},
"plugins": {
"type": "boolean"
},
"prevent_idle_sleep": {
"type": "boolean"
},
"realtime_conversation": {
"type": "boolean"
},
"remote_compaction_v2": {
"type": "boolean"
},
"remote_control": {
"type": "boolean"
},
"remote_models": {
"type": "boolean"
},
"remote_plugin": {
"type": "boolean"
},
"request_permissions": {
"type": "boolean"
},
"request_permissions_tool": {
"type": "boolean"
},
"request_rule": {
"type": "boolean"
},
"resize_all_images": {
"type": "boolean"
},
"responses_websockets": {
"type": "boolean"
},
"responses_websockets_v2": {
"type": "boolean"
},
"runtime_metrics": {
"type": "boolean"
},
"search_tool": {
"type": "boolean"
},
"secret_auth_storage": {
"type": "boolean"
},
"shell_snapshot": {
"type": "boolean"
},
"shell_tool": {
"type": "boolean"
},
"shell_zsh_fork": {
"type": "boolean"
},
"skill_env_var_dependency_prompt": {
"type": "boolean"
},
"skill_mcp_dependency_install": {
"type": "boolean"
},
"sleep_tool": {
"type": "boolean"
},
"sqlite": {
"type": "boolean"
},
"standalone_web_search": {
"type": "boolean"
},
"steer": {
"type": "boolean"
},
"telepathy": {
"type": "boolean"
},
"terminal_resize_reflow": {
"type": "boolean"
},
"terminal_visualization_instructions": {
"type": "boolean"
},
"token_budget": {
"type": "boolean"
},
"tool_call_mcp_elicitation": {
"type": "boolean"
},
"tool_search": {
"type": "boolean"
},
"tool_search_always_defer_mcp_tools": {
"type": "boolean"
},
"tool_suggest": {
"type": "boolean"
},
"tui_app_server": {
"type": "boolean"
},
"unavailable_dummy_tools": {
"type": "boolean"
},
"undo": {
"type": "boolean"
},
"unified_exec": {
"type": "boolean"
},
"unified_exec_zsh_fork": {
"type": "boolean"
},
"use_legacy_landlock": {
"type": "boolean"
},
"use_linux_sandbox_bwrap": {
"type": "boolean"
},
"web_search": {
"type": "boolean"
},
"web_search_cached": {
"type": "boolean"
},
"web_search_request": {
"type": "boolean"
},
"workspace_dependencies": {
"type": "boolean"
},
"workspace_owner_usage_nudge": {
"type": "boolean"
}
},
"type": "object"
},
"include_apps_instructions": {
"type": "boolean"
},
"include_collaboration_mode_instructions": {
"type": "boolean"
},
"include_environment_context": {
"type": "boolean"
},
"include_permissions_instructions": {
"type": "boolean"
},
"model": {
"type": "string"
},
"model_catalog_json": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Optional path to a JSON model catalog (applied on startup only)."
},
"model_instructions_file": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Optional path to a file containing model instructions."
},
"model_provider": {
"description": "The key in the `model_providers` map identifying the [`ModelProviderInfo`] to use.",
"type": "string"
},
"model_reasoning_effort": {
"$ref": "#/definitions/ReasoningEffort"
},
"model_reasoning_summary": {
"$ref": "#/definitions/ReasoningSummary"
},
"model_verbosity": {
"$ref": "#/definitions/Verbosity"
},
"oss_provider": {
"type": "string"
},
"personality": {
"$ref": "#/definitions/Personality"
},
"plan_mode_reasoning_effort": {
"$ref": "#/definitions/ReasoningEffort"
},
"sandbox_mode": {
"$ref": "#/definitions/SandboxMode"
},
"service_tier": {
"description": "Optional explicit service tier request id for new turns (for example `default`, `priority`, or `flex`; legacy `fast` also works).",
"type": "string"
},
"tools": {
"$ref": "#/definitions/ToolsToml"
},
"tui": {
"allOf": [
{
"$ref": "#/definitions/ProfileTui"
}
],
"default": null,
"description": "TUI settings scoped to this profile."
},
"web_search": {
"$ref": "#/definitions/WebSearchMode"
},
"windows": {
"allOf": [
{
"$ref": "#/definitions/WindowsToml"
}
],
"default": null
}
},
"type": "object"
},
"DebugConfigLockToml": {
"additionalProperties": false,
"properties": {
"allow_codex_version_mismatch": {
"description": "Allow replaying a lock generated by a different Codex version.",
"type": "boolean"
},
"export_dir": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Directory where Codex writes effective session config lock files."
},
"load_path": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Lockfile to replay as the authoritative effective config."
},
"save_fields_resolved_from_model_catalog": {
"description": "Save fields resolved from the model catalog/session configuration.",
"type": "boolean"
}
},
"type": "object"
},
"DebugToml": {
"additionalProperties": false,
"properties": {
"config_lockfile": {
"$ref": "#/definitions/DebugConfigLockToml"
}
},
"type": "object"
},
"ExperimentalRequestUserInput": {
"additionalProperties": false,
"properties": {
"enabled": {
"default": true,
"type": "boolean"
}
},
"type": "object"
},
"ExternalConfigMigrationPrompts": {
"additionalProperties": false,
"description": "Settings for notices we display to users via the tui and app-server clients (primarily the Codex IDE extension). NOTE: these are different from notifications - notices are warnings, NUX screens, acknowledgements, etc.",
"properties": {
"home": {
"description": "Tracks whether home-level external config migration prompts are hidden.",
"type": "boolean"
},
"home_last_prompted_at": {
"description": "Tracks the last time the home-level external config migration prompt was shown.",
"format": "int64",
"type": "integer"
},
"project_last_prompted_at": {
"additionalProperties": {
"format": "int64",
"type": "integer"
},
"default": {},
"description": "Tracks the last time a project-level external config migration prompt was shown.",
"type": "object"
},
"projects": {
"additionalProperties": {
"type": "boolean"
},
"default": {},
"description": "Tracks which project paths have opted out of external config migration prompts.",
"type": "object"
}
},
"type": "object"
},
"FeatureToml_for_CodeModeConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/CodeModeConfigToml"
}
]
},
"FeatureToml_for_MultiAgentV2ConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/MultiAgentV2ConfigToml"
}
]
},
"FeatureToml_for_NetworkProxyConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/NetworkProxyConfigToml"
}
]
},
"FeedbackConfigToml": {
"additionalProperties": false,
"properties": {
"enabled": {
"description": "When `false`, disables the feedback flow across Codex product surfaces.",
"type": "boolean"
}
},
"type": "object"
},
"FileSystemAccessMode": {
"description": "Access mode for a filesystem entry.\n\nWhen two equally specific entries target the same path, we compare these by conflict precedence rather than by capability breadth: `deny` beats `write`, and `write` beats `read`.",
"oneOf": [
{
"enum": [
"read",
"write"
],
"type": "string"
},
{
"description": "`none` is a legacy input alias retained temporarily for compatibility.",
"enum": [
"deny"
],
"type": "string"
}
]
},
"FilesystemPermissionToml": {
"anyOf": [
{
"$ref": "#/definitions/FileSystemAccessMode"
},
{
"additionalProperties": {
"$ref": "#/definitions/FileSystemAccessMode"
},
"type": "object"
}
]
},
"FilesystemPermissionsToml": {
"properties": {
"glob_scan_max_depth": {
"description": "Optional maximum depth for expanding unreadable glob patterns on platforms that snapshot glob matches before sandbox startup.",
"format": "uint",
"minimum": 1.0,
"type": "integer"
}
},
"type": "object"
},
"ForcedChatgptWorkspaceIds": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Backward-compatible shape for ChatGPT workspace login restrictions in config.toml."
},
"ForcedLoginMethod": {
"enum": [
"chatgpt",
"api"
],
"type": "string"
},
"GhostSnapshotToml": {
"additionalProperties": false,
"properties": {
"disable_warnings": {
"description": "Legacy no-op setting retained for compatibility.",
"type": "boolean"
},
"ignore_large_untracked_dirs": {
"description": "Legacy no-op setting retained for compatibility.",
"format": "int64",
"type": "integer"
},
"ignore_large_untracked_files": {
"description": "Legacy no-op setting retained for compatibility.",
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"GranularApprovalConfig": {
"properties": {
"mcp_elicitations": {
"description": "Whether to allow MCP elicitation prompts.",
"type": "boolean"
},
"request_permissions": {
"default": false,
"description": "Whether to allow prompts triggered by the `request_permissions` tool.",
"type": "boolean"
},
"rules": {
"description": "Whether to allow prompts triggered by execpolicy `prompt` rules.",
"type": "boolean"
},
"sandbox_approval": {
"description": "Whether to allow shell command approval requests, including inline `with_additional_permissions` and `require_escalated` requests.",
"type": "boolean"
},
"skill_approval": {
"default": false,
"description": "Whether to allow approval prompts triggered by skill script execution.",
"type": "boolean"
}
},
"required": [
"mcp_elicitations",
"rules",
"sandbox_approval"
],
"type": "object"
},
"History": {
"additionalProperties": false,
"description": "Settings that govern if and what will be written to `~/.codex/history.jsonl`.",
"properties": {
"max_bytes": {
"default": null,
"description": "If set, the maximum size of the history file in bytes. The oldest entries are dropped once the file exceeds this limit.",
"format": "uint",
"minimum": 0.0,
"type": "integer"
},
"persistence": {
"allOf": [
{
"$ref": "#/definitions/HistoryPersistence"
}
],
"default": "save-all",
"description": "If true, history entries will not be written to disk."
}
},
"type": "object"
},
"HistoryPersistence": {
"oneOf": [
{
"description": "Save all history entries to disk.",
"enum": [
"save-all"
],
"type": "string"
},
{
"description": "Do not write history to disk.",
"enum": [
"none"
],
"type": "string"
}
]
},
"HookHandlerConfig": {
"oneOf": [
{
"properties": {
"async": {
"default": false,
"type": "boolean"
},
"command": {
"type": "string"
},
"commandWindows": {
"default": null,
"type": "string"
},
"statusMessage": {
"default": null,
"type": "string"
},
"timeout": {
"default": null,
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"type": {
"enum": [
"command"
],
"type": "string"
}
},
"required": [
"command",
"type"
],
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"prompt"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"agent"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
}
]
},
"HookStateToml": {
"properties": {
"enabled": {
"type": "boolean"
},
"trusted_hash": {
"type": "string"
}
},
"type": "object"
},
"HooksToml": {
"properties": {
"PermissionRequest": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"PostCompact": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"PostToolUse": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"PreCompact": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"PreToolUse": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"SessionStart": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"Stop": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"SubagentStart": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"SubagentStop": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"UserPromptSubmit": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"state": {
"additionalProperties": {
"$ref": "#/definitions/HookStateToml"
},
"type": "object"
}
},
"type": "object"
},
"KeybindingsSpec": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "One action binding value in config.\n\nThis accepts either:\n\n1. A single key spec string (`\"ctrl-a\"`). 2. A list of key spec strings (`[\"ctrl-a\", \"alt-a\"]`).\n\nAn empty list explicitly unbinds the action in that scope. Because an explicit empty list is still a configured value, runtime resolution must not fall through to global or built-in defaults for that action."
},
"MarketplaceConfig": {
"additionalProperties": false,
"properties": {
"last_revision": {
"default": null,
"description": "Git revision Codex last successfully activated for this marketplace.",
"type": "string"
},
"last_updated": {
"default": null,
"description": "Last time Codex successfully added or refreshed this marketplace.",
"type": "string"
},
"ref": {
"default": null,
"description": "Git ref to check out when `source_type` is `git`.",
"type": "string"
},
"source": {
"default": null,
"description": "Source location used when the marketplace was added.",
"type": "string"
},
"source_type": {
"allOf": [
{
"$ref": "#/definitions/MarketplaceSourceType"
}
],
"default": null,
"description": "Source kind used to install this marketplace."
},
"sparse_paths": {
"default": null,
"description": "Sparse checkout paths used when `source_type` is `git`.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"MarketplaceSourceType": {
"enum": [
"git",
"local"
],
"type": "string"
},
"MatcherGroup": {
"properties": {
"hooks": {
"default": [],
"items": {
"$ref": "#/definitions/HookHandlerConfig"
},
"type": "array"
},
"matcher": {
"default": null,
"type": "string"
}
},
"type": "object"
},
"McpServerEnvVar": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"source": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
]
},
"McpServerOAuthConfig": {
"additionalProperties": false,
"description": "OAuth client settings used when Codex launches an MCP OAuth flow.",
"properties": {
"client_id": {
"description": "Explicit OAuth client identifier to present during authorization and token exchange.",
"type": "string"
}
},
"type": "object"
},
"McpServerToolConfig": {
"additionalProperties": false,
"description": "Per-tool approval settings for a single MCP server tool.",
"properties": {
"approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"description": "Approval mode for this tool."
}
},
"type": "object"
},
"MemoriesToml": {
"additionalProperties": false,
"description": "Memories settings loaded from config.toml.",
"properties": {
"consolidation_model": {
"description": "Model used for memory consolidation.",
"type": "string"
},
"dedicated_tools": {
"description": "When `true`, expose dedicated memory tools through the extension tool surface.",
"type": "boolean"
},
"disable_on_external_context": {
"description": "When `true`, external context sources mark the thread `memory_mode` as `\"polluted\"`.",
"type": "boolean"
},
"extract_model": {
"description": "Model used for thread summarisation.",
"type": "string"
},
"generate_memories": {
"description": "When `false`, newly created threads are stored with `memory_mode = \"disabled\"` in the state DB.",
"type": "boolean"
},
"max_raw_memories_for_consolidation": {
"description": "Maximum number of recent raw memories retained for global consolidation.",
"format": "uint",
"maximum": 4096.0,
"minimum": 1.0,
"type": "integer"
},
"max_rollout_age_days": {
"description": "Maximum age of the threads used for memories.",
"format": "int64",
"type": "integer"
},
"max_rollouts_per_startup": {
"description": "Maximum number of rollout candidates processed per pass.",
"format": "uint",
"maximum": 128.0,
"minimum": 1.0,
"type": "integer"
},
"max_unused_days": {
"description": "Maximum number of days since a memory was last used before it becomes ineligible for phase 2 selection.",
"format": "int64",
"type": "integer"
},
"min_rate_limit_remaining_percent": {
"description": "Minimum remaining percentage required in Codex rate-limit windows before memory startup runs.",
"format": "int64",
"maximum": 100.0,
"minimum": 0.0,
"type": "integer"
},
"min_rollout_idle_hours": {
"description": "Minimum idle time between last thread activity and memory creation (hours). > 12h recommended.",
"format": "int64",
"type": "integer"
},
"use_memories": {
"description": "When `false`, skip injecting memory usage instructions into developer prompts.",
"type": "boolean"
}
},
"type": "object"
},
"ModelAvailabilityNuxConfig": {
"additionalProperties": {
"format": "uint32",
"minimum": 0.0,
"type": "integer"
},
"type": "object"
},
"ModelProviderAuthInfo": {
"additionalProperties": false,
"description": "Configuration for obtaining a provider bearer token from a command.",
"properties": {
"args": {
"default": [],
"description": "Command arguments.",
"items": {
"type": "string"
},
"type": "array"
},
"command": {
"description": "Command to execute. Bare names are resolved via `PATH`; paths are resolved against `cwd`.",
"type": "string"
},
"cwd": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Working directory used when running the token command."
},
"refresh_interval_ms": {
"default": 300000,
"description": "Maximum age for the cached token before rerunning the command. Set to `0` to disable proactive refresh and only rerun after a 401 retry path.",
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"timeout_ms": {
"default": 5000,
"description": "Maximum time to wait for the token command to exit successfully.",
"format": "uint64",
"minimum": 1.0,
"type": "integer"
}
},
"required": [
"command"
],
"type": "object"
},
"ModelProviderAwsAuthInfo": {
"additionalProperties": false,
"description": "AWS SigV4 auth configuration for a model provider.",
"properties": {
"profile": {
"description": "AWS profile name to use. When unset, the AWS SDK default chain decides.",
"type": "string"
},
"region": {
"description": "AWS region to use for provider-specific endpoints.",
"type": "string"
}
},
"type": "object"
},
"ModelProviderInfo": {
"additionalProperties": false,
"description": "Serializable representation of a provider definition.",
"properties": {
"auth": {
"allOf": [
{
"$ref": "#/definitions/ModelProviderAuthInfo"
}
],
"description": "Command-backed bearer-token configuration for this provider."
},
"aws": {
"allOf": [
{
"$ref": "#/definitions/ModelProviderAwsAuthInfo"
}
],
"description": "AWS SigV4 auth configuration for this provider."
},
"base_url": {
"description": "Base URL for the provider's OpenAI-compatible API.",
"type": "string"
},
"env_http_headers": {
"additionalProperties": {
"type": "string"
},
"description": "Optional HTTP headers to include in requests to this provider where the (key, value) pairs are the header name and _environment variable_ whose value should be used. If the environment variable is not set, or the value is empty, the header will not be included in the request.",
"type": "object"
},
"env_key": {
"description": "Environment variable that stores the user's API key for this provider.",
"type": "string"
},
"env_key_instructions": {
"description": "Optional instructions to help the user get a valid value for the variable and set it.",
"type": "string"
},
"experimental_bearer_token": {
"description": "Value to use with `Authorization: Bearer
