Codex 桌面應(yīng)用實(shí)際配置，逐項(xiàng)說(shuō)明每個(gè)配置項(xiàng)的作用、觸發(fā)場(chǎng)景和驗(yàn)證方法。

一、引言

Codex 桌面應(yīng)用的配置文件 ~/.codex/config.toml 控制著 Agent 的核心行為。本文檔記錄當(dāng)前環(huán)境的完整配置狀態(tài)，幫助快速定位問(wèn)題、理解能力邊界。

適用場(chǎng)景：

• 排查某個(gè)功能"為什么沒(méi)生效"
• 新增配置項(xiàng)前確認(rèn)影響范圍
• 向同事解釋 Codex 的工作機(jī)制

預(yù)期收獲： 讀完本文檔，你能：

1. 快速定位任意配置項(xiàng)的作用和驗(yàn)證方法
2. 理解 Feature Flags 如何影響 Agent 的工具集
3. 知道哪些配置是"被動(dòng)生效"、哪些需要"主動(dòng)觸發(fā)"

二、配置文件概覽

2.1 文件位置與格式

~/.codex/config.toml

• 格式： TOML（Tom’s Obvious, Minimal Language）
• 優(yōu)先級(jí)： 項(xiàng)目級(jí) > 用戶級(jí) > 系統(tǒng)級(jí)（詳見(jiàn)附錄 A）
• 生效方式： 大部分配置需重啟 Codex 應(yīng)用后生效

2.2 當(dāng)前配置結(jié)構(gòu)

# 全局配置
model_provider = "custom"
model = "qwen3.7-max"
web_search = "cached"
personality = "friendly"
# 模型提供商
[model_providers.custom]
...
# MCP 服務(wù)器（17 個(gè)）
[mcp_servers.node_repl]
[mcp_servers.brave-search]
...
# 插件（14 個(gè)）
[plugins."browser@openai-bundled"]
...
# 功能開(kāi)關(guān)（11 個(gè)）
[features]
multi_agent = true
...

三、全局配置項(xiàng)詳解

3.1 模型與推理配置

驗(yàn)證方法：

# 檢查當(dāng)前生效的模型
codex --version
# 或在會(huì)話中輸入 /model 查看

[!NOTE]
model_reasoning_effort = "high" 會(huì)消耗更多 token，復(fù)雜任務(wù)建議保持 high。如果代理不支持 reasoning 參數(shù)，會(huì)被忽略，不會(huì)報(bào)錯(cuò)。

3.2 網(wǎng)絡(luò)搜索與個(gè)性化

web_search 三種模式對(duì)比：

personality 三種風(fēng)格：

四、Feature Flags 詳解

Feature Flags 是 Codex 的能力開(kāi)關(guān)，控制哪些工具和機(jī)制可用。

4.1 當(dāng)前狀態(tài)總覽

[features]
computer_use = true      # 計(jì)算機(jī)控制
js_repl = false          # JS REPL（關(guān)閉）
goals = true             # 目標(biāo)管理
multi_agent = true       # 子 Agent 協(xié)作
hooks = true             # 生命周期鉤子
shell_snapshot = true    # Shell 快照加速
fast_mode = true         # 快速模式
undo = true              # Git Ghost 撤銷
personality = true       # 個(gè)性化控件
apps = true              # ChatGPT Apps/Connectors
memories = true          # 跨會(huì)話記憶

4.2 multi_agent（子 Agent 協(xié)作）

作用： 啟用 spawn_agent、wait_agent、close_agent 三個(gè)工具，允許 Codex 派生子 Agent 并行執(zhí)行任務(wù)。

何時(shí)觸發(fā)：

• 使用 subagent-driven-development skill 時(shí)
• 使用 dispatching-parallel-agents skill 時(shí)
• 遇到復(fù)雜任務(wù)需要拆分時(shí)

典型場(chǎng)景：

用戶：實(shí)現(xiàn)一個(gè)用戶登錄功能，包括前端表單、后端接口、數(shù)據(jù)庫(kù)設(shè)計(jì)。

Codex 主 Agent：
  → spawn_agent("前端表單", task_description)
  → spawn_agent("后端接口", task_description)
  → spawn_agent("數(shù)據(jù)庫(kù)設(shè)計(jì)", task_description)
  → wait_agent(所有子 Agent)
  → 匯總結(jié)果

