組態參考資料 | ChatGPT Learn

本頁提供可搜尋的 Codex 設定檔參考資料。如需概念說明和範例，請先參閱基本設定和進階設定。

`config.toml`

使用者層級組態儲存在 ~/.codex/config.toml。您也可以在 .codex/config.toml 檔案中加入專案範圍的覆寫設定。只有在您信任專案時，Codex 才會載入專案範圍的設定檔。

專案範圍的組態無法覆寫本機的提供者、身分驗證、由主機管理的應用程式請求中繼資料、通知、設定檔選擇或遙測路由設定鍵。如果 openai_base_url、 chatgpt_base_url、apps_mcp_product_sku、model_provider、 model_providers、notify、profile、profiles、 experimental_realtime_ws_base_url 和 otel 出現在專案內的 .codex/config.toml 中，Codex 會忽略這些設定；請改將提供者、通知和遙測設定鍵放在使用者層級組態中。設定檔與 config.toml 存放於同一目錄，路徑為 $CODEX_HOME/profile-name.config.toml；請使用 --profile profile-name 選取。

如需瞭解沙盒與核准設定鍵（approval_policy、sandbox_mode 和 sandbox_workspace_write.*），請搭配本參考資料查閱沙盒與核准、可寫入根目錄中的受保護路徑和網路存取。如需測試版權限設定檔的資訊，請參閱權限。

