1.安装

本文假设你已经安装了cli代码工具...

2. 使用前准备

2.1 检查安装是否成功

codex --version

codex --help

2.2 进入项目根目录

建议在仓库根目录下使用 Codex：

cd /path/to/your-project
pwd
ls

如果你本地装了 tree，也可以先看结构：

tree -L 2

没有 tree 的话，也可以用：

find . -maxdepth 2 -type f | head -100

2.3 配置认证信息

部分版本可能需要 API Key 或登录信息。

例如常见环境变量方式：

export OPENAI_API_KEY="your_api_key"

检查是否已设置：

echo $OPENAI_API_KEY

实际认证方式以你所用版本为准。

2.4 建议先开一个 Git 分支

git checkout -b feat/use-codex

这样就算 Codex 改得不理想，也更容易回滚。

3. 快速开始

第一次进入一个仓库，建议按这个最小流程走。

3.1 启动 Codex

codex

进入交互模式后，先看帮助：

/help

如果支持，也可以直接输入：

/

3.2 先初始化项目说明

在交互模式里执行：

/init

它通常会基于当前仓库生成一份项目说明文件，例如：

  • AGENTS.md

  • 或其他版本约定的说明文件

生成后建议检查一遍，再补充团队规范。

3.3 先分析，不要急着修改

示例提示词：

请先阅读当前项目结构，并告诉我：
1. 项目入口文件在哪里
2. 主要业务模块有哪些
3. 测试目录在哪里
4. 如果我要改登录逻辑，应该先看哪些文件

先分析，不要修改任何文件。

3.4 再让它修改

例如：

请只修改登录相关逻辑：
1. 增加用户名和密码的非空校验
2. 保持原有接口不变
3. 不要改动其他文件
4. 修改后补充测试

3.5 修改后检查结果

git status
git diff

再跑测试：

npm test
# 或
pytest
# 或
go test ./...
# 或
mvn test

4. Codex 的命令行启动方式

这一节说的是直接在 shell 里怎么启动和调用 Codex。

4.1 查看帮助

codex --help

如果某个子命令存在，也通常可以这样看：

codex <subcommand> --help

4.2 查看版本

codex --version

4.3 最常见：启动交互模式

codex

这通常是最稳妥、最常用的方式。

4.4 在指定目录中使用

最常见还是手动切目录：

cd /path/to/project
codex

某些版本如果支持，也可能存在类似参数：

codex -C /path/to/project

是否支持请以 codex --help 为准。
如果不支持，直接 cd 进去即可。

4.5 直接带一句任务启动（如果支持）

某些版本支持这样直接带任务：

codex "请分析当前项目入口文件和启动流程"

或者：

codex "请只解释 src/auth/login.ts 的逻辑，不要修改文件"

如果你本地版本不支持这种写法，请使用交互模式。

4.6 从标准输入传入任务（如果支持）

echo "请分析当前仓库的核心模块，不要修改文件" | codex

或者：

cat task.txt | codex

4.7 指定模型（如果支持）

某些版本可能支持类似：

codex --model <model-name>

例如：

codex --model gpt-5

模型参数名、可用模型名会因版本不同而变化，请先看帮助。

4.8 指定沙箱/审批模式（如果支持）

一些版本可能支持类似参数：

codex --sandbox workspace-write
codex --approval on-request

常见概念包括：

  • read-only：只读

  • workspace-write：允许修改当前仓库

  • 更高权限模式：允许执行更多操作

  • on-request：需要时请求审批

  • never：不询问

  • untrusted / trusted：不同安全等级

实际名字不一定完全相同，以本地帮助为准。

4.9 输出日志 / 详细模式（如果支持）

一些版本会支持：

codex --verbose
codex --debug

用于排查为什么某次行为和预期不一致。

4.10 会话恢复 / 继续上次任务（如果支持）

有些版本会提供“恢复会话”能力。
命令名可能类似：

codex resume

或其他形式。

