高階設定

當你需要更精細地控制供應商、策略和整合時，請使用這些選項。如需快速入門，請參閱設定基礎。

如需瞭解專案指導、可複用能力、自定義斜槓命令、子智能體工作流程和整合的背景資訊，請參閱自定義。有關設定鍵，請參閱設定參考。

設定方案

設定方案可讓你儲存具名設定層，並通過 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，而不是定義新的供應商。這樣無需單獨新增 model_providers.<id> 條目，即可更改內建 openai 供應商的基礎 URL。

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 會同時載入 兩者並發出警告。每個設定層最好只使用一種表示形式。

有關當前事件列表、輸入欄位、輸出行為和限制，請參閱 鉤子。

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

有關子智能體角色設定（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 時主動重新整理；將 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 只保留 與 include 模式匹配的變數。include 不會恢復已被排除的變數。 過濾器鍵會在設定層之間以不區分大小寫的方式合並。

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

Codex 會依次應用自動排除規則、自定義排除規則、來自 set 的值，最後應用 include 模式允許列表。由於 set 在 排除規則之後執行，因此它可以恢復被排除的變數。include 模式允許列表 仍可能移除這個已恢復的值。

舊版 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），且不包含 codex 嘗試應用的實際 shell 命令或補丁。

執行時和模型傳輸

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）不會發出原始推理；在這種情況下，此設定不會產生可見效果。

通知

每當 Codex 發出支援的事件（目前僅限 agent-turn-complete）時，使用 notify 觸發外部程式。這適用於桌面通知、聊天 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 控制是否僅在終端為 unfocused 或 always 時觸發 TUI 通知。

在 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 追加一個包含 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 }
}

選擇自定義處理程序作為首選編輯器後，其選擇將以與選擇內建編輯器相同的 方式持久儲存，包括按專案儲存的偏好設定。

TUI 選項

執行不帶子命令的 codex 會啟動互動式終端 UI（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）。

有關完整的鍵列表，請參閱設定參考。