logo
Zihuatanejo
banner
NEWS LETTER

Codex CLI 详细使用流程

Scroll down

一、Codex CLI 是什么

Codex CLI 是 OpenAI Codex 的命令行工具，适合在本地终端里处理真实代码仓库中的开发任务。它可以读取当前项目、执行命令、修改文件、运行测试、解释代码、做代码审查，并且会根据权限配置决定什么时候直接执行、什么时候向你确认。

简单理解：

  • 在 IDE 中写代码时，可以把 Codex CLI 当成一个“终端里的结对编程助手”。
  • 在已有项目中排查问题时，可以让它先阅读代码，再给出修改方案并直接落地。
  • 在重复性任务中，可以用非交互命令让它批量完成检查、重构、生成文档等工作。

二、安装前准备

2.1 基础环境

建议先准备好：

  • Node.js：建议安装当前 LTS 版本。
  • npm：Node.js 自带。
  • Git：用于项目版本管理。
  • 一个 OpenAI / ChatGPT 账号，或者 OpenAI API Key。
  • 一个可以正常构建、测试的本地代码项目。

检查命令：

1
2
3
node -v
npm -v
git --version

2.2 安装 Codex CLI

使用 npm 全局安装：

1
npm install -g @openai/codex

安装完成后检查版本：

1
codex --version

如果你不想全局安装，也可以用 npx 临时运行：

1
npx @openai/codex --version

2.3 Windows 注意事项

在 Windows 上推荐使用 WSL2 运行 Codex CLI。原因是很多项目的构建、脚本、Git 行为在 Linux 环境下更稳定，Codex 也更容易和常见开发工具链配合。

如果使用 WSL2：

1
2
3
sudo apt update
sudo apt install -y nodejs npm git
npm install -g @openai/codex

三、登录和认证

Codex CLI 常见有两种认证方式。

3.1 使用 ChatGPT 账号登录

1
codex login

执行后按终端提示在浏览器中完成授权。

适合场景：

  • 你主要使用 ChatGPT 账号。
  • 你希望本地 CLI 使用账号授权。
  • 你不想在本机长期保存 API Key。

3.2 使用 API Key

也可以通过环境变量提供 API Key：

1
export OPENAI_API_KEY="你的 API Key"

为了长期生效，可以把它写入 shell 配置文件，例如 ~/.bashrc、~/.zshrc：

1
2
echo 'export OPENAI_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

注意：不要把 API Key 写进项目代码、README、.env.example、截图或提交记录中。

四、在项目中启动 Codex

进入你的项目目录：

1
cd /path/to/your/project

启动交互式 Codex：

1
codex

第一次进入一个项目时，Codex 通常会确认当前目录是否可信。只有你确认之后，它才适合读取项目、执行命令、修改文件。

建议第一次提问时先让它熟悉项目：

1
请先阅读这个项目的结构，说明主要模块、启动方式、测试命令和部署方式，不要修改代码。

这样做的好处是先建立上下文，避免一上来就让它盲目修改。

五、常用交互方式

5.1 让 Codex 解释项目

1
请阅读这个仓库，说明它的技术栈、目录结构、核心入口文件和本地运行方式。

适合刚接手新项目时使用。

5.2 让 Codex 修复 Bug

1
登录接口在 token 过期后没有自动刷新，请定位原因并修复。修改完成后运行相关测试。

建议把现象、期望结果、复现步骤都写清楚：

1
2
3
4
5
6
7
复现步骤：
1. 登录成功后等待 token 过期
2. 访问 /api/user/profile
3. 页面直接跳回登录页

期望结果：
token 过期时先调用刷新接口，刷新失败后再跳转登录。

5.3 让 Codex 新增功能

1
2
3
4
5
给文章列表增加按标签筛选功能，要求：
1. URL 支持 ?tag=xxx
2. 页面刷新后保留筛选状态
3. 增加必要测试
4. 保持现有 UI 风格

需求越具体，结果越稳定。复杂功能建议拆成多轮：

  • 第一轮：让 Codex 阅读相关代码并给方案。
  • 第二轮：确认方案后再实现。
  • 第三轮：运行测试并修复问题。

5.4 让 Codex 做代码审查

可以直接在交互模式中说：

1
请 review 当前工作区的改动，重点关注潜在 bug、边界条件和测试缺失。

也可以使用命令模式：

1
codex review

代码审查时建议让它优先输出问题，而不是先总结优点：

1
请按严重程度列出 review 发现，必须包含文件和行号；如果没有问题，请说明剩余风险。

5.5 让 Codex 生成文档

1
2
3
4
5
6
7
请根据当前项目生成一份 README，包含：
1. 项目简介
2. 环境要求
3. 安装依赖
4. 本地启动
5. 测试命令
6. 构建和部署

如果是写技术博客、接口文档、迁移说明，也可以让它直接输出 Markdown。

六、常用命令

6.1 交互模式

1
codex

进入后可以连续对话，适合开发、调试、重构、解释代码。

6.2 非交互执行

