Codex CLI 實驗性功能：Goal、Memories...

作者：Ranger Ramblings

日期：2026年5月20日下午7:47

來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點高亮

Codex CLI 嘅實驗性功能：Goals同Memories，幫你設定持續目標同跨會話記憶，但使用時要留意佢哋仲未穩定，行為隨時會變。

整理版摘要

呢篇文章係整理自OpenAI官方文檔同作者嘅使用經驗，主要介紹Codex CLI入面嘅實驗性功能（experimental features）。作者想解決讀者對「實驗性功能」嘅誤解：佢哋唔係隱藏彩蛋，而係仲喺打磨階段嘅能力，行為同配置都可能變，甚至會被成個移除。整體結論係：呢啲功能好有用，特別係Goals同Memories，可以大幅提升工作效率，但用之前一定要清楚風險，知道點樣回滾，同埋唔好放喺生產環境或者團隊共享流程。

文章首先解釋咗兩種「實驗性」嘅形式：Feature Flags（功能開關）同Experimental Commands（實驗性命令）。Feature Flags係細粒嘅能力開關，可以獨立開關，狀態會寫入~/.codex/config.toml。Experimental Commands係成個子命令未穩定，唔受Feature Flags控制。然後詳細介紹咗六個Feature Flags：goals、memories、prevent_idle_sleep、network_proxy、terminal_resize_reflow、external_migration。重點係goals同memories，前者可以畀你設定持續目標，自動推進任務；後者可以跨會話記憶個人偏好同項目約定。

最後介紹咗幾個Experimental Commands：codex cloud、app-server、exec-server…

Codex CLI嘅實驗性功能分兩種：Feature Flags（功能開關）同Experimental Commands（實驗性命令），兩者管理嘅粒度唔同，要分開看待。
用/goal設定持續目標時，一定要包含五個要素：最終目標、邊界約束、驗證方式、檢查點、停止條件，否則Codex會一直執行到天荒地老。
memories可以跨會話記住你嘅偏好（例如用pnpm唔用npm），但團隊級規則一定要寫入AGENTS.md或README，唔可以只靠memory。
prevent_idle_sleep可以防止長任務期間電腦休眠，但筆電要接電源，任務完咗要記得關閉。
唔好因為功能睇起嚟新就用，要有明確痛點、知道點樣回滾、唔影響生產環境先值得開。

值得記低

連結 developers.openai.com

OpenAI Developers：Codex Feature Maturity

官方文檔，解釋功能成熟度標籤嘅含義。

連結 developers.openai.com

OpenAI Developers：Codex CLI Features

官方文檔，列出所有Feature Flags同使用方式。

連結 developers.openai.com

OpenAI Developers：Follow a Goal

官方文檔，詳細講解/goal嘅用法同最佳實踐。

連結 developers.openai.com

OpenAI Developers：Memories

官方文檔，講解memories嘅概念同用法。

結構示例

內容片段

內容片段 text

Feature                  Maturity      Enabled─────────────────────────────────────────────external_migration       experimental  falsegoals                    experimental  truememories                 experimental  truenetwork_proxy            experimental  falseprevent_idle_sleep       experimental  falseterminal_resize_reflow   experimental  true

整理重點

咩係實驗性功能？點樣分清楚？

Codex CLI嘅實驗性功能係OpenAI未正式發佈前畀用戶驗證嘅新能力。佢哋唔係隱藏彩蛋，而係功能仲喺打磨階段，行為、接口、配置都可能隨版本變化，甚至會被成個移除。

另外，文章強調兩種「實驗性」形式：Feature Flags（例如goals、memories）同Experimental Commands（例如codex cloud、codex app-server）。前者係細粒嘅能力開關，後者係成個子命令未穩定，兩者管嘅範圍唔同。

1 Feature Flags：可以獨立開關，狀態寫入~/.codex/config.toml，用codex features list查看。
2 Experimental Commands：用codex --help見到標註[EXPERIMENTAL]嘅子命令，唔受Feature Flags控制。

整理重點

六個Feature Flags：Goals、Memories同其他

目前有六個Feature Flags，其中goals同memories默認啟用，最值得關注。下面逐一介紹。

/goal可以設定持續目標，Codex會自動推進直到停止條件

goals解決咗「一問一答」模式唔適合多步驟任務嘅問題。你可以用/goal設定一個結構化目標契約，例如遷移模塊、修復測試。一個好嘅goal要包含五個要素：

最終目標：一句話講清要做乜
邊界約束：邊啲文件/接口唔可以改
驗證方式：用咩命令證明完成
檢查點：點樣分階段避免一嘢跑太遠
停止條件：咩情況下應該結束

