設定參考
Codex config.toml 和 requirements.toml 的完整參考
將此頁面用作 Codex 設定檔的可搜尋參考。如需概念指導和範例,請先參閱設定基礎和高階設定。
通過 Work Cloud 存取本機電腦的設定
啟用通過 Work Cloud 存取本機電腦的功能後,OpenAI 雲端負責協調任務,受支援的工具則在雲端或所連線的電腦上執行。要求用於設定限制;設定值用於提供預設值。
使用策略 API 管理 Global 設定。要管理 Local 或 Codex Cloud 設定,請使用 Agent Security 介面。遷移後,現有的 Global API 工作流程仍然可用。請測試你的指令碼和 Terraform 整合,並確認策略分配及排序保持不變。支援某個 requirements.toml 欄位本身並不能證明 API 相容性。
| 設定或設定類別 | 通過 Work Cloud 存取本機電腦時的作用域 | 指南 |
|---|---|---|
| 審批策略和審查要求 | 啟用受管策略時的 Global 編排器策略 | 將審批和審查控制保留在 Global 中。環境覆蓋設定無法更改編排器控制。本機執行與雲容器執行具有各自獨立的策略作用域。 |
| 受管應用、MCP server、外掛、市場和命令規則 | Global 策略 | 將這些控制保留在全域作用域中。不要將欄位出現在資料結構中視為可以按環境編輯該欄位的證明。 |
| 檔案、沙箱和可跨環境使用的網路要求 | 本機執行 | 對於本機執行,MDM 和舊版受管裝置要求的優先順序高於 Agent Security。裝置的系統要求檔案的優先順序低於 Agent Security。新的企業 requirements.toml 設定不適用於 Work 雲容器,後者保留現有的 Work Cloud 策略。 |
| 特定平台的執行器控制 | 執行該步驟的電腦 | 支援情況取決於執行器和平台。 |
| 受管鉤子 | 啟用後,管理員定義的 MCP 鉤子會針對受支援的生命週期事件和工具事件在雲端協調器(編排器)上執行。 | 在依賴這些鉤子之前,請測試回呼連線,確認其接收的事件,並檢查失敗會如何影響任務。MCP 鉤子無法提供完整的 Compliance API 審計跟蹤記錄。雲端編排不支援命令鉤子、本機設定鉤子和外掛鉤子,即使工具在本機執行也是如此。對於編排和執行均在本機進行的純本機 Work 和 Codex 執行緒,現有的受支援鉤子仍然適用。 |
| 代理監聽地址、埠和程序設定 | 不屬於可跨環境使用的環境策略 | 雲端執行時不支援受管 HTTP/SOCKS 監聽埠和非迴環代理監聽器;套接字規則的支援情況取決於執行路徑。自定義代理設定與受支援的目標地址限制相互獨立。 |
| 僅適用於應用的設定和普通本機預設值 | 雲端協調不一定使用這些設定 | 即使通過 Work Cloud 存取本機電腦的功能不使用應用強制實施的控制,這些控制仍可能有效。雲端交付和雲端瀏覽器行為需要單獨驗證。 |
通過 Work Cloud 存取本機電腦的 Agent Security 要求
對於具有本機存取權限的 Work 和 dots,啟用受管策略後,受支援的 Global 策略會應用於共享的雲端編排器。本機執行要求約束所連線的電腦。Work 雲容器和 dots 雲電腦使用各自的執行設定和要求。請分別測試本機和雲端控制措施。
Agent Security UI 中提供的設定
- 允許的審批策略
- 允許的網頁搜尋模式
通過 TOML 設定的設定
allowed_approvals_reviewersauto_reviewguardian_policy_configappsmcp_serverspluginsrules
這些編排器要求保留在 Global 中。它們不會設定共享雲端功能的權限,也不會使本機執行設定可移植到 Work 雲容器或 dots 雲電腦。
通過 Work Cloud 存取本機電腦的相容性限制
是否支援取決於欄位、策略的下發方式以及任務的執行位置。啟用同步前,請檢查成員實際生效的策略。如表中所述,某些控制措施需要在你的部署環境中測試。
在同一策略內,優先順序從高到低依次為:特定作業系統的環境覆蓋 → 所有作業系統的環境覆蓋 → Global。即使較低優先順序的策略更具體,仍以較高優先順序的策略為準。
對於本機執行,MDM 和舊版受管裝置要求的優先順序高於 Agent Security,而 Agent Security 的優先順序高於裝置的系統要求檔案。某些要求(包括網路要求)具有特定於欄位的合併規則和執行時限制。範例請參閱受管設定。
| 設定或設定類別 | 通過 Work Cloud 存取本機電腦的相容性 | 管理員指導 |
|---|---|---|
sqlite_home, log_dir, model_catalog_json |
不支援用作受管雲端覆蓋。 | 本機路徑無法更改雲端儲存或日誌的位置。本機模型目錄不會沿用到雲端。 |
model_provider, model_providers |
通過 Work Cloud 存取本機電腦的受管要求或設定不支援這些欄位。 | 自定義推理閘道器和供應商連線不會通過這些欄位沿用到雲端。這與模型選擇是兩回事。 |
enforce_residency |
在任一雲端策略中啟用時,會阻止通過 Work Cloud 存取本機電腦。 | 如果在任一雲端策略中啟用 enforce_residency,Work 和 dots 的允許存取本機電腦 都會被停用。此保護措施不會設定工作區的資料駐留位置,也不會單獨停用 Work Cloud 或 dots。 |
application.network.enabled 和 application.network.domains |
通過 Work Cloud 存取本機電腦不支援這些欄位。 | 請勿將這些應用目標地址限制用作通過 Work Cloud 存取本機電腦時的命令網路控制措施。 |
allow_browser_and_computer_use, in_app_browser, additional_developer_instructions |
雲端策略下發需要驗證。通過 Work Cloud 存取本機電腦會拒絕這些受管要求鍵。 | 瀏覽器限制在應用端有檢查機制。這並不能證明策略會下發到雲端或在雲端瀏覽器中強制執行。additional_developer_instructions 需要編排器支援。 |
experimental_network 和 permissions.<profile>.network |
部分支援。受支援的目標地址和執行器限制與自定義代理設定不同。 | 雲端執行時不支援受管 HTTP/SOCKS 監聽埠和非迴環代理監聽器;套接字規則的支援情況取決於執行路徑。本機執行的合併行為需單獨考慮。命令網路限制不會停用受管搜尋、MCP 或應用工具。 |
功能 / feature_requirements, 模型, computer_use |
部分支援。 | 已停用的開關會被拒絕,例如 tool_search = false、tool_search_always_defer_mcp_tools = false、js_repl = true 和 remote_control = true。某些電腦使用設定仍需進行端到端驗證。 |
browser_use, allow_appshots, 回饋, allow_remote_control, 市場來源限制 |
在某些策略下發路徑中,應用或 app-server 會強制執行這些控制措施。 | 即使通過 Work Cloud 存取本機電腦時忽略某個欄位,應用控制措施仍可能生效。桌面瀏覽器站點規則不適用於 Work 雲容器。請驗證實際介面和策略下發路徑。 |
設定資料結構包含的某些鍵可能不適用於通過 Work Cloud 存取本機電腦,或不支援環境覆蓋。有關全域基線和優先順序,請參閱受管設定。
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 會忽略它們;請改為將供應商、通知和遙測
鍵放在使用者級設定中。設定設定檔以
$CODEX_HOME/profile-name.config.toml 的形式與 config.toml 位於同一位置;使用
--profile profile-name 選擇一個設定檔。
對於沙箱和審批鍵(approval_policy、sandbox_mode 和 sandbox_workspace_write.*),請將本參考與沙箱和審批、可寫根目錄中的受保護路徑及網路存取配合使用。有關測試版權限設定檔,請參閱權限。
Codex 和 ChatGPT Work 不再支援 approval_policy = "untrusted"。
請移除該設定,或選擇受支援的策略。專案條目中設定的
trust_level = "untrusted" 在使用者級 ~/.codex/config.toml 中仍受支援。請參閱
從已停用的 untrusted 審批策略遷移,
瞭解範例及審批方式的權衡。
將 model 設定為你已登入的帳戶或工作區可用的模型。使用範例值前,請參閱
GPT-6.1 Sol 可用性。
| 鍵 | 類型 / 值 | 詳細資訊 |
|---|---|---|
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 |
啟用或停用此電腦或設定檔的分析功能。在 Codex CLI 中,false 還會停用自定義 OTLP 指標匯出器。未設定時,使用客戶端預設值。 |
approval_policy |
on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } } |
控制 Codex 何時在執行命令前暫停以請求審批。你也可以使用 approval_policy = { granular = { ... } } 允許或自動拒絕特定類別的提示,同時保留其他提示的互動式審批。untrusted 不受支援,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.extra_policy |
string |
用於自動審查的附加本機 Markdown 策略,與主策略一同納入審查。受管理的 guardian_extra_policy 優先。空白值會被忽略。 |
auto_review.policy |
string |
用於自動審查的本機 Markdown 策略指令。受管理的 guardian_policy_config 優先。空白值會被忽略。 |
background_terminal_max_timeout |
number |
空 write_stdin 輪詢(後臺終端輪詢)的最長輪詢視窗,以毫秒為單位。預設值:300000(5 分鐘)。替代舊版 background_terminal_timeout 鍵。 |
browser_use.allow_history_access |
boolean |
設為 false 可限制瀏覽器歷史記錄存取。受管理要求可以強制實施此限制。 |
browser_use.default_origin_policy |
table |
預設瀏覽器源限制。支援 access、uploads、downloads 和 full_cdp_access,每項均可設為 allow 或 deny。 |
browser_use.origins.<origin> |
table |
針對各個源的瀏覽器限制,欄位與 browser_use.default_origin_policy 相同。需包含 HTTP 或 HTTPS 協議方案,可選填埠;不包含路徑、查詢參數和片段。本機值不能放寬受管理的拒絕規則。 |
chatgpt_base_url |
string |
覆蓋 ChatGPT 登入流程中使用的基礎 URL。 |
check_for_update_on_startup |
boolean |
啟動時檢查 Codex 更新(僅在集中管理更新時才設為 false)。 |
cli_auth_credentials_store |
file | keyring | auto | ephemeral |
控制 CLI 儲存快取憑據的位置。 |
compact_prompt |
string |
歷史記錄壓縮提示詞的內聯覆蓋設定。 |
computer_use.default_app_access |
allow | deny |
Computer Use 的預設原生應用存取策略。應用專屬條目可以提供策略;本機設定不能放寬受管理的限制。 |
computer_use.macos.bundle_ids |
map<string, allow | deny> |
以 bundle identifier 為鍵的原生 macOS 應用存取設定。 |
computer_use.windows.always_allowed_app_ids |
array<string> |
Computer Use 無需提示即可開啟的 Windows 應用識別符。不在列表中的應用需要審批;可在 ChatGPT 桌面應用的 Computer Use 設定中移除已儲存的條目。 |
computer_use.windows.aumids |
map<string, allow | deny> |
以 Application User Model ID(AUMID)為鍵的打包 Windows 應用存取設定。 |
computer_use.windows.exes |
array<table> |
Windows 執行檔存取規則。每條規則必須包含 publisher_name、product_name 和 access(allow 或 deny);binary_name 為可選項。 |
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.disable_paste_burst 的舊版後備設定。建議使用 [tui] 下的設定。 |
experimental_compact_prompt_file |
string (path) |
從檔案載入壓縮提示詞覆蓋設定(實驗性)。 |
experimental_use_unified_exec_tool |
boolean |
啟用統一 exec 的舊版名稱;請優先使用 [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.context_management.experimental_mode |
boolean |
實驗性上下文管理設定。此功能目前不可用。 |
features.enable_request_compression |
boolean |
在受支援時使用 zstd 壓縮流式請求體(穩定功能;預設開啟)。 |
features.fast_mode |
boolean |
啟用當前模型宣告支援的 Fast 模式控制項(穩定功能;預設開啟),獨立於 features.ultrafast_mode。是否可用仍取決於模型和帳戶。 |
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.prefer_mxc |
boolean |
原生能力和策略允許時,本機 Windows 執行優先使用 MXC;否則保留已設定的舊版沙箱和設定。在獨立 CLI 中預設停用;桌面應用可以通過功能發布設定啟用。命令失敗不會觸發回退。 |
features.prevent_idle_sleep |
boolean |
在輪次執行期間防止電腦休眠(實驗性;預設關閉)。 |
features.remote_plugin |
boolean |
啟用遠端外掛目錄(穩定功能;預設開啟)。 |
features.rollout_budget.enabled |
boolean |
啟用 rollout 預算跟蹤。此功能正在開發中,預設關閉。啟用後,必須設定 features.rollout_budget.limit_tokens。 |
features.rollout_budget.limit_tokens |
integer |
rollout 預算跟蹤的 token 上限,必須為正數。啟用 rollout 預算時必填。 |
features.rollout_budget.prefill_token_weight |
number |
rollout 預算核算中預填充 token 的有限非負乘數。預設為 1.0。 |
features.rollout_budget.reminder_interval_tokens |
integer |
rollout 預算提醒之間的 token 間隔,必須為正數。預設為 limit_tokens 的 10%,最少為 1 個 token。 |
features.rollout_budget.sampling_token_weight |
number |
rollout 預算核算中取樣 token 的有限非負乘數。預設為 1.0。 |
features.shell_snapshot |
boolean |
為 shell 環境建立快照,以加快重複命令的執行(穩定功能;預設開啟)。 |
features.shell_tool |
boolean |
啟用命令執行工具(穩定功能;預設開啟)。 |
features.skill_mcp_dependency_install |
boolean |
允許提示並安裝技能缺失的 MCP 依賴項(穩定功能;預設開啟)。 |
features.ultrafast_mode |
boolean |
啟用 Ultrafast 模式控制項(穩定功能;預設開啟),獨立於 features.fast_mode。是否可用仍取決於模型和帳戶。 |
features.unified_exec |
boolean |
使用可恢復的命令執行(穩定功能;在所有平台上啟用)。使用者停用此功能的設定會被忽略。受管要求可以停用可恢復程序和 write_stdin,同時保留一次性的 exec_command。 |
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 或 Interrupt。 |
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。 |
marketplaces.<name>.ref |
string |
市場的可選 Git 分支、標籤或提交。 |
marketplaces.<name>.source |
string |
Git 儲存庫位置或本機市場根目錄。本機來源需使用絕對路徑;該目錄包含 .agents/plugins/marketplace.json。 |
marketplaces.<name>.source_type |
git | local |
已設定外掛市場的來源類型。市場可以在系統、雲端管理、使用者或受信任專案的 config.toml 中定義。 |
marketplaces.<name>.sparse_paths |
array<string> |
Git 市場的可選稀疏檢出路徑。需包含市場目錄檔案及其引用的所有本機外掛目錄。 |
mcp_oauth_callback_port |
integer |
MCP OAuth 登入期間使用的本機 HTTP 回呼伺服器的可選全域固定埠。伺服器專屬的 oauth.callback_port 優先。兩者均未設定時,Codex 會繫結到作業系統選擇的臨時埠。 |
mcp_oauth_callback_url |
string |
MCP OAuth 登入的可選基礎回呼 URL,例如 devbox 入口 URL。當授權伺服器支援頒發者識別時,新新增的預註冊客戶端會直接使用此 URL;未儲存回呼的現有客戶端會在其後附加伺服器專屬回呼 ID。不支援頒發者識別時,任何已設定回呼缺少所需 ID 的預註冊 MCP server都會回退到此 URL,並在其後附加該 ID。回呼 URL 中的埠不會決定監聽埠。 |
mcp_oauth_credentials_store |
auto | file | keyring |
MCP OAuth 憑據的首選儲存位置。 |
mcp_optional_startup_grace_ms |
integer (milliseconds) |
建置初始工具目錄時,可選 MCP server共用的等待時間。預設為 1000。設為 0 則改為按各伺服器的 startup_timeout_sec 等待。 |
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 server的 enabled_tools 之後應用的拒絕列表。 |
mcp_servers.<id>.enabled |
boolean |
停用 MCP server,但不移除其設定。 |
mcp_servers.<id>.enabled_tools |
array<string> |
MCP server暴露的工具名稱允許列表。 |
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 server的實驗性執行位置設定。remote 通過遠端執行器環境啟動 stdio 伺服器;尚未實現可流式 HTTP 的遠端執行。 |
mcp_servers.<id>.http_headers |
map<string,string> |
每個 MCP HTTP 請求中包含的靜態 HTTP 請求頭。 |
mcp_servers.<id>.http_headers_helper |
string (command) |
輸出包含 HTTP 請求頭名稱和值的 JSON 物件的本機命令。僅支援本機連線的 HTTP MCP server。顯式指定的 bearer token 和 OAuth 憑據優先於輔助程式提供的 Authorization 請求頭。 |
mcp_servers.<id>.oauth_resource |
string |
MCP 登入期間包含的可選 RFC 8707 OAuth 資源參數。 |
mcp_servers.<id>.oauth.callback_port |
integer |
此 MCP server的固定 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 server請求授權和交換令牌。 |
mcp_servers.<id>.oauth.client_secret |
string |
使用預註冊客戶端交換令牌時所需的 OAuth 客戶端金鑰。要求 oauth.client_id 非空;金鑰也必須非空。儲存在設定中。 |
mcp_servers.<id>.required |
boolean |
設為 true 時,如果此已啟用的 MCP server無法初始化,則啟動或恢復失敗。 |
mcp_servers.<id>.scopes |
array<string> |
向該 MCP server進行身份驗證時請求的 OAuth 作用域。 |
mcp_servers.<id>.startup_timeout_ms |
number |
startup_timeout_sec 的別名,以毫秒為單位。 |
mcp_servers.<id>.startup_timeout_sec |
number |
覆蓋 MCP server預設的 10 秒啟動超時。 |
mcp_servers.<id>.tool_timeout_sec |
number |
覆蓋 MCP server預設的 60 秒單工具超時。 |
mcp_servers.<id>.tools.<tool>.approval_mode |
auto | prompt | writes | approve |
此伺服器上單個 MCP 工具的審批行為覆蓋設定。 |
mcp_servers.<id>.tools.<tool>.output_token_limit |
integer (positive) |
單個 MCP 工具輸出的 token 預算,尚未計入標準的 20% 序列化餘量。覆蓋模型對此工具的預設輸出截斷預算。 |
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 |
每次啟動處理的候選 rollout 數量上限。預設為 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-6.1-sol)。 |
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> |
傳遞給令牌命令的參數。 |
model_providers.<id>.auth.command |
string |
Codex 需要 bearer token 時執行的命令。該命令必須將令牌輸出到 stdout。 |
model_providers.<id>.auth.cwd |
string (path) |
令牌命令的工作目錄。 |
model_providers.<id>.auth.refresh_interval_ms |
number |
Codex 主動重新整理令牌的時間間隔,以毫秒為單位(預設值:300000)。設為 0 可僅在身份驗證重試後重新整理。 |
model_providers.<id>.auth.timeout_ms |
number |
令牌命令的最長執行時間,以毫秒為單位(預設值:5000)。 |
model_providers.<id>.base_url |
string |
模型供應商的 API 基礎 URL。 |
model_providers.<id>.capabilities.external_web_access |
boolean |
供應商託管的網頁搜尋是否可以存取即時網頁。省略時保留供應商預設值;模型和輪次設定可能進一步限制存取。 |
model_providers.<id>.capabilities.remote_compaction |
unsupported | v2 |
供應商的壓縮協議。unsupported 使用本機壓縮;v2 通過 Responses 傳送壓縮觸發請求。省略時保留供應商預設值;模型和輪次設定可能進一步限制支援範圍。 |
model_providers.<id>.env_http_headers |
map<string,string> |
在相應環境變數存在時,從中填充的 HTTP 請求頭。 |
model_providers.<id>.env_key |
string |
提供該供應商 API key 的環境變數。 |
model_providers.<id>.env_key_instructions |
string |
該供應商 API key 的可選設定指引。 |
model_providers.<id>.experimental_bearer_token |
string |
直接指定的供應商 bearer token(不推薦;請使用 env_key)。 |
model_providers.<id>.http_headers |
map<string,string> |
新增到供應商請求的靜態 HTTP 請求頭。 |
model_providers.<id>.model_catalog_url |
string |
Codex 原生模型目錄的完整 URL。省略時保留供應商的預設模型發現方式。 |
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 |
string |
所選模型宣告支援的推理強度,例如 low、medium、high、xhigh、max 或 ultra。可用級別取決於模型和客戶端。 |
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> |
以 old->new 對映記錄已確認的模型遷移。 |
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)。在 Codex CLI 中,analytics.enabled = false 會停用此匯出器,包括自定義 OTLP 匯出器。設為 none 可單獨停用指標匯出。 |
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 |
命名的檔案系統權限設定檔。每個鍵都是絕對路徑,或 :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 模式或特殊標記授予直接存取權限,或限定該根目錄下巢狀條目的作用範圍。使用 "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 server。 |
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 |
已棄用的相容性設定。friendly 和 pragmatic 不再用於選擇風格。none 會從模型指令中省略內建的 Personality 部分;顯式指令覆蓋設定不受影響。 |
plan_mode_reasoning_effort |
string |
計劃模式專用的推理覆蓋設定,使用所選模型支援的級別。未設定時,計劃模式使用其內建預設組態的預設值。 |
plugins.<plugin>.enabled |
boolean |
使用 plugin-name@marketplace-name 鍵啟用或停用本機市場外掛。從合併後的有效設定中讀取;受信任專案的設定可以覆蓋使用者、雲端管理和系統預設值。即使外掛已停用,市場重新整理仍可安裝或重新整理已設定的外掛。此設定不會覆蓋工作區管理的啟用狀態。 |
plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode |
auto | prompt | writes | approve |
外掛提供的 MCP server上工具的預設審批行為。 |
plugins.<plugin>.mcp_servers.<server>.disabled_tools |
array<string> |
在外掛提供的 MCP server的 enabled_tools 之後應用的拒絕列表。 |
plugins.<plugin>.mcp_servers.<server>.enabled |
boolean |
啟用或停用已安裝外掛捆綁的 MCP server,而無需更改外掛清單。 |
plugins.<plugin>.mcp_servers.<server>.enabled_tools |
array<string> |
外掛提供的 MCP server所暴露工具的允許列表。 |
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 的技能資料夾路徑。 |
skills.max_context_tokens |
integer (positive) |
可用技能目錄的 token 預算。預設為模型上下文視窗的 2%。顯式設定的值最多為 10000 個 token。 |
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 server。 |
tui |
table |
TUI 專用選項,例如啟用內聯桌面通知。 |
tui.alternate_screen |
auto | always | never |
控制 TUI 是否使用備用螢幕(預設值:auto;auto 在 Zellij 中會跳過備用螢幕,以保留終端回看歷史)。 |
tui.animations |
boolean |
啟用終端動畫(歡迎介面、微光效果、載入動畫)(預設值:true)。 |
tui.auto_recap |
boolean |
在終端失去焦點時自動生成對話回顧(預設值:true)。設為 false 可停用自動回顧;/recap 仍然可用。 |
tui.disable_paste_burst |
boolean |
停用 TUI 中的突發貼上檢測(預設值:false)。優先於舊版頂層 disable_paste_burst 設定。 |
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_server_version_notice |
boolean |
顯示關於所連線 app-server 版本差異的資訊提示(預設值:true)。不會隱藏相容性錯誤或版本狀態。 |
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 |
mxc | elevated | unelevated |
原生 Windows 沙箱實現。當 MXC 不可用或被受管理要求禁止時,顯式選擇 mxc 會失敗。將 features.prefer_mxc 與舊版選項配合使用,可自動選擇 MXC 並在必要時回退。 |
沒有相符的設定選項。
你可以在此處找到 config.toml 的最新 JSON Schema。
要在 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 和 Enterprise 使用者,Codex 還可以應用從雲端取得的 要求。有關優先順序的詳細資訊,請參閱安全頁面。
在 requirements.toml 中使用 [features],通過與 config.toml 所用相同的
規範鍵固定執行時功能開關。要求還可以包含不屬於 config.toml 的、已有文件說明的
僅限應用的鍵。未指定的鍵不受
約束。
某些受管理要求會強制採用確切的設定值,而不是使用 允許列表。使用者無法覆蓋強制指定的路徑、更新偏好、登入 shell 策略或回饋設定。
受管權限設定檔允許列表要求 Codex 0.138.0 或更高版本。Codex
0.137.0 及更早版本會忽略 allowed_permission_profiles 和受管的
default_permissions。
將 allowed_sandbox_modes 與 sandbox_mode 搭配使用。對於權限設定檔
部署,請將 allowed_permission_profiles 與受管的
default_permissions 搭配使用。
untrusted 條目在 allowed_approval_policies 中仍然有效,適用於
Codex 在專案使用以下設定時推導出的更嚴格的審批行為:
trust_level = "untrusted"。這並不允許顯式設定
approval_policy = "untrusted"。
[models.new_thread] 表提供受管的預設值,而非強制約束。
如果你通過 --model、
--config 或 --profile 顯式覆蓋模型或推理強度,Codex 會忽略 model 和
model_reasoning_effort,這兩個欄位均位於 [models.new_thread] 中。service_tier 獨立生效。
瀏覽器要求涵蓋三個獨立的操作介面。in_app_browser
控制由使用者直接開啟和使用的瀏覽器窗格。browser_use
控制由智能體在瀏覽器中執行的操作。computer_use 控制由智能體在
原生桌面應用中執行的操作。
巢狀的 Browser Use 和 Computer Use 策略值本身並不會授予存取權限。
針對特定源或應用的 allow 可以覆蓋同一策略來源的
回退設定,但常規的功能、審批及其他策略檢查仍然適用。當受管要求與
config.toml 同時適用時,只要其中任一方設為 deny,
就以此為準。
| 鍵 | 類型 / 值 | 詳細資訊 |
|---|---|---|
additional_developer_instructions |
string |
以單獨的開發者訊息新增的受管開發者指令。Codex 會拒絕預估超過 10,000 個 token 的指令,計數包含上下文標記。 |
allow_appshots |
boolean |
設定為 false 可為受管使用者停用 Appshots。如果省略,Appshots 不受要求約束,遵循常規產品可用性規則。 |
allow_browser_and_computer_use |
boolean |
設定為 false 可同時阻止智能體驅動的 Browser Use 和原生應用 Computer Use。設定為 true 或省略此項不會啟用任一功能;其餘功能、策略和審批檢查仍然適用。 |
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> |
允許的審批策略,例如 on-request、never 和 granular。包含 untrusted 可允許從不受信任專案派生的更嚴格策略;無法通過 approval_policy 直接選擇該策略。 |
allowed_approvals_reviewers |
array<string> |
approvals_reviewer 允許的值,例如 user 和 auto_review。 |
allowed_chatgpt_workspaces |
array<string> |
將 ChatGPT 登入(包括 Codex 存取令牌)限制在列出的工作區 ID 範圍內。空列表會停用 ChatGPT 登入;在獲准的情況下,API 身份驗證仍然可用。通過本機系統要求檔案或 macOS MDM 設定;雲端管理的值會被忽略。 |
allowed_login_methods |
array<string> |
允許 chatgpt、api 或兩者。如果省略,此設定不限制登入方式。如果設定,列表必須至少包含一種方式。api 允許 API 身份驗證,包括 Amazon Bedrock。通過本機系統要求檔案或 macOS MDM 設定。雲端管理的值會被忽略。 |
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。 |
application |
table |
受管桌面應用要求。 |
application.network |
table |
桌面應用網路請求的目標限制,獨立於命令網路存取和瀏覽器源規則。此設定不對原生模組或啟動的程序施加目標限制。 |
application.network.domains |
table<allow | deny> |
桌面應用請求的精確域名規則。啟用策略後,僅允許向顯式允許的域名傳送 HTTPS 和 WSS 請求;不會隱式允許子域。 |
application.network.domains.<domain> |
allow | deny |
允許或拒絕精確域名。使用不含 URL 協議方案、埠或萬用字元的域名。 |
application.network.enabled |
boolean |
存在此表時預設為 true。為 true 時,桌面應用的外部請求必須存取顯式允許的域名。空域名對映不允許任何外部目標。應用網路策略不存在或值為 false 時,此策略不限制目標。 |
apps |
table |
以應用識別符為鍵的受管應用要求。要求可以停用應用,或約束各個工具的審批行為。 |
apps.<id>.enabled |
boolean |
設定為 false 可停用應用。合併多個要求來源時,停用要求仍然具有限製作用。 |
apps.<id>.tools.<tool>.approval_mode |
auto | prompt | writes | approve |
設定單個應用工具的受管審批模式。 |
auto_review |
table |
受管自動審查要求。 |
auto_review.ignore_rules |
array<string> |
完整模型識別;對於這些模型,Codex 會忽略命令執行策略中的 allow 字首規則。必須精確匹配識別,包括其供應商命名空間(如有);與 required_on_models 不同,此處不接受不含命名空間的別名。拒絕規則和網路規則仍然適用。 |
auto_review.required_on_models |
array<string> |
必須使用自動審查的模型識別。識別不能為空,不得包含供應商命名空間,且首尾不能有空白字元。多個要求來源中的列表會合併。 |
browser_use |
table |
智能體驅動的 Browser Use 的受管理要求。 |
browser_use.allow_global_persistent_approval |
boolean |
設定為 false 可阻止 Browser Use 建立或遵循涵蓋所有網站的 Always allow 核准,例如允許從任意網站下載。已儲存的核准會被忽略,但不會被刪除。設定為 true 或省略此項不會建立核准。 |
browser_use.allow_history_access |
boolean |
設定為 false 可阻止 Browser Use 讀取瀏覽器歷史記錄。設定為 true 或省略此項時,常規歷史記錄設定和可用性檢查仍然適用。 |
browser_use.allow_webmcp |
boolean |
設定為 true 可為桌面應用的內建瀏覽器啟用網站工具(WebMCP)。設定為 false 或省略此項時,常規功能可用性檢查仍然適用;false 不會強制阻止此功能。使用者偏好設定和網站權限仍然適用。 |
browser_use.default_origin_policy |
table |
當 browser_use.origins 下沒有匹配條目定義某項 Browser Use 設定時,該設定使用的回退值。匹配的源規則會替換該源的回退值。隨後,Codex 會採用受管理要求與使用者設定中更嚴格的結果。 |
browser_use.default_origin_policy.access |
allow | deny |
使用 deny 可阻止在採用回退值的源上使用 Browser Use。被拒絕的源也會禁止上傳、下載、完整瀏覽器除錯存取和自動審查。allow 僅允許繼續進行常規審批和策略檢查。 |
browser_use.default_origin_policy.access_approval_lifetime |
turn | thread |
設定非永續性網站存取核准的有效期:turn 將其限制為當前輪次,thread 則使其在當前執行緒的剩餘時間內保持有效。persistent_approval 單獨控制 Always allow 是否可用。產品預設值為 thread。 |
browser_use.default_origin_policy.auto_review |
allow | deny |
使用 deny 可在採用回退值的源上跳過自動審查,改為請求使用者核准。allow 會在其他設定允許時保持自動審查可用。 |
browser_use.default_origin_policy.downloads |
allow | deny |
使用 deny 可阻止 Browser Use 在採用回退值的源上下載。allow 僅允許繼續進行常規審批和策略檢查。 |
browser_use.default_origin_policy.full_cdp_access |
allow | deny |
使用 deny 可阻止在採用回退值的源上進行完整 Chrome DevTools Protocol(CDP)存取。allow 僅允許繼續進行常規主動啟用和審批檢查。 |
browser_use.default_origin_policy.persistent_approval |
boolean |
設定為 false 可阻止 Browser Use 在採用回退值的源上儲存或遵循 Always allow 核准。當前輪次或執行緒的核准仍可適用。true 會在其他條件允許時使 Always allow 可用,但不會建立核准。 |
browser_use.default_origin_policy.uploads |
allow | deny |
使用 deny 可阻止 Browser Use 在採用回退值的源上上傳。allow 僅允許繼續進行常規審批和策略檢查。 |
browser_use.disable_auto_review |
boolean |
設定為 true 可跳過 Browser Use 的自動審查,改為請求使用者核准。設定為 false 或省略此項時,只要其他設定允許,自動審查就保持可用。 |
browser_use.origins |
map<string, table> |
特定源的 Browser Use 策略。鍵使用 <scheme>://<host-pattern>[:<port>],搭配 http 或 https。可使用精確主機名、僅匹配子域的 *.example.com,或匹配根域及其子域的 **.example.com。其他 * 萬用字元可以跨越點號,因此 region*.example.com 也會匹配 region.api.example.com;主機為 * 時,會匹配該協議方案下的所有主機。協議方案和非預設埠會影響匹配;顯式指定的預設埠會在規範化時移除。路徑、查詢、嵌入的使用者名或密碼,以及萬用字元協議方案或埠均無效。在 TOML 中請用引號括起模式,例如 [browser_use.origins."https://**.example.com"]。 |
browser_use.origins.<pattern> |
table |
匹配此模式的源所採用的策略。如果多個模式匹配,Codex 會為每項能力採用最嚴格的值:deny 優先於 allow,false 優先於 true,turn 優先於 thread。 |
browser_use.origins.<pattern>.access |
allow | deny |
使用 deny 可阻止在匹配的源上使用 Browser Use。拒絕存取也會禁止該源上的上傳、下載、完整瀏覽器除錯存取和自動審查。allow 僅允許繼續進行常規審批和策略檢查。 |
browser_use.origins.<pattern>.access_approval_lifetime |
turn | thread |
設定匹配源的非永續性網站存取核准的有效期:turn 將其限制為當前輪次,thread 則使其在當前執行緒的剩餘時間內保持有效。persistent_approval 單獨控制 Always allow 是否可用。 |
browser_use.origins.<pattern>.auto_review |
allow | deny |
使用 deny 可在匹配的源上跳過自動審查,改為請求使用者核准。allow 會在其他設定允許時保持自動審查可用。 |
browser_use.origins.<pattern>.downloads |
allow | deny |
使用 deny 可阻止 Browser Use 在匹配的源上下載。allow 僅允許繼續進行常規審批和策略檢查。 |
browser_use.origins.<pattern>.full_cdp_access |
allow | deny |
使用 deny 可阻止在匹配的源上進行完整 Chrome DevTools Protocol(CDP)存取。allow 僅允許繼續進行常規主動啟用和審批檢查。 |
browser_use.origins.<pattern>.persistent_approval |
boolean |
設定為 false 可阻止 Browser Use 在匹配的源上儲存或遵循 Always allow 核准。當前輪次或執行緒的核准仍可適用。true 會在其他條件允許時使 Always allow 可用,但不會建立核准。 |
browser_use.origins.<pattern>.uploads |
allow | deny |
使用 deny 可阻止 Browser Use 在匹配的源上上傳。allow 僅允許繼續進行常規審批和策略檢查。 |
chatgpt_base_url |
string |
在身份驗證和取得雲端策略之前,強制指定 ChatGPT 服務的基礎 URL。此設定並不設定 Codex 的所有網路目標。通過本機系統要求檔案或 macOS MDM 設定;雲端管理的值會被忽略。 |
check_for_update_on_startup |
boolean |
強制指定 Codex 是否在啟動時檢查更新。 |
cli_auth_credentials_store |
file | keyring | auto | ephemeral |
在載入身份驗證之前,強制指定 CLI 憑據儲存方式。file 使用 CODEX_HOME/auth.json;keyring 要求使用作業系統憑據儲存;auto 在憑據儲存不可用時回退到檔案;ephemeral 將憑據儲存在當前程序的記憶體中。通過本機系統要求檔案或 macOS MDM 設定;雲端管理的值會被忽略。 |
computer_use |
table |
智能體在原生桌面應用中工作的受管要求。受管應用規則和 config.toml 應用規則均會強制執行;應用必須得到每個策略來源的允許。 |
computer_use.allow_locked_computer_use |
boolean |
設定為 false 可阻止使用者在受管 macOS 裝置上啟用 Locked Use。此要求會移除啟用控制項;如果 Locked Use 已啟用,則不會將其關閉。如果省略,則遵循常規產品可用性規則。 |
computer_use.allow_persistent_approval |
boolean |
設定為 false 可移除跨會話儲存應用核准的選項。當前會話的核准仍然可用。設定為 true 或省略此項不會核准任何應用。 |
computer_use.default_app_access |
allow | deny |
不匹配任何平台特定規則的原生應用所使用的回退存取設定。deny 會阻止存取。allow 僅允許繼續進行常規審批和策略檢查。產品預設值為 allow。 |
computer_use.macos |
table |
macOS 的 Computer Use 應用規則。 |
computer_use.macos.bundle_ids |
map<string, allow | deny> |
將精確的 macOS bundle 識別符對映到 allow 或 deny。匹配的規則會替換同一策略來源中的 computer_use.default_app_access。受管要求或使用者設定中任一方的拒絕仍會阻止存取。 |
computer_use.macos.bundle_ids.<bundle-id> |
allow | deny |
使用 deny 可阻止具有該精確 bundle 識別符的應用。allow 僅覆蓋此策略來源的預設值,仍要求其他所有策略來源及常規審批流程允許該應用。 |
computer_use.windows |
table |
適用於已打包和未打包 Windows 應用的 Computer Use 應用規則。 |
computer_use.windows.aumids |
map<string, allow | deny> |
將已簽名打包應用的精確、已註冊應用使用者模型 ID(AUMID)對映到 allow 或 deny。匹配的規則會替換同一策略來源中的 computer_use.default_app_access。 |
computer_use.windows.aumids.<aumid> |
allow | deny |
使用 deny 可阻止具有該精確打包應用身份的應用。allow 僅覆蓋此策略來源的預設值,仍要求其他所有策略來源及常規審批流程允許該應用。 |
computer_use.windows.exes |
array<table> |
適用於已簽名、未打包 Windows 執行檔的規則。規則匹配執行檔經過驗證的發布者和已簽名版本資訊,而不是其路徑或當前檔名。匹配的拒絕規則優先於匹配的允許規則。未簽名的執行檔使用 computer_use.default_app_access;無法明確驗證簽名身份的執行檔會被阻止。 |
computer_use.windows.exes[].access |
allow | deny |
必填,對匹配的執行檔作出的存取決定。deny 會阻止存取。allow 僅覆蓋此策略來源的預設值,仍要求其他所有策略來源及常規審批流程允許該應用。 |
computer_use.windows.exes[].binary_name |
string |
可選,執行檔已簽名版本資訊中的 OriginalFilename。匹配不區分大小寫。如果匹配的發布者和產品規則要求此值,但執行檔未提供,Computer Use 會阻止該執行檔。 |
computer_use.windows.exes[].product_name |
string |
必填,執行檔已簽名版本資訊中的精確 ProductName。 |
computer_use.windows.exes[].publisher_name |
string |
必填,執行檔受信任簽名證書中的精確發布者名稱,格式為 Windows X.500 可分辨名稱。 |
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 server、原生應用流量或其他特定能力的流量。在受支援的受管 Codex Cloud 路徑上,這些要求與獨立的 Cloud 環境網際網路設定共同約束命令網路存取。在策略允許的情況下,獲批的完整沙箱提權可以繞過命令代理。Work Cloud 不繼承這些要求。 |
experimental_network.allow_local_binding |
boolean |
允許沙箱網路進行更廣泛的本機或私有網路存取。在受支援的 Codex Cloud 代理路徑上,顯式設定為 false 可以阻止上游代理存取,即使域名已獲准也不例外。只有在沒有適用要求、所選網路設定檔或代理功能設定提供值時,才預設為 true。繼承的 false 仍視為顯式值。受支援且優先順序更高的 Cloud 覆蓋設定可以更改此值,而無需擴大適用於 Local 的 Global 範圍,也無需新增域名 Allow 條目。請驗證執行器支援情況。請勿將此 Cloud 預設值應用於 Local。 |
experimental_network.allow_upstream_proxy |
boolean |
允許沙箱網路通過環境中的上游代理進行鏈式連線。 |
experimental_network.allowed_domains |
array<string> |
受管網路代理啟用期間,適用於沙箱命令網路存取的管理員允許規則。這些規則不適用於網頁搜尋、應用或 MCP server。請勿與 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,以及全域 * 允許規則。優先使用限定範圍的規則,因為 * 會廣泛開放公共出站存取。環境規則可以替換策略中相同的 Global 域名鍵。優先順序更高的值會替換相同的鍵,其他繼承的鍵則保持不變。合併後,其他匹配的 deny(包括繼承的萬用字元)仍會阻止請求。空環境對映不會清除 Global 規則。請驗證執行器支援情況。請勿與 experimental_network.allowed_domains 或 experimental_network.denied_domains 組合使用。 |
experimental_network.domains.<pattern> |
allow | deny |
允許或拒絕匹配域名模式的沙箱網路存取。多個模式匹配時,拒絕規則優先。 |
experimental_network.enabled |
boolean |
啟用沙箱網路要求。如果當前沙箱停用了命令網路存取,此設定不會授予網路存取權限。 |
experimental_network.http_port |
integer |
用於 [experimental_network] 要求的迴環 HTTP 監聽埠。 |
experimental_network.managed_allowed_domains_only |
boolean |
啟用網路要求且此值為 true 時,普通使用者設定和按域名核准均無法擴大受管代理允許列表。如果沒有有效的已設定或繼承的 Allow 條目,普通受管命令就沒有任何允許存取的目標。僅包含拒絕規則的策略不會允許存取網際網路的其餘部分。此設定並不涵蓋所有工具或獲批的完整沙箱提權。 |
experimental_network.socks_port |
integer |
用於 [experimental_network] 要求的迴環 SOCKS5 監聽埠。 |
experimental_network.unix_sockets |
map<string, allow | deny> |
由管理員管理的 macOS 沙箱網路 Unix 套接字允許列表。路徑必須為絕對路徑。 |
experimental_network.unix_sockets.<path> |
allow | deny |
在 macOS 上,allow 會將 Unix 套接字的絕對路徑加入允許列表;deny 則不將其加入。啟用允許所有 Unix 套接字時,deny 條目無法阻止套接字存取。 |
features |
table |
固定的功能值。執行時功能使用 config.toml 中的規範名稱;此處也支援文件中記錄的僅用於應用的要求鍵。 |
features.<name> |
boolean |
要求文件中記錄的執行時或應用功能保持啟用或停用。 |
features.apps |
boolean |
為受管使用者固定啟用或停用 Apps 整合。 |
features.browser_use |
boolean |
在 requirements.toml 中設定為 false 可停用智能體驅動的 Browser Use。 |
features.browser_use_external |
boolean |
在 requirements.toml 中設定為 false,可阻止 Codex 通過 ChatGPT 瀏覽器擴充套件操作受支援的瀏覽器,包括現有標籤頁和已登入的會話。 |
features.browser_use_full_cdp_access |
boolean |
在 requirements.toml 中設定為 false,可停用本機執行時中的完整 Chrome DevTools Protocol 存取權限(包括 Browser Developer 模式),並阻止 ChatGPT 桌面應用啟用相應設定。如果省略,則遵循常規產品可用性規則。 |
features.computer_use |
boolean |
在 requirements.toml 中設定為 false,可停用 Computer Use、Record & Replay 及相關安裝或啟用流程。 |
features.fast_mode |
boolean |
為受管使用者固定啟用或停用規範功能 fast_mode。 |
features.guardian_approval |
boolean |
為受管使用者固定啟用或停用 Guardian 審批。 |
features.in_app_browser |
boolean |
在 requirements.toml 中設定為 false,可停用由使用者直接開啟和控制的內建瀏覽器面板。 |
features.in_app_chat |
boolean |
設定為 false 可隱藏 ChatGPT 桌面應用中的 ChatGPT 和 ChatGPT Work 對話介面及相關雲端自動化介面。此設定不會阻止 ChatGPT Voice,也不會停止現有雲端任務。設定為 true 不會繞過帳戶、工作區權限或功能推出檢查。 |
features.in_app_dictation |
boolean |
設定為 false 可停用桌面應用中的應用內聽寫。設定為 true 不會繞過其他可用性檢查。 |
features.in_app_local_automation |
boolean |
設定為 false 可停用桌面應用中的本機定時任務。設定為 true 不會繞過其他可用性檢查。 |
features.in_app_updates |
boolean |
在 requirements.toml 中設定為 false 可停用應用內更新。省略此要求時,更新預設保持啟用。 |
features.memories |
boolean |
為受管使用者固定啟用或停用 Memories。 |
features.multi_agent |
boolean |
為受管使用者固定啟用或停用多智能體功能。 |
features.plugin_sharing |
boolean |
在雲端管理的 requirements.toml 中設定為 false,可停用本機建置外掛的工作區共享。 |
features.plugins |
boolean |
為受管使用者固定啟用或停用外掛。 |
features.realtime_conversation |
boolean |
設定為 false 可停用 Codex CLI 中的實驗性 /voice 命令。請勿依賴此設定來阻止桌面應用中的 ChatGPT Voice 或 app-server 語音會話。設定為 true 不會繞過客戶端或功能推出檢查。 |
features.remote_plugin |
boolean |
為受管使用者固定啟用或停用遠端外掛目錄。 |
features.workspace_dependencies |
boolean |
為受管使用者固定啟用或停用捆綁的工作區依賴執行時。 |
feedback |
table |
受管回饋設定。 |
feedback.enabled |
boolean |
強制指定使用者是否可以在各個 Codex 客戶端中提交回饋。 |
guardian_extra_policy |
string |
用於自動審查的附加受管 Markdown 策略,與主策略一同納入。優先於本機 [auto_review].extra_policy。空白值會被忽略。 |
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 會驗證該目錄為絕對路徑且確實存在。 |
in_app_browser |
table |
內建瀏覽器面板的要求。這些設定不控制智能體驅動的 Browser Use。 |
in_app_browser.allow_external_browser_settings_import |
boolean |
設定為 false 可阻止使用者將外部瀏覽器的設定或瀏覽資料匯入內建瀏覽器。設定為 true 或省略此項時,只要其他產品檢查允許,匯入功能就保持可用。此設定僅限受管設定,無法通過 config.toml 覆蓋。 |
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 引用。省略時,該規則允許匹配儲存庫的任意引用。 |
marketplaces.allowed_sources.<name>.source |
git | host_pattern | local |
市場來源匹配器類型。使用 git 匹配單個儲存庫,使用 host_pattern 通過正規表示式匹配 Git 主機,或使用 local 匹配單個目錄。 |
marketplaces.allowed_sources.<name>.url |
string |
source = "git" 時必需的 Git 儲存庫 URL。Codex 會先規範化已設定的 URL 和允許的 URL,再要求精確匹配儲存庫。 |
marketplaces.restrict_to_allowed_sources |
boolean |
為 true 時,新增市場、安裝外掛、重新整理和執行時載入均要求已設定的市場來源匹配 allowed_sources。OpenAI 精選 Git 目錄(包括 API key 目錄)也必須匹配允許列表。捆綁的工作區外掛和遠端安裝的工作區外掛獨立於此精選 Git 來源策略。 |
mcp_servers |
table |
允許啟用的 MCP server允許列表。伺服器名稱(<id>)及其身份必須均匹配,才能啟用該 MCP server。任何已設定但不在允許列表中(或身份不匹配)的 MCP server都會被停用。 |
mcp_servers.<id>.identity |
table |
單個 MCP server的身份規則。設定 command(stdio)或 url(streamable 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 streamable HTTP 伺服器,或使用 exact、prefix 或 regex 值匹配器表。 |
mcp_servers.<id>.identity.url.expression |
string |
regex URL 匹配器使用的正規表示式。表示式必須有效,且必須匹配完整的 URL 值。 |
mcp_servers.<id>.identity.url.match |
exact | prefix | regex |
已設定 MCP server URL 的匹配操作。 |
mcp_servers.<id>.identity.url.value |
string |
exact 或 prefix URL 匹配器使用的值。 |
model_catalog_json |
string (path) |
強制指定 Codex 啟動時使用的 JSON 模型目錄。 |
model_provider |
string |
強制指定模型供應商 ID,覆蓋本機和會話設定。 |
model_providers |
map<string, table> |
受管模型供應商定義。每個條目都會完整替換已設定的同 ID 供應商;欄位不會與使用者定義合併。其他 ID 的供應商仍然可用。 |
model_providers.<id> |
table |
完整的受管供應商定義。使用與 config.toml 相同的供應商欄位,包括 name、base_url、身份驗證和傳輸設定。 |
models |
table |
包含 [models.new_thread] 表。 |
models.new_thread |
table |
啟動新的本機執行緒時應用的可選預設值。優先於使用者和專案預設值,但可以被顯式覆蓋。 |
models.new_thread.model |
string |
新執行緒的預設模型。顯式覆蓋模型或推理強度中的任意一項,都會導致這兩個欄位被忽略。 |
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 server允許列表。存在此表時,沒有匹配外掛和伺服器條目的外掛捆綁伺服器會被停用。 |
plugins.<plugin>.mcp_servers |
table |
單個外掛捆綁的 MCP server允許列表。外掛伺服器要求使用與頂層 mcp_servers 要求相同的精確身份和匹配器形式。 |
plugins.<plugin>.mcp_servers.<server>.identity |
table |
單個外掛捆綁 MCP server的身份規則。設定 command(stdio)或 url(streamable HTTP)中的一項。 |
plugins.<plugin>.mcp_servers.<server>.identity.command |
string | table |
通過精確命令字串允許外掛的 stdio MCP server,或使用匹配器表來要求精確匹配執行檔並按順序匹配參數。 |
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 字串允許外掛的 streamable HTTP MCP server,或使用 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 server 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 或 any_of 中的一項。 |
rules.prefix_rules[].pattern[].any_of |
array<string> |
此位置允許的備選詞元列表。 |
rules.prefix_rules[].pattern[].token |
string |
此位置的單個字面量詞元。 |
sqlite_home |
string (path) |
強制指定 Codex 儲存基於 SQLite 的執行時狀態的目錄。 |
windows |
table |
原生 Windows 沙箱要求。 |
windows.allow_mxc |
boolean |
設定為 false 可同時禁止顯式選擇 MXC 和通過 features.prefer_mxc 自動選擇 MXC。省略此要求或將其設定為 true 會允許 MXC,但不會啟用或強制使用它。回退時仍受舊版實現限制的約束。 |
windows.allowed_sandbox_implementations |
array<string> |
允許的舊版原生 Windows 沙箱實現(elevated 和 unelevated)。列表不能為空。當兩者均獲准且未選擇模式時,Codex 優先使用 elevated。此列表不限制可用的 mxc 沙箱。 |
沒有相符的設定選項。