OpenAI Codex CLI 完全指南 2026：从安装到生产级配置的终端 AI 编程助手

OpenAI Codex CLI 是 OpenAI 于 2025 年中推出的终端 AI 编程助手，它将强大的代码生成能力直接带入命令行环境。作为对标 Anthropic Claude Code 的核心产品，Codex CLI 凭借其开源免费、沙箱安全模型、MCP 协议集成和灵活的 Profile 配置体系，迅速成为 2026 年开发者工具箱中的必备利器。

什么是 Codex CLI？

不只是"终端里的 ChatGPT"

很多初次接触 Codex CLI 的开发者会将其简单理解为"在终端里运行的 ChatGPT"，但这种认知严重低估了它的设计深度。Codex CLI 是一个完整的交互式代码代理（Code Agent），它不仅能够理解自然语言指令，还能：

读取项目上下文：自动分析当前目录的文件结构、依赖关系和代码风格
执行多步任务：从需求分析到代码实现再到测试验证，形成完整工作流
安全沙箱隔离：通过三级沙箱模式和四级审批策略，确保 AI 操作不会破坏系统
会话持久化：支持会话恢复、分叉实验和历史追溯，避免工作进度丢失

核心架构设计

Codex CLI 基于 Rust 开发，采用模块化架构：

codex-cli/
├── core/          # 核心引擎：模型调用、上下文管理
├── sandbox/       # 沙箱层：文件系统隔离、命令执行限制
├── mcp/           # MCP 协议集成：外部工具连接
├── config/        # 配置系统：Profile 管理、别名解析
└── ui/            # 交互界面：TUI、斜杠命令解析

这种设计使得 Codex CLI 在保持轻量的同时，具备了企业级的安全性和可扩展性。与传统的 IDE 插件相比，它的优势在于：

无编辑器绑定：无论你喜欢 Vim、Emacs 还是 VS Code，都能在终端中无缝使用
远程友好：在 SSH 连接的服务器或 Docker 容器中同样流畅运行
资源占用低：Rust 编写的二进制文件启动速度快，内存占用远低于 Electron 应用

安装与基础配置

四种安装方式

1. npm 安装（推荐大多数用户）

npm install -g @openai/codex

这是最通用的安装方式，适用于 macOS、Linux 和 Windows（WSL2）。安装完成后，运行 codex --version 确认安装成功。

2. Homebrew 安装（macOS 用户首选）

brew install --cask codex

Homebrew 安装的优势在于自动处理依赖和 PATH 配置，升级时只需 brew upgrade codex。

3. 二进制文件下载

访问 GitHub Releases 下载对应平台的预编译二进制文件：

macOS Apple Silicon：codex-macos-arm64
macOS Intel：codex-macos-x86_64
Linux x86_64：codex-linux-x86_64
Linux ARM64：codex-linux-arm64
Windows：codex-windows-x86_64.exe

下载后赋予执行权限并移动到 PATH 目录：

chmod +x codex-linux-x86_64
sudo mv codex-linux-x86_64 /usr/local/bin/codex

4. WSL2 安装（Windows 用户）

Windows 原生支持尚在完善中，建议通过 WSL2（Windows Subsystem for Linux）安装：

# 在 WSL2 Ubuntu 中
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g @openai/codex

认证方式：ChatGPT 订阅 vs API Key

Codex CLI 支持两种认证方式，各有适用场景：

ChatGPT 订阅登录（适合个人用户）

如果你拥有 ChatGPT Plus、Pro、Team、Edu 或 Enterprise 订阅，可以直接通过浏览器登录：

codex login

这会打开默认浏览器，完成 OAuth 授权后自动保存令牌。订阅用户的福利：

Plus 用户：每月 5 美元免费 API 额度（30 天滚动）
Pro 用户：每月 50 美元免费 API 额度（30 天滚动）

超出额度后按标准 API 定价计费。

API Key 环境变量（适合团队/自动化）

对于团队协作或 CI/CD 集成，推荐使用 API Key：

export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"

将此行添加到 ~/.bashrc 或 ~/.zshrc 中永久生效。API Key 可以在 OpenAI Platform 创建和管理。

