企业官网建设流程全解析

1. Codex CLI 在 TypeScript 项目里到底解决什么问题

Codex CLI 是 OpenAI 推出的命令行编码代理，它能在你的终端里读取仓库、修改文件、执行命令，把「描述需求 → 生成代码 → 跑测试 → 提交」串成一条流水线。GPT-5 的大统一方向，本质是把 Codex、Operator、Deep Research、Memory 这些能力收敛成一套统一的代理体系，而 Codex CLI 就是这套体系里最贴近日常编码的入口。它适合谁？适合每天在 TypeScript 项目里写业务、改 bug、补测试的开发者，尤其是那些仓库规模不小、单元测试覆盖尚可、希望把重复劳动交给代理的团队。

为什么 Codex CLI 本体用 TypeScript 写？AMA 里作者说得很直白：他最熟悉 TypeScript，而且 TypeScript 做终端 UI 体验好。这对我们普通开发者其实是个好消息——CLI 是开源的，配置格式、行为逻辑都能直接读源码确认，不用猜。短期路线图里还提到会提供高性能引擎并做多语言绑定，也就是说未来你在 Node、Python、Go 项目里都能用同一套代理逻辑，但当下最成熟的落地场景仍然是 TypeScript 仓库。

我实测下来，Codex 最擅长的组合是「大仓库 + 明确单元测试」。你给它一句「帮我造一个 App」，它大概率会给你一堆看起来对但跑不起来的代码；你给它「把src/utils/date.ts里的formatRange补上边界测试，跑pnpm test date通过后提交」，它成功率会高很多。这背后的逻辑是：任务拆得越小、验收标准越明确，代理的搜索空间就越窄，出错概率越低。

Ask → Code 的工作流值得单独说。Ask Mode 用来解析设计文档、拆任务、理清依赖关系，Code Mode 负责真正改代码。两者当前由用户显式切换，各跑独立容器。你可以先用 Ask Mode 把一份需求文档拆成 5 到 8 个可独立验证的子任务，再逐个丢给 Code Mode 执行。AMA 里提到 AGENTS.md 里写清楚测试命令、格式化命令、提交模板，能显著提升成功率——这一点我在多个仓库里验证过，确实是投入产出比最高的准备工作。

安全模型方面，代理拿到运行时后会断网，只用本地 repo 和预加载文件，保证输出可审计。CLI 已经支持--approval-mode full-auto，但仍在云端沙箱里跑。这意味着你可以放心让它执行测试和构建命令，不用担心它偷偷访问外部网络。对于企业内网项目，这个边界尤其重要。

2. 接入前的准备：TaoToken 与 Codex CLI 环境搭建

在讲具体配置之前，先把「模型从哪来」这件事说清楚。Codex CLI 本身是开源客户端，它需要一个兼容 OpenAI 接口的后端来提供模型能力。TaoToken 提供的就是这样一个统一入口，你可以在 https://taotoken.net/api 拿到兼容的 Base URL，然后用一把 Key 驱动 Codex CLI、Cline、Claude Code 等多个工具。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，需要看文档和套餐的话从那里进。

第一步，拿到 API Key。进入控制台 https://taotoken.net/console ，在 API Keys 页面创建一个新 Key。建议按项目或按工具分开建 Key，比如codex-ts-project一把、cline-local一把，这样后面排查用量和吊销都方便。创建后立刻复制保存，页面刷新后就看不到完整 Key 了。

第二步，确认 Node 环境。Codex CLI 是 npm 包，需要 Node 18 以上。在终端里跑：

node -v npm -v

如果版本低于 18，先用 nvm 或官方安装包升级。TypeScript 项目本身通常已经有 Node 环境，这一步一般不会卡住。

第三步，安装 Codex CLI。官方推荐全局安装：

npm install -g @openai/codex

安装完成后验证：

codex --version

能打印出版本号就说明 CLI 本体就绪。如果提示command not found，检查 npm 全局 bin 目录是否在 PATH 里，npm config get prefix可以看到全局安装路径。

第四步，准备项目侧的 AGENTS.md。这是 Codex 读取项目约定的核心文件，放在仓库根目录。一个最小可用的 TypeScript 项目 AGENTS.md 长这样：

