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.jsonWindows 在%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结尾不要带/v1Codex 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 8000temperature设 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 -DtestOrderServiceTest codex 有个测试失败了看下是什么问题 codex 原来是 Mock 没设置对修复下 codex /run mvn test -DtestOrderServiceTest -v结果是测试覆盖率从 0% 提到 95%生成 28 个测试用例还顺带发现了 3 个潜在 Bug。这里有个技巧让 Codex 生成测试时明确要求「Mock 所有外部依赖」否则它可能真的去连数据库测试跑不起来。3. 场景 4-6API 开发、数据库迁移与文档生成的配置要点3.1 场景 415 分钟开发一套 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 根据以下需求开发用户管理 APIGET /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:info10 分钟完成。这里有个细节多级回复通常用parent_id自关联Codex 默认会加ON DELETE CASCADE如果你的业务需要保留子评论要在第一轮明确说「删除父评论时子评论不级联删除」。3.3 场景 6项目文档一键生成需求是生成 README、API 文档、数据库字典、部署文档四份。第一轮codex 分析项目结构生成 README.md包含项目介绍、技术栈、快速开始、目录结构、开发指南、部署说明第二轮codex 扫描所有 Controller生成 Markdown 格式的 API 文档每个接口包含请求方法和路径、请求参数、响应格式、示例第三轮codex 连接数据库生成所有表的字段说明文档格式表名 | 字段名 | 类型 | 说明 | 约束第四轮整理输出codex /export docs/README.md20 分钟拿到四份文档。注意/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 validation5 分钟发现 2 个 Bug、1 个性能问题、1 个安全隐患、3 处代码风格问题。这里的关键是/git diff命令它让 Codex 直接读暂存区的差异比手动贴代码准确得多。4.2 场景 8慢查询接口优化GET /api/users?department技术部page1size20响应时间 3.2 秒。第一轮分析codex 这个接口响应太慢了GET /api/users?department技术部响应时间 3.2 秒。请分析可能的原因给出优化方案Codex 列出四个可能原因没有索引、N1 查询、查询了不必要字段、没有分页优化。建议检查 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:run20 分钟拿到可运行的项目访问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 解释这段代码开始逐步过渡到重构和自动化脚本。跑通一个场景剩下的就是复制粘贴改参数的事。
