高階設定

當你需要更細粒度地控制提供方、策略和整合時，請使用這些設定項。若你只需要快速入門，先看 設定基礎。

如果你想了解專案指導、可複用能力、自定義斜槓命令、子智能體工作流程和整合能力的背景概念，參見 自定義。如果你想查具體鍵名，參見 設定參考。

設定檔

設定檔允許你儲存具名設定層，並從 CLI 中切換。傳入 --profile profile-name 時，Codex 會先載入 ~/.codex/config.toml，再疊加 ~/.codex/profile-name.config.toml。設定檔名稱可以包含字母、數字、連字元和下劃線。

每個設定檔都使用獨立 TOML 檔案。設定檔檔案中直接寫頂層設定鍵，不要巢狀在 [profiles.profile-name] 下面。

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

由於設定檔檔案是疊加在使用者基礎設定之上、專案和 CLI 設定之下的一層，它只需要寫出和基礎設定不同的值。設定檔檔案也可以覆蓋 model_catalog_json；如果兩個檔案都設定了該值，Codex 會使用設定檔中的值。

從 Codex 0.134.0 開始，--profile 不再讀取 config.toml 中的 [profiles.profile-name]，頂層的 profile = "profile-name" 選擇器也不再支援。請把舊設定檔設定移動到 ~/.codex/profile-name.config.toml，然後從 config.toml 中移除對應的 [profiles.profile-name] 表和 profile = "profile-name" 選擇器。

通過 CLI 做一次性覆蓋

除了直接編輯 ~/.codex/config.toml 之外，你還可以在 CLI 中只對單次執行做設定覆蓋：

• 優先使用專用 flag，例如 --model
• 當你需要覆蓋任意設定鍵時，使用 -c / --config

範例：

# 专用 flag
codex --model gpt-5.6-terra

# 通用键值覆盖（这里的值是 TOML，不是 JSON）
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

補充說明：

• --config 裡的值使用的是 TOML 語法，而不是 JSON。
• 你可以覆蓋巢狀鍵，例如 mcp_servers.context7.enabled=false。
• 如果拿不準，請給值加上引號，避免 shell 因為空格把它拆開。
• 如果某個值無法被解析成 TOML，Codex 會把它當作普通字串處理。

設定與狀態檔案位置

Codex 會把本機狀態儲存在 CODEX_HOME 下，預設路徑是 ~/.codex。

你在其中最常見到的檔案包括：

• config.toml（你的本機設定）
• auth.json（如果你使用基於檔案的憑據儲存；否則會使用作業系統的 keychain / keyring）
• history.jsonl（如果啟用了歷史記錄持久化）
• 其他按使用者儲存的狀態，例如日誌與快取檔案

關於認證細節，包括憑據儲存模式，參見 認證。關於完整設定鍵列表，參見 設定參考。

關於被提交到儲存庫或系統路徑中的共享預設設定、規則和技能，參見 Team Config。

如果你只是想讓內建的 OpenAI 提供方指向某個 LLM 代理、路由器，或啟用了資料駐留的專案，可以直接在 config.toml 中設定 openai_base_url，而不必定義一個新的提供方。這樣會修改內建 openai 提供方的基礎 URL，而不需要額外建立 model_providers.<id> 條目。

openai_base_url = "https://us.api.openai.com/v1"

專案設定檔（.codex/config.toml）

除了使用者級設定外，Codex 還會讀取儲存庫內 .codex/config.toml 裡的專案級覆蓋設定。Codex 會從專案根目錄一路向下遍歷到當前工作目錄，並載入沿途找到的所有 .codex/config.toml。如果多個檔案定義了同一個鍵，則離當前工作目錄最近的檔案生效。

出於安全考慮，Codex 只會在專案被標記為可信時載入這些專案級設定檔。如果專案不可信，Codex 會忽略專案中的 .codex/ 設定層，包括 .codex/config.toml、專案本機鉤子和專案本機規則。使用者層和系統層保持獨立，仍會正常載入。