Key	Type / Values	Details
`agents`	`table`	多智慧體設定與自訂角色宣告。純量設定名稱屬於保留名稱，不能作為自訂角色名稱。
`agents.<name>.config_file`	`string (path)`	該角色的 TOML 組態層路徑；相對路徑會以宣告該角色的設定檔所在位置為基準解析。
`agents.<name>.description`	`string`	Codex 選擇並建立該類型智慧體時，向其顯示的角色指引。
`agents.default_subagent_model`	`string`	建立智慧體時使用的預設模型。若建立時明確指定模型，則以指定的模型為準。
`agents.default_subagent_reasoning_effort`	`string`	建立智慧體時使用的預設推理程度。若建立時明確指定推理程度，則以指定的程度為準。
`agents.enabled`	`boolean`	啟用或停用多智慧體工具（預設為 true）。
`agents.interrupt_message`	`boolean`	智慧體的輪次中斷時，記錄一則模型可見的訊息（預設為 true）。
`agents.max_concurrent_threads_per_session`	`number`	為智慧體建立的執行緒可同時保持開啟的數量上限，不包含主要執行緒。若未設定，Codex 會選擇預設值。
`agents.max_threads`	`number`	`agents.max_concurrent_threads_per_session` 的舊版別名。
`allow_login_shell`	`boolean`	允許以 Shell 為基礎的工具使用登入 Shell 語意。預設為 `true`；設為 `false` 時，會拒絕 `login = true` 請求，省略 `login` 時則預設使用非登入 Shell。
`analytics.enabled`	`boolean`	啟用或停用此電腦／設定檔的分析功能。未設定時，採用用戶端預設值。
`approval_policy`	`untrusted \| on-request \| never \| { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }`	控制 Codex 在執行指令前何時暫停並要求核准。您也可以使用 `approval_policy = { granular = { ... } }`，允許顯示或自動拒絕特定類別的提示，同時讓其他提示維持互動方式。`on-failure` 已棄用；互動式執行請使用 `on-request`，非互動式執行請使用 `never`。
`approval_policy.granular.mcp_elicitations`	`boolean`	設為 `true` 時，允許顯示 MCP 資訊請求提示，而不會自動拒絕。
`approval_policy.granular.request_permissions`	`boolean`	設為 `true` 時，允許顯示來自 `request_permissions` 工具的提示。
`approval_policy.granular.rules`	`boolean`	設為 `true` 時，允許顯示由 execpolicy `prompt` 規則觸發的核准提示。
`approval_policy.granular.sandbox_approval`	`boolean`	設為 `true` 時，允許顯示沙盒權限提升核准提示。
`approval_policy.granular.skill_approval`	`boolean`	設為 `true` 時，允許顯示技能指令碼核准提示。
`approvals_reviewer`	`user \| auto_review`	指定在 `on-request` 或細部核准政策下，由誰審查符合條件的核准提示。預設為 `user`；`auto_review` 會使用審查者子代理程式。此設定不會變更沙盒機制，也不會審查沙盒內已允許的操作。
`apps._default.approvals_reviewer`	`user \| auto_review`	應用程式工具核准提示的預設審查者，除非個別應用程式有覆寫設定。省略時，應用程式會繼承頂層的 `approvals_reviewer` 值。
`apps._default.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	未針對個別應用程式或工具設定覆寫時，應用程式工具的預設核准行為。
`apps._default.destructive_enabled`	`boolean`	設有 `destructive_hint = true` 的應用程式工具的預設允許／拒絕設定。
`apps._default.enabled`	`boolean`	所有應用程式的預設啟用狀態，除非個別應用程式有覆寫設定。
`apps._default.open_world_enabled`	`boolean`	設有 `open_world_hint = true` 的應用程式工具的預設允許／拒絕設定。
`apps.<id>.approvals_reviewer`	`user \| auto_review`	此應用程式工具核准提示的審查者。會覆寫 `apps._default.approvals_reviewer`。
`apps.<id>.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	此應用程式中工具的預設核准行為，除非個別工具有覆寫設定。
`apps.<id>.default_tools_enabled`	`boolean`	此應用程式中工具的預設啟用狀態，除非個別工具有覆寫設定。
`apps.<id>.destructive_enabled`	`boolean`	允許或封鎖此應用程式中宣告 `destructive_hint = true` 的工具。
`apps.<id>.enabled`	`boolean`	依 ID 啟用或停用特定應用程式／連接器（預設：true）。
`apps.<id>.open_world_enabled`	`boolean`	允許或封鎖此應用程式中宣告 `open_world_hint = true` 的工具。
`apps.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	針對單一應用程式工具的核准行為覆寫設定。
`apps.<id>.tools.<tool>.enabled`	`boolean`	針對個別應用程式工具的啟用狀態覆寫設定（例如 `repos/list`）。
`auto_review.policy`	`string`	用於自動審查的本機 Markdown 政策指示。受管理的 `guardian_policy_config` 優先。空白值會被忽略。
`background_terminal_max_timeout`	`number`	空白 `write_stdin` 輪詢（背景終端輪詢）的最長等待時間，以毫秒為單位。預設為 `300000`（5 分鐘）。取代舊的 `background_terminal_timeout` 鍵。
`chatgpt_base_url`	`string`	覆寫 ChatGPT 登入流程使用的基礎 URL。
`check_for_update_on_startup`	`boolean`	啟動時檢查是否有 Codex 更新（僅在集中管理更新時才設為 false）。
`cli_auth_credentials_store`	`file \| keyring \| auto`	控制 CLI 儲存快取認證資訊的位置（auth.json 檔案或作業系統鑰匙圈）。
`compact_prompt`	`string`	歷史記錄壓縮提示詞的內嵌覆寫設定。
`computer_use.windows.always_allowed_app_ids`	`array<string>`	「電腦」無須顯示提示即可開啟的 Windows 應用程式識別碼。不在清單中的應用程式需要核准；請從 ChatGPT 桌面版應用程式的「電腦」設定中移除已儲存的項目。
`default_permissions`	`string`	套用於沙盒工具呼叫的預設權限設定檔名稱。內建設定檔為 `:read-only`、`:workspace` 和 `:danger-full-access`；自訂設定檔名稱必須有相符的 `[permissions.<name>]` 資料表。不得與 `sandbox_mode` 或 `[sandbox_workspace_write]` 並用。
`desktop.custom_file_handlers.<id>`	`table`	僅限使用者層級。為 ChatGPT 桌面版應用程式定義額外的開啟方式目標。請參閱新增自訂檔案處理程式，瞭解相關範例與處理程式 ID 限制。
`desktop.custom_file_handlers.<id>.args`	`array<string>`	插入指令與檔案輸入之間的引數（預設：`[]`）。
`desktop.custom_file_handlers.<id>.command`	`string`	用於偵測與啟動的可執行檔路徑或指令名稱。必填。
`desktop.custom_file_handlers.<id>.icon`	`string`	處理程式圖示的隨附資源路徑、以 Base64 編碼的 `data:image/...` URL、檔案 URI 或本機絕對路徑。必填；不支援的來源會改用預設 VS Code 圖示。
`desktop.custom_file_handlers.<id>.input`	`path \| json_argument \| json_stdin`	應用程式將檔案輸入傳送至處理程式的方式（預設：`path`）。
`desktop.custom_file_handlers.<id>.label`	`string`	顯示在開啟方式選單中的名稱。必填。
`desktop.custom_file_handlers.<id>.supports_ssh`	`boolean`	針對 SSH 工作區中的檔案提供此處理程式（預設：`false`）。
`developer_instructions`	`string`	注入工作階段的額外開發人員指示（選用）。
`disable_paste_burst`	`boolean`	停用 TUI 對短時間大量貼上的偵測。
`experimental_compact_prompt_file`	`string (path)`	從檔案載入壓縮提示詞的覆寫設定（實驗性）。
`experimental_use_unified_exec_tool`	`boolean`	啟用統一執行功能的舊名稱；建議使用 `[features].unified_exec` 或 `codex --enable unified_exec`。
`features.apps`	`boolean`	啟用應用程式（連接器）整合（穩定；預設開啟）。應用程式和連接器的流量不受沙盒內指令所用的網路代理伺服器或其網域允許清單控制。
`features.code_mode.direct_only_tool_namespaces`	`array<string>`	程式碼模式只能透過直接工具呼叫使用這些工具命名空間。
`features.code_mode.enabled`	`boolean`	啟用程式碼模式的功能組態。此功能仍在開發中，預設關閉。
`features.code_mode.excluded_tool_namespaces`	`array<string>`	程式碼模式會從巢狀程式碼模式的工具指引中排除這些工具命名空間，也不會向執行器公開這些命名空間。
`features.enable_request_compression`	`boolean`	在支援的情況下，使用 zstd 壓縮串流請求主體（穩定功能；預設啟用）。
`features.fast_mode`	`boolean`	啟用 TUI 中由模型目錄提供的服務層級選擇功能；若目前使用的模型宣告支援快速層級指令，也會一併啟用（穩定功能；預設啟用）。
`features.goals`	`boolean`	啟用目標持久化與自動接續功能（穩定功能；預設啟用）。
`features.hooks`	`boolean`	啟用從 `hooks.json` 載入或在 `[hooks]` 組態中內嵌定義的生命週期掛勾。`features.codex_hooks` 是已棄用的別名。
`features.memories`	`boolean`	啟用記憶（預設關閉）。
`features.multi_agent`	`boolean`	啟用多智慧體協作工具（`spawn_agent`、`send_input`、`resume_agent`、`wait_agent` 和 `close_agent`）（穩定；預設啟用）。
`features.network_proxy`	`boolean \| table`	啟動沙盒指令使用的網路代理伺服器（實驗性功能；預設關閉）。除非由管理員管理的 `experimental_network` 要求已啟用並啟動代理伺服器，否則必須啟用此功能，才能強制執行權限設定檔的網域規則。設定 `domains` 等功能層級的政策選項時，請使用資料表形式。此功能不會篩選網頁搜尋、應用程式、MCP 或其他託管工具。
`features.network_proxy.allow_local_binding`	`boolean`	允許更廣泛的本機或私人網路存取。預設為 `false`；針對確切本機 IP 常值或 `localhost` 設定的允許規則，仍可允許存取特定本機目標。
`features.network_proxy.allow_upstream_proxy`	`boolean`	允許透過環境中設定的上游代理伺服器進行串接。預設為 `true`。
`features.network_proxy.dangerously_allow_all_unix_sockets`	`boolean`	允許存取任意 Unix 通訊端目的地，而非僅限允許清單中的目的地。預設為 `false`；僅限在嚴格受控的環境中使用。
`features.network_proxy.dangerously_allow_non_loopback_proxy`	`boolean`	允許監聽器使用非回送位址。預設為 `false`；啟用後，可能讓 localhost 以外的來源也能存取代理伺服器監聽器。
`features.network_proxy.domains`	`map<string, allow \| deny>`	沙盒網路的網域政策。預設未設定，因此在新增 `allow` 規則前，不允許存取任何外部目的地。支援精確主機比對、僅涵蓋子網域的 `.example.com`、涵蓋網域本身及其子網域的 `.example.com`，以及全域 `` 允許規則；建議使用限定範圍的規則，因為 `*` 會廣泛開放公用網路的對外存取。請為要封鎖的目的地新增 `deny` 規則；發生衝突時以 `deny` 為準。
`features.network_proxy.enable_socks5`	`boolean`	提供 SOCKS5 支援。預設為 `true`。
`features.network_proxy.enable_socks5_udp`	`boolean`	允許透過 SOCKS5 使用 UDP。預設為 `true`。
`features.network_proxy.enabled`	`boolean`	當指令的網路存取已啟用時，啟動沙盒指令的網路代理伺服器。預設為 `false`；代理伺服器關閉時，不會強制執行權限設定檔的網域規則。
`features.network_proxy.proxy_url`	`string`	沙盒網路使用的 HTTP 監聽器 URL。預設為 `"http://127.0.0.1:3128"`。
`features.network_proxy.socks_url`	`string`	SOCKS5 監聽器 URL。預設為 `"http://127.0.0.1:8081"`。
`features.network_proxy.unix_sockets`	`map<string, allow \| deny>`	沙盒網路的 Unix 通訊端政策。預設未設定；請為允許的通訊端新增 `allow` 項目。
`features.personality`	`boolean`	啟用個性選擇控制項（穩定功能；預設啟用）。
`features.prevent_idle_sleep`	`boolean`	回合執行期間，防止電腦進入睡眠（實驗性功能；預設關閉）。
`features.remote_plugin`	`boolean`	啟用遠端外掛程式目錄（穩定功能；預設啟用）。
`features.rollout_budget.enabled`	`boolean`	啟用推演預算追蹤。此功能仍在開發中，預設關閉。啟用後，必須設定 `features.rollout_budget.limit_tokens`。
`features.rollout_budget.limit_tokens`	`integer`	推演預算追蹤的 Token 上限，必須為正數。啟用推演預算時，必須設定此項。
`features.rollout_budget.prefill_token_weight`	`number`	推演預算計算中預填 Token 的乘數，必須為有限的非負數。預設為 `1.0`。
`features.rollout_budget.reminder_interval_tokens`	`integer`	推演預算提醒之間的 Token 間隔，必須為正數。預設為 `limit_tokens` 的 10%，且至少為 1 個 Token。
`features.rollout_budget.sampling_token_weight`	`number`	推演預算計算中取樣 Token 的乘數，必須為有限的非負數。預設為 `1.0`。
`features.shell_snapshot`	`boolean`	建立 shell 環境快照，以加快重複執行指令的速度（穩定；預設啟用）。
`features.shell_tool`	`boolean`	啟用用來執行指令的預設 `shell` 工具（穩定功能；預設啟用）。
`features.skill_mcp_dependency_install`	`boolean`	允許在技能缺少 MCP 相依套件時提示使用者並加以安裝（穩定功能；預設啟用）。
`features.unified_exec`	`boolean`	使用以 PTY 為後端的統一 exec 工具（穩定；除 Windows 外，預設啟用）。
`features.web_search`	`boolean`	已棄用的舊版切換設定；建議改用頂層 `web_search` 設定。
`features.web_search_cached`	`boolean`	已棄用的舊版切換設定。若未設定 `web_search`，true 會對應至 `web_search = "cached"`。
`features.web_search_request`	`boolean`	已棄用的舊版切換設定。若未設定 `web_search`，true 會對應至 `web_search = "live"`。
`feedback.enabled`	`boolean`	允許所有本機用戶端透過 `/feedback` 提交意見回饋（預設：true）。
`file_opener`	`vscode \| vscode-insiders \| windsurf \| cursor \| none`	用於開啟 Codex 輸出中引用內容的 URI 配置（預設：`vscode`）。
`forced_chatgpt_workspace_id`	`string (uuid)`	將 ChatGPT 登入限制於特定工作區識別碼。
`forced_login_method`	`chatgpt \| api`	將 Codex 限制為使用特定身分驗證方式。
`hide_agent_reasoning`	`boolean`	同時隱藏 TUI 和 `codex exec` 輸出中的推理事件。
`history.max_bytes`	`number`	設定後，會透過刪除最舊的項目，將歷史紀錄檔案大小限制在指定的位元組數內。
`history.persistence`	`save-all \| none`	控制 Codex 是否將工作階段記錄儲存至 history.jsonl。
`hooks`	`table`	在 `config.toml` 中內嵌設定的生命週期掛勾。使用與 `hooks.json` 相同的事件結構描述；如需範例和支援的事件，請參閱掛勾指南。
`hooks.<Event>`	`array<table>`	用於 `PreToolUse`、`PermissionRequest`、`PostToolUse`、`PreCompact`、`PostCompact`、`SessionStart`、`SessionEnd`、`SubagentStart`、`SubagentStop`、`UserPromptSubmit` 或 `Stop` 等掛勾事件的比對器群組。
`hooks.<Event>[].hooks`	`array<table>`	比對器群組的掛勾處理常式。支援指令掛勾和 MCP 工具掛勾；提示詞掛勾與智慧體掛勾的處理常式會經過剖析，但不會執行。
`hooks.<Event>[].hooks[].additionalContextLimit`	`integer`	每個處理常式適用的概略 Token 閾值；超過閾值時，會將過大的 `additionalContext` 儲存至磁碟，並向模型顯示較短的預覽。預設為 `2500`；設為 `0` 時，會將完整上下文直接傳給模型。請參閱過大的掛勾輸出。
`hooks.<Event>[].hooks[].async`	`boolean`	在背景執行指令掛勾，而不延遲觸發該掛勾的作業。預設為 `false`；`SessionEnd` 一律同步執行。請參閱在背景執行掛勾。
`hooks.<Event>[].hooks[].commandWindows`	`string`	覆寫指令掛勾的指令，僅適用於 Windows。也可使用 TOML 別名 `command_windows`。
`instructions`	`string`	保留供日後使用；建議優先使用 `model_instructions_file` 或 `AGENTS.md`。
`log_dir`	`string (path)`	Codex 寫入記錄檔的目錄；預設為 `$CODEX_HOME/log`。明確設定此值也會在該目錄中啟用需主動選用的純文字 TUI 記錄檔 `codex-tui.log`。
`mcp_oauth_callback_port`	`integer`	選用的全域固定連接埠，供 MCP OAuth 登入期間的本機 HTTP 回呼伺服器使用。伺服器專屬的 `oauth.callback_port` 設定優先。若兩者皆未設定，Codex 會繫結至作業系統選擇的臨時連接埠。
`mcp_oauth_callback_url`	`string`	MCP OAuth 登入的選用基礎回呼 URL，例如 devbox 入口 URL。若授權伺服器支援簽發者識別，新加入的預先註冊用戶端會直接使用此 URL，不做更動；未儲存回呼的既有用戶端則會附加伺服器專屬的回呼 ID。若不支援簽發者識別，任何預先註冊的 MCP 伺服器，只要其設定的回呼缺少必要的 ID，就會改用此 URL 並附加該 ID。回呼 URL 中的連接埠不會決定監聽器的連接埠。
`mcp_oauth_credentials_store`	`auto \| file \| keyring`	MCP OAuth 認證資訊的偏好儲存位置。
`mcp_servers.<id>.args`	`array<string>`	傳遞給 MCP stdio 伺服器指令的引數。
`mcp_servers.<id>.auth`	`oauth \| chatgpt`	MCP HTTP 伺服器的備援身分驗證方式，優先順序在已設定的 bearer Token 和授權標頭之後。`oauth`（預設）會在有可用憑證時使用已儲存的 MCP OAuth 憑證。`chatgpt` 會對受信任的第一方 ChatGPT 來源使用目前的 ChatGPT 工作階段，並以已儲存的 OAuth 憑證作為備援。如果所有憑證來源都無法提供憑證，兩種模式都能在未經身分驗證的情況下連線。
`mcp_servers.<id>.bearer_token_env_var`	`string`	提供 MCP HTTP 伺服器 bearer Token 的環境變數。
`mcp_servers.<id>.command`	`string`	用於啟動 MCP stdio 伺服器的指令。
`mcp_servers.<id>.cwd`	`string`	MCP stdio 伺服器程序的工作目錄。
`mcp_servers.<id>.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	此伺服器上 MCP 工具的預設核准行為；如有個別工具的覆寫設定，則以該設定為準。
`mcp_servers.<id>.disabled_tools`	`array<string>`	MCP 伺服器在 `enabled_tools` 之後套用的拒絕清單。
`mcp_servers.<id>.enabled`	`boolean`	停用 MCP 伺服器，但保留其組態。
`mcp_servers.<id>.enabled_tools`	`array<string>`	允許 MCP 伺服器公開的工具名稱清單。
`mcp_servers.<id>.env`	`map<string,string>`	轉送至 MCP stdio 伺服器的環境變數。
`mcp_servers.<id>.env_http_headers`	`map<string,string>`	供 MCP HTTP 伺服器使用、值由環境變數填入的 HTTP 標頭。
`mcp_servers.<id>.env_vars`	`array<string \| { name = string, source = "local" \| "remote" }>`	要額外加入 MCP stdio 伺服器允許清單的環境變數。字串項目預設使用 `source = "local"`；只有搭配以執行器為後端的遠端 stdio 時，才能使用 `source = "remote"`。
`mcp_servers.<id>.experimental_environment`	`local \| remote`	MCP 伺服器的實驗性執行位置設定。`remote` 會透過遠端執行器環境啟動 stdio 伺服器；尚未實作可串流 HTTP 伺服器的遠端執行位置功能。
`mcp_servers.<id>.http_headers`	`map<string,string>`	每個 MCP HTTP 請求中包含的靜態 HTTP 標頭。
`mcp_servers.<id>.oauth_resource`	`string`	MCP 登入時可選擇包含的 RFC 8707 OAuth 資源參數。
`mcp_servers.<id>.oauth.callback_port`	`integer`	此 MCP 伺服器的固定 OAuth 回呼接聽連接埠。覆寫 `mcp_oauth_callback_port`。若直接使用回送位址回呼，且 URL 明確指定連接埠，請將接聽連接埠設為相同值。
`mcp_servers.<id>.oauth.callback_url`	`string`	伺服器專屬的 OAuth 回呼。當支援簽發者識別，或 URL 已以該伺服器專屬的回呼 ID 結尾時，預先註冊的用戶端會沿用此回呼。否則，Codex 會使用附加了該 ID 的全域或預設回呼。沒有預先註冊 ID 的用戶端會在用戶端註冊期間使用此回呼。
`mcp_servers.<id>.oauth.client_id`	`string`	預先註冊的 OAuth 用戶端 ID，用於與此 MCP 伺服器進行授權及 Token 交換。
`mcp_servers.<id>.required`	`boolean`	設為 true 時，若這個已啟用的 MCP 伺服器無法初始化，啟動或恢復就會失敗。
`mcp_servers.<id>.scopes`	`array<string>`	向該 MCP 伺服器進行身分驗證時，要請求的 OAuth 授權範圍。
`mcp_servers.<id>.startup_timeout_ms`	`number`	以毫秒為單位的 `startup_timeout_sec` 別名。
`mcp_servers.<id>.startup_timeout_sec`	`number`	覆寫 MCP 伺服器預設的 10 秒啟動逾時設定。
`mcp_servers.<id>.tool_timeout_sec`	`number`	覆寫 MCP 伺服器每個工具預設的 60 秒逾時設定。
`mcp_servers.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	此伺服器上單一 MCP 工具的核准行為覆寫設定。
`mcp_servers.<id>.url`	`string`	MCP 可串流 HTTP 伺服器的端點。
`memories.consolidation_model`	`string`	全域記憶整併所用模型的覆寫設定（選填）。
`memories.disable_on_external_context`	`boolean`	設為 `true` 時，使用 MCP 工具呼叫、網頁搜尋或工具搜尋等外部上下文的執行緒，不會納入記憶生成。預設為 `false`。舊版別名：`memories.no_memories_if_mcp_or_web_search`。
`memories.extract_model`	`string`	個別執行緒記憶擷取所用模型的覆寫設定（選填）。
`memories.generate_memories`	`boolean`	設為 `false` 時，新建立的執行緒不會儲存為記憶生成的輸入資料。預設為 `true`。
`memories.max_raw_memories_for_consolidation`	`number`	為全域整併保留的近期原始記憶數量上限。預設為 `256`，上限為 `4096`。
`memories.max_rollout_age_days`	`number`	可納入記憶生成的執行緒存續時間上限。預設為 `30`，且會限制在 `0`-`90` 之間。
`memories.max_rollouts_per_startup`	`number`	每輪啟動作業處理的推演候選項數量上限。預設為 `16`，上限為 `128`。
`memories.max_unused_days`	`number`	記憶自上次使用後，仍可納入整併的最長天數。預設為 `30`，且會限制在 `0`-`365` 之間。
`memories.min_rate_limit_remaining_percent`	`number`	開始生成記憶前，Codex 速率限制視窗中所需的最低剩餘額度百分比。預設為 `25`，且會限制在 `0`-`100` 之間。
`memories.min_rollout_idle_hours`	`number`	執行緒在納入記憶生成考量前所需的最短閒置時間。預設為 `6`，且會限制在 `1`-`48` 之間。
`memories.use_memories`	`boolean`	設為 `false` 時，Codex 不會將現有記憶注入日後的工作階段。預設為 `true`。
`model`	`string`	要使用的模型（例如 `gpt-5.5`）。
`model_auto_compact_token_limit`	`number`	觸發自動壓縮歷史記錄的 Token 閾值（未設定時使用模型預設值）。
`model_auto_compact_token_limit_scope`	`total \| body_after_prefix`	控制自動壓縮閾值是計入目前的完整上下文（`total`，預設值），還是僅計入沿用的壓縮視窗前綴之後的增長量（`body_after_prefix`）。
`model_catalog_json`	`string (path)`	啟動時載入的 JSON 模型目錄路徑（選用）。所選的 `$CODEX_HOME/profile-name.config.toml` 設定檔可個別覆寫此路徑。
`model_context_window`	`number`	目前使用的模型可用的上下文視窗 Token 數量。
`model_instructions_file`	`string (path)`	用來取代內建指示，而不是使用 `AGENTS.md`。
`model_provider`	`string`	來自 `model_providers` 的提供者 ID（預設：`openai`）。
`model_providers.<id>`	`table`	自訂供應商定義。內建供應商 ID（`openai`、`ollama` 和 `lmstudio`）均為保留值，無法覆寫。
`model_providers.<id>.auth`	`table`	自訂供應商透過指令取得 Bearer Token 的組態。請勿與 `env_key`、`experimental_bearer_token` 或 `requires_openai_auth` 同時使用。
`model_providers.<id>.auth.args`	`array<string>`	傳給 Token 指令的引數。
`model_providers.<id>.auth.command`	`string`	Codex 需要 Bearer Token 時要執行的指令。該指令必須將 Token 輸出至 stdout。
`model_providers.<id>.auth.cwd`	`string (path)`	Token 指令的工作目錄。
`model_providers.<id>.auth.refresh_interval_ms`	`number`	Codex 主動更新 Token 的間隔，以毫秒為單位（預設：300000）。設為 `0` 時，僅在身分驗證重試後更新。
`model_providers.<id>.auth.timeout_ms`	`number`	Token 指令的最長執行時間，以毫秒為單位（預設：5000）。
`model_providers.<id>.base_url`	`string`	模型供應商的 API 基底 URL。
`model_providers.<id>.env_http_headers`	`map<string,string>`	當環境變數存在時，以其值填入的 HTTP 標頭。
`model_providers.<id>.env_key`	`string`	提供供應商 API 金鑰的環境變數。
`model_providers.<id>.env_key_instructions`	`string`	供應商 API 金鑰的設定指引（選用）。
`model_providers.<id>.experimental_bearer_token`	`string`	直接設定的供應商 Bearer Token（不建議使用；請改用 `env_key`）。
`model_providers.<id>.http_headers`	`map<string,string>`	新增至供應商請求的靜態 HTTP 標頭。
`model_providers.<id>.name`	`string`	自訂模型供應商的顯示名稱。
`model_providers.<id>.query_params`	`map<string,string>`	附加至供應商請求的額外查詢參數。
`model_providers.<id>.request_max_retries`	`number`	向供應商發出 HTTP 請求時的重試次數（預設：4）。
`model_providers.<id>.requires_openai_auth`	`boolean`	此供應商使用 OpenAI 身分驗證（預設為 false）。
`model_providers.<id>.stream_idle_timeout_ms`	`number`	SSE 串流的閒置逾時，以毫秒為單位（預設：300000）。
`model_providers.<id>.stream_max_retries`	`number`	SSE 串流中斷時的重試次數（預設：5）。
`model_providers.<id>.supports_standalone_web_search`	`boolean`	宣告支援相容的獨立網頁搜尋端點（預設：false）。獨立搜尋功能仍在開發中，且預設關閉；供應商相容並不代表此功能會自動啟用。
`model_providers.<id>.supports_websockets`	`boolean`	該供應商是否支援 Responses API 的 WebSocket 傳輸方式。
`model_providers.<id>.wire_api`	`responses`	供應商使用的通訊協定。唯一支援的值是 `responses`；若省略，預設也會使用此值。
`model_providers.amazon-bedrock.aws.profile`	`string`	內建 `amazon-bedrock` 供應商使用的 AWS 設定檔名稱。
`model_providers.amazon-bedrock.aws.region`	`string`	內建 `amazon-bedrock` 供應商使用的 AWS 區域。
`model_reasoning_effort`	`minimal \| low \| medium \| high \| xhigh`	調整受支援模型的推理投入程度（僅限 Responses API；對 `xhigh` 的支援依模型而定）。
`model_reasoning_summary`	`auto \| concise \| detailed \| none`	選擇推理摘要的詳細程度，或完全停用摘要。
`model_supports_reasoning_summaries`	`boolean`	強制 Codex 傳送或不傳送推理中繼資料。
`model_verbosity`	`low \| medium \| high`	GPT-5 Responses API 輸出詳細程度的覆寫設定（選用）；若未設定，會採用所選模型或預設組合的預設值。
`notice.hide_full_access_warning`	`boolean`	追蹤是否已確認完整存取權警告提示。
`notice.hide_gpt-5.1-codex-max_migration_prompt`	`boolean`	追蹤是否已確認 gpt-5.1-codex-max 遷移提示。
`notice.hide_gpt5_1_migration_prompt`	`boolean`	追蹤是否已確認 GPT-5.1 遷移提示。
`notice.hide_rate_limit_model_nudge`	`boolean`	追蹤是否已選擇不再顯示因速率限制而切換模型的提醒。
`notice.hide_world_writable_warning`	`boolean`	追蹤是否已確認關於 Windows 目錄對所有使用者開放寫入的警告。
`notice.model_migrations`	`map<string,string>`	以舊模型->新模型的對應關係，追蹤已確認的模型遷移。
`notify`	`array<string>`	發出通知時執行的指令；會接收來自 Codex 的 JSON 承載資料。
`openai_base_url`	`string`	內建 `openai` 模型提供者的基礎 URL 覆寫設定。
`oss_provider`	`lmstudio \| ollama`	使用 `--oss` 執行時採用的預設本機提供者（若未設定，預設會提示您選擇）。
`otel.environment`	`string`	套用至所發出 OpenTelemetry 事件的環境標記（預設：`dev`）。
`otel.exporter`	`none \| otlp-http \| otlp-grpc`	選擇 OpenTelemetry 匯出器，並提供相關的端點中繼資料。
`otel.exporter.<id>.endpoint`	`string`	OTEL 紀錄的匯出器端點。
`otel.exporter.<id>.headers`	`map<string,string>`	OTEL 匯出器請求中包含的靜態標頭。
`otel.exporter.<id>.protocol`	`binary \| json`	OTLP/HTTP 匯出器使用的通訊協定。
`otel.exporter.<id>.tls.ca-certificate`	`string`	OTEL 匯出器 TLS 使用的 CA 憑證路徑。
`otel.exporter.<id>.tls.client-certificate`	`string`	OTEL 匯出器 TLS 使用的用戶端憑證路徑。
`otel.exporter.<id>.tls.client-private-key`	`string`	OTEL 匯出器 TLS 使用的用戶端私密金鑰路徑。
`otel.log_user_prompt`	`boolean`	選擇將原始使用者提示詞隨 OpenTelemetry 紀錄一併匯出。
`otel.metrics_exporter`	`none \| statsig \| otlp-http \| otlp-grpc`	選擇 OpenTelemetry 指標匯出器（預設為 `statsig`）。
`otel.trace_exporter`	`none \| otlp-http \| otlp-grpc`	選擇 OpenTelemetry 追蹤匯出器，並提供相關的端點中繼資料。
`otel.trace_exporter.<id>.endpoint`	`string`	OTEL 紀錄的追蹤匯出器端點。
`otel.trace_exporter.<id>.headers`	`map<string,string>`	OTEL 追蹤匯出器請求中包含的靜態標頭。
`otel.trace_exporter.<id>.protocol`	`binary \| json`	OTLP/HTTP 追蹤匯出器使用的通訊協定。
`otel.trace_exporter.<id>.tls.ca-certificate`	`string`	OTEL 追蹤匯出器 TLS 使用的 CA 憑證路徑。
`otel.trace_exporter.<id>.tls.client-certificate`	`string`	OTEL 追蹤匯出器 TLS 使用的用戶端憑證路徑。
`otel.trace_exporter.<id>.tls.client-private-key`	`string`	OTEL 追蹤匯出器 TLS 使用的用戶端私密金鑰路徑。
`permissions.<name>.description`	`string`	此具名設定檔的易讀說明。設定檔不會透過 `extends` 繼承父設定檔的說明。
`permissions.<name>.extends`	`string`	選用的父設定檔，會先於此具名設定檔套用。可設為其他具名設定檔、`:read-only` 或 `:workspace`；不接受 `:danger-full-access`、未定義的父設定檔或循環繼承。
`permissions.<name>.filesystem`	`table`	具名檔案系統權限設定檔。每個索引鍵都是絕對路徑或特殊 Token，例如 `:minimal` 或 `:workspace_roots`。
`permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob>`	`"read" \| "write" \| "deny"`	以每個有效工作區根目錄為基準，限定檔案系統的存取範圍。使用 `"."` 表示根目錄本身；`"*/.env"` 等 glob 子路徑可使用 `"deny"` 拒絕讀取。
`permissions.<name>.filesystem.<path-or-glob>`	`"read" \| "write" \| "deny" \| table`	授予路徑、glob 模式或特殊 Token 所指定目標的直接存取權，或將巢狀項目的範圍限定在該根目錄下。使用 `"deny"` 拒絕讀取相符路徑。
`permissions.<name>.filesystem.glob_scan_max_depth`	`number`	在會於沙盒啟動前為相符項目建立快照的平台上，展開拒絕讀取 glob 模式的最大深度。若有設定，值必須至少為 `1`。
`permissions.<name>.network.allow_local_binding`	`boolean`	允許透過沙盒網路存取更廣泛的本機或私人網路。即使此設定維持 `false`，精確指定本機 IP 常值或 `localhost` 的允許規則，仍可允許存取特定本機目標。
`permissions.<name>.network.allow_upstream_proxy`	`boolean`	允許沙盒網路串接另一個上游代理伺服器。
`permissions.<name>.network.dangerously_allow_all_unix_sockets`	`boolean`	允許連線至任意 Unix 通訊端目的地，而不限於預設範圍。僅限在嚴格控管的環境中使用。
`permissions.<name>.network.dangerously_allow_non_loopback_proxy`	`boolean`	允許沙盒網路接聽器繫結至非回送位址。啟用後，可能讓 localhost 以外的位置也能存取接聽器。
`permissions.<name>.network.domains`	`table`	適用於沙盒內指令的網域規則。僅當 `features.network_proxy` 或已啟用、由管理員管理的網路要求啟動代理伺服器時，才會強制執行。支援精確指定的主機、`.example.com`、`.example.com` 和全域 `` 允許規則；`deny` 優先。不會限制網頁搜尋、應用程式或 MCP 伺服器。
`permissions.<name>.network.domains.<pattern>`	`allow \| deny`	允許或拒絕精確指定的主機，或 `.example.com`、`*.example.com` 等限定範圍的萬用字元模式。
`permissions.<name>.network.enable_socks5`	`boolean`	此權限設定檔啟用沙盒網路時，提供 SOCKS5 支援。
`permissions.<name>.network.enable_socks5_udp`	`boolean`	啟用後，允許透過 SOCKS5 接聽器傳送 UDP。
`permissions.<name>.network.enabled`	`boolean`	啟用此權限設定檔下指令的網路存取。這不會啟動網路代理伺服器。如果未啟用 `features.network_proxy`，也未啟用由管理員管理的網路要求，指令會直接存取網路，且設定檔的網域規則不會強制執行。
`permissions.<name>.network.mode`	`limited \| full`	子程序流量使用的網路代理伺服器模式。
`permissions.<name>.network.proxy_url`	`string`	此權限設定檔啟用沙盒網路時所使用的 HTTP 接聽器 URL。
`permissions.<name>.network.socks_url`	`string`	此權限設定檔使用的 SOCKS5 代理伺服器端點。
`permissions.<name>.network.unix_sockets`	`table`	沙盒網路的 Unix 通訊端允許清單覆寫設定。以通訊端路徑作為索引鍵；`allow` 會新增路徑，`deny` 則拒絕該路徑。
`permissions.<name>.network.unix_sockets.<path>`	`allow \| deny`	使用 `allow` 將 Unix 通訊端絕對路徑加入實際生效的允許清單，或使用 `deny` 拒絕該路徑。遭拒絕的項目不會納入實際生效的允許清單。
`permissions.<name>.workspace_roots`	`table`	由設定檔定義的工作區根目錄，會與工作階段執行時的工作區根目錄一同套用 `:workspace_roots` 檔案系統規則。
`permissions.<name>.workspace_roots.<path>`	`boolean`	設為 `true` 時，將路徑納入此設定檔的工作區根目錄集合。停用的項目不會生效。
`personality`	`none \| friendly \| pragmatic`	宣告支援 `supportsPersonality` 的模型所採用的預設溝通風格；可針對個別對話串或輪次覆寫，也可透過 `/personality` 覆寫。
`plan_mode_reasoning_effort`	`none \| minimal \| low \| medium \| high \| xhigh`	規劃模式專用的推理覆寫設定。若未設定，規劃模式會使用內建預設組合的預設值。
`plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	外掛程式提供的 MCP 伺服器上各項工具的預設核准行為。
`plugins.<plugin>.mcp_servers.<server>.disabled_tools`	`array<string>`	外掛程式提供的 MCP 伺服器的拒絕清單，會在 `enabled_tools` 之後套用。
`plugins.<plugin>.mcp_servers.<server>.enabled`	`boolean`	在不變更外掛程式資訊清單的情況下，啟用或停用已安裝外掛程式隨附的 MCP 伺服器。
`plugins.<plugin>.mcp_servers.<server>.enabled_tools`	`array<string>`	外掛程式提供的 MCP 伺服器所公開的工具允許清單。
`plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	針對外掛程式提供的 MCP 工具，個別覆寫核准行為。
`project_doc_fallback_filenames`	`array<string>`	找不到 `AGENTS.md` 時要嘗試的其他檔名。
`project_doc_max_bytes`	`number`	建立專案指示時，從 `AGENTS.md` 讀取的位元組數上限。
`project_root_markers`	`array<string>`	專案根目錄標記檔的檔名清單；搜尋上層目錄以尋找專案根目錄時使用。
`projects.<path>.trust_level`	`string`	將專案或工作樹標記為受信任或不受信任（`"trusted"` \| `"untrusted"`）。不受信任的專案會略過專案範圍的 `.codex/` 層，包括專案本機組態、掛勾和規則。
`review_model`	`string`	供 `/review` 使用的選用模型覆寫設定（預設為目前工作階段的模型）。
`sandbox_mode`	`read-only \| workspace-write \| danger-full-access`	指令執行期間檔案系統與網路存取的沙盒政策。
`sandbox_workspace_write.exclude_slash_tmp`	`boolean`	在 workspace-write 模式下，將 `/tmp` 排除在可寫入根目錄之外。
`sandbox_workspace_write.exclude_tmpdir_env_var`	`boolean`	在 workspace-write 模式下，將 `$TMPDIR` 排除在可寫入根目錄之外。
`sandbox_workspace_write.network_access`	`boolean`	允許 workspace-write 沙盒內的對外網路存取。
`sandbox_workspace_write.writable_roots`	`array<string>`	當 `sandbox_mode = "workspace-write"` 時，額外允許寫入的根目錄。
`service_tier`	`string`	新輪次的偏好服務層級。請使用 `fast` 或目前使用的模型宣告支援的其他層級；`fast` 對應至請求值 `priority`。
`shell_environment_policy.exclude`	`array<string>`	舊版環境變數排除模式。新組態請使用 `shell_environment_policy.filters`；請勿在同一層中同時使用這兩種形式。
`shell_environment_policy.experimental_use_profile`	`boolean`	啟動子程序時使用使用者的 shell 設定檔。
`shell_environment_policy.filters`	`map<string, include \| exclude>`	標準的環境變數模式篩選器，不區分大小寫。納入項目會建立允許清單，且無法還原已排除的值。明確指定的 `set` 值會在排除作業後套用。請勿在同一層中同時使用這些篩選器與舊版 `exclude` 或 `include_only` 陣列。
`shell_environment_policy.ignore_default_excludes`	`boolean`	在執行其他篩選器前，保留名稱中包含 KEY、SECRET 或 TOKEN 的變數（預設：true）。設為 false 可自動依機密相關名稱排除變數。
`shell_environment_policy.include_only`	`array<string>`	舊版環境變數模式允許清單。新組態請使用 `shell_environment_policy.filters`；請勿在同一層中同時使用這兩種形式。
`shell_environment_policy.inherit`	`all \| core \| none`	啟動子程序時的基準環境繼承方式。
`shell_environment_policy.set`	`map<string,string>`	在排除作業後注入明確指定的環境變數值；納入篩選器仍可將其移除。
`show_raw_agent_reasoning`	`boolean`	當使用中的模型輸出原始推理內容時，將其顯示。
`skills.config`	`array<object>`	儲存在 config.toml 中的各技能啟用狀態覆寫設定。
`skills.config.<index>.enabled`	`boolean`	啟用或停用所參照的技能。
`skills.config.<index>.path`	`string (path)`	包含 `SKILL.md` 的技能資料夾路徑。
`sqlite_home`	`string (path)`	Codex 儲存 SQLite 狀態資料庫的目錄；該資料庫供智慧體作業及其他可恢復的執行階段狀態使用。
`suppress_unstable_features_warning`	`boolean`	隱藏啟用開發中功能旗標時顯示的警告。
`tool_output_token_limit`	`number`	將個別工具／函式輸出儲存至歷史紀錄的 Token 預算。
`tool_suggest.disabled_tools`	`array<table>`	停用特定可探索連接器或外掛程式的建議。每個項目都使用 `type = "connector"` 或 `"plugin"`，並指定一個 `id`。
`tool_suggest.discoverables`	`array<table>`	允許針對其他可探索的連接器或外掛程式提供工具建議。每個項目都使用 `type = "connector"` 或 `"plugin"`，並指定一個 `id`。
`tools.view_image`	`boolean`	啟用本機圖像附件工具 `view_image`。
`tools.web_search`	`boolean \| { context_size = "low\|medium\|high", allowed_domains = [string], location = { country, region, city, timezone } }`	選用的網頁搜尋工具組態。物件形式可設定搜尋上下文大小、允許的搜尋網域，以及使用者的大致位置。這些搜尋網域篩選條件與沙盒指令的網路網域規則相互獨立，且不會限制連接器或 MCP 伺服器。
`tui`	`table`	TUI 專用選項，例如啟用內嵌桌面通知。
`tui.alternate_screen`	`auto \| always \| never`	控制 TUI 是否使用替代畫面（預設：auto；auto 在 Zellij 中會略過替代畫面，以保留回捲內容）。
`tui.animations`	`boolean`	啟用終端動畫（歡迎畫面、微光效果、旋轉指示器）（預設：true）。
`tui.keymap.<context>.<action>`	`string \| array<string>`	TUI 動作的鍵盤快速鍵繫結。支援的上下文包括 `global`、`chat`、`composer`、`editor`、`vim_normal`、`vim_operator`、`vim_text_object`、`pager`、`list` 和 `approval`。部分撰寫工具動作會使用相符的 `tui.keymap.global` 繫結作為備用；若支援特定上下文的繫結，則優先使用該繫結。
`tui.keymap.<context>.<action> = []`	`empty array`	解除該動作在此按鍵對應上下文中的繫結。按鍵名稱使用標準化字串，例如 `ctrl-a`、`shift-enter`、`page-down` 或 `minus`。
`tui.model_availability_nux.<model>`	`integer`	以模型 Slug 為鍵的啟動工具提示內部狀態。
`tui.notification_condition`	`unfocused \| always`	控制 TUI 通知是僅在終端未取得焦點時觸發，還是不論焦點狀態皆會觸發。預設為 `unfocused`。
`tui.notification_method`	`auto \| osc9 \| bel`	終端通知使用的方式（預設：auto）。
`tui.notifications`	`boolean \| array<string>`	啟用 TUI 通知，也可選擇限制為特定事件類型。
`tui.raw_output_mode`	`boolean`	以原始回捲模式啟動 TUI，方便選取並複製終端內容（預設：false）。可使用 `/raw` 或預設的 `alt-r` 按鍵繫結切換。
`tui.resume_cwd`	`current \| session`	恢復工作階段或為其建立分支時使用的工作目錄。若未設定，而目前目錄與工作階段所儲存的目錄不同，Codex 會要求你選擇。
`tui.show_tooltips`	`boolean`	在 TUI 歡迎畫面中顯示新手引導工具提示（預設：true）。
`tui.status_line`	`array<string> \| null`	TUI 底部狀態列項目識別碼的有序清單。`null` 會停用狀態列。
`tui.terminal_title`	`array<string> \| null`	終端視窗／分頁標題項目識別碼的有序清單。預設為 `["spinner", "project"]`；`null` 會停用標題更新。
`tui.theme`	`string`	語法醒目提示佈景主題的覆寫設定（佈景主題名稱採用 kebab-case 格式）。
`tui.vim_mode_default`	`boolean`	啟動撰寫工具時使用 Vim 一般模式，而非插入模式（預設：false）。仍可在每個工作階段使用 `/vim` 切換。
`web_search`	`disabled \| cached \| indexed \| live`	網頁搜尋模式（預設：`"cached"`；cached 使用由 OpenAI 維護的索引，不會存取外部網頁；indexed 僅允許經搜尋索引控管的外部存取；若使用 `--yolo` 或其他完整存取權沙盒設定，則預設為 `"live"`）。若要進行不受限制的即時擷取，請使用 `"live"`；若要移除此工具，請使用 `"disabled"`。
`windows_wsl_setup_acknowledged`	`boolean`	追蹤 Windows 新手引導的確認狀態（僅限 Windows）。
`windows.sandbox`	`unelevated \| elevated`	Codex 在 Windows 上原生執行時使用的 Windows 專用原生沙盒模式。
`windows.sandbox_private_desktop`	`boolean`	在 Windows 原生環境中，預設會在私有桌面上執行最終的沙盒子處理程序。只有在需要與舊版 `Winsta0\\Default` 行為相容時，才設為 `false`。

Key

agents

Type / Values

table

Details

多智慧體設定與自訂角色宣告。純量設定名稱屬於保留名稱，不能作為自訂角色名稱。

Key

agents.<name>.config_file

Type / Values

string (path)

Details

該角色的 TOML 組態層路徑；相對路徑會以宣告該角色的設定檔所在位置為基準解析。

Key

agents.<name>.description

Type / Values

string

Details

Codex 選擇並建立該類型智慧體時，向其顯示的角色指引。

Key

agents.default_subagent_model

Type / Values

string

Details

建立智慧體時使用的預設模型。若建立時明確指定模型，則以指定的模型為準。

Key

agents.default_subagent_reasoning_effort

Type / Values

string

Details

建立智慧體時使用的預設推理程度。若建立時明確指定推理程度，則以指定的程度為準。

Key

agents.enabled

Type / Values

boolean

Details

啟用或停用多智慧體工具（預設為 true）。

Key

agents.interrupt_message

Type / Values

boolean

Details

智慧體的輪次中斷時，記錄一則模型可見的訊息（預設為 true）。

Key

agents.max_concurrent_threads_per_session

Type / Values

number

Details

為智慧體建立的執行緒可同時保持開啟的數量上限，不包含主要執行緒。若未設定，Codex 會選擇預設值。

Key

agents.max_threads

Type / Values

number

Details

agents.max_concurrent_threads_per_session 的舊版別名。

Key

allow_login_shell

Type / Values

boolean

Details

允許以 Shell 為基礎的工具使用登入 Shell 語意。預設為 true；設為 false 時，會拒絕 login = true 請求，省略 login 時則預設使用非登入 Shell。

Key

analytics.enabled

Type / Values

boolean

Details

啟用或停用此電腦／設定檔的分析功能。未設定時，採用用戶端預設值。

Key

approval_policy

Type / Values

untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }

Details

控制 Codex 在執行指令前何時暫停並要求核准。您也可以使用 approval_policy = { granular = { ... } }，允許顯示或自動拒絕特定類別的提示，同時讓其他提示維持互動方式。on-failure 已棄用；互動式執行請使用 on-request，非互動式執行請使用 never。

Key

approval_policy.granular.mcp_elicitations

Type / Values

boolean

Details

設為 true 時，允許顯示 MCP 資訊請求提示，而不會自動拒絕。

Key

approval_policy.granular.request_permissions

Type / Values

boolean

Details

設為 true 時，允許顯示來自 request_permissions 工具的提示。

Key

approval_policy.granular.rules

Type / Values

boolean

Details

設為 true 時，允許顯示由 execpolicy prompt 規則觸發的核准提示。

Key

approval_policy.granular.sandbox_approval

Type / Values

boolean

Details

設為 true 時，允許顯示沙盒權限提升核准提示。

Key

approval_policy.granular.skill_approval

Type / Values

boolean

Details

設為 true 時，允許顯示技能指令碼核准提示。

Key

approvals_reviewer

Type / Values

user | auto_review

Details

指定在 on-request 或細部核准政策下，由誰審查符合條件的核准提示。預設為 user；auto_review 會使用審查者子代理程式。此設定不會變更沙盒機制，也不會審查沙盒內已允許的操作。

Key

apps._default.approvals_reviewer

Type / Values

user | auto_review

Details

應用程式工具核准提示的預設審查者，除非個別應用程式有覆寫設定。省略時，應用程式會繼承頂層的 approvals_reviewer 值。

Key

apps._default.default_tools_approval_mode

Type / Values

auto | prompt | writes | approve

Details

未針對個別應用程式或工具設定覆寫時，應用程式工具的預設核准行為。

Key

apps._default.destructive_enabled

Type / Values

boolean

Details

設有 destructive_hint = true 的應用程式工具的預設允許／拒絕設定。

Key

apps._default.enabled

Type / Values

boolean

Details

所有應用程式的預設啟用狀態，除非個別應用程式有覆寫設定。

Key

apps._default.open_world_enabled

Type / Values

boolean

Details

設有 open_world_hint = true 的應用程式工具的預設允許／拒絕設定。

Key

apps.<id>.approvals_reviewer

Type / Values

user | auto_review

Details

此應用程式工具核准提示的審查者。會覆寫 apps._default.approvals_reviewer。

Key

apps.<id>.default_tools_approval_mode

Type / Values

auto | prompt | writes | approve

Details

此應用程式中工具的預設核准行為，除非個別工具有覆寫設定。

Key

apps.<id>.default_tools_enabled

Type / Values

boolean

Details

此應用程式中工具的預設啟用狀態，除非個別工具有覆寫設定。

Key

apps.<id>.destructive_enabled

Type / Values

boolean

Details

允許或封鎖此應用程式中宣告 destructive_hint = true 的工具。

Key

apps.<id>.enabled

Type / Values

boolean

Details

依 ID 啟用或停用特定應用程式／連接器（預設：true）。

Key

apps.<id>.open_world_enabled

Type / Values

boolean

Details

允許或封鎖此應用程式中宣告 open_world_hint = true 的工具。

Key

apps.<id>.tools.<tool>.approval_mode

Type / Values

auto | prompt | writes | approve

Details

針對單一應用程式工具的核准行為覆寫設定。

Key

apps.<id>.tools.<tool>.enabled

Type / Values

boolean

Details

針對個別應用程式工具的啟用狀態覆寫設定（例如 repos/list）。

Key

auto_review.policy

Type / Values

string

Details

用於自動審查的本機 Markdown 政策指示。受管理的 guardian_policy_config 優先。空白值會被忽略。

Key

background_terminal_max_timeout

Type / Values

number

Details

空白 write_stdin 輪詢（背景終端輪詢）的最長等待時間，以毫秒為單位。預設為 300000（5 分鐘）。取代舊的 background_terminal_timeout 鍵。

Key

chatgpt_base_url

Type / Values

string

Details

覆寫 ChatGPT 登入流程使用的基礎 URL。

Key

check_for_update_on_startup

Type / Values

boolean

Details

啟動時檢查是否有 Codex 更新（僅在集中管理更新時才設為 false）。

Key

cli_auth_credentials_store

Type / Values

file | keyring | auto

Details

控制 CLI 儲存快取認證資訊的位置（auth.json 檔案或作業系統鑰匙圈）。

Key

compact_prompt

Type / Values

string

Details

歷史記錄壓縮提示詞的內嵌覆寫設定。

Key

computer_use.windows.always_allowed_app_ids

Type / Values

array<string>

Details

「電腦」無須顯示提示即可開啟的 Windows 應用程式識別碼。不在清單中的應用程式需要核准；請從 ChatGPT 桌面版應用程式的「電腦」設定中移除已儲存的項目。

Key

default_permissions

Type / Values

string

Details

套用於沙盒工具呼叫的預設權限設定檔名稱。內建設定檔為 :read-only、:workspace 和 :danger-full-access；自訂設定檔名稱必須有相符的 [permissions.<name>] 資料表。不得與 sandbox_mode 或 [sandbox_workspace_write] 並用。

Key

desktop.custom_file_handlers.<id>

Type / Values

table

Details

僅限使用者層級。為 ChatGPT 桌面版應用程式定義額外的 開啟方式 目標。請參閱新增自訂檔案處理程式，瞭解相關範例與處理程式 ID 限制。

Key

desktop.custom_file_handlers.<id>.args

Type / Values

array<string>

Details

插入指令與檔案輸入之間的引數（預設：[]）。

Key

desktop.custom_file_handlers.<id>.command

Type / Values

string

Details

用於偵測與啟動的可執行檔路徑或指令名稱。必填。

Key

desktop.custom_file_handlers.<id>.icon

Type / Values

string

Details

處理程式圖示的隨附資源路徑、以 Base64 編碼的 data:image/... URL、檔案 URI 或本機絕對路徑。必填；不支援的來源會改用預設 VS Code 圖示。

Key

desktop.custom_file_handlers.<id>.input

Type / Values

path | json_argument | json_stdin

Details

應用程式將檔案輸入傳送至處理程式的方式（預設：path）。

Key

desktop.custom_file_handlers.<id>.label

Type / Values

string

Details

顯示在 開啟方式 選單中的名稱。必填。

Key

desktop.custom_file_handlers.<id>.supports_ssh

Type / Values

boolean

Details

針對 SSH 工作區中的檔案提供此處理程式（預設：false）。

Key

developer_instructions

Type / Values

string

Details

注入工作階段的額外開發人員指示（選用）。

Key

disable_paste_burst

Type / Values

boolean

Details

停用 TUI 對短時間大量貼上的偵測。

Key

experimental_compact_prompt_file

Type / Values

string (path)

Details

從檔案載入壓縮提示詞的覆寫設定（實驗性）。

Key

experimental_use_unified_exec_tool

Type / Values

boolean

Details

啟用統一執行功能的舊名稱；建議使用 [features].unified_exec 或 codex --enable unified_exec。

Key

features.apps

Type / Values

boolean

Details

啟用應用程式（連接器）整合（穩定；預設開啟）。應用程式和連接器的流量不受沙盒內指令所用的網路代理伺服器或其網域允許清單控制。

Key

features.code_mode.direct_only_tool_namespaces

Type / Values

array<string>

Details

程式碼模式只能透過直接工具呼叫使用這些工具命名空間。

Key

features.code_mode.enabled

Type / Values

boolean

Details

啟用程式碼模式的功能組態。此功能仍在開發中，預設關閉。

Key

features.code_mode.excluded_tool_namespaces

Type / Values

array<string>

Details

程式碼模式會從巢狀程式碼模式的工具指引中排除這些工具命名空間，也不會向執行器公開這些命名空間。

Key

features.enable_request_compression

Type / Values

boolean

Details

在支援的情況下，使用 zstd 壓縮串流請求主體（穩定功能；預設啟用）。

Key

features.fast_mode

Type / Values

boolean

Details

啟用 TUI 中由模型目錄提供的服務層級選擇功能；若目前使用的模型宣告支援快速層級指令，也會一併啟用（穩定功能；預設啟用）。

Key

features.goals

Type / Values

boolean

Details

啟用目標持久化與自動接續功能（穩定功能；預設啟用）。

Key

features.hooks

Type / Values

boolean

Details

啟用從 hooks.json 載入或在 [hooks] 組態中內嵌定義的生命週期掛勾。features.codex_hooks 是已棄用的別名。

Key

features.memories

Type / Values

boolean

Details

啟用記憶（預設關閉）。

Key

features.multi_agent

Type / Values

boolean

Details

啟用多智慧體協作工具（spawn_agent、send_input、resume_agent、wait_agent 和 close_agent）（穩定；預設啟用）。

Key

features.network_proxy

Type / Values

boolean | table

Details

啟動沙盒指令使用的網路代理伺服器（實驗性功能；預設關閉）。除非由管理員管理的 experimental_network 要求已啟用並啟動代理伺服器，否則必須啟用此功能，才能強制執行權限設定檔的網域規則。設定 domains 等功能層級的政策選項時，請使用資料表形式。此功能不會篩選網頁搜尋、應用程式、MCP 或其他託管工具。

Key

features.network_proxy.allow_local_binding

Type / Values

boolean

Details

允許更廣泛的本機或私人網路存取。預設為 false；針對確切本機 IP 常值或 localhost 設定的允許規則，仍可允許存取特定本機目標。

Key

features.network_proxy.allow_upstream_proxy

Type / Values

boolean

Details

允許透過環境中設定的上游代理伺服器進行串接。預設為 true。

Key

features.network_proxy.dangerously_allow_all_unix_sockets

Type / Values

boolean

Details

允許存取任意 Unix 通訊端目的地，而非僅限允許清單中的目的地。預設為 false；僅限在嚴格受控的環境中使用。

Key

features.network_proxy.dangerously_allow_non_loopback_proxy

Type / Values

boolean

Details

允許監聽器使用非回送位址。預設為 false；啟用後，可能讓 localhost 以外的來源也能存取代理伺服器監聽器。

Key

features.network_proxy.domains

Type / Values

map<string, allow | deny>

Details

沙盒網路的網域政策。預設未設定，因此在新增 allow 規則前，不允許存取任何外部目的地。支援精確主機比對、僅涵蓋子網域的 *.example.com、涵蓋網域本身及其子網域的 **.example.com，以及全域 * 允許規則；建議使用限定範圍的規則，因為 * 會廣泛開放公用網路的對外存取。請為要封鎖的目的地新增 deny 規則；發生衝突時以 deny 為準。

Key

features.network_proxy.enable_socks5

Type / Values

boolean

Details

提供 SOCKS5 支援。預設為 true。

Key

features.network_proxy.enable_socks5_udp

Type / Values

boolean

Details

允許透過 SOCKS5 使用 UDP。預設為 true。

Key

features.network_proxy.enabled

Type / Values

boolean

Details

當指令的網路存取已啟用時，啟動沙盒指令的網路代理伺服器。預設為 false；代理伺服器關閉時，不會強制執行權限設定檔的網域規則。

Key

features.network_proxy.proxy_url

Type / Values

string

Details

沙盒網路使用的 HTTP 監聽器 URL。預設為 "http://127.0.0.1:3128"。

Key

features.network_proxy.socks_url

Type / Values

string

Details

SOCKS5 監聽器 URL。預設為 "http://127.0.0.1:8081"。

Key

features.network_proxy.unix_sockets

Type / Values

map<string, allow | deny>

Details

沙盒網路的 Unix 通訊端政策。預設未設定；請為允許的通訊端新增 allow 項目。

Key

features.personality

Type / Values

boolean

Details

啟用個性選擇控制項（穩定功能；預設啟用）。

Key

features.prevent_idle_sleep

Type / Values

boolean

Details

回合執行期間，防止電腦進入睡眠（實驗性功能；預設關閉）。

Key

features.remote_plugin

Type / Values

boolean

Details

啟用遠端外掛程式目錄（穩定功能；預設啟用）。

Key

features.rollout_budget.enabled

Type / Values

boolean

Details

啟用推演預算追蹤。此功能仍在開發中，預設關閉。啟用後，必須設定 features.rollout_budget.limit_tokens。

Key

features.rollout_budget.limit_tokens

Type / Values

integer

Details

推演預算追蹤的 Token 上限，必須為正數。啟用推演預算時，必須設定此項。

Key

features.rollout_budget.prefill_token_weight

Type / Values

number

Details

推演預算計算中預填 Token 的乘數，必須為有限的非負數。預設為 1.0。

Key

features.rollout_budget.reminder_interval_tokens

Type / Values

integer

Details

推演預算提醒之間的 Token 間隔，必須為正數。預設為 limit_tokens 的 10%，且至少為 1 個 Token。

Key

features.rollout_budget.sampling_token_weight

Type / Values

number

Details

推演預算計算中取樣 Token 的乘數，必須為有限的非負數。預設為 1.0。

Key

features.shell_snapshot

Type / Values

boolean

Details

建立 shell 環境快照，以加快重複執行指令的速度（穩定；預設啟用）。

Key

features.shell_tool

Type / Values

boolean

Details

啟用用來執行指令的預設 shell 工具（穩定功能；預設啟用）。

Key

features.skill_mcp_dependency_install

Type / Values

boolean

Details

允許在技能缺少 MCP 相依套件時提示使用者並加以安裝（穩定功能；預設啟用）。

Key

features.unified_exec

Type / Values

boolean

Details

使用以 PTY 為後端的統一 exec 工具（穩定；除 Windows 外，預設啟用）。

Key

features.web_search

Type / Values

boolean

Details

已棄用的舊版切換設定；建議改用頂層 web_search 設定。

Key

features.web_search_cached

Type / Values

boolean

Details

已棄用的舊版切換設定。若未設定 web_search，true 會對應至 web_search = "cached"。

Key

features.web_search_request

Type / Values

boolean

Details

已棄用的舊版切換設定。若未設定 web_search，true 會對應至 web_search = "live"。

Key

feedback.enabled

Type / Values

boolean

Details

允許所有本機用戶端透過 /feedback 提交意見回饋（預設：true）。

Key

file_opener

Type / Values

vscode | vscode-insiders | windsurf | cursor | none

Details

用於開啟 Codex 輸出中引用內容的 URI 配置（預設：vscode）。

Key

forced_chatgpt_workspace_id

Type / Values

string (uuid)

Details

將 ChatGPT 登入限制於特定工作區識別碼。

Key

forced_login_method

Type / Values

chatgpt | api

Details

將 Codex 限制為使用特定身分驗證方式。

Key

hide_agent_reasoning

Type / Values

boolean

Details

同時隱藏 TUI 和 codex exec 輸出中的推理事件。

Key

history.max_bytes

Type / Values

number

Details

設定後，會透過刪除最舊的項目，將歷史紀錄檔案大小限制在指定的位元組數內。

Key

history.persistence

Type / Values

save-all | none

Details

控制 Codex 是否將工作階段記錄儲存至 history.jsonl。

Key

hooks

Type / Values

table

Details

在 config.toml 中內嵌設定的生命週期掛勾。使用與 hooks.json 相同的事件結構描述；如需範例和支援的事件，請參閱掛勾指南。

Key

hooks.<Event>

Type / Values

array<table>

Details

用於 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SessionEnd、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop 等掛勾事件的比對器群組。

Key

hooks.<Event>[].hooks

Type / Values

array<table>

Details

比對器群組的掛勾處理常式。支援指令掛勾和 MCP 工具掛勾；提示詞掛勾與智慧體掛勾的處理常式會經過剖析，但不會執行。

Key

hooks.<Event>[].hooks[].additionalContextLimit

Type / Values

integer

Details

每個處理常式適用的概略 Token 閾值；超過閾值時，會將過大的 additionalContext 儲存至磁碟，並向模型顯示較短的預覽。預設為 2500；設為 0 時，會將完整上下文直接傳給模型。請參閱過大的掛勾輸出。

Key

hooks.<Event>[].hooks[].async

Type / Values

boolean

Details

在背景執行指令掛勾，而不延遲觸發該掛勾的作業。預設為 false；SessionEnd 一律同步執行。請參閱在背景執行掛勾。

Key

hooks.<Event>[].hooks[].commandWindows

Type / Values

string

Details

覆寫指令掛勾的指令，僅適用於 Windows。也可使用 TOML 別名 command_windows。

Key

instructions

Type / Values

string

Details

保留供日後使用；建議優先使用 model_instructions_file 或 AGENTS.md。

Key

log_dir

Type / Values

string (path)

Details

Codex 寫入記錄檔的目錄；預設為 $CODEX_HOME/log。明確設定此值也會在該目錄中啟用需主動選用的純文字 TUI 記錄檔 codex-tui.log。

Key

mcp_oauth_callback_port

Type / Values

integer

Details

選用的全域固定連接埠，供 MCP OAuth 登入期間的本機 HTTP 回呼伺服器使用。伺服器專屬的 oauth.callback_port 設定優先。若兩者皆未設定，Codex 會繫結至作業系統選擇的臨時連接埠。

Key

mcp_oauth_callback_url

Type / Values

string

Details

MCP OAuth 登入的選用基礎回呼 URL，例如 devbox 入口 URL。若授權伺服器支援簽發者識別，新加入的預先註冊用戶端會直接使用此 URL，不做更動；未儲存回呼的既有用戶端則會附加伺服器專屬的回呼 ID。若不支援簽發者識別，任何預先註冊的 MCP 伺服器，只要其設定的回呼缺少必要的 ID，就會改用此 URL 並附加該 ID。回呼 URL 中的連接埠不會決定監聽器的連接埠。

Key

mcp_oauth_credentials_store

Type / Values

auto | file | keyring

Details

MCP OAuth 認證資訊的偏好儲存位置。

Key

mcp_servers.<id>.args

Type / Values

array<string>

Details

傳遞給 MCP stdio 伺服器指令的引數。

Key

mcp_servers.<id>.auth

Type / Values

oauth | chatgpt

Details

MCP HTTP 伺服器的備援身分驗證方式，優先順序在已設定的 bearer Token 和授權標頭之後。oauth（預設）會在有可用憑證時使用已儲存的 MCP OAuth 憑證。chatgpt 會對受信任的第一方 ChatGPT 來源使用目前的 ChatGPT 工作階段，並以已儲存的 OAuth 憑證作為備援。如果所有憑證來源都無法提供憑證，兩種模式都能在未經身分驗證的情況下連線。

Key

mcp_servers.<id>.bearer_token_env_var

Type / Values

string

Details

提供 MCP HTTP 伺服器 bearer Token 的環境變數。

Key

mcp_servers.<id>.command

Type / Values

string

Details

用於啟動 MCP stdio 伺服器的指令。

Key

mcp_servers.<id>.cwd

Type / Values

string

Details

MCP stdio 伺服器程序的工作目錄。

Key

mcp_servers.<id>.default_tools_approval_mode

Type / Values

auto | prompt | writes | approve

Details

此伺服器上 MCP 工具的預設核准行為；如有個別工具的覆寫設定，則以該設定為準。

Key

mcp_servers.<id>.disabled_tools

Type / Values

array<string>

Details

MCP 伺服器在 enabled_tools 之後套用的拒絕清單。

Key

mcp_servers.<id>.enabled

Type / Values

boolean

Details

停用 MCP 伺服器，但保留其組態。

Key

mcp_servers.<id>.enabled_tools

Type / Values

array<string>

Details

允許 MCP 伺服器公開的工具名稱清單。

Key

mcp_servers.<id>.env

Type / Values

map<string,string>

Details

轉送至 MCP stdio 伺服器的環境變數。

Key

mcp_servers.<id>.env_http_headers

Type / Values

map<string,string>

Details

供 MCP HTTP 伺服器使用、值由環境變數填入的 HTTP 標頭。

Key

mcp_servers.<id>.env_vars

Type / Values

array<string | { name = string, source = "local" | "remote" }>

Details

要額外加入 MCP stdio 伺服器允許清單的環境變數。字串項目預設使用 source = "local"；只有搭配以執行器為後端的遠端 stdio 時，才能使用 source = "remote"。

Key

mcp_servers.<id>.experimental_environment

Type / Values

local | remote

Details

MCP 伺服器的實驗性執行位置設定。remote 會透過遠端執行器環境啟動 stdio 伺服器；尚未實作可串流 HTTP 伺服器的遠端執行位置功能。

Key

mcp_servers.<id>.http_headers

Type / Values

map<string,string>

Details

每個 MCP HTTP 請求中包含的靜態 HTTP 標頭。

Key

mcp_servers.<id>.oauth_resource

Type / Values

string

Details

MCP 登入時可選擇包含的 RFC 8707 OAuth 資源參數。

Key

mcp_servers.<id>.oauth.callback_port

Type / Values

integer

Details

此 MCP 伺服器的固定 OAuth 回呼接聽連接埠。覆寫 mcp_oauth_callback_port。若直接使用回送位址回呼，且 URL 明確指定連接埠，請將接聽連接埠設為相同值。

Key

mcp_servers.<id>.oauth.callback_url

Type / Values

string

Details

伺服器專屬的 OAuth 回呼。當支援簽發者識別，或 URL 已以該伺服器專屬的回呼 ID 結尾時，預先註冊的用戶端會沿用此回呼。否則，Codex 會使用附加了該 ID 的全域或預設回呼。沒有預先註冊 ID 的用戶端會在用戶端註冊期間使用此回呼。

Key

mcp_servers.<id>.oauth.client_id

Type / Values

string

Details

預先註冊的 OAuth 用戶端 ID，用於與此 MCP 伺服器進行授權及 Token 交換。

Key

mcp_servers.<id>.required

Type / Values

boolean

Details

設為 true 時，若這個已啟用的 MCP 伺服器無法初始化，啟動或恢復就會失敗。

Key

mcp_servers.<id>.scopes

Type / Values

array<string>

Details

向該 MCP 伺服器進行身分驗證時，要請求的 OAuth 授權範圍。

Key

mcp_servers.<id>.startup_timeout_ms

Type / Values

number

Details

以毫秒為單位的 startup_timeout_sec 別名。

Key

mcp_servers.<id>.startup_timeout_sec

Type / Values

number

Details

覆寫 MCP 伺服器預設的 10 秒啟動逾時設定。

Key

mcp_servers.<id>.tool_timeout_sec

Type / Values

number

Details

覆寫 MCP 伺服器每個工具預設的 60 秒逾時設定。

Key

mcp_servers.<id>.tools.<tool>.approval_mode

Type / Values

auto | prompt | writes | approve

Details

此伺服器上單一 MCP 工具的核准行為覆寫設定。

Key

mcp_servers.<id>.url

Type / Values

string

Details

MCP 可串流 HTTP 伺服器的端點。

Key

memories.consolidation_model

Type / Values

string

Details

全域記憶整併所用模型的覆寫設定（選填）。

Key

memories.disable_on_external_context

Type / Values

boolean

Details

設為 true 時，使用 MCP 工具呼叫、網頁搜尋或工具搜尋等外部上下文的執行緒，不會納入記憶生成。預設為 false。舊版別名：memories.no_memories_if_mcp_or_web_search。

Key

memories.extract_model

Type / Values

string

Details

個別執行緒記憶擷取所用模型的覆寫設定（選填）。

Key

memories.generate_memories

Type / Values

boolean

Details

設為 false 時，新建立的執行緒不會儲存為記憶生成的輸入資料。預設為 true。

Key

memories.max_raw_memories_for_consolidation

Type / Values

number

Details

為全域整併保留的近期原始記憶數量上限。預設為 256，上限為 4096。

Key

memories.max_rollout_age_days

Type / Values

number

Details

可納入記憶生成的執行緒存續時間上限。預設為 30，且會限制在 0-90 之間。

Key

memories.max_rollouts_per_startup

Type / Values

number

Details

每輪啟動作業處理的推演候選項數量上限。預設為 16，上限為 128。

Key

memories.max_unused_days

Type / Values

number

Details

記憶自上次使用後，仍可納入整併的最長天數。預設為 30，且會限制在 0-365 之間。

Key

memories.min_rate_limit_remaining_percent

Type / Values

number

Details

開始生成記憶前，Codex 速率限制視窗中所需的最低剩餘額度百分比。預設為 25，且會限制在 0-100 之間。

Key

memories.min_rollout_idle_hours

Type / Values

number

Details

執行緒在納入記憶生成考量前所需的最短閒置時間。預設為 6，且會限制在 1-48 之間。

Key

memories.use_memories

Type / Values

boolean

Details

設為 false 時，Codex 不會將現有記憶注入日後的工作階段。預設為 true。

Key

model

Type / Values

string

Details

要使用的模型（例如 gpt-5.5）。

Key

model_auto_compact_token_limit

Type / Values

number

Details

觸發自動壓縮歷史記錄的 Token 閾值（未設定時使用模型預設值）。

Key

model_auto_compact_token_limit_scope

Type / Values

total | body_after_prefix

Details

控制自動壓縮閾值是計入目前的完整上下文（total，預設值），還是僅計入沿用的壓縮視窗前綴之後的增長量（body_after_prefix）。

Key

model_catalog_json

Type / Values

string (path)

Details

啟動時載入的 JSON 模型目錄路徑（選用）。所選的 $CODEX_HOME/profile-name.config.toml 設定檔可個別覆寫此路徑。

Key

model_context_window

Type / Values

number

Details

目前使用的模型可用的上下文視窗 Token 數量。

Key

model_instructions_file

Type / Values

string (path)

Details

用來取代內建指示，而不是使用 AGENTS.md。

Key

model_provider

Type / Values

string

Details

來自 model_providers 的提供者 ID（預設：openai）。

Key

model_providers.<id>

Type / Values

table

Details

自訂供應商定義。內建供應商 ID（openai、ollama 和 lmstudio）均為保留值，無法覆寫。

Key

model_providers.<id>.auth

Type / Values

table

Details

自訂供應商透過指令取得 Bearer Token 的組態。請勿與 env_key、experimental_bearer_token 或 requires_openai_auth 同時使用。

Key

model_providers.<id>.auth.args

Type / Values

array<string>

Details

傳給 Token 指令的引數。

Key

model_providers.<id>.auth.command

Type / Values

string

Details

Codex 需要 Bearer Token 時要執行的指令。該指令必須將 Token 輸出至 stdout。

Key

model_providers.<id>.auth.cwd

Type / Values

string (path)

Details

Token 指令的工作目錄。

Key

model_providers.<id>.auth.refresh_interval_ms

Type / Values

number

Details

Codex 主動更新 Token 的間隔，以毫秒為單位（預設：300000）。設為 0 時，僅在身分驗證重試後更新。

Key

model_providers.<id>.auth.timeout_ms

Type / Values

number

Details

Token 指令的最長執行時間，以毫秒為單位（預設：5000）。

Key

model_providers.<id>.base_url

Type / Values

string

Details

模型供應商的 API 基底 URL。

Key

model_providers.<id>.env_http_headers

Type / Values

map<string,string>

Details

當環境變數存在時，以其值填入的 HTTP 標頭。

Key

model_providers.<id>.env_key

Type / Values

string

Details

提供供應商 API 金鑰的環境變數。

Key

model_providers.<id>.env_key_instructions

Type / Values

string

Details

供應商 API 金鑰的設定指引（選用）。

Key

model_providers.<id>.experimental_bearer_token

Type / Values

string

Details

直接設定的供應商 Bearer Token（不建議使用；請改用 env_key）。

Key

model_providers.<id>.http_headers

Type / Values

map<string,string>

Details

新增至供應商請求的靜態 HTTP 標頭。

Key

model_providers.<id>.name

Type / Values

string

Details

自訂模型供應商的顯示名稱。

Key

model_providers.<id>.query_params

Type / Values

map<string,string>

Details

附加至供應商請求的額外查詢參數。

Key

model_providers.<id>.request_max_retries

Type / Values

number

Details

向供應商發出 HTTP 請求時的重試次數（預設：4）。

Key

model_providers.<id>.requires_openai_auth

Type / Values

boolean

Details

此供應商使用 OpenAI 身分驗證（預設為 false）。

Key

model_providers.<id>.stream_idle_timeout_ms

Type / Values

number

Details

SSE 串流的閒置逾時，以毫秒為單位（預設：300000）。

Key

model_providers.<id>.stream_max_retries

Type / Values

number

Details

SSE 串流中斷時的重試次數（預設：5）。

Key

model_providers.<id>.supports_standalone_web_search

Type / Values

boolean

Details

宣告支援相容的獨立網頁搜尋端點（預設：false）。獨立搜尋功能仍在開發中，且預設關閉；供應商相容並不代表此功能會自動啟用。

Key

model_providers.<id>.supports_websockets

Type / Values

boolean

Details

該供應商是否支援 Responses API 的 WebSocket 傳輸方式。

Key

model_providers.<id>.wire_api

Type / Values

responses

Details

供應商使用的通訊協定。唯一支援的值是 responses；若省略，預設也會使用此值。

Key

model_providers.amazon-bedrock.aws.profile

Type / Values

string

Details

內建 amazon-bedrock 供應商使用的 AWS 設定檔名稱。

Key

model_providers.amazon-bedrock.aws.region

Type / Values

string

Details

內建 amazon-bedrock 供應商使用的 AWS 區域。

Key

model_reasoning_effort

Type / Values

minimal | low | medium | high | xhigh

Details

調整受支援模型的推理投入程度（僅限 Responses API；對 xhigh 的支援依模型而定）。

Key

model_reasoning_summary

Type / Values

auto | concise | detailed | none

Details

選擇推理摘要的詳細程度，或完全停用摘要。

Key

model_supports_reasoning_summaries

Type / Values

boolean

Details

強制 Codex 傳送或不傳送推理中繼資料。

Key

model_verbosity

Type / Values

low | medium | high

Details

GPT-5 Responses API 輸出詳細程度的覆寫設定（選用）；若未設定，會採用所選模型或預設組合的預設值。

Key

notice.hide_full_access_warning

Type / Values

boolean

Details

追蹤是否已確認完整存取權警告提示。

Key

notice.hide_gpt-5.1-codex-max_migration_prompt

Type / Values

boolean

Details

追蹤是否已確認 gpt-5.1-codex-max 遷移提示。

Key

notice.hide_gpt5_1_migration_prompt

Type / Values

boolean

Details

追蹤是否已確認 GPT-5.1 遷移提示。

Key

notice.hide_rate_limit_model_nudge

Type / Values

boolean

Details

追蹤是否已選擇不再顯示因速率限制而切換模型的提醒。

Key

notice.hide_world_writable_warning

Type / Values

boolean

Details

追蹤是否已確認關於 Windows 目錄對所有使用者開放寫入的警告。

Key

notice.model_migrations

Type / Values

map<string,string>

Details

以舊模型->新模型的對應關係，追蹤已確認的模型遷移。

Key

notify

Type / Values

array<string>

Details

發出通知時執行的指令；會接收來自 Codex 的 JSON 承載資料。

Key

openai_base_url

Type / Values

string

Details

內建 openai 模型提供者的基礎 URL 覆寫設定。

Key

oss_provider

Type / Values

lmstudio | ollama

Details

使用 --oss 執行時採用的預設本機提供者（若未設定，預設會提示您選擇）。

Key

otel.environment

Type / Values

string

Details

套用至所發出 OpenTelemetry 事件的環境標記（預設：dev）。

Key

otel.exporter

Type / Values

none | otlp-http | otlp-grpc

Details

選擇 OpenTelemetry 匯出器，並提供相關的端點中繼資料。

Key

otel.exporter.<id>.endpoint

Type / Values

string

Details

OTEL 紀錄的匯出器端點。

Key

otel.exporter.<id>.headers

Type / Values

map<string,string>

Details

OTEL 匯出器請求中包含的靜態標頭。

Key

otel.exporter.<id>.protocol

Type / Values

binary | json

Details

OTLP/HTTP 匯出器使用的通訊協定。

Key

otel.exporter.<id>.tls.ca-certificate

Type / Values

string

Details

OTEL 匯出器 TLS 使用的 CA 憑證路徑。

Key

otel.exporter.<id>.tls.client-certificate

Type / Values

string

Details

OTEL 匯出器 TLS 使用的用戶端憑證路徑。

Key

otel.exporter.<id>.tls.client-private-key

Type / Values

string

Details

OTEL 匯出器 TLS 使用的用戶端私密金鑰路徑。

Key

otel.log_user_prompt

Type / Values

boolean

Details

選擇將原始使用者提示詞隨 OpenTelemetry 紀錄一併匯出。

Key

otel.metrics_exporter

Type / Values

none | statsig | otlp-http | otlp-grpc

Details

選擇 OpenTelemetry 指標匯出器（預設為 statsig）。

Key

otel.trace_exporter

Type / Values

none | otlp-http | otlp-grpc

Details

選擇 OpenTelemetry 追蹤匯出器，並提供相關的端點中繼資料。

Key

otel.trace_exporter.<id>.endpoint

Type / Values

string

Details

OTEL 紀錄的追蹤匯出器端點。

Key

otel.trace_exporter.<id>.headers

Type / Values

map<string,string>

Details

OTEL 追蹤匯出器請求中包含的靜態標頭。

Key

otel.trace_exporter.<id>.protocol

Type / Values

binary | json

Details

OTLP/HTTP 追蹤匯出器使用的通訊協定。

Key

otel.trace_exporter.<id>.tls.ca-certificate

Type / Values

string

Details

OTEL 追蹤匯出器 TLS 使用的 CA 憑證路徑。

Key

otel.trace_exporter.<id>.tls.client-certificate

Type / Values

string

Details

OTEL 追蹤匯出器 TLS 使用的用戶端憑證路徑。

Key

otel.trace_exporter.<id>.tls.client-private-key

Type / Values

string

Details

OTEL 追蹤匯出器 TLS 使用的用戶端私密金鑰路徑。

Key

permissions.<name>.description

Type / Values

string

Details

此具名設定檔的易讀說明。設定檔不會透過 extends 繼承父設定檔的說明。

Key

permissions.<name>.extends

Type / Values

string

Details

選用的父設定檔，會先於此具名設定檔套用。可設為其他具名設定檔、:read-only 或 :workspace；不接受 :danger-full-access、未定義的父設定檔或循環繼承。

Key

permissions.<name>.filesystem

Type / Values

table

Details

具名檔案系統權限設定檔。每個索引鍵都是絕對路徑或特殊 Token，例如 :minimal 或 :workspace_roots。

Key

permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob>

Type / Values

"read" | "write" | "deny"

Details

以每個有效工作區根目錄為基準，限定檔案系統的存取範圍。使用 "." 表示根目錄本身；"**/*.env" 等 glob 子路徑可使用 "deny" 拒絕讀取。

Key

permissions.<name>.filesystem.<path-or-glob>

Type / Values

"read" | "write" | "deny" | table

Details

授予路徑、glob 模式或特殊 Token 所指定目標的直接存取權，或將巢狀項目的範圍限定在該根目錄下。使用 "deny" 拒絕讀取相符路徑。

Key

permissions.<name>.filesystem.glob_scan_max_depth

Type / Values

number

Details

在會於沙盒啟動前為相符項目建立快照的平台上，展開拒絕讀取 glob 模式的最大深度。若有設定，值必須至少為 1。

Key

permissions.<name>.network.allow_local_binding

Type / Values

boolean

Details

允許透過沙盒網路存取更廣泛的本機或私人網路。即使此設定維持 false，精確指定本機 IP 常值或 localhost 的允許規則，仍可允許存取特定本機目標。

Key

permissions.<name>.network.allow_upstream_proxy

Type / Values

boolean

Details

允許沙盒網路串接另一個上游代理伺服器。

Key

permissions.<name>.network.dangerously_allow_all_unix_sockets

Type / Values

boolean

Details

允許連線至任意 Unix 通訊端目的地，而不限於預設範圍。僅限在嚴格控管的環境中使用。

Key

permissions.<name>.network.dangerously_allow_non_loopback_proxy

Type / Values

boolean

Details

允許沙盒網路接聽器繫結至非回送位址。啟用後，可能讓 localhost 以外的位置也能存取接聽器。

Key

permissions.<name>.network.domains

Type / Values

table

Details

適用於沙盒內指令的網域規則。僅當 features.network_proxy 或已啟用、由管理員管理的網路要求啟動代理伺服器時，才會強制執行。支援精確指定的主機、*.example.com、**.example.com 和全域 * 允許規則；deny 優先。不會限制網頁搜尋、應用程式或 MCP 伺服器。

Key

permissions.<name>.network.domains.<pattern>

Type / Values

allow | deny

Details

允許或拒絕精確指定的主機，或 *.example.com、**.example.com 等限定範圍的萬用字元模式。

Key

permissions.<name>.network.enable_socks5

Type / Values

boolean

Details

此權限設定檔啟用沙盒網路時，提供 SOCKS5 支援。

Key

permissions.<name>.network.enable_socks5_udp

Type / Values

boolean

Details

啟用後，允許透過 SOCKS5 接聽器傳送 UDP。

Key

permissions.<name>.network.enabled

Type / Values

boolean

Details

啟用此權限設定檔下指令的網路存取。這不會啟動網路代理伺服器。如果未啟用 features.network_proxy，也未啟用由管理員管理的網路要求，指令會直接存取網路，且設定檔的網域規則不會強制執行。

Key

permissions.<name>.network.mode

Type / Values

limited | full

Details

子程序流量使用的網路代理伺服器模式。

Key

permissions.<name>.network.proxy_url

Type / Values

string

Details

此權限設定檔啟用沙盒網路時所使用的 HTTP 接聽器 URL。

Key

permissions.<name>.network.socks_url

Type / Values

string

Details

此權限設定檔使用的 SOCKS5 代理伺服器端點。

Key

permissions.<name>.network.unix_sockets

Type / Values

table

Details

沙盒網路的 Unix 通訊端允許清單覆寫設定。以通訊端路徑作為索引鍵；allow 會新增路徑，deny 則拒絕該路徑。

Key

permissions.<name>.network.unix_sockets.<path>

Type / Values

allow | deny

Details

使用 allow 將 Unix 通訊端絕對路徑加入實際生效的允許清單，或使用 deny 拒絕該路徑。遭拒絕的項目不會納入實際生效的允許清單。

Key

permissions.<name>.workspace_roots

Type / Values

table

Details

由設定檔定義的工作區根目錄，會與工作階段執行時的工作區根目錄一同套用 :workspace_roots 檔案系統規則。

Key

permissions.<name>.workspace_roots.<path>

Type / Values

boolean

Details

設為 true 時，將路徑納入此設定檔的工作區根目錄集合。停用的項目不會生效。

Key

personality

Type / Values

none | friendly | pragmatic

Details

宣告支援 supportsPersonality 的模型所採用的預設溝通風格；可針對個別對話串或輪次覆寫，也可透過 /personality 覆寫。

Key

plan_mode_reasoning_effort

Type / Values

Details

規劃模式專用的推理覆寫設定。若未設定，規劃模式會使用內建預設組合的預設值。

Key

plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode

Type / Values

auto | prompt | writes | approve

Details

外掛程式提供的 MCP 伺服器上各項工具的預設核准行為。

Key

plugins.<plugin>.mcp_servers.<server>.disabled_tools

Type / Values

array<string>

Details

外掛程式提供的 MCP 伺服器的拒絕清單，會在 enabled_tools 之後套用。

Key

plugins.<plugin>.mcp_servers.<server>.enabled

Type / Values

boolean

Details

在不變更外掛程式資訊清單的情況下，啟用或停用已安裝外掛程式隨附的 MCP 伺服器。

Key

plugins.<plugin>.mcp_servers.<server>.enabled_tools

Type / Values

array<string>

Details

外掛程式提供的 MCP 伺服器所公開的工具允許清單。

Key

plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode

Type / Values

auto | prompt | writes | approve

Details

針對外掛程式提供的 MCP 工具，個別覆寫核准行為。

Key

project_doc_fallback_filenames

Type / Values

array<string>

Details

找不到 AGENTS.md 時要嘗試的其他檔名。

Key

project_doc_max_bytes

Type / Values

number

Details

建立專案指示時，從 AGENTS.md 讀取的位元組數上限。

Key

project_root_markers

Type / Values

array<string>

Details

專案根目錄標記檔的檔名清單；搜尋上層目錄以尋找專案根目錄時使用。

Key

projects.<path>.trust_level

Type / Values

string

Details

將專案或工作樹標記為受信任或不受信任（"trusted" | "untrusted"）。不受信任的專案會略過專案範圍的 .codex/ 層，包括專案本機組態、掛勾和規則。

Key

review_model

Type / Values

string

Details

供 /review 使用的選用模型覆寫設定（預設為目前工作階段的模型）。

Key

sandbox_mode

Type / Values

read-only | workspace-write | danger-full-access

Details

指令執行期間檔案系統與網路存取的沙盒政策。

Key

sandbox_workspace_write.exclude_slash_tmp

Type / Values

boolean

Details

在 workspace-write 模式下，將 /tmp 排除在可寫入根目錄之外。

Key

sandbox_workspace_write.exclude_tmpdir_env_var

Type / Values

boolean

Details

在 workspace-write 模式下，將 $TMPDIR 排除在可寫入根目錄之外。

Key

sandbox_workspace_write.network_access

Type / Values

boolean

Details

允許 workspace-write 沙盒內的對外網路存取。

Key

sandbox_workspace_write.writable_roots

Type / Values

array<string>

Details

當 sandbox_mode = "workspace-write" 時，額外允許寫入的根目錄。

Key

service_tier

Type / Values

string

Details

新輪次的偏好服務層級。請使用 fast 或目前使用的模型宣告支援的其他層級；fast 對應至請求值 priority。

Key

shell_environment_policy.exclude

Type / Values

array<string>

Details

舊版環境變數排除模式。新組態請使用 shell_environment_policy.filters；請勿在同一層中同時使用這兩種形式。

Key

shell_environment_policy.experimental_use_profile

Type / Values

boolean

Details

啟動子程序時使用使用者的 shell 設定檔。

Key

shell_environment_policy.filters

Type / Values

map<string, include | exclude>

Details

標準的環境變數模式篩選器，不區分大小寫。納入項目會建立允許清單，且無法還原已排除的值。明確指定的 set 值會在排除作業後套用。請勿在同一層中同時使用這些篩選器與舊版 exclude 或 include_only 陣列。

Key

shell_environment_policy.ignore_default_excludes

Type / Values

boolean

Details

在執行其他篩選器前，保留名稱中包含 KEY、SECRET 或 TOKEN 的變數（預設：true）。設為 false 可自動依機密相關名稱排除變數。

Key

shell_environment_policy.include_only

Type / Values

array<string>

Details

舊版環境變數模式允許清單。新組態請使用 shell_environment_policy.filters；請勿在同一層中同時使用這兩種形式。

Key

shell_environment_policy.inherit

Type / Values

all | core | none

Details

啟動子程序時的基準環境繼承方式。

Key

shell_environment_policy.set

Type / Values

map<string,string>

Details

在排除作業後注入明確指定的環境變數值；納入篩選器仍可將其移除。

Key

show_raw_agent_reasoning

Type / Values

boolean

Details

當使用中的模型輸出原始推理內容時，將其顯示。

Key

skills.config

Type / Values

array<object>

Details

儲存在 config.toml 中的各技能啟用狀態覆寫設定。

Key

skills.config.<index>.enabled

Type / Values

boolean

Details

啟用或停用所參照的技能。

Key

skills.config.<index>.path

Type / Values

string (path)

Details

包含 SKILL.md 的技能資料夾路徑。

Key

sqlite_home

Type / Values

string (path)

Details

Codex 儲存 SQLite 狀態資料庫的目錄；該資料庫供智慧體作業及其他可恢復的執行階段狀態使用。

Key

suppress_unstable_features_warning

Type / Values

boolean

Details

隱藏啟用開發中功能旗標時顯示的警告。

Key

tool_output_token_limit

Type / Values

number

Details

將個別工具／函式輸出儲存至歷史紀錄的 Token 預算。

Key

tool_suggest.disabled_tools

Type / Values

array<table>

Details

停用特定可探索連接器或外掛程式的建議。每個項目都使用 type = "connector" 或 "plugin"，並指定一個 id。

Key

tool_suggest.discoverables

Type / Values

array<table>

Details

允許針對其他可探索的連接器或外掛程式提供工具建議。每個項目都使用 type = "connector" 或 "plugin"，並指定一個 id。

Key

tools.view_image

Type / Values

boolean

Details

啟用本機圖像附件工具 view_image。

Key

tools.web_search

Type / Values

boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }

Details

選用的網頁搜尋工具組態。物件形式可設定搜尋上下文大小、允許的搜尋網域，以及使用者的大致位置。這些搜尋網域篩選條件與沙盒指令的網路網域規則相互獨立，且不會限制連接器或 MCP 伺服器。

Key

tui

Type / Values

table

Details

TUI 專用選項，例如啟用內嵌桌面通知。

Key

tui.alternate_screen

Type / Values

auto | always | never

Details

控制 TUI 是否使用替代畫面（預設：auto；auto 在 Zellij 中會略過替代畫面，以保留回捲內容）。

Key

tui.animations

Type / Values

boolean

Details

啟用終端動畫（歡迎畫面、微光效果、旋轉指示器）（預設：true）。

Key

tui.keymap.<context>.<action>

Type / Values

string | array<string>

Details

TUI 動作的鍵盤快速鍵繫結。支援的上下文包括 global、chat、composer、editor、vim_normal、vim_operator、vim_text_object、pager、list 和 approval。部分撰寫工具動作會使用相符的 tui.keymap.global 繫結作為備用；若支援特定上下文的繫結，則優先使用該繫結。

Key

tui.keymap.<context>.<action> = []

Type / Values

empty array

Details

解除該動作在此按鍵對應上下文中的繫結。按鍵名稱使用標準化字串，例如 ctrl-a、shift-enter、page-down 或 minus。

Key

tui.model_availability_nux.<model>

Type / Values

integer

Details

以模型 Slug 為鍵的啟動工具提示內部狀態。

Key

tui.notification_condition

Type / Values

unfocused | always

Details

控制 TUI 通知是僅在終端未取得焦點時觸發，還是不論焦點狀態皆會觸發。預設為 unfocused。

Key

tui.notification_method

Type / Values

auto | osc9 | bel

Details

終端通知使用的方式（預設：auto）。

Key

tui.notifications

Type / Values

boolean | array<string>

Details

啟用 TUI 通知，也可選擇限制為特定事件類型。

Key

tui.raw_output_mode

Type / Values

boolean

Details

以原始回捲模式啟動 TUI，方便選取並複製終端內容（預設：false）。可使用 /raw 或預設的 alt-r 按鍵繫結切換。

Key

tui.resume_cwd

Type / Values

current | session

Details

恢復工作階段或為其建立分支時使用的工作目錄。若未設定，而目前目錄與工作階段所儲存的目錄不同，Codex 會要求你選擇。

Key

tui.show_tooltips

Type / Values

boolean

Details

在 TUI 歡迎畫面中顯示新手引導工具提示（預設：true）。

Key

tui.status_line

Type / Values

array<string> | null

Details

TUI 底部狀態列項目識別碼的有序清單。null 會停用狀態列。

Key

tui.terminal_title

Type / Values

array<string> | null

Details

終端視窗／分頁標題項目識別碼的有序清單。預設為 ["spinner", "project"]；null 會停用標題更新。

Key

tui.theme

Type / Values

string

Details

語法醒目提示佈景主題的覆寫設定（佈景主題名稱採用 kebab-case 格式）。

Key

tui.vim_mode_default

Type / Values

boolean

Details

啟動撰寫工具時使用 Vim 一般模式，而非插入模式（預設：false）。仍可在每個工作階段使用 /vim 切換。

Key

web_search

Type / Values

disabled | cached | indexed | live

Details

網頁搜尋模式（預設："cached"；cached 使用由 OpenAI 維護的索引，不會存取外部網頁；indexed 僅允許經搜尋索引控管的外部存取；若使用 --yolo 或其他完整存取權沙盒設定，則預設為 "live"）。若要進行不受限制的即時擷取，請使用 "live"；若要移除此工具，請使用 "disabled"。

Key

windows_wsl_setup_acknowledged

Type / Values

boolean

Details

追蹤 Windows 新手引導的確認狀態（僅限 Windows）。

Key

windows.sandbox

Type / Values

unelevated | elevated

Details

Codex 在 Windows 上原生執行時使用的 Windows 專用原生沙盒模式。

Key

windows.sandbox_private_desktop

Type / Values

boolean

Details

在 Windows 原生環境中，預設會在私有桌面上執行最終的沙盒子處理程序。只有在需要與舊版 Winsta0\\Default 行為相容時，才設為 false。

您可以在此處找到 config.toml 的最新 JSON 結構描述。

若要在 VS Code 或 Cursor 中編輯 config.toml 時取得自動完成功能和診斷資訊，您可以安裝 Even Better TOML 擴充功能，並將以下這行新增至 config.toml 頂端：

#:schema https://developers.openai.com/codex/config-schema.json

注意：請將 experimental_instructions_file 重新命名為 model_instructions_file。Codex 已棄用舊索引鍵；請更新現有組態，改用新名稱。

`requirements.toml`

requirements.toml 是由管理員強制套用的組態檔，用來限制涉及安全性的設定，使用者無法覆寫這些限制。如需詳細資訊、位置和範例，請參閱管理員強制要求。

對於 ChatGPT Business 和 ChatGPT Enterprise 使用者，Codex 也可以套用從雲端擷取的要求。如需優先順序的詳細資訊，請參閱安全性頁面。

在 requirements.toml 中使用 [features]，即可透過與 config.toml 相同的標準索引鍵，固定執行階段功能旗標的值。要求也可以包含文件中記載的 App 專用索引鍵，這些索引鍵不屬於 config.toml。未列出的索引鍵仍不受限制。

部分受管理的要求會強制套用確切的組態值，而非使用允許清單。使用者無法覆寫強制設定的路徑、更新偏好設定、登入 Shell 原則、意見回饋設定或 Windows 私人桌面設定。

受管理的權限設定檔允許清單需要 Codex 0.138.0 或更新版本。 Codex 0.137.0 及更早版本會忽略 allowed_permission_profiles 以及受管理的 default_permissions。

請搭配使用 allowed_sandbox_modes 與 sandbox_mode。若部署使用權限設定檔，請搭配使用 allowed_permission_profiles 與受管理的 default_permissions。

[models.new_thread] 表提供受管理的預設值，並非強制設定。透過專用 CLI 旗標或 --config 覆寫所明確指定的啟動選項，具有較高優先順序。明確覆寫模型或推理投入程度時，會略過兩個受管理的模型欄位； service_tier 則獨立運作。

Key	Type / Values	Details
`allow_appshots`	`boolean`	設為 `false` 可為受管理使用者停用應用程式快照。若省略，應用程式快照不受需求限制，其可用性依產品的一般規則而定。
`allow_login_shell`	`boolean`	強制設定 Shell 工具是否可啟動登入 Shell。
`allow_managed_hooks_only`	`boolean`	設為 `true` 時，Codex 會略過使用者、專案、工作階段及外掛程式的掛勾，但仍允許來自 `requirements.toml` 和其他管理式設定層的管理式掛勾。
`allow_remote_control`	`boolean`	設為 `false` 可為受管理使用者停用裝置遠端控制。若省略，裝置遠端控制不受需求限制，其可用性依產品的一般規則而定。
`allowed_approval_policies`	`array<string>`	`approval_policy` 的允許值，例如 `untrusted`、`on-request`、`never` 和 `granular`。
`allowed_approvals_reviewers`	`array<string>`	`approvals_reviewer` 的允許值，例如 `user` 和 `auto_review`。
`allowed_permission_profiles`	`table<boolean>`	允許使用的權限設定檔完整清單。設為 `true` 的設定檔允許使用。未列出或設為 `false` 的設定檔皆不允許使用，包括未來版本新增的設定檔。合併要求來源時，會依設定檔名稱比對項目。
`allowed_permission_profiles.<name>`	`boolean`	允許或拒絕已載入組態或要求來源中定義的內建或自訂權限設定檔。後續套用且優先順序較高的要求來源，可使用 `false` 停用先前優先順序較低的來源所允許的設定檔。
`allowed_sandbox_modes`	`array<string>`	`sandbox_mode` 的允許值。
`allowed_web_search_modes`	`array<string>`	`web_search` 的允許值（`disabled`、`cached`、`indexed`、`live`）。一律允許 `disabled`；空清單實際上只允許 `disabled`。
`apps`	`table`	受管理的應用程式要求，以應用程式識別碼作為索引鍵。這些要求可停用應用程式，或限制個別工具的核准行為。
`apps.<id>.enabled`	`boolean`	設為 `false` 可停用應用程式。合併多個要求來源時，這項停用要求仍具限制效力。
`apps.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	設定單一應用程式工具的受管理核准模式。
`check_for_update_on_startup`	`boolean`	強制設定 Codex 啟動時是否檢查更新。
`computer_use`	`table`	由 `requirements.toml` 強制執行的電腦功能需求。
`computer_use.allow_locked_computer_use`	`boolean`	設為 `false` 可防止電腦功能在受管理的 macOS 裝置鎖定後繼續運作。若省略，鎖定狀態下使用電腦功能不受需求限制。
`default_permissions`	`string`	受管理的預設權限設定檔。此設定檔必須獲 `allowed_permission_profiles` 允許。請明確設定此項以確保行為可預期；若省略，只有在 `:workspace` 和 `:read-only` 均獲明確允許時，Codex 才會預設使用 `:workspace`。
`enforce_residency`	`string`	要求 Codex 服務流量使用受支援的資料駐留位置。目前接受 `us`。
`experimental_network`	`table`	管理員為沙盒內的本機指令設定的網路需求，由 `requirements.toml` 強制執行。啟用後，即使未使用 `features.network_proxy`，這些需求也能啟動指令網路代理伺服器。這些需求不會控管網頁搜尋、應用程式、MCP 伺服器、瀏覽器或 Codex 雲端的網路連線。
`experimental_network.allow_local_binding`	`boolean`	允許沙盒網路連線存取更廣泛的本機或私有網路。此值維持 `false` 時，明確指定本機 IP 位址常值或 `localhost` 的允許規則，仍可放行特定本機目標。
`experimental_network.allow_upstream_proxy`	`boolean`	允許沙盒網路連線串接環境中的上游代理伺服器。
`experimental_network.allowed_domains`	`array<string>`	受管理的網路代理伺服器啟用時，適用於沙盒內指令網路連線的管理員允許規則。這些規則不適用於網頁搜尋、應用程式或 MCP 伺服器。請勿與 `experimental_network.domains` 搭配使用。
`experimental_network.dangerously_allow_all_unix_sockets`	`boolean`	允許任意 Unix 通訊端目的地，而非僅限允許清單中的目的地。僅限在嚴格控管的環境中使用。
`experimental_network.dangerously_allow_non_loopback_proxy`	`boolean`	允許 `[experimental_network]` 需求使用非回送接聽位址。啟用後，接聽器可能會開放給 localhost 以外的來源存取。
`experimental_network.denied_domains`	`array<string>`	管理員的沙盒網路連線拒絕規則，採用清單格式。請勿與 `experimental_network.domains` 搭配使用。
`experimental_network.domains`	`map<string, allow \| deny>`	管理員的沙盒網路連線網域原則，採用對應表格式。支援完全相符的主機、僅比對子網域的 `.example.com`、同時比對根網域及其子網域的 `.example.com`，以及全域 `` 允許規則；由於 `*` 會廣泛開放對公用網路的對外連線，建議使用限定範圍的規則。若有衝突，以 `deny` 為準。請勿與 `experimental_network.allowed_domains` 或 `experimental_network.denied_domains` 搭配使用。
`experimental_network.enabled`	`boolean`	啟用沙盒網路連線需求。若作用中的沙盒仍禁止指令連網，這項設定不會授予網路存取權。
`experimental_network.http_port`	`integer`	`[experimental_network]` 需求所使用的回送 HTTP 接聽連接埠。
`experimental_network.managed_allowed_domains_only`	`boolean`	設為 `true` 時，啟用沙盒網路連線需求期間，只有管理員設定的允許規則會維持有效；使用者新增的允許清單項目將遭忽略。若沒有管理員設定的允許規則，使用者新增的網域允許規則也不會繼續生效。
`experimental_network.socks_port`	`integer`	`[experimental_network]` 需求所使用的回送 SOCKS5 接聽連接埠。
`experimental_network.unix_sockets`	`map<string, allow \| deny>`	管理員為沙盒網路連線設定的 Unix 通訊端原則。
`features`	`table`	固定的功能設定值。執行階段功能請使用 `config.toml` 中的標準名稱；此處也支援文件所載的應用程式專用需求鍵。
`features.<name>`	`boolean`	要求文件所載的執行階段或應用程式功能維持啟用或停用狀態。
`features.apps`	`boolean`	將受管理使用者的應用程式整合功能固定為啟用或停用。
`features.browser_use`	`boolean`	在 `requirements.toml` 中設為 `false` 可停用瀏覽器中的電腦功能，並停用瀏覽器智慧體。
`features.browser_use_external`	`boolean`	在 `requirements.toml` 中設為 `false` 可停用外部瀏覽器中的電腦功能。
`features.browser_use_full_cdp_access`	`boolean`	在 `requirements.toml` 中設為 `false` 可停用本機執行階段對 Chrome DevTools Protocol 的完整存取，包括瀏覽器開發人員模式，並防止 ChatGPT 桌面版應用程式啟用對應設定。若省略，其可用性依產品的一般規則而定。
`features.computer_use`	`boolean`	在 `requirements.toml` 中設為 `false` 可停用電腦功能、錄製與重播，以及相關的安裝或啟用流程。
`features.fast_mode`	`boolean`	將受管理使用者的標準 `fast_mode` 功能固定為啟用或停用。
`features.guardian_approval`	`boolean`	將受管理使用者的 Guardian 核准功能固定為啟用或停用。
`features.in_app_browser`	`boolean`	在 `requirements.toml` 中設為 `false` 可停用內建瀏覽器窗格。
`features.in_app_updates`	`boolean`	在 `requirements.toml` 中設為 `false` 可停用應用程式內更新。若省略此需求，更新預設仍維持啟用。
`features.memories`	`boolean`	將受管理使用者的記憶功能固定為啟用或停用。
`features.multi_agent`	`boolean`	將受管理使用者的多智慧體功能固定為啟用或停用。
`features.plugin_sharing`	`boolean`	在雲端管理的 `requirements.toml` 中設為 `false`，即可停用在工作區內分享本機建置外掛程式的功能。
`features.plugins`	`boolean`	將受管理使用者的外掛程式功能固定為啟用或停用。
`features.remote_plugin`	`boolean`	將受管理使用者的遠端外掛程式目錄固定為啟用或停用。
`features.workspace_dependencies`	`boolean`	為受管理使用者固定啟用或停用隨附的工作區相依性執行階段。
`feedback`	`table`	受管理的意見回饋設定。
`feedback.enabled`	`boolean`	強制設定使用者是否可透過各個 Codex 用戶端提交意見回饋。
`guardian_policy_config`	`string`	供自動審查使用的受管理 Markdown 原則指示。此設定的優先順序高於本機 `[auto_review].policy`。空白值會被忽略。
`hooks`	`table`	由管理員強制執行的管理式生命週期掛勾。需要管理式掛勾目錄，並使用與 `config.toml` 中內嵌 `[hooks]` 相同的事件結構描述。
`hooks.<Event>`	`array<table>`	掛勾事件（例如 `PreToolUse`、`PermissionRequest`、`PostToolUse`、`PreCompact`、`PostCompact`、`SessionStart`、`SessionEnd`、`SubagentStart`、`SubagentStop`、`UserPromptSubmit` 或 `Stop`）的比對器群組。
`hooks.<Event>[].hooks`	`array<table>`	比對器群組的掛勾處理常式。支援指令掛勾和 MCP 工具掛勾；提示詞和智慧體掛勾處理常式則會經過剖析，但會略過執行。
`hooks.<Event>[].hooks[].additionalContextLimit`	`integer`	每個處理常式的大致 Token 臨界值；`additionalContext` 超過此值時，會儲存至磁碟，並向模型顯示較短的預覽。預設為 `2500`；設為 `0` 會將完整上下文直接傳給模型。請參閱大型掛勾輸出。
`hooks.<Event>[].hooks[].async`	`boolean`	在背景執行指令掛勾，不延遲觸發該掛勾的作業。預設為 `false`；`SessionEnd` 一律同步執行。請參閱在背景執行掛勾。
`hooks.<Event>[].hooks[].commandWindows`	`string`	指令掛勾的 Windows 專用指令覆寫值。也接受 TOML 別名 `command_windows`。
`hooks.managed_dir`	`string (absolute path)`	macOS 和 Linux 上存放管理式掛勾指令碼的目錄。Codex 會在載入管理式掛勾前，驗證目錄路徑為絕對路徑，且該目錄存在。
`hooks.windows_managed_dir`	`string (absolute path)`	Windows 上存放管理式掛勾指令碼的目錄。Codex 會在載入管理式掛勾前，驗證目錄路徑為絕對路徑，且該目錄存在。
`log_dir`	`string (path)`	強制指定 Codex 寫入本機記錄檔的目錄。
`marketplaces`	`table`	外掛程式市集來源的管理員要求。`restrict_to_allowed_sources` 設為 `true` 時，規則會生效。
`marketplaces.allowed_sources`	`table`	允許的市集來源以管理員選定的規則名稱作為索引鍵。名稱不同的規則會跨要求層累加；相同名稱下的欄位則採用一般的分層優先順序。
`marketplaces.allowed_sources.<name>`	`table`	一項允許來源的規則。合併要求後的最終 `source` 值，決定 Codex 會解讀哪些同層欄位。
`marketplaces.allowed_sources.<name>.host_pattern`	`string`	當 `source = "host_pattern"` 時，必須提供規則運算式。Codex 會以此比對從 HTTPS、SSH 或 SCP 樣式的 Git 來源剖析出的全小寫主機名稱。使用 `^` 和 `$` 可要求整個主機名稱完全相符。
`marketplaces.allowed_sources.<name>.path`	`string (absolute path)`	當 `source = "local"` 時，必須提供本機市集目錄。Codex 要求使用絕對路徑，並在路徑正規化後進行比較。
`marketplaces.allowed_sources.<name>.ref`	`string`	`git` 規則可選擇指定必須完全相符的 Git ref。若省略，規則會允許相符程式碼庫的任何 ref。
`marketplaces.allowed_sources.<name>.source`	`git \| host_pattern \| local`	市集來源的比對器類型。單一程式碼庫使用 `git`，以規則運算式比對 Git 主機使用 `host_pattern`，單一目錄則使用 `local`。
`marketplaces.allowed_sources.<name>.url`	`string`	當 `source = "git"` 時，必須提供 Git 程式碼庫 URL。Codex 會先將已設定的 URL 與允許的 URL 正規化，再要求程式碼庫完全相符。
`marketplaces.restrict_to_allowed_sources`	`boolean`	設為 `true` 時，使用者設定的市集來源必須符合 `allowed_sources`，才能執行新增市集、安裝外掛程式及重新整理已設定的 Git 市集等操作。由 Codex 管理的 OpenAI 市集，只要來源與名稱符合保留值，仍可使用。這不會在執行階段篩選使用者已設定的市集。
`mcp_servers`	`table`	可啟用 MCP 伺服器的允許清單。伺服器名稱（`<id>`）與識別資訊都必須相符，才能啟用 MCP 伺服器。任何不在允許清單中的已設定 MCP 伺服器，或識別資訊不符的伺服器，都會停用。
`mcp_servers.<id>.identity`	`table`	單一 MCP 伺服器的識別規則。請設定 `command`（stdio）或 `url`（可串流 HTTP）其中之一。
`mcp_servers.<id>.identity.command`	`string \| table`	以完全相符的指令字串允許 MCP stdio 伺服器，或使用比對器表格，要求可執行檔完全相符，且引數須依序符合比對器條件。字串形式不會檢查引數、`cwd`、`env` 或 `env_vars`。
`mcp_servers.<id>.identity.command.args`	`array<table>`	stdio 伺服器依序排列的引數比對器。已設定的引數清單長度必須相同，且每個位置都必須相符。指令比對器不會檢查 `cwd`、`env` 或 `env_vars`。
`mcp_servers.<id>.identity.command.args[].expression`	`string`	`regex` 引數比對器使用的規則運算式。該運算式必須有效，且須與完整引數值相符。
`mcp_servers.<id>.identity.command.args[].match`	`exact \| prefix \| regex`	此引數位置的比對方式。
`mcp_servers.<id>.identity.command.args[].value`	`string`	供 `exact` 或 `prefix` 引數比對器使用的值。
`mcp_servers.<id>.identity.command.executable`	`string`	stdio 伺服器設定中的 `command` 必須完全符合的可執行檔。
`mcp_servers.<id>.identity.url`	`string \| table`	以完全相符的 URL 字串允許 MCP 可串流 HTTP 伺服器，或使用 `exact`、`prefix` 或 `regex` 值比對器表格。
`mcp_servers.<id>.identity.url.expression`	`string`	`regex` URL 比對器使用的規則運算式。該運算式必須有效，且須與完整 URL 值相符。
`mcp_servers.<id>.identity.url.match`	`exact \| prefix \| regex`	已設定 MCP 伺服器 URL 的比對方式。
`mcp_servers.<id>.identity.url.value`	`string`	供 `exact` 或 `prefix` URL 比對器使用的值。
`model_catalog_json`	`string (path)`	強制指定 Codex 啟動時使用的 JSON 模型目錄。
`models`	`table`	新對話串的受管理模型預設值。這些值的優先順序高於使用者和專案預設值，但建立新對話串時明確選取的設定可將其覆寫。
`models.new_thread`	`table`	啟動新的本機對話串時套用的預設值。每項模型設定皆為選用。
`models.new_thread.model`	`string`	新對話串的預設模型。透過 `--model` 明確指定模型，或透過 `--config` 明確覆寫模型或推理設定時，會優先使用該設定。
`models.new_thread.model_reasoning_effort`	`string`	新對話串的預設推理投入程度。明確覆寫模型或推理投入程度時，會略過兩個受管理的模型欄位。
`models.new_thread.service_tier`	`string`	新對話串的預設服務層級。明確指定的服務層級覆寫具有更高優先順序，且不受模型欄位影響。
`permissions`	`table`	由管理員定義的權限設定檔，以設定檔名稱為索引鍵。使用與 `config.toml` 相同的設定檔欄位。
`permissions.<name>`	`table`	由管理員定義的權限設定檔。名稱不得以 `:` 開頭、使用保留名稱 `filesystem`，也不得與已載入組態中的設定檔同名。使用與 `config.toml` 相同的設定檔欄位；如需完整的設定檔結構描述，請參閱權限指南。
`permissions.filesystem.deny_read`	`array<string>`	由管理員強制執行的檔案系統讀取拒絕規則。項目可以是路徑或 glob 模式，且使用者無法透過本機設定放寬這些規則。
`plugins`	`table`	以外掛程式識別碼為鍵的外掛程式專屬 MCP 伺服器允許清單。若此表格存在，外掛程式隨附的伺服器必須有相符的外掛程式與伺服器項目，否則會停用。
`plugins.<plugin>.mcp_servers`	`table`	單一外掛程式隨附的 MCP 伺服器允許清單。外掛程式伺服器需求使用與頂層 `mcp_servers` 需求相同的精確識別規則與比對器格式。
`plugins.<plugin>.mcp_servers.<server>.identity`	`table`	外掛程式隨附之單一 MCP 伺服器的識別規則。請設定 `command`（stdio）或 `url`（可串流 HTTP）其中之一。
`plugins.<plugin>.mcp_servers.<server>.identity.command`	`string \| table`	以完全相符的指令字串允許外掛程式的 stdio MCP 伺服器，或使用比對器表格，要求執行檔完全相符，並依序比對引數。
`plugins.<plugin>.mcp_servers.<server>.identity.command.args`	`array<table>`	外掛程式隨附的 stdio 伺服器所用的引數比對器，按引數順序排列。所設定的引數清單長度必須與比對器清單相同，且每個位置都必須相符。
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression`	`string`	`regex` 引數比對器所使用的規則運算式。此運算式必須比對完整的引數值。
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match`	`exact \| prefix \| regex`	此引數位置的比對操作。
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value`	`string`	`exact` 或 `prefix` 引數比對器所使用的值。
`plugins.<plugin>.mcp_servers.<server>.identity.command.executable`	`string`	外掛程式隨附的 stdio 伺服器所設定的指令，必須與此執行檔完全相符。
`plugins.<plugin>.mcp_servers.<server>.identity.url`	`string \| table`	以完全相符的 URL 字串允許外掛程式的可串流 HTTP MCP 伺服器，或使用 `exact`、`prefix` 或 `regex` 值比對器表格。
`plugins.<plugin>.mcp_servers.<server>.identity.url.expression`	`string`	`regex` URL 比對器所使用的規則運算式。此運算式必須比對完整的 URL 值。
`plugins.<plugin>.mcp_servers.<server>.identity.url.match`	`exact \| prefix \| regex`	外掛程式隨附的 MCP 伺服器 URL 比對操作。
`plugins.<plugin>.mcp_servers.<server>.identity.url.value`	`string`	`exact` 或 `prefix` URL 比對器所使用的值。
`remote_sandbox_config`	`array<table>`	主機專屬的沙盒需求。第一個 `hostname_patterns` 符合解析後主機名稱的項目，會覆寫該需求來源的頂層 `allowed_sandbox_modes`。主機專屬項目目前只能覆寫沙盒模式。
`remote_sandbox_config[].allowed_sandbox_modes`	`array<string>`	此主機專屬項目相符時，允許套用的沙盒模式。
`remote_sandbox_config[].hostname_patterns`	`array<string>`	不區分大小寫的主機名稱模式。支援以 `*` 代表任意字元序列，以 `?` 代表單一字元。
`rules`	`table`	由管理員強制執行的指令規則，會與 `.rules` 檔案合併。要求中的規則必須具有限制作用。
`rules.prefix_rules`	`array<table>`	強制執行的前綴規則清單。每項規則都必須包含 `pattern` 和 `decision`。
`rules.prefix_rules[].decision`	`prompt \| forbidden`	必填。要求規則只能要求核准或禁止（不能允許）。
`rules.prefix_rules[].justification`	`string`	選填的理由；若提供則不得為空，並會顯示在核准提示或拒絕訊息中。
`rules.prefix_rules[].pattern`	`array<table>`	以模式 Token 表示的指令前綴。每個 Token 都設定 `token` 或 `any_of` 其中一項。
`rules.prefix_rules[].pattern[].any_of`	`array<string>`	此位置允許的替代 Token 清單。
`rules.prefix_rules[].pattern[].token`	`string`	此位置的一個常值 Token。
`sqlite_home`	`string (path)`	強制指定 Codex 儲存以 SQLite 為後端的執行階段狀態所用的目錄。
`windows`	`table`	原生 Windows 沙盒要求。
`windows.allowed_sandbox_implementations`	`array<string>`	允許用於 `windows.sandbox` 的原生 Windows 沙盒實作（`elevated` 和 `unelevated`）。清單不得為空。兩者均獲允許且未選擇模式時，Codex 優先使用 `elevated`。
`windows.sandbox_private_desktop`	`boolean`	強制設定原生 Windows 沙盒是否在私有桌面上啟動其子處理程序。

Key

allow_appshots

Type / Values

boolean

Details

設為 false 可為受管理使用者停用應用程式快照。若省略，應用程式快照不受需求限制，其可用性依產品的一般規則而定。

Key

allow_login_shell

Type / Values

boolean

Details

強制設定 Shell 工具是否可啟動登入 Shell。

Key

allow_managed_hooks_only

Type / Values

boolean

Details

設為 true 時，Codex 會略過使用者、專案、工作階段及外掛程式的掛勾，但仍允許來自 requirements.toml 和其他管理式設定層的管理式掛勾。

Key

allow_remote_control

Type / Values

boolean

Details

設為 false 可為受管理使用者停用裝置遠端控制。若省略，裝置遠端控制不受需求限制，其可用性依產品的一般規則而定。

Key

allowed_approval_policies

Type / Values

array<string>

Details

approval_policy 的允許值，例如 untrusted、on-request、never 和 granular。

Key

allowed_approvals_reviewers

Type / Values

array<string>

Details

approvals_reviewer 的允許值，例如 user 和 auto_review。

Key

allowed_permission_profiles

Type / Values

table<boolean>

Details

允許使用的權限設定檔完整清單。設為 true 的設定檔允許使用。未列出或設為 false 的設定檔皆不允許使用，包括未來版本新增的設定檔。合併要求來源時，會依設定檔名稱比對項目。

Key

allowed_permission_profiles.<name>

Type / Values

boolean

Details

允許或拒絕已載入組態或要求來源中定義的內建或自訂權限設定檔。後續套用且優先順序較高的要求來源，可使用 false 停用先前優先順序較低的來源所允許的設定檔。

Key

allowed_sandbox_modes

Type / Values

array<string>

Details

sandbox_mode 的允許值。

Key

allowed_web_search_modes

Type / Values

array<string>

Details

web_search 的允許值（disabled、cached、indexed、live）。一律允許 disabled；空清單實際上只允許 disabled。

Key

apps

Type / Values

table

Details

受管理的應用程式要求，以應用程式識別碼作為索引鍵。這些要求可停用應用程式，或限制個別工具的核准行為。

Key

apps.<id>.enabled

Type / Values

boolean

Details

設為 false 可停用應用程式。合併多個要求來源時，這項停用要求仍具限制效力。

Key

apps.<id>.tools.<tool>.approval_mode

Type / Values

auto | prompt | writes | approve

Details

設定單一應用程式工具的受管理核准模式。

Key

check_for_update_on_startup

Type / Values

boolean

Details

強制設定 Codex 啟動時是否檢查更新。

Key

computer_use

Type / Values

table

Details

由 requirements.toml 強制執行的電腦功能需求。

Key

computer_use.allow_locked_computer_use

Type / Values

boolean

Details

設為 false 可防止電腦功能在受管理的 macOS 裝置鎖定後繼續運作。若省略，鎖定狀態下使用電腦功能不受需求限制。

Key

default_permissions

Type / Values

string

Details

受管理的預設權限設定檔。此設定檔必須獲 allowed_permission_profiles 允許。請明確設定此項以確保行為可預期；若省略，只有在 :workspace 和 :read-only 均獲明確允許時，Codex 才會預設使用 :workspace。

Key

enforce_residency

Type / Values

string

Details

要求 Codex 服務流量使用受支援的資料駐留位置。目前接受 us。

Key

experimental_network

Type / Values

table

Details

管理員為沙盒內的本機指令設定的網路需求，由 requirements.toml 強制執行。啟用後，即使未使用 features.network_proxy，這些需求也能啟動指令網路代理伺服器。這些需求不會控管網頁搜尋、應用程式、MCP 伺服器、瀏覽器或 Codex 雲端的網路連線。

Key

experimental_network.allow_local_binding

Type / Values

boolean

Details

允許沙盒網路連線存取更廣泛的本機或私有網路。此值維持 false 時，明確指定本機 IP 位址常值或 localhost 的允許規則，仍可放行特定本機目標。

Key

experimental_network.allow_upstream_proxy

Type / Values

boolean

Details

允許沙盒網路連線串接環境中的上游代理伺服器。

Key

experimental_network.allowed_domains

Type / Values

array<string>

Details

受管理的網路代理伺服器啟用時，適用於沙盒內指令網路連線的管理員允許規則。這些規則不適用於網頁搜尋、應用程式或 MCP 伺服器。請勿與 experimental_network.domains 搭配使用。

Key

experimental_network.dangerously_allow_all_unix_sockets

Type / Values

boolean

Details

允許任意 Unix 通訊端目的地，而非僅限允許清單中的目的地。僅限在嚴格控管的環境中使用。

Key

experimental_network.dangerously_allow_non_loopback_proxy

Type / Values

boolean

Details

允許 [experimental_network] 需求使用非回送接聽位址。啟用後，接聽器可能會開放給 localhost 以外的來源存取。

Key

experimental_network.denied_domains

Type / Values

array<string>

Details

管理員的沙盒網路連線拒絕規則，採用清單格式。請勿與 experimental_network.domains 搭配使用。

Key

experimental_network.domains

Type / Values

map<string, allow | deny>

Details

管理員的沙盒網路連線網域原則，採用對應表格式。支援完全相符的主機、僅比對子網域的 *.example.com、同時比對根網域及其子網域的 **.example.com，以及全域 * 允許規則；由於 * 會廣泛開放對公用網路的對外連線，建議使用限定範圍的規則。若有衝突，以 deny 為準。請勿與 experimental_network.allowed_domains 或 experimental_network.denied_domains 搭配使用。

Key

experimental_network.enabled

Type / Values

boolean

Details

啟用沙盒網路連線需求。若作用中的沙盒仍禁止指令連網，這項設定不會授予網路存取權。

Key

experimental_network.http_port

Type / Values

integer

Details

[experimental_network] 需求所使用的回送 HTTP 接聽連接埠。

Key

experimental_network.managed_allowed_domains_only

Type / Values

boolean

Details

設為 true 時，啟用沙盒網路連線需求期間，只有管理員設定的允許規則會維持有效；使用者新增的允許清單項目將遭忽略。若沒有管理員設定的允許規則，使用者新增的網域允許規則也不會繼續生效。

Key

experimental_network.socks_port

Type / Values

integer

Details

[experimental_network] 需求所使用的回送 SOCKS5 接聽連接埠。

Key

experimental_network.unix_sockets

Type / Values

map<string, allow | deny>

Details

管理員為沙盒網路連線設定的 Unix 通訊端原則。

Key

features

Type / Values

table

Details

固定的功能設定值。執行階段功能請使用 config.toml 中的標準名稱；此處也支援文件所載的應用程式專用需求鍵。

Key

features.<name>

Type / Values

boolean

Details

要求文件所載的執行階段或應用程式功能維持啟用或停用狀態。

Key

features.apps

Type / Values

boolean

Details

將受管理使用者的應用程式整合功能固定為啟用或停用。

Key

features.browser_use

Type / Values

boolean

Details

在 requirements.toml 中設為 false 可停用瀏覽器中的電腦功能，並停用瀏覽器智慧體。

Key

features.browser_use_external

Type / Values

boolean

Details

在 requirements.toml 中設為 false 可停用外部瀏覽器中的電腦功能。

Key

features.browser_use_full_cdp_access

Type / Values

boolean

Details

在 requirements.toml 中設為 false 可停用本機執行階段對 Chrome DevTools Protocol 的完整存取，包括瀏覽器開發人員模式，並防止 ChatGPT 桌面版應用程式啟用對應設定。若省略，其可用性依產品的一般規則而定。

Key

features.computer_use

Type / Values

boolean

Details

在 requirements.toml 中設為 false 可停用電腦功能、錄製與重播，以及相關的安裝或啟用流程。

Key

features.fast_mode

Type / Values

boolean

Details

將受管理使用者的標準 fast_mode 功能固定為啟用或停用。

Key

features.guardian_approval

Type / Values

boolean

Details

將受管理使用者的 Guardian 核准功能固定為啟用或停用。

Key

features.in_app_browser

Type / Values

boolean

Details

在 requirements.toml 中設為 false 可停用內建瀏覽器窗格。

Key

features.in_app_updates

Type / Values

boolean

Details

在 requirements.toml 中設為 false 可停用應用程式內更新。若省略此需求，更新預設仍維持啟用。

Key

features.memories

Type / Values

boolean

Details

將受管理使用者的記憶功能固定為啟用或停用。

Key

features.multi_agent

Type / Values

boolean

Details

將受管理使用者的多智慧體功能固定為啟用或停用。

Key

features.plugin_sharing

Type / Values

boolean

Details

在雲端管理的 requirements.toml 中設為 false，即可停用在工作區內分享本機建置外掛程式的功能。

Key

features.plugins

Type / Values

boolean

Details

將受管理使用者的外掛程式功能固定為啟用或停用。

Key

features.remote_plugin

Type / Values

boolean

Details

將受管理使用者的遠端外掛程式目錄固定為啟用或停用。

Key

features.workspace_dependencies

Type / Values

boolean

Details

為受管理使用者固定啟用或停用隨附的工作區相依性執行階段。

Key

feedback

Type / Values

table

Details

受管理的意見回饋設定。

Key

feedback.enabled

Type / Values

boolean

Details

強制設定使用者是否可透過各個 Codex 用戶端提交意見回饋。

Key

guardian_policy_config

Type / Values

string

Details

供自動審查使用的受管理 Markdown 原則指示。此設定的優先順序高於本機 [auto_review].policy。空白值會被忽略。

Key

hooks

Type / Values

table

Details

由管理員強制執行的管理式生命週期掛勾。需要管理式掛勾目錄，並使用與 config.toml 中內嵌 [hooks] 相同的事件結構描述。

Key

hooks.<Event>

Type / Values

array<table>

Details

掛勾事件（例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SessionEnd、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop）的比對器群組。

Key

hooks.<Event>[].hooks

Type / Values

array<table>

Details

比對器群組的掛勾處理常式。支援指令掛勾和 MCP 工具掛勾；提示詞和智慧體掛勾處理常式則會經過剖析，但會略過執行。

Key

hooks.<Event>[].hooks[].additionalContextLimit

Type / Values

integer

Details

每個處理常式的大致 Token 臨界值；additionalContext 超過此值時，會儲存至磁碟，並向模型顯示較短的預覽。預設為 2500；設為 0 會將完整上下文直接傳給模型。請參閱大型掛勾輸出。

Key

hooks.<Event>[].hooks[].async

Type / Values

boolean

Details

在背景執行指令掛勾，不延遲觸發該掛勾的作業。預設為 false；SessionEnd 一律同步執行。請參閱在背景執行掛勾。

Key

hooks.<Event>[].hooks[].commandWindows

Type / Values

string

Details

指令掛勾的 Windows 專用指令覆寫值。也接受 TOML 別名 command_windows。

Key

hooks.managed_dir

Type / Values

string (absolute path)

Details

macOS 和 Linux 上存放管理式掛勾指令碼的目錄。Codex 會在載入管理式掛勾前，驗證目錄路徑為絕對路徑，且該目錄存在。

Key

hooks.windows_managed_dir

Type / Values

string (absolute path)

Details

Windows 上存放管理式掛勾指令碼的目錄。Codex 會在載入管理式掛勾前，驗證目錄路徑為絕對路徑，且該目錄存在。

Key

log_dir

Type / Values

string (path)

Details

強制指定 Codex 寫入本機記錄檔的目錄。

Key

marketplaces

Type / Values

table

Details

外掛程式市集來源的管理員要求。restrict_to_allowed_sources 設為 true 時，規則會生效。

Key

marketplaces.allowed_sources

Type / Values

table

Details

允許的市集來源以管理員選定的規則名稱作為索引鍵。名稱不同的規則會跨要求層累加；相同名稱下的欄位則採用一般的分層優先順序。

Key

marketplaces.allowed_sources.<name>

Type / Values

table

Details

一項允許來源的規則。合併要求後的最終 source 值，決定 Codex 會解讀哪些同層欄位。

Key

marketplaces.allowed_sources.<name>.host_pattern

Type / Values

string

Details

當 source = "host_pattern" 時，必須提供規則運算式。Codex 會以此比對從 HTTPS、SSH 或 SCP 樣式的 Git 來源剖析出的全小寫主機名稱。使用 ^ 和 $ 可要求整個主機名稱完全相符。

Key

marketplaces.allowed_sources.<name>.path

Type / Values

string (absolute path)

Details

當 source = "local" 時，必須提供本機市集目錄。Codex 要求使用絕對路徑，並在路徑正規化後進行比較。

Key

marketplaces.allowed_sources.<name>.ref

Type / Values

string

Details

git 規則可選擇指定必須完全相符的 Git ref。若省略，規則會允許相符程式碼庫的任何 ref。

Key

marketplaces.allowed_sources.<name>.source

Type / Values

git | host_pattern | local

Details

市集來源的比對器類型。單一程式碼庫使用 git，以規則運算式比對 Git 主機使用 host_pattern，單一目錄則使用 local。

Key

marketplaces.allowed_sources.<name>.url

Type / Values

string

Details

當 source = "git" 時，必須提供 Git 程式碼庫 URL。Codex 會先將已設定的 URL 與允許的 URL 正規化，再要求程式碼庫完全相符。

Key

marketplaces.restrict_to_allowed_sources

Type / Values

boolean

Details

設為 true 時，使用者設定的市集來源必須符合 allowed_sources，才能執行新增市集、安裝外掛程式及重新整理已設定的 Git 市集等操作。由 Codex 管理的 OpenAI 市集，只要來源與名稱符合保留值，仍可使用。這不會在執行階段篩選使用者已設定的市集。

Key

mcp_servers

Type / Values

table

Details

可啟用 MCP 伺服器的允許清單。伺服器名稱（<id>）與識別資訊都必須相符，才能啟用 MCP 伺服器。任何不在允許清單中的已設定 MCP 伺服器，或識別資訊不符的伺服器，都會停用。

Key

mcp_servers.<id>.identity

Type / Values

table

Details

單一 MCP 伺服器的識別規則。請設定 command（stdio）或 url（可串流 HTTP）其中之一。

Key

mcp_servers.<id>.identity.command

Type / Values

string | table

Details

以完全相符的指令字串允許 MCP stdio 伺服器，或使用比對器表格，要求可執行檔完全相符，且引數須依序符合比對器條件。字串形式不會檢查引數、cwd、env 或 env_vars。

Key

mcp_servers.<id>.identity.command.args

Type / Values

array<table>

Details

stdio 伺服器依序排列的引數比對器。已設定的引數清單長度必須相同，且每個位置都必須相符。指令比對器不會檢查 cwd、env 或 env_vars。

Key

mcp_servers.<id>.identity.command.args[].expression

Type / Values

string

Details

regex 引數比對器使用的規則運算式。該運算式必須有效，且須與完整引數值相符。

Key

mcp_servers.<id>.identity.command.args[].match

Type / Values

exact | prefix | regex

Details

此引數位置的比對方式。

Key

mcp_servers.<id>.identity.command.args[].value

Type / Values

string

Details

供 exact 或 prefix 引數比對器使用的值。

Key

mcp_servers.<id>.identity.command.executable

Type / Values

string

Details

stdio 伺服器設定中的 command 必須完全符合的可執行檔。

Key

mcp_servers.<id>.identity.url

Type / Values

string | table

Details

以完全相符的 URL 字串允許 MCP 可串流 HTTP 伺服器，或使用 exact、prefix 或 regex 值比對器表格。

Key

mcp_servers.<id>.identity.url.expression

Type / Values

string

Details

regex URL 比對器使用的規則運算式。該運算式必須有效，且須與完整 URL 值相符。

Key

mcp_servers.<id>.identity.url.match

Type / Values

exact | prefix | regex

Details

已設定 MCP 伺服器 URL 的比對方式。

Key

mcp_servers.<id>.identity.url.value

Type / Values

string

Details

供 exact 或 prefix URL 比對器使用的值。

Key

model_catalog_json

Type / Values

string (path)

Details

強制指定 Codex 啟動時使用的 JSON 模型目錄。

Key

models

Type / Values

table

Details

新對話串的受管理模型預設值。這些值的優先順序高於使用者和專案預設值，但建立新對話串時明確選取的設定可將其覆寫。

Key

models.new_thread

Type / Values

table

Details

啟動新的本機對話串時套用的預設值。每項模型設定皆為選用。

Key

models.new_thread.model

Type / Values

string

Details

新對話串的預設模型。透過 --model 明確指定模型，或透過 --config 明確覆寫模型或推理設定時，會優先使用該設定。

Key

models.new_thread.model_reasoning_effort

Type / Values

string

Details

新對話串的預設推理投入程度。明確覆寫模型或推理投入程度時，會略過兩個受管理的模型欄位。

Key

models.new_thread.service_tier

Type / Values

string

Details

新對話串的預設服務層級。明確指定的服務層級覆寫具有更高優先順序，且不受模型欄位影響。

Key

permissions

Type / Values

table

Details

由管理員定義的權限設定檔，以設定檔名稱為索引鍵。使用與 config.toml 相同的設定檔欄位。

Key

permissions.<name>

Type / Values

table

Details

由管理員定義的權限設定檔。名稱不得以 : 開頭、使用保留名稱 filesystem，也不得與已載入組態中的設定檔同名。使用與 config.toml 相同的設定檔欄位；如需完整的設定檔結構描述，請參閱權限指南。

Key

permissions.filesystem.deny_read

Type / Values

array<string>

Details

由管理員強制執行的檔案系統讀取拒絕規則。項目可以是路徑或 glob 模式，且使用者無法透過本機設定放寬這些規則。

Key

plugins

Type / Values

table

Details

以外掛程式識別碼為鍵的外掛程式專屬 MCP 伺服器允許清單。若此表格存在，外掛程式隨附的伺服器必須有相符的外掛程式與伺服器項目，否則會停用。

Key

plugins.<plugin>.mcp_servers

Type / Values

table

Details

單一外掛程式隨附的 MCP 伺服器允許清單。外掛程式伺服器需求使用與頂層 mcp_servers 需求相同的精確識別規則與比對器格式。

Key

plugins.<plugin>.mcp_servers.<server>.identity

Type / Values

table

Details

外掛程式隨附之單一 MCP 伺服器的識別規則。請設定 command（stdio）或 url（可串流 HTTP）其中之一。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command

Type / Values

string | table

Details

以完全相符的指令字串允許外掛程式的 stdio MCP 伺服器，或使用比對器表格，要求執行檔完全相符，並依序比對引數。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.args

Type / Values

array<table>

Details

外掛程式隨附的 stdio 伺服器所用的引數比對器，按引數順序排列。所設定的引數清單長度必須與比對器清單相同，且每個位置都必須相符。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression

Type / Values

string

Details

regex 引數比對器所使用的規則運算式。此運算式必須比對完整的引數值。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match

Type / Values

exact | prefix | regex

Details

此引數位置的比對操作。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value

Type / Values

string

Details

exact 或 prefix 引數比對器所使用的值。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.executable

Type / Values

string

Details

外掛程式隨附的 stdio 伺服器所設定的指令，必須與此執行檔完全相符。

Key

plugins.<plugin>.mcp_servers.<server>.identity.url

Type / Values

string | table

Details

以完全相符的 URL 字串允許外掛程式的可串流 HTTP MCP 伺服器，或使用 exact、prefix 或 regex 值比對器表格。

Key

plugins.<plugin>.mcp_servers.<server>.identity.url.expression

Type / Values

string

Details

regex URL 比對器所使用的規則運算式。此運算式必須比對完整的 URL 值。

Key

plugins.<plugin>.mcp_servers.<server>.identity.url.match

Type / Values

exact | prefix | regex

Details

外掛程式隨附的 MCP 伺服器 URL 比對操作。

Key

plugins.<plugin>.mcp_servers.<server>.identity.url.value

Type / Values

string

Details

exact 或 prefix URL 比對器所使用的值。

Key

remote_sandbox_config

Type / Values

array<table>

Details

主機專屬的沙盒需求。第一個 hostname_patterns 符合解析後主機名稱的項目，會覆寫該需求來源的頂層 allowed_sandbox_modes。主機專屬項目目前只能覆寫沙盒模式。

Key

remote_sandbox_config[].allowed_sandbox_modes

Type / Values

array<string>

Details

此主機專屬項目相符時，允許套用的沙盒模式。

Key

remote_sandbox_config[].hostname_patterns

Type / Values

array<string>

Details

不區分大小寫的主機名稱模式。支援以 * 代表任意字元序列，以 ? 代表單一字元。

Key

rules

Type / Values

table

Details

由管理員強制執行的指令規則，會與 .rules 檔案合併。要求中的規則必須具有限制作用。

Key

rules.prefix_rules

Type / Values

array<table>

Details

強制執行的前綴規則清單。每項規則都必須包含 pattern 和 decision。

Key

rules.prefix_rules[].decision

Type / Values

prompt | forbidden

Details

必填。要求規則只能要求核准或禁止（不能允許）。

Key

rules.prefix_rules[].justification

Type / Values

string

Details

選填的理由；若提供則不得為空，並會顯示在核准提示或拒絕訊息中。

Key

rules.prefix_rules[].pattern

Type / Values

array<table>

Details

以模式 Token 表示的指令前綴。每個 Token 都設定 token 或 any_of 其中一項。

Key

rules.prefix_rules[].pattern[].any_of

Type / Values

array<string>

Details

此位置允許的替代 Token 清單。

Key

rules.prefix_rules[].pattern[].token

Type / Values

string

Details

此位置的一個常值 Token。

Key

sqlite_home

Type / Values

string (path)

Details

強制指定 Codex 儲存以 SQLite 為後端的執行階段狀態所用的目錄。

Key

windows

Type / Values

table

Details

原生 Windows 沙盒要求。

Key

windows.allowed_sandbox_implementations

Type / Values

array<string>

Details

允許用於 windows.sandbox 的原生 Windows 沙盒實作（elevated 和 unelevated）。清單不得為空。兩者均獲允許且未選擇模式時，Codex 優先使用 elevated。

Key

windows.sandbox_private_desktop

Type / Values

boolean

Details

強制設定原生 Windows 沙盒是否在私有桌面上啟動其子處理程序。

建議

開始使用

Core concepts

SDKs and CLI

資源

Legacy APIs

Choose a model

Text and code

提示詞

Reasoning

Images and video

Realtime and audio

Specialized models

Agents SDK

ChatKit

Search and retrieval

Connect tools and data

Build tool workflows

Computer and code

Media

開始使用

Audio

Connection methods

Sessions and operations

Go live

Performance and quality

Cost and throughput

Safety and governance

Infrastructure and access

營運

Core concepts

Plan

Build

Test and publish

Conversion specs

指南

資源

開始使用

指南

File Upload

API

Measurement

Advertiser API

API 參考文件

開始使用

基礎

探索

適用平台

版本資訊

工作流程

能力

參考資料

自訂

設定檔

智慧體組態

擴充 ChatGPT 與 Codex 的功能

Linux

Windows

開發工作流程

擴充與自動化

環境

使用 Codex 進行建置

第三方整合

參考資料

權限

Codex Security

網路安全

開始使用

身分識別與身分驗證

工作區存取權、政策與模型

外掛程式與連接器控制措施

使用情況、治理與合規

部署與模型供應商

社群

部落格

社群

部落格

最近搜尋

Topics

Topics

`config.toml`

`requirements.toml`