企业官网建设流程全解析

1. 为什么你的 Codex CLI 总是卡在 auth.json 这一步

Codex CLI 是 OpenAI 推出的本地命令行编程助手，能直接在终端里读代码、改文件、跑测试、提交 Git，适合习惯命令行工作流的后端和全栈开发者。但很多人第一次装完之后，卡在登录环节：浏览器回调打不开、token 过期、auth.json路径找不到，最后只能放弃。我试过在三个不同项目里反复折腾这套配置，踩过的坑基本都集中在认证文件和 Base URL 这两处。

这篇不讲空泛概念，直接把 10 个真实开发场景拆开，每个场景都给你可复制的命令和验证动作。核心思路是：先把 Codex CLI 的auth.json指向 TaoToken 的兼容端点，让 CLI 能稳定拿到模型响应，然后再谈重构、修 Bug、写测试这些具体活。顺序反了，后面全是报错。

你需要准备的东西很少：Node.js 18+、一个能用的 API Key、以及下面这段配置。TaoToken 的 API 地址是https://taotoken.net/api，兼容 OpenAI 的请求格式，所以 Codex CLI 不需要改源码，只改配置文件即可。模型 ID 建议先用gpt-4o或claude-3-5-sonnet这类通用编码模型，等跑通后再换更贵的推理模型。

先确认你的 Codex CLI 版本，不同版本auth.json的字段名有差异：

codex --version # 输出示例：codex-cli 0.9.2

如果版本低于 0.8，建议先升级，否则下面的base_url字段可能不生效。升级命令：

npm install -g @openai/codex

装完之后不要急着codex login，因为默认登录会走 OpenAI 官方端点，在国内网络环境下大概率超时。正确做法是手动创建auth.json，把端点和 Key 写死。文件位置分两种：macOS/Linux 在~/.codex/auth.json，Windows 在%USERPROFILE%\.codex\auth.json。如果目录不存在，手动建一个：

mkdir -p ~/.codex touch ~/.codex/auth.json

接下来就是这篇最关键的一步。很多人以为只要填个 API Key 就行，其实 Codex CLI 读的是OPENAI_API_KEY和OPENAI_BASE_URL两个字段的组合。只填 Key 不填 Base URL，请求还是会打到官方端点，然后报 401 或超时。下面这段 JSON 可以直接复制，把sk-开头的部分换成你在 TaoToken 控制台生成的 Key：

{ "OPENAI_API_KEY": "sk-你的TaoToken密钥", "OPENAI_BASE_URL": "https://taotoken.net/api", "model": "gpt-4o", "provider": "openai" }

注意OPENAI_BASE_URL结尾不要带/v1，Codex CLI 内部会自己拼/v1/chat/completions。如果你多写了/v1，请求路径会变成/v1/v1/chat/completions，直接 404。这个坑我在第一次配置时踩了整整半小时，日志里只显示unexpected status 404，根本看不出是路径重复。

保存之后，用一条最简单的命令验证配置是否生效：

codex "用一句话解释什么是闭包"

如果终端能正常返回中文解释，说明认证和端点都通了。如果报401 Unauthorized，检查 Key 是否复制完整；如果报local proxy failed或connection refused，检查 Base URL 是否写错；如果报reading choices相关错误，说明返回体格式不对，大概率是模型 ID 写错了。

验证通过后，建议把模型 ID 也固定下来，避免每次对话都手动指定。在auth.json同级目录建一个config.toml：

[model] default = "gpt-4o" temperature = 0.2 [history] max_tokens = 8000

temperature设 0.2 是为了让代码生成更稳定，减少胡编乱造。max_tokens控制上下文长度，设太大容易触发限流，设太小又记不住项目结构，8000 是个比较平衡的值。

到这里前置配置就完成了。下面进入 10 个真实场景，每个场景我都会给出目标、原始状态、Codex CLI 对话过程、以及验证结果。你可以按顺序跟做，也可以挑自己最需要的场景直接跳过去。

2. 场景 1-3：代码重构、Bug 修复与单元测试的 Codex CLI 实操

2.1 场景 1：把 500 行上帝类拆成 5 个单一职责类

目标很明确：一个UserService.java承担了用户 CRUD、订单处理、支付逻辑、通知发送、报表生成五件事，总共 500 行。传统做法是手动读一遍再拆，至少半天。用 Codex CLI 可以分三轮对话完成。

第一轮先让它分析，不要直接让它改。直接改的风险是它可能漏掉依赖注入或者破坏原有调用链。命令如下：

codex "分析 src/main/java/com/example/service/UserService.java 的代码结构，列出它承担了哪些职责，应该如何拆分，先不要修改文件"