安全提示：不要将 API Key 硬编码在代码仓库中，建议使用 .env 文件或密钥管理服务。

系统要求与前置检查

在安装前，请确保系统满足以下要求：

组件	最低版本	推荐版本
Node.js	18.x	20.x LTS
npm	9.x	10.x
Git	2.x	2.40+
操作系统	macOS 12+/Ubuntu 20.04+/WSL2	最新稳定版

运行以下命令检查前置条件：

node --version   # 应输出 v18.x 或更高
npm --version    # 应输出 9.x 或更高
git --version    # 应输出 git version 2.x

如果 Node.js 版本过低，请访问 Node.js 官网下载安装最新版 LTS。

三种操作模式详解

Codex CLI 提供三种操作模式，分别对应不同的自动化程度和安全级别：

suggest 模式（最安全）

codex --mode suggest

在 suggest 模式下，Codex 只会提供代码建议和解释，不会自动修改任何文件。你需要手动复制建议的代码并应用到项目中。

适用场景： - 学习新框架时，希望理解每一步的原理 - 审查敏感代码变更前，需要人工确认 - 初次使用 Codex，熟悉其输出风格

示例：

$ codex --mode suggest
> 创建一个 React Todo 组件

[CODEx] 我建议创建以下文件结构：
- src/components/TodoList.jsx
- src/components/TodoItem.jsx
- src/hooks/useTodos.js

以下是 TodoList.jsx 的内容：
[code block...]

你可以手动创建这些文件，或者切换到 auto-edit 模式让我自动写入。

auto-edit 模式（平衡）

codex --mode auto-edit

auto-edit 是默认模式，Codex 会自动编辑文件，但在执行可能产生副作用的命令（如 rm、git push）时会请求确认。

适用场景： - 日常开发工作流 - 需要 AI 快速迭代代码，但保留关键操作的审批权 - 中等复杂度项目的重构

示例：

[CODEx] 我将创建 src/components/TodoList.jsx... ✓
[CODEx] 我将创建 src/components/TodoItem.jsx... ✓
[CODEx] 我需要运行 npm install react-icons，是否继续？[Y/n]

full-auto 模式（最快）

codex --mode full-auto

full-auto 模式下，Codex 会全自动执行所有操作，包括文件编辑和命令运行，无需任何确认。这是最高效但也最危险的模式。

适用场景： - 隔离的开发环境（如 Docker 容器） - 已充分信任 Codex 的判断，追求极致效率 - 批量代码生成任务

警告：在生产环境中使用 full-auto 前，务必配置沙箱模式限制其权限范围。

沙箱安全模型深度解析 ⭐差异化重点

沙箱（Sandbox）是 Codex CLI 的核心安全机制，它通过隔离文件系统和命令执行权限，防止 AI 误操作或恶意行为破坏系统。理解沙箱模型是生产级使用 Codex 的关键。

三种沙箱模式对比

Codex 提供三级沙箱模式，通过 --sandbox 参数指定：

模式	文件系统权限	命令执行	适用场景
`read-only`	只读，禁止任何写入	允许只读命令（ls, cat, grep）	代码审查、文档分析
`workspace-write`	仅允许在当前项目目录写入	允许常规命令，禁止系统级操作	日常开发（推荐）
`danger-full-access`	完全读写权限	允许所有命令	隔离环境、实验性任务

默认模式：workspace-write，在安全性和便利性之间取得平衡。

read-only 模式实战

codex --sandbox read-only
> 分析这个项目的架构

[CODEx] 我正在读取 src/ 目录结构...
[CODEx] 发现以下模块：
- auth/ (身份验证)
- api/ (REST API)
- components/ (UI 组件)

由于处于 read-only 模式，我无法修改文件。如需重构，请切换到 workspace-write 模式。

workspace-write 模式（推荐）

codex --sandbox workspace-write
> 重构 auth 模块，添加 JWT 刷新令牌

[CODEx] 我将修改 src/auth/token.js... ✓
[CODEx] 我将创建 src/auth/refresh.js... ✓
[CODEx] 运行测试以验证更改... ✓

在此模式下，Codex 只能修改当前工作目录及其子目录中的文件，无法访问 /etc、/usr 等系统目录。

