ChatGPT 繁體中文教學
繁體中文
聯絡我 goolvyouyou@gmail.com

設定參考

config.toml 與 requirements.toml 的完整參考

把本頁當成 Codex 設定檔的可檢索參考手冊來使用。若你想先看概念解釋和典型範例，請從 設定基礎 和 高階設定 開始。

config.toml

使用者級設定位於 ~/.codex/config.toml。你也可以在 .codex/config.toml 中新增專案級覆蓋設定。Codex 只會在你信任該專案時載入專案級 .codex/ 設定層。

專案級設定不能覆蓋機器本機的 provider、認證、host-owned app request metadata、通知、設定檔選擇或 telemetry 路由鍵。Codex 會忽略專案本機 .codex/config.toml 中的 openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url 和 otel；provider、通知和 telemetry 鍵應放在使用者級設定中。設定檔檔案與 config.toml 放在同一目錄，格式為 $CODEX_HOME/profile-name.config.toml，並通過 --profile profile-name 選擇。

對於和沙箱、審批有關的設定鍵，例如 approval_policy、sandbox_mode 和 sandbox_workspace_write.*，建議把本頁與 沙箱與審批、可寫根目錄中的受保護路徑 以及 網路存取 搭配閱讀。關於 beta 權限設定檔，請參見權限。

