MCP 深度整合、安全強化與效能成本調校

15.1 MCP client 進階鍵：env、過濾順序、Plugin 覆寫、OAuth 綁定

這節一句話重點：每個 MCP server 都吃你的 token 和 context，進階鍵讓你「給得剛剛好」——值不寫入磁碟、工具只露需要的、權限逐項管。

基礎的 [mcp_servers.名稱] 怎麼寫，見第 13 章。這裡只補高手才會碰的幾個鍵。

env vs env_vars：兩個長很像、語意完全不同的鍵

很多人把這兩個搞混，結果不是 token 明文寫入磁碟，就是環境變數沒傳進去：

官方逐字：env 是「Environment variables forwarded to the MCP stdio server」；env_vars 是「Additional environment variables to whitelist for an MCP stdio server」。

env_vars 還有進階寫法——可以指定從哪個環境取值：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]                       # 從你本機環境讀（預設 source = "local"）
# 或物件形式，從遠端 executor 環境讀：
# env_vars = [{ name = "TOKEN", source = "remote" }]

物件形式 { name = "TOKEN", source = "remote" } 要從遠端 executor 環境讀，前提是搭配 experimental_environment = "remote"（此鍵讓 stdio server 透過遠端 executor 啟動）。

逾時與必要性：startup_timeout 與 required

工具過濾的求值順序（組合技關鍵）

當你同時用白名單 enabled_tools 和黑名單 disabled_tools，順序很重要——黑名單後於白名單套用：

[mcp_servers.chrome_devtools]
enabled_tools  = ["open", "screenshot"]   # 1. 先白名單：只露這兩個
disabled_tools = ["screenshot"]           # 2. 再黑名單：screenshot 被剔除
# 最終：只剩 open

這是官方文件自己的範例。求值順序完整版：enabled_tools（白名單）→ disabled_tools（黑名單，後套用）→ default_tools_approval_mode（server 級核准）→ tools.<tool>.approval_mode（單一工具覆寫）。核准模式三個值：auto / prompt / approve。

Plugin-scoped 覆寫：不改 plugin 本體也能調它的 MCP

如果某個 plugin 內建了 MCP server，你可以用獨立命名空間覆寫它，而不去動 plugin 本身：

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

可覆寫的鍵：enabled / default_tools_approval_mode / enabled_tools / disabled_tools / tools.<tool>.approval_mode。

streamable HTTP 專屬欄位：跟 stdio 不是同一組鍵

前面 env / env_vars 講的都是 stdio server（本機子程序）。如果你接的是 streamable HTTP server（codex mcp add --url ... 那種），設定檔裡對應的是另一組欄位：

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
auth = "oauth"
scopes = ["repo", "user"]

OAuth callback 綁定（冷門安全細節）

連 OAuth 型的 HTTP server 時，callback 埠的綁定行為會影響暴露面：

另外，自建 server 時別忘了 server 在 init 回傳的 instructions 欄位會被 Codex 讀來輔助選工具，官方建議前 512 字元要 self-contained。

15.2 MCP CLI 與把 Codex 變成 MCP server

這節一句話重點：codex mcp add 幫你快速接 server（但沒有 --scope），而 codex mcp-server 能反過來把 Codex 自己變成別人能驅動的 MCP server——前提是你的 client 一定要接住 approval handler，否則它會卡死等核准。

codex mcp add 旗標（注意：沒有 --scope）

# 加一個 stdio server
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 只傳非敏感設定，例如日誌等級
codex mcp add myserver --env LOG_LEVEL=info -- my-server-cmd --flag

不改檔、單次 session 臨時覆寫任何 MCP 鍵，用全域 -c / --config：

# 臨時停用某 server
codex --config mcp_servers.context7.enabled=false

# 臨時拉長啟動逾時（值含特殊字記得用引號）
codex -c "mcp_servers.github.startup_timeout_sec=60"

# 結構化盤點 / 單點診斷
codex mcp list --json          # 機器可讀，含 marketplace 資訊
codex mcp get context7 --json  # 單一 server 的 raw config（診斷首選）