驗(yàn)證方法：

1. 重啟 Codex 后，在會(huì)話中請(qǐng)求一個(gè)多文件任務(wù)
2. 觀察是否有多個(gè)子 Agent 并行工作
3. 或在終端輸入 /tools 查看工具列表，應(yīng)包含 spawn_agent

4.3 hooks（生命周期鉤子）

作用： 在工具調(diào)用前后、會(huì)話啟動(dòng)時(shí)執(zhí)行自定義腳本。

當(dāng)前已配置的鉤子：

驗(yàn)證方法：

# 查看已信任的鉤子
grep -A 5 "\[hooks.state\]" ~/.codex/config.toml

[!TIP]
鉤子腳本需要被信任后才會(huì)執(zhí)行。使用 /hooks 命令可以查看、審查、信任鉤子。

4.4 shell_snapshot（Shell 快照加速）

作用： 首次執(zhí)行某個(gè)命令時(shí)快照 shell 環(huán)境，后續(xù)相同命令直接復(fù)用，啟動(dòng)更快。

何時(shí)觸發(fā)： 自動(dòng)觸發(fā)，無(wú)感。

性能提升示例：

第一次執(zhí)行 ls -la：
  - 初始化 shell 環(huán)境：~200ms
  - 執(zhí)行命令：~50ms
  - 總計(jì)：~250ms

第二次執(zhí)行 ls -la：
  - 復(fù)用快照：~10ms
  - 執(zhí)行命令：~50ms
  - 總計(jì)：~60ms（提速 4x）

驗(yàn)證方法：

• 無(wú)直接驗(yàn)證方式，但命令響應(yīng)速度會(huì)明顯提升
• 可通過(guò)對(duì)比重啟前后的命令執(zhí)行時(shí)間感知

4.5 fast_mode（快速模式）

作用： 使用 service_tier = "fast" 的模型層，響應(yīng)更快、成本更低。

何時(shí)觸發(fā)： 自動(dòng)觸發(fā)，適用于簡(jiǎn)單任務(wù)。

[!NOTE]
如果當(dāng)前代理不支持該參數(shù)，會(huì)被忽略。復(fù)雜推理任務(wù)仍會(huì)使用 model_reasoning_effort 配置的力度。

4.6 undo（Git Ghost 撤銷）

作用： 每次編輯文件前做一次 git ghost 快照，支持回滾到任意歷史狀態(tài)。

何時(shí)觸發(fā)：

• 在會(huì)話中說(shuō)"撤銷剛才的改動(dòng)"
• 在會(huì)話中說(shuō)"回滾到上一個(gè)版本"
• Codex 檢測(cè)到改壞了，主動(dòng)建議回滾

工作原理：

驗(yàn)證方法：

1. 讓 Codex 修改一個(gè)文件
2. 說(shuō)"撤銷剛才的改動(dòng)"
3. 觀察文件是否恢復(fù)到修改前

[!WARNING]
Ghost 快照不會(huì)出現(xiàn)在 git log 中。重啟 Codex 后，之前的快照會(huì)丟失。

4.7 personality（個(gè)性化控件）

作用： 啟用個(gè)性化交流風(fēng)格，根據(jù) personality = "friendly" 調(diào)整輸出。

何時(shí)觸發(fā)： 所有會(huì)話自動(dòng)應(yīng)用。

驗(yàn)證方法： 對(duì)比 personality = "none" 時(shí)的輸出風(fēng)格差異。

4.8 apps（ChatGPT Apps/Connectors）

作用： 啟用 ChatGPT Apps 和 Connectors 支持，使 Figma、Canva 等插件的工具可用。

何時(shí)觸發(fā)：

• 使用 Figma 插件時(shí)
• 使用 Canva 插件時(shí)
• 使用任何需要 App 集成能力的插件時(shí)

當(dāng)前依賴 apps 的插件：

驗(yàn)證方法：

1. 在會(huì)話中請(qǐng)求使用 Figma
2. 觀察是否有 Figma 相關(guān)工具可用
3. 或輸入 /tools 查看工具列表

4.9 memories（跨會(huì)話記憶）

作用： 從歷史會(huì)話中提取有用的上下文（技術(shù)棧、項(xiàng)目規(guī)范、踩過(guò)的坑），在新會(huì)話中自動(dòng)注入。

