如何安装与使用 Codex CLI (2026)
OpenAI 终端代码代理设置指南
Hypereal AI Team开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始，扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
如何安装与使用 Codex CLI (2026)
OpenAI 的 Codex CLI 是一款基于终端的 AI 编程智能体（AI coding agent），允许你直接从命令行使用 OpenAI 的模型来编写、编辑、调试和重构代码。可以将其视为 OpenAI 对 Anthropic 的 Claude Code 的回应——这是一个轻量且强大的工具，无需完整的 IDE 即可在终端中运行。
本指南涵盖了 2026 年 Codex CLI 的安装、配置、日常用法以及获取最佳效果的技巧。
什么是 Codex CLI？
Codex CLI 是由 OpenAI 开发的开源命令行工具。它连接到 OpenAI API 并提供：
- 终端中的交互式编程会话
- AI 辅助下的文件读取与编辑
- 根据自然语言描述生成代码
- 对现有代码进行调试与重构
- AI 引导工作流下的** Shell 命令执行**
- 多文件项目理解能力
| 特性 | Codex CLI | Claude Code | Aider |
|---|---|---|---|
| 提供商 | OpenAI | Anthropic | 任意（自带 Key） |
| 默认模型 | o4-mini | Claude Sonnet | 可配置 |
| 开源 | 是 | 否 | 是 |
| 沙箱模式 | 是 | 是 | 否 |
| 文件编辑 | 是 | 是 | 是 |
| Shell 命令 | 是 | 是 | 受限 |
| 成本 | API 使用费 | 订阅或 API | API 使用费 |
| IDE 集成 | 仅终端 | 仅终端 | 仅终端 |
前提条件
在安装 Codex CLI 之前，你需要：
- Node.js 22+ (推荐 LTS 版本)
- npm 或 yarn
- 拥有访问 o4-mini 或 GPT-4o 权限的 OpenAI API key
- Git (推荐用于版本控制项目)
- macOS 或 Linux (Windows 可通过 WSL 支持)
安装
方法 1：通过 npm 安装（推荐）
# 全局安装
npm install -g @openai/codex
# 验证安装
codex --version
方法 2：从源码安装
# 克隆仓库
git clone https://github.com/openai/codex.git
cd codex
# 安装依赖
npm install
# 构建并链接
npm run build
npm link
方法 3：无需安装直接运行
# 使用 npx 运行而无需全局安装
npx @openai/codex "explain this project"
配置
设置 API Key
# 选项 1：环境变量（推荐）
export OPENAI_API_KEY="sk-your-api-key-here"
# 添加到 shell 配置文件以永久生效
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
# 选项 2：内联传递
OPENAI_API_KEY="sk-your-key" codex "your prompt"
配置文件
创建一个配置文件用于持久化设置：
# 创建配置目录
mkdir -p ~/.codex
# ~/.codex/config.yaml
model: o4-mini
approval_mode: suggest # suggest, auto-edit, 或 full-auto
审批模式 (Approval Modes)
Codex CLI 具有三个安全级别，用于控制 AI 的自主权：
| 模式 | 标志 (Flag) | 行为 |
|---|---|---|
| Suggest (默认) | --suggest |
显示建议的更改，在进行任何编辑前请求许可 |
| Auto-edit | --auto-edit |
自动应用文件编辑，执行 Shell 命令前请求许可 |
| Full-auto | --full-auto |
自动执行一切（仅建议在沙箱环境中使用） |
# 使用 suggest 模式（最安全）
codex --suggest "refactor this function"
# 使用 auto-edit 模式
codex --auto-edit "add error handling to all API calls"
# 使用 full-auto 模式（请小心）
codex --full-auto "set up a new Express.js project with TypeScript"
基本用法
交互模式
在你的项目目录中启动交互式会话：
cd /path/to/your/project
codex
这将打开一个类似聊天的界面，你可以输入提示词，Codex 将读取你的文件、建议更改并执行命令。
单次命令 (One-Shot Commands)
在不进入交互模式的情况下发送单个提示词：
# 询问关于代码的问题
codex "what does the handleAuth function do?"
# 生成代码
codex "create a Python script that monitors CPU usage and sends a Slack alert when it exceeds 90%"
# 调试错误
codex "I'm getting a TypeError: Cannot read property 'map' of undefined in UserList.tsx. Fix it."
# 重构
codex "refactor the database queries in models/user.js to use prepared statements"
管道输入 (Piping Input)
通过管道将文件内容或命令输出传给 Codex：
# 解释错误日志
cat error.log | codex "explain what went wrong and how to fix it"
# 审查差异 (diff)
git diff | codex "review these changes for bugs or issues"
# 分析文件
cat src/utils/auth.ts | codex "are there any security vulnerabilities in this code?"
常见用例
1. 生成新文件
codex "create a REST API endpoint for user registration with:
- email/password validation
- bcrypt password hashing
- JWT token generation
- proper error handling
Save it as src/routes/auth.ts"
2. 调试错误
# 直接传递错误信息
codex "fix this error:
Error: ECONNREFUSED 127.0.0.1:5432
The PostgreSQL connection is failing in src/db/connection.ts"
3. 编写测试
codex "write unit tests for src/utils/validation.ts using Jest. Cover all edge cases."
4. 重构代码
codex "refactor src/components/Dashboard.tsx to:
1. Extract the chart logic into a custom hook
2. Add proper TypeScript types
3. Replace any with specific types"
5. 解释代码
codex "explain the authentication flow in this project. Walk through each file involved."
6. 编写文档
codex "generate JSDoc comments for all exported functions in src/utils/"
7. Shell 自动化
codex "write a bash script that:
1. Backs up the PostgreSQL database
2. Compresses the backup with gzip
3. Uploads it to S3
4. Deletes backups older than 30 days"
高级配置
使用不同的模型
# 对复杂任务使用 GPT-4o
codex --model gpt-4o "architect a microservices system for an e-commerce platform"
# 对快速任务使用 o4-mini (默认，更便宜)
codex --model o4-mini "fix the typo in the README"
自定义指令
创建一个项目特定的指令文件：
<!-- 项目根目录下的 codex.md -->
# Codex 指令
## 项目上下文
这是一个使用 TypeScript, Tailwind CSS 和 Prisma ORM 的 Next.js 15 应用程序。
## 编码标准
- 使用带有 hooks 的函数组件
- 所有函数必须有 TypeScript 类型
- 使用 Zod 进行运行时校验
- 遵循现有的文件命名规范 (kebab-case)
- 为所有新的工具函数编写测试
## 禁止事项
- 未经询问请勿修改数据库模式 (schema)
- 未经许可请勿安装新的依赖
- 请勿修改 .env 文件
在项目目录中工作时，Codex CLI 会自动读取此文件。
特定环境设置
# 使用 .env 为每个项目设置模型
echo 'CODEX_MODEL=gpt-4o' >> .env
# 为每个项目设置审批模式
echo 'CODEX_APPROVAL_MODE=auto-edit' >> .env
Codex CLI vs. Claude Code
两者都是基于终端的 AI 编程智能体。以下是它们的对比：
| 维度 | Codex CLI | Claude Code |
|---|---|---|
| 模型 | OpenAI (o4-mini, GPT-4o) | Claude (Sonnet, Opus) |
| 定价 | 按 Token 付费 (API) | 订阅制 ($20/月) 或 API |
| 开源 | 是 (Apache 2.0) | 否 |
| 沙箱 | 禁用网络连接的沙箱 | 基于权限 |
| 上下文窗口 | 最高 128K tokens | 最高 200K tokens |
| 文件编辑 | 基于 Diff 的补丁 | 内联编辑 |
| MCP 支持 | 受限 | 完全支持 |
| 适用人群 | OpenAI 生态用户 | Claude 生态用户 |
| 社区 | GitHub Issues | Anthropic 支持 |
何时使用 Codex CLI
- 你偏好 OpenAI 模型
- 你想要一个可以自行修改的开源工具
- 你需要 o4-mini 推理模型来处理复杂逻辑
- 你已经拥有 OpenAI API key
何时使用 Claude Code
- 你偏好 Claude 模型（特别是长上下文需求）
- 你需要 MCP 服务集成
- 你更喜欢订阅模式而非按量付费
- 你需要 Anthropic 的“扩展思考”功能处理复杂重构
成本管理
估算成本
| 模型 | 输入 (每 1M tokens) | 输出 (每 1M tokens) | 典型会话成本 |
|---|---|---|---|
| o4-mini | $1.10 | $4.40 | $0.05 - $0.50 |
| GPT-4o | $2.50 | $10.00 | $0.10 - $2.00 |
| GPT-4o-mini | $0.15 | $0.60 | $0.01 - $0.10 |
降低成本的技巧
- 大多数任务使用 o4-mini（默认选项）
- 提示词要具体，减少往返次数
- 在配置中设置 max_tokens 以限制响应长度
- 使用 suggest 模式在执行更改前进行审查（避免浪费重试次数）
- 在 OpenAI 控制面板中设置支出限额
故障排除
| 问题 | 解决方案 |
|---|---|
command not found: codex |
重新运行 npm install -g @openai/codex，检查你的 PATH 路径 |
OPENAI_API_KEY not set |
导出 Key：export OPENAI_API_KEY="sk-..." |
model not found |
检查你的 OpenAI 账户是否有权访问该模型 |
| 响应速度慢 | 切换到 o4-mini 或 gpt-4o-mini 以获得更快输出 |
| 文件编辑未生效 | 检查文件权限以及是否处于正确的目录 |
Node.js version too old |
升级到 Node.js 22+：nvm install 22 |
| 沙箱错误 | 尝试在沙箱外运行：codex --no-sandbox |
常见问题解答
Codex CLI 是免费的吗？ 工具本身是免费且开源的。你需要根据消耗的 Token 为 OpenAI API 的使用付费。
我可以在没有 OpenAI Key 的情况下使用 Codex CLI 吗？ 不行。Codex CLI 需要 OpenAI API key。如需免费替代方案，可考虑使用 Aider 配合 Google 或 Groq 的免费层级 API Key。
Codex CLI 可以在 Windows 上运行吗？ 不能原生运行。请使用 WSL (Windows Subsystem for Linux) 在 Windows 上运行它。
Codex CLI 可以修改我系统上的任何文件吗？ 在 suggest 模式（默认）下，它在进行任何更改前都会请求许可。在 full-auto 模式下，它会在禁用网络访问的沙箱环境中运行以保证安全。
它与 GitHub Copilot 相比如何？ Copilot 是一个用于提供内联建议的 IDE 扩展。Codex CLI 是一个用于处理复杂的、跨文件任务的终端智能体。它们用途不同，可以配合使用。
总结
如果你已经在使用 OpenAI 生态系统，Codex CLI 是一个非常可靠的终端 AI 编程智能体。其开源特性、沙箱安全功能以及对推理模型的支持，使其成为偏好在终端工作的开发者的有力选择。
如果你正在构建生成图像、视频或数字人的 AI 应用，免费试用 Hypereal AI —— 包含 35 个额度，无需信用卡。其 REST API 可以轻松集成到你使用 Codex CLI 构建的任何项目中。