專案設定中的相對路徑，例如 model_instructions_file，會相對於包含該 config.toml 的 .codex/ 目錄來解析。

專案設定檔不能覆蓋可能重定向憑據、改變宿主應用請求後設資料、改變提供方認證、選擇設定檔，或執行本機通知與遙測命令的設定。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。提供方、通知和遙測相關鍵應設定在使用者級 ~/.codex/config.toml 中；設定檔請通過 --profile profile-name 和 ~/.codex/profile-name.config.toml 選擇。

生命週期鉤子

Codex 還可以載入位於活動設定層旁邊的生命週期鉤子，來源可以是 hooks.json 檔案，也可以是 config.toml 檔案中的內聯 [hooks] 表。

實踐中最常用的四個位置是：

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

專案本機鉤子只會在專案 .codex/ 設定層受信任時載入。使用者級鉤子與專案信任狀態無關。

內聯 TOML 鉤子使用與 hooks.json 相同的事件結構：

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

如果同一設定層同時包含 hooks.json 和內聯 [hooks]，Codex 會同時載入並給出警告。建議每個設定層只使用其中一種表示方式。

關於當前支援的事件列表、輸入欄位、輸出行為和限制，請參見 Hooks。

智能體角色（config.toml 中的 [agents]）

關於子智能體角色設定，也就是 config.toml 中的 [agents]，參見 子智能體。

專案根目錄檢測

Codex 會從當前工作目錄向上查詢專案根，從而發現專案設定，例如 .codex/ 設定層和 AGENTS.md。

預設情況下，Codex 會把包含 .git 的目錄視為專案根。若要自定義這一行為，可以在 config.toml 中設定 project_root_markers：

# 当目录中包含以下任一标记时，将其视为项目根目录。
project_root_markers = [".git", ".hg", ".sl"]

如果你設定 project_root_markers = []，Codex 就不會再向父目錄搜尋，而是直接把當前工作目錄視為專案根。

自定義模型提供方

模型提供方定義了 Codex 如何連線到某個模型，例如基礎 URL、wire_api 協議、認證方式，以及可選的 HTTP 請求頭。自定義提供方不能複用內建的保留 ID：openai、ollama 和 lmstudio。

你可以定義額外的提供方，並讓 model_provider 指向它們：

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

如果自定義提供方支援獨立的 Web search endpoint，請在提供方設定中宣告該能力：

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

自定義提供方的該設定預設為 false。獨立 Web search 仍在開發中，且預設關閉。把提供方能力設為 true 並不會自行啟用它：提供方必須支援相容 endpoint，所選模型和執行時也必須支援獨立搜尋。設定的 web_search 模式和託管搜尋限制仍然適用。

如有需要，也可以新增請求頭：

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

如果某個提供方需要 Codex 通過外部憑據助手獲取 bearer token，可以使用命令式認證：

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

認證命令不會收到 stdin，並且必須把 token 輸出到 stdout。Codex 會去掉首尾空白，把空 token 視為錯誤，並按 refresh_interval_ms 主動重新整理；設定 refresh_interval_ms = 0 後，只會在認證重試後重新整理。不要把 [model_providers.<id>.auth] 與 env_key、experimental_bearer_token 或 requires_openai_auth 混用。

Amazon Bedrock 提供方

Codex 內建了 amazon-bedrock 模型提供方。可以直接把它設為 model_provider；和自定義提供方不同，這個內建提供方只支援巢狀的 AWS 設定檔和區域覆蓋項。

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

如果省略 profile，Codex 會使用標準 AWS 憑據鏈。請把 region 設為處理請求的受支援 Bedrock 區域。

關於完整設定流程、認證選項、受支援模型和功能可用性，請參見通過 Amazon Bedrock 使用 ChatGPT Work 和 Codex。

OSS 模式（本機提供方）

傳入 --oss 後，Codex 可以使用 Ollama 或 LM Studio 等本機“開源”提供方。單次執行可通過 --local-provider 選擇提供方，也可用 oss_provider 設定預設值。如果兩者都沒有設定，互動式 CLI 會要求你選擇；codex exec 則會報錯退出。

