CodexPotter | 如何讓 Codex 持續工作一整天
整理版優先睇
CodexPotter 令 OpenAI Codex 自動持續執行編碼任務，透過多輪循環 Review 同乾淨上下文解決爛尾問題。
呢篇文章由開發者 breezewish 撰寫，介紹一個叫 CodexPotter 嘅工具，佢係基於 OpenAI Codex CLI 嘅自主循環執行器。作者本身用 Codex 做大規模編碼任務嗰陣，成日遇到單輪 Codex 只完成一部分就爛尾、長對話導致上下文污染越聊越蠢、要人肉反覆 review 等問題。為咗解放開發者，佢設計咗 CodexPotter，將任務畀佢自主執行，而唔係同佢傾偈。整體結論係：CodexPotter 透過多輪自動 Review + 繼續執行、每輪用乾淨上下文、以文件系統做記憶，有效提升 Codex 完成大型任務嘅一致性同質素。
CodexPotter 嘅工作流程係咁：你提交一個任務 Prompt，佢會寫入進度文件 MAIN.md，然後 Codex 拆成子任務 Todo，循環執行直到所有 Todo 完成，再嚴格 Review，確認完全對齊先結束。呢個過程唔需要你插手，佢會自動 commit 每步變更，仲支援 Resume 中途斷連嘅任務。
作者強調 CodexPotter 唔係取代 Codex，而係同佢配合：CodexPotter 負責循環排程，Codex 負責實際編碼。佢仲有知識庫機制，跨會話積累項目知識，避免新 Codex 會話重新理解。總括嚟講，呢個工具適合有明確目標嘅多輪迭代任務，例如移植功能、重構模塊、實現訂閲系統等，但唔適合需要 UI 反饋或開放性討論嘅場景。
- CodexPotter 多輪自動 Review + 繼續執行，直到任務完全對齊，解決單輪爛尾。
- 每輪用乾淨上下文（clean context），避免上下文積累導致的質量退化。
- 以文件系統做記憶（MAIN.md），任務細節唔會喺多輪對話中丟失。
- 與 Codex CLI 配合使用：CodexPotter 負責循環排程，Codex 負責實際編碼。
- 支援 Resume、知識庫、雙模型交叉 Review 等高級功能，適合大型編碼任務。
GitHub 倉庫
CodexPotter 原始碼同說明文件。
npm 套件
可透過 npm install -g codex-potter 安裝。
任務示例：移植 resume 功能
用嚟畀 CodexPotter 執行嘅任務 Prompt：「port upstream codex's /resume into this project, keep code aligned」。
兩階段工作流（先規劃後實現）
任務一：用 CodexPotter 規劃設計方案，輸出到文件；任務二：根據文件實現，確保測試通過。
內容片段
Analyze the codebase, research and design a solution for introducing subscription system.Output plan to docs/subscription_design.md.Your solution should meet the following requirements: ...Do not implement the plan, just design a good and simple solution.背景同問題
CodexPotter 係一個圍繞 OpenAI Codex CLI 構建嘅自主循環執行器，靈感來自 Ralph Wiggum 模式——持續將代碼庫「對齊」到你指定嘅目標狀態。作者 breezewish 發現，用 Codex 做大規模編碼任務嗰陣，最頭痛嘅係單輪 Codex 成日留下「爛尾」，而且長對話會令模型「越聊越蠢」，因為上下文污染。
- 痛點：單輪爛尾 → CodexPotter 多輪自動 Review 直到完成。
- 痛點：長對話上下文污染 → 每輪用乾淨上下文（clean context）。
- 痛點：需要人工反覆跟進 → 自動 review 流程，你只需專註定義任務。
- 痛點：任務細節喺多輪對話中丟失 → 以文件系統做記憶（MAIN.md）。
工作原理：點樣自主執行？
你提交一個任務 Prompt 之後，CodexPotter 會將任務寫入進度文件 MAIN.md，狀態設為 initial。然後 Codex 讀取進度文件，將任務拆解成子任務（Todo），狀態變為 open，再循環執行每個 Todo：Todo → In Progress → Done，每輪完成後自動 git commit。
- 1 你向 CodexPotter 提交任務 Prompt。
- 2 CodexPotter 寫入 MAIN.md，狀態 initial。
- 3 Codex 讀取進度，拆解為 Todo，狀態 open。
- 4 Codex 循環執行子任務，每輪完成 commit。
- 5 所有 Todo 完成後，Codex 嚴格 Review，補充遺漏，直到完全對齊。
進度文件同知識庫都保存在 .codexpotter/ 目錄下，已自動加入 .gitignore，唔會污染你嘅 git 歷史。
使用場景同示例
CodexPotter 適合有明確目標、需要多輪迭代嘅編碼任務，例如移植功能、重構模塊、實現訂閲系統。佢亦適合需要持久化產出嘅設計文檔或研究任務。
唔適合需要人工 UI 反饋嘅前端開發，或者開放性討論——嗰啲直接用 Codex CLI 就得。
示例 1：單任務執行——「port upstream codex's /resume into this project, keep code aligned」。示例 3：先規劃後實現——任務一輸出設計文檔，任務二根據文檔實現，確保 e2e 測試通過。
- ✅ 適合：有明確範圍嘅編碼任務、多輪迭代、持久化產出、全量測試覆蓋。
- ❌ 唔適合：前端開發（需要 UI 反饋）、問答解釋代碼、頭腦風暴。
高級功能同注意事項
CodexPotter 支援 雙模型交叉 Review（--xmodel），用 gpt-5.2 執行、gpt-5.4 Review，可能產出更好結果。仲有 Resume 功能，網絡斷連後可以繼續迭代。
知識庫（.codexpotter/kb/）會喺每次深度探索模塊後記錄關鍵事實同代碼位置，新會話啟動前讀取知識庫，等 Codex 快速上手。
- 1 Resume：歷史回放 + 繼續迭代，斷連無有怕。
- 2 知識庫：跨會話積累項目知識，減少重新理解。
- 3 AGENTS.md / Skills / MCP 集成：與 Codex 生態無縫兼容。
- 4 注意：每個 Prompt 係獨立任務，唔好當係聊天工具。
Ralph loop for codex — 持續將程式碼庫對齊你指定嘅目標狀態。
• 倉庫地址：https://github.com/breezewish/CodexPotter • License：Apache-2.0 • 發佈渠道：npm: codex-potter[1] • 支持平台：Linux（x86_64 / aarch64）、macOS（Apple Silicon / Intel）、Windows（x86_64 / ARM64）
📌 項目簡介
CodexPotter 係一個圍繞 OpenAI Codex CLI[2] 構建的自主循環執行器，佢實現咗 Ralph Wiggum 模式[3]——即係持續地、多輪咁將程式碼庫「對齊」（reconcile）到你話俾佢知嘅目標狀態，直到任務完全搞掂為止。
同直接同 Codex CLI 傾偈唔同，CodexPotter 嘅核心概念係：將任務交俾佢，等佢自己執行，而唔係同佢傾偈。
🧩 解決咗啲乜嘢問題
用 Codex 做大規模編碼任務嘅時候，常見嘅痛點包括：
.codexpotter/kb/），跨會話累積項目知識 | |
⚙️ 工作原理
CodexPotter 嘅工作流程可以用下圖嚟理解：
執行流程（內部 Prompt 機制）：
1. 你向 CodexPotter 提交一個任務 Prompt 2. CodexPotter 將任務寫入進度檔案（ MAIN.md），狀態設為initial3. Codex 讀取進度檔案，將任務拆散做子任務（ Todo），狀態變為open4. Codex 循環執行子任務： Todo → In Progress → Done，並喺每輪完成之後提交 git commit5. 所有 Todo完成之後，Codex 進行嚴格 Review，揾出漏咗或者未對齊嘅地方，繼續補充Todo6. 直到 Review 確認完全對齊，任務就完
進度檔案、知識庫等全部都保存喺 .codexpotter/ 目錄下（已經自動加入 .gitignore，唔會被提交）。
🚀 快速上手
前置條件
確保本地已經安裝同配置好 Codex CLI[2]（需要 OpenAI Codex 訂閲）。
安裝
# 使用 npm
npm install -g codex-potter
# 使用 bun
bun install -g codex-potter啓動
喺你嘅項目目錄下運行：
# 推薦使用 --yolo 模式以實現完全自主執行（無沙箱）
codex-potter --yolo⚠️ 重要注意事項
• 每條 Prompt 都係獨立任務：同 Codex 唔同，CodexPotter 入面每個後續 Prompt 都會開一個新任務，唔會同上一個任務共享上下文。請將佢當做任務分配工具，而唔係吹水工具。 • 唔係 Codex 嘅替代品：CodexPotter 係循環執行器，Codex 負責實際編碼。兩者配合用，效果最好。
💡 使用場景
✅ 適合嘅場景
❌ 唔適合嘅場景
📋 使用示例
示例 1：單任務執行
port upstream codex's /resume into this project, keep code aligned示例 2：輸出持久化（等結果可以喺後續輪次重用）
create a design doc for the new subscription system in DESIGN.md技巧：叫 Codex 將中間產出寫入檔案（例如
DESIGN.md），咁就可以俾下一個任務直接引用，實現「先設計再實現」嘅工作流程。
示例 3：先規劃後實現（兩階段工作流）
任務 1（規劃階段）：
Analyze the codebase, research and design a solution for introducing subscription system.
Output plan to docs/subscription_design.md.
Your solution should meet the following requirements: ...
Do not implement the plan, just design a good and simple solution.任務 2（實現階段）：
Implement according to docs/subscription_design.md
Make sure all user journeys are properly covered by e2e tests and pass.示例 4：喺 Codex 入面追問 CodexPotter 嘅任務詳情
based on .codexpotter/projects/2026/03/18/1/MAIN.md,
please explain more about the root cause of the issue🔧 高級功能
--xmodel（實驗性）
使用雙模型交叉 Review：先用 gpt-5.2 執行，再用 gpt-5.4 對 gpt-5.2 嘅工作進行 Review。對清晰嘅編碼任務，可能產出比單一模型更好嘅結果。
codex-potter --yolo --xmodel/yolo 命令
喺交互介面中切換係咪默認為所有會話開啓 YOLO 模式（無沙箱）。
/list 或 Ctrl+L
睇曬所有項目（任務）同佢哋嘅執行結果歷史。
AGENTS.md / Skills / MCP 集成
CodexPotter 同 Codex 嘅 AGENTS.md、Skills、MCP（Model Context Protocol）完美兼容，喺項目根目錄放 AGENTS.md 就可以令 Codex 跟從你嘅工程規範。
知識庫（.codexpotter/kb/）
CodexPotter 會喺每次深度探索模塊之後，將關鍵事實同代碼位置寫入本地知識庫（.codexpotter/kb/xxx.md）並維護索引（README.md）。新嘅乾淨上下文會話開動之前會讀取知識庫，令 Codex 快啲上手項目背景。
🛠️ 常見問題與解決方案
Q1：運行時報錯 Missing optional dependency codex-potter-<platform>
原因：npm 安裝時冇正確拉取到當前平台對應嘅原生二進制包。
解決方案：重新安裝 CodexPotter，確保包管理器可以拉取到正確嘅平台包：
npm uninstall -g codex-potter
npm install -g codex-potterQ2：任務執行到一半停咗，冇完全完成
原因：網絡斷線、stream 中斷等間歇性網絡問題。
解決方案：CodexPotter 支援 Resume（歷史回放 + 繼續疊代），直接重新進入項目繼續執行就得。可以透過 /list 睇歷史任務並揀 Resume。
Q3：工具（tool）報錯導致 CLI 直接退出
原因：呢個係一個已知 Bug（issue #1[4]），某啲工具調用嘅錯誤會直接令 CLI 退出，而唔係優雅處理。
解決方案：目前可以重新開 CodexPotter 並 Resume 對應任務；等官方修復。
Q4：Codex 多輪執行之後輸出質量下降
原因：呢個唔係 CodexPotter 嘅問題——CodexPotter 嘅核心設計就係每輪用乾淨上下文，避免上下文累積搞到質量下降。如果仲有質量問題，請檢查知識庫（.codexpotter/kb/）係咪有過時嘅資訊，手動更新之後重新執行。
Q5：任務太大，Codex 冇辦法喺一輪內完成
解決方案：將大任務拆分做兩個 CodexPotter 任務（先規劃、再實現），並透過檔案傳遞中間產出（詳見示例 3）。如果連規劃都唔清楚，先用 Codex CLI 進行頭腦風暴，形成基本方案之後再交俾 CodexPotter 執行。
Q6：點樣喺唔影響項目 git 歷史嘅情況下使用 CodexPotter
CodexPotter 會將進度檔案、知識庫等保存喺 .codexpotter/ 目錄下，呢個目錄已經自動加入 .gitignore，唔會被提交到 git 歷史。每次編碼變更會由 Codex 以獨立 commit 提交，方便 review。
🗺️ Roadmap
🏗️ 本地開發
# 代碼格式化
cargo fmt
# Lint 檢查
cargo clippy
# 運行測試
cargo nextest run
# 構建
cargo build📎 相關連結
• 項目倉庫[5] • npm 包頁面[1] • OpenAI Codex CLI 文檔[2] • Ralph Wiggum 模式介紹[3] • 上游 openai/codex 倉庫[6] • LINUX DO 社區[7]
引用連結
[1] npm: codex-potter: https://www.npmjs.com/package/codex-potter[2] OpenAI Codex CLI: https://developers.openai.com/codex/quickstart?setup=cli[3] Ralph Wiggum 模式: https://ghuntley.com/ralph/[4] issue #1: https://github.com/breezewish/CodexPotter/issues/1[5] 項目倉庫: https://github.com/breezewish/CodexPotter[6] 上游 openai/codex 倉庫: https://github.com/openai/codex[7] LINUX DO 社區: https://linux.do
Ralph loop for codex — 持續將代碼庫向你指定的目標狀態對齊。
• 倉庫地址：https://github.com/breezewish/CodexPotter • License：Apache-2.0 • 發佈渠道：npm: codex-potter[1] • 支持平台：Linux（x86_64 / aarch64）、macOS（Apple Silicon / Intel）、Windows（x86_64 / ARM64）
📌 項目簡介
CodexPotter 是一個圍繞 OpenAI Codex CLI[2] 構建的自主循環執行器，它實現了 Ralph Wiggum 模式[3]——即持續地、多輪地將代碼庫"對齊"（reconcile）到你所指示的目標狀態，直到任務完全完成。
與直接使用 Codex CLI 進行對話不同，CodexPotter 的核心理念是：將任務交給它，讓它自主執行，而不是和它聊天。
🧩 解決了什麼問題
在使用 Codex 進行較大規模的編碼任務時，常見的痛點包括：
.codexpotter/kb/），跨會話積累項目知識 | |
⚙️ 工作原理
CodexPotter 的工作流可以用下圖來理解：
執行流程（內部 Prompt 機制）：
1. 你向 CodexPotter 提交一個任務 Prompt 2. CodexPotter 將任務寫入進度文件（ MAIN.md），狀態設為initial3. Codex 讀取進度文件，將任務拆解為子任務（ Todo），狀態變為open4. Codex 循環執行子任務： Todo → In Progress → Done，並在每輪完成後提交 git commit5. 所有 Todo完成後，Codex 進行嚴格 Review，識別遺漏或未對齊的地方，繼續補充Todo6. 直到 Review 確認完全對齊，任務結束
進度文件、知識庫等均保存在 .codexpotter/ 目錄下（已自動加入 .gitignore，不會被提交）。
🚀 快速上手
前置條件
確保本地已安裝並配置好 Codex CLI[2]（需要 OpenAI Codex 訂閲）。
安裝
# 使用 npm
npm install -g codex-potter
# 使用 bun
bun install -g codex-potter啓動
在你的項目目錄下運行：
# 推薦使用 --yolo 模式以實現完全自主執行（無沙箱）
codex-potter --yolo⚠️ 重要注意事項
• 每條 Prompt 都是獨立任務：與 Codex 不同，CodexPotter 中每個後續 Prompt 都會開啓一個新任務，不與上一個任務共享上下文。請將它當作任務分配工具，而非聊天工具。 • 不是 Codex 的替代品：CodexPotter 是循環執行器，Codex 負責實際編碼。兩者配合使用，效果最佳。
💡 使用場景
✅ 適合的場景
❌ 不適合的場景
📋 使用示例
示例 1：單任務執行
port upstream codex's /resume into this project, keep code aligned示例 2：輸出持久化（讓結果可在後續輪次中複用）
create a design doc for the new subscription system in DESIGN.md技巧：讓 Codex 將中間產出寫入文件（如
DESIGN.md），可以讓下一個任務直接引用，實現"先設計再實現"的工作流。
示例 3：先規劃後實現（兩階段工作流）
任務 1（規劃階段）：
Analyze the codebase, research and design a solution for introducing subscription system.
Output plan to docs/subscription_design.md.
Your solution should meet the following requirements: ...
Do not implement the plan, just design a good and simple solution.任務 2（實現階段）：
Implement according to docs/subscription_design.md
Make sure all user journeys are properly covered by e2e tests and pass.示例 4：在 Codex 中追問 CodexPotter 的任務詳情
based on .codexpotter/projects/2026/03/18/1/MAIN.md,
please explain more about the root cause of the issue🔧 高級功能
--xmodel（實驗性）
使用雙模型交叉 Review：先用 gpt-5.2 執行，再用 gpt-5.4 對 gpt-5.2 的工作進行 Review。對於清晰的編碼任務，可能產出比單一模型更好的結果。
codex-potter --yolo --xmodel/yolo 命令
在交互界面中切換是否默認為所有會話開啓 YOLO 模式（無沙箱）。
/list 或 Ctrl+L
查看所有項目（任務）及其執行結果歷史。
AGENTS.md / Skills / MCP 集成
CodexPotter 與 Codex 的 AGENTS.md、Skills、MCP（Model Context Protocol）無縫兼容，在項目根目錄放置 AGENTS.md 即可讓 Codex 遵循你的工程規範。
知識庫（.codexpotter/kb/）
CodexPotter 會在每次深度探索模塊後，將關鍵事實和代碼位置寫入本地知識庫（.codexpotter/kb/xxx.md）並維護索引（README.md）。新的乾淨上下文會話啓動前會讀取知識庫，讓 Codex 快速上手項目背景。
🛠️ 常見問題與解決方案
Q1：運行時報錯 Missing optional dependency codex-potter-<platform>
原因：npm 安裝時未能正確拉取當前平台對應的原生二進制包。
解決方案：重新安裝 CodexPotter，確保包管理器可以拉取到正確的平台包：
npm uninstall -g codex-potter
npm install -g codex-potterQ2：任務執行到一半停止了，沒有完全完成
原因：網絡斷連、stream 中斷等偶發網絡問題。
解決方案：CodexPotter 支持 Resume（歷史回放 + 繼續迭代），直接重新進入項目並繼續執行即可。可通過 /list 查看歷史任務並選擇 Resume。
Q3：工具（tool）報錯導致 CLI 直接退出
原因：這是一個已知 Bug（issue #1[4]），某些工具調用的錯誤會直接導致 CLI 退出，而非優雅處理。
解決方案：目前可重新啓動 CodexPotter 並 Resume 對應任務；等待官方修復。
Q4：Codex 在多輪執行後輸出質量下降
原因：這不是 CodexPotter 的問題——CodexPotter 的核心設計就是每輪使用乾淨上下文，避免上下文積累導致的質量退化。如果仍出現質量問題，請檢查知識庫（.codexpotter/kb/）是否包含過時的信息，手動更新後重新執行。
Q5：任務太大，Codex 無法在一輪內完成
解決方案：將大任務拆分為兩個 CodexPotter 任務（先規劃、再實現），並通過文件傳遞中間產出（詳見示例 3）。如果連規劃也不清楚，先用 Codex CLI 進行頭腦風暴，形成基本方案後再交給 CodexPotter 執行。
Q6：如何在不影響項目 git 歷史的情況下使用 CodexPotter
CodexPotter 會將進度文件、知識庫等保存在 .codexpotter/ 目錄下，該目錄已自動加入 .gitignore，不會被提交到 git 歷史中。每次編碼變更會由 Codex 以獨立 commit 提交，便於 review。
🗺️ Roadmap
🏗️ 本地開發
# 代碼格式化
cargo fmt
# Lint 檢查
cargo clippy
# 運行測試
cargo nextest run
# 構建
cargo build📎 相關連結
• 項目倉庫[5] • npm 包頁面[1] • OpenAI Codex CLI 文檔[2] • Ralph Wiggum 模式介紹[3] • 上游 openai/codex 倉庫[6] • LINUX DO 社區[7]
引用連結
[1] npm: codex-potter: https://www.npmjs.com/package/codex-potter[2] OpenAI Codex CLI: https://developers.openai.com/codex/quickstart?setup=cli[3] Ralph Wiggum 模式: https://ghuntley.com/ralph/[4] issue #1: https://github.com/breezewish/CodexPotter/issues/1[5] 項目倉庫: https://github.com/breezewish/CodexPotter[6] 上游 openai/codex 倉庫: https://github.com/openai/codex[7] LINUX DO 社區: https://linux.do