而memories可以跨會話記住你嘅偏好，例如「呢個項目用pnpm唔用npm」、「commit message要用中文」。佢哋儲存喺~/.codex/memories/，每條記憶包含內容、來源、時間戳。

但係要注意：memories唔係規則手冊，佢只係偏好召回層。團隊級別嘅強制約束一定要寫入AGENTS.md或README，唔可以只靠memory。另外要定期清理過時嘅記憶，避免幹擾新任務。

其他四個Flags：prevent_idle_sleep防止長任務期間電腦休眠，默認關閉；network_proxy處理代理網絡問題，默認關閉；terminal_resize_reflow改善終端窗口調整後嘅顯示，默認開啟；external_migration說明不足，唔建議主動開。

整理重點

Experimental Commands：雲端、集成同調試

除咗Feature Flags，仲有幾個實驗性命令：codex cloud可以從終端操作雲端任務，提交、查看、應用diff；codex app-server係平台集成接口，用JSON-RPC協議支援IDE插件；codex remote-control係遠程控制模式，配合SSH使用；codex exec-server係獨立執行服務，高權限高風險；codex sandbox係沙箱執行環境；codex debug係診斷工具。

對於普通開發者，日常用交互式TUI就得，唔需要搞呢啲複雜嘢。但如果你係整IDE插件或者內部平台，app-server就係必備。

整理重點

功能開關管理同風險控制

管理Feature Flags好簡單：用codex --enable <flag>臨時啟用，用codex features enable <flag>持久啟用。如果你唔想影響日常配置，可以用--profile參數隔離實驗配置。

唔應該啓用嘅信號：只係覺得新、冇明確痛點、影響生產環境、冇時間排查問題

文章最後畀咗一個實用嘅判斷框架：有真實痛點、知道成功標準、曉得回滾、接受未來變化、唔影響團隊共享流程，先值得開。推薦嘅開啓順序：第一批：goals、memories、terminal_resize_reflow（低風險）；第二批：prevent_idle_sleep、network_proxy（有場景先開）；external_migration暫唔建議。

整理重點

常見問題快速排查

文章整理咗幾個常見問題：/goal執行跑偏通常係目標描述太模糊，要補充邊界約束；/goal中途停止可能係遇到審批或者token耗盡，可以用/goal status檢查；memories帶錯規則可以用prompt覆蓋或者清理記憶；network_proxy唔通要逐項排查代理環境變量同feature狀態；app-server連接拒絕要先確認監聽地址同認證。

另外，如果prevent_idle_sleep失效，可以用系統工具做後備：macOS用caffeinate，Windows用powercfg。

自己整嘅中轉站每日都跑唔滿...所以有需要嘅朋友可以私訊我，價錢係￥1 = $10 咁樣。

咩係實驗性功能

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 需要包含五個元素：

要素	說明	示例
最終目標	具體要完成啲咩，一句說話講清楚	完成 billing 模組嘅 TypeScript 搬遷
邊界限制	邊啲檔案、接口、行為唔可以掂	唔改變 public API 嘅入參同回傳值
驗證方式	用咩指令或者產物證明完成咗	`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 暴露到唔可信嘅網絡
• --experimental schema 可能包含未穩定嘅 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 = false

Windows 上設定檔路徑通常係：

%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 resume

memories 將舊項目嘅規則帶到新項目

現象：喺新項目入面，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 --coverage

`network_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 caffeinate

Windows 可以用 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）
• 你可以接受將來行為變化
• 呢個功能唔會直接影響生產環境或團隊共享流程

唔應該啟用嘅訊號

• 只係覺得「呢個功能好似好新」
• 而家嘅工作流程已經夠用，冇明確痛點
• 團隊入面其他人冇辦法重現或驗證效果
• 任務涉及敏感數據、高權限操作或不可逆變更
• 你冇時間排查實驗功能帶嚟嘅額外變數

附錄：驗證指令與當前狀態

基礎驗證指令

# 查看版本
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

設定檔位置

平台	預設設定檔路徑
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`
自訂 profile	`~/.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 確認當前狀態。

自建的中轉站每天還是跑不滿...所以有需要的朋友可以私信我，價格是￥1 = $10 這樣子。

什麼是實驗性功能

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 需要包含五個要素：