danger-full-access 模式（谨慎使用）

codex --sandbox danger-full-access
> 清理所有 node_modules 目录

[CODEx] 警告：此操作将删除多个目录，确认继续？[Y/n]

仅在以下场景使用： - Docker 容器内的临时环境 - 专门的沙箱虚拟机 - 你完全信任 Codex 的判断且已备份重要数据

审批策略四级粒度

除了沙箱模式，Codex 还提供细粒度的命令审批策略，通过 --ask-for-approval 参数控制：

策略	行为	适用场景
`untrusted`	只有不可信命令才需审批（默认）	日常开发
`on-failure`	命令失败时才请求审批	调试场景
`on-request`	只在 Codex 主动请求时审批	高度信任 AI
`never`	从不请求审批	配合沙箱使用

不可信命令的定义： - 涉及网络操作（curl, wget） - 涉及包管理（npm install, pip install） - 涉及版本控制（git push, git reset --hard） - 涉及系统配置（sudo, chmod）

组合使用示例

# 最安全组合：只读沙箱 + 严格审批
codex --sandbox read-only --ask-for-approval untrusted

# 高效组合：工作区写入 + 失败时审批
codex --sandbox workspace-write --ask-for-approval on-failure

# 全自动组合：危险沙箱 + 从不审批（仅限隔离环境）
codex --sandbox danger-full-access --ask-for-approval never

--full-auto vs --yolo 的本质区别

很多用户混淆 --mode full-auto 和 --yolo 参数，它们的作用层面不同：

--mode full-auto：控制 Codex 是否需要用户确认代码编辑
--yolo：跳过所有命令执行的审批提示（等价于 --ask-for-approval never）

# 以下两条命令效果相同
codex --mode full-auto --yolo
codex --mode full-auto --ask-for-approval never

命名来源："Yolo" 源自流行语 "You Only Live Once"，在技术社区中常用来表示"不顾后果地执行"。OpenAI 用这个幽默的命名提醒用户：此模式有风险，请谨慎使用。

生产环境的安全最佳实践

在生产环境中使用 Codex CLI，建议遵循以下安全准则：

默认使用 workspace-write 沙箱：限制 AI 只能修改当前项目文件
启用 Git 集成：每次 AI 修改都自动提交，便于回滚
定期审查 Transcripts：Codex 会记录所有交互和操作日志
敏感操作手动执行：数据库迁移、生产部署等关键步骤不要交给 AI
使用 Profile 隔离环境：为不同项目配置不同的安全策略

# 生产项目配置示例
codex --profile production --sandbox workspace-write --ask-for-approval untrusted

# 实验项目配置示例
codex --profile experimental --sandbox danger-full-access --yolo

24 个斜杠命令全解析 ⭐差异化重点

Codex CLI 提供 24 个斜杠命令（Slash Commands），覆盖会话控制、模型切换、权限管理、文件操作等多个维度。熟练掌握这些命令能显著提升工作效率。

会话控制（/new, /resume, /fork, /compact）

/new - 开始新会话

/new

清除当前上下文，开始全新的对话。适用于切换任务或清空历史干扰。

/resume - 恢复历史会话

/resume

打开交互式会话选择器，列出所有历史会话，支持按日期、目录筛选。详见后文"会话恢复"章节。

/fork - 分叉实验

/fork

创建当前会话的副本，在新分支中尝试不同的解决方案，而不影响主会话。适用于：

对比多种实现方案
实验性重构，失败后可轻松丢弃
并行探索不同架构设计

> /fork
[CODEx] 已创建会话分支 fork-2026-06-07-14-30
> 尝试用 Redux 替代 Context API

[CODEx] 在分支中，我将重构状态管理...

/compact - 压缩上下文

/compact

当会话历史过长导致 token 消耗激增时，使用 /compact 压缩上下文，保留关键信息并清除冗余对话。这能有效降低后续调用的成本。

模型与风格（/model, /personality, /plan）

/model - 切换模型

/model gpt-5

运行时切换使用的模型。可用模型包括：

gpt-5.3-codex（默认，专为代码优化）
gpt-5（通用旗舰模型）
o4-mini（轻量推理模型，成本低）