鍵 類型 / 可選值 說明
model string 要使用的模型，例如 gpt-5.5。
review_model string /review 使用的可選模型覆蓋值（預設使用當前 session 模型）。
model_provider string 從 model_providers 中選擇的提供方 ID（預設 openai）。
openai_base_url string 內建 openai model provider 的 base URL 覆蓋值。
model_context_window number 當前啟用模型可用的 context window token 數。
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 model catalog 路徑。選中的 $CODEX_HOME/profile-name.config.toml 設定檔檔案可以覆蓋該值。
oss_provider lmstudio | ollama 執行 --oss 時使用的預設本機 provider（未設定時會提示使用者選擇）。
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.sandbox_approval boolean 為 true 時，允許沙箱升級時的審批提示顯示出來。
approval_policy.granular.rules boolean 為 true 時，允許由 execpolicy 提示詞規則觸發的審批提示顯示出來。
approval_policy.granular.mcp_elicitations boolean 為 true 時，允許 MCP elicitation 提示真正顯示出來，而不是被自動拒絕。
approval_policy.granular.request_permissions boolean 為 true 時，允許 request_permissions 工具觸發的提示顯示出來。
approval_policy.granular.skill_approval boolean 為 true 時，允許技能指令碼觸發的審批提示顯示出來。
approvals_reviewer user | auto_review 在 on-request 或細粒度審批策略下，指定由誰稽核符合條件的審批提示。預設是 user；設為 auto_review 時，會由審查子智能體自動稽核。這不會改變沙箱邊界，也不會影響原本已在沙箱內允許執行的動作。
auto_review.policy string 自動審查使用的本機 Markdown 策略指令。若管理員下發了 guardian_policy_config，則以託管設定為準；空值會被忽略。
allow_login_shell boolean 是否允許基於 shell 的工具使用 login-shell 語義。預設 true；若設為 false，則 login = true 的請求會被拒絕，未顯式設定 login 時預設使用非 login shell。
sandbox_mode read-only | workspace-write | danger-full-access 命令執行期間的檔案系統與網路存取沙箱策略。
sandbox_workspace_write.writable_roots array<string> 當 sandbox_mode = "workspace-write" 時的額外可寫根目錄。
sandbox_workspace_write.network_access boolean 在 workspace-write sandbox 中允許向外聯網。
sandbox_workspace_write.exclude_tmpdir_env_var boolean 在 workspace-write 模式下，將 $TMPDIR 排除出可寫根目錄。
sandbox_workspace_write.exclude_slash_tmp boolean 在 workspace-write 模式下，將 /tmp 排除出可寫根目錄。
windows.sandbox unelevated | elevated 在 Windows 原生模式下執行 Codex 時使用的原生 sandbox 模式（僅 Windows）。
windows.sandbox_private_desktop boolean 在原生 Windows 上，預設讓最終 sandboxed 子程序執行在私有桌面中。只有為相容舊版 Winsta0\Default 行為時才應設為 false。
computer_use.windows.always_allowed_app_ids array<string> Computer Use 無需提示即可開啟的 Windows app 識別符號。列表外的 app 仍需審批；可在 ChatGPT 桌面應用的 Computer Use 設定中刪除已儲存條目。
notify array<string> 用於通知的命令；Codex 會向其傳入一個 JSON payload。
check_for_update_on_startup boolean 啟動時是否檢查 Codex 更新（只有在更新由中心化方式統一管理時才建議設為 false）。
feedback.enabled boolean 在本機客戶端中啟用通過 /feedback 提交回饋（預設 true）。
analytics.enabled boolean 為當前機器 / 設定檔啟用或關閉分析資料上報。未設定時使用客戶端預設值。
instructions string 預留給未來使用；當前請優先使用 model_instructions_file 或 AGENTS.md。
developer_instructions string 注入到會話中的額外開發者指令（可選）。
log_dir string (path) Codex 寫日誌檔案的目錄，例如 codex-tui.log；預設值是 $CODEX_HOME/log。
sqlite_home string (path) Codex 存放基於 SQLite 的狀態資料庫目錄，供智能體作業與其他可恢復執行時狀態使用。
compact_prompt string 對歷史壓縮提示詞的內聯覆蓋。
model_instructions_file string (path) 用於替代內建 instructions 的檔案，而不是使用 AGENTS.md。
personality none | friendly | pragmatic 對支援 supportsPersonality 的模型設定預設溝通風格；可在對話執行緒 / 會話輪次級別或通過 /personality 覆蓋。
service_tier string 新會話輪次的 service tier 偏好。使用 fast 或當前模型公佈的其它 tier；fast 會對映為請求值 priority。
experimental_compact_prompt_file string (path) 從檔案載入歷史壓縮提示詞覆蓋值（實驗性）。
skills.config array<object> 儲存在 config.toml 中的按技能啟用覆蓋設定。
skills.config.<index>.path string (path) 指向技能資料夾的路徑，該資料夾內應包含 SKILL.md。
skills.config.<index>.enabled boolean 啟用或停用對應技能。
apps.<id>.enabled boolean 啟用或停用某個具體 app / connector（預設 true）。
apps._default.enabled boolean 對所有 app 生效的預設啟用狀態，除非被單個 app 覆蓋。
apps._default.destructive_enabled boolean 預設是否允許帶 destructive_hint = true 的 app 工具。
apps._default.open_world_enabled boolean 預設是否允許帶 open_world_hint = true 的 app 工具。
apps._default.approvals_reviewer user | auto_review app 工具審批提示的預設 reviewer，除非被單個 app 覆蓋。省略時，app 會繼承頂層 approvals_reviewer。
apps._default.default_tools_approval_mode auto | prompt | writes | approve 沒有單 app 或單工具覆蓋時，app 工具使用的預設審批行為。
apps.<id>.destructive_enabled boolean 是否允許該 app 中聲明瞭 destructive_hint = true 的工具。
apps.<id>.open_world_enabled boolean 是否允許該 app 中聲明瞭 open_world_hint = true 的工具。
apps.<id>.default_tools_enabled boolean 該 app 中工具的預設啟用狀態，除非單個工具另有覆蓋。
apps.<id>.approvals_reviewer user | auto_review 該 app 工具審批提示的 reviewer。會覆蓋 apps._default.approvals_reviewer。
apps.<id>.default_tools_approval_mode auto | prompt | writes | approve 該 app 中工具的預設審批行為，除非單個工具另有覆蓋。
apps.<id>.tools.<tool>.enabled boolean 對單個 app 工具的啟用狀態覆蓋，例如 repos/list。
apps.<id>.tools.<tool>.approval_mode auto | prompt | writes | approve 對單個 app 工具的審批行為覆蓋。
tool_suggest.discoverables array<table> 允許對額外的可發現連接器或外掛給出工具建議。每一項都應包含 type = "connector" 或 "plugin"，以及對應的 id。
tool_suggest.disabled_tools array<table> 停用特定可發現連接器或外掛的工具建議。每一項都應包含 type = "connector" 或 "plugin"，以及對應的 id。
features.apps boolean 啟用 App（連接器）整合（Stable；預設開啟）。
features.hooks boolean 啟用從 hooks.json 或內聯 [hooks] 設定載入的生命週期鉤子。features.codex_hooks 是已棄用 alias。
features.code_mode.enabled boolean 啟用 code mode 功能設定。該功能仍在開發中，預設關閉。
features.code_mode.excluded_tool_namespaces array<string> code mode 從巢狀 code-mode 工具指引和 executor 暴露中排除的工具 namespace。
features.code_mode.direct_only_tool_namespaces array<string> code mode 只能通過直接工具呼叫使用的工具 namespace。
features.rollout_budget.enabled boolean 啟用 rollout budget 跟蹤。該功能仍在開發中，預設關閉。啟用後必須設定 features.rollout_budget.limit_tokens。
features.rollout_budget.limit_tokens integer rollout budget 跟蹤使用的正 token 上限。啟用 rollout budget 時必填。
features.rollout_budget.reminder_interval_tokens integer rollout budget 提醒之間的正 token 間隔。預設是 limit_tokens 的 10%，最小為 1 token。
features.rollout_budget.sampling_token_weight number rollout budget 記賬時 sampled tokens 使用的有限非負乘數。預設 1.0。
features.rollout_budget.prefill_token_weight number rollout budget 記賬時 prefill tokens 使用的有限非負乘數。預設 1.0。
hooks table 在 config.toml 中內聯設定的生命週期鉤子。使用與 hooks.json 相同的事件 schema；範例和支援事件請參見 Hooks。
hooks.<Event> array<table> 某個鉤子事件的 matcher 分組，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SessionEnd、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。
hooks.<Event>[].hooks array<table> matcher 分組下的鉤子處理器。當前支援 command hooks；prompt 和 agent hook handlers 會被解析但跳過。
hooks.<Event>[].hooks[].commandWindows string command hooks 的 Windows 專用命令覆蓋。也接受 TOML alias command_windows。
features.memories boolean 啟用 Memories（預設關閉）。
mcp_servers.<id>.command string MCP stdio server 的啟動命令。
mcp_servers.<id>.args array<string> 傳給 MCP stdio server 啟動命令的參數。
mcp_servers.<id>.env map<string,string> 轉發給 MCP stdio server 的環境變數。
mcp_servers.<id>.env_vars array<string | { name = string, source = "local" | "remote" }> 額外允許轉發給 MCP stdio server 的環境變數。字串條目預設使用 source = "local"；只有在 executor-backed remote stdio 場景下才使用 source = "remote"。
mcp_servers.<id>.cwd string MCP stdio server 程序的工作目錄。
mcp_servers.<id>.url string MCP streamable HTTP server 的端點。
mcp_servers.<id>.auth oauth | chatgpt 在已設定 bearer token 和 authorization headers 之後使用的 MCP HTTP server 認證回退方式。oauth（預設）優先使用已儲存的 MCP OAuth 憑據；chatgpt 對受信任的第一方 ChatGPT origin 使用當前 ChatGPT 會話，再回退到已儲存的 OAuth。若所有憑據來源都未解析成功，兩種模式都可以在無認證狀態下連線。
mcp_servers.<id>.bearer_token_env_var string 作為 MCP HTTP server bearer token 來源的環境變數名。
mcp_servers.<id>.http_headers map<string,string> 每次 MCP HTTP 請求都攜帶的靜態 HTTP headers。
mcp_servers.<id>.env_http_headers map<string,string> 對 MCP HTTP server，從環境變數填充出來的 HTTP headers。
mcp_servers.<id>.enabled boolean 在不刪除設定的前提下停用一個 MCP server。
mcp_servers.<id>.required boolean 為 true 時，若該已啟用 MCP server 無法初始化，則啟動 / 恢復會失敗。
mcp_servers.<id>.startup_timeout_sec number 覆蓋 MCP server 預設 10 秒的啟動超時。
mcp_servers.<id>.startup_timeout_ms number startup_timeout_sec 的毫秒別名。
mcp_servers.<id>.tool_timeout_sec number 覆蓋 MCP server 預設 60 秒的單工具超時。
mcp_servers.<id>.enabled_tools array<string> MCP server 暴露的工具允許列表。
mcp_servers.<id>.disabled_tools array<string> MCP server 的 deny list；會在 enabled_tools 之後應用。
mcp_servers.<id>.default_tools_approval_mode auto | prompt | writes | approve 該 MCP server 中工具的預設審批行為，除非有單工具覆蓋。
mcp_servers.<id>.tools.<tool>.approval_mode auto | prompt | writes | approve 對該 MCP server 中單個工具的審批行為覆蓋。
mcp_servers.<id>.scopes array<string> 對該 MCP server 進行認證時請求的 OAuth 權限範圍（scopes）。
mcp_servers.<id>.oauth_resource string MCP 登入期間附帶的可選 RFC 8707 OAuth resource 參數。
mcp_servers.<id>.experimental_environment local | remote MCP server 的實驗性執行位置。remote 會通過遠端 executor 環境啟動 stdio server；streamable HTTP 的 remote placement 尚未實現。
agents table 多智能體設定和自定義角色宣告。標量設定名屬於保留名稱，不能用作自定義角色名。
agents.enabled boolean 啟用或停用多智能體工具（預設 true）。
agents.max_concurrent_threads_per_session number 同時開啟的子智能體對話執行緒最大數量，不含主對話執行緒。未設定時由 Codex 選擇預設值。
agents.max_threads number agents.max_concurrent_threads_per_session 的舊別名。
agents.default_subagent_model string 子智能體的預設模型；生成時顯式指定的模型優先。
agents.default_subagent_reasoning_effort string 子智能體的預設推理強度；生成時顯式指定的推理強度優先。
agents.interrupt_message boolean 智能體的會話輪次被中斷時，是否記錄一條模型可見訊息（預設 true）。
agents.<name>.description string 當 Codex 選擇並生成該智能體類型時展示給它的角色說明。
agents.<name>.config_file string (path) 該角色使用的 TOML 設定層路徑；相對路徑相對於宣告該角色的設定檔解析。
memories.generate_memories boolean 為 false 時，新建立的對話執行緒不會作為記憶生成輸入儲存。預設 true。
memories.use_memories boolean 為 false 時，Codex 不會把現有記憶注入到後續會話中。預設 true。
memories.disable_on_external_context boolean 為 true 時，使用 MCP 工具呼叫、Web 搜尋或工具搜尋等外部上下文的對話執行緒不會進入記憶生成。預設 false。舊別名：memories.no_memories_if_mcp_or_web_search。
memories.max_raw_memories_for_consolidation number 全域記憶合併保留的近期原始記憶最大數量。預設 256，上限 4096。
memories.max_unused_days number 記憶距離上次使用超過多少天后不再參與記憶合併。預設 30，範圍限制為 0-365。
memories.max_rollout_age_days number 參與記憶生成的對話執行緒最大年齡。預設 30，範圍限制為 0-90。
memories.max_rollouts_per_startup number 每次啟動處理的 rollout 候選最大數量。預設 16，上限 128。
memories.min_rollout_idle_hours number 對話執行緒進入記憶生成前需要空閒的最短時間。預設 6，範圍限制為 1-48。
memories.min_rate_limit_remaining_percent number Codex 速率限制視窗剩餘百分比達到該閾值後，才會開始記憶生成。預設 25，範圍限制為 0-100。
memories.extract_model string 針對單執行緒記憶提取使用的可選模型覆蓋。
memories.consolidation_model string 針對全域記憶合併使用的可選模型覆蓋。
features.unified_exec boolean 使用統一的 PTY 支撐 exec 工具（Stable；除 Windows 外預設開啟）。
features.shell_snapshot boolean 快照 shell 環境，以加快重複命令（Stable；預設開啟）。
features.multi_agent boolean 啟用多智能體協作工具，例如 spawn_agent、send_input、resume_agent、wait_agent、close_agent（Stable；預設開啟）。
features.goals boolean 啟用持久化 goals 與自動續跑（Stable；預設開啟）。
features.remote_plugin boolean 啟用遠端 plugin 目錄（Stable；預設開啟）。
features.personality boolean 啟用 personality 選擇控制項（Stable；預設開啟）。
features.network_proxy boolean | table 啟用沙箱化網路。設定 domains 等網路策略選項時使用 table 形式（實驗性；預設關閉）。
features.network_proxy.enabled boolean 啟用沙箱化網路。預設 false。
features.network_proxy.domains map<string, allow | deny> 沙箱化網路的域名策略。預設未設定，表示在新增 allow 規則前不允許外部目的地。支援精確主機、只匹配子域名的 *.example.com、同時匹配 apex 和子域名的 **.example.com，以及全域 * allow 規則；* 會寬泛開啟公共出站存取，應優先使用更窄規則。新增 deny 規則可阻止目的地，衝突時 deny 優先。
features.network_proxy.unix_sockets map<string, allow | deny> 沙箱化網路的 Unix socket 策略。預設未設定；為允許的 socket 新增 allow 條目。
features.network_proxy.allow_local_binding boolean 允許更寬的本機 / 私有網路存取。預設 false；精確本機 IP literal 或 localhost allow 規則仍可允許特定本機目標。
features.network_proxy.enable_socks5 boolean 暴露 SOCKS5 支援。預設 true。
features.network_proxy.enable_socks5_udp boolean 允許通過 SOCKS5 使用 UDP。預設 true。
features.network_proxy.allow_upstream_proxy boolean 允許通過環境中的 upstream proxy 級聯。預設 true。
features.network_proxy.dangerously_allow_non_loopback_proxy boolean 允許非 loopback 監聽器地址。預設 false；啟用後可能把代理監聽器暴露到 localhost 之外。
features.network_proxy.dangerously_allow_all_unix_sockets boolean 允許任意 Unix socket 目的地，而不是隻允許 allowlist 條目。預設 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.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"。
features.shell_tool boolean 啟用預設 shell 工具來執行命令（Stable；預設開啟）。
features.enable_request_compression boolean 在支援時使用 zstd 壓縮流式請求體（Stable；預設開啟）。
features.skill_mcp_dependency_install boolean 允許針對技能缺失的 MCP 依賴進行提示並安裝（Stable；預設開啟）。
features.fast_mode boolean 啟用 TUI 中基於模型目錄的 service tier 選擇；噹噹前模型宣告 Fast tier 時，也會啟用對應命令（Stable；預設開啟）。
features.prevent_idle_sleep boolean 在會話輪次正在執行時阻止機器休眠（Experimental；預設關閉）。
suppress_unstable_features_warning boolean 壓制開啟“開發中”功能開關時顯示的警告。
model_providers.<id> table 自定義模型提供方的定義。
model_providers.<id>.name string 自定義 model provider 的顯示名稱。
model_providers.<id>.base_url string 該模型提供方的 API base URL。
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>.requires_openai_auth boolean 該提供方是否使用 OpenAI 認證（預設 false）。
model_providers.<id>.wire_api responses 該 provider 使用的協議。當前唯一支援值是 responses，且省略時預設即為此值。
model_providers.<id>.query_params map<string,string> 附加到提供方請求上的額外 query 參數。
model_providers.<id>.http_headers map<string,string> 附加到提供方請求上的靜態 HTTP headers。
model_providers.<id>.env_http_headers map<string,string> 僅在環境變數存在時，從環境變數填充的 HTTP headers。
model_providers.<id>.request_max_retries number 向該提供方發起 HTTP 請求時的重試次數（預設 4）。
model_providers.<id>.stream_max_retries number SSE 流中斷時的重試次數（預設 5）。
model_providers.<id>.stream_idle_timeout_ms number SSE stream 的空閒超時（毫秒，預設 300000）。
model_providers.<id>.supports_websockets boolean 該 provider 是否支援 Responses API 的 WebSocket transport。
model_providers.<id>.supports_standalone_web_search boolean 宣告支援相容的獨立 Web 搜尋端點（預設 false）。獨立搜尋仍在開發中且預設關閉；僅有 provider 相容性不會自動啟用它。
model_providers.<id>.auth table 針對自定義提供方的命令式 bearer token 設定。不要與 env_key、experimental_bearer_token 或 requires_openai_auth 混用。
model_providers.<id>.auth.command string 當 Codex 需要 bearer token 時要執行的命令。該命令必須把 token 列印到 stdout。
model_providers.<id>.auth.args array<string> 傳給 token 命令的參數。
model_providers.<id>.auth.timeout_ms number token 命令的最長執行時間（毫秒，預設 5000）。
model_providers.<id>.auth.refresh_interval_ms number Codex 主動重新整理的 token 週期（毫秒，預設 300000）。設為 0 時，只會在認證重試後重新整理。
model_providers.<id>.auth.cwd string (path) 執行 token 命令時使用的工作目錄。
model_providers.amazon-bedrock.aws.profile string 內建 amazon-bedrock provider 使用的 AWS profile 名稱。
model_providers.amazon-bedrock.aws.region string 內建 amazon-bedrock provider 使用的 AWS region。
model_reasoning_effort minimal | low | medium | high | xhigh 在支援的模型上調整推理強度（僅 Responses API；xhigh 是否可用取決於模型）。
plan_mode_reasoning_effort none | minimal | low | medium | high | xhigh 計劃模式專用的 reasoning 覆蓋值。未設定時，計劃模式使用其內建預設預設值。
model_reasoning_summary auto | concise | detailed | none 選擇 reasoning summary 的詳細程度，或徹底關閉 summary。
model_verbosity low | medium | high 可選的 GPT-5 Responses API 輸出詳細程度覆蓋值；未設定時使用模型 / 預設預設值。
model_supports_reasoning_summaries boolean 強制 Codex 傳送或不傳送 reasoning metadata。
shell_environment_policy.inherit all | core | none 啟動子程序時的基礎環境繼承策略。
shell_environment_policy.ignore_default_excludes boolean 在其他過濾之前保留包含 KEY、SECRET 或 TOKEN 的環境變數（預設 true）。設為 false 可啟用自動 secret 名稱排除。
shell_environment_policy.filters map<string, include | exclude> 權威的、不區分大小寫的環境變數 pattern filter。include 條目會建立 allowlist，且不能恢復已經排除的值；顯式 set 值在排除後應用。同一層中不要把 filters 與舊版 exclude 或 include_only 陣列混用。
shell_environment_policy.exclude array<string> 舊版環境變數排除 pattern。新設定請使用 shell_environment_policy.filters；同一層中不要混用兩種形式。
shell_environment_policy.include_only array<string> 舊版環境變數 allowlist pattern。新設定請使用 shell_environment_policy.filters；同一層中不要混用兩種形式。
shell_environment_policy.set map<string,string> 排除之後注入的顯式環境變數值；include filter 仍可將其移除。
shell_environment_policy.experimental_use_profile boolean 讓子程序通過使用者 shell profile 執行。
project_root_markers array<string> 專案根標記檔名列表；用於向父目錄搜尋專案根。
project_doc_max_bytes number 建置專案指令時，從 AGENTS.md 最多讀取的位元組數。
project_doc_fallback_filenames array<string> 當 AGENTS.md 缺失時要嘗試的額外檔名。
history.persistence save-all | none 控制 Codex 是否把 session transcript 持久儲存到 history.jsonl。
tool_output_token_limit number 在歷史中儲存單次 tool / function 輸出時可使用的 token 預算。
background_terminal_max_timeout number 後臺終端空 write_stdin 輪詢的最大等待視窗（毫秒）。預設 300000（5 分鐘）。替代舊鍵 background_terminal_timeout。
history.max_bytes number 若設定，則通過丟棄最舊條目來限制 history 檔案的最大位元組數。
file_opener vscode | vscode-insiders | windsurf | cursor | none Codex 輸出中的 citation 開啟時使用的 URI scheme（預設 vscode）。
otel.environment string 應用於 OpenTelemetry 事件的環境標籤（預設 dev）。
otel.exporter none | otlp-http | otlp-grpc 選擇 OpenTelemetry exporter，並提供相應 endpoint 後設資料。
otel.trace_exporter none | otlp-http | otlp-grpc 選擇 OpenTelemetry trace exporter，並提供相應 endpoint 後設資料。
otel.metrics_exporter none | statsig | otlp-http | otlp-grpc 選擇 OpenTelemetry metrics exporter（預設 statsig）。
otel.log_user_prompt boolean 是否把原始使用者 prompt 一併匯出到 OpenTelemetry logs。
otel.exporter.<id>.endpoint string OTEL logs exporter 的 endpoint。
otel.exporter.<id>.protocol binary | json OTLP/HTTP exporter 使用的協議。
otel.exporter.<id>.headers map<string,string> OTEL exporter 請求所帶的靜態 headers。
otel.trace_exporter.<id>.endpoint string OTEL trace exporter 的 endpoint。
otel.trace_exporter.<id>.protocol binary | json OTLP/HTTP trace exporter 使用的協議。
otel.trace_exporter.<id>.headers map<string,string> OTEL trace exporter 請求所帶的靜態 headers。
otel.exporter.<id>.tls.ca-certificate string OTEL exporter TLS 使用的 CA 證書路徑。
otel.exporter.<id>.tls.client-certificate string OTEL exporter TLS 使用的客戶端證書路徑。
otel.exporter.<id>.tls.client-private-key string OTEL exporter TLS 使用的客戶端私鑰路徑。
otel.trace_exporter.<id>.tls.ca-certificate string OTEL trace exporter TLS 使用的 CA 證書路徑。
otel.trace_exporter.<id>.tls.client-certificate string OTEL trace exporter TLS 使用的客戶端證書路徑。
otel.trace_exporter.<id>.tls.client-private-key string OTEL trace exporter TLS 使用的客戶端私鑰路徑。
tui table TUI 專屬選項，例如是否啟用內聯桌面通知。
desktop.custom_file_handlers.<id> table 僅限使用者級設定。為 ChatGPT 桌面 App 定義額外的 Open in（開啟方式） 目標。範例和 handler ID 約束參見新增自定義檔案處理器。
desktop.custom_file_handlers.<id>.label string Open in（開啟方式） 選單中顯示的名稱。必填。
desktop.custom_file_handlers.<id>.icon string handler 圖示的內建資源路徑、Base64 編碼的 data:image/... URL、file URI 或本機絕對路徑。必填；不支援的來源會使用預設 VS Code 圖示。
desktop.custom_file_handlers.<id>.command string 用於檢測並啟動的執行檔路徑或命令名。必填。
desktop.custom_file_handlers.<id>.args array<string> 插入在命令與檔案輸入之間的參數（預設 []）。
desktop.custom_file_handlers.<id>.input path | json_argument | json_stdin App 向 handler 傳遞檔案輸入的方式（預設 path）。
desktop.custom_file_handlers.<id>.supports_ssh boolean 是否為 SSH 工作區中的檔案提供該 handler（預設 false）。
tui.notifications boolean | array<string> 啟用 TUI 通知；也可限制為特定事件類型。
tui.notification_method auto | osc9 | bel 終端通知使用的方法（預設 auto）。
tui.notification_condition unfocused | always 控制 TUI 通知只在終端失焦時觸發，還是無論焦點狀態都觸發。預設 unfocused。
tui.animations boolean 啟用終端動畫，例如 welcome screen、shimmer、spinner（預設 true）。
tui.alternate_screen auto | always | never 控制 TUI 是否使用 alternate screen（預設 auto；在 Zellij 中會自動跳過，以保留 scrollback）。
tui.resume_cwd current | session 恢復或分叉會話時使用的工作目錄。未設定時，若當前目錄與會話儲存的目錄不同，Codex 會詢問你要使用哪一個。
tui.vim_mode_default boolean 啟動時讓輸入框進入 Vim normal mode，而不是 insert mode（預設 false）。仍可在會話中用 /vim 切換。
tui.raw_output_mode boolean 啟動 TUI 時使用原始滾動回看（raw scrollback）模式，便於在終端中選擇和複製（預設 false）。可通過 /raw 或預設 alt-r 繫結切換。
tui.show_tooltips boolean 是否在 TUI welcome screen 中顯示 onboarding tooltips（預設 true）。
tui.status_line array<string> | null TUI 底部狀態列項的有序列表。null 表示停用狀態列。
tui.terminal_title array<string> | null 終端視窗 / 標籤標題項的有序列表。預設是 ["spinner", "project"]；null 表示停用標題更新。
tui.theme string 語法高亮主題覆蓋值（kebab-case 主題名）。
tui.keymap.<context>.<action> string | array<string> TUI 動作的快捷鍵繫結。支援的 context 包括 global、chat、composer、editor、vim_normal、vim_operator、vim_text_object、pager、list 和 approval。部分 composer 動作會回退到匹配的 tui.keymap.global 繫結；支援特定 context 繫結時，該 context 會優先生效。
tui.keymap.<context>.<action> = [] empty array 在對應 keymap context 中解除該動作繫結。按鍵名使用 ctrl-a、shift-enter、page-down 或 minus 這類規範化字串。
plugins.<plugin>.mcp_servers.<server>.enabled boolean 在不修改外掛 manifest 的前提下，啟用或停用已安裝外掛打包的 MCP server。
plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode auto | prompt | writes | approve 外掛提供的 MCP server 中工具的預設審批行為。
plugins.<plugin>.mcp_servers.<server>.enabled_tools array<string> 外掛提供的 MCP server 暴露工具允許列表。
plugins.<plugin>.mcp_servers.<server>.disabled_tools array<string> 外掛提供的 MCP server 的 deny list，會在 enabled_tools 之後應用。
plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode auto | prompt | writes | approve 對外掛提供的單個 MCP 工具的審批行為覆蓋。
tui.model_availability_nux.<model> integer 以模型 slug 為 key 的內部啟動提示狀態。
hide_agent_reasoning boolean 在 TUI 與 codex exec 輸出中壓制 reasoning 事件。
show_raw_agent_reasoning boolean 噹噹前模型會發出 raw reasoning 時，直接顯示該內容。
disable_paste_burst boolean 關閉 TUI 中的 burst-paste 檢測。
windows_wsl_setup_acknowledged boolean 記錄 Windows onboarding 是否已確認（僅 Windows）。
chatgpt_base_url string 覆蓋 ChatGPT 登入流程所使用的 base URL。
cli_auth_credentials_store file | keyring | auto 控制 CLI 把快取憑據儲存在何處（檔案型 auth.json 或作業系統 keychain）。
mcp_oauth_credentials_store auto | file | keyring MCP OAuth 憑據的首選儲存位置。
mcp_oauth_callback_port integer MCP OAuth 登入時本機 HTTP callback server 使用的固定埠。未設定時由作業系統分配臨時埠。
mcp_oauth_callback_url string MCP OAuth 登入的可選基礎回撥 URL 覆蓋值，例如 devbox ingress URL。Codex 會在傳送最終 OAuth redirect_uri 前追加 server 專屬回撥 ID，因此請在提供方處註冊完整派生 URI。mcp_oauth_callback_port 仍然控制回撥監聽埠。
experimental_use_unified_exec_tool boolean 啟用 unified exec 的舊鍵名；優先使用 [features].unified_exec 或 codex --enable unified_exec。
tools.web_search boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } } 可選的 web search 工具設定。舊版布林寫法仍被接受，但物件寫法可額外設定搜尋上下文大小、允許域名，以及近似使用者位置。
tools.view_image boolean 啟用本機圖片附件工具 view_image。
web_search disabled | cached | indexed | live Web search 模式。預設 "cached"：使用 OpenAI 維護的索引且不存取外部 Web；"indexed" 只在搜尋索引放行時存取外部 Web；使用 --yolo 或其他 full access sandbox 設定時預設切到 "live"。"live" 允許不受索引門控的即時檢索，"disabled" 會移除該工具。
default_permissions string 應用於沙箱化工具呼叫的預設權限設定檔名稱。內建值為 :read-only、:workspace 和 :danger-full-access；自定義設定檔名稱必須有對應的 [permissions.<name>] 表。不要和 sandbox_mode 或 [sandbox_workspace_write] 混用。
permissions.<name>.description string 這個具名設定檔的人類可讀說明。設定檔不會通過 extends 繼承父級的 description。
permissions.<name>.extends string 可選父級設定檔，會先於當前具名設定檔應用。可以設為另一個具名設定檔、:read-only 或 :workspace；:danger-full-access、未定義父級和繼承迴圈會被拒絕。
permissions.<name>.workspace_roots table 由設定檔定義的工作區根目錄，會和當前會話的執行時工作區根目錄一起接收 :workspace_roots 檔案系統規則。
permissions.<name>.workspace_roots.<path> boolean 值為 true 時，把該路徑加入這個設定檔的工作區根目錄集合；停用的條目保持不生效。
permissions.<name>.filesystem table 命名的檔案系統權限設定檔。每個 key 可以是絕對路徑，或 :minimal、:workspace_roots 等特殊標記。
permissions.<name>.filesystem.glob_scan_max_depth number 在某些需要在沙箱啟動前快照匹配結果的平台上，展開 deny-read glob pattern 的最大深度。設定時必須至少為 1。
permissions.<name>.filesystem.<path-or-glob> "read" | "write" | "deny" | table 對某個路徑、glob pattern 或特殊標記直接賦權，或在該根下繼續做巢狀授權。使用 "deny" 可以拒絕讀取匹配路徑。
permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob> "read" | "write" | "deny" 相對於每個有效工作區根目錄設定存取權限。用 "." 表示根目錄本身；可用 "**/*.env" 這類 glob 子路徑配合 "deny" 拒絕讀取。
permissions.<name>.network.enabled boolean 是否為該命名權限設定檔啟用網路存取。這會改變沙箱網路策略，但不會自行啟動網路代理。
permissions.<name>.network.proxy_url string 當該權限設定檔啟用沙箱化網路時使用的 HTTP 監聽器 URL。
permissions.<name>.network.enable_socks5 boolean 當該權限設定檔啟用沙箱化網路時，暴露 SOCKS5 支援。
permissions.<name>.network.socks_url string 該權限設定檔使用的 SOCKS5 代理端點。
permissions.<name>.network.enable_socks5_udp boolean 在啟用 SOCKS5 監聽器時允許 UDP。
permissions.<name>.network.allow_upstream_proxy boolean 允許沙箱化網路級聯到另一個 upstream proxy。
permissions.<name>.network.dangerously_allow_non_loopback_proxy boolean 允許沙箱化網路監聽器繫結非 loopback 地址。啟用後可能把監聽器暴露到 localhost 之外。
permissions.<name>.network.dangerously_allow_all_unix_sockets boolean 允許任意 Unix socket 目的地，而不是預設受限集合。只能在嚴格受控環境中使用。
permissions.<name>.network.mode limited | full 子程序流量使用的網路代理模式。
permissions.<name>.network.domains table 沙箱化網路的域名規則。支援精確主機、只匹配子域名的 *.example.com、同時匹配 apex 和子域名的 **.example.com，以及全域 * allow 規則。衝突時 deny 優先。
permissions.<name>.network.domains.<pattern> allow | deny 允許或拒絕精確主機，或 *.example.com、**.example.com 這類限定萬用字元模式。
permissions.<name>.network.unix_sockets table 沙箱化網路的 Unix socket allowlist 覆蓋。鍵為 socket 路徑；allow 會加入路徑，deny 會拒絕該路徑。
permissions.<name>.network.unix_sockets.<path> allow | deny 用 allow 把絕對 Unix socket 路徑加入有效 allowlist，或用 deny 拒絕該路徑。被拒絕的條目會從有效 allowlist 中省略。
permissions.<name>.network.allow_local_binding boolean 允許通過沙箱化網路進行更寬的本機 / 私有網路存取。當它保持 false 時，精確本機 IP literal 或 localhost allow 規則仍可允許特定本機目標。
projects.<path>.trust_level string 將某個專案或工作樹標記為可信或不可信（"trusted" | "untrusted"）。不可信專案會跳過專案作用域的 .codex/ 設定層，包括專案本機設定、鉤子和規則。
notice.hide_full_access_warning boolean 記錄是否已確認 full access warning 提示。
notice.hide_world_writable_warning boolean 記錄是否已確認 Windows world-writable 目錄警告。
notice.hide_rate_limit_model_nudge boolean 記錄是否選擇不再看到 rate limit 模型切換提醒。
notice.hide_gpt5_1_migration_prompt boolean 記錄是否已確認 GPT-5.1 遷移提示。
notice.hide_gpt-5.1-codex-max_migration_prompt boolean 記錄是否已確認 gpt-5.1-codex-max 遷移提示。
notice.model_migrations map<string,string> 以 old->new 對映方式記錄已確認的模型遷移。
forced_login_method chatgpt | api 將 Codex 限制為某一種認證方式。
forced_chatgpt_workspace_id string (uuid) 將 ChatGPT 登入限制在某個特定 workspace identifier。

