codex 使用

目录

• Codex 使用指南
  • 一、快速安装
  • 二、核心概念速览
  • 三、权限模式：安全与效率的平衡
  • 四、新手第一步
    • 1. 先建独立项目目录
    • 2. 三个循序渐进的小任务
  • 五、实用技巧
    • ✅ 提示词三要素
    • ✅ 先要方案，再要实现
    • ✅ 用 /plan 命令梳理思路
    • ✅ 把长期规则沉淀到 AGENTS.md
    • ✅ 常用 Slash 命令（CLI & App 通用）
  • 六、典型使用场景
  • 七、避坑指南
  • 八、进阶入口

Codex 使用指南

Codex 是 OpenAI 推出的 AI 编程智能体，与传统代码补全工具不同，它能直接读取文件、修改代码、运行命令、执行测试，甚至发起 PR。以下从安装到实战，帮你快速上手。

---

一、快速安装

Codex 提供多种安装方式，选择最适合你的即可。

方式一：npm 安装（全平台通用，推荐）

npm install -g @openai/codex

方式二：macOS Homebrew

brew install --cask codex

方式三：桌面 App（新手最友好）

• 访问 OpenAI Codex 官网 下载对应系统版本
• 安装后用 ChatGPT 账号登录

安装完成后运行 codex --version 验证是否成功。首次启动需要完成 GitHub 授权（桌面 App）或登录认证（CLI）。

---

二、核心概念速览

概念	说明
Thread（线程）	一次完整对话会话，每个任务建议单独开线程，避免混乱
Project（项目）	绑定本地文件夹作为工作目录，Codex 在此范围内操作
Skills	可扩展的能力单元，类似给 AI 安装“自定义工具”
AGENTS.md	项目规则文件，Codex 每次启动会自动读取，用于统一代码规范

---

三、权限模式：安全与效率的平衡

Codex 提供三种权限级别，建议新手从保守模式开始：

模式	能力	适用场景
默认权限	读文件需确认，改文件/跑命令/联网需审批	刚上手、不熟悉时
自动审查（推荐）	低风险操作自动放行，高风险操作弹框确认	日常开发
完全访问	全自动执行，无确认	高度信任的练习项目

💡 桌面 App：左下角可直接切换权限模式
CLI：用 /permissions 命令切换

---

四、新手第一步

1. 先建独立项目目录

mkdir ~/codex-projects/my-first-project
cd ~/codex-projects/my-first-project
codex

⚠️ 不要在桌面或知识库目录直接操作，避免文件被“污染”。

2. 三个循序渐进的小任务

建议按以下顺序完成闭环，不要一上来就做大任务：

任务①——只调研（不修改任何文件）

“请总结这个仓库的目录结构和开发流程。先不要修改任何文件，只做调研。”

任务②——单文件小改动

“只修改 components/header.tsx，目标是缩小导航间距。不要改业务逻辑。”

任务③——加上验证环节

“修复这个失败的测试。修复后只运行相关测试，用 3 行说明改了什么。”

每轮完成务必先看 diff（差异面板）再决定是否接受改动。

---

五、实用技巧

✅ 提示词三要素

每个任务至少包含：

1. 允许改哪里——“只修改 src/ 目录下的文件”
2. 目标是什么——“让首屏加载时间减少 20%”
3. 明确不改什么——“不要新增依赖，不要动数据库逻辑”

✅ 先要方案，再要实现

“先用 3 步给出修复方案，确认后再执行实现。”

这个方法对 bug 修复和重构特别有效，能减少大量返工。

✅ 用 /plan 命令梳理思路

在真正改代码之前，先用 /plan 让 Codex 把步骤、边界、风险梳理清楚，对齐后再执行。

✅ 把长期规则沉淀到 AGENTS.md

在项目根目录创建 AGENTS.md，内容示例：

# 项目约定
- 代码风格：Python 用 Black，JS/TS 用 ESLint
- 测试：运行 `pytest tests/` 验证
- PR 标题格式：[Fix/Feat] 简短描述

Codex 每次启动会自动读取，不用反复在提示词里强调。

✅ 常用 Slash 命令（CLI & App 通用）

命令	功能
/status	查看当前余量和模型信息
/model	切换模型
/permissions	调整权限模式
/review	对当前改动做代码审查
/list	列出所有线程
/new	开启新线程

---

六、典型使用场景

场景①——理解陌生代码库

“请解释这个模块的职责和依赖关系。不要编辑任何文件。”

场景②——修复 bug

“npm test 报错 TypeError: Cannot read property 'map' of undefined，定位并修复，修复后只运行相关测试。”

场景③——审查 PR

“对这个分支相对 main 做 review，分别从安全、bug、可维护性三个角度给结论。”

场景④——生成测试

“为 src/utils/format.js 生成单元测试，使用 Jest，覆盖边界情况。”

---

七、避坑指南

常见问题	解决方案
文件到处乱放	每次新建独立项目目录，不要混在桌面
不看 diff 就接受改动	必做：每次改完先看差异面板
一个线程里做多件事	一个线程只做一件事（实现/测试/重构/文档各开一个）
提示词太模糊	写清楚“范围 + 目标 + 约束”
WSL 路径问题	项目放在 WSL 的 Linux 文件系统（/home/），不要放 /mnt/c/
额度查询	用 /status 查看 5 小时和 1 周余量

---

八、进阶入口

熟悉基础后，可以继续探索：

• Skills：创建自定义能力（如“浏览器调用”“API 集成”）
• 工作树（Worktree）：多线程并行处理同一仓库而不冲突
• 云线程：把任务丢到云端远程执行，支持 GitHub 仓库直接操作
• Exec 模式：无交互自动化，适合 CI/CD 场景

codex exec "运行 npm test 并修复所有失败的测试用例"