企业官网建设流程全解析

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 Potter

Codex 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_KEY="sk-你的TaoTokenKey" export OPENAI_BASE_URL="https://taotoken.net/api" export OPENAI_MODEL="claude-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.x，Node 20 - 包管理：pnpm - 测试框架：Vitest - 代码风格：函数式优先，禁止 class 继承，除非必要 ## 目录约定 - src/ 源码 - tests/ 单元测试，文件名 *.test.ts - docs/ 设计文档，规划阶段输出到这里 ## 编码规范 - 变量命名用 camelCase，常量用 UPPER_SNAKE_CASE - 每个导出函数必须有 JSDoc 注释，说明参数和返回值 - 错误处理统一用 Result 类型，不抛裸异常 - 禁止 any，必要时用 unknown 加类型守卫 ## 任务执行约定 - 每个子任务完成后必须跑 pnpm test，失败则修复后再继续 - 修改代码后自动 git add 并 commit，commit 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 = true

max_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 aligned；git log里多了几条 conventional commit；pnpm 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 # Ctrl+B 然后 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回滚。这套组合我跑了几周，迁移和补测试的任务基本不用盯，你按上面的配置走一遍就能复现。