何時(shí)觸發(fā)：

• 后臺(tái)異步工作，不需要手動(dòng)操作
• 新會(huì)話啟動(dòng)時(shí)自動(dòng)加載相關(guān)記憶

記憶內(nèi)容示例：

技術(shù)棧偏好：
- 用戶喜歡用 Spring Boot + MyBatis
- 數(shù)據(jù)庫(kù)偏好 MySQL 8.0
- 前端使用 Vue 3 + Element Plus

項(xiàng)目規(guī)范：
- commit message 使用 Conventional Commits
- 代碼風(fēng)格遵循 Google Java Style
- 測(cè)試覆蓋率要求 ≥ 80%

踩過(guò)的坑：
- Redis 連接池默認(rèn)大小不夠，建議 10+
- MyBatis 的 resultMap 映射容易漏字段

驗(yàn)證方法：

1. 新開(kāi)一個(gè)會(huì)話
2. 問(wèn) Codex “你還記得我之前項(xiàng)目的技術(shù)棧嗎？”
3. 觀察是否能回憶起歷史信息

[!IMPORTANT]
記憶是異步生成的，不是每個(gè)會(huì)話結(jié)束都會(huì)更新。敏感信息會(huì)被自動(dòng)脫敏?？梢酝ㄟ^(guò) /memories 控制當(dāng)前會(huì)話是否使用/生成記憶。

4.10 computer_use（計(jì)算機(jī)控制）

作用： 允許 Codex 操作 macOS/Windows 桌面應(yīng)用，包括看屏幕、點(diǎn)擊、輸入。

何時(shí)觸發(fā)：

• 測(cè)試桌面應(yīng)用時(shí)
• 操作沒(méi)有 API/插件的數(shù)據(jù)源時(shí)
• 復(fù)現(xiàn) GUI 相關(guān)的 bug 時(shí)

驗(yàn)證方法：

1. 在會(huì)話中請(qǐng)求"打開(kāi)計(jì)算器應(yīng)用"
2. 觀察 Codex 是否能控制桌面

[!CAUTION]
需要授予屏幕錄制和輔助功能權(quán)限。建議保持任務(wù)范圍窄，避免誤操作。

4.11 goals（目標(biāo)管理）

作用： 啟用目標(biāo)跟蹤功能，可以設(shè)定目標(biāo)并追蹤進(jìn)度。

何時(shí)觸發(fā)：

• 使用 /goal 命令時(shí)
• Codex 判斷需要跟蹤長(zhǎng)期任務(wù)時(shí)

4.12 js_repl（JS REPL）

當(dāng)前值： false（關(guān)閉）

作用： 啟用 JavaScript REPL 工具，可以交互式執(zhí)行 JS 代碼。

為何關(guān)閉： 當(dāng)前工作流主要使用 Python/Java，JS REPL 不是必需。如需啟用，改為 true 并重啟。

五、MCP 服務(wù)器配置

5.1 當(dāng)前配置的 MCP 服務(wù)器

5.2 安全風(fēng)險(xiǎn)提醒

5.2.1 brave-search 缺 API Key

問(wèn)題：

[mcp_servers.brave-search]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]
# 缺少 env 配置

影響： Brave 搜索工具無(wú)法正常工作。

解決方案（二選一）：

方案 A：添加 API Key

[mcp_servers.brave-search]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-brave-search"]
[mcp_servers.brave-search.env]
BRAVE_API_KEY = "your-api-key-here"

方案 B：刪除該 MCP 服務(wù)器（推薦，因?yàn)橐延?web_search = "cached"）

# 刪除 brave-search 相關(guān)配置
sed -i '/\[mcp_servers.brave-search\]/,/^$/d' ~/.codex/config.toml

5.2.2 飛書(shū) app-secret 明文

問(wèn)題：

[mcp_servers.feishu]
args = [
    "-y",
    "@larksuiteoapi/lark-mcp",
    "mcp",
    "--app-id",
    "cli_a9256761dd389cc6",
    "--app-secret",
    "zBuX1x7MhvsGKgiKg2hTVh0E4w7uFsWo",  # ← 明文
]

風(fēng)險(xiǎn)： 雖然 config.toml 不進(jìn) git，但如果被其他人看到或備份到云端，會(huì)泄露。