Codex 会输出类似这样的分析：用户管理约 150 行、订单处理约 120 行、支付逻辑约 100 行、通知发送约 80 行、报表生成约 50 行，建议拆成UserService、OrderService、PaymentService、NotificationService、ReportService五个类。

第二轮再让它执行拆分，关键是加一句「保持原有功能不变，每个类添加必要的依赖注入」：

codex "按照上面的建议拆分，保持原有功能不变，每个类添加必要的依赖注入，拆分后运行 mvn test 确保没有破坏"

第三轮验证并提交：

codex "/run mvn test" codex "/git add ." codex "/git commit -m 'refactor: split UserService into 5 single-responsibility services'"

实测下来，500 行拆成 5 个类，平均每个 100 行左右，测试覆盖率不变，所有测试通过。整个过程大约 12 分钟，其中大部分时间花在等mvn test跑完。

2.2 场景 2：修复间歇性 NullPointerException

错误信息很典型：

java.lang.NullPointerException: Cannot invoke "String.length()" because "username" is null at com.example.service.UserService.validateUsername(UserService.java:45) at com.example.controller.UserController.createUser(UserController.java:32)

第一轮把错误信息原样贴给 Codex，让它定位：

codex "有个 NPE 错误：Cannot invoke \"String.length()\" because \"username\" is null，位置在 UserService.java:45。请找到这个方法，分析为什么会空指针，给出修复方案"

第二轮让它读上游调用链：

codex "/read src/main/java/com/example/service/UserService.java" codex "为什么会是 null？上游调用链是什么？"

Codex 的分析是：validateUsername()第 45 行调用username.length()，username来自UserDTO.getUsername()，前端可能发送了{"username": null}，而 Controller 没有做空值校验。修复方案有三条：给UserDTO.username加@NotNull、在validateUsername()里加空值检查、Controller 加@Valid。

第三轮执行修复并补测试：

codex "按照方案修复，并添加单元测试覆盖这个边界情况" codex "/run mvn test"

第四轮手动验证边界：

codex "/run curl -X POST http://localhost:8080/api/users -d '{\"username\": null}'"

从定位到验证总共 8 分钟，传统方式至少 30 分钟。这里的关键是「先分析后动手」，如果第一轮就让它改，它很可能只加一个if (username == null) return;，治标不治本。

2.3 场景 3：给没有测试的 Service 补单元测试

OrderService有两个公开方法createOrder和cancelOrder，完全没有测试。第一轮生成测试框架：

codex "为 src/main/java/com/example/service/OrderService.java 编写单元测试，要求：使用 JUnit 5 + Mockito，覆盖所有公开方法，测试正常流程和异常流程，测试边界条件，Mock 所有外部依赖"

第二轮补充边界用例：

codex "还需要测试以下场景：产品列表为空、用户余额不足、订单已发货不能取消、退款金额计算正确"

第三轮运行并修复：

codex "/run mvn test -Dtest=OrderServiceTest" codex "有个测试失败了，看下是什么问题" codex "原来是 Mock 没设置对，修复下" codex "/run mvn test -Dtest=OrderServiceTest -v"

结果是测试覆盖率从 0% 提到 95%，生成 28 个测试用例，还顺带发现了 3 个潜在 Bug。这里有个技巧：让 Codex 生成测试时，明确要求「Mock 所有外部依赖」，否则它可能真的去连数据库，测试跑不起来。

3. 场景 4-6：API 开发、数据库迁移与文档生成的配置要点

3.1 场景 4：15 分钟开发一套 RESTful API

需求是五个接口：GET /api/users分页列表、GET /api/users/{id}单个用户、POST /api/users创建、PUT /api/users/{id}更新、DELETE /api/users/{id}删除。技术栈 Spring Boot 3.3 + MyBatis-Plus + MySQL。

第一轮生成基础代码：

codex "根据以下需求开发用户管理 API：GET /api/users 分页列表、GET /api/users/{id} 单个用户、POST /api/users 创建、PUT /api/users/{id} 更新、DELETE /api/users/{id} 删除。技术栈 Spring Boot 3.3 + MyBatis-Plus，数据库 MySQL，遵循项目现有编码规范"

第二轮加参数验证：

codex "添加参数验证：username 2-50 字符且不能重复，email 必须是有效邮箱，password 至少 8 位且包含大小写和数字"

第三轮加全局异常处理：

codex "添加全局异常处理：用户不存在返回 404，参数验证失败返回 400，重复创建返回 409，统一返回 ApiResponse 格式"

第四轮生成文档：

codex "生成 API 文档，包含请求和响应示例"

