config-reference.md +231 −21
6 6
7User-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.7User-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.
8 8
9Project-scoped config can't override machine-local provider, auth,
10notification, profile, or telemetry routing keys. Codex ignores
11`openai_base_url`, `chatgpt_base_url`, `model_provider`, `model_providers`,
12`notify`, `profile`, `profiles`, `experimental_realtime_ws_base_url`, and
13`otel` when they appear in a project-local `.codex/config.toml`; put those in
14user-level config instead.
15
9For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).16For sandbox and approval keys (`approval_policy`, `sandbox_mode`, and `sandbox_workspace_write.*`), pair this reference with [Sandbox and approvals](https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/agent-approvals-security#network-access).
10 17
11<ConfigTable18<ConfigTable
224 },231 },
225 {232 {
226 key: "service_tier",233 key: "service_tier",
227234 type: "flex | fast", type: "string",
228235 description: "Preferred service tier for new turns.", description:
236 "Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored.",
229 },237 },
230 {238 {
231 key: "experimental_compact_prompt_file",239 key: "experimental_compact_prompt_file",
325 description: "Enable ChatGPT Apps/connectors support (experimental).",333 description: "Enable ChatGPT Apps/connectors support (experimental).",
326 },334 },
327 {335 {
328336 key: "features.codex_hooks", key: "features.hooks",
329 type: "boolean",337 type: "boolean",
330 description:338 description:
331339 "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config.", "Enable lifecycle hooks loaded from `hooks.json` or inline `[hooks]` config. `features.codex_hooks` is a deprecated alias.",
332 },340 },
333 {341 {
334 key: "features.codex_git_commit",342 key: "features.codex_git_commit",
342 description:350 description:
343 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",351 "Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events.",
344 },352 },
353 {
354 key: "features.plugin_hooks",
355 type: "boolean",
356 description:
357 "Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in.",
358 },
345 {359 {
346 key: "features.memories",360 key: "features.memories",
347 type: "boolean",361 type: "boolean",
434 description:448 description:
435 "Deny list applied after `enabled_tools` for the MCP server.",449 "Deny list applied after `enabled_tools` for the MCP server.",
436 },450 },
451 {
452 key: "mcp_servers.<id>.default_tools_approval_mode",
453 type: "auto | prompt | approve",
454 description:
455 "Default approval behavior for MCP tools on this server unless a per-tool override exists.",
456 },
457 {
458 key: "mcp_servers.<id>.tools.<tool>.approval_mode",
459 type: "auto | prompt | approve",
460 description:
461 "Per-tool approval behavior override for one MCP tool on this server.",
462 },
437 {463 {
438 key: "mcp_servers.<id>.scopes",464 key: "mcp_servers.<id>.scopes",
439 type: "array<string>",465 type: "array<string>",
581 description:607 description:
582 "Enable personality selection controls (stable; on by default).",608 "Enable personality selection controls (stable; on by default).",
583 },609 },
610 {
611 key: "features.network_proxy",
612 type: "boolean | table",
613 description:
614 "Enable sandboxed networking. Use a table form when setting network policy options such as `domains` (experimental; off by default).",
615 },
616 {
617 key: "features.network_proxy.enabled",
618 type: "boolean",
619 description: "Enable sandboxed networking. Defaults to `false`.",
620 },
621 {
622 key: "features.network_proxy.domains",
623 type: "map<string, allow | deny>",
624 description:
625 "Domain policy for sandboxed networking. Unset by default, which means no external destinations are allowed until you add `allow` rules. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules; prefer scoped rules because `*` broadly opens public outbound access. Add `deny` rules for blocked destinations; `deny` wins on conflicts.",
626 },
627 {
628 key: "features.network_proxy.unix_sockets",
629 type: "map<string, allow | none>",
630 description:
631 "Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets.",
632 },
633 {
634 key: "features.network_proxy.allow_local_binding",
635 type: "boolean",
636 description:
637 "Allow broader local/private-network access. Defaults to `false`; exact local IP literal or `localhost` allow rules can still permit specific local targets.",
638 },
639 {
640 key: "features.network_proxy.enable_socks5",
641 type: "boolean",
642 description: "Expose SOCKS5 support. Defaults to `true`.",
643 },
644 {
645 key: "features.network_proxy.enable_socks5_udp",
646 type: "boolean",
647 description: "Allow UDP over SOCKS5. Defaults to `true`.",
648 },
649 {
650 key: "features.network_proxy.allow_upstream_proxy",
651 type: "boolean",
652 description:
653 "Allow chaining through an upstream proxy from the environment. Defaults to `true`.",
654 },
655 {
656 key: "features.network_proxy.dangerously_allow_non_loopback_proxy",
657 type: "boolean",
658 description:
659 "Permit non-loopback listener addresses. Defaults to `false`; enabling it can expose proxy listeners beyond localhost.",
660 },
661 {
662 key: "features.network_proxy.dangerously_allow_all_unix_sockets",
663 type: "boolean",
664 description:
665 "Permit arbitrary Unix socket destinations instead of allowlist-only access. Defaults to `false`; use only in tightly controlled environments.",
666 },
667 {
668 key: "features.network_proxy.proxy_url",
669 type: "string",
670 description:
671 'HTTP listener URL for sandboxed networking. Defaults to `"http://127.0.0.1:3128"`.',
672 },
673 {
674 key: "features.network_proxy.socks_url",
675 type: "string",
676 description:
677 'SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`.',
678 },
584 {679 {
585 key: "features.web_search",680 key: "features.web_search",
586 type: "boolean",681 type: "boolean",
621 key: "features.fast_mode",716 key: "features.fast_mode",
622 type: "boolean",717 type: "boolean",
623 description:718 description:
624719 'Enable Fast mode selection and the `service_tier = "fast"` path (stable; on by default).', "Enable model-catalog service tier selection in the TUI, including Fast-tier commands when the active model advertises them (stable; on by default).",
625 },720 },
626 {721 {
627 key: "features.prevent_idle_sleep",722 key: "features.prevent_idle_sleep",
858 },953 },
859 {954 {
860 key: "profiles.<name>.service_tier",955 key: "profiles.<name>.service_tier",
861956 type: "flex | fast", type: "string",
862 description: "Profile-scoped service tier preference for new turns.",957 description: "Profile-scoped service tier preference for new turns.",
863 },958 },
864 {959 {
1072 description:1167 description:
1073 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",1168 "Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).",
1074 },1169 },
1170 {
1171 key: "tui.vim_mode_default",
1172 type: "boolean",
1173 description:
1174 "Start the composer in Vim normal mode instead of insert mode (default: false). You can still toggle it per session with `/vim`.",
1175 },
1176 {
1177 key: "tui.raw_output_mode",
1178 type: "boolean",
1179 description:
1180 "Start the TUI in raw scrollback mode for copy-friendly terminal selection (default: false). You can toggle it with `/raw` or the default `alt-r` key binding.",
1181 },
1075 {1182 {
1076 key: "tui.show_tooltips",1183 key: "tui.show_tooltips",
1077 type: "boolean",1184 type: "boolean",
1106 key: "tui.keymap.<context>.<action> = []",1213 key: "tui.keymap.<context>.<action> = []",
1107 type: "empty array",1214 type: "empty array",
1108 description:1215 description:
11091216 "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, or `page-down`.", "Unbind the action in that keymap context. Key names use normalized strings such as `ctrl-a`, `shift-enter`, `page-down`, or `minus`.",
1217 },
1218 {
1219 key: "plugins.<plugin>.mcp_servers.<server>.enabled",
1220 type: "boolean",
1221 description:
1222 "Enable or disable an MCP server bundled by an installed plugin without changing the plugin manifest.",
1223 },
1224 {
1225 key: "plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode",
1226 type: "auto | prompt | approve",
1227 description:
1228 "Default approval behavior for tools on a plugin-provided MCP server.",
1229 },
1230 {
1231 key: "plugins.<plugin>.mcp_servers.<server>.enabled_tools",
1232 type: "array<string>",
1233 description:
1234 "Allow list of tools exposed from a plugin-provided MCP server.",
1235 },
1236 {
1237 key: "plugins.<plugin>.mcp_servers.<server>.disabled_tools",
1238 type: "array<string>",
1239 description:
1240 "Deny list applied after `enabled_tools` for a plugin-provided MCP server.",
1241 },
1242 {
1243 key: "plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode",
1244 type: "auto | prompt | approve",
1245 description:
1246 "Per-tool approval behavior override for a plugin-provided MCP tool.",
1110 },1247 },
1111 {1248 {
1112 key: "tui.model_availability_nux.<model>",1249 key: "tui.model_availability_nux.<model>",
1225 key: "permissions.<name>.network.proxy_url",1362 key: "permissions.<name>.network.proxy_url",
1226 type: "string",1363 type: "string",
1227 description:1364 description:
12281365 "HTTP proxy endpoint used when this permissions profile enables the managed network proxy.", "HTTP listener URL used when this permissions profile enables sandboxed networking.",
1229 },1366 },
1230 {1367 {
1231 key: "permissions.<name>.network.enable_socks5",1368 key: "permissions.<name>.network.enable_socks5",
1232 type: "boolean",1369 type: "boolean",
1233 description:1370 description:
12341371 "Expose a SOCKS5 listener when this permissions profile enables the managed network proxy.", "Expose SOCKS5 support when this permissions profile enables sandboxed networking.",
1235 },1372 },
1236 {1373 {
1237 key: "permissions.<name>.network.socks_url",1374 key: "permissions.<name>.network.socks_url",
1247 key: "permissions.<name>.network.allow_upstream_proxy",1384 key: "permissions.<name>.network.allow_upstream_proxy",
1248 type: "boolean",1385 type: "boolean",
1249 description:1386 description:
12501387 "Allow the managed proxy to chain to another upstream proxy.", "Allow sandboxed networking to chain through another upstream proxy.",
1251 },1388 },
1252 {1389 {
1253 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",1390 key: "permissions.<name>.network.dangerously_allow_non_loopback_proxy",
1254 type: "boolean",1391 type: "boolean",
1255 description:1392 description:
12561393 "Permit non-loopback bind addresses for the managed proxy listener.", "Permit non-loopback bind addresses for sandboxed networking listeners. Enabling it can expose listeners beyond localhost.",
1257 },1394 },
1258 {1395 {
1259 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",1396 key: "permissions.<name>.network.dangerously_allow_all_unix_sockets",
1260 type: "boolean",1397 type: "boolean",
1261 description:1398 description:
12621399 "Allow the proxy to use arbitrary Unix sockets instead of the default restricted set.", "Allow arbitrary Unix socket destinations instead of the default restricted set. Use only in tightly controlled environments.",
1263 },
1264 {
1265 key: "permissions.<name>.network.mode",
1266 type: "limited | full",
1267 description: "Network proxy mode used for subprocess traffic.",
1268 },1400 },
1269 {1401 {
1270 key: "permissions.<name>.network.domains",1402 key: "permissions.<name>.network.domains",
1271 type: "map<string, allow | deny>",1403 type: "map<string, allow | deny>",
1272 description:1404 description:
12731405 "Domain rules for the managed proxy. Use domain names or wildcard patterns as keys, with `allow` or `deny` values.", "Domain rules for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules. `deny` wins on conflicts.",
1274 },1406 },
1275 {1407 {
1276 key: "permissions.<name>.network.unix_sockets",1408 key: "permissions.<name>.network.unix_sockets",
1277 type: "map<string, allow | none>",1409 type: "map<string, allow | none>",
1278 description:1410 description:
12791411 "Unix socket rules for the managed proxy. Use socket paths as keys, with `allow` or `none` values.", "Unix socket rules for sandboxed networking. Use socket paths as keys, with `allow` or `none` values.",
1280 },1412 },
1281 {1413 {
1282 key: "permissions.<name>.network.allow_local_binding",1414 key: "permissions.<name>.network.allow_local_binding",
1283 type: "boolean",1415 type: "boolean",
1284 description:1416 description:
12851417 "Permit local bind/listen operations through the managed proxy.", "Permit broader local/private-network access through sandboxed networking. Exact local IP literal or `localhost` allow rules can still permit specific local targets when this stays `false`.",
1286 },1418 },
1287 {1419 {
1288 key: "projects.<path>.trust_level",1420 key: "projects.<path>.trust_level",
1435 description:1567 description:
1436 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",1568 "Set to `false` in `requirements.toml` to disable Computer Use availability and related install or enablement flows.",
1437 },1569 },
1570 {
1571 key: "experimental_network",
1572 type: "table",
1573 description:
1574 "Network access requirements enforced from `requirements.toml`. These constraints are separate from `features.network_proxy` and can configure sandboxed networking without the user feature flag.",
1575 },
1576 {
1577 key: "experimental_network.enabled",
1578 type: "boolean",
1579 description:
1580 "Enable sandboxed networking requirements. This does not grant network access when the active sandbox keeps command networking off.",
1581 },
1582 {
1583 key: "experimental_network.http_port",
1584 type: "integer",
1585 description:
1586 "Loopback HTTP listener port to use for `[experimental_network]` requirements.",
1587 },
1588 {
1589 key: "experimental_network.socks_port",
1590 type: "integer",
1591 description:
1592 "Loopback SOCKS5 listener port to use for `[experimental_network]` requirements.",
1593 },
1594 {
1595 key: "experimental_network.allow_upstream_proxy",
1596 type: "boolean",
1597 description:
1598 "Allow sandboxed networking to chain through an upstream proxy from the environment.",
1599 },
1600 {
1601 key: "experimental_network.dangerously_allow_non_loopback_proxy",
1602 type: "boolean",
1603 description:
1604 "Permit non-loopback listener addresses for `[experimental_network]` requirements. Enabling it can expose listeners beyond localhost.",
1605 },
1606 {
1607 key: "experimental_network.dangerously_allow_all_unix_sockets",
1608 type: "boolean",
1609 description:
1610 "Permit arbitrary Unix socket destinations instead of allowlist-only access. Use only in tightly controlled environments.",
1611 },
1612 {
1613 key: "experimental_network.domains",
1614 type: "map<string, allow | deny>",
1615 description:
1616 "Map-shaped administrator domain policy for sandboxed networking. Supports exact hosts, `*.example.com` for subdomains only, `**.example.com` for apex plus subdomains, and global `*` allow rules; prefer scoped rules because `*` broadly opens public outbound access. `deny` wins on conflicts. Do not combine this with `experimental_network.allowed_domains` or `experimental_network.denied_domains`.",
1617 },
1618 {
1619 key: "experimental_network.allowed_domains",
1620 type: "array<string>",
1621 description:
1622 "List-shaped administrator allow rules for sandboxed networking. Do not combine this with `experimental_network.domains`.",
1623 },
1624 {
1625 key: "experimental_network.denied_domains",
1626 type: "array<string>",
1627 description:
1628 "List-shaped administrator deny rules for sandboxed networking. Do not combine this with `experimental_network.domains`.",
1629 },
1630 {
1631 key: "experimental_network.managed_allowed_domains_only",
1632 type: "boolean",
1633 description:
1634 "When `true`, only administrator-managed allow rules remain effective while sandboxed networking requirements are active; user allowlist additions are ignored. Without managed allow rules, user-added domain allow rules do not remain effective.",
1635 },
1636 {
1637 key: "experimental_network.unix_sockets",
1638 type: "map<string, allow | none>",
1639 description:
1640 "Administrator-managed Unix socket policy for sandboxed networking.",
1641 },
1642 {
1643 key: "experimental_network.allow_local_binding",
1644 type: "boolean",
1645 description:
1646 "Permit broader local/private-network access for sandboxed networking. Exact local IP literal or `localhost` allow rules can still permit specific local targets when this stays `false`.",
1647 },
1438 {1648 {
1439 key: "hooks",1649 key: "hooks",
1440 type: "table",1650 type: "table",
1457 key: "hooks.<Event>",1667 key: "hooks.<Event>",
1458 type: "array<table>",1668 type: "array<table>",
1459 description:1669 description:
14601670 "Matcher groups for a hook event such as `PreToolUse`, `PostToolUse`, `PermissionRequest`, `SessionStart`, `UserPromptSubmit`, or `Stop`.", "Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`.",
1461 },1671 },
1462 {1672 {
1463 key: "hooks.<Event>[].hooks",1673 key: "hooks.<Event>[].hooks",