如果你的版本没有这个功能，就继续使用普通交互模式即可。

5. 交互模式里的斜杠命令

进入 codex 交互界面后，通常可以使用以 / 开头的命令。
最准确的查看方式是：

/help

或者输入：

/

下面是常见思路。

5.1 /help

查看当前版本支持哪些斜杠命令。

/help

这个命令建议每次第一次使用新版本时都执行一下。

5.2 /init

用于初始化当前仓库的项目说明文件，常见会生成：

  • AGENTS.md

  • 或类似的仓库说明文件

作用是让 Codex 更稳定地遵守项目规则。

/init

这个命令通常适合在第一次进入某个仓库时使用。

5.3 /status

查看当前会话状态。
常见会包括：

  • 当前目录

  • 当前模型

  • 权限/沙箱模式

  • 审批模式

  • 其他运行状态

/status

5.4 /clear 或 /new

清空当前上下文，开始新任务。

/clear

或者：

/new

适合场景：

  • 你前面已经聊了很多内容

  • 新任务和旧任务完全无关

  • 想避免上下文污染

5.5 /model（如果支持）

查看或切换模型：

/model

如果支持切换，通常也可能有进一步提示。

5.6 /approval（如果支持）

查看或调整审批策略：

/approval

5.7 /sandbox（如果支持）

查看或调整当前沙箱/权限模式：

/sandbox

5.8 /exit 或 /quit

退出交互模式：

/exit

或：

/quit

5.9 其他你可能会见到的斜杠命令

不同版本还可能出现：

  • 会话压缩/总结类命令

  • 附件/文件上下文类命令

  • 配置查看类命令

  • 审批列表类命令

  • 会话历史类命令

所以再次强调：
你本地版本支持哪些命令，最准确的方法就是 /help。

6. /init 的用途与最佳实践

这是很多人最容易忽略、但非常有价值的功能。

6.1 /init 是干什么的

它通常会根据当前仓库内容，生成一份给 Codex 看的项目规则说明。
常见内容包括：

  • 项目是做什么的

  • 使用什么语言和框架

  • 代码风格要求

  • 测试命令

  • 启动命令

  • 哪些目录能改、哪些不能改

  • 输出语言要求

  • 是否要先计划后执行

  • 是否要求最小改动

6.2 什么时候应该执行 /init

建议以下场景都执行一下：

  • 第一次进入一个仓库

  • 团队准备长期使用 Codex

  • 希望减少重复提示

  • 你发现 Codex 经常误解项目结构

  • 仓库结构刚刚发生过大变化

6.3 推荐流程

/help
/init
请阅读刚生成的 AGENTS.md，并先分析当前项目结构，不要修改代码。

6.4 /init 生成后一定要人工检查

重点检查：

  • 项目名是否正确

  • 技术栈是否识别对

  • 测试命令是否正确

  • 构建命令是否正确

  • 有无写清“最小改动”

  • 有无写清“不要改无关文件”

  • 有无要求“修改后补测试”

  • 输出语言是否符合团队要求

6.5 建议把生成的说明文件提交到仓库

git add AGENTS.md
git commit -m "docs: add AGENTS.md for Codex workflow"

这样后续团队成员也能复用。

7. 常见自然语言任务写法

Codex 能不能稳定干活，很大程度取决于你怎么描述任务。

7.1 只分析，不修改

请分析当前项目的目录结构和核心模块，不要修改任何文件。

7.2 只解释某个文件

请解释 src/auth/login.ts 的主要逻辑，不要修改文件。

7.3 先出方案，再修改

我想重构订单创建流程。
请先输出：
1. 影响文件
2. 修改计划
3. 风险点
4. 回滚方式

先不要修改代码，等我确认后再执行。

7.4 最小改动修 Bug

请用最小改动修复这个问题：
1. 保持原有接口不变
2. 不做额外重构
3. 不要修改无关文件
4. 修改后补测试