> /model o4-mini
[CODEx] 已切换到 o4-mini 模型。此模型适合简单任务，推理能力较弱但成本更低。

/personality - 调整 AI 性格

/personality concise

调整 Codex 的回答风格：

concise：简洁直接，少解释
verbose：详细解释，适合学习
professional：正式语气，适合文档生成
friendly：友好轻松，适合日常交流

/plan - 生成执行计划

/plan

让 Codex 先输出详细的执行计划，再逐步实施。适用于复杂任务，帮助你提前发现潜在问题。

> /plan
> 重构整个认证模块，添加 OAuth2 支持

[CODEx] 执行计划：
1. 分析现有 auth/ 目录结构
2. 设计 OAuth2 流程（Authorization Code Grant）
3. 创建 oauth2/ 子模块
4. 修改登录接口，兼容传统密码和 OAuth2
5. 更新测试用例
6. 生成迁移文档

是否开始执行？[Y/n]

权限与状态（/permissions, /status, /debug-config）

/permissions - 查看当前权限

/permissions

显示当前的沙箱模式和审批策略配置。

> /permissions
[CODEx] 当前权限配置：
- Sandbox: workspace-write
- Approval Policy: untrusted
- Yolo Mode: disabled

/status - 查看会话状态

/status

显示当前会话的详细信息，包括：

使用的模型和推理等级
Token 用量统计
会话时长
已执行的操作数量

> /status
[CODEx] 会话状态：
- Model: gpt-5.3-codex (reasoning: high)
- Tokens: 12,450 input / 3,200 output
- Duration: 45 minutes
- Operations: 23 file edits, 8 commands executed

/debug-config - 诊断配置加载链路

/debug-config

这是排查配置问题的神器。它会显示 Codex 如何加载配置文件，包括：

全局配置路径（~/.codex/config.toml）
项目配置路径（.codex/config.toml）
环境变量覆盖
Profile 激活状态
最终生效的配置值

> /debug-config
[CODEx] 配置加载链路：
1. 全局配置: /home/user/.codex/config.toml ✓
2. 项目配置: /path/to/project/.codex/config.toml ✓
3. 环境变量: OPENAI_API_KEY set ✓
4. Active Profile: production
5. Final Config:
   - model: gpt-5.3-codex
   - sandbox_mode: workspace-write
   - approval_policy: untrusted

文件与工具（/mention, /diff, /review, /mcp）

/mention - 引用特定文件

/mention src/auth/token.js

强制 Codex 关注某个特定文件，即使它不在当前上下文中。适用于大型项目中定位关键文件。

/diff - 查看变更差异

/diff

显示自会话开始以来所有文件变更的差异对比。便于审查 AI 的修改是否符合预期。

/review - 代码审查

/review

让 Codex 对最近的代码变更进行审查，指出潜在问题、性能瓶颈和安全风险。

> /review
[CODEx] 代码审查报告：
✓ 优点：
  - 正确使用 async/await 处理异步操作
  - 添加了完善的错误处理

⚠ 建议改进：
  - token.js 第 45 行：缺少输入验证，可能导致注入攻击
  - refresh.js 第 12 行：未设置 HttpOnly 标志，存在 XSS 风险

🔴 严重问题：
  - 硬编码的 JWT 密钥，应使用环境变量

/mcp - 管理 MCP 服务器

/mcp list

列出已配置的 Model Context Protocol (MCP) 服务器。MCP 允许 Codex 连接外部工具，如 GitHub、数据库、监控平台等。详见后文"MCP 协议集成"章节。

其他实用命令

命令	功能
`/init`	初始化项目配置，创建 `.codex/config.toml`
`/feedback`	向 OpenAI 发送反馈
`/logout`	退出登录，清除认证令牌
`/quit`	退出 Codex CLI
`/statusline`	自定义终端状态栏显示
`/ps`	查看后台运行的任务
`/apps`	管理集成的应用程序

会话恢复：不再丢失工作进度 ⭐差异化重点