# AGENTS.md ## 项目结构 - src/ 业务源码 - tests/ 单元测试，使用 vitest - scripts/ 构建与发布脚本 ## 常用命令 - 安装依赖：pnpm install - 跑全部测试：pnpm test - 跑单个测试文件：pnpm test <filename> - 类型检查：pnpm tsc --noEmit - 格式化：pnpm prettier --write . ## 提交规范 - 提交信息格式：<type>(<scope>): <subject> - 提交前必须通过 pnpm test 和 pnpm tsc --noEmit ## 编码约定 - 禁止使用 any，必要时用 unknown + 类型守卫 - 所有导出函数必须有 JSDoc - 异步函数统一用 async/await，不用回调

这份文件不需要写得多漂亮，关键是让代理知道「怎么跑测试、怎么算通过、提交信息长什么样」。AMA 里研发负责人专门强调过这一点，我自己的经验也是：AGENTS.md 写得越具体，Code Mode 一次通过率越高。

第五步，配置模型接入。Codex CLI 支持通过环境变量或配置文件指定 Base URL 和 Key。推荐用配置文件方式，路径在~/.codex/config.toml。下一节给出完整可复制片段。

3. 可复制的 Codex 配置片段与 TypeScript 项目接入步骤

这一节是全文最核心的部分，所有片段都可以直接复制。先给配置文件，再给项目侧接入步骤。

3.1~/.codex/config.toml完整配置

# Codex CLI 全局配置 # 路径：~/.codex/config.toml model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat" [profiles.default] model = "gpt-5-codex" model_provider = "taotoken" approval_mode = "on-request" [profiles.fullauto] model = "gpt-5-codex" model_provider = "taotoken" approval_mode = "full-auto"

这里有几个关键点。base_url用https://taotoken.net/api，不要加 UTM 参数，那是给网页链接用的。env_key指定从哪个环境变量读 Key，这样 Key 不会明文写在配置文件里。wire_api = "chat"表示走 Chat Completions 兼容协议，Codex CLI 和多数兼容后端都支持这个。

3.2 设置环境变量

在~/.zshrc或~/.bashrc里加一行：

export TAOTOKEN_API_KEY="sk-你的Key"

然后source ~/.zshrc生效。验证：

echo $TAOTOKEN_API_KEY

能打印出 Key 就对了。注意不要把 Key 提交到任何 Git 仓库，.env和 shell 配置文件都要在.gitignore里。

3.3 TypeScript 项目侧接入

进入你的 TypeScript 项目根目录，确认package.json里有测试和类型检查脚本：

{ "scripts": { "test": "vitest run", "test:watch": "vitest", "tsc": "tsc --noEmit", "lint": "eslint src --ext .ts", "format": "prettier --write ." } }

然后在项目根目录创建或更新AGENTS.md，内容参考上一节。接着在项目里启动 Codex：

cd your-ts-project codex

第一次启动会读取~/.codex/config.toml，用defaultprofile。你会看到一个交互式终端界面，可以输入自然语言指令。

3.4 用 Ask Mode 拆任务

假设你有一个需求文档docs/feature-user-export.md，描述要给用户列表加导出 CSV 功能。先在 Codex 里用 Ask Mode：

请阅读 docs/feature-user-export.md，把它拆成 5 个可独立验证的子任务， 每个子任务说明涉及哪些文件、验收命令是什么。不要改代码。

Codex 会返回一个任务列表，类似：

1. 在src/types/user.ts增加UserExportRow类型，验收：pnpm tsc
2. 在src/utils/csv.ts实现toCsv函数，验收：pnpm test csv
3. 在src/services/userExport.ts组装导出逻辑，验收：pnpm test userExport
4. 在src/api/routes/user.ts增加/export路由，验收：pnpm test routes
5. 补充集成测试tests/integration/export.test.ts，验收：pnpm test integration

3.5 用 Code Mode 逐个执行

切换到 Code Mode，把第一个子任务丢进去：

执行子任务 1：在 src/types/user.ts 增加 UserExportRow 类型， 字段包括 id、name、email、createdAt。完成后跑 pnpm tsc 确认通过。

Codex 会读取文件、生成 diff、执行命令。你可以在终端里看到它每一步的动作。确认无误后按提示接受修改。然后依次执行子任务 2 到 5。

