OpenAI Codex CLI 常用技巧大全：从入门到高效实战
·
OpenAI Codex CLI 常用技巧大全：从入门到高效实战
导读：Codex CLI 是 OpenAI 推出的开源终端 AI 编程助手，能直接在你的项目目录中读取代码、执行命令、修改文件，甚至参与重构和调试。本文整理了 Codex CLI 最实用的使用技巧，涵盖安装配置、提示词工程、工作流优化、高级功能等，帮助你快速将 Codex 融入日常开发。
一、快速安装与认证
1.1 一行命令安装
# npm 全局安装（推荐）
npm install -g @openai/codex@latest
# macOS 也可用 Homebrew
brew install --cask codex
# 国内用户加速安装
npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com
环境要求：Node.js ≥ 22，Git。
1.2 两种认证方式
# 方式一：ChatGPT 账号登录（推荐，浏览器自动弹出授权页）
codex login
# 方式二：API Key 认证
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
将 API Key 写入 Shell 配置文件可永久生效：
echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
1.3 验证安装
codex --version
二、核心使用模式：命令式 vs 交互式
2.1 命令模式（一次性调用）
适合快速任务、脚本和 CI 流程：
# 直接提问，执行完即退出
codex "帮我写一个 Java 的 JSON 解析工具类"
# 全自动模式（自动读写文件，谨慎使用）
codex -a never "修复 UserService 中的空指针异常"
# 非交互模式（适合 CI/CD）
codex exec "运行所有单元测试并输出报告"
# 指定模型
codex -m gpt-5.4 "分析这段代码的性能瓶颈"
2.2 交互模式（推荐日常使用）
交互模式才是 Codex 的核心能力，支持上下文记忆和连续任务：
# 启动交互式 TUI
codex
# 带初始提示启动
codex "帮我分析这个项目的架构"
进入后可连续下达多步任务：
> 分析这个项目的代码结构
> 给 UserService 加上 Redis 缓存
> 写单元测试
> 跑测试并修复失败用例
💡 核心建议：命令模式是"调用 AI"，交互模式才是"雇佣 AI"。日常开发优先使用交互模式。
三、提示词工程：四要素法则
OpenAI 官方推荐的提示词四要素结构：
3.1 四要素模板
1. 目标：你想要改变什么或构建什么？
2. 上下文：哪些文件与此任务相关？（使用 @ 引用文件）
3. 约束：必须遵守的架构规则、安全要求或性能指标
4. 输出格式：你希望以什么形式呈现结果？
3.2 实战示例
❌ 差的提示词：
写个登录接口
✅ 好的提示词：
创建一个用户登录接口，要求：
1. 目标：基于 Spring Boot + MyBatis Plus 实现用户登录验证
2. 上下文：参考 @UserController 和 @AuthService 的现有风格
3. 约束：使用 JWT Token 认证，密码 BCrypt 加密，遵循 RESTful 规范
4. 输出：包含 Controller、Service、Entity 完整代码
3.3 使用 @ 引用文件
在交互模式中输入 @ 会触发文件模糊搜索，可以快速引用项目中的文件作为上下文：
> 参考 @UserService.java 的风格，重写 @OrderService.java
四、三级权限控制：安全与效率的平衡
Codex 提供四种审批模式（Approval Mode），通过 --ask-for-approval 或 -a 参数控制：
| 模式 | 参数 | 说明 | 适用场景 |
|---|---|---|---|
| 默认（不信任） | -a untrusted |
对不可信操作需审批（默认） | 日常开发 |
| 仅失败时 | -a on-failure |
命令执行失败时才询问 | 半自动化开发 |
| 按需审批 | -a on-request |
按请求进行审批 | 经验丰富的开发者 |
| 全自动（永不询问） | -a never |
从不询问，自动执行所有操作 | CI/CD、容器内运行 |
# 默认模式：不可信操作需审批
codex -a untrusted "审查这段代码的安全漏洞"
# 全自动模式：永不询问（谨慎使用）
codex -a never "重构所有 Controller 的返回值类型"
⚠️ 重要提醒：
never模式下 Codex 会自动执行所有命令而不询问，建议仅在受控环境（Docker/VM）中使用。
五、AGENTS.md：让 Codex 真正懂你的项目
AGENTS.md 是 Codex 的项目级指令文件，类似于给 AI 写的"开发手册"。Codex 会按层级自动加载并合并：
5.1 三级加载机制
1. ~/.codex/AGENTS.md → 全局个人偏好（所有项目共享）
2. 项目根目录/AGENTS.md → 团队共享的项目规范
3. 当前目录/AGENTS.md → 子模块/功能的特定指令
5.2 实战配置示例
全局配置（~/.codex/AGENTS.md）：
## 工作约定
- 提交 PR 前必须运行测试
- 优先使用 pnpm 而非 npm
- 添加新依赖前先询问
- 代码注释使用中文
项目级配置（项目根目录 AGENTS.md）：
## 项目规范
- 技术栈：Spring Boot 2.7 + MyBatis Plus + JDK 1.8
- 运行测试：mvn test
- 任何面向用户的变更必须更新 CHANGELOG.md
- 禁止直接修改数据库表结构，必须通过 Flyway 迁移脚本
- API 文档使用 Swagger 注解
5.3 兼容其他 AI 工具的指令文件
如果你的项目已经有 CLAUDE.md、TEAM_GUIDE.md 等文件，可以在 config.toml 中配置兼容：
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", "CONTRIBUTING.md", "CLAUDE.md"]
六、config.toml 核心配置技巧
配置文件路径：~/.codex/config.toml
6.1 推荐配置模板
# 交互风格：pragmatic（务实）/ concise（简洁）
personality = "pragmatic"
# 默认模型
model = "gpt-5.3"
# 推理强度：low / medium / high / xhigh
reasoning_effort = "medium"
# 项目信任级别
[projects."/Users/yourname/projects/myapp"]
trust_level = "trusted"
6.2 配置自定义模型提供商
model_provider = "custom-provider"
model = "my-model"
[model_providers.custom-provider]
name = "My Custom Provider"
base_url = "http://127.0.0.1:8080/v1"
env_key = "CUSTOM_API_KEY"
wire_api = "responses"
6.3 MCP 服务器配置
[mcp_servers.sequential-thinking]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
[mcp_servers.memory]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]
七、会话管理技巧
7.1 恢复历史会话
# 打开会话选择器
codex resume
# 恢复最近的会话
codex resume --last
# 按 ID 恢复指定会话
codex resume 7f9f9a2e-1b3c-4c7a-9b0e-123456789abc
# 以分支方式恢复（不影响原会话）
codex resume --last --fork
7.2 交互模式内置命令
在交互模式中输入 / 可查看所有支持的命令：
| 命令 | 功能 |
|---|---|
/status |
查看当前状态：模型、权限级别、上下文信息 |
/approvals |
管理权限审批策略 |
/mcp |
管理 MCP 服务器连接 |
/model <模型名> |
切换模型 |
/new |
开启新对话线程 |
/list |
列出所有线程 |
/permissions |
切换权限模式 |
/memories |
管理记忆功能 |
/init |
自动生成 AGENTS.md |
/review |
让第二个 AI Agent 审计变更 |
7.3 编辑已发送的消息
当输入框为空时，按 Esc 进入"回溯"模式，可以编辑之前发送的消息。
八、三大实战工作流
8.1 端到端功能开发
> 在 billing 页面添加"下载发票 PDF"按钮，对接 /invoices/:id/pdf 接口，并编写测试
Codex 会自动完成：创建按钮组件 → 编写对接逻辑 → 生成测试文件 → 运行测试验证。
8.2 大型重构的分步执行
第一步 — 仅规划：
> 扫描整个仓库，列出将邮件发送逻辑抽取为独立模块的具体步骤。先不要修改任何文件。
第二步 — 逐步执行：
> 执行第 1 步，完成后运行测试并展示 diff
💡 对于大型重构，让 Codex 先"规划"再"执行"，避免一步到位导致的不可控修改。
8.3 自动调试与修复
> 运行所有 Python 测试，找到失败的用例并修复它们。在修改文件前先说明修改原因。
Codex 会自动：运行测试 → 定位失败用例 → 分析原因 → 提出修复方案 → 执行修复 → 重新验证。
九、高级技巧
9.1 使用 CODEX_HOME 隔离环境
通过环境变量可以为不同项目创建完全独立的 Codex 环境：
# 个人开发环境
export CODEX_HOME="$HOME/.codex"
# CI/CD 自动化环境
export CODEX_HOME="$HOME/.codex-ci"
每个 CODEX_HOME 拥有独立的配置、历史记录、MCP 服务器和 AGENTS.md。
9.2 Profile 一键切换配置
# 使用预定义的 profile 启动
codex --profile focus "完成用户模块开发"
# 在 config.toml 中定义 profile
[profiles.focus]
model = "gpt-5.4"
reasoning_effort = "high"
approval_mode = "auto-edit"
9.3 非交互模式用于 CI/CD
# CI 环境中自动执行任务
codex exec "运行 lint 检查并修复所有可自动修复的问题"
# 输出 JSON 格式结果
codex exec --json "检查代码覆盖率是否达标"
9.4 推理强度选择
| 强度 | 适用场景 |
|---|---|
low |
简单问答、格式化、小修改 |
medium（推荐） |
日常开发，平衡速度与质量 |
high |
复杂重构、架构设计 |
xhigh |
极度复杂的任务 |
codex --reasoning-effort high "重构整个支付模块的异常处理逻辑"
9.5 两种协作个性
在 config.toml 中设置 personality：
pragmatic（务实）：详细解释，适合学习和理解concise（简洁）：直接给出结果，适合高效开发
十、快捷命令速查表
10.1 CLI 启动参数
codex # 启动交互式 TUI
codex "任务描述" # 带初始提示启动
codex exec "任务" # 非交互模式
codex resume # 恢复会话选择器
codex resume --last # 恢复最近的会话
codex -m gpt-5.4 "任务" # 指定模型
codex --profile focus "任务" # 使用指定 Profile
codex -a never "任务" # 全自动模式（永不询问）
codex --cwd /path/to/project "任务" # 指定工作目录
codex completion bash # 生成 Shell 补全脚本
10.2 交互模式快捷键
| 快捷键 | 功能 |
|---|---|
Enter |
发送消息 |
Ctrl+C |
取消当前操作 |
Ctrl+D |
退出 Codex |
↑ / ↓ |
浏览历史消息 |
@ |
触发文件模糊搜索 |
Esc（输入框为空时） |
进入回溯模式，编辑已发送消息 |
10.3 交互模式斜杠命令
| 命令 | 功能 |
|---|---|
/status |
查看当前状态 |
/init |
生成 AGENTS.md |
/review |
AI 审计当前变更 |
/model <名称> |
切换模型 |
/new |
新建对话线程 |
/list |
列出所有线程 |
/approvals |
管理权限 |
/mcp |
管理 MCP 连接 |
/memories |
管理记忆 |
十一、常见问题与排查
11.1 环境变量未生效
# 检查环境变量
echo $OPENAI_API_KEY
# 如果为空，手动设置并刷新
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"
source ~/.zshrc
11.2 macOS 提示"恶意软件已阻止"
旧版 Codex 二进制文件未经过 Apple 公证，解决方式：
# 方式一：使用最新版（已签名）
npm install -g @openai/codex@latest
# 方式二：手动签名
codesign --force --deep -s - /path/to/codex/binary
11.3 模型元数据警告
出现 Model metadata for 'xxx' not found 是正常警告，Codex 会使用默认配置，不影响使用。
11.4 Git 脏工作区处理
Codex 在有未提交更改的工作区中也能正常工作，但建议在执行大规模修改前先 git stash 或创建新分支：
git checkout -b codex-refactor
codex "重构用户认证模块"
十二、最佳实践总结
| 技巧 | 说明 |
|---|---|
| 优先交互模式 | 交互模式有上下文记忆，支持连续迭代 |
| 善用 AGENTS.md | 将团队规范写入项目级 AGENTS.md，减少重复说明 |
| 提示词四要素 | 目标 + 上下文 + 约束 + 输出格式 |
用 @ 引用文件 |
精确指定上下文，避免 AI 猜测 |
| 重构先规划 | 大型任务分步执行，先规划后行动 |
| Git 分支保护 | 在新分支上执行 AI 修改，方便回滚 |
| 合理选择推理强度 | 日常用 medium，复杂任务用 high |
| CI 用非交互模式 | codex exec 适合自动化流水线 |
| CODEX_HOME 隔离 | 不同项目/场景使用独立配置环境 |
/review 双重检查 |
用第二个 AI Agent 审计变更，提升代码质量 |
参考链接
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
7
0- 0
已为社区贡献5条内容
所有评论(0)