# `--oss` 默认使用的本地提供方
oss_provider = "ollama" # 或 "lmstudio"

Azure 提供方與按提供方微調

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

如果你只是想修改內建 OpenAI 提供方的基礎 URL，請使用 openai_base_url，不要建立 [model_providers.openai]，因為內建提供方 ID 不能被覆蓋。

啟用了資料駐留的 ChatGPT 客戶

如果你的專案啟用了 資料駐留，可以建立一個模型提供方，把 base_url 換成正確字首。

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # 将 us 替换为对应地域前缀

模型推理、輸出詳細程度與限制

model_reasoning_summary = "none"          # 关闭摘要
model_verbosity = "low"                   # 缩短回答
model_supports_reasoning_summaries = true # 强制开启推理摘要
model_context_window = 128000             # 上下文窗口大小

model_verbosity 只對使用 Responses API 的提供方生效。基於 Chat Completions 的提供方會忽略這個設定。

審批策略與沙箱模式

你可以同時設定審批嚴格程度（控制 Codex 何時暫停）和沙箱級別（控制檔案 / 網路存取範圍）。

在編輯 config.toml 時，和這些設定相關的執行時行為細節可參考 常見的沙箱與審批組合、可寫根目錄中的受保護路徑 和 網路存取。

如果要使用同時設定檔系統和網路存取的 Beta（測試版）權限設定檔，請參見權限。

你也可以使用細粒度審批策略，也就是 approval_policy = { granular = { ... } }，按類別允許或自動拒絕單獨的提示。這適合你希望某些情形仍保留互動式核准，而另一些情形，例如 request_permissions 或技能指令碼提示，則預設直接拒絕的場景。

如果你希望把符合條件的互動式審批請求交給自動審查，可以設定 approvals_reviewer = "auto_review"。這隻會改變由誰來審查，不會改變沙箱邊界。

本機審查策略指令可以寫在 [auto_review].policy 裡。若管理員下發了 guardian_policy_config，則以託管策略為準。

approval_policy = "untrusted"   # 其他可选值：on-request、never 或 { granular = { ... } }
approvals_reviewer = "user"     # 也可以设为 "auto_review"，启用自动评审
sandbox_mode = "workspace-write"
allow_login_shell = false       # 可选加固项：禁止 shell 工具使用 login shell

# 细粒度审批策略示例：
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # 允许使用 $TMPDIR
exclude_slash_tmp = false       # 允许使用 /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # 如需出站网络访问，请显式开启

[auto_review]
policy = """
Use your organization's automatic review policy.
"""

命名權限設定檔

關於內建設定檔、自定義設定檔語法，以及完整的檔案系統與網路設定模型，請參見權限。

如果你需要完整鍵列表和 requirements 強制規則，參見 設定參考 與 託管設定。

如果你想徹底關閉沙箱（僅當你的執行環境本身已經提供程序隔離時才建議這樣做）：

sandbox_mode = "danger-full-access"

Shell 環境策略

shell_environment_policy 控制 Codex 會把哪些環境變數傳給它啟動的命令。可以通過 inherit = "none" 從空環境開始，也可以使用 inherit = "core" 繼承一組精簡變數。再新增顯式值與按鍵過濾器，避免把不必要的敏感資訊傳給命令。

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

過濾模式不區分大小寫，並支援 * 和 ?。使用 "exclude" 刪除匹配的變數。當任一模式使用 "include" 時，Codex 只保留匹配 include 模式的變數。include 不會恢復先前已排除的變數。不同設定層中的過濾鍵以不區分大小寫的方式合併。

ignore_default_excludes 預設為 true，因此 Codex 不會自動刪除名稱中包含 KEY、SECRET 或 TOKEN 的變數。將其設為 false 後，會先應用這些自動排除規則，再執行顯式過濾器。