7.5 限定修改文件范围

只允许修改以下文件：
- src/api/user.ts
- tests/user.test.ts

不要修改其他文件。

7.6 带日志分析问题

这是错误日志：
<粘贴日志>

请结合当前项目代码分析：
1. 根因
2. 最小修复方案
3. 受影响文件
4. 验证方式

先分析，不要立刻改代码。

7.7 修改后做总结

修改完成后请总结：
1. 改了哪些文件
2. 每个文件改了什么
3. 为什么这么改
4. 需要执行哪些测试
5. 还有哪些潜在风险

7.8 结构化输出

请按以下格式输出：
1. 问题描述
2. 根因分析
3. 修改方案
4. 影响范围
5. 测试建议

8. 其他命令行操作：与 Git / 搜索 / 测试配合

这部分是你刚才提到的“其他命令行操作”。
这里不只是 Codex 自己的命令，还包括你在终端里经常和 Codex 配合使用的命令。

8.1 目录与文件查看

看当前目录

pwd
ls
ls -la

看目录树

tree -L 2

查找文件

find . -name "login*"
find src -type f | head -100

搜索文本

推荐 rg（ripgrep）：

rg "login"
rg "createOrder" src tests
rg "TODO|FIXME"

这类命令很适合先自己粗看一遍，再让 Codex分析。

8.2 查看文件内容

cat README.md
less README.md
sed -n '1,200p' src/auth/login.ts

8.3 Git 配合操作

查看工作区状态

git status

看改动 diff

git diff

只看某个文件的 diff

git diff -- src/auth/login.ts

建分支

git checkout -b fix/login-validation

暂存与提交

git add .
git commit -m "fix: add login validation"

如果不满意，回滚某个文件

git checkout -- src/auth/login.ts

新版 Git 也可能推荐 git restore。

8.4 运行测试

Node.js

npm test
npm run test
pnpm test
yarn test

Python

pytest
pytest -q
pytest tests/auth/test_login.py

Go

go test ./...
go test ./pkg/auth

Java / Maven

mvn test

Gradle

./gradlew test

Rust

cargo test

PHP

phpunit

8.5 运行构建 / 检查

npm run build
npm run lint
cargo build
go vet ./...
mvn package

如果你让 Codex 改了代码，建议至少做：

  1. git diff

  2. 跑测试

  3. 跑构建/静态检查（如果项目有）

  4. 手动 spot check 关键逻辑

8.6 输出重定向

某些情况下你想保存 Codex 的结果或日志：

codex "请分析当前仓库结构" > codex-output.txt

或者：

codex "请生成修复计划" | tee plan.txt

是否支持直接输出到 stdout，取决于你的版本；不支持就用交互式复制。

8.7 把任务写到文件里

适合复杂需求：

task.txt：

请分析支付模块：
1. 入口文件
2. 调用链
3. 核心依赖
4. 风险点

先不要修改代码。

然后如果版本支持：

cat task.txt | codex

8.8 组合使用示例

git checkout -b fix/payment-timeout
rg "timeout" src tests
codex

进入交互模式后：

/init
请分析 payment 模块里 timeout 相关逻辑，不要修改代码。

分析确认后：

请用最小改动修复 timeout 配置不生效的问题，只修改 payment 相关文件，并补测试。

然后退出后检查：

git diff
pytest -q

9. 非交互式使用方式

如果你的版本支持，非交互模式适合做一些简单、一次性的任务。

9.1 单句任务

codex "请解释当前仓库的启动方式"

9.2 从文件或 stdin 读取

echo "请分析当前项目入口，不要修改代码" | codex

cat task.txt | codex

9.3 适合非交互模式的任务

  • 快速解释一个文件

  • 快速分析目录结构

  • 生成一段 README 说明

  • 输出修改计划

  • 做一次性总结

9.4 不太适合非交互模式的任务

  • 多轮澄清的大任务

  • 高风险重构

  • 涉及审批/权限确认的任务

  • 需要你反复 review 的修改任务