15 分钟拿到五个接口、完整参数验证、统一异常处理、自动生成的 API 文档。传统方式至少 2 小时。这里要注意，Codex 生成的 MyBatis-Plus 代码默认用LambdaQueryWrapper，如果你的项目用的是 XML 映射，需要在第一轮就说明，否则它会按自己的习惯写。

3.2 场景 5：数据库迁移脚本与回滚脚本

新增评论功能，需要建comments表、加外键、建索引、生成 Flyway 迁移脚本和回滚脚本。第一轮设计表结构：

codex "设计评论功能的数据库表，需求：支持多级回复、支持点赞、支持软删除、记录创建和更新时间。请给出表结构设计，包括字段、类型、索引"

第二轮生成迁移脚本：

codex "根据设计生成 Flyway 迁移脚本，文件名 V2026_05_26_001__create_comments_table.sql"

第三轮生成回滚脚本：

codex "生成对应的回滚脚本"

第四轮运行迁移：

codex "/run mvn flyway:migrate" codex "/run mvn flyway:info"

10 分钟完成。这里有个细节：多级回复通常用parent_id自关联，Codex 默认会加ON DELETE CASCADE，如果你的业务需要保留子评论，要在第一轮明确说「删除父评论时子评论不级联删除」。

3.3 场景 6：项目文档一键生成

需求是生成 README、API 文档、数据库字典、部署文档四份。第一轮：

codex "分析项目结构，生成 README.md，包含项目介绍、技术栈、快速开始、目录结构、开发指南、部署说明"

第二轮：

codex "扫描所有 Controller，生成 Markdown 格式的 API 文档，每个接口包含请求方法和路径、请求参数、响应格式、示例"

第三轮：

codex "连接数据库，生成所有表的字段说明文档，格式：表名 | 字段名 | 类型 | 说明 | 约束"

第四轮整理输出：

codex "/export docs/README.md"

20 分钟拿到四份文档。注意/export命令需要 Codex CLI 0.9 以上版本，低版本用codex "将上述内容写入 docs/README.md"代替。

4. 场景 7-10：代码审查、性能优化、Git 操作与项目初始化

4.1 场景 7：提交前的代码审查

修改了两个文件，git status显示UserService.java和UserController.java有改动。第一轮：

codex "/git diff" codex "请审查这些修改，找出潜在的 bug、性能问题、安全隐患、代码风格问题、命名是否规范"

第二轮修复：

codex "第 3 个问题说缺少空值检查，请帮我修复"

第三轮再审：

codex "/git diff" codex "还有其他问题吗？"

第四轮提交：

codex "/git add ." codex "/git commit -m 'feat: add user validation'"

5 分钟发现 2 个 Bug、1 个性能问题、1 个安全隐患、3 处代码风格问题。这里的关键是/git diff命令，它让 Codex 直接读暂存区的差异，比手动贴代码准确得多。

4.2 场景 8：慢查询接口优化

GET /api/users?department=技术部&page=1&size=20响应时间 3.2 秒。第一轮分析：

codex "这个接口响应太慢了：GET /api/users?department=技术部，响应时间 3.2 秒。请分析可能的原因，给出优化方案"

Codex 列出四个可能原因：没有索引、N+1 查询、查询了不必要字段、没有分页优化。建议检查 SQL 执行计划、加department索引、用覆盖索引、优化查询语句。

第二轮执行：

codex "按照建议优化：添加索引、优化查询、添加缓存"

第三轮验证：

codex "/run curl -w \"\\n%{time_total}\\n\" http://localhost:8080/api/users?department=技术部"

响应时间从 3.2 秒降到 0.05 秒，提升 64 倍。这里要注意，加缓存前先确认业务能接受脏读，否则还是老老实实加索引。

4.3 场景 9：整理 Git 提交历史

当前分支有 10 个提交，信息混乱，需要整理成 3 个有意义的提交。第一轮：

codex "/git log --oneline -10" codex "帮我整理这些提交：合并相关的提交、重写提交信息、保持功能完整性"

第二轮交互式变基：

codex "执行交互式变基，将 10 个提交整理为 3 个有意义的提交"

第三轮验证：

codex "/git log --oneline -5" codex "看起来不错，推送到远程"

10 个提交变成 3 个，历史整洁。注意变基会改写提交哈希，如果分支已经推送到远程且有人协作，先确认没有其他人基于旧提交工作。

4.4 场景 10：从零初始化 Spring Boot 项目

需求：电商订单服务，Spring Boot 3.3 + Java 21 + MySQL + Redis + RabbitMQ + Swagger。第一轮：

