進階設定

當您需要進一步控制供應商、政策與整合時，請使用這些選項。如要快速開始，請參閱基本設定。

如需瞭解專案指引、可重複使用的能力、自訂斜線指令、子代理程式工作流程與整合的背景資訊，請參閱自訂。如需設定鍵資訊，請參閱設定參考資料。

設定檔

設定檔可讓您儲存具名設定層， 並透過 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.6-sol"
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 覆寫單次執行的設定：

• 如有專用旗標，請優先使用，例如 --model。
• 若需覆寫任意設定鍵，請使用 -c / --config。

範例：

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not 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"]'

注意事項：

• 設定鍵可以使用點標記法設定巢狀值，例如 mcp_servers.context7.enabled=false。
• --config 的值會以 TOML 格式剖析。如不確定，請為值加上引號，以免 Shell 在空格處將其拆分。
• 若無法將值剖析為 TOML，Codex 會將其視為字串。

設定與狀態的儲存位置

Codex 將本機狀態儲存在 CODEX_HOME 下（預設為 ~/.codex）。

該位置可能包含以下常見檔案：

• config.toml（您的本機設定）
• auth.json（若使用檔案型憑證儲存），或作業系統的鑰匙圈／金鑰環
• history.jsonl（若已啟用歷程記錄持續保存）
• 其他個別使用者的狀態，例如記錄檔與快取

如需身分驗證的詳細資訊，包括憑證儲存模式，請參閱身分驗證。如需完整的設定鍵清單，請參閱設定參考資料。

如需瞭解存放在程式碼庫或系統路徑中的共用預設值、規則和技能，請參閱團隊設定。

如果只需將內建 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 會載入兩者並發出警告。建議每一層只使用一種表示方式。

如需目前的事件清單、輸入欄位、輸出行為和限制，請參閱 掛勾。

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

如需子代理程式角色設定（config.toml 中的 [agents]）的說明，請參閱子代理程式。

專案根目錄偵測

Codex 會從工作目錄逐層向上搜尋，直到專案根目錄，以尋找專案設定，例如 .codex/ 層與 AGENTS.md。

預設情況下，Codex 會將包含 .git 的目錄視為專案根目錄。若要自訂此行為，請在 config.toml 中設定 project_root_markers：

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

設定 project_root_markers = []，即可略過上層目錄搜尋，並將目前工作目錄視為專案根目錄。

自訂模型供應商

模型供應商定義 Codex 連線至模型的方式，包括基礎 URL、通訊 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"

如果自訂供應商支援獨立網頁搜尋端點， 請在其供應商設定中宣告這項能力：