这类更适合交互模式。

10. 权限、沙箱、审批

很多 Codex CLI 版本都会涉及这些概念。

10.1 只读模式

特点：

  • 可以看代码

  • 可以分析

  • 不能改文件

适合：

  • 初次审查仓库

  • 安全要求很高的环境

  • 先做架构分析

10.2 工作区可写

特点：

  • 可以修改当前仓库文件

  • 一般是最常用模式

适合：

  • 修 bug

  • 改局部功能

  • 补测试

  • 补文档

10.3 更高权限模式

特点：

  • 可能允许执行更强的系统命令

  • 风险更高

适合：

  • 你明确知道需要这些能力

  • 你愿意为执行结果负责

  • 有足够审计和回滚能力

10.4 审批模式

常见思路：

  • 每次危险命令都要你确认

  • 某些类型命令自动允许

  • 完全不询问

建议：

  • 日常开发优先用受限权限 + 需要时审批

  • 不要默认给过高权限

  • 删除、覆盖、批量替换尤其要谨慎

11. 推荐工作流

这一节是最实用的。

11.1 工作流一：第一次接手一个仓库

  1. 进入仓库

  2. codex

  3. /help

  4. /init

  5. 让它先分析项目结构

  6. 自己对照代码确认

  7. 再进入具体问题

示例：

/help
/init
请先分析当前仓库的入口文件、核心模块、测试方式，不要修改代码。

11.2 工作流二：修一个小 Bug

  1. 建 Git 分支

  2. codex

  3. /status

  4. 描述 bug 和日志

  5. 要求先分析根因

  6. 确认后再修改

  7. git diff

  8. 跑测试

  9. 提交

示例：

git checkout -b fix/login-bug
codex

交互里：

请根据下面的日志分析登录接口 500 的根因，先不要修改代码：
<日志>

然后：

请用最小改动修复，保持原有接口不变，并补充测试。

11.3 工作流三：做一个中等规模重构

  1. 先分析现状

  2. 输出修改计划

  3. 拆成 2~4 步

  4. 每一步完成都 review diff

  5. 每一步都跑测试

  6. 分多次 commit

示例：

这个需求比较大，请分三步执行：
1. 先分析订单创建链路
2. 再重构 service 层
3. 最后调整 controller 层

每一步先汇报，再继续下一步。

11.4 工作流四：补测试

请为 src/utils/date.ts 补充单元测试，覆盖：
1. 正常输入
2. 边界输入
3. 异常输入

不要修改业务逻辑，除非测试暴露了明确 bug。

11.5 工作流五：做代码审查

请审查当前改动，重点看：
1. 兼容性风险
2. 空指针/异常处理
3. 并发问题
4. 是否缺少测试
5. 是否存在明显性能问题

12. AGENTS.md 示例模板

如果 /init 自动生成后还不够完整，你可以手工补充成这样。

# AGENTS.md

## 项目说明
- 这是一个 Python Web 项目
- 使用 FastAPI
- 使用 PostgreSQL
- 使用 pytest 进行测试

## 开发约定
- 所有回复使用中文
- 优先最小改动
- 不要修改无关文件
- 不要做无必要的重构
- 修改功能代码后尽量补充测试
- 先说明计划，再执行修改
- 输出结论时要包含影响范围和风险点

## 代码约定
- 保持现有目录结构
- 保持公开接口兼容
- 不要随意重命名函数和文件
- 不要批量格式化无关文件

## 常用命令
- 安装依赖：`pip install -r requirements.txt`
- 运行测试：`pytest -q`
- 本地启动：`uvicorn app.main:app --reload`

## 风险目录
- `migrations/` 不要自动改
- `config/production.py` 不要直接改
- 涉及数据库 schema 的改动必须先说明

## 交付要求
修改完成后请总结：
1. 改了哪些文件
2. 为什么改
3. 如何验证
4. 还存在哪些风险