Codex 依次應用自動排除、自定義排除、set 中的值，最後應用 include 模式的 allowlist。由於 set 在排除之後執行，它可以恢復已排除的變數；但 include allowlist 仍可能再次移除該值。

舊版 exclude 和 include_only 陣列仍受支援。不要在同一設定層中將其中任一陣列與 [shell_environment_policy.filters] 混用，否則 Codex 會拒絕該設定。

MCP server

關於 MCP server 的設定細節，參見獨立的 MCP 文件。

可觀測性與遙測

你可以啟用 OpenTelemetry（OTel）日誌匯出，用來追蹤 Codex 執行過程，包括 API 請求、SSE 事件、提示詞、工具審批和工具結果。該功能預設關閉；如需啟用，請在 [otel] 中設定：

[otel]
environment = "staging"   # 默认为 "dev"
exporter = "none"         # 设为 otlp-http 或 otlp-grpc 以发送事件
log_user_prompt = false   # 默认脱敏用户提示词，除非显式开启

你可以選擇匯出器：

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

如果 exporter = "none"，Codex 仍會記錄事件，但不會傳送出去。匯出器會非同步批次傳送，並在退出時重新整理。事件後設資料中會包含服務名、CLI 版本、環境標籤、會話 ID、模型、沙箱 / 審批設定，以及按事件不同而擴充套件的欄位，詳見 設定參考。

會發出哪些事件

Codex 會發出結構化日誌事件，用於描述執行過程和工具呼叫。代表性的事件類型包括：

• codex.conversation_starts：記錄模型、推理設定以及沙箱 / 審批策略
• codex.api_request：記錄請求次數、狀態 / 是否成功、耗時和錯誤詳情
• codex.sse_event：記錄流式事件類型、成功 / 失敗、耗時，以及在 response.completed 時附帶的 token 統計
• codex.websocket_request 和 codex.websocket_event：記錄請求耗時，以及每條訊息的類型 / 是否成功 / 錯誤資訊
• codex.user_prompt：記錄長度；除非顯式開啟，否則內容會被脫敏
• codex.tool_decision：記錄是核准還是拒絕，以及決定來自設定還是來自使用者
• codex.tool_result：記錄耗時、是否成功和輸出片段

OTel 發出的指標

當 OTel 指標流水線啟用後，Codex 會為 API、流式響應和工具活動發出計數器與耗時直方圖。

下面每個指標還會帶上預設後設資料標籤：auth_mode、originator、session_source、model、app.version。

關於遙測相關的安全與隱私建議，參見 監控與遙測。

匿名指標上報

預設情況下，Codex 會定期向 OpenAI 回傳少量匿名使用與健康狀態資料。這些資料有助於識別 Codex 何時工作異常，也能讓團隊瞭解哪些功能和設定正在被實際使用，從而把精力投入到最重要的問題上。這些指標不包含任何個人身份資訊（PII）。需要注意的是，指標收集與 OTel 日誌及 trace 匯出彼此獨立。

如果你想在某臺機器上的 ChatGPT 桌面應用、Codex CLI 和 IDE 擴充套件中徹底關閉指標收集，可在設定中設定分析資料上報開關 analytics：

[analytics]
enabled = false

每個指標除自身欄位外，還會帶上下面這些預設上下文欄位。

預設上下文欄位（適用於每個事件 / 指標）

• auth_mode：swic | api | unknown
• model：當前使用的模型名稱。
• app.version：Codex 版本。

指標目錄

每個指標都會帶上其必需欄位以及上面的預設上下文欄位。下面省略指標名字首 codex.。大多數指標名集中定義在 codex-rs/otel/src/metrics/names.rs；少量功能專屬指標會在對應功能程式碼中發出。如果某個指標帶有 tool 欄位，它表示內部工具名，例如 apply_patch 或 shell，不會包含 Codex 正在執行的實際 shell 命令或 patch 內容。

執行時與模型傳輸

cloud_requirements.fetch_attempt 指標包含 trigger、attempt、outcome 和 status_code 欄位。cloud_requirements.fetch_final 指標包含 trigger、outcome、reason、attempt_count 和 status_code 欄位。