会话恢复是 Codex CLI 被严重低估的功能之一。在传统终端工具中，关闭终端意味着丢失所有上下文，而 Codex 通过 Transcripts 机制实现了会话的持久化和灵活恢复。

四种恢复方式

1. 交互式选择器（推荐）

codex resume

打开交互式界面，列出所有历史会话，支持：

按日期排序
按目录筛选
搜索关键词
预览会话摘要

$ codex resume
选择要恢复的会话：
  1. [2026-06-07 14:30] refactor auth module (12 ops)
  2. [2026-06-07 10:15] create React todo app (8 ops)
  3. [2026-06-06 16:45] debug API endpoint (5 ops)
> 1
[CODEx] 已恢复会话：refactor auth module

2. 恢复最近一次会话

codex resume --last

快速恢复最近一次使用的会话，无需交互式选择。适用于中断后继续工作的场景。

3. 恢复特定会话

codex resume <SESSION_ID>

通过会话 ID 精确恢复。会话 ID 可在 /status 命令输出中找到，或在 Transcripts 目录中查看。

codex resume sess_abc123def456

4. 跨目录恢复所有会话

codex resume --all

列出所有目录下的历史会话，适用于在多项目间切换的场景。

恢复时会保留什么？

会话恢复时，Codex 会重建以下状态：

对话历史：所有之前的问答记录
文件上下文：已读取和修改的文件列表
模型配置：使用的模型和推理等级
沙箱权限：当前的安全配置
未完成的任务：如果之前正在执行多步任务，会从断点继续

不会保留的内容： - 临时变量或未保存的中间结果 - 外部命令的执行状态（如正在运行的服务器）

实用场景案例

场景 1：中断后继续工作

# 上午开始重构认证模块
$ codex
> 重构 auth 模块，添加 JWT 刷新令牌
[CODEx] 正在分析现有代码...
# 突然需要开会，Ctrl+C 退出

# 下午回来，直接恢复
$ codex resume --last
[CODEx] 已恢复会话。上次我们分析了 auth/token.js，接下来我将创建 refresh.js...

场景 2：对比多种方案

# 主会话：使用 Context API
$ codex
> 实现状态管理
[CODEx] 我将使用 Context API...

# 分叉实验：尝试 Redux
> /fork
[CODEx] 已创建分支。现在尝试 Redux 方案...

# 对比后决定保留主会话，丢弃分支

场景 3：长期项目的渐进式开发

# 第一天：搭建项目骨架
$ codex
> 创建 Next.js 项目结构
[CODEx] 已完成...

# 第二天：恢复会话，继续开发
$ codex resume --last
[CODEx] 欢迎回来。昨天我们创建了项目结构，今天继续实现页面组件...

生产级配置方案 ⭐差异化重点

Codex CLI 的配置系统非常灵活，支持全局配置、项目配置和 Profile 多场景配置。合理的配置能显著提升工作效率和安全性。

别名配置：一条命令搞定启动参数

对于常用的启动参数组合，可以通过 shell 别名简化命令：

# ~/.bashrc 或 ~/.zshrc
alias codex-safe='codex --sandbox read-only --ask-for-approval untrusted'
alias codex-dev='codex --sandbox workspace-write --mode auto-edit'
alias codex-yolo='codex --sandbox danger-full-access --yolo'

使用后：

codex-safe   # 安全审查模式
codex-dev    # 日常开发模式
codex-yolo   # 实验模式（谨慎！）

Profile 多场景配置（更优雅的方案）

别名虽然简单，但缺乏灵活性。Codex 的 Profile 系统允许你在配置文件中定义多个场景，通过 --profile 参数一键切换。

配置文件结构

全局配置文件位于 ~/.codex/config.toml，项目配置文件位于 .codex/config.toml。

# ~/.codex/config.toml

# 默认配置
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
web_search = "live"
sandbox_mode = "workspace-write"
approval_policy = "untrusted"

# Profile: 代码审查（只读，严格审批）
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "untrusted"
model_reasoning_effort = "medium"

# Profile: 快速原型（轻量模型，低成本）
[profiles.quick]
model = "o4-mini"
model_reasoning_effort = "low"
web_search = "disabled"
sandbox_mode = "workspace-write"