你可以在 這裡 找到最新的 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 強制規則。具體優先順序請參見 託管設定。

你也可以在 requirements.toml 中使用 [features]，通過 config.toml 使用的同一組 canonical key 固定執行時功能開關。Requirements 還可以包含文件列出的僅 App 鍵，它們不屬於 config.toml。沒有寫出的鍵不會受到限制。

部分託管要求會強制使用精確設定值，而不是 allowlist。使用者無法覆蓋被強制指定的路徑、更新偏好、login 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 flag 或 --config 顯式選擇的啟動值優先順序更高。顯式模型或推理強度覆蓋會同時跳過兩個託管模型欄位；service_tier 會獨立處理。

鍵 類型 / 可選值 說明
sqlite_home string (path) 強制指定 Codex 儲存 SQLite 支援的執行時狀態的目錄。
log_dir string (path) 強制指定 Codex 寫入本機日誌檔案的目錄。
model_catalog_json string (path) 強制指定 Codex 啟動時使用的 JSON 模型目錄。
check_for_update_on_startup boolean 強制指定 Codex 啟動時是否檢查更新。
allow_login_shell boolean 強制指定 shell 工具能否啟動 login shell。
feedback table 託管回饋設定。
feedback.enabled boolean 強制指定使用者能否在各個 Codex 客戶端中提交回饋。
allowed_approval_policies array<string> approval_policy 允許使用的值，例如 untrusted、on-request、never 和 granular。
allowed_approvals_reviewers array<string> approvals_reviewer 允許使用的值，例如 user 和 auto_review。
guardian_policy_config string 自動審查使用的託管 Markdown 策略指令。它的優先順序高於本機 [auto_review].policy；空值會被忽略。
allowed_permission_profiles table<boolean> 完整的權限設定檔允許列表。設為 true 的設定檔會被允許；省略或設為 false 的設定檔會被拒絕，包括未來版本新增的設定檔。合併多個 requirements 來源時，會按設定檔名稱匹配條目。
allowed_permission_profiles.<name> boolean 允許或拒絕已載入設定或 requirements 來源中定義的內建 / 自定義權限設定檔。較晚、優先順序更高的 requirements 來源可以用 false 關閉較早、優先順序更低來源允許的設定檔。
default_permissions string 託管預設權限設定檔。該設定檔必須被 allowed_permission_profiles 允許。請顯式設定它，以獲得可預測行為；如果省略，只有在 :workspace 和 :read-only 都被顯式允許時，Codex 才會預設使用 :workspace。
enforce_residency string 要求 Codex 服務流量使用受支援的資料駐留。目前接受 us。
models table 新任務使用的託管模型預設值。它們優先於使用者和專案預設值，但啟動新任務時的顯式選擇仍可覆蓋。
models.new_thread table 啟動新的本機 thread 時應用的預設值；每項模型設定都可省略。
models.new_thread.model string 新 thread 的預設模型。顯式 --model 或模型 / 推理相關 --config 覆蓋優先。
models.new_thread.model_reasoning_effort string 新 thread 的預設推理強度。顯式模型或推理強度覆蓋會同時跳過這兩個託管模型欄位。
models.new_thread.service_tier string 新 thread 的預設 service tier。顯式 service-tier 覆蓋會獨立優先於該值。
permissions table 按設定檔名稱組織的管理員定義權限設定檔。使用與 config.toml 相同的設定檔欄位。
permissions.<name> table 管理員定義的權限設定檔。名稱不能以 : 開頭，不能使用保留名稱 filesystem，也不能和已載入設定中的設定檔重名。使用與 config.toml 相同的設定檔欄位；完整 schema 見權限。
allowed_sandbox_modes array<string> sandbox_mode 允許使用的值。
windows table Windows 原生沙箱 requirements。
windows.allowed_sandbox_implementations array<string> windows.sandbox 允許使用的原生 Windows 沙箱實現（elevated 和 unelevated）。列表不能為空。兩者都允許且未選擇模式時，Codex 優先使用 elevated。
windows.sandbox_private_desktop boolean 強制指定原生 Windows 沙箱是否在私有桌面上啟動子程序。
remote_sandbox_config array<table> 針對特定主機的沙箱強制要求。第一個 hostname_patterns 匹配解析後主機名的條目，會覆蓋該 requirements 來源頂層的 allowed_sandbox_modes。當前主機級條目只會覆蓋沙箱模式。
remote_sandbox_config[].hostname_patterns array<string> 不區分大小寫的主機名模式。支援用 * 匹配任意字元序列，用 ? 匹配單個字元。
remote_sandbox_config[].allowed_sandbox_modes array<string> 當該主機級條目命中時要應用的沙箱模式允許列表。
allowed_web_search_modes array<string> web_search 允許使用的值（disabled、cached、indexed、live）。disabled 永遠允許；若為空陣列，則效果上只允許 disabled。
allow_managed_hooks_only boolean 為 true 時，Codex 會跳過使用者、專案、會話和外掛 hooks，但仍允許 requirements.toml 與其他託管設定層提供的託管 hooks。
allow_appshots boolean 設為 false 可為受管理使用者停用 Appshots。如果省略，Appshots 不會受到 requirements 約束，仍按正常產品可用性決定。
allow_remote_control boolean 設為 false 可為受管理使用者停用裝置遠端控制。如果省略，裝置遠端控制不會受到 requirements 約束，仍按正常產品可用性決定。
features.plugin_sharing boolean 在 cloud-managed requirements.toml 中設為 false 可停用本機建置外掛的工作區共享。
features table 固定功能值。執行時功能使用 config.toml 中的 canonical key；這裡也支援文件列出的僅 App requirements 鍵。
features.<name> boolean 要求某個已記錄的執行時功能或 App 功能保持啟用或停用。
features.apps boolean 固定受管理使用者的 Apps 整合可用性。
features.in_app_updates boolean 在 requirements.toml 中設為 false 可停用 App 內更新。省略此要求時，更新預設保持啟用。
features.in_app_browser boolean 在 requirements.toml 中設為 false 可停用內建瀏覽器面板。
features.browser_use boolean 在 requirements.toml 中設為 false 可停用瀏覽器中的 Computer Use 和 Browser Agent。
features.browser_use_external boolean 在 requirements.toml 中設為 false 可停用外部瀏覽器中的 Computer Use。
features.browser_use_full_cdp_access boolean 在 requirements.toml 中設為 false 可停用本機執行時中的完整 Chrome DevTools Protocol 存取（包括 Browser Developer mode），並阻止 ChatGPT 桌面應用啟用對應設定。省略時按正常產品可用性決定。
features.fast_mode boolean 固定受管理使用者的 canonical fast_mode 功能開關。
features.guardian_approval boolean 固定受管理使用者的 Guardian approval 可用性。
features.memories boolean 固定受管理使用者的 Memories 可用性。
features.multi_agent boolean 固定受管理使用者的 multi-agent 可用性。
features.plugins boolean 固定受管理使用者的外掛可用性。
features.remote_plugin boolean 固定受管理使用者的遠端 plugin 目錄可用性。
features.computer_use boolean 在 requirements.toml 中設為 false 可停用 Computer Use、Record & Replay 及相關安裝或設定流程。
features.workspace_dependencies boolean 固定受管理使用者的捆綁工作區依賴執行時可用性。
computer_use table 從 requirements.toml 強制執行的 Computer Use requirements。
computer_use.allow_locked_computer_use boolean 設為 false 可阻止 Computer Use 在託管 macOS 裝置鎖定後繼續操作。如果省略，鎖定狀態使用不會被 requirements 約束。
experimental_network table 從 requirements.toml 強制執行的網路存取要求。這些約束與 features.network_proxy 相互獨立，可以在沒有使用者功能開關的情況下設定沙箱化網路。
experimental_network.enabled boolean 啟用沙箱化網路要求。如果當前啟用的沙箱關閉命令聯網，這不會授予網路存取。
experimental_network.http_port integer [experimental_network] 要求使用的 loopback HTTP 監聽器埠。
experimental_network.socks_port integer [experimental_network] 要求使用的 loopback SOCKS5 監聽器埠。
experimental_network.allow_upstream_proxy boolean 允許沙箱化網路使用環境中的 upstream proxy。
experimental_network.dangerously_allow_non_loopback_proxy boolean 允許 [experimental_network] 要求使用非 loopback 監聽器地址。啟用後可能把監聽器暴露到 localhost 之外。
experimental_network.dangerously_allow_all_unix_sockets boolean 允許任意 Unix socket 目的地，而不是 allowlist-only 存取。只能在嚴格受控環境中使用。
experimental_network.domains map<string, allow | deny> 管理員域名策略。支援精確主機、*.example.com、**.example.com 和全域 * allow 規則；應優先使用更窄規則。衝突時 deny 優先。不要與 experimental_network.allowed_domains 或 experimental_network.denied_domains 混用。
experimental_network.allowed_domains array<string> 列表形式的管理員 allow 規則。不要與 experimental_network.domains 混用。
experimental_network.denied_domains array<string> 列表形式的管理員 deny 規則。不要與 experimental_network.domains 混用。
experimental_network.managed_allowed_domains_only boolean 為 true 時，在沙箱化網路要求生效期間，只有管理員管理的 allow 規則繼續有效；使用者新增的 allowlist 條目會被忽略。若沒有託管 allow 規則，使用者新增的域名 allow 規則也不會繼續有效。
experimental_network.unix_sockets map<string, allow | deny> 管理員管理的 Unix socket 策略，用於沙箱化網路。
experimental_network.allow_local_binding boolean 允許沙箱化網路進行更寬的本機 / 私有網路存取。當它保持 false 時，精確本機 IP literal 或 localhost allow 規則仍可允許特定本機目標。
hooks table 管理員強制的託管生命週期鉤子。需要設定託管鉤子目錄，並使用與 config.toml 內聯 [hooks] 相同的事件 schema。
hooks.managed_dir string (absolute path) macOS 和 Linux 上存放託管鉤子指令碼的目錄。Codex 會在載入託管鉤子前校驗它是絕對路徑且已存在。
hooks.windows_managed_dir string (absolute path) Windows 上存放託管鉤子指令碼的目錄。Codex 會在載入託管鉤子前校驗它是絕對路徑且已存在。
hooks.<Event> array<table> 某個鉤子事件的 matcher 分組，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SessionEnd、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。
hooks.<Event>[].hooks array<table> matcher 分組下的鉤子處理器。當前支援 command hooks；prompt 和 agent hook handlers 會被解析但跳過。
hooks.<Event>[].hooks[].commandWindows string command hooks 的 Windows 專用命令覆蓋。也接受 TOML alias command_windows。
permissions.filesystem.deny_read array<string> 管理員強制的檔案系統讀拒絕規則。條目可以是路徑或 glob pattern，使用者不能通過本機設定放寬這些規則。
mcp_servers table 允許啟用的 MCP server allowlist。只有當 server 名稱（<id>）和身份資訊都匹配時，該 MCP server 才能啟用。凡是不在 allowlist 中，或身份不匹配的 MCP server，都會被停用。
mcp_servers.<id>.identity table 單個 MCP server 的身份規則。可設定 command（stdio）或 url（streamable HTTP）之一。
mcp_servers.<id>.identity.command string | table 可以用精確的 command 字串允許一個 MCP stdio server，也可以用 matcher table 要求精確的 executable 和有序參數 matcher。字串形式不會檢查參數、cwd、env 或 env_vars。
mcp_servers.<id>.identity.command.executable string stdio server 設定的 command 必須精確匹配的 executable。
mcp_servers.<id>.identity.command.args array<table> stdio server 的有序參數 matcher。已設定的參數列表長度必須相同，且每個位置都要匹配。Command matcher 不會檢查 cwd、env 或 env_vars。
mcp_servers.<id>.identity.command.args[].match exact | prefix | regex 該參數位置使用的匹配操作。
mcp_servers.<id>.identity.command.args[].value string exact 或 prefix 參數 matcher 使用的值。
mcp_servers.<id>.identity.command.args[].expression string regex 參數 matcher 使用的正規表示式。表示式必須有效，並匹配完整參數值。
mcp_servers.<id>.identity.url string | table 可以用精確的 URL 字串允許一個 MCP streamable HTTP server，也可以用 exact、prefix 或 regex value matcher table。
mcp_servers.<id>.identity.url.match exact | prefix | regex 已設定 MCP server URL 使用的匹配操作。
mcp_servers.<id>.identity.url.value string exact 或 prefix URL matcher 使用的值。
mcp_servers.<id>.identity.url.expression string regex URL matcher 使用的正規表示式。表示式必須有效，並匹配完整 URL 值。
plugins table 按外掛標識組織的外掛專屬 MCP server allowlist。存在該 table 時，沒有匹配 plugin 和 server 條目的外掛打包 server 會被停用。
plugins.<plugin>.mcp_servers table 某個外掛打包的 MCP server allowlist。外掛 server requirements 使用與頂層 mcp_servers requirements 相同的精確身份和 matcher 形態。
plugins.<plugin>.mcp_servers.<server>.identity table 某個外掛打包 MCP server 的身份規則。可設定 command（stdio）或 url（streamable HTTP）之一。
plugins.<plugin>.mcp_servers.<server>.identity.command string | table 可以用精確的 command 字串允許某個外掛 stdio MCP server，也可以用 matcher table 要求精確 executable 和有序參數 matcher。
plugins.<plugin>.mcp_servers.<server>.identity.command.executable string 外掛打包 stdio server 設定的 command 必須精確匹配的 executable。
plugins.<plugin>.mcp_servers.<server>.identity.command.args array<table> 外掛打包 stdio server 的有序參數 matcher。已設定的參數列表長度必須相同，且每個位置都要匹配。
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match exact | prefix | regex 該參數位置使用的匹配操作。
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value string exact 或 prefix 參數 matcher 使用的值。
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression string regex 參數 matcher 使用的正規表示式。表示式必須匹配完整參數值。
plugins.<plugin>.mcp_servers.<server>.identity.url string | table 可以用精確的 URL 字串允許某個外掛 streamable HTTP MCP server，也可以用 exact、prefix 或 regex value matcher table。
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 matcher 使用的值。
plugins.<plugin>.mcp_servers.<server>.identity.url.expression string regex URL matcher 使用的正規表示式。表示式必須匹配完整 URL 值。
marketplaces table 外掛 marketplace source 的管理員 requirements。只有在 restrict_to_allowed_sources 為 true 時，規則才會生效。
marketplaces.restrict_to_allowed_sources boolean 為 true 時，使用者自設定 marketplace source 必須匹配 allowed_sources，才能執行 marketplace add、外掛安裝和已設定 Git marketplace 重新整理操作。只要 reserved source 和 name 匹配，Codex 管理的 OpenAI marketplaces 仍然允許使用。這不會在執行時過濾已經設定好的使用者 marketplaces。
marketplaces.allowed_sources table 以管理員選擇的規則名為鍵的允許 marketplace source。不同名稱會跨 requirements 層累積；同名條目下的欄位按正常層級優先順序處理。
marketplaces.allowed_sources.<name> table 單條允許 source 規則。requirements 合併後的最終 source 值決定 Codex 如何解釋同級欄位。
marketplaces.allowed_sources.<name>.source git | host_pattern | local Marketplace source matcher 類型。git 用於單個儲存庫，host_pattern 用於正則匹配 Git host，local 用於單個目錄。
marketplaces.allowed_sources.<name>.url string 當 source = "git" 時必填的 Git 儲存庫 URL。Codex 會先規範化已設定 URL 和允許 URL，再要求儲存庫精確匹配。
marketplaces.allowed_sources.<name>.ref string git 規則可選的精確 Git ref。省略時，該規則允許匹配儲存庫的任意 ref。
marketplaces.allowed_sources.<name>.host_pattern string 當 source = "host_pattern" 時必填的正規表示式。Codex 會把它與從 HTTPS、SSH 或 SCP-style Git source 解析出來的小寫 hostname 匹配。若要匹配完整 host，請使用 ^ 和 $。
marketplaces.allowed_sources.<name>.path string (absolute path) 當 source = "local" 時必填的本機 marketplace 目錄。Codex 要求絕對路徑，並在路徑規範化後比較。
apps table 按 app 標識組織的託管 app requirements。Requirements 可以停用某個 app，或約束單個工具的審批行為。
apps.<id>.enabled boolean 設為 false 可停用某個 app。合併多個 requirements 來源時，停用要求仍會保持收緊。
apps.<id>.tools.<tool>.approval_mode auto | prompt | writes | approve 設定某個 app 工具的託管審批模式。
rules table 與 .rules 檔案合併的管理員強制命令規則。requirements 中的 rules 必須是收緊型限制。
rules.prefix_rules array<table> 強制生效的 prefix rules 列表。每條規則都必須包含 pattern 和 decision。
rules.prefix_rules[].pattern array<table> 以字首 token 形式表達的命令模式。每個 token 位置都要設定 token 或 any_of。
rules.prefix_rules[].pattern[].token string 該位置必須匹配的單個字面 token。
rules.prefix_rules[].pattern[].any_of array<string> 該位置允許的多個備選 token。
rules.prefix_rules[].decision prompt | forbidden 必填。requirements 中的規則只能是 prompt 或 forbidden，不能是 allow。
rules.prefix_rules[].justification string 可選的非空說明，會顯示在 approval 提示或拒絕訊息中。

來源：</zh-TW/docs/config-file/config-reference> 更新時間：2026-07-10（UTC）