Codex SDK 实操指南：从安装到 CI/CD 自动化的完整流程

OpenAI Codex 是基于 GPT-5.3-Codex 打造的 AI 编程智能体，能自主读取代码仓库、修改文件、执行测试、提交 PR，覆盖完整工程链路。与 GitHub Copilot 的实时补全不同，Codex 的核心是"自主做事"而非"辅助输入"。它提供五种接入形态——CLI、桌面客户端、IDE 插件、Web 端、API/SDK 自动化——本文聚焦 SDK 向的实操路径：如何安装 CLI、配置认证、写 AGENTS.md 教它认识你的项目、用 config.toml 切换模型，以及如何接入 CI/CD 流水线。

五种接入形态，SDK 适合哪类场景

在选择接入方式之前，先明确各形态的适用场景：

形态	适用场景
CLI（命令行）	本地开发、脚本调用、CI/CD 自动化
桌面客户端	macOS / Windows 可视化操作
IDE 插件	VS Code、Cursor、JetBrains 内嵌使用
Web 端	chatgpt.com/codex，无需安装
API/SDK	程序化调用、Agents 编排、MCP 集成

"SDK 实操"对应的主要是 CLI + API/SDK 自动化这条路径：用命令行或代码驱动 Codex 完成可重复、可脚本化的工程任务。

安装：三种方式任选一

方式一：npm（推荐，跨平台）

npm install -g @openai/codex

安装完成后运行 codex --version 验证。

方式二：Homebrew（macOS）

brew install --cask codex

方式三：一键安装脚本

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
 
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

也可从 GitHub Releases 手动下载对应平台的二进制文件（macOS Apple Silicon / macOS x86_64 / Linux x86_64 / Linux arm64），解压后重命名为 codex 放入 $PATH。

认证配置

Codex CLI 支持两种认证方式：

方式一：ChatGPT 账号登录（适合个人使用）

codex

首次运行选择 “Sign in with ChatGPT”，在浏览器完成授权。支持 Plus、Pro、Business、Edu、Enterprise 套餐。

方式二：API Key（适合自动化和 CI/CD）

export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
codex exec "任务描述"

API Key 通过环境变量传入，不直接写入配置文件，避免密钥泄漏到仓库。

核心用法：交互模式 vs exec 模式

交互模式（TUI）

codex

启动终端交互界面，适合探索性任务。可在会话中追问、补充上下文、查看中间步骤。

exec 模式（非交互，SDK 场景首选）

codex exec "重构 src/utils/date.ts，将所有日期格式化函数统一到 formatDate 工厂函数"

exec 模式是脚本化和 CI 场景的标准用法：单次任务、可控、可重试。

approval-mode 控制自主程度

# 每一步都确认（默认）
codex --approval-mode suggest "帮我写单元测试覆盖 auth 模块"
 
# 自动读写文件，危险操作（删除、网络请求）才确认
codex --approval-mode auto-edit "修复所有 TypeScript 类型错误"
 
# 完全自主，在沙箱环境内无限制执行
codex --approval-mode full-auto "从 issue #42 的描述出发，完成 feature branch 并提交 PR"

实际建议：本地开发用 auto-edit，CI/CD 用 full-auto（配合沙箱隔离），生产敏感仓库保持 suggest。

AGENTS.md：让 Codex 理解你的项目

AGENTS.md 是 Codex 在进入仓库时优先读取的上下文文件，相当于给它的"项目说明书"。支持三个级别：

位置	生效范围
~/.codex/AGENTS.md	用户全局，所有项目生效
<repo-root>/AGENTS.md	当前仓库
<subdir>/AGENTS.md	特定子目录（层级合并，就近优先）

一个实用的 AGENTS.md 模板：

## 技术栈
本项目使用 Next.js 14 + TypeScript + Tailwind CSS + Prisma（PostgreSQL）。
 
## 编码规范
- 禁止内联样式，统一用 Tailwind 类名
- 组件使用 function 声明，不用 const arrow function
- 所有异步函数用 async/await，不用 .then()
 
## 常用命令
- 启动开发服务器：`pnpm dev`
- 运行测试：`pnpm test`
- 类型检查：`pnpm type-check`
- 构建：`pnpm build`
 
## 禁止操作
- 不得修改 prisma/migrations/ 下的任何文件
- 不得直接修改 .env 文件

AGENTS.md 写得越具体，Codex 犯低级错误的概率越低。特别是"禁止操作"一栏，可以明确防止它修改不该动的关键文件。

config.toml：自定义模型与接口

Codex 配置文件路径：

● 用户全局：~/.codex/config.toml

● 项目级：.codex/config.toml（优先级更高）

使用 OpenAI 官方模型：

model = "codex-mini-latest"
model_reasoning_effort = "high"

