Codex CLI 使用技巧
Codex CLI 是 OpenAI 推出的命令行 AI 编程助手，它可以直接在终端中运行，帮助你完成各种编程任务。与 ChatGPT 网页版不同，Codex CLI 可以直接读写文件、执行命令，并深度理解你的项目代码。本文将详细介绍 Codex CLI 的安装、配置和使用技巧。
1. 安装和配置
1.1 安装 Codex CLI
Codex CLI 可以通过 npm 安装：
# 全局安装
npm install -g @openai/codex
# 或使用 yarn
yarn global add @openai/codex也可以使用 Homebrew 安装（macOS）：
brew install codex1.2 配置 API 密钥
安装完成后，需要配置 OpenAI API 密钥：
# 设置环境变量
export OPENAI_API_KEY="your-api-key-here"或者在配置文件中设置：
# 创建配置目录
mkdir -p ~/.config/codex
# 创建配置文件
cat > ~/.config/codex/config.json << 'EOF'
{
"api_key": "your-api-key-here",
"model": "gpt-4o"
}
EOF1.3 验证安装
运行以下命令验证安装是否成功：
codex --version2. 基本使用
2.1 启动交互式会话
在项目根目录运行 codex 命令启动交互式会话：
codex启动后，你可以直接输入自然语言描述你的需求，例如：
帮我创建一个简单的 REST API2.2 执行单次查询
使用 -p 参数执行单次查询并退出：
codex -p "解释一下这个项目的结构"2.3 命令行参数
| 参数 | 说明 | 示例 |
|---|---|---|
-p, --prompt | 执行单次查询 | codex -p "解释代码" |
-d, --directory | 指定工作目录 | codex -d /path/to/project |
-m, --model | 指定使用的模型 | codex -m gpt-4o |
--verbose | 显示详细日志 | codex --verbose |
--version | 显示版本号 | codex --version |
--help | 显示帮助信息 | codex --help |
2.4 会话内命令
在交互式会话中可以使用的命令：
| 命令 | 说明 | 示例 |
|---|---|---|
/clear | 清除当前会话历史 | /clear |
/exit | 退出会话 | /exit |
/help | 显示帮助信息 | /help |
/save <file> | 保存会话到文件 | /save session.json |
/load <file> | 加载历史会话 | /load session.json |
/model | 查看/切换模型 | /model gpt-4o |
/status | 显示当前状态 | /status |
3. 模型配置
3.1 支持的模型
Codex CLI 支持多种 OpenAI 模型：
| 模型 | 说明 | 适用场景 |
|---|---|---|
gpt-4o | 最新旗舰模型 | 复杂任务、代码生成 |
gpt-4o-mini | 轻量级模型 | 简单任务、快速响应 |
gpt-4-turbo | 高性能模型 | 大型项目、复杂推理 |
gpt-3.5-turbo | 经济型模型 | 日常任务、成本敏感 |
3.2 切换模型
在会话中切换模型：
/model gpt-4o或者通过命令行参数指定：
codex -m gpt-4o-mini -p "优化这段代码"3.3 自定义端点
如果使用兼容 OpenAI API 的第三方服务：
export OPENAI_BASE_URL="https://your-custom-endpoint.com/v1"
export OPENAI_API_KEY="your-api-key"4. 高级使用技巧
4.1 项目上下文理解
Codex CLI 会自动读取项目中的文件来理解上下文。为了更好地利用这个功能：
4.1.1 创建项目说明文件
在项目根目录创建 README.md 或 PROJECT.md，描述项目结构和技术栈：
# 项目概述
这是一个基于 Node.js 的 REST API 项目...
## 技术栈
- Node.js 18
- Express.js
- PostgreSQL
## 目录结构
- `src/`: 源代码
- `tests/`: 测试代码
- `config/`: 配置文件4.1.2 使用 .codexignore 排除文件
创建 .codexignore 文件排除不需要读取的文件：
node_modules/
*.log
dist/
build/
.env4.2 多文件操作
4.2.1 批量读取文件
在对话中明确指定要读取的文件：
请读取 src/models/User.js 和 src/controllers/UserController.js，分析它们的关系4.2.2 创建多个文件
创建一个完整的用户模块，包括：
- User 模型
- UserController 控制器
- UserService 服务层
- 用户路由4.3 代码执行和验证
Codex CLI 可以执行 shell 命令来验证代码：
帮我修复这个编译错误，然后运行 npm test 验证安全提示：Codex CLI 在执行命令前会请求确认，确保你了解命令的作用。
4.4 会话管理
4.4.1 保存重要对话
使用 /save 命令保存当前会话：
/save important-session.json4.4.2 加载历史会话
/load important-session.json5. 实际应用场景
5.1 代码生成
创建一个 Express.js 的 REST API，包括：
- 用户注册和登录
- JWT 认证
- 密码加密
- 错误处理5.2 代码重构
这个函数有 200 行代码，太长了。请帮我：
1. 分析职责划分
2. 提出拆分建议
3. 逐步执行重构5.3 Bug 调试
这个测试失败了，请帮我分析原因：
1. 查看错误日志
2. 定位问题代码
3. 提出修复方案
4. 验证修复结果5.4 代码审查
请审查这段代码，找出潜在的问题：
1. 检查是否有安全漏洞
2. 检查异常处理是否完善
3. 检查是否有性能问题
4. 提出改进建议5.5 文档生成
根据代码生成 API 文档：
- 提取所有路由
- 说明请求参数和响应格式
- 添加使用示例5.6 测试生成
为 UserService 类生成单元测试，要求：
- 使用 Jest 框架
- 覆盖所有公共方法
- 包括边界条件测试6. 最佳实践
6.1 提示词技巧
具体明确：不要说"修复这个 bug"，而要说"修复 TypeError，发生在第 42 行的 user.name 属性"
分步执行：复杂任务分解成多个小步骤
第一步：分析代码结构 第二步：提出改进建议 第三步：执行重构提供上下文：告诉 AI 项目的技术栈和约束条件
使用代码块：对于复杂的代码，使用代码块格式
6.2 安全注意事项
- 审查所有改动：在提交前仔细检查 AI 生成的代码
- 敏感信息保护：不要在对话中暴露 API 密钥、数据库密码等
- 命令执行确认：仔细审查要执行的命令，特别是 rm、chmod 等危险操作
- 使用 .codexignore：排除敏感文件和目录
6.3 成本控制
- 使用合适的模型：简单任务使用
gpt-4o-mini，复杂任务使用gpt-4o - 精简上下文：只包含必要的文件
- 复用会话：在同一会话中继续任务，避免重复发送上下文
- 设置 max_tokens：限制响应长度
6.4 项目组织
- 保持项目结构清晰：便于 AI 理解项目
- 编写清晰的注释：帮助 AI 理解代码意图
- 使用类型定义：TypeScript 项目使用类型定义
- 维护 README：保持文档更新
7. 常见问题
7.1 模型响应慢
- 检查网络连接
- 尝试使用更小的模型（
gpt-4o-mini） - 减少上下文文件大小
- 检查 API 配额
7.2 API 调用失败
# 检查 API 密钥是否正确
echo $OPENAI_API_KEY
# 检查端点是否可达
curl -I https://api.openai.com/v1/models
# 查看详细日志
codex --verbose7.3 模型不理解项目
- 确保在项目根目录运行
- 创建清晰的项目说明文档
- 主动提供相关文件路径
- 使用
.codexignore排除无关文件
7.4 文件读取失败
- 检查文件路径是否正确
- 确认文件权限
- 检查
.codexignore配置
8. 与其他工具对比
8.1 Codex CLI vs Claude Code
| 特性 | Codex CLI | Claude Code |
|---|---|---|
| 开发商 | OpenAI | Anthropic |
| 默认模型 | GPT-4o | Claude 3.5 Sonnet |
| 安装方式 | npm/brew | curl 脚本 |
| 配置文件 | ~/.config/codex/config.json | ~/.claude/config.json |
| 忽略文件 | .codexignore | .kilocodeignore |
8.2 Codex CLI vs GitHub Copilot
| 特性 | Codex CLI | GitHub Copilot |
|---|---|---|
| 使用方式 | 命令行工具 | IDE 插件 |
| 交互模式 | 对话式 | 补全式 |
| 文件操作 | 直接读写 | 通过 IDE |
| 命令执行 | 支持 | 不支持 |
9. 总结
Codex CLI 是一个强大的命令行 AI 编程助手，通过合理配置和使用技巧，可以显著提高开发效率。
核心要点：
- 灵活配置：支持多种模型和自定义端点
- 深度集成：可以直接读写文件、执行命令
- 安全可控：所有操作都会请求确认
- 场景广泛：适用于代码生成、重构、调试、文档等多种场景
- 成本可控：可以根据任务复杂度选择合适的模型
推荐配置：
# 设置 API 密钥
export OPENAI_API_KEY="sk-..."
# 生产环境使用 GPT-4o
codex -m gpt-4o
# 开发测试使用 GPT-4o-mini
codex -m gpt-4o-mini常用命令速查：
# 启动交互式会话
codex
# 执行单次查询
codex -p "解释这段代码"
# 指定模型
codex -m gpt-4o -p "优化这段代码"
# 指定工作目录
codex -d /path/to/project
# 保存/加载会话
/save session.json
/load session.json通过掌握这些技巧，你可以让 Codex CLI 更好地服务于你的开发工作流，提高编程效率和代码质量。
Related Articles
2026-02-19
Claude Code
Claude Code 是 Anthropic 推出的命令行 AI 编程助手，它可以理解你的代码库、执行命令、读写文件，并协助你完成各种开发任务。本文将详细介绍 Claude Code 的使用方法，特别是如何配合自定义模型使用。 1. 安装和配置 1.1 安装 Claude Code Claude Code 原生安装使用了 bun 打包的，性能更好： curl -fsSL https://claude.ai/install.sh | bash 安装完成后，需要配置 API 密钥： claude # 首次运行会提示输入 API 密钥 或者通过环境变量设置： export ANTHROPIC_API_KEY="your-api-key-here" 1.2 验证安装 运行以下命令验证安装是否成功： claude --version 2. 基本使用 2.1 启动交互式会话 在项目根目录运行 claude 命令启动交互式会话： claude 启动后，你可以直接输入自然语言描述你的需求，例如： 帮我创建一个简单的 HTTP 服务器 2.2 执行单次查询 使用 -p 参数执行单次查询并退出： ...
2026-03-07
OpenCode 架构详解
OpenCode 是一个开源的 AI 编程助手，类似于 Claude Code，使用 TypeScript 开发。本文将深入分析 OpenCode 的架构设计，帮助你理解其内部工作原理。 1. 整体架构概览 OpenCode 采用模块化的分层架构设计，主要由以下几个核心组件构成： ┌─────────────────────────────────────────────────────────────┐ │ CLI Interface │ ├─────────────────────────────────────────────────────────────┤ │ Session Manager │ ├─────────────────────────────────────────────────────────────┤ │ ┌──────────────┐ ┌────────────...