codex "创建一个新的 Spring Boot 项目，项目名 order-service，技术栈 Spring Boot 3.3 + Java 21 + MySQL + Redis + RabbitMQ，功能包括订单 CRUD、订单状态管理、支付集成、消息队列。请生成完整的项目结构和基础代码"

第二轮加配置：

codex "添加配置文件：application.yml 多环境、数据库配置、Redis 配置、RabbitMQ 配置、Swagger 配置"

第三轮生成基础代码：

codex "生成基础代码：实体类、Repository、Service、Controller、配置类"

第四轮验证：

codex "/run mvn clean package -DskipTests" codex "/run mvn spring-boot:run"

20 分钟拿到可运行的项目，访问http://localhost:8080/swagger-ui.html验证。这里有个坑：Codex 生成的application.yml默认用localhost连 MySQL，如果你的数据库在 Docker 里，要手动改成容器名或宿主机 IP。

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

配置 Codex CLI 时最容易遇到的四类报错，我按出现频率排个序，每个都给出真实日志和解决动作。

第一类：401 Unauthorized。日志长这样：

error: unexpected status 401 Unauthorized body: {"error":{"message":"Invalid API key","type":"invalid_request_error"}}

原因通常是 Key 复制不完整、Key 已过期、或者auth.json里字段名写错。检查三件事：OPENAI_API_KEY是否以sk-开头且没有多余空格；Key 是否在 TaoToken 控制台被禁用；auth.json的 JSON 格式是否合法（用cat ~/.codex/auth.json | python -m json.tool验证）。如果都正常，重新生成一个 Key 再试。

第二类：local proxy failed或connection refused。日志：

error: local proxy failed: Post "http://127.0.0.1:8080/v1/chat/completions": dial tcp 127.0.0.1:8080: connect: connection refused

这说明 Codex CLI 还在往本地代理发请求，OPENAI_BASE_URL没生效。检查auth.json里是否真的写了"OPENAI_BASE_URL": "https://taotoken.net/api"，注意不要带/v1。另外确认没有设置HTTP_PROXY或HTTPS_PROXY环境变量，这些会覆盖配置文件。用env | grep -i proxy检查，有的话unset掉。

第三类：reading choices相关错误。日志：

error: failed to parse response: reading choices: unexpected end of JSON input

这是返回体格式不对，通常是模型 ID 写错了。Codex CLI 期望 OpenAI 格式的choices数组，如果模型 ID 不存在，服务端可能返回错误对象而不是正常响应。检查auth.json里的model字段，先用gpt-4o这种确定存在的模型。如果还报错，用curl直接测端点：

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

如果curl能返回正常 JSON，说明是 Codex CLI 配置问题；如果curl也报错，说明 Key 或模型 ID 有问题。

第四类：OAuth 相关报错。日志：

error: OAuth flow failed: context deadline exceeded

这是因为你执行了codex login，走了官方 OAuth 流程。用auth.json手动配置的方案不需要登录，直接删掉~/.codex/下的 token 缓存文件，重新用auth.json启动即可。具体是删除~/.codex/tokens.json（如果存在），然后确认auth.json内容正确。

排查顺序建议：先curl测端点，再检查auth.json格式，最后看环境变量。三步走完，90% 的报错都能定位。

6. 把 Codex CLI 接进日常开发流的三个实用建议

第一个建议：给每个项目单独建AGENTS.md。Codex CLI 会读项目根目录的AGENTS.md作为上下文，你可以在里面写清楚项目技术栈、编码规范、常用命令。比如：

# 项目说明 - 技术栈：Spring Boot 3.3 + MyBatis-Plus + MySQL 8 - 测试命令：mvn test - 代码风格：阿里巴巴 Java 开发手册 - 禁止事项：不要修改 src/main/resources/application-prod.yml

这样每次对话不用重复交代背景，Codex 生成的代码也更贴合项目习惯。

第二个建议：复杂任务拆成「分析-执行-验证」三步，不要一句话让它全干完。前面 10 个场景里，每个都是先分析再动手。一次性给太多任务，Codex 容易混乱，生成的代码质量反而下降。你可以把这三步写成固定话术，比如「先分析不要改」「按方案执行」「运行测试验证」。

第三个建议：重要操作前先建分支或提交检查点。Codex 改代码很快，但偶尔会改错。在让它重构之前，先git checkout -b refactor/xxx或者git commit -m "checkpoint"，出问题直接回滚，成本最低。

如果你还没配好 Key，去 TaoToken 控制台生成一个，然后按第 1 节的auth.json片段填进去。配好之后，从最简单的codex "解释这段代码"开始，逐步过渡到重构和自动化脚本。跑通一个场景，剩下的就是复制粘贴改参数的事。