3.6 用 full-auto 模式跑批量任务

当子任务之间依赖清晰、验收命令明确时，可以用 full-auto profile：

codex --profile fullauto

然后输入：

依次执行 AGENTS.md 里记录的子任务 2、3、4，每个任务完成后跑对应测试， 全部通过后按提交规范生成一条提交信息，不要自动提交。

full-auto 模式下 Codex 会自动执行命令，不再逐步询问。因为它在云端沙箱里跑，且代理运行时断网，所以风险可控。但第一次用建议还是先用on-request模式观察几轮，确认它的行为符合预期再放开。

4. 验证 Codex 补全与命令执行是否生效

配置写完不代表生效，必须做几个具体动作验证。这一节给出可复现的验证步骤，每一步都有预期结果。

4.1 验证模型连通性

在项目目录下跑：

codex exec "用一句话说明这个仓库是做什么的"

codex exec是非交互模式，适合脚本化验证。预期结果是 Codex 读取仓库文件后返回一句描述。如果返回 401，说明 Key 或环境变量有问题；如果返回local proxy failed，说明 Base URL 或网络配置有问题。这两个报错下一节详细讲。

4.2 验证文件读取与补全

在 Codex 交互界面里输入：

读取 src/utils/date.ts，告诉我 formatRange 函数的签名和它调用了哪些内部函数。

预期结果是 Codex 准确引用文件内容并列出函数名。如果它说「找不到文件」，检查你启动 Codex 的目录是不是项目根目录。

4.3 验证命令执行

输入：

跑 pnpm tsc --noEmit，把输出贴给我。

预期结果是 Codex 执行命令并返回真实的类型检查输出。如果项目本身有类型错误，它会原样贴出来；如果没有错误，它会说命令成功退出。这一步验证的是 Codex 有没有真正拿到运行时权限。

4.4 验证代码修改与测试闭环

找一个真实的小改动，比如给某个工具函数补一个边界测试：

在 tests/utils/date.test.ts 里给 formatRange 补一个跨月边界的测试用例， 然后跑 pnpm test date，确认通过。

预期结果是 Codex 生成测试代码、写入文件、执行测试、返回通过信息。如果测试失败，它会尝试修复并重跑。这个闭环跑通，说明你的 Codex 工作流已经可用。

4.5 验证 AGENTS.md 被读取

输入：

根据 AGENTS.md，这个项目的提交信息格式是什么？跑测试的命令是什么？

预期结果是 Codex 准确复述你写在 AGENTS.md 里的内容。如果它答不上来，说明 AGENTS.md 没被读取，检查文件是否在项目根目录、文件名大小写是否正确。

4.6 验证多文件任务

输入：

在 src/types/user.ts 增加 UserExportRow 类型，在 src/utils/csv.ts 增加 toCsv 函数， 两个文件都改完后跑 pnpm tsc。

预期结果是 Codex 同时修改两个文件并执行类型检查。这一步验证它能否处理跨文件任务，这是日常编码里最常见的场景。

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

这一节按真实报错逐个排查。每个报错给出触发场景、原因和修复动作。

5.1 401 Unauthorized

报错长这样：

Error: 401 Unauthorized {"error":{"message":"Invalid API key","type":"invalid_request_error"}}

原因通常是三种：Key 没设置、Key 设置错、Key 被吊销。排查顺序：

echo $TAOTOKEN_API_KEY

如果输出为空，说明环境变量没生效，检查~/.zshrc是否 source 过。如果输出有值但仍是 401，去控制台 https://taotoken.net/console 确认这把 Key 是否还在、是否被禁用。如果 Key 正确但仍 401，检查config.toml里env_key写的是不是TAOTOKEN_API_KEY，大小写要完全一致。

5.2 local proxy failed

报错长这样：

Error: local proxy failed: connect ECONNREFUSED 127.0.0.1:7890

这个报错说明系统里配置了本地代理，但代理没启动。Codex CLI 会读取HTTP_PROXY/HTTPS_PROXY环境变量。检查：

env | grep -i proxy

如果有输出，说明有代理配置。如果你不需要代理，直接 unset：

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

然后重新启动 Codex。如果你确实需要走某个网络配置，确保那个配置本身是通的。注意不要配置任何不合规的网络工具，企业环境请用公司统一的网络出口。