1
codex exec "修复当前项目中的 lint 错误，并运行测试"

适合一次性任务、脚本化任务、CI 辅助任务。

常见用法：

1
2
3
codex exec "阅读 package.json，说明这个项目如何启动和测试"
codex exec "为 src/utils/date.ts 增加单元测试"
codex exec "检查当前 git diff，找出可能的 bug"

6.3 恢复会话

如果之前的上下文还需要继续，可以恢复会话：

1
codex resume

适合长任务中断后继续，例如前面已经分析过项目结构、制定过方案，不想重新解释一遍。

6.4 查看帮助

1
codex --help

某个子命令的帮助：

1
2
codex exec --help
codex review --help

七、权限、沙箱和确认机制

Codex CLI 的一个重要概念是：它不应该默认拥有无限制权限。实际使用中要理解三个层面。

7.1 文件读写权限

Codex 会读取当前项目文件，必要时修改文件。一般建议：

  • 只在可信项目目录中运行。
  • 让项目保持 Git 管理。
  • 修改前先看 git status。
  • 修改后用 git diff 检查。

7.2 命令执行权限

Codex 可能会运行命令，例如：

1
2
3
4
npm test
npm run build
git diff
rg "keyword"

对于安装依赖、访问网络、删除文件、发布部署等高风险动作，建议保持确认机制，不要长期设置成完全自动。

7.3 网络权限

如果任务需要查询外部文档、下载依赖、访问包管理器，Codex 可能需要网络权限。你应该确认：

  • 这个网络访问是否真的必要。
  • 是否会上传敏感代码或配置。
  • 是否只是访问官方文档、npm、GitHub 等可信来源。

八、配置文件 config.toml

Codex CLI 可以通过配置文件保存默认行为。常见位置是：

1
~/.codex/config.toml

也可能在项目中使用 .codex/config.toml 保存项目级配置。

示例：

1
2
3
4
5
6
model = "你的可用 Codex 模型"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[projects."/path/to/your/project"]
trust_level = "trusted"

说明：

  • model：指定默认模型。可根据账号可用模型调整。
  • approval_policy：控制什么时候需要用户确认。
  • sandbox_mode：控制文件和命令的隔离程度。
  • projects：保存特定项目的信任配置。

如果不确定怎么配置，建议先使用默认值，只在遇到明确需求时再调整。

九、AGENTS.md 项目说明

如果一个项目长期使用 Codex，建议在仓库根目录新增 AGENTS.md，把项目规则写清楚。

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# AGENTS.md

## 项目命令

- 安装依赖：npm install
- 本地启动：npm run dev
- 单元测试：npm test
- 构建：npm run build

## 代码规范

- 优先使用 TypeScript。
- 新增功能必须补充测试。
- 不要修改 public 目录中的构建产物。
- 提交前必须运行 npm test。

## 注意事项

- API Key 只能从环境变量读取。
- 不要提交 .env 文件。
- UI 改动需要保持现有设计风格。

AGENTS.md 适合保存项目长期规则，例如构建命令、测试命令、代码风格、禁止修改的目录、部署注意事项等。

十、推荐工作流

10.1 修改前

先确认工作区状态：

1
git status

如果当前有未提交代码，先明确哪些是自己的改动，避免让 Codex 覆盖未完成内容。

然后启动：

1
codex

先让 Codex 读项目：

1
请先阅读项目结构和关键配置，告诉我启动、测试、构建命令，不要修改代码。

10.2 修改中

给任务时尽量包含：

  • 背景：为什么要改。
  • 目标：最终要达到什么效果。
  • 范围：哪些文件或模块可以改。
  • 限制：哪些行为不能变。
  • 验证：改完要跑什么命令。

示例：

1
2
3
请修复移动端菜单点击后无法关闭的问题。
范围限制：优先修改 Header 组件，不要重构路由。
验证方式：运行 npm test 和 npm run build。

10.3 修改后

让 Codex 总结：

1
请总结你修改了哪些文件、解决了什么问题、运行了哪些验证命令。

自己再检查：

1
2
3
git diff
npm test
npm run build

最后提交：

1
2
git add .
git commit -m "fix: close mobile menu after navigation"

十一、常见任务模板

11.1 排查构建失败

1
npm run build 失败了。请先运行构建命令，阅读错误信息，定位根因并修复。修改后重新运行构建。

11.2 增加测试

1
请为 userService 增加单元测试，覆盖成功、失败、空数据和异常返回。保持现有测试框架和命名风格。

11.3 重构代码

1
请重构订单金额计算逻辑，目标是降低重复代码并保持行为不变。先阅读现有测试，重构后必须运行测试。

11.4 写发布说明

1
请根据当前 git diff 生成一份发布说明，包含新增功能、问题修复、兼容性影响和测试结果。

11.5 生成提交信息

1
请根据当前 git diff 生成 3 个符合 Conventional Commits 的提交信息，我会从中选择一个。

十二、排错

12.1 command not found: codex

原因通常是 npm 全局 bin 目录不在 PATH 中。

检查：

1
npm config get prefix