把 Codex 變成 MCP server

# 把 Codex 當 server 接到你的 client
codex mcp-server | your_mcp_client

# 用官方 Inspector 看可用方法（自建除錯首選）
npx @modelcontextprotocol/inspector codex mcp-server

指令名是 codex mcp-server（連字號），沒有 codex mcp serve。它走 stdio 的 JSON-RPC 2.0、line-delimited，downstream client 關連線時自己退出，並且會繼承全域設定覆寫。它也吃這些全域旗標：-c/--config、-p/--profile、-m/--model、--strict-config。

# 自建配方：用專屬 profile 驅動 + 設定打錯立即失敗
codex mcp-server -p ci-profile --strict-config

Approval handler 必接（否則 hang）

當你寫 client 去驅動 Codex server，Codex 會在要改檔 / 跑指令前丟「核准請求」給你，你必須回覆 {decision}，否則它會卡住等核准：

applyPatchApproval   { conversationId, callId, fileChanges, reason?, grantRoot? }
execCommandApproval  { conversationId, callId, approvalId?, command, cwd, reason? }
# Client 必須回：{ decision: "allow" | "deny" }

事後稽核：從 rollout JSONL 回放工具呼叫

不管是 Codex 自己呼叫 MCP 工具、還是別人透過 codex mcp-server 驅動 Codex，每一輪都會忠實記錄進 session JSONL（~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl，同一份檔案 15.14 會用來查 token 用量）。事後想知道某次自動化到底呼叫了哪些工具、帶了什麼參數、回傳了什麼，不用憑印象回想，直接查檔案：

jq 'select(.type == "tool_call")' ~/.codex/sessions/2026/07/10/rollout-*.jsonl

先把 rollout JSONL 視同機密紀錄。它可能含 prompt、工具參數、MCP 回應與路徑資訊；只在本機、權限受限的位置做最小範圍查詢，不要直接上傳、貼工單或 commit 原始檔。需要分享時，先篩選必要欄位，再手動遮罩憑證、個資與內網資訊。

這比事後憑記憶回報「那次自動化到底改了什麼」可靠得多，成本回顧、安全事件回顧都用得上。

15.3 MCP 除錯：段名硬規則、log、失敗模式表

這節一句話重點：MCP 連不上九成是三件事——段名打成連字號、握手逾時、ERROR 其實是假警報；先看 /mcp，再翻 log，別被 log 嚇到。

段名底線硬規則（最常見的靜默失敗）

[mcp_servers.myserver]   # ✅ 正確：底線
# [mcp-servers.myserver] # ❌ 連字號 → 靜默忽略，不報錯！
# [mcpServers.myserver]  # ❌ 駝峰 → 同樣靜默忽略

結構化診斷（官方優先）

# TUI 內：看 active server / transport / 已註冊工具
/mcp

# 單一 server 的 raw config（設定到底有沒有被讀到）
codex mcp get <server-name> --json

RUST_LOG 深度 trace 與 log 路徑

Codex 是 Rust 程式，可以用 RUST_LOG 控制分層 trace：

# 連不上 / 逾時時，先全開再縮
RUST_LOG=codex_core=trace codex

更精準的 module target（如 codex_core::mcp_connection_manager=trace）和 log 檔路徑 ~/.codex/log/codex-tui.log，出自第三方知識庫。

已知失敗模式速查表

0.140.0 的 MCP 可靠性改進

官方 changelog 逐字：「Improved MCP reliability by retrying transient startup failures, reporting unusable OAuth credentials as logged out, and preserving explicitly disabled servers.」

意思是：(1) 暫時性啟動失敗會自動重試；(2) OAuth 憑證失效會被當成「已登出」而非硬錯（去重登即可）；(3) 你手動標為 disabled 的 server 不會被自動拉回來。

15.4 MCP 效能與成本觀測：砍 schema、OTEL 指標

這節一句話重點：每個 MCP server、每個工具的 schema 都在你還沒打字前就吃掉 context；enabled_tools 是最直接的省錢動作，OTEL 則讓你量到底花了多少。