model_reasoning_effort 可设为 low / medium / high，影响推理深度与耗时。

切换到自定义兼容接口（支持 OpenAI 协议的任意服务）：

model = "gpt-5.5"
model_provider = "my_provider"
 
[model_providers.my_provider]
name = "My API Gateway"
base_url = "https://api.example.com/v1"
wire_api = "responses"
env_key = "MY_API_KEY"

字段说明：

字段	说明
model	调用的模型名，需与 provider 支持的名称一致
model_provider	指向下方 provider 块的 key
base_url	接口入口地址
wire_api	"responses"（OpenAI Responses API）或 "chat"（Chat Completions）
env_key	指定存放 API Key 的环境变量名

多个 provider 可并列配置，切换时只需修改顶层 model_provider 字段即可。国内开发者可在此配置国内可直接访问的兼容推理接口；七牛云 AI 编程工具配置大全（developer.qiniu.com/aitokenapi/13195/AI-Coding）提供了主流 IDE 工具接入国产模型的完整参考。

CI/CD 自动化：把 Codex 接入流水线

Codex exec 天然适合集成进 GitHub Actions 等 CI 系统：

# .github/workflows/codex-changelog.yml
name: Auto Update CHANGELOG
 
on:
  push:
    branches: [main]
 
jobs:
  update-changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Codex CLI
        run: npm install -g @openai/codex
      - name: Update CHANGELOG
        run: |
          codex exec --approval-mode full-auto \
            "根据最近 10 条 commit 更新 CHANGELOG.md，按 Features / Bug Fixes / Breaking Changes 分类"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

几个 CI 场景下的实用模式：

● 自动更新 CHANGELOG：每次合并主干时触发

● 自动修复 lint 错误：在 PR 中运行，提交 fix commit

● 代码审查辅助：生成结构化 review 注释

● 自动生成测试：针对新增函数补充单元测试

关键原则：CI 场景统一用 codex exec，而不是启动交互式 TUI；--approval-mode full-auto 配合沙箱隔离使用；密钥通过 secrets 注入，不出现在代码或日志里。

最佳实践

任务粒度：一次 exec，一件事

不要把五个不相关的需求塞进一条指令。codex exec "重构 auth 模块 + 修 3 个 bug + 写文档" 会让 Codex 自行拆解，结果难以预期。拆成独立的 exec 调用，每次专注一个目标，出错时也更容易定位。

任务描述：目标 + 上下文 + 约束 + 完成条件

codex exec \
  "重构 @src/services/payment.ts 中的 processPayment 函数，
   拆分成 validateInput、callGateway、handleResponse 三个子函数，
   保持现有测试全部通过，不修改公开 API 签名"

AGENTS.md 先写，任务再下

每进入一个新仓库，先花 5 分钟写 AGENTS.md，比事后反复纠正低级错误省时得多。

常见问题

Q：codex exec 和 codex 交互模式有什么本质区别？

codex（交互 TUI）适合探索和调试，任务路径可以中途调整；codex exec 是单次确定性调用，输入任务、执行、返回结果，适合脚本化和 CI 场景。生产级自动化统一用 exec，可控、可重试、易于日志追踪。

Q：config.toml 的 wire_api 字段选 responses 还是 chat？

优先选 "responses"——这是 OpenAI 较新的 Responses API 格式，Codex 原生支持；如果你的接口只暴露 Chat Completions 端点（/v1/chat/completions），选 "chat"。两者都是 JSON-over-HTTP，差异在于请求/响应的字段结构。

Q：AGENTS.md 和直接在提示词里写上下文有什么区别？

AGENTS.md 是持久化的项目配置，Codex 每次进入仓库都会读取，无需在每条指令里重复描述技术栈和规范；提示词里的上下文是一次性的。长期在同一仓库工作，AGENTS.md 是主力；临时任务或一次性脚本，直接在 exec 命令里描述即可。

结语

Codex SDK 的核心使用路径是：安装 CLI → 配置认证 → 写 AGENTS.md → 按需调整 config.toml → 用 exec 模式集成进自动化流程。它和传统代码补全工具的本质区别，在于它能"自主执行"而不只是"辅助输入"——从读仓库到跑测试到提 PR，整条工程链路都可以交给它。

本文核心数据来源：OpenAI Codex 官方 GitHub 仓库（github.com/openai/codex）、OpenAI 开发者文档（developers.openai.com/codex）及多篇 2026 年 6-7 月发布的实战测评。Codex 处于快速迭代阶段，配置格式和模型名称以官方最新文档为准。

延伸资源

● Codex CLI 官方仓库：github.com/openai/codex

● Codex 开发者文档：developers.openai.com/codex

● Codex 非交互模式文档：developers.openai.com/codex/noninteractive

● AI 编程工具Token Plan：https://www.qiniu.com/ai/plan