[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。 獨立網頁搜尋仍在開發中，預設為關閉。將供應商能力設為 true 並不會啟用此功能：供應商必須支援相容的端點， 且所選模型與執行階段必須支援獨立搜尋。 已設定的 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 指定的間隔主動更新 Token；設定 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 則會以錯誤結束執行。

# Default local provider used with `--oss`
oss_provider = "ollama" # or "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 無法覆寫。

使用資料駐留的 API 組織

對於建立時已啟用資料駐留的專案，可以建立模型供應商，將 base_url 更新為使用正確的前置字串。對於已啟用資料駐留的 ChatGPT 工作區，無須自訂供應商；使用 ChatGPT 登入時，Codex 會遵循工作區的資料駐留設定。

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

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

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity 僅適用於使用 Responses API 的供應商。Chat Completions 供應商會忽略此設定。

核准政策與沙盒模式

選擇核准的嚴格程度（影響 Codex 何時暫停）與沙盒層級（影響檔案與網路存取）。

編輯 config.toml 時需留意的操作細節，請參閱常見的沙盒與核准組合、可寫入根目錄中的受保護路徑與網路存取。

Codex 和 ChatGPT Work 已不再支援 approval_policy = "untrusted"。請參閱 從已停用的 untrusted 核准政策遷移， 了解支援的設定，以及由專案設定衍生的更嚴格核准規則。

如需了解可同時設定檔案系統與網路存取的測試版權限設定檔，請參閱權限。

你也可以使用細粒度核准政策（approval_policy = { granular = { ... } }），允許個別類別的核准提示，或自動拒絕該類別的請求。如果你希望部分情況維持一般的互動式核准，而其他情況（例如 request_permissions 或技能指令碼的核准提示）則自動拒絕執行，這項設定就很實用。

設定 approvals_reviewer = "auto_review"，即可將符合條件的互動式核准請求 交由自動審查處理。這會變更審查者， 但不會改變沙盒邊界。

使用 [auto_review].policy 設定本機審查者的政策指示。 受管理的 guardian_policy_config 具有較高優先順序。

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# 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  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

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

具名權限設定檔

如需了解內建設定檔、自訂設定檔語法，以及完整的檔案系統與網路設定模型， 請參閱權限。

如需完整的設定鍵清單與必要條件限制，請參閱 設定參考與 受管理的設定。

完全停用沙盒（僅在環境已具備程序隔離機制時使用）：

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 就會 僅保留符合納入模式的變數。納入規則不會還原 已被排除的變數。跨設定層合併篩選鍵時， 不區分大小寫。

ignore_default_excludes 預設為 true，因此 Codex 不會自動 移除名稱包含 KEY、SECRET 或 TOKEN 的變數。將其設為 false， 即可在執行你明確設定的篩選條件之前，先套用這些自動排除規則。

Codex 會先套用自動排除規則，接著依序套用自訂排除規則、 set 中的值，最後套用納入模式允許清單。由於 set 在排除規則 之後執行，因此可以還原已被排除的變數。納入模式允許清單 仍可移除該還原值。

既有設定仍可使用舊版的 exclude 與 include_only 陣列。 請勿在同一設定層中，將其中任一陣列與 [shell_environment_policy.filters] 搭配使用； Codex 會拒絕這種組合。

MCP 伺服器

如需設定細節，請參閱專門的 MCP 文件。

可觀測性與遙測

啟用 OpenTelemetry（OTel）日誌匯出，即可追蹤 Codex 的執行作業（API 請求、SSE／事件、提示詞、工具核准／結果）。此功能預設停用；可透過 [otel] 啟用：

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

選擇匯出器：

[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 運作異常，並瞭解使用者正在使用哪些功能與組態選項，讓 Codex 團隊能專注於最重要的事項。這些指標不含任何個人識別資訊 (PII)。指標收集與 OTel 記錄／追蹤匯出互相獨立。

若要在一部機器上全面停用 ChatGPT 桌面版應用程式、Codex CLI 和 IDE 擴充功能的指標收集，請在組態中設定分析旗標：

[analytics]
enabled = false

每個指標都包含其專屬欄位，以及下列預設上下文欄位。

預設上下文欄位（適用於所有事件／指標）

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

指標目錄

每個指標都包含必要欄位，以及上述預設上下文欄位。以下指標名稱省略了 codex. 前綴。 大多數指標名稱集中定義於 codex-rs/otel/src/metrics/names.rs；此處也列出了在該檔案之外發出的特定功能指標。 若指標包含 tool 欄位，該欄位會顯示所使用的內部工具（例如 apply_patch 或 shell），但不會包含實際的 Shell 指令，也不會包含 codex 嘗試套用的修補內容。

執行階段與模型傳輸

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 應用程式 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）時觸發外部程式。這適用於桌面快顯通知、聊天 Webhooks、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 會執行外部程式（適合用於 Webhooks、桌面通知程式及 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 自訂指示。

桌面版

本節選項僅適用於 ChatGPT 桌面版應用程式。

新增自訂檔案處理常式

在使用者層級的 ~/.codex/config.toml 中，於 desktop.custom_file_handlers 下新增項目，即可使用 ChatGPT 桌面版應用程式 預設不支援的編輯器或內部啟動器開啟檔案。每個項目都會在應用程式的 開啟方式 選單中新增一個編輯器選項。當 command 是已存在的絕對路徑，或可透過應用程式的 PATH 找到時，應用程式就會列出該選項。

以下範例示範將檔案傳遞給處理常式的三種方式：

# Append the opened path directly after the command.
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# Place fixed arguments before the opened path.
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# Append one JSON argument with the path and editor context.
[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 桌面版應用程式。

處理常式 ID 是 TOML 資料表標頭的最後一段。它必須包含 1–64 個字元，以 ASCII 字母或數字開頭，其餘字元 只能是 ASCII 字母、數字、句點、底線或連字號。應用程式提供此 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"

每個處理常式都支援以下欄位：

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

• path 會將路徑附加為指令的最後一個引數。
• json_argument 會附加一個 JSON 物件，其中包含 target、path、appPath 和 location。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 }
}

將自訂處理常式選為偏好編輯器時，系統會以選擇內建編輯器時的相同方式儲存這項選擇， 包括各專案的偏好設定。

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：控制替代螢幕的使用方式（設為 never 可保留終端的回捲記錄）
• tui.show_tooltips：顯示或隱藏歡迎畫面上的入門工具提示

tui.notification_method 預設為 auto。在 auto 模式下，若終端看起來支援 OSC 9 通知，Codex 會優先使用這類通知（這是一種終端逸出序列，部分終端會將其解讀為桌面通知），否則會改用 BEL（\x07）。

完整的鍵清單請參閱組態參考資料。