从零到一：用 OpenAI Codex CLI 实战开发一个微服务网关

引言

做后端开发八年，用过的 AI 编程工具从 Tabnine 到 GitHub Copilot，再到各种大模型，有一个问题始终没解决——它们只会“给代码”，不会“干活”。

直到 2025 年 OpenAI 推出新版 Codex，情况才真正发生变化。它不是在你编辑器里补全几行代码，而是在云端沙箱里替你完成一整套开发闭环：读代码、改代码、跑测试、看报错、再改代码，直到任务完成。Codex 的重点不是“回答”，而是“执行”——你把任务交给它，它可以读取你的项目文件，理解目录结构，修改代码，运行命令和测试，再把改动结果交给你检查。

本文将通过一个完整的实战案例——用 Codex CLI 开发一个轻量级微服务网关——带你从零掌握 Codex 的核心用法。全程代码可跑、命令可复现，不灌水。

---

一、Codex CLI 是什么

很多人会把 Codex 理解成“更会写代码的 ChatGPT”。这个理解不算错，但远远不够。

ChatGPT 更像一个顾问——你问它“这个函数怎么写”，它给你代码片段。接下来怎么把代码放进项目、怎么改文件、怎么跑测试，通常还要你自己完成。Codex 则不同：你把任务交给它，它能读项目文件、理解目录结构、修改代码、运行命令、跑测试、查报错，形成一个从理解到修改再到验证的完整工作闭环。

Codex CLI 是 Codex 的终端入口，完全开源，使用 Rust 编写以保证执行速度。截至 2026 年已发布 640 个版本，GitHub 上超过 83,200 星。它支持三种审批模式、多袋里协作、图像输入（截图转代码）和 Web 搜索，还可以通过 codex exec 子命令以非交互方式运行，天然适配 CI/CD 流水线。

---

二、环境准备

2.1 系统要求

macOS、Linux 或 Windows 11（Windows 推荐使用 WSL2）Node.js 22 （硬性要求）

2.2 安装 Codex CLI

方式一：npm（推荐）

代码语言：ja vascript

复制

npm install -g @openai/codex

安装完成后验证：

代码语言：ja vascript

复制

codex --version

方式二：Homebrew（macOS）

代码语言：ja vascript

复制

brew install --cask codex

方式三：二进制下载

从 GitHub Releases 下载对应平台的压缩包，解压后重命名为 codex，放到 PATH 目录下。

2.3 认证

首次运行 Codex 需要认证：

代码语言：ja vascript

复制

codex login

浏览器会打开 OpenAI 的授权页面，登录后即可使用。

---

三、实战项目：微服务网关

3.1 项目背景

我们要开发一个轻量级微服务网关，具备以下核心功能：

路由转发：根据请求路径将请求转发到对应的后端服务限流：基于令牌桶算法对每个服务做 QPS 限流健康检查：定期探测后端服务健康状态，自动摘除不健康节点日志记录：记录每个请求的耗时和状态码

技术栈：Go Gin Redis（Go 适合网关类场景，性能好、并发高）

3.2 初始化项目

创建一个新目录并初始化 Go module：

代码语言：ja vascript

复制

mkdir gateway && cd gatewaygo mod init github.com/yourname/gateway

3.3 第一次对话：让 Codex 理解项目

启动 Codex：

代码语言：ja vascript

复制

codex

Codex 会进入交互式会话，读取当前目录的项目结构。先让它理解项目现状：

代码语言：ja vascript

复制

请阅读当前项目，告诉我这是一个什么项目，目录结构如何，以及还缺少什么。

Codex 会分析 go.mod 文件，识别出这是一个 Go 项目，并给出目录结构建议。

3.4 核心开发：让 Codex 完成网关主体

接下来，我们让 Codex 完成网关的核心代码。关键在于把需求拆解成清晰的子任务，而不是一次性丢一个模糊的需求。

任务一：实现路由转发

代码语言：ja vascript

复制