查看全部

13. 常见问题

13.1 codex: command not found

通常说明：

  • 没安装成功

  • 可执行文件不在 PATH

  • 终端没刷新环境变量

先检查：

which codex
codex --version

13.2 认证失败 / API Key 报错

检查：

echo $OPENAI_API_KEY

如果为空，说明没配置好。
如果不为空，但还是报错，检查是否是当前 shell 会话未生效。

13.3 /init 不存在

原因通常有两个：

  1. 你的版本不支持

  2. 你的版本命令名不同

先执行：

/help

或者输入：

/

看实际支持哪些斜杠命令。

如果确实没有 /init，你也可以手工创建 AGENTS.md。

13.4 它改得太多

通常是因为提示词太宽泛。

不要说：

帮我优化这个项目

要说：

请只优化 src/cache/redis.ts 的异常处理逻辑：
1. 保持接口不变
2. 不做其他重构
3. 不要修改无关文件
4. 修改后补测试

13.5 它没有按预期修改

补充更清楚的限制：

  • 只改哪些文件

  • 不许改哪些文件

  • 保持接口不变

  • 先出方案再执行

  • 最小改动

  • 修改后补测试

13.6 大项目分析太慢

建议：

  • 只分析某个目录

  • 只分析某条调用链

  • 不要一次问太多问题

  • 先让它做概览，再深入局部

例如：

请只分析 src/payment 目录，不要扫描整个仓库。

14. 最佳实践

14.1 先分析，再修改

不要一上来就让它改整个项目。

14.2 每次只做一件事

一次只修一个 bug，或只做一类重构。

14.3 明确修改范围

告诉它：

  • 改哪些文件

  • 不改哪些文件

  • 是否允许重命名

  • 是否允许改接口

  • 是否要补测试

14.4 优先最小改动

这样更容易 review，也更容易回滚。

14.5 一定配合 Git

至少做到：

git status
git diff

14.6 修改后一定验证

最少检查：

  1. git diff

  2. 跑测试

  3. 跑构建/检查

  4. 手动 spot check 核心逻辑

14.7 善用 /init

它能大幅减少你重复输入规则的次数。

14.8 大任务拆小

不要说“重构整个系统”，要拆成：

  • 先分析

  • 再计划

  • 再改一部分

  • 再验证

  • 再继续

14.9 对危险操作保持谨慎

例如：

  • 批量删除

  • 全局替换

  • 自动重命名

  • 跨模块大改

这些最好先让它只出方案，不直接执行。

15. 快速备忘清单

15.1 最常用命令

codex --help
codex --version
codex
git status
git diff
rg "keyword"
pytest
npm test

15.2 最常用斜杠命令

/help
/init
/status
/clear
/new
/model
/approval
/sandbox
/exit
/quit

具体是否都支持，以你本地 /help 为准。

15.3 最常用提示词模板

只分析不修改

请分析当前项目的目录结构和核心模块，不要修改任何文件。

先计划后执行

请先输出修改计划和影响范围，不要直接改代码。

限定修改范围

只允许修改 src/auth/login.ts 和 tests/login.test.ts，不要改其他文件。

最小改动修 Bug

请用最小改动修复这个问题，保持接口不变，不做额外重构。

修改后给总结

修改完成后请总结：
1. 改了哪些文件
2. 为什么这样改
3. 需要执行哪些测试
4. 还有哪些风险

总结

Codex CLI 的高效使用方式，核心就这几步：

  1. 先进入仓库根目录

  2. 先 codex 再 /help

  3. 第一次进仓库先 /init

  4. 先分析，不要急着改

  5. 改动时明确范围、强调最小改动

  6. 修改后必须 git diff + 跑测试

  7. 大任务拆小步，逐步确认

如果你把约束说清楚、配合 Git 和测试一起用，Codex CLI 会非常适合做日常开发辅助。

License

本文由 shiyebushihua 原创，采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。

Share