把输出目录下的 bin 加入 PATH，例如：

1
export PATH="$(npm config get prefix)/bin:$PATH"

12.2 登录失败

可以尝试：

1
2
codex logout
codex login

如果使用 API Key，确认环境变量是否存在：

1
echo $OPENAI_API_KEY

不要直接把真实 Key 输出到截图或日志里。

12.3 模型不可用

如果配置了固定模型但账号没有权限，可能会报模型不可用。处理方式：

  • 删除配置里的 model，使用默认模型。
  • 或改成当前账号可用的 Codex 模型。
  • 或在 ChatGPT / OpenAI 平台确认账号权限。

12.4 Codex 修改了不该修改的文件

先不要慌，使用 Git 检查：

1
2
git status
git diff

如果只是想撤销某个文件：

1
git restore path/to/file

如果文件中既有你的改动又有 Codex 的改动，不要直接恢复整个文件，应该手动挑选需要保留的部分。

12.5 任务执行到一半中断

可以尝试恢复：

1
codex resume

也可以重新打开 Codex，把当前状态说明清楚：

1
刚才任务中断了。请先查看 git status 和相关文件，继续完成未完成的修改，并说明你接下来要做什么。

十三、安全建议

  • 始终在 Git 仓库里使用 Codex。
  • 复杂修改前先提交或 stash 当前工作。
  • 不要把密钥、证书、生产数据库地址交给 Codex 处理。
  • 发布、删除、迁移数据等高风险命令必须人工确认。
  • 让 Codex 运行测试，但不要完全依赖它判断业务正确性。
  • 代码审查时要求它指出文件和行号，方便你复核。
  • 长期项目建议维护 AGENTS.md，减少重复说明。

十四、一个完整示例

下面是一套比较稳妥的真实使用流程。

进入项目：

1
2
3
cd ~/work/my-app
git status
codex

让 Codex 先读项目：

1
请阅读项目结构，找出启动、测试、构建命令，并说明主要业务模块。不要修改代码。

提出任务：

1
2
3
4
5
6
请修复用户资料页刷新后偶尔显示空白的问题。
要求：
1. 先定位原因
2. 保持现有 UI 样式
3. 增加必要的边界处理
4. 修改后运行测试和构建

查看结果：

1
请总结修改内容、影响范围和验证结果。

本地复核：

1
2
3
git diff
npm test
npm run build

提交：

1
2
git add .
git commit -m "fix: handle empty profile state after refresh"

十五、参考资料

其他文章
cover
Linux开发
Linux 应用开发入门
  • 26/06/21
  • 11:08
cover
博客建站
Hello World
  • 26/06/20
  • 17:00
© 2019 - 2026 Zihuatanejo
由 Hexo 驱动 v7.3.0 主题 - Async v2.2.7
目录导航 置顶
  1. 1. 一、Codex CLI 是什么
  2. 2. 二、安装前准备
    1. 2.1. 2.1 基础环境
    2. 2.2. 2.2 安装 Codex CLI
    3. 2.3. 2.3 Windows 注意事项
  3. 3. 三、登录和认证
    1. 3.1. 3.1 使用 ChatGPT 账号登录
    2. 3.2. 3.2 使用 API Key
  4. 4. 四、在项目中启动 Codex
  5. 5. 五、常用交互方式
    1. 5.1. 5.1 让 Codex 解释项目
    2. 5.2. 5.2 让 Codex 修复 Bug
    3. 5.3. 5.3 让 Codex 新增功能
    4. 5.4. 5.4 让 Codex 做代码审查
    5. 5.5. 5.5 让 Codex 生成文档
  6. 6. 六、常用命令
    1. 6.1. 6.1 交互模式
    2. 6.2. 6.2 非交互执行
    3. 6.3. 6.3 恢复会话
    4. 6.4. 6.4 查看帮助
  7. 7. 七、权限、沙箱和确认机制
    1. 7.1. 7.1 文件读写权限
    2. 7.2. 7.2 命令执行权限
    3. 7.3. 7.3 网络权限
  8. 8. 八、配置文件 config.toml
  9. 9. 九、AGENTS.md 项目说明
  10. 10. 十、推荐工作流
    1. 10.1. 10.1 修改前
    2. 10.2. 10.2 修改中
    3. 10.3. 10.3 修改后
  11. 11. 十一、常见任务模板
    1. 11.1. 11.1 排查构建失败
    2. 11.2. 11.2 增加测试
    3. 11.3. 11.3 重构代码
    4. 11.4. 11.4 写发布说明
    5. 11.5. 11.5 生成提交信息
  12. 12. 十二、排错
    1. 12.1. 12.1 command not found: codex
    2. 12.2. 12.2 登录失败
    3. 12.3. 12.3 模型不可用
    4. 12.4. 12.4 Codex 修改了不该修改的文件
    5. 12.5. 12.5 任务执行到一半中断
  13. 13. 十三、安全建议
  14. 14. 十四、一个完整示例
  15. 15. 十五、参考资料
请输入关键词进行搜索
  • to close