Codex CLI 實驗性功能：Goal、Memories...
整理版優先睇
Codex CLI 實驗性功能解說：Goals、Memories 同其他 Feature Flags 嘅用法同風險管理
呢篇文章出自一位有自行搭建 API 中轉站經驗嘅開發者，佢整理咗 OpenAI Codex CLI 入面嘅實驗性功能，主要係 Feature Flags 同 Experimental Commands。作者想解決嘅問題係：呢啲新功能仲未穩定，點樣判斷邊個值得用、邊個要等？整體結論係要根據功能成熟度同自身痛點去選擇，並且要識得設定邊界同回滾方法。
文章首先解釋咗 OpenAI 對功能成熟度嘅定義（stable / experimental / under development / deprecated / removed），強調 experimental 功能嘅行為可能隨時變，用家要自己承擔風險。然後介紹咗 Feature Flags 同 Experimental Commands 嘅分別：Feature Flags 係細粒度嘅行為開關（例如 goals、memories），可以逐個開關；而 Experimental Commands 係成個子命令（例如 codex cloud）仲未穩定，唔受 Feature Flags 控制。
之後文章深入講解咗六個 Feature Flags：goals（俾 Codex 一個持續目標）、memories（跨會話記憶）、prevent_idle_sleep（防止長任務中斷）、network_proxy（代理支援）、terminal_resize_reflow（終端重排）、exter…
- 實驗性功能分 Feature Flags 同 Experimental Commands，前者係細粒度行為開關，後者係成個子命令；兩者成熟度分開標註。
- Goals 功能容許你用 /goal 設定持續目標，包含最終目標、邊界約束、驗證方式、檢查點同停止條件，適合模組遷移、測試修復、迭代優化等場景。
- Memories 將個人偏好、項目約定儲存在本地，跨會話重用，但團隊級規則必須寫入 AGENTS.md 等文件，唔可以只靠 memory。
- 啟用實驗性功能要跟從判斷框架：有真實痛點、有成功標準、識得回滾、唔影響生產環境。唔應該因為「睇起嚟新」就開。
- 推薦啟用順序：第一批係 goals、memories、terminal_resize_reflow（低風險）；第二批係 prevent_idle_sleep 同 network_proxy（有具體場景先用）；external_migration 暫唔建議主動開。
OpenAI Developers – Codex Feature Maturity
官方文件：功能成熟度定義
OpenAI Developers – Codex CLI Features
官方文件：Codex CLI 功能列表
OpenAI Developers – Codex CLI Command Line Reference
官方文件：CLI 命令參考
OpenAI Developers – Follow a Goal
官方文件：Goals 使用指南
實驗性功能嘅基本概念
Codex CLI 嘅實驗性功能係 OpenAI 喺正式發佈前交俾真實用戶驗證嘅新能力。佢哋唔係隱藏彩蛋，而係功能仲喺打磨階段，行為、接口、配置都可能隨版本變，甚至會被成個移除。
成熟度標籤有 stable、experimental、under development、deprecated 同 removed
對於 experimental 狀態，官方嘅態度係：你可以用，但要自己承擔行為變化嘅風險。呢個意味住佢可能下個版本改咗名、配置項默認值變咗、行為同文檔對唔上，甚至可能被砍掉。知呢啲之後你先判斷到咩場景值得用。
Feature Flags：六個能力開關
用 codex features list 可以見到六個 Feature Flags，每個都有自身嘅成熟度同默認狀態。以下係最重要嘅兩個：
goals：俾 Codex 一個持續目標，解決「一問一答」模式嘅限制
Goals 功能容許你用 /goal 設定結構化目標契約，Codex 會持續推進直到停止條件。一個好嘅 Goal 需要包含五個要素：最終目標、邊界約束、驗證方式、檢查點同停止條件。
/goal Migrate the billing module from JavaScript to TypeScript.
Constraints: do not change the public API signatures or return types.
After completing each file, run: pnpm test billing && pnpm typecheck.
Stop when all files are migrated, all tests pass, and MIGRATION.md is updated
with the list of changed files.如果冇停止條件就唔好設 goal，因為 Codex 會一直做到你叫停為止。複雜任務最好拆成多個小 goal。
memories：跨會話嘅記憶層，令偏好設定同項目約定可以持久留低
Memories 儲存喺本地 ~/.codex/memories/，係結構化條目。你可以手動加記憶（用 Remember:），或者叫 Codex 自動總結值得記嘅內容。注意：團隊級別嘅強制約束一定要寫入 AGENTS.md 或項目文檔，唔可以只靠 memory。
- 1 prevent_idle_sleep：防止長任務期間電腦休眠，配合 goals 使用，適合大型重構或無人值守任務。默認 false，建議用完關閉。
- 2 network_proxy：代理網絡支援，解決企業內網或特殊地區嘅網絡限制。默認 false，有需要先開。
- 3 terminal_resize_reflow：終端窗口調整後重新排版，純顯示增強，默認 true。
- 4 external_migration：遷移兼容路徑，說明不足，目前唔建議主動啟用。
呢啲 Feature Flags 可以臨時用 --enable/--disable 控制，或者持久用 codex features enable/disable 寫入 ~/.codex/config.toml。亦可以用 --profile 隔離實驗配置，避免影響日常使用。
Experimental Commands：平台集成同進階操作
除咗 Feature Flags，codex --help 仲有幾個標註為 [EXPERIMENTAL] 嘅子命令。呢啲命令偏向平台集成、遠程執行同底層調試。
codex cloud：從終端操作雲端任務，提交、查看、拉取結果
適合已經用緊 Codex Cloud 嘅團隊。核心子命令包括 codex cloud exec、list、apply。注意：應用 diff 前一定要 review。
codex app-server：平台集成接口，供 IDE 或自研客戶端用 JSON-RPC over stdio/WebSocket 連接
適合開發插件或嵌入 Codex 能力。暴露 TCP 端口時必須配置認證。另有 codex remote-control 同 codex exec-server，分別用於 SSH 場景同獨立執行節點，兩者都需要嚴格嘅安全考慮。
- codex sandbox：喺受限沙箱環境執行命令，驗證策略或調試平台差異。唔係絕對安全，唔好用嚟執行來歷不明嘅腳本。
- codex debug：診斷工具，用嚟查模型列表、測試 app-server 連接、睇配置等。輸出可能包含敏感資訊，分享前要脱敏。
管理方法同常見問題
管理 Feature Flags 有幾種方式：臨時啟用（--enable/--disable，隻影響當前 session）、持久啟用（codex features enable/disable，寫入 config.toml）、用 profile 隔離實驗配置（codex --profile experimental）。
推薦啟用順序：第一批 goals、memories、terminal_resize_reflow；第二批 prevent_idle_sleep、network_proxy；external_migration 暫不建議
常見問題方面：如果 goal 執行跑偏，立即 pause 然後補充邊界約束；如果 memories 帶錯規則，用 prompt 覆蓋或清理記憶；如果 network_proxy 唔通，逐項排查代理配置；如果 prevent_idle_sleep 失效，可用 caffeinate（macOS）或 powercfg（Windows）作為備選。
# 查看版本
codex --version
# 查看所有 feature flags
codex features list
# 查看所有命令（包括實驗性）
codex --help
# 各實驗性命令幫助
codex cloud --help
codex app-server --help
咩係實驗性功能
Codex CLI 裏面嘅實驗性功能，係 OpenAI 喺正式發佈之前交俾真實用戶驗證嘅一組新能力。佢哋唔係"隱藏彩蛋"，亦唔係"高級會員專屬"——而係功能本身仲喺度打磨階段，行為、接口、配置項都可能隨住版本變化，甚至俾整體移除。
OpenAI 對功能成熟度有明確嘅定義：
stable | |
experimental | |
under development | |
deprecated | |
removed |
對於 experimental 狀態嘅功能，官方嘅態度係：你可以用，但係要自己承擔行為變化嘅風險。
呢個意味住：
• 佢可能喺下一個版本裏面偷偷改咗名 • 佢某個配置項聽日就換咗默認值 • 佢嘅行為同文檔描述對唔上，呢個唔一定係 bug，可能係文檔未跟上 • 佢可能俾正式畢業（進入 stable），亦可能俾砍咗
知道呢啲之後，你先可以判斷咩場景值得用、咩場景應該等。
兩種"實驗性"，唔好搞混
喺 Codex CLI 裏面，"實驗性"有兩種形式，放喺唔同地方，管嘅係唔同粒度嘅嘢。
第一種：Feature Flags（功能開關）
用呢個命令可以見到：
codex features list輸出大概係咁樣：
Feature Maturity Enabled
─────────────────────────────────────────────
external_migration experimental false
goals experimental true
memories experimental true
network_proxy experimental false
prevent_idle_sleep experimental false
terminal_resize_reflow experimental true呢啲係顆粒度好細嘅能力開關，你可以單獨開啓或者關閉，狀態會持久寫入 ~/.codex/config.toml。
第二種：實驗性命令（Experimental Commands）
運行 codex --help，可以見到一啲子命令旁邊標註咗 [EXPERIMENTAL] 或 [experimental]：
codex cloud [EXPERIMENTAL]
codex app-server [experimental]
codex exec-server [EXPERIMENTAL]呢啲命令本身處於實驗階段，唔受 features list 嘅開關控制，佢哋嘅成熟度係命令層面嘅標註。
兩者嘅分別：Feature Flag 係"某個具體行為係咪開啓"，實驗性命令係"呢個成個子命令未穩定"。管嘅係唔同層次嘅嘢，需要分開睇。
Feature Flags：六個能力開關
goals：俾 Codex 一個持續目標
當前狀態：experimental，默認 true（已啓用）
佢解決咩問題
普通 Codex 會話係"一問一答"模式：你發一條消息，佢回一條，然後等你繼續。呢個喺處理短任務時冇問題，但係遇到需要跨多個步驟持續推進嘅任務——例如將一個模塊由 JavaScript 遷移到 TypeScript、修復一批測試直到全部通過、按照需求文檔逐步實現一個功能——你就需要一直坐喺旁邊睇實，不斷同佢講"繼續""記得驗證""唔好改呢個文件"。
goals 功能令你可以用 /goal 命令俾 Codex 設定一個結構化嘅目標契約。Codex 會圍繞呢個契約持續推進，直到滿足停止條件，而唔係每輪都等你下一個指令。
核心命令
/goal <目標描述> 設定目標，開始持續執行
/goal pause 暫停當前目標
/goal resume 恢復已暫停的目標
/goal clear 清除當前目標
/goal status 查看當前目標狀態點樣寫一個好嘅 Goal
/goal 可唔可以發揮價值，完全取決於你寫嘅目標質量。一個好嘅 goal 需要包含五個要素：
| 最終目標 | ||
| 邊界約束 | ||
| 驗證方式 | pnpm test billing && pnpm typecheck | |
| 檢查點 | ||
| 停止條件 |
使用示例
示例一：TypeScript 遷移任務
/goal Migrate the billing module from JavaScript to TypeScript.
Constraints: do not change the public API signatures or return types.
After completing each file, run: pnpm test billing && pnpm typecheck.
Stop when all files are migrated, all tests pass, and MIGRATION.md is updated
with the list of changed files.示例二：測試修復任務
/goal Fix all failing tests in the payments package.
Do not modify test files — only fix implementation code.
After each fix attempt, run: pnpm test packages/payments.
Stop when all tests pass with zero failures.
If a test seems fundamentally broken by design, add a note in FIXME.md
and skip it rather than deleting it.示例三：持續優化 prompts
/goal Improve the summarization prompt in src/prompts/summarize.ts.
Evaluate quality by running: node scripts/eval-summary.js.
Target: average score >= 0.85 across all test cases.
Stop when the target score is reached or after 10 iterations, whichever comes first.
Log each iteration's score to eval-results.log.暫停同恢復
# 臨時暫停，去處理別的事情
/goal pause
# 回來之後恢復
/goal resume適合嘅使用場景
• 模塊遷移：框架升級、語言遷移、API 替換 • 批量修復：修測試、修 lint、修類型錯誤 • 迭代優化：有可量化指標嘅持續改進任務 • 原型開發：由空文件到可以運行，需要多步驟迭代 • 部署排障：失敗之後按策略反覆定位、修復、驗證
注意事項
• 冇停止條件就唔好設 goal。Codex 唔知咩叫"差唔多"，佢會一直執行，直到你同佢講停，或者你嘅 token 用完。 • 複雜任務建議拆成多個小 goal，唔好一次塞入太多要求。 • goal 執行期間建議保持終端可見，間唔中確認佢做緊嘅嘢方向正確。 • 要明確寫出邊啲文件或者範圍唔可以掂，Codex 唔會自己估邊界。
memories：跨會話嘅記憶層
當前狀態：experimental，默認 true（已啓用）
佢解決咩問題
Codex 嘅每個會話默認係無狀態嘅：上一個會話裏面你同佢講過"呢個項目用 pnpm 唔用 npm"，下一個會話佢又唔知喇，你要再講一次。
長期維護幾個固定倉庫嘅開發者，通常有一大堆呢啲"重複交代"：
• 呢個項目嘅測試命令係 pnpm test --filter=...• commit message 必須用中文，格式係 type: 描述• 前端代碼唔可以改 API contract，只可以改視圖層 • 某個第三方庫有伏，唔好用佢嘅 .toFixed()方法• 代碼風格要同 ESLint 配置保持一致，唔好"修"佢
memories 令呢啲穩定嘅偏好、項目約定同踩坑經驗可以喺會話之間持續存在，唔使每次都重新交代。
記憶嘅儲存位置
memories 儲存喺本地，通常喺：
~/.codex/memories/每條記憶係一個結構化條目，包含內容、來源、時間戳同關聯嘅項目路徑（如果有的話）。
使用示例
手動添加記憶
Remember: this repo uses pnpm, not npm or yarn. Always use pnpm for package management.
Remember: commit messages in this project must be in Chinese,
format: "type(scope): description", e.g. "fix(auth): 修復登錄態丟失問題".
Remember: do not modify any files under src/api/ — those are auto-generated
from the OpenAPI schema and will be overwritten on next build.叫 Codex 自動總結值得記住嘅內容
We just fixed the race condition in the WebSocket reconnection logic.
The root cause was that onClose and onMessage could fire in the wrong order
during reconnect. Please remember this for future debugging sessions.睇嚇已經有嘅記憶（通過 /status 或者配置文件睇）
cat ~/.codex/memories/index.json記憶嘅分層使用策略
┌─────────────────────────────────────────────────────┐
│ 強制團隊規則 → 寫進 AGENTS.md / README / docs │
│ （版本控制，人人可見，不依賴本地狀態） │
├─────────────────────────────────────────────────────┤
│ 個人長期偏好 → 放進 memories │
│ （跨 session 複用，本地存儲） │
├─────────────────────────────────────────────────────┤
│ 當前任務要求 → 寫在當前 prompt 裏 │
│ （臨時，任務結束就失效） │
└─────────────────────────────────────────────────────┘注意事項
• memories 唔係規則手冊，係"偏好召回層"。佢可能過期、唔完整，亦可能俾錯誤咁套到唔適合嘅項目上。 • 團隊級別嘅強制約束必須寫入 AGENTS.md或者項目文檔，唔可以淨係靠 memory。• 如果你喺多部機器或者多個項目上交替工作，要注意 memory 係咪仲適用於當前上下文。 • 定期清理過時嘅 memory，避免陳舊規則幹擾新任務。
prevent_idle_sleep：防止長任務中斷
當前狀態：experimental，默認 false（未啓用）
佢解決咩問題
呢個問題好具體：你用 /goal 開咗個大型遷移任務，或者叫 Codex 持續跑測試修復，然後去攞咗杯咖啡返嚟，發現電腦瞓咗，Codex session 斷咗，任務要從頭嚟過。
prevent_idle_sleep 防止系統喺 Codex 任務執行期間進入休眠狀態。
使用方法
# 臨時啓用（當前 session）
codex --enable prevent_idle_sleep
# 持久啓用
codex features enable prevent_idle_sleep
# 任務結束後關閉
codex features disable prevent_idle_sleep配合 goals 使用
呢兩個功能本來就係一對：
# 先確保不會休眠
codex features enable prevent_idle_sleep
# 然後開啓長時間目標任務
# 在 Codex session 裏：
/goal Migrate all 47 test files from Jest to Vitest.
After each file migration, run: pnpm test --reporter=verbose.
Stop when all tests pass and the migration summary is written to MIGRATION.md.適合嘅場景
• 大型重構或者遷移（幾十個文件） • 持續跑測試直到全部通過 • 無人值守嘅本地任務（晚上掛住嚟跑） • 任何預計執行時間超過屏保/休眠等待時間嘅任務
注意事項
• 筆記本使用時一定要插電源，防止電量耗盡直接關機比休眠更難恢復 • 注意散熱，長時間高負載運行要確認機器散熱冇問題 • 任務結束之後記得關閉呢個 feature，唔好俾佢一直開住影響日常使用 • 唔好喺不可信嘅工作區長時間無人值守執行，Codex 喺度持續工作，你唔喺場
network_proxy：代理網絡支持
當前狀態：experimental，默認 false（未啓用）
佢解決咩問題
喺一啲網絡環境裏面，Codex 嘅網絡請求需要經過代理先至可以正常訪問：企業內網強制代理、本地運行緊 Clash / Surge / 系統代理、某啲國家同地區嘅網絡限制等。
network_proxy 嘗試處理 Codex 經過代理時嘅網絡行為，令佢可以正確識別同使用系統或者手動配置嘅代理。
使用方法
# 臨時啓用測試效果
codex --enable network_proxy
# 確認有效後持久啓用
codex features enable network_proxy
# 問題排查時關閉
codex features disable network_proxy配合環境變量使用：
# 設置代理環境變量
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,*.local"
# 然後啓用 network_proxy feature
codex features enable network_proxy
# 運行 Codex
codex排查清單
如果開啓之後仲有網絡問題，按呢個清單逐項檢查：
# 1. 確認當前代理環境
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY
# 2. 確認系統代理是否生效（macOS）
networksetup -getwebproxy Wi-Fi
networksetup -getsecurewebproxy Wi-Fi
# 3. 測試代理是否能正常訪問目標
curl -v --proxy http://127.0.0.1:7890 https://api.openai.com
# 4. 查看 Codex CLI 版本
codex --version
# 5. 關掉 feature 後對比行為
codex features disable network_proxy
codex # 測試不走代理時是否有區別注意事項
• 淨係喺真係遇到網絡問題嗰時先開，唔好"以防萬一"提前打開 • 每次排查淨係改一個變量，唔好同時修改代理配置同 feature 狀態 • 呢個功能可能會影響 Codex 嘅所有網絡請求行為，出現新問題要知道點樣回滾 • 記錄開啓前後嘅具體差異，方便反饋俾 OpenAI
terminal_resize_reflow：終端重排
當前狀態：experimental，默認 true（已啓用）
佢解決咩問題
喺 Codex TUI 裏面，如果你調整咗終端窗口大小，已經渲染嘅內容有時候會變形或者顯示錯亂——長行截斷、表格列對唔齊、代碼塊冇咗縮進。
terminal_resize_reflow 喺窗口尺寸變化之後重新計算同渲染已有內容嘅佈局，解決呢個顯示問題。
適合嘅場景
• 成日調整終端窗口大小 • 用 tmux、screen 等分屏工具 • 喺 IDE 內置終端裏面用（VS Code terminal、JetBrains terminal） • Windows Terminal、iTerm2 等支援多標籤/分屏嘅終端 • 需要成日喺 Codex TUI 裏面睇長 diff、長日誌、大段 markdown
使用方法
# 這個 feature 默認已啓用，通常不需要額外操作
# 如果遇到問題想關閉測試：
codex features disable terminal_resize_reflow
# 重新啓用：
codex features enable terminal_resize_reflow注意事項
呢個係純顯示體驗嘅增強，唔影響 Codex 嘅任何功能。如果你冇遇到終端顯示問題，唔需要特別關注呢個開關。
external_migration：遷移兼容路徑
當前狀態：experimental，默認 false（未啓用）
佢係咩
呢個功能目前公開說明比較少，由名稱判斷同數據遷移路徑或者跨版本兼容性有關。
使用建議
唔建議主動開啓。判斷原則如下：
• 如果你冇跟隨某個明確嘅官方遷移文檔，唔好搞佢 • 如果工具鏈冇要求你開啓佢，唔好搞佢 • 如果你唔清楚佢控制啲咩行為，唔好搞佢
"說明唔充分"本身就係一個信號：呢個功能仲未準備好俾更廣泛咁用。等官方有咗明確嘅使用說明先講。
如果真係需要測試遷移相關行為：
# 臨時啓用，測試完立刻關閉
codex --enable external_migration
# 記錄開啓前後的行為差異
# 確認沒有問題或完成測試後：
codex features disable external_migration實驗性命令
除咗 feature flags，codex --help 裏面仲有幾個俾標註為 [EXPERIMENTAL] 嘅子命令。呢啲命令更偏向平台集成、遠程執行同底層調試，而唔係日常開發嘅直接入口。
codex cloud：由終端操作雲端任務
用途：由本地終端發起、查看同管理 Codex Cloud 任務，將 Cloud 生成嘅結果拉返本地。
核心子命令
# 打開交互式任務選擇器
codex cloud
# 提交雲端任務
codex cloud exec --env <environment-name> "<任務描述>"
# 查看最近的雲端任務列表
codex cloud list
# 查看特定任務詳情
codex cloud list --id <task-id>
# 把 Cloud 任務的 diff 應用到本地
codex cloud apply --id <task-id>使用示例
# 提交一個雲端任務
codex cloud exec --env production-debug \
"Analyze the memory leak in the worker service.
Check heap allocations and event listener cleanup.
Produce a findings report in /tmp/memory-leak-report.md"
# 查看任務是否完成
codex cloud list
# 把結果拉回本地
codex cloud apply --id abc123def456適合嘅場景
• 已經用緊 Codex Cloud 嘅團隊 • 需要喺有特定環境、數據同權限嘅 Cloud 環境裏面執行任務 • 想由終端發起任務而唔使切換到瀏覽器 • 將 Cloud 任務產生嘅 diff 拉返本地做 code review
注意事項
• 需要登錄同有對應 Cloud environment 嘅訪問權限 • --env參數決定任務跑喺邊個環境，揀錯環境會影響結果• Cloud 任務完成唔等於可以跳過本地測試——佢幫你生成 diff，diff 嘅質量仍然係你嘅責任 • 應用 diff 之前一定要 review，唔好直接 apply 就 commit
codex app-server：平台集成接口
用途：為 IDE、內部平台、自研客戶端等上層應用提供統一嘅 Codex 集成接口。官方將佢定位為支撐 richer clients 嘅後端協議層，VS Code extension 就係典型嘅使用方。
核心特性
• 傳輸方式：JSON-RPC over stdio 或者 WebSocket（Unix socket / TCP） • 支援內容：認證、會話歷史、審批流、流式 agent 事件 • 持久化：threads（持久會話）、turns（操作組）、items（原子輸入/輸出） • 協議：支援 V1 同 V2 兩個版本， --experimental可以訪問包含 gated fields 嘅 schema
啓動方式
# 基礎啓動（stdio 模式，供客戶端直接 spawn）
codex app-server
# 監聽本地 Unix socket
codex app-server --listen unix:///tmp/codex-app.sock
# 監聽本地 TCP 端口（需要認證）
codex app-server --listen tcp://127.0.0.1:9000
# 使用 capability token 認證
codex app-server --listen tcp://127.0.0.1:9000 \
--auth-token <your-capability-token>
# 輸出實驗性 JSON Schema（用於生成客戶端協議綁定）
codex app-server --print-schema --experimental協議簡要說明
客戶端連接之後，通過 JSON-RPC 發送消息，格式大致如下：
{
"jsonrpc": "2.0",
"id": "req-001",
"method": "sendMessage",
"params": {
"threadId": "thread-abc123",
"content": "Add input validation to the login endpoint",
"model": "codex-1"
}
}響應以 JSONL 流式返回：
{"type":"turn_start","turnId":"turn-001"}
{"type":"text_delta","content":"I'll add input validation to the login endpoint."}
{"type":"tool_call","tool":"write_file","params":{"path":"src/auth/login.ts"}}
{"type":"approval_required","action":"write_file","path":"src/auth/login.ts"}
{"type":"turn_end","turnId":"turn-001"}適合嘅場景
• 開發 IDE 插件或者編輯器擴展 • 構建內部開發平台同嵌入 Codex 能力 • 調試 app-server 協議行為 • 生成客戶端協議綁定（SDK、類型定義）
唔適合嘅場景
• 普通日常寫代碼（用交互式 TUI 就得） • CI/CD 任務（用 Codex SDK 或者 codex exec --json）• 簡單自動化腳本（ codex exec更加合適）
注意事項
• 暴露 TCP 端口時必須配置認證，支援 capability token 或者 signed bearer token • 唔好將本地調試用嘅 server 暴露到不可信網絡 • --experimentalschema 可能包含未穩定嘅 gated fields，協議將來會變• 自建客戶端時要處理重連邏輯，app-server 可能因為 Codex 側面原因重啓
codex remote-control：遠程控制模式
用途：令本地 app-server daemon 以支援遠程控制嘅模式運行，服務於 SSH 場景同 managed remote-control clients。
佢唔係 app-server 嘅替代品，而係 app-server 嘅一種特殊運行模式，專門用於需要俾受控客戶端連接嘅場景。
# 以遠程控制模式啓動
codex remote-control
# 指定監聽地址（適合 SSH tunnel 場景）
codex remote-control --listen unix:///tmp/codex-rc.sock典型 SSH 場景
# 在遠程服務器上啓動 remote-control daemon
ssh user@remote-server "codex remote-control --listen unix:///tmp/codex.sock &"
# 在本地通過 SSH tunnel 連接
ssh -L /tmp/local-codex.sock:/tmp/codex.sock user@remote-server
# 然後本地客戶端連接 /tmp/local-codex.sock注意事項
• 先明確認證機制同網絡邊界，再考慮部署 • 團隊環境裏面需要有明確嘅安全策略 • 唔好喺冇 SSH tunnel 加密嘅情況下暴露遠程控制接口
codex exec-server：獨立執行服務
用途：運行一個 standalone exec-server service，作為獨立嘅代碼執行節點，供平台集成使用。
# 啓動 exec-server
codex exec-server
# 指定監聽地址和端口
codex exec-server --listen tcp://0.0.0.0:9001
# 註冊到上游 Codex 平台
codex exec-server --register --platform-url https://your-platform.example.com適合嘅場景
• 平台團隊自建執行節點，提供俾多個開發者共用 • 遠程執行環境：服務器或者雲主機上掛 Codex 執行能力 • 驗證 Codex 執行服務嘅安全邊界
重要警告
這是高權限、高風險嘅入口。使用前必須確認：
• 網絡監聽嘅範圍同訪問控制 • executor identity 嘅認證機制 • 可以執行嘅命令範圍同資源限制 • 日誌審計
唔建議喺個人開發機上隨手暴露監聽端口。冇清晰嘅平台設計方案，唔好部署呢個服務。
codex sandbox：沙箱執行環境
用途：喺 Codex 提供嘅受限沙箱環境裏面運行命令，用於驗證命令喺限制環境下嘅行為、調試 sandbox policy，或者排查平台差異。
# 在沙箱裏運行命令
codex sandbox -- <command> [args]
# 示例：在沙箱裏運行測試
codex sandbox -- pnpm test
# 查看沙箱配置
codex sandbox --show-policy
# 只讀沙箱（不允許寫文件）
codex sandbox --policy readonly -- node script.js沙箱策略類型
workspace-write | |
readonly | |
full | |
注意事項
• 沙箱唔係"絕對安全嘅黑盒"，唔好用嚟運行來源不明嘅腳本 • macOS、Linux、Windows 嘅沙箱實現機制唔同，行為可能會有差異 • 如果只係普通開發，用 Codex 標準嘅 --approval-policy就夠，唔需要專門用codex sandbox
codex debug：診斷工具
呢個係俾排查問題用嘅，唔係日常工作入口。
可用子命令
# 查看 Codex 當前識別到的模型列表（raw model catalog）
codex debug models
# 通過內置測試客戶端向 app-server 發送 V2 格式消息
codex debug app-server send-message-v2 \
--thread <thread-id> \
--content "test message"
# 查看當前配置加載狀態
codex debug config
# 測試網絡連通性
codex debug network幾時用
• 模型列表同你預期嘅唔一致，想睇原始數據 • 調試自建客戶端同 app-server 嘅協議交互 • 俾 OpenAI 報告 bug 嗰時，用嚟收集診斷信息 • 排查配置文件加載問題
注意事項
• 輸出可能包含環境相關信息（API key 前綴、本地路徑等），分享前要脱敏 • debug 輸出唔係穩定嘅 API，唔好寫代碼依賴佢嘅格式 • 呢啲命令主要面向工具鏈維護者同高級用戶，睇唔明係正常
功能開關嘅管理方法
睇當前狀態
# 查看所有 feature flags 及其成熟度和當前狀態
codex features list
# 查看幫助
codex features --help臨時開啓（隻影響當前 session）
# 本次運行時臨時啓用
codex --enable goals
# 本次運行時臨時禁用
codex --disable goals
# 同時控制多個
codex --enable goals --enable memories適合第一次試用，唔確定係咪值得長期保留嗰時用。
持久開啓（寫入配置文件）
# 持久啓用
codex features enable goals
# 持久禁用
codex features disable goals呢個會修改 ~/.codex/config.toml：
[features]
goals = true
memories = true
prevent_idle_sleep = false
network_proxy = false
terminal_resize_reflow = true
external_migration = falseWindows 上配置文件路徑通常係：
%USERPROFILE%\.codex\config.toml如果你用咗 --profile 參數，feature 狀態會寫入對應 profile 嘅配置文件，而唔係默認配置。
用 profile 隔離實驗配置
如果你唔想俾實驗配置影響日常使用，可以用 profile 隔離：
# 創建一個用於實驗的 profile 並啓用某些 feature
codex --profile experimental --enable goals --enable prevent_idle_sleep
# 日常使用時不帶 profile，走默認配置
codex配置文件完整示例
# ~/.codex/config.toml
[features]
goals = true
memories = true
terminal_resize_reflow = true
prevent_idle_sleep = false
network_proxy = false
external_migration = false
[model]
default = "codex-1"
[sandbox]
default_policy = "workspace-write"常見問題同解決方案
/goal 設咗但 Codex 執行方向走偏
現象：設咗 goal，但 Codex 改咗唔應該改嘅文件，或者做嘅嘢同目標描述不符。
原因：目標描述太模糊，或者冇明確嘅邊界約束。
解決方案：
# 問題寫法（過於寬泛）
/goal Improve the codebase quality
# 改進寫法（有邊界，有驗證，有停止條件）
/goal Improve type safety in the auth module (src/auth/).
Do not modify test files or the public API types in src/types/auth.d.ts.
After each change, run: pnpm typecheck src/auth.
Stop when pnpm typecheck passes with zero errors for the auth module.如果任務已經開始走偏，即刻暫停：
/goal pause然後重新審視目標描述，補充約束條件之後再 /goal resume。
/goal 執行中途停咗，冇完成
可能原因：
1. 遇到咗需要審批嘅操作，等你回應 2. token 用曬或者 context window 滿咗 3. Codex 遇到咗佢冇辦法處理嘅情況並主動停咗
解決方案：
# 查看當前 goal 狀態
# 在 Codex session 裏：
/goal status
# 如果是審批等待，處理審批：
/OK # 批准
/NO # 拒絕
# 如果 context 太長，壓縮一下：
/compact confirm
# 然後恢復目標
/goal resumememories 將舊項目嘅規則帶咗去新項目
現象：喺新項目裏面，Codex 用咗唔適合嘅命令或者風格，原因係之前某個項目嘅 memory 俾帶過嚟。
解決方案：
有幾種處理方式：
1. 喺 prompt 裏面明確覆蓋：
For this project, ignore any memories about pnpm — this repo uses yarn.
The test command here is: yarn test --coverage.2. 清理唔再適用嘅 memory（編輯 ~/.codex/memories/目錄下嘅文件）。3. 喺 AGENTS.md裏面寫明項目級規則，佢嘅優先級高過 memories：
# AGENTS.md
## Package Manager
This project uses yarn. Do NOT use npm or pnpm.
## Testing
Run tests with: yarn test --coveragenetwork_proxy 開咗但網絡仲係唔通
排查步驟：
# Step 1：確認代理環境變量是否設置
echo $HTTP_PROXY
echo $HTTPS_PROXY
# Step 2：測試代理本身是否可用
curl -v --proxy $HTTP_PROXY https://api.openai.com/v1/models
# Step 3：確認 feature 已啓用
codex features list | grep network_proxy
# Step 4：查看 Codex 是否識別到代理配置
codex debug network
# Step 5：嘗試直連（關掉 feature）
codex features disable network_proxy
codex # 測試直連能否工作如果直連得但代理唔得，問題喺代理配置本身，唔關 Codex 事。
app-server 啓動之後客戶端連接俾拒絕
可能原因：
1. 冇指定正確嘅監聽地址 2. 認證 token 唔啱或者冇傳 3. 端口俾人用咗
解決方案：
# 檢查端口是否被佔用
lsof -i :9000
# Windows:
netstat -ano | findstr :9000
# 確認監聽地址正確
codex app-server --listen tcp://127.0.0.1:9000 --auth-token your-token
# 測試連接
curl -v http://127.0.0.1:9000/health
# 查看 app-server 輸出的日誌，確認啓動成功prevent_idle_sleep 開咗但電腦仍然休眠咗
可能原因：
1. macOS 上某啲低電量情況會強制休眠 2. 外部電源策略覆蓋咗軟件層嘅設置 3. 呢個 feature 本身處於 experimental 狀態，可能喺某啲系統上未完全生效
解決方案：
# macOS：使用 caffeinate 作為備選方案
caffeinate -i codex
# 或者在長任務期間手動保持系統喚醒
caffeinate -dis & # 保持磁盤、空閒、系統喚醒
# 任務結束後：
kill %1 # 或 killall caffeinateWindows 可以用 PowerShell：
# 防止休眠（直到按 Ctrl+C）
powercfg /change standby-timeout-ac 0
# 任務結束後恢復
powercfg /change standby-timeout-ac 15 # 恢復為 15 分鐘codex features enable 之後重啓 Codex 配置消失
可能原因：用咗 --profile 但寫咗去唔同嘅配置文件，或者 config.toml 嘅路徑唔啱。
排查：
# 查看配置文件實際路徑
codex debug config
# 直接查看配置文件內容
cat ~/.codex/config.toml
# Windows
type %USERPROFILE%\.codex\config.toml確認 [features] 部分係咪存在同格式正確。
功能成熟度參考
當你唔確定某個功能係咪值得用嗰時，可以參考呢個判斷框架：
應該開啓嘅信號
• 你有呢個功能對應嘅真實痛點 • 你可以清楚咁寫出成功標準（尤其係對 goals） • 你知道點樣回滾（disable feature 或者退回普通 session） • 你可以接受將來行為變化 • 呢個功能唔會直接影響生產環境或團隊共享流程
唔應該開啓嘅信號
• 只係覺得"呢個功能睇起嚟好新" • 當前工作流已經夠用，冇明確痛點 • 團隊裏面其他人冇辦法復現或者驗證效果 • 任務涉及敏感數據、高權限操作或不可逆變更 • 你冇時間排查實驗功能帶嚟嘅額外變量
推薦嘅開啓順序
第一批（最低風險，最廣適用）：
✅ goals — 適合遷移、重構、持續優化
✅ memories — 適合長期維護固定倉庫
✅ terminal_resize_reflow — 純顯示體驗，無副作用
第二批（有具體場景時啓用）：
⚠️ prevent_idle_sleep — 有長任務時再開，用完關掉
⚠️ network_proxy — 有代理問題時再開排查
暫不建議主動啓用：
⛔ external_migration — 說明不足，等有明確需求再說附錄：驗證命令同當前狀態
基礎驗證命令
# 查看版本
codex --version
# 查看所有 feature flags
codex features list
# 查看 feature 管理幫助
codex features --help
# 查看所有命令（包括實驗性命令）
codex --help
# 各實驗性命令幫助
codex cloud --help
codex app-server --help
codex exec-server --help
codex sandbox --help
codex debug --help本機驗證輸出（codex-cli 0.131.0 / 2026-05-20）
$ codex --version
codex-cli 0.131.0
$ codex features list
Feature Maturity Enabled
─────────────────────────────────────────────
external_migration experimental false
goals experimental true
memories experimental true
network_proxy experimental false
prevent_idle_sleep experimental false
terminal_resize_reflow experimental true配置文件位置
~/.codex/config.toml | |
%USERPROFILE%\.codex\config.toml | |
~/.codex/profiles/<name>/config.toml |
參考資料
• OpenAI Developers：Codex Feature Maturity
https://developers.openai.com/codex/feature-maturity• OpenAI Developers：Codex CLI Features
https://developers.openai.com/codex/cli/features• OpenAI Developers：Codex CLI Command Line Reference
https://developers.openai.com/codex/cli/reference• OpenAI Developers：Follow a Goal
https://developers.openai.com/codex/use-cases/follow-goals• OpenAI Developers：Memories
https://developers.openai.com/codex/memories• OpenAI Developers：Codex App Server
https://developers.openai.com/codex/app-server• GitHub：openai/codex
https://github.com/openai/codex
基準版本：codex-cli 0.131.0 · 驗證日期：2026-05-20
實驗性功能隨版本迭代，使用前建議先執行 codex features list 確認當前狀態。
什麼是實驗性功能
Codex CLI 裏的實驗性功能，是 OpenAI 在正式發佈之前交給真實用戶驗證的一組新能力。它們不是"隱藏彩蛋"，也不是"高級會員專屬"——而是功能本身還在打磨階段，行為、接口、配置項都可能隨版本變化，甚至被整體移除。
OpenAI 對功能成熟度有明確定義：
stable | |
experimental | |
under development | |
deprecated | |
removed |
對於 experimental 狀態的功能，官方的態度是：你可以用，但得自己承擔行為變化的風險。
這意味着：
• 它可能在下一個版本里悄悄改了名字 • 它的某個配置項明天就換了默認值 • 它的行為和文檔描述對不上，這不一定是 bug，可能是文檔沒跟上 • 它可能被正式畢業（進入 stable），也可能被砍掉
知道這些之後，你才能判斷什麼場景值得用、什麼場景應該等。
兩種"實驗性"，別搞混
在 Codex CLI 裏，"實驗性"有兩種形式，放在不同地方，管的是不同粒度的東西。
第一種：Feature Flags（功能開關）
用這個命令可以看到：
codex features list輸出大概長這樣：
Feature Maturity Enabled
─────────────────────────────────────────────
external_migration experimental false
goals experimental true
memories experimental true
network_proxy experimental false
prevent_idle_sleep experimental false
terminal_resize_reflow experimental true這些是顆粒度很細的能力開關，你可以單獨開啓或關閉，狀態會持久寫入 ~/.codex/config.toml。
第二種：實驗性命令（Experimental Commands）
運行 codex --help，可以看到一些子命令旁邊標註了 [EXPERIMENTAL] 或 [experimental]：
codex cloud [EXPERIMENTAL]
codex app-server [experimental]
codex exec-server [EXPERIMENTAL]這些命令本身處於實驗階段，不受 features list 的開關控制，它們的成熟度是命令層面的標註。
兩者的區別：Feature Flag 是"某個具體行為是否開啓"，實驗性命令是"這整個子命令還沒穩定"。管的是不同層次的東西，需要分開看待。
Feature Flags：六個能力開關
goals：給 Codex 一個持續目標
當前狀態：experimental，默認 true（已啓用）
它解決什麼問題
普通 Codex 會話是"一問一答"模式：你發一條消息，它回一條，然後等你繼續。這在處理短任務時沒問題，但遇到需要跨多個步驟持續推進的任務——比如把一個模塊從 JavaScript 遷移到 TypeScript、修復一批測試直到全部通過、按照需求文檔逐步實現一個功能——你就得一直坐在旁邊盯着，不斷告訴它"繼續""記得驗證""不要改這個文件"。
goals 功能讓你可以用 /goal 命令給 Codex 設定一個結構化的目標契約。Codex 會圍繞這個契約持續推進，直到滿足停止條件，而不是每輪都在等你下一個指令。
核心命令
/goal <目標描述> 設定目標，開始持續執行
/goal pause 暫停當前目標
/goal resume 恢復已暫停的目標
/goal clear 清除當前目標
/goal status 查看當前目標狀態怎麼寫一個好的 Goal
/goal 能不能發揮價值，完全取決於你寫的目標質量。一個好的 goal 需要包含五個要素：
| 最終目標 | ||
| 邊界約束 | ||
| 驗證方式 | pnpm test billing && pnpm typecheck | |
| 檢查點 | ||
| 停止條件 |
使用示例
示例一：TypeScript 遷移任務
/goal Migrate the billing module from JavaScript to TypeScript.
Constraints: do not change the public API signatures or return types.
After completing each file, run: pnpm test billing && pnpm typecheck.
Stop when all files are migrated, all tests pass, and MIGRATION.md is updated
with the list of changed files.示例二：測試修復任務
/goal Fix all failing tests in the payments package.
Do not modify test files — only fix implementation code.
After each fix attempt, run: pnpm test packages/payments.
Stop when all tests pass with zero failures.
If a test seems fundamentally broken by design, add a note in FIXME.md
and skip it rather than deleting it.示例三：持續優化 prompts
/goal Improve the summarization prompt in src/prompts/summarize.ts.
Evaluate quality by running: node scripts/eval-summary.js.
Target: average score >= 0.85 across all test cases.
Stop when the target score is reached or after 10 iterations, whichever comes first.
Log each iteration's score to eval-results.log.暫停和恢復
# 臨時暫停，去處理別的事情
/goal pause
# 回來之後恢復
/goal resume適合的使用場景
• 模塊遷移：框架升級、語言遷移、API 替換 • 批量修復：修測試、修 lint、修類型錯誤 • 迭代優化：有可量化指標的持續改進任務 • 原型開發：從空文件到可運行，需要多步驟迭代 • 部署排障：失敗後按策略反覆定位、修復、驗證
注意事項
• 沒有停止條件就不要設 goal。Codex 不知道什麼叫"差不多了"，它會一直執行，直到你告訴它停，或者你的 token 用完。 • 複雜任務建議拆成多個小 goal，不要一次塞進去太多要求。 • goal 執行期間建議保持終端可見，偶爾確認它在做的事情方向正確。 • 要明確寫出哪些文件或範圍不能碰，Codex 不會自己猜邊界。
memories：跨會話的記憶層
當前狀態：experimental，默認 true（已啓用）
它解決什麼問題
Codex 的每個會話默認是無狀態的：上一個會話裏你告訴過它"這個項目用 pnpm 不用 npm"，下一個會話它又不知道了，你得再說一遍。
長期維護幾個固定倉庫的開發者，通常有一大批這樣的"重複交代"：
• 這個項目的測試命令是 pnpm test --filter=...• commit message 必須用中文，格式是 type: 描述• 前端代碼不能改 API contract，只能改視圖層 • 某個第三方庫有坑，別用它的 .toFixed()方法• 代碼風格要和 ESLint 配置保持一致，別"修"它
memories 讓這些穩定的偏好、項目約定和踩坑經驗可以在會話之間持續存在，不用每次重新交代。
記憶的存儲位置
memories 存儲在本地，通常位於：
~/.codex/memories/每條記憶是一個結構化條目，包含內容、來源、時間戳和關聯的項目路徑（如果有的話）。
使用示例
手動添加記憶
Remember: this repo uses pnpm, not npm or yarn. Always use pnpm for package management.
Remember: commit messages in this project must be in Chinese,
format: "type(scope): description", e.g. "fix(auth): 修復登錄態丟失問題".
Remember: do not modify any files under src/api/ — those are auto-generated
from the OpenAPI schema and will be overwritten on next build.讓 Codex 自動總結值得記住的內容
We just fixed the race condition in the WebSocket reconnection logic.
The root cause was that onClose and onMessage could fire in the wrong order
during reconnect. Please remember this for future debugging sessions.查看已有記憶（通過 /status 或配置文件查看）
cat ~/.codex/memories/index.json記憶的分層使用策略
┌─────────────────────────────────────────────────────┐
│ 強制團隊規則 → 寫進 AGENTS.md / README / docs │
│ （版本控制，人人可見，不依賴本地狀態） │
├─────────────────────────────────────────────────────┤
│ 個人長期偏好 → 放進 memories │
│ （跨 session 複用，本地存儲） │
├─────────────────────────────────────────────────────┤
│ 當前任務要求 → 寫在當前 prompt 裏 │
│ （臨時，任務結束就失效） │
└─────────────────────────────────────────────────────┘注意事項
• memories 不是規則手冊，是"偏好召回層"。它可能過期、不完整，也可能被錯誤地套到不適合的項目上。 • 團隊級別的強制約束必須寫進 AGENTS.md或項目文檔，不能只靠 memory。• 如果你在多台機器或多個項目上交替工作，要注意 memory 是否還適用於當前上下文。 • 定期清理過時的 memory，避免陳舊規則干擾新任務。
prevent_idle_sleep：防止長任務中斷
當前狀態：experimental，默認 false（未啓用）
它解決什麼問題
這個問題很具體：你用 /goal 開了一個大型遷移任務，或者讓 Codex 持續跑測試修復，然後去拿了杯咖啡回來，發現電腦睡着了，Codex session 斷掉了，任務從頭來。
prevent_idle_sleep 防止系統在 Codex 任務執行期間進入休眠狀態。
使用方法
# 臨時啓用（當前 session）
codex --enable prevent_idle_sleep
# 持久啓用
codex features enable prevent_idle_sleep
# 任務結束後關閉
codex features disable prevent_idle_sleep配合 goals 使用
這兩個功能本來就是一對：
# 先確保不會休眠
codex features enable prevent_idle_sleep
# 然後開啓長時間目標任務
# 在 Codex session 裏：
/goal Migrate all 47 test files from Jest to Vitest.
After each file migration, run: pnpm test --reporter=verbose.
Stop when all tests pass and the migration summary is written to MIGRATION.md.適合的場景
• 大型重構或遷移（幾十個文件） • 持續跑測試直到全部通過 • 無人值守的本地任務（晚上掛着跑） • 任何預計執行時間超過屏保/休眠等待時間的任務
注意事項
• 筆記本使用時一定要接電源，防止電量耗盡直接關機比休眠更難恢復 • 注意散熱，長時間高負載運行要確認機器散熱沒問題 • 任務結束後記得關閉這個 feature，不要讓它一直開着影響日常使用 • 不要在不可信的工作區長時間無人值守執行，Codex 在持續工作，你不在場
network_proxy：代理網絡支持
當前狀態：experimental，默認 false（未啓用）
它解決什麼問題
在一些網絡環境裏，Codex 的網絡請求需要經過代理才能正常訪問：企業內網強制代理、本地運行着 Clash / Surge / 系統代理、某些國家和地區的網絡限制等。
network_proxy 嘗試處理 Codex 經過代理時的網絡行為，讓它能正確識別和使用系統或手動配置的代理。
使用方法
# 臨時啓用測試效果
codex --enable network_proxy
# 確認有效後持久啓用
codex features enable network_proxy
# 問題排查時關閉
codex features disable network_proxy配合環境變量使用：
# 設置代理環境變量
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,*.local"
# 然後啓用 network_proxy feature
codex features enable network_proxy
# 運行 Codex
codex排查清單
如果開啓後仍有網絡問題，按這個清單逐項檢查：
# 1. 確認當前代理環境
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY
# 2. 確認系統代理是否生效（macOS）
networksetup -getwebproxy Wi-Fi
networksetup -getsecurewebproxy Wi-Fi
# 3. 測試代理是否能正常訪問目標
curl -v --proxy http://127.0.0.1:7890 https://api.openai.com
# 4. 查看 Codex CLI 版本
codex --version
# 5. 關掉 feature 後對比行為
codex features disable network_proxy
codex # 測試不走代理時是否有區別注意事項
• 只在真實遇到網絡問題時才開，不要"以防萬一"提前打開 • 每次排查只改一個變量，不要同時修改代理配置和 feature 狀態 • 這個功能可能影響 Codex 的所有網絡請求行為，出現新問題要知道怎麼回滾 • 記錄開啓前後的具體差異，便於反饋給 OpenAI
terminal_resize_reflow：終端重排
當前狀態：experimental，默認 true（已啓用）
它解決什麼問題
在 Codex TUI 裏，如果你調整了終端窗口大小，已經渲染的內容有時候會變形或者顯示錯亂——長行截斷、表格列對不齊、代碼塊丟了縮進。
terminal_resize_reflow 在窗口尺寸變化後重新計算和渲染已有內容的佈局，解決這個顯示問題。
適合的場景
• 經常調整終端窗口大小 • 使用 tmux、screen 等分屏工具 • 在 IDE 內置終端裏使用（VS Code terminal、JetBrains terminal） • Windows Terminal、iTerm2 等支持多標籤/分屏的終端 • 需要頻繁在 Codex TUI 裏查看長 diff、長日誌、大段 markdown
使用方法
# 這個 feature 默認已啓用，通常不需要額外操作
# 如果遇到問題想關閉測試：
codex features disable terminal_resize_reflow
# 重新啓用：
codex features enable terminal_resize_reflow注意事項
這是純顯示體驗的增強，不影響 Codex 的任何功能。如果你沒有遇到終端顯示問題，不需要特別關注這個開關。
external_migration：遷移兼容路徑
當前狀態：experimental，默認 false（未啓用）
它是什麼
這個功能目前公開說明較少，從名稱判斷與數據遷移路徑或跨版本兼容性有關。
使用建議
不建議主動開啓。判斷原則如下：
• 如果你沒有在跟隨某個明確的官方遷移文檔，不要碰它 • 如果工具鏈沒有要求你啓用它，不要碰它 • 如果你不清楚它控制什麼行為，不要碰它
"說明不充分"本身就是一個信號：這個功能還沒準備好被更廣泛地使用。等官方有了明確的使用說明再說。
如果確實需要測試遷移相關行為：
# 臨時啓用，測試完立刻關閉
codex --enable external_migration
# 記錄開啓前後的行為差異
# 確認沒有問題或完成測試後：
codex features disable external_migration實驗性命令
除了 feature flags，codex --help 裏還有幾個被標註為 [EXPERIMENTAL] 的子命令。這些命令更偏向平台集成、遠程執行和底層調試，而不是日常開發的直接入口。
codex cloud：從終端操作雲端任務
用途：從本地終端發起、查看和管理 Codex Cloud 任務，把 Cloud 生成的結果拉回本地。
核心子命令
# 打開交互式任務選擇器
codex cloud
# 提交雲端任務
codex cloud exec --env <environment-name> "<任務描述>"
# 查看最近的雲端任務列表
codex cloud list
# 查看特定任務詳情
codex cloud list --id <task-id>
# 把 Cloud 任務的 diff 應用到本地
codex cloud apply --id <task-id>使用示例
# 提交一個雲端任務
codex cloud exec --env production-debug \
"Analyze the memory leak in the worker service.
Check heap allocations and event listener cleanup.
Produce a findings report in /tmp/memory-leak-report.md"
# 查看任務是否完成
codex cloud list
# 把結果拉回本地
codex cloud apply --id abc123def456適合的場景
• 已經在使用 Codex Cloud 的團隊 • 需要在有特定環境、數據和權限的 Cloud 環境裏執行任務 • 想從終端發起任務而不用切換到瀏覽器 • 把 Cloud 任務產生的 diff 拉回本地做 code review
注意事項
• 需要登錄並有對應 Cloud environment 的訪問權限 • --env參數決定任務跑在哪個環境，選錯環境影響結果• Cloud 任務完成不等於可以跳過本地測試——它幫你生成 diff，diff 的質量仍然是你的責任 • 應用 diff 前一定要 review，不要直接 apply 就 commit
codex app-server：平台集成接口
用途：為 IDE、內部平台、自研客戶端等上層應用提供統一的 Codex 集成接口。官方將其定位為支撐 richer clients 的後端協議層，VS Code extension 就是典型的使用方。
核心特性
• 傳輸方式：JSON-RPC over stdio 或 WebSocket（Unix socket / TCP） • 支持內容：認證、會話歷史、審批流、流式 agent 事件 • 持久化：threads（持久會話）、turns（操作組）、items（原子輸入/輸出） • 協議：支持 V1 和 V2 兩個版本， --experimental可訪問包含 gated fields 的 schema
啓動方式
# 基礎啓動（stdio 模式，供客戶端直接 spawn）
codex app-server
# 監聽本地 Unix socket
codex app-server --listen unix:///tmp/codex-app.sock
# 監聽本地 TCP 端口（需要認證）
codex app-server --listen tcp://127.0.0.1:9000
# 使用 capability token 認證
codex app-server --listen tcp://127.0.0.1:9000 \
--auth-token <your-capability-token>
# 輸出實驗性 JSON Schema（用於生成客戶端協議綁定）
codex app-server --print-schema --experimental協議簡要說明
客戶端連接後，通過 JSON-RPC 發送消息，格式大致如下：
{
"jsonrpc": "2.0",
"id": "req-001",
"method": "sendMessage",
"params": {
"threadId": "thread-abc123",
"content": "Add input validation to the login endpoint",
"model": "codex-1"
}
}響應以 JSONL 流式返回：
{"type":"turn_start","turnId":"turn-001"}
{"type":"text_delta","content":"I'll add input validation to the login endpoint."}
{"type":"tool_call","tool":"write_file","params":{"path":"src/auth/login.ts"}}
{"type":"approval_required","action":"write_file","path":"src/auth/login.ts"}
{"type":"turn_end","turnId":"turn-001"}適合的場景
• 開發 IDE 插件或編輯器擴展 • 構建內部開發平台並嵌入 Codex 能力 • 調試 app-server 協議行為 • 生成客戶端協議綁定（SDK、類型定義）
不適合的場景
• 普通日常寫代碼（用交互式 TUI 就好） • CI/CD 任務（用 Codex SDK 或 codex exec --json）• 簡單自動化腳本（ codex exec更合適）
注意事項
• 暴露 TCP 端口時必須配置認證，支持 capability token 或 signed bearer token • 不要把本地調試用的 server 暴露到不可信網絡 • --experimentalschema 可能包含未穩定的 gated fields，協議未來會變• 自建客戶端時要處理重連邏輯，app-server 可能因 Codex 側原因重啓
codex remote-control：遠程控制模式
用途：讓本地 app-server daemon 以支持遠程控制的模式運行，服務於 SSH 場景和 managed remote-control clients。
它不是 app-server 的替代品，而是 app-server 的一種特殊運行模式，專門用於需要被受控客戶端連接的場景。
# 以遠程控制模式啓動
codex remote-control
# 指定監聽地址（適合 SSH tunnel 場景）
codex remote-control --listen unix:///tmp/codex-rc.sock典型 SSH 場景
# 在遠程服務器上啓動 remote-control daemon
ssh user@remote-server "codex remote-control --listen unix:///tmp/codex.sock &"
# 在本地通過 SSH tunnel 連接
ssh -L /tmp/local-codex.sock:/tmp/codex.sock user@remote-server
# 然後本地客戶端連接 /tmp/local-codex.sock注意事項
• 先明確認證機制和網絡邊界，再考慮部署 • 團隊環境裏需要有明確的安全策略 • 不要在沒有 SSH tunnel 加密的情況下暴露遠程控制接口
codex exec-server：獨立執行服務
用途：運行一個 standalone exec-server service，作為獨立的代碼執行節點，供平台集成使用。
# 啓動 exec-server
codex exec-server
# 指定監聽地址和端口
codex exec-server --listen tcp://0.0.0.0:9001
# 註冊到上游 Codex 平台
codex exec-server --register --platform-url https://your-platform.example.com適合的場景
• 平台團隊自建執行節點，提供給多個開發者共用 • 遠程執行環境：服務器或雲主機上掛 Codex 執行能力 • 驗證 Codex 執行服務的安全邊界
重要警告
這是高權限、高風險的入口。使用前必須確認：
• 網絡監聽的範圍和訪問控制 • executor identity 的認證機制 • 可執行的命令範圍和資源限制 • 日誌審計
不建議在個人開發機上隨手暴露監聽端口。沒有清晰的平台設計方案，不要部署這個服務。
codex sandbox：沙箱執行環境
用途：在 Codex 提供的受限沙箱環境裏運行命令，用於驗證命令在限制環境下的行為、調試 sandbox policy，或者排查平台差異。
# 在沙箱裏運行命令
codex sandbox -- <command> [args]
# 示例：在沙箱裏運行測試
codex sandbox -- pnpm test
# 查看沙箱配置
codex sandbox --show-policy
# 只讀沙箱（不允許寫文件）
codex sandbox --policy readonly -- node script.js沙箱策略類型
workspace-write | |
readonly | |
full | |
注意事項
• 沙箱不是"絕對安全的黑盒"，不要用來運行來源不明的腳本 • macOS、Linux、Windows 的沙箱實現機制不同，行為可能有差異 • 如果只是普通開發，用 Codex 標準的 --approval-policy就夠了，不需要專門用codex sandbox
codex debug：診斷工具
這是給排查問題用的，不是日常工作入口。
可用子命令
# 查看 Codex 當前識別到的模型列表（raw model catalog）
codex debug models
# 通過內置測試客戶端向 app-server 發送 V2 格式消息
codex debug app-server send-message-v2 \
--thread <thread-id> \
--content "test message"
# 查看當前配置加載狀態
codex debug config
# 測試網絡連通性
codex debug network什麼時候用
• 模型列表和你預期的不一致，想看原始數據 • 調試自建客戶端與 app-server 的協議交互 • 給 OpenAI 報告 bug 時，用來收集診斷信息 • 排查配置文件加載問題
注意事項
• 輸出可能包含環境相關信息（API key 前綴、本地路徑等），分享前要脱敏 • debug 輸出不是穩定的 API，不要寫代碼依賴它的格式 • 這些命令主要面向工具鏈維護者和高級用戶，看不懂是正常的
功能開關的管理方法
查看當前狀態
# 查看所有 feature flags 及其成熟度和當前狀態
codex features list
# 查看幫助
codex features --help臨時啓用（隻影響當前 session）
# 本次運行時臨時啓用
codex --enable goals
# 本次運行時臨時禁用
codex --disable goals
# 同時控制多個
codex --enable goals --enable memories適合第一次試用，不確定是否值得長期保留時使用。
持久啓用（寫入配置文件）
# 持久啓用
codex features enable goals
# 持久禁用
codex features disable goals這會修改 ~/.codex/config.toml：
[features]
goals = true
memories = true
prevent_idle_sleep = false
network_proxy = false
terminal_resize_reflow = true
external_migration = falseWindows 上配置文件路徑通常是：
%USERPROFILE%\.codex\config.toml如果你使用了 --profile 參數，feature 狀態會寫入對應 profile 的配置文件，而不是默認配置。
使用 profile 隔離實驗配置
如果你不想讓實驗配置影響日常使用，可以用 profile 隔離：
# 創建一個用於實驗的 profile 並啓用某些 feature
codex --profile experimental --enable goals --enable prevent_idle_sleep
# 日常使用時不帶 profile，走默認配置
codex配置文件完整示例
# ~/.codex/config.toml
[features]
goals = true
memories = true
terminal_resize_reflow = true
prevent_idle_sleep = false
network_proxy = false
external_migration = false
[model]
default = "codex-1"
[sandbox]
default_policy = "workspace-write"常見問題與解決方案
/goal 設了但 Codex 執行方向跑偏
現象：設了 goal，但 Codex 改了不該改的文件，或者做的事和目標描述不符。
原因：目標描述太模糊，或者沒有明確的邊界約束。
解決方案：
# 問題寫法（過於寬泛）
/goal Improve the codebase quality
# 改進寫法（有邊界，有驗證，有停止條件）
/goal Improve type safety in the auth module (src/auth/).
Do not modify test files or the public API types in src/types/auth.d.ts.
After each change, run: pnpm typecheck src/auth.
Stop when pnpm typecheck passes with zero errors for the auth module.如果任務已經開始跑偏，立刻暫停：
/goal pause然後重新審視目標描述，補充約束條件後再 /goal resume。
/goal 執行中途停止，沒有完成
可能原因：
1. 遇到了需要審批的操作，等待你的響應 2. token 耗盡或 context window 滿了 3. Codex 遇到了它無法處理的情況並主動停了
解決方案：
# 查看當前 goal 狀態
# 在 Codex session 裏：
/goal status
# 如果是審批等待，處理審批：
/OK # 批准
/NO # 拒絕
# 如果 context 太長，壓縮一下：
/compact confirm
# 然後恢復目標
/goal resumememories 把舊項目的規則帶到了新項目
現象：在新項目裏，Codex 用了不適合的命令或風格，原因是之前某個項目的 memory 被帶過來了。
解決方案：
有幾種處理方式：
1. 在 prompt 裏明確覆蓋：
For this project, ignore any memories about pnpm — this repo uses yarn.
The test command here is: yarn test --coverage.2. 清理不再適用的 memory（編輯 ~/.codex/memories/目錄下的文件）。3. 在 AGENTS.md裏寫明項目級規則，它的優先級高於 memories：
# AGENTS.md
## Package Manager
This project uses yarn. Do NOT use npm or pnpm.
## Testing
Run tests with: yarn test --coveragenetwork_proxy 開了但網絡還是不通
排查步驟：
# Step 1：確認代理環境變量是否設置
echo $HTTP_PROXY
echo $HTTPS_PROXY
# Step 2：測試代理本身是否可用
curl -v --proxy $HTTP_PROXY https://api.openai.com/v1/models
# Step 3：確認 feature 已啓用
codex features list | grep network_proxy
# Step 4：查看 Codex 是否識別到代理配置
codex debug network
# Step 5：嘗試直連（關掉 feature）
codex features disable network_proxy
codex # 測試直連能否工作如果直連可以但代理不行，問題在代理配置本身，不在 Codex。
app-server 啓動後客戶端連接被拒絕
可能原因：
1. 沒有指定正確的監聽地址 2. 認證 token 不對或沒傳 3. 端口被佔用
解決方案：
# 檢查端口是否被佔用
lsof -i :9000
# Windows:
netstat -ano | findstr :9000
# 確認監聽地址正確
codex app-server --listen tcp://127.0.0.1:9000 --auth-token your-token
# 測試連接
curl -v http://127.0.0.1:9000/health
# 查看 app-server 輸出的日誌，確認啓動成功prevent_idle_sleep 開了但電腦還是休眠了
可能原因：
1. macOS 上某些低電量情況會強制休眠 2. 外部電源策略覆蓋了軟件層的設置 3. 這個 feature 本身處於 experimental 狀態，可能在某些系統上未完全生效
解決方案：
# macOS：使用 caffeinate 作為備選方案
caffeinate -i codex
# 或者在長任務期間手動保持系統喚醒
caffeinate -dis & # 保持磁盤、空閒、系統喚醒
# 任務結束後：
kill %1 # 或 killall caffeinateWindows 可以用 PowerShell：
# 防止休眠（直到按 Ctrl+C）
powercfg /change standby-timeout-ac 0
# 任務結束後恢復
powercfg /change standby-timeout-ac 15 # 恢復為 15 分鐘codex features enable 後重啓 Codex 配置消失
可能原因：使用了 --profile 但寫入了不同的配置文件，或者 config.toml 的路徑不對。
排查：
# 查看配置文件實際路徑
codex debug config
# 直接查看配置文件內容
cat ~/.codex/config.toml
# Windows
type %USERPROFILE%\.codex\config.toml確認 [features] 部分是否存在且格式正確。
功能成熟度參考
當你不確定某個功能是否值得使用時，可以參考這個判斷框架：
應該啓用的信號
• 你有這個功能對應的真實痛點 • 你能清楚地寫出成功標準（尤其對 goals） • 你知道怎麼回滾（disable feature 或退回普通 session） • 你能接受未來行為變化 • 這個功能不會直接影響生產環境或團隊共享流程
不應該啓用的信號
• 只是覺得"這個功能看起來很新" • 當前工作流已經夠用，沒有明確痛點 • 團隊裏其他人沒辦法復現或驗證效果 • 任務涉及敏感數據、高權限操作或不可逆變更 • 你沒有時間排查實驗功能帶來的額外變量
推薦的開啓順序
第一批（最低風險，最廣適用）：
✅ goals — 適合遷移、重構、持續優化
✅ memories — 適合長期維護固定倉庫
✅ terminal_resize_reflow — 純顯示體驗，無副作用
第二批（有具體場景時啓用）：
⚠️ prevent_idle_sleep — 有長任務時再開，用完關掉
⚠️ network_proxy — 有代理問題時再開排查
暫不建議主動啓用：
⛔ external_migration — 說明不足，等有明確需求再說附錄：驗證命令與當前狀態
基礎驗證命令
# 查看版本
codex --version
# 查看所有 feature flags
codex features list
# 查看 feature 管理幫助
codex features --help
# 查看所有命令（包括實驗性命令）
codex --help
# 各實驗性命令幫助
codex cloud --help
codex app-server --help
codex exec-server --help
codex sandbox --help
codex debug --help本機驗證輸出（codex-cli 0.131.0 / 2026-05-20）
$ codex --version
codex-cli 0.131.0
$ codex features list
Feature Maturity Enabled
─────────────────────────────────────────────
external_migration experimental false
goals experimental true
memories experimental true
network_proxy experimental false
prevent_idle_sleep experimental false
terminal_resize_reflow experimental true配置文件位置
~/.codex/config.toml | |
%USERPROFILE%\.codex\config.toml | |
~/.codex/profiles/<name>/config.toml |
參考資料
• OpenAI Developers：Codex Feature Maturity
https://developers.openai.com/codex/feature-maturity• OpenAI Developers：Codex CLI Features
https://developers.openai.com/codex/cli/features• OpenAI Developers：Codex CLI Command Line Reference
https://developers.openai.com/codex/cli/reference• OpenAI Developers：Follow a Goal
https://developers.openai.com/codex/use-cases/follow-goals• OpenAI Developers：Memories
https://developers.openai.com/codex/memories• OpenAI Developers：Codex App Server
https://developers.openai.com/codex/app-server• GitHub：openai/codex
https://github.com/openai/codex
基準版本：codex-cli 0.131.0 · 驗證日期：2026-05-20
實驗性功能隨版本迭代，使用前建議先運行 codex features list 確認當前狀態。