會話輪次與工具活動

mcp.call 和 mcp.call.duration_ms 指標包含 status。常規工具呼叫還會包含 tool，並在可用時包含 connector_id 和 connector_name。被阻止的 Codex Apps MCP 呼叫可能只帶 status 發出 mcp.call。

對話執行緒、任務與功能

shell_snapshot 指標包含 success，失敗時還會包含 failure_reason。

記憶與本機狀態

external_agent_config.detect 和 external_agent_config.import 指標包含 migration_type；技能遷移還會包含 skills_count。

Windows 沙箱

提權設定失敗指標會在有 Windows 設定失敗細節時包含 code 和 message，從共享設定路徑發出時還可能包含 originator。windows_sandbox.legacy_setup_preflight_failed 從共享設定路徑發出時包含 originator，但回退提示中的預檢失敗可能不包含欄位。

回饋控制

預設情況下，本機客戶端允許使用者通過 /feedback 傳送回饋。如果你想在某臺機器上的 ChatGPT 桌面應用、Codex CLI 和 IDE 擴充套件中關閉回饋提交，可更新設定：

[feedback]
enabled = false

關閉後，/feedback 會顯示不可用提示，並且 Codex 會拒絕回饋提交。

隱藏或顯示推理事件

如果你想減少“推理”輸出帶來的噪音，例如出現在 CI 日誌中，可以壓制它：

hide_agent_reasoning = true

如果你想在模型有輸出時顯示原始推理內容：

show_raw_agent_reasoning = true

只有當你的工作流程能夠接受原始推理內容暴露時才建議開啟。某些模型 / 提供方，例如 gpt-oss，並不會輸出原始推理內容，這種情況下該設定不會產生可見效果。

通知

你可以使用 notify，在 Codex 發出受支援事件時觸發一個外部程式（目前僅支援 agent-turn-complete）。這很適合接入桌面通知、聊天 webhook、CI 狀態更新，或任何內建 TUI 通知沒有覆蓋到的旁路提醒。

notify = ["python3", "/path/to/notify.py"]

下面是一個會響應 agent-turn-complete 的 notify.py 範例（節選）：

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

該指令碼會收到一個單獨的 JSON 參數。常見欄位包括：

• type：當前為 agent-turn-complete
• thread-id：會話識別符號
• turn-id：當前輪次的識別符號
• cwd：工作目錄
• input-messages：觸發這一輪的使用者訊息
• last-assistant-message：助手最近一條訊息的文本內容

把指令碼放到磁碟上的任意位置，然後讓 notify 指向它即可。

notify 與 tui.notifications

• notify 用於執行外部程式，適合接 webhook、桌面通知程式或 CI 鉤子。
• tui.notifications 是 TUI 內建的通知機制，也可以按事件類型過濾，例如 agent-turn-complete 或 approval-requested。
• tui.notification_method 用於控制 TUI 傳送終端通知的方式，可選值為 auto、osc9 或 bel。
• tui.notification_condition 用於控制 TUI 通知只在終端 unfocused 時觸發，還是設為 always 後無論焦點狀態都觸發。

在 auto 模式下，Codex 會優先使用 OSC 9 通知。它是一種終端轉義序列，某些終端會把它解釋為桌面通知；如果不可用，則會退回到 BEL（\x07）。

具體鍵名見 設定參考。

歷史記錄持久化

預設情況下，Codex 會把本機會話記錄儲存到 CODEX_HOME 下，例如 ~/.codex/history.jsonl。如果你要關閉本機歷史記錄持久化：

[history]
persistence = "none"

如果你想限制歷史檔案大小，可設定 history.max_bytes。當檔案超過上限後，Codex 會丟棄最舊條目，並在保留最新記錄的前提下壓縮檔案。

[history]
max_bytes = 104857600 # 100 MiB

可點選引用