每個工具的 schema 都是成本

MCP server 越多、工具越多，system prompt 就越膨脹，不只貴，還更容易選錯工具。最直接的對策是用 enabled_tools 只暴露你真的會用的工具，砍掉 schema 噪音：

[mcp_servers.github]
enabled_tools = ["create_pull_request", "list_issues", "get_file_contents"]

重型 server 平時用 enabled = false 關著，要用時再 codex -c mcp_servers.<id>.enabled=true 臨時開。

OTEL MCP 指標

啟用 [otel] 區塊後，Codex 對 MCP 工具呼叫會發 metrics：

• codex.mcp.call（counter，計數）
• codex.mcp.call.duration_ms（histogram，耗時）

含 status 屬性；正常工具呼叫另含 tool，可用時含 connector_id / connector_name。

15.5 [permissions] named profile：超越 sandbox_mode 的細粒度權限

這節一句話重點：這是當前進階/企業部署的權限主軸——它能做到舊 sandbox_mode 做不到的事：「全 workspace 可寫，但連 .env 都不准讀」，代價是兩套系統不可混用。

入門教的 sandbox_mode + [sandbox_workspace_write] 仍可用（見第 4 章），但官方已推出更強的 [permissions] 命名 profile 系統。

三個內建 profile

自訂 profile + filesystem 三值

default_permissions = "project-edit"        # 選定預設 profile

[permissions.project-edit]
description = "Project editing, deny all secrets."
extends = ":workspace"                       # 可繼承 :read-only / :workspace / 其他具名 profile

filesystem 三個存取等級：

優先序鐵則（官方逐字）：「more specific entries override broader entries」，且同路徑下 deny > write > read。 這就是「可寫 source 但鎖死 .env」的關鍵——精確的 deny 蓋過廣泛的 write：

[permissions.project-edit.filesystem]
glob_scan_max_depth = 3                       # Linux/WSL/Windows 無界 ** 需要 bounded 預展開

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"                                 # workspace 整個可寫
"**/*.env" = "deny"                           # 但 .env 連讀都不准

支援的 path token：:root（檔系根）、:minimal（runtime 必要路徑）、:workspace_roots（當前 + profile 定義的 roots）、:tmpdir（$TMPDIR）、:slash_tmp（/tmp）、絕對路徑、~/path。subpath 相對於每個 workspace root 解析，../ parent traversal 被拒。

15.6 Approval × Sandbox 組合技：granular 五子鍵與 --add-dir

這節一句話重點：Approval 決定「何時停下來問」、Sandbox 決定「能碰什麼」，兩者組合出你的工作摩擦力；要多寫一個目錄，優先 --add-dir，別動不動就升 full-access。

官方鼓勵的三組 preset

granular 細粒度核可（五子鍵）

approval_policy 除了三個簡單值，還能給一個 granular 物件，逐欄獨立決定何時停下來問：

approval_policy = { granular = { sandbox_approval = true, rules = true, mcp_elicitations = true, request_permissions = false, skill_approval = false } }

五個 boolean 子鍵：sandbox_approval / rules / mcp_elicitations / request_permissions / skill_approval。

搭配 approvals_reviewer 決定「停下後誰來審」：

approvals_reviewer = "user"          # 預設；或 "auto_review"（交給獨立 reviewer 自動審）

--add-dir 優先於 full-access（決策樹）

官方建議：要寫更多目錄時，優先用 --add-dir（逐字「Grant additional directories write access alongside the main workspace」，可重複），而不是退化成 danger-full-access：

互動中還能即時調整：TUI 內 /permissions 切換權限、/status 確認當前 sandbox 與網路狀態。

workspace-write 收緊技巧

[sandbox_workspace_write]
writable_roots         = ["/Users/YOU/.pyenv/shims"]  # 額外可寫
network_access         = false   # 預設就是 false
exclude_tmpdir_env_var = true    # 連 $TMPDIR 都不放行
exclude_slash_tmp      = true    # 連 /tmp 都不放行

