Codex CLI 是 OpenAI 开源的 AI 编程代理，GitHub 85k+ stars，Apache-2.0 协议。终端里读代码、改文件、跑命令，支持三档安全审批。本文覆盖安装配置、日常使用、高级技巧和真实案例。

---

什么是 Codex CLI

Codex CLI 是 OpenAI 开源的命令行 AI 编程代理，和 Claude Code 是竞品。

核心特性：

• 开源（Apache-2.0），社区活跃，可自行扩展
• 三档安全审批模式（Read Only / Auto / Full Access）
• 支持图片输入（截图报错直接贴进终端）
• 多模型支持，交互中 /model 一键切换
• 沙箱隔离，危险操作需确认

和 Claude Code 的定位差异：

维度	Codex CLI	Claude Code
开源	Apache-2.0	闭源
速度	~61 tok/s	~43 tok/s
代码推理	SWE-bench Pro 57.7%	SWE-bench 79.6%
安全模式	三档选择	权限配置文件
图片输入	支持	支持
社区插件	丰富	官方主导

简单说：Codex 更快、开源、灵活。Claude Code 推理更强。两个都装，按任务切换。

---

安装

各平台安装命令

# Linux / WSL / macOS（官方推荐，自动更新）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# macOS (Homebrew)
brew install --cask codex

# npm（跨平台通用）
npm install -g @openai/codex

Windows 用户：CLI 版推荐通过 WSL 使用。Codex Desktop App 自 2026 年 3 月起原生支持 Windows。

验证安装：

codex --version
# 应显示类似 codex-cli 0.133.x

配置 API 接入

Codex CLI 默认需要 ChatGPT Plus 订阅或 OpenAI API Key，国内无法直连。解决方案是使用 OpenAI 兼容的 API 端点。

编辑 ~/.codex/config.toml：

model = "openai/gpt-5.4"
model_provider = "qiniu"
model_reasoning_effort = "high"
approval_policy = "on-request"

[model_providers.qiniu]
name = "七牛云"
base_url = "https://openai.qiniu.com/v1"
experimental_bearer_token = "sk-your-api-key"
wire_api = "responses"
supports_websockets = false

获取 API Key：

1. 打开 https://s.qiniu.com/2uMRza 注册七牛云账号
2. 完成实名认证
3. 进入费用中心，充值 100 元（开启每分钟 5 次请求额度）
4. 进入 API Key 管理页面：https://portal.qiniu.com/ai-inference/api-key
5. 点击「创建」，名称填 “codex-cli”
6. 复制 sk- 开头的 Key，粘贴到配置文件的 experimental_bearer_token

验证配置：

codex "你好，你是什么模型？"

看到回复就成功了。

---

三档安全模式详解

这是 Codex CLI 的核心设计之一，也是它和 Claude Code 最大的区别。

Read Only（只读）

codex --approval-mode read-only

• 只能读代码和回答问题
• 不修改任何文件
• 不执行任何命令
• 适合：代码审查、理解项目结构、学习新代码库

Auto（半自动）

codex --approval-mode auto

• 自动执行安全操作（读文件、写文件、运行测试）
• 危险操作弹出确认（删除文件、安装包、修改配置）
• 适合：日常开发（推荐默认使用这个模式）

Full Access（全自动）

codex --approval-mode full-access

• 完全自主，不需要任何确认
• 会直接执行所有操作
• 适合：信任的自动化流水线、CI/CD 集成
• ⚠️ 谨慎使用，确保你理解后果

在配置文件中设置默认模式：

approval_policy = "on-request"  # auto 模式
# 其他选项："suggest"(read-only), "on-request"(auto), "full-auto"(full-access)

---

日常使用

交互模式

# 进入交互式对话
cd my-project
codex

# 交互中常用斜杠命令
/help          # 查看所有命令
/model         # 切换模型
/approval      # 切换审批模式
/context       # 查看当前上下文
/clear         # 清空对话历史

单次命令

# 理解项目
codex "解释这个项目的架构，画一个模块依赖图"

# 写代码
codex "实现一个 rate limiter 中间件，支持滑动窗口算法"

# 修 Bug
codex "运行 npm test，分析失败的用例，修复它们"

# 重构
codex "把 src/legacy/ 目录下的回调地狱改成 async/await"

# 文档
codex "给 src/api/ 目录下所有导出函数加 JSDoc 注释"

图片输入

Codex 支持直接贴图片，适合：

# 截图报错
codex "看一下这个报错截图，分析原因" --image error.png

# 设计稿转代码
codex "按这个设计稿写 HTML/CSS" --image design.png

---

模型选择策略

Codex CLI 通过七牛云可以用 GPT 和 Claude 两个系列的模型：

按任务选模型