如果你的終端 / 編輯器整合支援，Codex 可以把檔案引用渲染為可點選連結。通過設定 file_opener，可指定 Codex 使用哪種 URI 方案：

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

例如，像 /home/user/project/main.py:42 這樣的引用，就可以被改寫成可點選的 vscode://file/...:42 連結。

專案指令發現

Codex 會讀取 AGENTS.md 以及相關檔案，並在會話的第一輪里納入一定量的專案指導。控制這一行為的兩個主要設定項是：

• project_doc_max_bytes：控制從 AGENTS.md 中最多讀取多少位元組
• project_doc_fallback_filenames：當 AGENTS.md 不存在時，按順序嘗試哪些替代檔名

更詳細說明參見 使用 AGENTS.md 編寫自定義說明。

Desktop

本節選項僅適用於 ChatGPT 桌面 App。

新增自定義檔案處理器

在使用者級 ~/.codex/config.toml 中，為 desktop.custom_file_handlers 新增條目，即可用 ChatGPT 桌面 App 預設不支援的編輯器或內部啟動器開啟檔案。每個條目都會在 App 的 Open in（開啟方式） 選單中增加一個編輯器目標。若 command 是現有絕對路徑，或能從 App 的 PATH 中解析，App 就會列出該目標。

下面的範例展示三種向 handler 傳遞檔案的方式：

# 把打开的路径直接追加到命令后。
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# 在打开的路径前放置固定参数。
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# 追加一个包含路径和编辑器上下文的 JSON 参数。
[desktop.custom_file_handlers.company_editor]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"
input = "json_argument"

儲存 config.toml，然後重啟 ChatGPT 桌面 App。

handler ID 是 TOML 表頭的最後一段。長度必須為 1–64 個字元，以 ASCII 字母或數字開頭，其餘字元只能使用 ASCII 字母、數字、句點、下劃線或連字元。App 會為 ID 新增 custom: 字首，例如 company_editor 會變成 custom:company_editor。包含句點的 ID 必須加引號，避免 TOML 將其解釋為巢狀表。例如：

[desktop.custom_file_handlers."company.editor"]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"

每個 handler 支援以下欄位：

input 的值決定 args 之後的內容：

• path：把路徑追加為最後一個命令參數。
• json_argument：追加一個包含 target、path、appPath 和 location 的 JSON 物件。location 是包含從 1 開始計數的 line、column 的物件，也可以是 null。
• json_stdin：把 JSON 物件寫入標準輸入，而不是追加參數。物件還包含 hostConfig、remoteWorkspaceRoot 和 remotePath；不適用時這些欄位為 null。

例如，當用戶開啟特定原始碼位置時，company_editor 可以收到以下參數：

{
  "target": "custom:company_editor",
  "path": "/repo/src/index.ts",
  "appPath": null,
  "location": { "line": 12, "column": 3 }
}

把自定義 handler 選為首選編輯器後，App 會像內建編輯器一樣儲存該選擇，包括專案級偏好。

TUI 選項

直接執行 codex 而不帶子命令時，會啟動互動式終端介面（TUI）。Codex 在 [tui] 下提供了一些 TUI 專屬設定項，包括：

• tui.notifications：啟用或關閉通知，也可以限制只接收特定類型的通知
• tui.notification_method：選擇終端通知方式，可用值為 auto、osc9 或 bel
• tui.notification_condition：選擇通知只在終端失焦時觸發，還是始終觸發；可用值為 unfocused 或 always
• tui.animations：啟用或關閉 ASCII 動畫與閃光效果
• tui.alternate_screen：控制是否使用備用螢幕（alternate screen）；設為 never 時會保留終端滾動歷史
• tui.show_tooltips：控制歡迎頁是否顯示引導提示

tui.notification_method 預設值為 auto。在 auto 模式下，如果 Codex 判斷當前終端支援，它會優先使用 OSC 9 通知。OSC 9 是一種終端轉義序列，有些終端會把它解釋為桌面通知；如果不可用，則會退回到 BEL（\x07）。

完整鍵列表請參見 設定參考。

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