# Profile: 生产环境（安全第一）
[profiles.production]
sandbox_mode = "workspace-write"
approval_policy = "on-failure"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"

# Profile: 实验环境（全自动，高风险）
[profiles.experimental]
sandbox_mode = "danger-full-access"
approval_policy = "never"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"

使用 Profile

# 代码审查场景
codex --profile review

# 快速原型场景
codex --profile quick

# 生产项目
codex --profile production

# 实验项目
codex --profile experimental

项目级配置覆盖

在项目根目录创建 .codex/config.toml，可以覆盖全局配置：

# my-project/.codex/config.toml

# 此项目强制使用只读沙箱
sandbox_mode = "read-only"

# 此项目禁用网络搜索
web_search = "disabled"

Codex 的配置加载优先级：项目配置 > Profile 配置 > 全局配置 > 默认值。

debug-config 诊断配置加载链路

当配置未按预期生效时，使用 /debug-config 命令诊断：

> /debug-config
[CODEx] 配置加载链路：
1. 全局配置: /home/user/.codex/config.toml ✓
   - model: gpt-5.3-codex
   - sandbox_mode: workspace-write
2. 项目配置: /path/to/project/.codex/config.toml ✓
   - sandbox_mode: read-only (覆盖全局配置)
3. Active Profile: review
   - approval_policy: untrusted
4. 环境变量:
   - OPENAI_API_KEY: set ✓
   - CODEX_MODEL: not set
5. Final Config:
   - model: gpt-5.3-codex (来自全局配置)
   - sandbox_mode: read-only (来自项目配置，优先级更高)
   - approval_policy: untrusted (来自 Profile)

通过此输出，你可以清晰地看到每个配置值的来源，快速定位问题。

模型切换与推理等级

默认模型 gpt-5.3-codex

Codex CLI 默认使用 gpt-5.3-codex 模型，这是 OpenAI 专门为代码生成优化的变体，具有以下特点：

代码理解能力强：对多种编程语言和框架有深入理解
上下文窗口大：支持长文件和复杂项目结构的分析
推理效率高：针对代码任务优化的推理路径

运行时切换模型

通过 /model 命令或配置文件切换模型：

# 切换到通用旗舰模型
/model gpt-5

# 切换到轻量模型
/model o4-mini

各模型适用场景：

模型	适用场景	成本
`gpt-5.3-codex`	复杂代码生成、重构、调试	高
`gpt-5`	通用任务、文档生成、架构设计	高
`o4-mini`	简单任务、快速原型、低成本场景	低

推理等级选择策略（high/medium/low）

推理等级（Reasoning Effort）控制模型在生成回答前的思考深度：

等级	行为	适用场景	Token 消耗
`high`	深度分析，多步推理	复杂算法、架构设计、疑难 bug	高
`medium`	平衡速度与质量	日常开发、常规重构	中
`low`	快速响应，浅层推理	简单任务、语法修正、模板生成	低

在配置文件中设置：

model_reasoning_effort = "high"  # 或 "medium", "low"

运行时切换：

> /reasoning high
[CODEx] 已切换到 high 推理等级。后续回答将进行更深入的分析。

成本优化：如何一个月省下一半 token

合理使用模型和推理等级能显著降低成本：

简单任务用 o4-mini + low 推理： bash codex --profile quick # 使用 o4-mini + low
复杂任务才用 gpt-5.3-codex + high 推理： bash codex --profile production # 使用 gpt-5.3-codex + high
定期使用 /compact 压缩上下文：清除冗余对话历史
利用 ChatGPT 订阅额度：Plus/Pro 用户的免费额度优先使用
避免不必要的网络搜索：设置 web_search = "disabled" 减少额外调用

估算节省效果： - 将 50% 的简单任务从 gpt-5.3-codex + high 切换到 o4-mini + low，可节省约 60-70% 的 token 成本 - 结合订阅额度，个人用户月均成本可控制在 $10-20 以内

MCP 协议集成：连接外部工具

Model Context Protocol (MCP) 是 Anthropic 提出的开放协议，允许 AI 助手连接外部工具和数据源。Codex CLI 通过 MCP 集成，能够访问 GitHub、数据库、监控平台等外部资源，大幅扩展其能力边界。

