1. 为什么单轮对话式 AI 编程总在“烂尾”如果你用常规 AI 编程工具处理过中大型任务大概率遇到过这三种情况任务执行不彻底单轮生成只覆盖核心逻辑边界条件、错误处理、单元测试全被忽略留下一个需要人工大量收尾的半成品上下文质量退化对话轮次一多历史讨论里的干扰信息不断稀释模型对工程规范的理解模型越聊越蠢注意力频繁切换你得不停 Review、追问、纠错根本没法抽身去思考架构。Codex Potter 就是冲着“烂尾”来的。它不和你聊天只负责干活直到把代码库对齐到你指定的目标状态。核心机制是 Ralph Loop把任务目标写进进度文件通过“自主拆解—执行—自动 Review—继续对齐”的闭环让任务在少人工干预的情况下走向完成。它适合谁适合手里有明确迁移、重构、补测试任务且项目已经用 Git 管起来的开发者。如果你只是想问个语法别用它成本不划算。我试过把一个上游项目的/resume功能迁移到当前仓库单轮对话工具给了个骨架就停了Codex Potter 则自己拆了 7 个子任务逐个执行并 Review最后还补了 e2e 测试。这篇文章就把这套流程拆开给你可复制的 AGENTS.md 模板、Ralph Loop 配置片段以及用 TaoToken 统一 Key/API 通道接入的完整步骤目标是让 Codex 稳定工作一整天。2. TaoToken 前置统一 Key 与 API 通道接入 Codex PotterCodex Potter 本身是循环执行器底层还是要调模型。它兼容 OpenAI Compatible API所以只要有一个稳定的 Base URL、API Key 和 Model ID就能跑起来。这里我用 TaoToken 作为统一通道原因是它把 Key 管理和 API 入口收在一处切换模型时不用改一堆环境变量。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新 Key复制出来。注意这个 Key 只显示一次丢了就重新建。然后确认你的 API Base URL 是https://taotoken.net/api不要带多余路径Codex Potter 会自己拼/v1/chat/completions。模型 ID 建议选当前文档里推荐的高性能编码模型比如claude-sonnet-4-5或gpt-5-codex这类具体以你账号里可用的为准。不要编造模型名填错会直接 404。接下来配置环境变量。Codex Potter 读取的是标准 OpenAI 变量所以你可以这样写export OPENAI_API_KEYsk-你的TaoTokenKey export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_MODELclaude-sonnet-4-5如果你用.env文件放在项目根目录Codex Potter 启动时会自动加载。注意.env要加进.gitignore别把 Key 提交上去。这里有个容易踩的坑有些人把 Base URL 写成https://taotoken.net/api/v1结果 Codex Potter 又拼一次/v1变成/api/v1/v1/chat/completions直接 404。正确写法就是https://taotoken.net/api不带/v1。另外如果你同时用 Claude Code 或 Cline可以把 TaoToken 的 Key 复用过去Base URL 和 Model ID 保持一致这样多个工具共享一个通道排查问题时只看一处日志。Coding Plan 适合长期跑 Agent 任务的场景按量或包月看你任务密度具体在 https://taotoken.net/coding-plan 看当前方案。配置完先别急着跑大任务用一条简单请求验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d { model: $OPENAI_MODEL, messages: [{role: user, content: reply with ok}] }返回里有choices[0].message.content就说明通道没问题。如果返回 401检查 Key 是否复制完整如果返回local proxy failed说明你的网络层有额外代理拦截把代理关掉再试。3. 可复制配置AGENTS.md 模板与 Ralph Loop 片段Codex Potter 在每一轮任务开始前会优先读取项目根目录的AGENTS.md。这个文件就是你给它的工程规范写得越具体它生成的代码越像你亲手写的。下面是我实测下来比较稳的模板你可以直接复制改# AGENTS.md ## 项目概览 - 语言TypeScript 5.xNode 20 - 包管理pnpm - 测试框架Vitest - 代码风格函数式优先禁止 class 继承除非必要 ## 目录约定 - src/ 源码 - tests/ 单元测试文件名 *.test.ts - docs/ 设计文档规划阶段输出到这里 ## 编码规范 - 变量命名用 camelCase常量用 UPPER_SNAKE_CASE - 每个导出函数必须有 JSDoc 注释说明参数和返回值 - 错误处理统一用 Result 类型不抛裸异常 - 禁止 any必要时用 unknown 加类型守卫 ## 任务执行约定 - 每个子任务完成后必须跑 pnpm test失败则修复后再继续 - 修改代码后自动 git add 并 commitcommit message 用 conventional commits - 遇到不确定的架构决策写入 docs/decisions.md 并暂停等待确认 ## 禁止事项 - 不修改 .env、package.json 的 scripts 字段 - 不删除已有测试用例只允许新增或修正 - 不引入新的运行时依赖除非在 docs/decisions.md 中说明理由这个文件放在项目根目录Codex Potter 每轮都会读。如果你用 Claude Code同样的AGENTS.md也能被识别这就是统一规范的好处。Ralph Loop 的配置在.codexpotter/config.toml核心是循环次数、Review 开关和模型分工[loop] max_iterations 50 review_each_task true resume_from_main true [model] executor claude-sonnet-4-5 reviewer gpt-5-codex xmodel true [context] clean_context true kb_dir .codexpotter/kb main_file .codexpotter/MAIN.md [safety] yolo false require_git_clean truemax_iterations控制最多循环多少轮50 轮足够跑一整天。review_each_task打开后每个子任务执行完会由 reviewer 模型检查一遍。xmodel true就是双模型交叉 Review执行和审核分开底层重构时特别有用。yolo false是安全默认值等你在独立分支上跑顺了再考虑打开。如果你用 Codex CLI 的auth.json路径通常在~/.codex/auth.json里面填{ OPENAI_API_KEY: sk-你的TaoTokenKey, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_MODEL: claude-sonnet-4-5 }三件套 Base URL、Key、Model ID 必须同时存在缺一个就会回退到默认配置然后报 401 或模型不存在。4. 验证请求让 Codex 持续跑一整天的实操步骤配置齐了先跑一个小任务验证闭环。在项目根目录执行codex-potter --task add a health check endpoint at /health returning {status:ok}, with a unit test启动后你会看到它在.codexpotter/下生成MAIN.md里面列出子任务创建路由、写 handler、写测试、跑测试、commit。每完成一个MAIN.md的状态就从 Todo 变成 Done。你可以随时cat .codexpotter/MAIN.md看进度。验证成功的结果有三个信号终端最后输出All tasks alignedgit log里多了几条 conventional commitpnpm test全绿。如果中途 CLI 崩了重新执行codex-potter --resume它会读MAIN.md从断点继续不会重头来。这就是进度持久化的价值。要让它跑一整天建议用tmux或screen挂后台tmux new -s potter codex-potter --task port upstream /resume feature, keep code aligned, cover with e2e tests --yolo # CtrlB 然后 D 脱离第二天回来tmux attach -t potter看结果。注意--yolo会自主执行删除、修改、跑脚本务必在干净 Git 分支上操作主分支别开。两阶段工作流也值得用。先规划codex-potter --task Analyze the codebase, design a subscription system, output plan to docs/subscription_design.md. Do not implement.再实现codex-potter --task Implement according to docs/subscription_design.md. Ensure all user journeys covered by e2e tests and pass.第二阶段会严格对照设计文档对齐不会跑偏。这套流程跑下来Codex 确实能持续工作一整天你只需要在关键决策点介入。5. 本篇常见错排查401、local proxy failed 与 reading choices跑 Codex Potter 时报错集中在几个地方。下面按真实报错对照排查。401 Unauthorized最常见。先确认OPENAI_API_KEY是否复制完整有没有多余空格。然后确认 Base URL 是https://taotoken.net/api不是带/v1的版本。如果还报 401去 https://taotoken.net/api-keys 重新生成一个 Key旧的可能被删了。注意环境变量优先级.env里的值会覆盖 shell export检查两处是否一致。local proxy failed这个报错说明请求没到 TaoToken被本地网络层拦了。检查你有没有设HTTP_PROXY或HTTPS_PROXY环境变量有就unset掉。Codex Potter 不需要额外代理直连即可。如果你在公司网络里确认防火墙放行了taotoken.net的 443 端口。reading choices 报错通常是响应体不是预期 JSON比如返回了 HTML 错误页。原因可能是 Base URL 拼错请求打到了网站首页而不是 API。确认 URL 是https://taotoken.net/api/v1/chat/completions路径别少/v1。另外模型 ID 填错也会导致返回错误结构检查OPENAI_MODEL是否是你账号里真实可用的。OAuth 相关报错如果你用 Claude Code 或 Codex CLI 的 OAuth 登录模式又同时设了OPENAI_API_KEY两者会冲突。解决办法是二选一用 TaoToken 的 Key 模式就把 OAuth 登出或者把 OAuth 配置清掉。Codex CLI 的auth.json里如果同时有 OAuth token 和 API Key优先走 OAuth导致 Key 不生效。CLI 直接退出社区反馈较多的一个情况通常是某个工具调用返回非预期错误。对策是用codex-potter --list查看历史任务选对应编号--resume它会从MAIN.md断点继续。如果MAIN.md损坏手动把未完成项改回 Todo 再 resume。输出质量下降模型开始胡言乱语时检查.codexpotter/kb/。如果知识库里存了过时的设计方案模型会被误导。手动清理或更新知识库文件然后重新 resume。这也是 clean context 机制的意义每轮只读MAIN.md和当前知识库不读历史聊天。排错时建议开一个终端专门tail -f .codexpotter/logs/*.log看请求和响应原文比猜快得多。6. 语义一致 CTA把通道和循环都固定下来整套流程跑通后你会发现关键就两件事通道稳定循环可控。通道这边TaoToken 把 Key、Base URL、Model ID 收在一处Codex Potter、Claude Code、Cline 共用同一套配置排查时只看一个入口。你可以在 https://taotoken.net/api-keys 管理 Key在 https://taotoken.net/doc 看接入文档模型对话调试用 https://taotoken.net/chat 长期跑 Agent 任务看 https://taotoken.net/coding-plan 。循环这边AGENTS.md定规范.codexpotter/config.toml定节奏MAIN.md定进度。三者固定下来Codex 就能稳定工作一整天。最后提醒一句--yolo只在独立 Git 分支开主分支永远保持require_git_clean true。跑之前git status确认干净跑完git log看 commit有问题直接git reset回滚。这套组合我跑了几周迁移和补测试的任务基本不用盯你按上面的配置走一遍就能复现。 
长河君 · 2026/10/17 21:22:29 · 阅读 1.2k 深度实战 Codex Potter：用 AGENTS.md 与 Ralph Loop 构建自主对齐的 AI 编程工作流，让 Codex 持续工作一整天
1. 为什么单轮对话式 AI 编程总在“烂尾”如果你用常规 AI 编程工具处理过中大型任务大概率遇到过这三种情况任务执行不彻底单轮生成只覆盖核心逻辑边界条件、错误处理、单元测试全被忽略留下一个需要人工大量收尾的半成品上下文质量退化对话轮次一多历史讨论里的干扰信息不断稀释模型对工程规范的理解模型越聊越蠢注意力频繁切换你得不停 Review、追问、纠错根本没法抽身去思考架构。Codex Potter 就是冲着“烂尾”来的。它不和你聊天只负责干活直到把代码库对齐到你指定的目标状态。核心机制是 Ralph Loop把任务目标写进进度文件通过“自主拆解—执行—自动 Review—继续对齐”的闭环让任务在少人工干预的情况下走向完成。它适合谁适合手里有明确迁移、重构、补测试任务且项目已经用 Git 管起来的开发者。如果你只是想问个语法别用它成本不划算。我试过把一个上游项目的/resume功能迁移到当前仓库单轮对话工具给了个骨架就停了Codex Potter 则自己拆了 7 个子任务逐个执行并 Review最后还补了 e2e 测试。这篇文章就把这套流程拆开给你可复制的 AGENTS.md 模板、Ralph Loop 配置片段以及用 TaoToken 统一 Key/API 通道接入的完整步骤目标是让 Codex 稳定工作一整天。2. TaoToken 前置统一 Key 与 API 通道接入 Codex PotterCodex Potter 本身是循环执行器底层还是要调模型。它兼容 OpenAI Compatible API所以只要有一个稳定的 Base URL、API Key 和 Model ID就能跑起来。这里我用 TaoToken 作为统一通道原因是它把 Key 管理和 API 入口收在一处切换模型时不用改一堆环境变量。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新 Key复制出来。注意这个 Key 只显示一次丢了就重新建。然后确认你的 API Base URL 是https://taotoken.net/api不要带多余路径Codex Potter 会自己拼/v1/chat/completions。模型 ID 建议选当前文档里推荐的高性能编码模型比如claude-sonnet-4-5或gpt-5-codex这类具体以你账号里可用的为准。不要编造模型名填错会直接 404。接下来配置环境变量。Codex Potter 读取的是标准 OpenAI 变量所以你可以这样写export OPENAI_API_KEYsk-你的TaoTokenKey export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_MODELclaude-sonnet-4-5如果你用.env文件放在项目根目录Codex Potter 启动时会自动加载。注意.env要加进.gitignore别把 Key 提交上去。这里有个容易踩的坑有些人把 Base URL 写成https://taotoken.net/api/v1结果 Codex Potter 又拼一次/v1变成/api/v1/v1/chat/completions直接 404。正确写法就是https://taotoken.net/api不带/v1。另外如果你同时用 Claude Code 或 Cline可以把 TaoToken 的 Key 复用过去Base URL 和 Model ID 保持一致这样多个工具共享一个通道排查问题时只看一处日志。Coding Plan 适合长期跑 Agent 任务的场景按量或包月看你任务密度具体在 https://taotoken.net/coding-plan 看当前方案。配置完先别急着跑大任务用一条简单请求验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d { model: $OPENAI_MODEL, messages: [{role: user, content: reply with ok}] }返回里有choices[0].message.content就说明通道没问题。如果返回 401检查 Key 是否复制完整如果返回local proxy failed说明你的网络层有额外代理拦截把代理关掉再试。3. 可复制配置AGENTS.md 模板与 Ralph Loop 片段Codex Potter 在每一轮任务开始前会优先读取项目根目录的AGENTS.md。这个文件就是你给它的工程规范写得越具体它生成的代码越像你亲手写的。下面是我实测下来比较稳的模板你可以直接复制改# AGENTS.md ## 项目概览 - 语言TypeScript 5.xNode 20 - 包管理pnpm - 测试框架Vitest - 代码风格函数式优先禁止 class 继承除非必要 ## 目录约定 - src/ 源码 - tests/ 单元测试文件名 *.test.ts - docs/ 设计文档规划阶段输出到这里 ## 编码规范 - 变量命名用 camelCase常量用 UPPER_SNAKE_CASE - 每个导出函数必须有 JSDoc 注释说明参数和返回值 - 错误处理统一用 Result 类型不抛裸异常 - 禁止 any必要时用 unknown 加类型守卫 ## 任务执行约定 - 每个子任务完成后必须跑 pnpm test失败则修复后再继续 - 修改代码后自动 git add 并 commitcommit message 用 conventional commits - 遇到不确定的架构决策写入 docs/decisions.md 并暂停等待确认 ## 禁止事项 - 不修改 .env、package.json 的 scripts 字段 - 不删除已有测试用例只允许新增或修正 - 不引入新的运行时依赖除非在 docs/decisions.md 中说明理由这个文件放在项目根目录Codex Potter 每轮都会读。如果你用 Claude Code同样的AGENTS.md也能被识别这就是统一规范的好处。Ralph Loop 的配置在.codexpotter/config.toml核心是循环次数、Review 开关和模型分工[loop] max_iterations 50 review_each_task true resume_from_main true [model] executor claude-sonnet-4-5 reviewer gpt-5-codex xmodel true [context] clean_context true kb_dir .codexpotter/kb main_file .codexpotter/MAIN.md [safety] yolo false require_git_clean truemax_iterations控制最多循环多少轮50 轮足够跑一整天。review_each_task打开后每个子任务执行完会由 reviewer 模型检查一遍。xmodel true就是双模型交叉 Review执行和审核分开底层重构时特别有用。yolo false是安全默认值等你在独立分支上跑顺了再考虑打开。如果你用 Codex CLI 的auth.json路径通常在~/.codex/auth.json里面填{ OPENAI_API_KEY: sk-你的TaoTokenKey, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_MODEL: claude-sonnet-4-5 }三件套 Base URL、Key、Model ID 必须同时存在缺一个就会回退到默认配置然后报 401 或模型不存在。4. 验证请求让 Codex 持续跑一整天的实操步骤配置齐了先跑一个小任务验证闭环。在项目根目录执行codex-potter --task add a health check endpoint at /health returning {status:ok}, with a unit test启动后你会看到它在.codexpotter/下生成MAIN.md里面列出子任务创建路由、写 handler、写测试、跑测试、commit。每完成一个MAIN.md的状态就从 Todo 变成 Done。你可以随时cat .codexpotter/MAIN.md看进度。验证成功的结果有三个信号终端最后输出All tasks alignedgit log里多了几条 conventional commitpnpm test全绿。如果中途 CLI 崩了重新执行codex-potter --resume它会读MAIN.md从断点继续不会重头来。这就是进度持久化的价值。要让它跑一整天建议用tmux或screen挂后台tmux new -s potter codex-potter --task port upstream /resume feature, keep code aligned, cover with e2e tests --yolo # CtrlB 然后 D 脱离第二天回来tmux attach -t potter看结果。注意--yolo会自主执行删除、修改、跑脚本务必在干净 Git 分支上操作主分支别开。两阶段工作流也值得用。先规划codex-potter --task Analyze the codebase, design a subscription system, output plan to docs/subscription_design.md. Do not implement.再实现codex-potter --task Implement according to docs/subscription_design.md. Ensure all user journeys covered by e2e tests and pass.第二阶段会严格对照设计文档对齐不会跑偏。这套流程跑下来Codex 确实能持续工作一整天你只需要在关键决策点介入。5. 本篇常见错排查401、local proxy failed 与 reading choices跑 Codex Potter 时报错集中在几个地方。下面按真实报错对照排查。401 Unauthorized最常见。先确认OPENAI_API_KEY是否复制完整有没有多余空格。然后确认 Base URL 是https://taotoken.net/api不是带/v1的版本。如果还报 401去 https://taotoken.net/api-keys 重新生成一个 Key旧的可能被删了。注意环境变量优先级.env里的值会覆盖 shell export检查两处是否一致。local proxy failed这个报错说明请求没到 TaoToken被本地网络层拦了。检查你有没有设HTTP_PROXY或HTTPS_PROXY环境变量有就unset掉。Codex Potter 不需要额外代理直连即可。如果你在公司网络里确认防火墙放行了taotoken.net的 443 端口。reading choices 报错通常是响应体不是预期 JSON比如返回了 HTML 错误页。原因可能是 Base URL 拼错请求打到了网站首页而不是 API。确认 URL 是https://taotoken.net/api/v1/chat/completions路径别少/v1。另外模型 ID 填错也会导致返回错误结构检查OPENAI_MODEL是否是你账号里真实可用的。OAuth 相关报错如果你用 Claude Code 或 Codex CLI 的 OAuth 登录模式又同时设了OPENAI_API_KEY两者会冲突。解决办法是二选一用 TaoToken 的 Key 模式就把 OAuth 登出或者把 OAuth 配置清掉。Codex CLI 的auth.json里如果同时有 OAuth token 和 API Key优先走 OAuth导致 Key 不生效。CLI 直接退出社区反馈较多的一个情况通常是某个工具调用返回非预期错误。对策是用codex-potter --list查看历史任务选对应编号--resume它会从MAIN.md断点继续。如果MAIN.md损坏手动把未完成项改回 Todo 再 resume。输出质量下降模型开始胡言乱语时检查.codexpotter/kb/。如果知识库里存了过时的设计方案模型会被误导。手动清理或更新知识库文件然后重新 resume。这也是 clean context 机制的意义每轮只读MAIN.md和当前知识库不读历史聊天。排错时建议开一个终端专门tail -f .codexpotter/logs/*.log看请求和响应原文比猜快得多。6. 语义一致 CTA把通道和循环都固定下来整套流程跑通后你会发现关键就两件事通道稳定循环可控。通道这边TaoToken 把 Key、Base URL、Model ID 收在一处Codex Potter、Claude Code、Cline 共用同一套配置排查时只看一个入口。你可以在 https://taotoken.net/api-keys 管理 Key在 https://taotoken.net/doc 看接入文档模型对话调试用 https://taotoken.net/chat 长期跑 Agent 任务看 https://taotoken.net/coding-plan 。循环这边AGENTS.md定规范.codexpotter/config.toml定节奏MAIN.md定进度。三者固定下来Codex 就能稳定工作一整天。最后提醒一句--yolo只在独立 Git 分支开主分支永远保持require_git_clean true。跑之前git status确认干净跑完git log看 commit有问题直接git reset回滚。这套组合我跑了几周迁移和补测试的任务基本不用盯你按上面的配置走一遍就能复现。