要素	說明	示例
最終目標	具體要完成什麼，一句話說清楚	完成 billing 模塊的 TypeScript 遷移
邊界約束	哪些文件、接口、行為不能碰	不改變 public API 的入參和返回值
驗證方式	用什麼命令或產物證明完成了	`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 暴露到不可信網絡
• --experimental schema 可能包含未穩定的 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 = false

Windows 上配置文件路徑通常是：

%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 resume

memories 把舊項目的規則帶到了新項目

現象：在新項目裏，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 --coverage

`network_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 caffeinate

Windows 可以用 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）
• 你能接受未來行為變化
• 這個功能不會直接影響生產環境或團隊共享流程

不應該啓用的信號

• 只是覺得"這個功能看起來很新"
• 當前工作流已經夠用，沒有明確痛點
• 團隊裏其他人沒辦法復現或驗證效果
• 任務涉及敏感數據、高權限操作或不可逆變更
• 你沒有時間排查實驗功能帶來的額外變量

附錄：驗證命令與當前狀態

基礎驗證命令

# 查看版本
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

配置文件位置

平台	默認配置文件路徑
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`
自定義 profile	`~/.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 確認當前狀態。

內容片段

咩係實驗性功能？點樣分清楚？

六個Feature Flags：Goals、Memories同其他

Experimental Commands：雲端、集成同調試

功能開關管理同風險控制

常見問題快速排查

咩係實驗性功能

兩種「實驗性」，唔好搞亂

Feature Flags：六個能力開關

goals：俾 Codex 一個持續目標

佢解決啲咩問題

核心指令

點樣寫一個好嘅 Goal

使用示例

適合嘅使用場景

注意事項

memories：跨對話嘅記憶層

佢解決啲咩問題

記憶嘅儲存位置

使用示例

記憶嘅分層使用策略

注意事項

prevent_idle_sleep：防止長任務中斷

佢解決啲咩問題

使用方法

配合 goals 使用

適合嘅場景

注意事項

network_proxy：代理網絡支援

佢解決啲咩問題

使用方法

排查清單

注意事項

terminal_resize_reflow：終端重新排版

佢解決啲咩問題

適合嘅場景

使用方法

注意事項

external_migration：搬遷兼容路徑

佢係咩嚟

使用建議

實驗性指令

codex cloud：由終端操作雲端任務

核心子指令

使用示例

適合嘅場景

注意事項

codex app-server：平台整合接口

核心特性

啟動方式

協議簡要說明

適合嘅場景

唔適合嘅場景

注意事項

codex remote-control：遠端控制模式

典型 SSH 場景

注意事項

codex exec-server：獨立執行服務

適合嘅場景

重要警告

codex sandbox：沙箱執行環境

沙箱策略類型

注意事項

codex debug：診斷工具

可用子指令

幾時用

注意事項

功能開關嘅管理方法

查看當前狀態

暫時啟用（隻影響當前 session）

持久啟用（寫入設定檔）

用 profile 隔離實驗配置

設定檔完整示例

常見問題與解決方案

/goal 設咗但 Codex 執行方向偏咗

/goal 執行中途停咗，冇完成

memories 將舊項目嘅規則帶到新項目

network_proxy 開咗但網絡仲係唔通

app-server 啟動後客戶端連接被拒絕

prevent_idle_sleep 開咗但電腦仍然休眠

`goals`：俾 Codex 一個持續目標

`memories`：跨對話嘅記憶層

`prevent_idle_sleep`：防止長任務中斷

`network_proxy`：代理網絡支援

`terminal_resize_reflow`：終端重新排版

`external_migration`：搬遷兼容路徑

`codex cloud`：由終端操作雲端任務

`codex app-server`：平台整合接口

`codex remote-control`：遠端控制模式

`codex exec-server`：獨立執行服務

`codex sandbox`：沙箱執行環境

`codex debug`：診斷工具

`/goal` 設咗但 Codex 執行方向偏咗

`/goal` 執行中途停咗，冇完成

`network_proxy` 開咗但網絡仲係唔通

`app-server` 啟動後客戶端連接被拒絕

`prevent_idle_sleep` 開咗但電腦仍然休眠

`codex features enable` 之後重啟 Codex 配置消失

`goals`：給 Codex 一個持續目標

`memories`：跨會話的記憶層

`prevent_idle_sleep`：防止長任務中斷

`network_proxy`：代理網絡支持

`terminal_resize_reflow`：終端重排

`external_migration`：遷移兼容路徑

`codex cloud`：從終端操作雲端任務

`codex app-server`：平台集成接口

`codex remote-control`：遠程控制模式

`codex exec-server`：獨立執行服務

`codex sandbox`：沙箱執行環境

`codex debug`：診斷工具