什么是 MCP？

MCP 的核心思想是：AI 助手不应局限于自身知识，而应能实时访问外部系统的最新数据。通过 MCP 服务器，Codex 可以：

读取 GitHub 仓库的 Issues 和 Pull Requests
查询 PostgreSQL 数据库的记录
获取 Sentry 的错误日志
访问 Slack 频道的消息

配置 GitHub/Sentry/数据库 MCP 服务器

在 ~/.codex/config.toml 中配置 MCP 服务器：

[mcp_servers]

# GitHub MCP 服务器
github = { command = "npx", args = ["-y", "@modelcontextprotocol/server-github"] }

# PostgreSQL MCP 服务器
postgres = { command = "npx", args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"] }

# Sentry MCP 服务器
sentry = { command = "npx", args = ["-y", "@modelcontextprotocol/server-sentry"] }

# 文件系统 MCP 服务器（扩展沙箱能力）
filesystem = { command = "npx", args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"] }

实战：用 MCP 扩展 Codex 能力

场景 1：分析 GitHub Issue

codex --mcp github
> 分析 repo:openai/codex 中最近的 bug report

[CODEx] 通过 GitHub MCP 查询...
[CODEx] 找到 5 个最近的 bug report：
1. #123: Session restore fails on Windows
2. #124: Sandbox permission leak in workspace-write mode
3. ...

我将详细分析 #123 的问题...

场景 2：查询数据库

codex --mcp postgres
> 查询 users 表中最近注册的用户

[CODEx] 通过 PostgreSQL MCP 执行查询...
[CODEx] 结果：
- user_id: 1001, email: alice@example.com, created_at: 2026-06-07
- user_id: 1002, email: bob@example.com, created_at: 2026-06-06

场景 3：排查 Sentry 错误

codex --mcp sentry
> 分析最近 24 小时的 critical errors

[CODEx] 通过 Sentry MCP 查询...
[CODEx] 发现 3 个 critical error：
1. TypeError: Cannot read property 'token' of undefined (auth/token.js:45)
2. ...

建议修复方案：在访问 token 属性前添加空值检查...

查看和管理 MCP 服务器

# 列出已配置的 MCP 服务器
/mcp list

# 启用/禁用特定服务器
/mcp enable github
/mcp disable postgres

# 查看服务器状态
/mcp status

Codex CLI vs Claude Code 全方位对比

Codex CLI 和 Claude Code 都是终端 AI 编程助手的代表产品，它们各有优劣。以下是全方位对比：

功能对比表格

维度	Claude Code	Codex CLI
自定义配置	支持状态栏、提示词、输出样式	Profile 多场景配置、推理等级精细控制
视觉上下文	支持图像输入	支持 Ctrl+V 粘贴图像
会话管理	会话恢复、后台任务	/resume, /fork, Transcripts 记录
安全性	内置安全审查	沙箱三级模式 + 审批四级粒度
特殊模式	Vim 模式	--yolo 全自动（危险模式）
MCP 集成	原生支持	通过配置文件集成
开源状态	闭源	开源（Apache 2.0）
模型选择	仅 Claude 模型	gpt-5.3-codex, gpt-5, o4-mini
社区生态	Anthropic 官方支持	GitHub 39K+ Stars，活跃社区

定价对比

项目	Claude Code	Codex CLI
工具本身	免费	免费（开源）
订阅费用	Claude Pro $20/月	无固定月费
API 费用	包含在 Pro 订阅中	按 API 用量付费
免费额度	Pro 订阅无限使用	Plus: $5/月, Pro: $50/月
超出后计费	无（Pro 无限）	按 OpenAI API 定价

成本估算： - 轻度用户（每日 1-2 小时）：Codex CLI 月均 $5-15（利用订阅额度），Claude Pro $20 - 中度用户（每日 3-5 小时）：Codex CLI 月均 $20-50，Claude Pro $20 - 重度用户（每日 6+ 小时）：Codex CLI 月均 $50-150+，Claude Pro $20

如何选择？

选择 Codex CLI，如果： - 你偏好开源工具和透明的配置系统 - 需要精细控制模型选择和推理等级 - 项目涉及多种模型切换（如简单任务用轻量模型） - 重视沙箱安全和会话恢复功能 - 预算有限，希望通过订阅额度降低成本

选择 Claude Code，如果： - 你已经是 Claude Pro 订阅用户 - 偏好成熟稳定的产品体验 - 不需要频繁切换模型 - 重视 Anthropic 的官方支持和生态整合

混合使用策略：许多开发者同时安装两个工具，根据场景选择： - 日常开发用 Claude Code（稳定、省心） - 复杂重构用 Codex CLI（多模型、精细控制） - 成本敏感时用 Codex CLI（利用订阅额度）

常见问题 FAQ

安装后运行报错 "command not found"

原因：npm 全局安装目录未在 PATH 中。

解决：

# 查找 codex 安装位置
which codex

# 如果未找到，检查 npm 全局目录
npm config get prefix

# 将该目录的 bin 子目录添加到 PATH
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Node.js 版本过低

原因：Codex CLI 要求 Node.js 18.x 或更高版本。

解决：

# 检查当前版本
node --version

# 如果低于 18.x，升级到 LTS 版本
# macOS
brew install node@20

# Ubuntu
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 使用 nvm（推荐）
nvm install 20
nvm use 20

API Key 无效

原因：API Key 格式错误、已过期或权限不足。

解决： 1. 确认 API Key 格式：应以 sk-proj- 或 sk- 开头 2. 在 OpenAI Platform 检查 Key 状态 3. 确认账户有足够的余额或订阅额度 4. 重新导出环境变量： bash export OPENAI_API_KEY="sk-proj-你的正确密钥"

国内如何使用 Codex CLI？

网络问题：Codex CLI 需要访问 OpenAI API，国内直连可能不稳定。

解决方案： 1. 使用代理：配置 HTTP_PROXY 环境变量 bash export HTTP_PROXY=http://your-proxy:port export HTTPS_PROXY=http://your-proxy:port 2. 使用中转服务：部分云服务提供商提供 API 中转 3. 本地部署模型：结合 Ollama 等本地模型工具（需修改 Codex 配置）

账号问题：注册 OpenAI 账户可能需要海外手机号或邮箱。

支付问题：ChatGPT 订阅需要国际信用卡或礼品卡。

Git 警告如何处理？

现象：Codex 运行时出现 Git 相关警告。

原因：Git 未安装或未配置用户信息。

解决：

# 安装 Git
# macOS
brew install git

# Ubuntu
sudo apt install git

# 配置用户信息
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

# 初始化仓库（如果在项目目录）
git init

总结与快速开始三步走

OpenAI Codex CLI 代表了终端 AI 编程助手的最新发展方向。它不仅是代码生成的工具，更是融合了安全沙箱、会话管理、MCP 集成和生产级配置的完整开发平台。

核心价值回顾

安全优先：三级沙箱模式 + 四级审批策略，确保 AI 操作可控
灵活配置：Profile 系统支持多场景一键切换
会话持久化：/resume 和 /fork 让工作进度不再丢失
生态扩展：MCP 协议连接 GitHub、数据库等外部工具
成本优化：多模型选择 + 推理等级控制，按需使用

快速开始三步走

第一步：安装与认证

npm install -g @openai/codex
codex login  # 或使用 API Key

第二步：选择安全模式

# 新手推荐：安全审查模式
codex --sandbox read-only

# 日常开发：工作区写入模式
codex --sandbox workspace-write

第三步：开始第一个任务

codex
> 创建一个简单的 Express.js API，包含 GET /health 端点

[CODEx] 我将创建以下文件：
- package.json
- server.js
- routes/health.js

开始执行... ✓

下一步学习资源

官方文档：developers.openai.com/codex
GitHub 仓库：github.com/openai/codex
IDE 集成指南：developers.openai.com/codex/ide
API 定价详情：openai.com/api/pricing
社区讨论：GitHub Issues 和 Reddit r/OpenAI

无论你是资深开发者还是 AI 编程新手，Codex CLI 都能为你的工作流带来显著提升。从今天开始，让 AI 成为你终端里的结对编程伙伴吧！