请实现一个 HTTP 网关的核心路由转发功能。要求：1. 使用 Gin 框架2. 从配置文件读取路由规则（格式：路径前缀 -> 后端服务地址）3. 支持路径通配符，如 /api/v1/* -> http://user-service:80804. 转发时保留原始请求的 Header 和 Body5. 后端返回的响应原样返回给客户端6. 超时时间设为 30 秒

Codex 会生成类似这样的代码（实际生成的文件会被 Codex 直接写入项目）：

代码语言：ja vascript

复制

// main.gopackage mainimport ("bytes""io""net/http""net/http/httputil""net/url""time""github.com/gin-gonic/gin""gopkg.in/yaml.v3""os")type RouteConfig struct {Routes []Route `yaml:"routes"`}type Route struct {Prefix string `yaml:"prefix"`Target string `yaml:"target"`}var routes map[string]*httputil.ReverseProxyfunc loadConfig(path string) (*RouteConfig, error) {data, err := os.ReadFile(path)if err != nil {return nil, err}var config RouteConfigif err := yaml.Unmarshal(data, &config); err != nil {return nil, err}return &config, nil}func initProxies(config *RouteConfig) {routes = make(map[string]*httputil.ReverseProxy)for _, route := range config.Routes {targetURL, _ := url.Parse(route.Target)proxy := httputil.NewSingleHostReverseProxy(targetURL)proxy.Transport = &http.Transport{MaxIdleConns:100,IdleConnTimeout: 90 * time.Second,TLSHandshakeTimeout: 10 * time.Second,}routes[route.Prefix] = proxy}}func main() {r := gin.Default()config, err := loadConfig("config.yaml")if err != nil {panic(err)}initProxies(config)// 路由转发中间件r.Any("/*path", func(c *gin.Context) {path := c.Request.URL.Pathfor prefix, proxy := range routes {if len(path) >= len(prefix) && path[:len(prefix)] == prefix {proxy.ServeHTTP(c.Writer, c.Request)return}}c.JSON(http.StatusNotFound, gin.H{"error": "no route matched"})})r.Run(":8080")}

同时生成配置文件 config.yaml：

代码语言：ja vascript

将上述配置复制后，我们可以在沙箱环境中对 Codex 生成的代码进行验证：

text

代码语言：ja vascript

复制

请运行 go build，如果有编译错误请自动修复。

Codex 会执行 go build，如果缺少依赖会自动 go mod tidy，直到编译通过。

任务二：实现限流

代码语言：ja vascript

复制

在现有网关基础上增加限流功能。要求：1. 基于令牌桶算法，每个路由独立限流2. 限流配置写在 config.yaml 中，格式：每个路由的 QPS 上限3. 被限流的请求返回 429 Too Many Requests4. 使用 Redis 做分布式限流（假设 Redis 地址为 localhost:6379）5. 限流逻辑作为 Gin 中间件，在路由转发之前执行

Codex 会生成限流中间件代码：

代码语言：ja vascript

复制

// ratelimit.gopackage mainimport ("context""fmt""time""github.com/gin-gonic/gin""github.com/redis/go-redis/v9")type RateLimitConfig struct {Limits map[string]int `yaml:"limits"`}var rdb *redis.Clientfunc initRedis() {rdb = redis.NewClient(&redis.Options{Addr: "localhost:6379",})}func RateLimitMiddleware(limits map[string]int) gin.HandlerFunc {return func(c *gin.Context) {path := c.Request.URL.Pathfor prefix, qps := range limits {if len(path) >= len(prefix) && path[:len(prefix)] == prefix {key := fmt.Sprintf("ratelimit:%s", prefix)ctx := context.Background()// 令牌桶算法：使用 Redis 的 INCR 过期时间count, err := rdb.Incr(ctx, key).Result()if err != nil {c.JSON(500, gin.H{"error": "rate limit error"})c.Abort()return}if count == 1 {rdb.Expire(ctx, key, time.Second)}if int(count) > qps {c.JSON(429, gin.H{"error": "too many requests"})c.Abort()return}c.Next()return}}c.Next()}}

任务三：实现健康检查

代码语言：ja vascript

复制

在网关中增加健康检查功能。要求：1. 每个后端服务定期（每 10 秒）做一次健康探测（GET /health）2. 连续失败 3 次的服务标记为不健康，不再转发请求3. 连续成功 3 次后恢复4. 提供一个管理接口 GET /admin/health 查看所有服务状态

3.5 让 Codex 生成测试

Codex 不仅能写代码，还能模仿项目已有写法生成测试：

代码语言：ja vascript

复制

请参考项目现有代码风格，为核心的路由转发和限流功能生成单元测试。要求：1. 使用 Go 标准 testing 包2. 覆盖正常转发、路由未匹配、限流触发等场景3. 测试可独立运行，不依赖外部 Redis（使用 mock）

3.6 代码审查

Codex CLI 内置了代码审查能力：

代码语言：ja vascript

复制

codex review main.go

或者让 Codex 审查当前所有变更：

代码语言：ja vascript

复制

请审查当前 diff，找出可能导致并发问题或资源泄漏的代码。

Codex 会扫描代码，指出潜在问题。例如它可能会提醒：ReverseProxy 的 Transport 需要复用而不是每次新建，以及 Redis 连接没有做优雅关闭。

3.7 最终验证

让 Codex 跑一遍完整的验证流程：

代码语言：ja vascript

请执行以下验证步骤：1. go test ./... 确保所有测试通过2. go build -o gateway 编译生产二进制3. 启动服务，用 curl 测试路由转发和限流是否正常工作

Codex 会在沙箱中依次执行这些命令，如果测试失败会自动分析原因并修复。

---

四、高级用法：将 Codex 接入 CI/CD

Codex CLI 支持非交互式执行，可以嵌入 CI/CD 流水线：

代码语言：ja vascript

复制

# 在 CI 中自动代码审查codex exec "请审查本次 PR 的代码变更，重点关注安全漏洞和性能问题" --no-interactive# 自动生成测试codex exec "请为 src/ 目录下所有新增的函数生成单元测试" --no-interactive

在 GitHub Actions 中：

代码语言：ja vascript

复制

- name: AI Code Reviewrun: |npm install -g @openai/codexcodex login --api-key ${{ secrets.OPENAI_API_KEY }}codex exec "请审查本次 PR 的代码，输出审查报告" --no-interactive

---

五、避坑指南

5.1 第一次实战不要选重构整个项目

初次使用 Codex，建议从低风险任务开始：修一个文案错别字、给纯函数补测试、更新 README 里的过期命令。等摸清它的工作方式后再挑战复杂任务。

5.2 善用 @ 显式引入文件

CLI 不会自动推断上下文范围，需要使用 @ 显式引入文件：

代码语言：ja vascript

复制

codex请阅读 @main.go @config.yaml 解释请求流转的完整路径

5.3 使用 /status 查看额度

代码语言：ja vascript

复制

/status

这个命令可以查看 Codex 的使用额度，避免任务执行到一半被中断。

5.4 审批模式要选对

Codex CLI 提供多种审批模式：

Auto：自动执行所有操作（适合 CI）Manual：每一步都需要确认（适合第一次使用）Diff：只展示变更，不自动应用（适合代码审查场景）

建议第一次使用选择 Manual 模式，看清楚每一步 Codex 要做什么再放行。

---

六、总结

通过这个实战案例，我们完整走了一遍 Codex CLI 的开发流程：

阶段	操作	Codex 的作用
初始化	go mod init	识别项目类型，给出目录结构建议
编码	自然语言描述需求	生成代码、配置文件、自动修复编译错误
测试	要求生成测试	模仿项目风格生成单元测试
审查	codex review	扫描代码潜在问题
验证	要求运行测试和构建	执行命令、分析失败、自动修复

Codex 的核心价值在于把“写代码 → 跑测试 → 看报错 → 改代码”这套工程师日常循环做成了自动化的智能体流程。它不是替你写代码的工具，而是能进入项目替你干活的工程搭档。