任务类型	推荐模型	原因
日常编码	openai/gpt-5.4	稳定旗舰，$15/M
代码专用任务	openai/gpt-5.3-codex	代码专用优化，$14/M
快速问答	openai/gpt-5.4-nano	$1.25/M，极快
批量轻量任务	openai/gpt-5-nano	$0.40/M，几乎免费
复杂推理	claude-4.6-sonnet	SWE-bench 79.6%
深度重构	claude-4.6-opus	最强推理

切换模型

交互中切换：

/model    # 弹出模型选择菜单

配置文件切换：

# 改 model 字段即可
model = "claude-4.6-sonnet"

命令行指定：

codex --model "openai/gpt-5.3-codex" "重构这个函数"

---

高级玩法

1. 项目指令文件

在项目根目录创建 codex.md 或 AGENTS.md：

# 项目上下文

## 技术栈
- TypeScript + Node.js 20
- Fastify 框架
- PostgreSQL + Drizzle ORM
- Vitest 测试

## 规范
- 所有函数必须有返回类型注解
- 错误处理用 Result<T, E> 模式
- 测试文件放在同级 __tests__ 目录

## 常用命令
- `pnpm dev` 启动
- `pnpm test` 测试
- `pnpm build` 构建

Codex 启动时会自动读取这个文件，减少重复交代上下文。

2. 批量文件操作

# 批量加类型注解
codex "给 src/ 下所有 .js 文件转成 .ts，加上类型注解"

# 批量更新 import
codex "项目从 CommonJS 迁移到 ESM，更新所有 require 为 import"

# 批量加测试
codex "给 src/services/ 目录下每个文件生成对应的单元测试"

3. CI/CD 集成

Codex CLI 可以在 CI 中使用（full-access 模式）：

# GitHub Actions 示例
- name: Auto-fix lint errors
  run: |
    codex --approval-mode full-access \
      "运行 eslint，自动修复所有可以修复的问题，提交结果"
  env:
    OPENAI_API_KEY: ${{ secrets.QINIU_API_KEY }}

4. 自定义插件

Codex 开源，社区有丰富的插件生态：

# 查看可用插件
codex plugin list

# 安装插件
codex plugin install @codex/git-helper

5. 结合 Git 工作流

# 自动 PR 描述
codex "看 main..HEAD 的 diff，写一个清晰的 PR 描述"

# 交互式 rebase 辅助
codex "这个分支有 15 个 commit，帮我整理成 3-4 个逻辑清晰的 commit"

# 冲突解决
codex "git merge main 有冲突，帮我解决，优先保留当前分支的业务逻辑"

---

性能调优

减少上下文消耗

在 codex.md 中明确告诉 Codex 哪些目录不需要关注：

## 忽略目录
- node_modules/
- dist/
- coverage/
- .next/
- *.lock 文件

推理强度

# 复杂任务
model_reasoning_effort = "high"

# 简单问答（省钱省时间）
model_reasoning_effort = "low"

交互中也能调：

/effort high   # 复杂任务
/effort low    # 简单问答

多模型策略

日常开发：gpt-5.4（稳定）
快速问答：gpt-5.4-nano（便宜快速）
复杂重构：切到 claude-4.6-sonnet（推理强）

一个 Key 全模型切换，不需要多套配置。

---

真实案例

案例 1：遗留项目现代化

codex "这是一个 5 年前的 Express + JavaScript 项目。帮我：
1. 列出核心业务模块
2. 按依赖关系排序
3. 从最底层开始逐个转 TypeScript
先只转 src/utils/ 目录，确保现有测试通过"

案例 2：性能问题排查

codex "用户反馈首页加载慢。看一下 src/pages/index.tsx 和相关组件，
分析可能的性能问题，给出优化方案并实现前两个最有效的"

案例 3：API 测试生成

codex "看 src/routes/ 目录下所有 API 端点，
给每个端点生成集成测试，覆盖正常流程、参数校验、权限控制三种场景"

---

常见问题

Codex CLI 免费吗？

Codex CLI 本身开源免费。使用时需要 API（按量付费），充 100 元即可开始用。

和 Claude Code 选哪个？

建议两个都装。Codex 更快、开源、有三档审批。Claude Code 推理更强。同一个 API Key 两边都能用，根据任务切换。

支持哪些模型？

GPT 全系列（5.5/5.4/5.3-codex/nano）+ Claude 全系列 + Grok + Gemini + 国内模型。交互中 /model 查看完整列表。

每天花多少钱？

取决于模型和用量。GPT-5.4 日常编码约 $5-10/天。用 nano 做轻量任务几乎不花钱。

能在 Codex 里用 Claude 吗？

能。改一行配置：model = "claude-4.6-sonnet"。七牛云的 OpenAI 兼容接口同时支持 GPT 和 Claude。

---

延伸阅读

1. Codex CLI GitHub：https://github.com/openai/codex
2. 七牛云注册（获取 API Key）：https://s.qiniu.com/2uMRza
3. 模型价格对比：https://modelink.ai/en-US/models
4. API 端点：https://openai.qiniu.com/v1