解決方案： 使用環(huán)境變量

# 1. 設(shè)置環(huán)境變量
export FEISHU_APP_SECRET="zBuX1x7MhvsGKgiKg2hTVh0E4w7uFsWo"
# 2. 修改配置
[mcp_servers.feishu]
args = [
    "-y",
    "@larksuiteoapi/lark-mcp",
    "mcp",
    "--app-id",
    "cli_a9256761dd389cc6",
    "--app-secret",
    "${FEISHU_APP_SECRET}",  # ← 引用環(huán)境變量
]

[!NOTE]
環(huán)境變量注入需要在 [shell_environment_policy] 中配置，當(dāng)前未配置此項(xiàng)，需要額外處理。

5.2.3 生產(chǎn)環(huán)境數(shù)據(jù)庫(kù)密碼

問(wèn)題： 多個(gè) MySQL MCP 服務(wù)器配置了生產(chǎn)環(huán)境密碼明文。

[mcp_servers.mall_prod.env]
MYSQL_PASS = "Mall123!@#"  # ← 生產(chǎn)密碼

[mcp_servers.mysql-kkd-prod.env]
MYSQL_PASS = "Abc123!@#"   # ← 生產(chǎn)密碼

風(fēng)險(xiǎn)： 同上，泄露風(fēng)險(xiǎn)。

解決方案： 同飛書(shū)，使用環(huán)境變量或密鑰管理工具。

六、配置速查表

6.1 快速定位問(wèn)題

6.2 常用命令

# 查看當(dāng)前配置
cat ~/.codex/config.toml

# 備份配置
cp ~/.codex/config.toml ~/.codex/config.toml.bak

# 查看已啟用的功能
grep -A 20 "\[features\]" ~/.codex/config.toml

# 查看已信任的鉤子
grep -A 10 "\[hooks.state\]" ~/.codex/config.toml

# 查看 MCP 服務(wù)器列表
grep "\[mcp_servers" ~/.codex/config.toml

# 查看插件列表
grep "\[plugins" ~/.codex/config.toml

七、驗(yàn)證清單

重啟 Codex 后，逐項(xiàng)驗(yàn)證：

7.1 Feature Flags 驗(yàn)證

7.2 全局配置驗(yàn)證

7.3 MCP 服務(wù)器驗(yàn)證

八、總結(jié)與建議

8.1 配置狀態(tài)總結(jié)

? 已正確配置：

• 11 個(gè) Feature Flags 全部啟用（除 js_repl 合理關(guān)閉）
• 全局配置項(xiàng)完整（model、web_search、personality）
• 17 個(gè) MCP 服務(wù)器配置（16 個(gè)可用）

?? 需要處理：

• brave-search 缺 API Key（建議刪除或補(bǔ)全）
• 飛書(shū) app-secret 明文（建議改為環(huán)境變量）
• 生產(chǎn)數(shù)據(jù)庫(kù)密碼明文（建議改為環(huán)境變量）

8.2 下一步建議

優(yōu)先級(jí) 1（安全）：

• 處理飛書(shū) app-secret 明文問(wèn)題
• 處理生產(chǎn)數(shù)據(jù)庫(kù)密碼明文問(wèn)題

優(yōu)先級(jí) 2（清理）：

• 刪除 brave-search MCP 服務(wù)器（或補(bǔ)全 API Key）

優(yōu)先級(jí) 3（優(yōu)化）：

• 定期驗(yàn)證 memories 功能是否正常工作
• 測(cè)試 undo 功能是否符合預(yù)期

九、附錄

附錄 A：配置文件優(yōu)先級(jí)

CLI 標(biāo)志和 --config 覆蓋（最高）
  ↓
項(xiàng)目配置文件：.codex/config.toml
  ↓
Profile 文件：~/.codex/profile-name.config.toml
  ↓
用戶配置：~/.codex/config.toml
  ↓
系統(tǒng)配置：/etc/codex/config.toml
  ↓
內(nèi)置默認(rèn)值（最低）

附錄 B：相關(guān)文件位置

附錄 C：術(shù)語(yǔ)表

以上就是Codex config.toml配置實(shí)戰(zhàn)指南的詳細(xì)內(nèi)容，更多關(guān)于Codex config.toml配置指南的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論