企业官网建设流程全解析

1. 为什么你的 Codex 总在“重新学一遍”

用 Codex 写代码，最消耗耐心的往往不是它写不出来，而是它每次都像第一次进这个仓库。你刚说完“依赖用 pnpm，别用 npm”，下一个新会话它又给你npm install；你刚强调过generated/目录不能手改，换个任务它又准备直接编辑生成文件；发布流程更典型，看 diff、核对测试、更新 CHANGELOG、生成发布说明，这一整套你几乎每次都要重新描述一遍。

问题不在于 Codex 不聪明，而在于你把不同寿命的信息全塞进了同一个地方——当前 Prompt。Prompt 是“这一次”的载体，它天然是短命的。你把长期规则、重复流程、外部数据入口都写进去，结果就是提示词越来越臃肿，新任务还要重新复制，真正只对当前需求有效的边界反而被埋在一堆长期规则里，模型抓不住重点。

Codex 其实提供了四种定制机制：Prompt、AGENTS.md、Skills、MCP。它们看起来都在“告诉 Agent 怎么工作”，但职责完全不同。先记住一句话：Prompt 交代这一次，AGENTS.md 约束这个仓库，Skill 固化一套流程，MCP 连接外部系统。它们是组合关系，不是四选一。

这篇会先讲清四种机制各自解决什么问题、适合放什么内容，再给出可直接复制的配置片段，然后用同一个“准备 v1.4.0 发布材料”的任务，演示四种方式如何配合。最后落到一个很多人忽略的工程细节：把 Codex 的auth.jsonendpoint 改到 TaoToken 统一 Key 通道，让多项目、多工具的 Key 管理不再散落各处。适合已经在用 Codex、但被重复交代背景折磨的开发者。

2. 四种机制怎么选：一张判断表 + 30 秒决策流程

在动手配置之前，先把“什么内容该放在哪里”想清楚，比急着写文件更重要。下面这张表是我实际用下来最省心的划分方式。

判断一条要求该放哪里，我习惯按这个顺序问自己四个问题：

只影响当前任务吗？写进 Prompt。每次进入这个仓库都要遵守吗？写进 AGENTS.md。它是一套会反复执行的多步流程吗？做成 Skill。它需要外部实时数据或外部操作吗？接入 MCP。

有些要求会同时命中两项。比如“每次发布都要更新 CHANGELOG”，可以在 AGENTS.md 里保留一句长期规则，再用 Skill 承载完整的发布流程；需要读取 GitHub PR 时，再让 Skill 调用 MCP 提供的工具。这种分层不是重复，而是各司其职。

这里有个容易踩的坑：把一次性需求写进 AGENTS.md。“这次只改登录页”“今天先别跑测试”都属于临时边界，写进项目规则后，下一次任务很可能忘记删除，反而干扰正常工作。反过来，把几十页操作手册塞进 AGENTS.md 也不对——项目说明应尽量短，重点保留会改变行为的命令、边界和验收要求，复杂流程交给 Skill，长篇背景放进正式文档，再给出明确的读取路径。

3. 可复制配置：AGENTS.md、SKILL.md 与 auth.json 三件套

这一节给三份可以直接抄的配置。先说明一点：无论用哪种机制，Codex 最终都要通过一个 endpoint 和 Key 去调用模型。把 endpoint 统一到 TaoToken，能让多项目、多工具的 Key 管理收敛到一处，后面切换模型或轮换 Key 都只改一个地方。

3.1 精简版 AGENTS.md

放在仓库根目录，Codex 开始工作前会读取。规则可以放在全局、仓库根目录和更靠近代码的子目录，从根目录到当前工作目录逐层组合，越靠近当前目录优先级越高。

# AGENTS.md ## Project - This is a TypeScript monorepo managed with pnpm workspaces. - Frontend code lives in `apps/web`; API code lives in `services/api`. ## Commands - Install dependencies with `pnpm install` from the repository root. - Run targeted tests for the package you changed. - Run `pnpm lint` and `pnpm typecheck` before finalizing code changes. ## Boundaries - Do not edit files under `generated/`; use `pnpm generate`. - Preserve unrelated user changes in the working tree. - Ask before adding production dependencies or changing public APIs. ## Handoff - Summarize what changed and why. - List the checks actually run and their results. - Call out anything that remains unverified.

注意它没有写业务背景，也没有写完整 API 文档。那些应该留在原来的文档里，只在 AGENTS.md 里告诉 Codex 去哪里读、什么时候必须读。

3.2 最小可用 SKILL.md

Skill 至少包含一个SKILL.md，还可以按需加入脚本、参考资料和模板。目录结构大概是这样：

release-docs/ ├── SKILL.md ├── references/ │ └── release-style.md ├── scripts/ │ └── collect-diff.sh └── assets/ └── release-template.md

SKILL.md的 frontmatter 至少要提供name和description，Codex 会先看元数据，任务匹配时再读取完整说明，需要时才继续读引用或跑脚本。这种渐进加载能避免一开始就把所有细节塞进上下文。

--- name: release-docs description: 根据已确认的代码变更生成 CHANGELOG、技术文档和发布说明。用于准备版本发布材料；不要在尚未确认变更范围时触发。 --- 1. 只读检查 Git 状态、目标 diff、相关测试和已有文档。 2. 建立事实清单，区分用户可见变化、内部重构和无法证实内容。 3. 输出文档影响范围，等待确认后再修改文件。 4. 分别起草 CHANGELOG、技术文档和发布说明，不混用三者的读者视角。 5. 运行仓库已有的文档检查，并列出未验证项。 6. 未经确认，不提交、不推送、不发布。