5.3 reading choices 相关报错

报错长这样：

Error: reading choices: unexpected end of JSON input

或者：

Error: reading choices: invalid character '<' looking for beginning of value

这个报错说明 Codex 收到了非 JSON 响应，通常是 Base URL 配错，请求打到了某个返回 HTML 的地址。检查config.toml里的base_url：

base_url = "https://taotoken.net/api"

注意结尾不要多斜杠，不要写成https://taotoken.net/api/v1/chat/completions，Codex 会自己拼路径。如果确认 URL 正确，用 curl 直接验证：

curl -s https://taotoken.net/api/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" | head -c 200

如果返回 JSON，说明后端正常；如果返回 HTML 或空，说明 URL 或 Key 有问题。

5.4 OAuth 相关报错

报错长这样：

Error: OAuth token expired, please re-authenticate

或者：

Error: failed to refresh OAuth token

Codex CLI 支持两种认证方式：API Key 和 OAuth。如果你用的是 API Key 方式，不应该出现 OAuth 报错。出现这个报错通常是因为之前登录过 ChatGPT 账号，本地缓存了过期的 OAuth token。清理缓存：

rm -rf ~/.codex/auth.json

然后重新启动 Codex，它会读取config.toml里的 API Key 配置。如果你确实想用 OAuth 方式，按 CLI 提示重新登录即可。两种方式不要混用，否则容易出现认证状态混乱。

5.5 模型 ID 不存在

报错长这样：

Error: model gpt-5-codex not found

检查config.toml里的model字段。不同后端支持的模型 ID 可能不同，去 https://taotoken.net/doc 确认当前可用的模型列表。如果gpt-5-codex不可用，换成文档里列出的等价模型 ID。

5.6 三件套对照表

出现任何接入问题时，先对照这张表检查三件套：

这三项任意一项错，都会导致请求失败。排查时先用 curl 验证 Base URL + Key，再验证 Model ID，逐项排除。

6. 把 Codex 工作流固定下来的几个实用动作

配置跑通之后，真正决定效率的是工作流本身。AMA 里提到的「拆小任务优于一句帮我造一个 App」，我自己的做法是把它固化成几个习惯动作。

第一个动作：每个需求先写一份docs/下的设计草稿，哪怕只有半页。Codex 的 Ask Mode 读这份草稿拆任务，比读你的口头描述准确得多。草稿里写清楚输入输出、边界条件、涉及模块，拆出来的子任务质量会高一个档次。

第二个动作：AGENTS.md 随项目演进持续更新。每次发现 Codex 在某个约定上犯错，就把那条约定补进 AGENTS.md。比如它总忘记给导出函数加 JSDoc，就在编码约定里写死。这份文件是活的，不是一次写完就扔。

第三个动作：用codex exec做 CI 里的自动化检查。比如在 PR 流水线里加一步，让 Codex 检查新增代码是否符合 AGENTS.md 里的约定，输出一份报告。这比纯 lint 更灵活，能覆盖 lint 管不到的语义约定。

第四个动作：full-auto 模式只在验收命令明确时用。子任务有清晰的测试命令、改动范围可控、不涉及敏感文件，才开 full-auto。涉及数据库迁移、生产配置、密钥文件的改动，一律用on-request模式逐步确认。

第五个动作：把常用 prompt 存成片段。比如「补边界测试」「重构这个函数降低圈复杂度」「给这个模块补 JSDoc」，每个片段配上固定的验收命令。下次直接调用，不用每次重新描述。

长期来看，GPT-5 的大统一方向会让 Codex、Operator、Memory 这些能力逐渐融合，代理能记住你项目的约定、跨会话保持上下文。但当下最务实的做法，还是把 Codex CLI 在 TypeScript 项目里的这套配置和工作流跑稳。配置片段在~/.codex/config.toml，项目约定在AGENTS.md，验证动作在第四节，排错对照在第五节。把这四块固定下来，你的 Codex 工作流就算真正落地了。需要看更多接入细节的话，接入文档在 https://taotoken.net/doc ，模型对话入口在 https://taotoken.net/chat ，长期编码和 Agent 场景可以看 Coding Plan https://taotoken.net/coding-plan 。