1. 从命令行到流水线：Codex CLI 智能体编程的工程化落地
很多人第一次接触 OpenAI Codex CLI，都是被它那种“在终端里直接对话就能改代码”的体验吸引的。敲一行codex，用自然语言描述需求，它就能读文件、改代码、跑测试，整个过程行云流水。但真正把它放到团队协作和持续交付的场景里，问题就来了：本地跑得好好的智能体，一进 CI 环境就各种超时、断连、构建失败。这一篇就专门聊这件事——怎么把 Codex CLI 从一个“玩具级”的终端助手，变成能稳定跑在 CI/CD 流水线里的工程化工具。
核心关键词先摆出来：OpenAI Codex CLI、智能体编程、CI/CD、WebSocket Keepalive、Bazel。这几个词看起来跨度挺大，一个讲 AI 编程工具，一个讲持续集成，一个讲网络保活，一个讲构建系统。但它们其实是一条链上的：Codex CLI 作为智能体，要在 CI/CD 里干活，就得解决长连接稳定性问题（WebSocket Keepalive），还得跟大型项目的构建体系（Bazel）配合好。这条链上任何一环掉链子，整个自动化流程就崩了。
这篇文章适合谁看？如果你已经在本地用过 Codex CLI，想把它接入团队的自动化流程，那这篇就是写给你的。如果你还没用过，但正在调研“AI 智能体能不能进 CI 流水线”，这篇也能帮你把坑先摸清楚。我会从整体设计思路讲起，然后拆解 WebSocket 保活和 Bazel 集成这两个硬骨头，再给一套可复现的实操流程，最后把常见问题和排查技巧整理成速查表。全程按我实际踩坑的顺序来，不绕弯子。
2. 整体设计思路：为什么智能体进 CI 比想象中难
2.1 本地交互和 CI 自动化的本质差异
本地用 Codex CLI 的时候，你是“人在回路”的。它卡住了你能看到，它问问题你能回答，网络抖一下你等两秒就恢复了。但 CI 环境里没有“人”这个角色，智能体必须自己把一整条任务链跑完：拉代码、理解上下文、生成修改、跑测试、提交结果。任何一个环节挂起，整个流水线就卡死，而且没人知道卡在哪。
这个差异决定了三件事。第一，超时策略必须重新设计。本地可以无限等，CI 里每个 job 都有时间上限，智能体的每一步都得有明确的超时和重试。第二，连接稳定性从“锦上添花”变成“生死线”。本地断线重连一下就行，CI 里断线可能意味着整个 job 失败，所以 WebSocket Keepalive 不是可选项，是必选项。第三，构建环境必须可预测。本地你可能用 npm、pip 混着来，CI 里如果项目用 Bazel，那智能体生成的代码必须能过 Bazel 的构建和测试，否则改了等于没改。
我见过太多团队在这三件事上翻车。最常见的就是把本地脚本直接扔进 CI，结果第一次跑就超时，第二次跑就断连，第三次跑 Bazel 报一堆依赖问题。所以设计思路的核心就一句话：把智能体当成一个需要高可用的分布式服务来对待，而不是一个本地命令行工具。
2.2 方案选型：为什么是 Keepalive + Bazel 这套组合
有人可能会问，WebSocket 保活和 Bazel 集成，这两个东西为什么要放在一起讲？因为它们解决的是同一个问题的两面：智能体在 CI 里的“存活”和“产出”。Keepalive 保证智能体活着，Bazel 保证智能体的产出能被验证。缺了前者，智能体中途死掉；缺了后者，智能体活着但产出的代码过不了构建。
选 WebSocket Keepalive 而不是简单的 HTTP 轮询，是因为 Codex CLI 和模型之间的交互是长连接、流式的。它需要持续接收 token 流，中间不能断。HTTP 轮询每次都要重建连接，延迟高、开销大，而且流式响应根本没法用轮询实现。WebSocket 天然适合这种场景，但它的弱点是空闲连接容易被中间设备掐断，所以必须加 Keepalive。
选 Bazel 作为构建验证工具，是因为大型项目里 Bazel 的增量构建和缓存机制对 CI 特别友好。智能体改一个文件，Bazel 只重建受影响的部分，不会全量重跑。而且 Bazel 的test命令能精确指定测试目标，智能体可以只跑相关测试，节省大量时间。如果用 Make 或者裸脚本，每次都得全量构建，CI 时间直接爆炸。
提示：如果你的项目还没用 Bazel，别为了接 Codex CLI 强行上 Bazel。先用项目现有的构建工具跑通流程，等智能体稳定了再考虑迁移。工具是为人服务的，不是反过来。
2.3 整体架构：三层结构拆开看
我把这套方案拆成三层。第一层是连接层，负责 Codex CLI 和模型服务之间的 WebSocket 连接，核心是 Keepalive 机制和断线重连。第二层是执行层，负责智能体的任务调度，包括读文件、生成修改、调用构建工具。第三层是验证层，用 Bazel 做构建和测试，把结果反馈给智能体，形成闭环。
这三层之间是解耦的。连接层挂了不影响执行层的逻辑，执行层出错可以单独重试，验证层失败可以触发智能体重新生成。这种解耦的好处是排查问题的时候能快速定位是哪一层出的问题。我实际用下来，大部分故障都在连接层，其次是验证层的 Bazel 配置问题，执行层反而最稳定。
3. WebSocket Keepalive 深度拆解：让智能体在 CI 里不掉线
3.1 为什么空闲连接会被掐断
要理解 Keepalive，先得理解为什么连接会断。WebSocket 建立之后，如果一段时间没有数据往来，中间的网络设备（负载均衡、反向代理、防火墙）会认为这个连接“死了”，然后主动回收。这个空闲超时时间因环境而异，短的 30 秒，长的几分钟。CI 环境里，智能体在“思考”或者“等待构建结果”的时候，连接上可能几十秒没有数据，正好撞上超时。
更麻烦的是，这种断连往往是静默的。客户端以为连接还在，发消息过去才发现写不进去，或者读的时候直接报错。在本地你马上能看到，在 CI 里就是 job 卡住直到超时。所以 Keepalive 的本质是：在空闲期间主动发心跳，让中间设备认为连接还活着。
3.2 Keepalive 的实现方式和参数选择
WebSocket 协议本身有 Ping/Pong 帧，这是最标准的保活方式。客户端定期发 Ping，服务端回 Pong，中间设备看到有数据流动就不会掐连接。Codex CLI 底层用的是标准 WebSocket 库，Ping/Pong 是支持的，但默认可能没开或者间隔太长。
我的做法是显式配置心跳间隔。具体参数怎么定？先看环境的空闲超时。如果你不确定，就按最保守的来：心跳间隔设为 20 到 30 秒。这个值要小于任何中间设备的空闲超时，同时不能太频繁，否则浪费带宽和 CPU。我实测下来，25 秒是个比较稳的值，既能覆盖大部分 30 秒超时的环境，又不会给连接带来明显负担。
除了 Ping/Pong，还有一层应用层的心跳。就是在 WebSocket 消息里定期发一个空操作或者状态查询，确保应用层也是活的。这层主要是防止“连接还在但应用卡死”的情况。两层心跳配合，基本能覆盖绝大多数断连场景。
// WebSocket Keepalive 配置示例（Node.js 环境） const WebSocket = require('ws'); const ws = new WebSocket('wss://api.example.com/stream', { handshakeTimeout: 10000, // 底层 TCP Keepalive perMessageDeflate: false, }); // 应用层心跳，每 25 秒一次 const heartbeatInterval = 25000; let heartbeatTimer = null; function startHeartbeat() { heartbeatTimer = setInterval(() => { if (ws.readyState === WebSocket.OPEN) { ws.ping(); // 协议层 Ping ws.send(JSON.stringify({ type: 'heartbeat', ts: Date.now() })); // 应用层心跳 } }, heartbeatInterval); } function stopHeartbeat() { if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } } ws.on('open', () => { console.log('连接已建立，启动心跳'); startHeartbeat(); }); ws.on('pong', () => { // 收到 Pong，说明连接健康 console.log('收到 Pong，连接正常'); }); ws.on('close', () => { console.log('连接关闭，停止心跳'); stopHeartbeat(); }); ws.on('error', (err) => { console.error('连接错误:', err.message); stopHeartbeat(); });这段代码的关键点在于：心跳只在连接打开时启动，连接关闭时清理定时器，避免内存泄漏。ws.ping()发的是协议层 Ping 帧，ws.send()发的是应用层消息，两层一起上。perMessageDeflate: false是关掉压缩，因为压缩会增加 CPU 开销，在 CI 环境里没必要。
3.3 断线重连：比 Keepalive 更重要的兜底
Keepalive 能防住大部分断连，但防不住所有。网络抖动、服务端重启、负载均衡切换，这些都会导致连接真的断掉。这时候就需要断线重连。重连策略的核心是指数退避：第一次断线等 1 秒重连，失败等 2 秒，再失败等 4 秒，以此类推，直到一个上限（比如 30 秒）。
为什么用指数退避而不是固定间隔？因为如果是服务端过载导致的断连，固定间隔重连会加剧过载，形成雪崩。指数退避给服务端恢复的时间，同时保证客户端最终能连上。上限是为了避免等待时间无限增长，CI 环境里等太久不如直接失败重跑。
重连的时候还要注意状态恢复。智能体可能正在处理一个任务，连接断了之后任务状态丢了怎么办？我的做法是把任务状态持久化到本地文件或者环境变量里，重连成功后先读状态，从断点继续。这样即使断线，也不会从头再来。
注意：重连次数要有上限，比如 5 次。超过上限就判定为不可恢复故障，直接让 CI job 失败。无限重连在 CI 里是灾难，会一直占着 runner 不放。
4. Bazel 集成实战：让智能体的产出过得了构建
4.1 为什么智能体改的代码容易过不了 Bazel
Bazel 的核心理念是严格的依赖声明和 hermetic 构建。每个 target 必须显式声明它依赖什么，构建过程中不能访问声明之外的东西。这个理念很好，但对智能体来说是个挑战。智能体生成代码的时候，可能引入一个新的 import，但没有在 BUILD 文件里加对应的依赖。本地用其他构建工具可能能跑，Bazel 直接报错。
另一个常见问题是文件可见性。Bazel 的visibility规则控制哪些 target 能依赖哪些 target。智能体可能把代码放到了错误的包路径下，导致 visibility 检查失败。还有就是测试目标的选择，智能体可能改了 A 模块的代码，但只跑了 B 模块的测试，结果 A 的测试挂了没发现。
这些问题本质上是因为智能体对 Bazel 的构建语义理解不够。解决办法不是让智能体去学 Bazel，而是在流程上做约束：智能体改完代码后，必须跑 Bazel 的构建和测试，失败了就把错误信息喂回给智能体，让它自己修。这个闭环是关键。
4.2 BUILD 文件的自动生成和校验
让智能体直接改 BUILD 文件风险比较大，因为 BUILD 文件的语法虽然简单，但规则很多，改错一个地方整个包都构建不了。我的做法是分两步：先让智能体改源码，然后用工具自动生成或更新 BUILD 文件。
Bazel 生态里有gazelle这个工具，能根据源码自动生成 BUILD 文件。对于 Go 项目，gazelle 能扫描 import 自动补依赖；对于其他语言，也有对应的插件。流程是这样的：智能体改完.go文件，跑gazelle更新 BUILD 文件，然后再跑bazel build。这样智能体不用关心 BUILD 文件的细节，gazelle 负责把依赖补全。
# 智能体改完代码后，用 gazelle 更新 BUILD 文件 bazel run //:gazelle -- update-repos -from_file=go.mod bazel run //:gazelle -- ./... # 然后跑构建验证 bazel build //... --keep_going # 跑相关测试 bazel test //path/to/changed/package:all --test_output=errors--keep_going这个参数很重要，它让 Bazel 在遇到错误时继续构建其他 target，一次性把所有错误都暴露出来。如果不加，Bazel 遇到第一个错误就停了，智能体得反复修反复跑，效率很低。--test_output=errors让测试失败时输出详细日志，方便智能体定位问题。
4.3 增量构建和缓存：让 CI 跑得快
Bazel 最大的优势之一是增量构建和远程缓存。智能体只改了一个文件，Bazel 只重建受影响的部分，其他部分直接用缓存。在 CI 里，这个优势更明显，因为 CI 环境每次都是全新的，如果没有缓存，每次都要全量构建，时间根本受不了。
配置远程缓存需要指定一个缓存后端，可以是本地目录，也可以是远程服务。CI 环境里通常用远程缓存，多个 job 共享。配置方式是在.bazelrc里加：
# .bazelrc 配置示例 build --remote_cache=grpc://cache.example.com:9092 build --remote_timeout=60 build --disk_cache=/tmp/bazel-cache # 只对 CI 环境生效的配置 build:ci --remote_cache=grpc://cache.example.com:9092 build:ci --remote_upload_local_results=true--remote_upload_local_results=true让本地构建的结果也上传到远程缓存，这样下次其他 job 就能直接用。--remote_timeout=60是缓存操作的超时，CI 环境网络可能不稳定，设长一点避免误判。
提示：远程缓存服务需要单独部署，如果团队规模小，可以先用
--disk_cache本地磁盘缓存。虽然不能跨机器共享，但同一个 runner 上的多次构建能复用，也能省不少时间。
5. 完整实操流程：从零搭一套可跑的 CI 流水线
5.1 环境准备和依赖安装
先把基础环境搭好。CI runner 上需要装这些东西：Node.js（跑 Codex CLI）、Bazel（构建验证）、Git（拉代码）。版本上，Node.js 建议 18 以上，Bazel 建议 6 以上。安装方式看 runner 的操作系统，Ubuntu 的话用 apt 或者官方脚本都行。
# 安装 Node.js 18 curl -fsSL https://deb.nodesource.com/setup_18.x | bash - apt-get install -y nodejs # 安装 Bazel apt-get install -y apt-transport-https curl gnupg curl -fsSL https://bazel.build/bazel-release.pub.gpg | gpg --dearmor > bazel.gpg mv bazel.gpg /etc/apt/trusted.gpg.d/ echo "deb [arch=amd64] https://storage.googleapis.com/bazel-apt stable jdk1.8" | tee /etc/apt/sources.list.d/bazel.list apt-get update && apt-get install -y bazel # 安装 Codex CLI npm install -g @openai/codex-cli装完之后验证一下：codex --version、bazel --version、node --version都能正常输出。这一步看着简单，但 CI 环境里经常因为权限或者源的问题卡住，建议把安装脚本单独跑一遍确认没问题再集成到流水线里。
5.2 配置 Codex CLI 的连接参数
Codex CLI 需要配置模型服务的连接信息。这些信息通过环境变量传入，不要硬编码在脚本里。CI 平台一般都有 secrets 管理，把 API key 之类的敏感信息放那里，运行时注入环境变量。
# 环境变量配置 export CODEX_API_KEY="your-api-key" export CODEX_API_BASE="https://api.example.com" export CODEX_WS_KEEPALIVE_INTERVAL=25000 export CODEX_WS_RECONNECT_MAX=5 export CODEX_TIMEOUT=600CODEX_WS_KEEPALIVE_INTERVAL就是前面说的心跳间隔，25 秒。CODEX_WS_RECONNECT_MAX是最大重连次数，5 次。CODEX_TIMEOUT是单次任务超时，600 秒，也就是 10 分钟。这些值可以根据实际任务复杂度调整，任务重就调大超时，网络差就调小心跳间隔。
5.3 编写智能体任务脚本
任务脚本是整个流程的核心。它要做的就是：读任务描述、调 Codex CLI 执行、拿结果、跑 Bazel 验证、根据结果决定是否重试。我把它写成一个 shell 脚本，逻辑清晰，方便调试。
#!/bin/bash set -euo pipefail TASK_DESC="$1" MAX_RETRY=3 RETRY=0 while [ $RETRY -lt $MAX_RETRY ]; do echo "=== 第 $((RETRY+1)) 次尝试 ===" # 调 Codex CLI 执行任务 if codex exec --task "$TASK_DESC" --timeout 600 --output /tmp/codex-result.json; then echo "智能体执行成功" else echo "智能体执行失败，准备重试" RETRY=$((RETRY+1)) sleep $((RETRY * 5)) continue fi # 用 gazelle 更新 BUILD 文件 bazel run //:gazelle -- ./... || true # 跑构建验证 if bazel build //... --keep_going --remote_cache=grpc://cache.example.com:9092; then echo "构建通过" else echo "构建失败，把错误喂回智能体" bazel build //... --keep_going 2>&1 | tail -50 > /tmp/build-error.log TASK_DESC="上次构建失败，错误如下：$(cat /tmp/build-error.log)。请修复。" RETRY=$((RETRY+1)) continue fi # 跑测试 if bazel test //... --test_output=errors --remote_cache=grpc://cache.example.com:9092; then echo "测试通过，任务完成" exit 0 else echo "测试失败，把错误喂回智能体" bazel test //... --test_output=errors 2>&1 | tail -50 > /tmp/test-error.log TASK_DESC="上次测试失败，错误如下：$(cat /tmp/test-error.log)。请修复。" RETRY=$((RETRY+1)) fi done echo "达到最大重试次数，任务失败" exit 1这个脚本的关键设计是错误反馈闭环。构建或测试失败时，把错误日志截取最后 50 行，拼到任务描述里，让智能体重新执行。这样智能体能看到自己的错误并修复，而不是盲目重试。tail -50是防止错误日志太长，把上下文撑爆。
5.4 集成到 CI 流水线
最后把脚本集成到 CI 平台的配置文件里。以常见的 YAML 配置为例：
# .ci/pipeline.yml stages: - agent-task agent-task: stage: agent-task script: - bash scripts/setup-env.sh - bash scripts/run-agent.sh "实现用户登录接口的单元测试" timeout: 30m retry: max: 2 when: runner_system_failure artifacts: paths: - /tmp/codex-result.json - /tmp/build-error.log - /tmp/test-error.log when: alwaystimeout: 30m是整个 job 的超时，比单次任务超时大，留出重试的余量。retry是 CI 平台层面的重试，只在 runner 系统故障时触发，业务逻辑失败不重试（因为脚本内部已经重试了）。artifacts把结果和日志都存下来，方便事后排查。
6. 常见问题与排查技巧实录
6.1 连接类问题速查
连接类问题是最常见的，表现是智能体执行到一半卡住，或者直接报连接错误。下面这张表是我实际遇到过的连接问题和对应的排查方法。
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 执行到一半卡住无输出 | 空闲连接被中间设备掐断 | 抓包看是否有 RST 包 | 调小心跳间隔到 20 秒 |
| 报 WebSocket 1006 错误 | 连接异常关闭，无关闭帧 | 检查网络抖动和服务端日志 | 开启断线重连，指数退避 |
| 重连后任务从头开始 | 状态未持久化 | 检查状态存储逻辑 | 任务状态写入本地文件 |
| 心跳发了但还断 | 中间设备不认 Ping/Pong | 抓包确认心跳是否到达 | 加应用层心跳消息 |
| 连接建立就失败 | API key 或地址错误 | 检查环境变量 | 确认 secrets 注入正确 |
抓包是排查连接问题的终极手段。在 CI 环境里可能不方便抓包，那就加详细日志，把 WebSocket 的 open、close、error、ping、pong 事件都打出来。日志里能看到连接什么时候断的、断之前有没有心跳，基本就能定位问题。
6.2 Bazel 构建类问题速查
Bazel 的问题通常比较明确，错误信息会告诉你哪个 target 缺什么依赖。但有些问题比较隐蔽，比如缓存导致的“本地能过 CI 不能过”。
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 报缺少依赖 | BUILD 文件未更新 | 看错误里的 target 名 | 跑 gazelle 更新 BUILD |
| 报 visibility 错误 | 包路径或可见性配置 | 检查 BUILD 的 visibility | 调整代码位置或 visibility |
| 本地过 CI 不过 | 缓存不一致 | 清缓存重跑 | 加--disk_cache或清远程缓存 |
| 构建超时 | 全量构建无缓存 | 看构建日志是否命中缓存 | 配置远程缓存 |
| 测试目标找不到 | 测试规则未声明 | 检查 BUILD 里的 test 规则 | 补上 test 规则 |
“本地过 CI 不过”这个问题特别坑。原因是本地有缓存，CI 没有，或者反过来。解决办法是统一缓存策略，CI 和本地用同一套远程缓存。如果做不到，至少在 CI 里加--noremote_accept_cached强制不用缓存跑一次，确认是不是缓存问题。
6.3 智能体行为类问题
智能体本身的行为问题也需要关注。比如它可能反复改同一个地方改不对，或者生成一堆无关的修改。
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 反复改同一处 | 错误反馈不清晰 | 看喂回的错误日志 | 截取更精确的错误行 |
| 生成无关修改 | 任务描述太宽泛 | 看任务描述 | 把任务拆细，加约束 |
| 不跑测试就提交 | 流程未强制 | 检查脚本逻辑 | 构建测试失败必须重试 |
| 修改范围过大 | 缺少文件范围限制 | 看 diff | 在任务描述里指定文件 |
“反复改同一处”通常是因为喂回的错误信息不够精确。智能体看到一大段错误日志，可能抓不住重点。我的做法是把错误日志里最关键的那几行提取出来，比如ERROR: /path/to/BUILD:12:5: no such target，只喂这一行，智能体定位就准多了。
提示：任务描述里加上“只修改 xxx 文件”或者“不要动 xxx 目录”这样的约束，能显著减少无关修改。智能体很听话，你约束得越明确，它改得越精准。
7. 我踩过的坑和几条实在建议
先说一个最坑的：心跳间隔设得太长。我一开始设了 60 秒，觉得够用了，结果 CI 环境的负载均衡 30 秒就掐连接。智能体跑到一半断线，重连后任务状态丢了，从头再来，浪费了十几分钟。后来改成 25 秒，再没出过这个问题。所以心跳间隔一定要小于环境的最短空闲超时，不确定就往小了设。
第二个坑是Bazel 缓存污染。有次 CI 跑出来的结果和本地完全不一样，排查了半天发现是远程缓存里存了一个错误的构建结果，所有 job 都命中了这个坏缓存。解决办法是给缓存加版本号，或者定期清理。Bazel 的--remote_cache支持在 URL 里加路径，可以用构建版本号做路径区分。
第三个坑是智能体的超时设置。CI 平台的 job 超时和智能体的任务超时是两回事。我一开始只设了 job 超时 30 分钟，没设任务超时，结果智能体卡在一个任务上跑了 25 分钟，剩下 5 分钟不够重试，整个 job 失败。后来把任务超时设成 10 分钟，留足重试时间，就稳了。
最后一条建议：先在本地模拟 CI 环境跑通再上 CI。用 Docker 起一个干净的环境，把脚本跑一遍，确认没问题再集成到流水线。这样能提前发现依赖缺失、权限问题、路径问题，比在 CI 上反复试错高效得多。我现在的习惯是每次改脚本都先在本地 Docker 里跑一遍，基本能拦住 90% 的问题。
