开篇先说一个核心判断：OpenAI Codex 和 GitHub Copilot 虽然都挂着“AI 编程”的标签，但本质上是两条截然不同的路子。Copilot 更像贴身助理，在你写代码的时候补全下一行、下一个函数；而 Codex，说白了，是一个能自己动手干活儿的 AI 程序员——它能读你的仓库，改你的文件，跑测试，甚至直接提 PR。它基于 GPT-5.3-Codex 打造，覆盖的不再是单个文件的补全，而是完整的工程链路。

那么，要怎么把这个“能干活”的智能体接进自己的项目里？官方提供了五种接入形态：CLI、桌面客户端、IDE 插件、Web 端，以及我们今天要重点聊的 API/SDK 自动化路径。CLI 和 API/SDK 的组合，正是最适合脚本化和 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 手动下载对应平台的二进制文件，解压重命名为 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	用户全局，所有项目生效
/AGENTS.md	当前仓库
/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 文件

把"禁止操作"写清楚，可以明确防止 Codex 修改那些不该动的关键文件。AGENTS.md 写得越具体，它犯低级错误的概率越低。

---

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 字段。国内开发者可以在这里配置可以直接访问的兼容推理接口。

---

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