15.7 沙箱網路 proxy 白名單：只准連特定網域

這節一句話重點：Codex 自帶一個「沙箱內網域白名單代理」，讓你精確控制 agent 只能連 npm、GitHub 這幾個域；但有個已知 bug，白名單在 exec 模式可能沒擋到，務必實測。

這套網路 proxy 跟公司的 HTTP proxy（HTTPS_PROXY）不是同一回事——它是把 agent 的網路流量約束到你設定的政策。兩種寫法都是官方的：

寫法 (a)：features.network_proxy.*（全域）

features.network_proxy.enabled       # 預設 false
features.network_proxy.domains        # map<string, allow|deny>
features.network_proxy.proxy_url     # 預設 "http://127.0.0.1:3128"
features.network_proxy.socks_url     # 預設 "http://127.0.0.1:8081"
features.network_proxy.allow_upstream_proxy            # 預設 true（可串接公司 proxy）
features.network_proxy.allow_local_binding            # 預設 false
features.network_proxy.dangerously_allow_non_loopback_proxy   # 預設 false
features.network_proxy.dangerously_allow_all_unix_sockets     # 預設 false

寫法 (b)：[permissions.<name>.network]（profile 內）

[permissions.net-allowlist.network]
enabled = true

[permissions.net-allowlist.network.domains]
"registry.npmjs.org"      = "allow"
"*.npmjs.org"             = "allow"
"github.com"              = "allow"
"*.githubusercontent.com" = "allow"
"ads.example.com"         = "deny"     # deny 勝出
# 其餘未列即不放行

wildcard 語意（官方逐字）

DNS rebinding / 私網防護（冷門但重要）

預設會套用 local/private-network guard 防 DNS rebinding：DNS 查詢失敗/逾時的 host 一律 block，解析到私網 IP 的 host 也 block。要放行本機服務得顯式：