3.3 Codex auth.json 接入 TaoToken

Codex 的凭据配置在~/.codex/auth.json。把 endpoint 指向 TaoToken，Key 也换成 TaoToken 的 Key，就能统一管理。下面这份是结构示例，把OPENAI_API_KEY换成你在 TaoToken 控制台创建的 Key 即可：

{ "OPENAI_API_KEY": "sk-你的TaoTokenKey", "tokens": { "access_token": "sk-你的TaoTokenKey", "refresh_token": "" }, "base_url": "https://taotoken.net/api", "last_refresh": "2025-01-01T00:00:00Z" }

如果你用的是环境变量方式，也可以直接设置：

export OPENAI_BASE_URL="https://taotoken.net/api" export OPENAI_API_KEY="sk-你的TaoTokenKey"

三件套记牢：Base URL 用https://taotoken.net/api，Key 用 TaoToken 控制台生成的 Key，Model ID 按你实际调用的模型填。这三项在 Cline MCP、CC Switch、Codex auth.json 里都是同一套逻辑，配一次就能复用。Key 可以在控制台创建和管理，接入细节参考官方文档。

4. 验证请求：同一任务在四种方式下的复现效果

配置写完必须验证，否则你不知道 Codex 到底有没有读到。我用同一个任务“为 v1.4.0 准备发布材料”跑了一遍，观察四种机制各自的表现。

先验证 endpoint 是否生效。最直接的方式是发一个最小请求，确认返回正常：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}] }'

返回里能看到正常的choices结构，说明 Key 和 endpoint 都通了。如果这里就报错，先别往下走，去第 5 节对照排查。

接着看四种机制在任务里的分工。Prompt 负责定义本次发布目标：版本是 v1.4.0，比较 v1.3.2 到当前分支，先生成草稿不要发布。AGENTS.md 提供仓库固定规则：使用项目原有术语，用户行为变化必须同步 docs，完成后运行文档检查。Skill 执行稳定工作流：收集差异、建立事实清单、更新文档、生成发布说明、反向验收。MCP 补齐外部上下文：读取 GitHub PR、Issue、里程碑或团队文档中的已确认信息。

实测下来，如果只写 Prompt，Codex 能做，但每次都要把完整步骤重新贴一遍；加上 AGENTS.md 后，仓库规则不用再重复；做成 Skill 后，发布流程一句话就能触发；接入 MCP 后，PR 和 Issue 的信息能自动带进来，不用手动复制。区别不在于“能不能做”，而在于这套工作以后是否还要重复、是否需要稳定复现。

验证 Skill 是否被正确触发，可以故意用一个模糊描述，看它会不会误触发。如果 description 写得含糊，Codex 可能该用时没用，也可能在不合适的任务里触发。先让一个高频流程跑稳，比收集一堆“以后也许能用”的技能更有效。

5. 常见报错排查：401、local proxy failed 与 OAuth

配置过程中最容易卡在几个固定报错上，逐个对照。

401 Unauthorized：Key 无效或没带上。先确认auth.json里的 Key 和 TaoToken 控制台里的一致，注意别把sk-前缀漏掉。如果用的是环境变量，检查OPENAI_API_KEY有没有被其他 shell 配置覆盖。还有一种情况是 Key 被删除或过期，去控制台重新生成一个。

local proxy failed / connection refused：通常是 endpoint 写错或本地网络配置冲突。确认base_url是https://taotoken.net/api，不要多写或少写路径段。如果你本地有旧的代理环境变量残留，先清掉再试：

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

reading choices 报错 / 返回结构异常：多半是请求体格式不对，或者 Model ID 填错。检查model字段是不是你实际有权限调用的模型，messages是不是标准结构。用第 4 节的 curl 先跑通最小请求，再回到 Codex 里试。

OAuth 相关报错：Codex 某些版本会走 OAuth 刷新流程，如果refresh_token为空又触发了刷新，就会失败。用 TaoToken Key 直连时，把tokens.access_token也设成同一个 Key，refresh_token留空即可，避免它去走刷新逻辑。

排查顺序建议固定：先 curl 验证 Key 和 endpoint，再检查auth.json结构，最后看 Codex 版本是否对配置字段有特殊要求。三件套（Base URL、Key、Model ID）任何一项不对都会报错，逐项核对比盲目重装快得多。

6. 从 Prompt 到 MCP：按这个顺序搭建你的 Codex 工作流

不用一上来就同时配置四套机制，从真实的重复问题出发更稳。先把当前任务写清楚，目标、上下文、边界和验证方式足够明确，很多问题已经能解决。再记录重复出现的仓库规则，把反复提醒的命令和边界整理进一份精简的 AGENTS.md。等流程稳定后再做 Skill，先手工跑通两三次，确认输入、步骤、输出和验收，再固化成可复用工作流。缺外部能力时再接 MCP，只开放真正需要的工具，优先只读，涉及外部写入时保留确认。

这样做的好处是，每一层都在解决一个已经出现的问题，不会为了“配置完整”而制造新的维护成本。把 Key 通道统一到 TaoToken 之后，多项目切换、模型轮换、Key 轮换都只改一处，配合 AGENTS.md 和 Skill，Codex 才算真正“记住”了你的项目。

如果你现在就想动手，建议从两件事开始：把仓库里反复提醒的三条规则写进 AGENTS.md，再把auth.json的 endpoint 换成 TaoToken。跑通之后，你会明显感觉到新会话不再从零开始。需要创建 Key 或查看接入细节，可以从 API Keys 页面和控制台入手；想先验证模型是否正常，用模型对话跑一轮最快；如果打算长期做编码和 Agent 任务，Coding Plan 会更省心。