[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"
[permissions.project-edit.network]
allow_local_binding = true   # 允許 hostname 解析到私網 IP

full-access 也能加「集中 deny 名單」（企業進階）

PR #16946 新增 experimental_network.danger_full_access_denylist_only：讓 full-access session 保留完整網路、但仍套用集中管理的 deny 規則。

15.8 Secrets 衛生：KEY/SECRET/TOKEN 過濾與 --yolo 紅線

這節一句話重點：Codex 預設就幫你過濾掉名稱含 KEY/SECRET/TOKEN 的環境變數，但有一個鍵會關掉這層保護；--yolo 則是同時拆掉檔案與網路兩道牆的最高紅線。

shell_environment_policy：子程序拿到哪些環境變數

[shell_environment_policy]
inherit = "core"                       # none（乾淨）| core（精簡）
set = { PATH = "/usr/bin" }            # 強制覆寫
exclude = ["AWS_*", "AZURE_*"]         # glob，疊加在預設排除之上
include_only = ["PATH", "HOME"]        # 白名單
ignore_default_excludes = false        # 預設 false：保留內建金鑰過濾

預設行為：名稱含 KEY / SECRET / TOKEN（大小寫不敏感）的環境變數，會在你的其他 exclude 套用之前先被過濾掉。 過濾順序是「內建 default excludes 先跑，再跑你的 includes/excludes」。

最乾淨的隔離是白名單式：

# 子程序只拿到 PATH + HOME，secrets 全砍
[shell_environment_policy]
inherit = "none"
include_only = ["PATH", "HOME"]
ignore_default_excludes = false   # 保留內建過濾

預設 deny-read 的金鑰路徑

官方在 read-only / workspace-write 下會預設加一批 deny-read 保護常見金鑰檔。第三方整理的清單含 .env*、SSH 私鑰、.npmrc、.netrc、.aws/credentials 等。

auth.json 明文 token

~/.codex/auth.json（若 cli_auth_credentials_store = "file"）存的是明文 token，等同密碼級機密。建議改 cli_auth_credentials_store = "keyring"（存 OS 憑證庫；0.140.0 起 CLI/MCP OAuth 憑證已加密本地儲存，標待確認、以 changelog 為準）。找不到 auth.json 不代表沒登入——可能在 keyring。

--yolo 紅線

--dangerously-bypass-approvals-and-sandbox（別名 --yolo），官方逐字：「Run every command without approvals or sandboxing. Only use inside an externally hardened environment.」它同時拆掉檔案系統與網路兩道邊界。

15.9 沙箱實作機制：Seatbelt、bubblewrap+seccomp、WSL2

這節一句話重點：沙箱不是靠 AI「自律」，是靠作業系統核心把它關進籠子；三個平台用三套不同機制，Linux 的預設已經換掉了——別再照舊文寫 Landlock。

無法表達的 split 讀寫政策，各平台都是「直接被拒」（unsupported policies are refused），不會默默放行——這是好事，代表沙箱寧可報錯也不假裝安全。

Ubuntu 24.04+ 的 bubblewrap 起不來：AppArmor 卡 user namespace

上面「容器內注意」講的是 CI / Docker，但連本機的 Ubuntu 24.04 以上桌機或 VM 都可能中招，不需要容器就會遇到。Ubuntu 24.04 起，核心參數 kernel.apparmor_restrict_unprivileged_userns 預設是 1（限制一般使用者建立 user namespace），而 bubblewrap 的沙箱機制恰好就是靠 user namespace 運作——兩者一撞上，典型錯誤長這樣：

bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted

看到這行、且系統是 Ubuntu 24.04 或更新，八九不離十是這個核心限制擋下來的，不是 Codex 本身壞了。兩條修法擇一：

# 方法一（較保守）：載入官方提供的 bwrap-userns-restrict AppArmor profile
# 沒有單一通用指令，做法依你的套件管理方式而異，以官方 Linux sandbox README 為準

# 方法二（較直接，影響全系統，請自行評估風險）：放行 unprivileged user namespace
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
# 要在重開機後持續生效，記得寫進 /etc/sysctl.d/ 底下的設定檔

15.10 untrusted 專案與企業強制：供應鏈防線

這節一句話重點：clone 來的惡意 repo 不能靠它自帶的 .codex/ 放寬你的沙箱；而企業可以用 requirements.toml 把安全設定鎖死到使用者改不動。這兩層是 Codex 的供應鏈與管理防線。

trust 閘：untrusted 專案跳過 .codex/

專案的 .codex/config.toml / hooks / rules 只在「信任專案」時才載入。官方逐字：「If you mark a project as untrusted, Codex skips project-scoped .codex/ layers, including project-local config, hooks, and rules.」

[projects."/abs/path/to/repo"]
trust_level = "trusted"     # 或 "untrusted"

真實案例：CVE-2025-61260 教你「trust 閘」到底在防什麼

trust 閘不是紙上談兵，2025 年下半年就出過一個對應的真實 CVE，正好示範惡意 repo 會怎麼繞過去。

專案層不能覆寫的 10 個鍵

下列鍵出現在專案 .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

企業強制：requirements.toml vs managed_config.toml

requirements.toml 能約束：allowed_approval_policies、allowed_sandbox_modes、allowed_permission_profiles、allowed_approvals_reviewers、default_permissions、experimental_network.*（網路白/黑名單）、[permissions.filesystem].deny_read、[features]（功能鎖死）、[rules]、[mcp_servers] 等。

衝突時官方逐字：「if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user.」——你寫 approval_policy = "never" 但企業禁止，Codex 自動退回相容值 + 通知，-c / profile 都擋不住。

抽象的鍵名不好想像，實際長相大概是這樣——企業 IT 用 identity 把可用的 MCP server 鎖到「只認這一支執行檔／這一個 URL」，再用 prefix_rules 擋掉危險指令前綴：

allowed_sandbox_modes     = ["read-only", "workspace-write"]
allowed_approval_policies = ["on-request", "untrusted"]

[mcp_servers.internal-docs]
identity = { command = "/usr/local/bin/docs-mcp" }   # 只認這支執行檔

[[rules.prefix_rules]]
pattern = [{ token = "rm" }]
decision = "forbidden"
justification = "用 git clean -fd 取代"

這裡的 identity 是拿來比對「這個 server 是不是我核准的那一個」，靠的是精確的 command（stdio）或 url（HTTP）字串比對——員工自己 codex mcp add 接一個同名但指令不同的 server，一樣會被擋下來，不會因為名字對就放行。

ZDR / disable_response_storage（待確認）

15.11 config.toml × Profiles 進階：overlay 獨立檔（0.134.0 breaking）

這節一句話重點：Profile 不再是寫在 config.toml 裡的 [profiles.X] 區塊了——0.134.0 起那個語法靜默失效，現在 profile 是一個獨立檔案。照舊寫法抄了不會報錯，但也不會生效。

必校正的硬傷：profile 是獨立 overlay 檔

正解：profile 是一個獨立檔案 ~/.codex/<名稱>.config.toml，用頂層 key 寫（不要包在 [profiles.X] 底下），它是 overlay——只需寫和 base config 不同的值，其餘繼承：

# ~/.codex/deep-review.config.toml — 深度審查：貴 + 慢 + 謹慎
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
model_reasoning_summary = "detailed"
approval_policy = "on-request"
sandbox_mode = "read-only"

# ~/.codex/fast-fix.config.toml — 快速修補：便宜 + 快 + 放手
model_reasoning_effort = "low"
model_reasoning_summary = "none"
approval_policy = "never"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false

切換：codex --profile deep-review（短旗標 -p）。

成本旋鈕（profile 裡調）

多層優先序與 --strict-config、-c

優先序（高 → 低）：CLI -c/旗標 > 專案 .codex/config.toml（僅 trusted，最靠近 cwd 者勝）> profile 檔 > user config > system config > 內建預設。monorepo 子目錄可層層覆寫，離 cwd 最近的子目錄 config 勝。

# CI 防呆：config 有未知鍵就 fail（升版砍鍵立刻爆，不靜默吃掉）
codex --strict-config exec "run tests"

# -c 字串值要「雙重引號」（shell 外層 + TOML 字串內層）
codex -c model='"gpt-5.5"'

# profile + -c 疊加（CLI 最高優先，蓋過 profile）
codex -p fast-fix -c model_reasoning_effort='"high"'

# 一次切本地 OSS provider（等同 -c model_provider="oss"）
codex --oss exec "..."

15.12 冷門旗標與 Feature Flags

這節一句話重點：Codex 有一層「隱藏功能」靠 feature flag 控制（/undo 為什麼官方 slash 頁查不到？因為它預設關），還有一票高手才用的冷門旗標與實驗子指令。

冷門全域旗標（官方逐字）

Feature Flags 三種切法

flag 有五階生命週期（UnderDevelopment → Experimental → Stable → Deprecated → Removed）；Experimental 階的 flag 會自動出現在 TUI 的 /experimental 選單，想玩實驗功能打 /experimental 即可。

隱藏 / 實驗性子指令

15.13 RUST_LOG 除錯與 codex doctor

這節一句話重點：環境/登入/網路出怪，除錯有固定順序——先跑已遮敏感的 codex doctor，再翻 log，最後才開 RUST_LOG；順序顛倒會洩密又浪費時間。

除錯三段式（順序別顛倒）

# 1. 已 redact（遮敏感），最安全先跑
codex doctor --summary --no-color

# 2. 取細節（已自動遮敏感）
codex doctor --json

# 3. 仍不明朗才開 debug
RUST_LOG=info,codex_core=debug codex

codex doctor 產出 support-ready 診斷，橫跨六大區段：runtime / auth / terminal / network / config / local state。登入壞看 Authentication 段；config 沒生效搭 /debug-config（印 config layer + 企業 requirements）；跑 /feedback 時 Codex 會盡力附上 codex-doctor-report.json。

RUST_LOG 分級與 per-module target

RUST_LOG 官方逐字：「Controls Rust log filtering and verbosity.」接受 error/warn/info/debug/trace 與 targeted filter：

RUST_LOG=debug codex                                          # 全域 debug
RUST_LOG=info,codex_core=debug codex                          # 只把 codex_core 拉高
RUST_LOG=codex_exec=trace,codex_core=debug codex exec "..."   # exec 全程
RUST_LOG_FORMAT=json RUST_LOG=debug codex                     # JSON log 給 jq（RUST_LOG_FORMAT 官方未列，社群實證，medium）

log 檔位置：TUI log 在 ~/.codex/log/codex-tui.log（路徑社群佐證）；session transcript 在 ~/.codex/sessions/YYYY/MM/DD/rollout-<id>.jsonl。codex exec（非互動）預設 RUST_LOG=error、訊息到 stderr 不寫檔，要 debug 自動化就在 exec 前明示 RUST_LOG=。

15.14 用量、成本與效能調校

這節一句話重點：把 token 當錢看——MCP 工具在你打字前就吃 context，reasoning effort 一開貴好幾倍，context 別等爆了才壓；高手用 profile 路由「一任務一人格」自動省。

內建用量檢視

session JSONL（$CODEX_HOME/sessions/...rollout-*.jsonl）每回合記累積 token（input / cached_input / output / reasoning），codex exec --json 可即時抽：

codex exec --json "..." | jq -c 'select(.type=="token_count") | .info'

token overhead 真相（為何 context 一開就被吃）

效能/成本 config 鍵

model_reasoning_effort = "medium"        # xhigh 比 medium 多 3~5x token（社群量測）
plan_mode_reasoning_effort = "high"      # 只在規劃階段給高
model_reasoning_summary = "none"         # 不需要摘要就關，省輸出
model_verbosity = "low"                  # 回應更精簡，省 output token
model_auto_compact_token_limit = 64000   # 比預設更早觸發自動壓縮
tool_output_token_limit = 12000          # 蓋住單次檔案讀取的 token

手動壓縮時機

codex exec 進階：resume 快取折扣與結構化輸出

codex exec 的基礎用法在第 10 章，這裡只補跟「省錢」直接相關的幾個進階旗標。

codex exec "審查這次改動有無 race condition"
codex exec resume --last "把剛才發現的問題修掉"          # 吃快取折扣，別每次重開
codex exec --json "跑測試並回報結果" | jq -c 'select(.type=="item.completed")'
codex exec --output-schema ./schema.json "產出風險摘要" -o ./result.json

profile 路由配方（省錢甜蜜點）

# ~/.codex/quick.config.toml — 日常小修
model_reasoning_effort = "low"
model_verbosity = "low"

# ~/.codex/deep.config.toml — 架構決策 / 難 bug
model_reasoning_effort = "high"

codex --profile quick     # 日常
codex --profile deep      # 動腦

本章官方文件參考

• MCP（進階鍵 / 過濾順序 / plugin 覆寫 / OAuth 綁定）：developers.openai.com/codex/mcp
• CLI reference（codex mcp 家族 / codex mcp-server / 冷門旗標 / 子指令）：developers.openai.com/codex/cli/reference
• MCP interface（自建 server 的 v2/v1 方法、approval 欄位）：codex_mcp_interface.md
• Permissions（named profile / filesystem / network 模型）：developers.openai.com/codex/permissions
• Sandboxing（三 preset / Seatbelt / bubblewrap）：developers.openai.com/codex/concepts/sandboxing
• Configuration Reference（全鍵 + 預設）：developers.openai.com/codex/config-reference
• Advanced Configuration（profile overlay / 0.134.0 breaking / OTEL / 不可覆寫鍵）：developers.openai.com/codex/config-advanced
• Config basics（優先序 / trust）：developers.openai.com/codex/config-basic
• Enterprise Managed configuration（requirements.toml）：developers.openai.com/codex/enterprise/managed-configuration
• Features（feature flags / 鍵盤快捷）：developers.openai.com/codex/cli/features
• Environment variables（RUST_LOG）：developers.openai.com/codex/environment-variables
• changelog（0.140.0：MCP 可靠性 / /usage）：developers.openai.com/codex/changelog