主流 Agent 入门教程 / Codex

4. 第一次使用Codex CLI

原文备份 · 第 5 / 27 篇 · 查看极客时间原知识库 ↗

本篇目录 · 18 节

来源：Codex

预计阅读时间：30 分钟
本篇目标：认识 Codex CLI 的基本界面，理解工作目录与权限的关系，完成第一次可检查、可撤销的文件修改。

前面三篇解决了“Codex 是什么”、“怎样安装”和“怎样选择模型”。从这一篇开始，我们正式进入 Codex CLI。

第一次使用 Coding Agent 时，人很容易走向两个极端：一种是不敢让它做任何事情，只把它当成问答工具；另一种是一开始就开放全部权限，希望它替自己完成所有工作。

更稳妥的方式是从一个独立练习目录开始，让 Codex 先观察，再修改，然后由我们检查结果。你会在这一篇中完整走一遍这个过程。

一、确认你位于正确的目录

第二篇已经创建了 taskflow 练习目录。现在重新进入它。

macOS、Linux 或 WSL2

打开终端，运行：

cd ~/codex-course/taskflow
pwd

最后一行应该以 codex-course/taskflow 结尾。

Windows PowerShell

打开 PowerShell，运行：

Set-Location "$HOME\codex-course\taskflow"
Get-Location

输出路径应该以 codex-course\taskflow 结尾。

如果目录不存在，请回到第二篇，重新创建练习目录。不要为了省一步，直接在桌面、下载目录或保存正式项目的目录中练习。

二、用 Git 为练习项目准备安全网

Git 能记录文件变化，方便我们检查和恢复。先检查电脑是否已经安装 Git：

git --version

如果看到类似 git version 2.x.x 的输出，说明 Git 可以使用。

如果提示找不到命令，可以暂时跳过本节，后面的 /diff 和 /review 功能会受到影响。建议在继续正式项目之前，从 Git 官方网站安装适合当前系统的版本。

在 taskflow 目录中运行：

git init

接着运行：

git status

你应该看到当前分支信息，以及“没有提交内容”或含义相近的提示。项目还没有任何文件，这是正常的。

git init 只会在当前目录中创建 Git 元数据，不会把文件上传到互联网，也不会自动创建 GitHub 仓库。

三、以只读方式启动 Codex

为了先观察界面，我们让 Codex 以只读模式启动。

在 macOS、Linux、WSL2 或 PowerShell 中都可以运行：

codex --sandbox read-only --ask-for-approval on-request

如果 Codex 询问是否信任当前目录，请先确认提示中的路径确实是刚才创建的 taskflow，再按照界面提示继续。

进入后，你会看到终端式交互界面。不同版本的颜色和排版可能略有变化，但通常能看到下面几类信息：

当前项目或工作目录；
当前模型；
当前对话记录；
底部用于输入任务的区域；
状态、上下文或使用量提示。

不必记住每个界面元素。真正重要的是：你知道 Codex 正在哪个目录工作，以及当前是否允许修改文件。

四、用 `/status` 检查当前会话

在输入区域键入：

/status

按回车后，Codex 会显示当前会话信息。请重点检查：

工作目录是不是 taskflow；
Sandbox 是否为 read-only；
当前使用的模型是否符合预期；
当前还有多少上下文空间；
哪些目录属于本次工作区。

不同版本可能使用“writable roots”“workspace”“sandbox”等不同标签。只读模式下，Codex 可以查看允许读取的文件，但不能直接写入工作目录。

如果工作目录不正确，输入：

/exit

退出后，在终端中进入正确目录，再重新运行 Codex。

五、让 Codex 先观察，不要马上修改

输入下面这段任务：

请检查当前工作目录，并告诉我：

1. 当前有哪些文件和目录；
2. 这里是否已经是 Git 仓库；
3. 当前是否具备开始一个新项目的基本条件。

只读取和分析，不要创建或修改任何文件，也不要访问当前工作目录之外的位置。

Codex 应该检查目录，并告诉你这里基本是一个空的 Git 仓库。由于当前是只读模式，即便它误解了要求，也没有权限直接创建项目文件。

这一步演示了一个很实用的习惯：面对陌生目录时，先让 Codex 盘点现状，再决定下一步。

六、观察只读模式如何阻止写入

现在故意给它一个需要写文件的任务：

请在当前目录创建 PROJECT_BRIEF.md，并写入项目标题“TaskFlow”。

因为当前处于只读模式，Codex 不能直接完成写入。根据客户端版本和权限策略，它可能会：

说明当前权限不允许写入；
请求你调整权限；
给出准备写入的内容，但不真正创建文件。

如果它弹出越过只读边界的授权请求，这一步选择拒绝。无论出现哪一种情况，都不要把它理解成故障。只读模式正在按预期工作。

七、使用 `/permissions` 切换权限

输入：

/permissions

界面会显示三个权限选项：Ask for approval、Approve for me 和 Full access。对于本教程的本地练习目录，选择 Ask for approval。

这三个选项不要只按字面理解：

Ask for approval：Codex 可以在当前工作区内读写和运行常规命令；需要越过工作区、访问受限网络等资源时，由你决定是否批准。本教程默认使用它。
Approve for me：工作区边界基本不变，但越界请求交给自动审查器判断，适合已经熟悉权限边界后减少手动确认。
Full access：可以访问工作区之外的文件和网络，风险明显更高；本教程的本地练习不需要选择它。

有些旧版本或旧资料把第一类工作方式称为 Auto，但你当前界面里没有这个选项。后文凡是需要在项目内改代码、跑测试，默认都选择 Ask for approval。

在命令行参数中，Ask for approval 对应本教程一直使用的组合：

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

它表示：

Codex 可以读取工作区中的文件；
Codex 可以修改当前工作区；
网络访问默认仍然受限；
写入工作区之外的位置时需要额外授权；
超出沙箱边界的操作不会静默执行，而是由你决定是否批准。

切换完成后，再输入一次：

/status

确认当前不再是只读模式，并且可写范围仍然只包括练习工作区和系统临时目录。

八、完成第一次文件修改

输入下面的完整任务：

请在当前目录创建 PROJECT_BRIEF.md，内容包括：

- 项目名称：TaskFlow
- 项目定位：一个用于学习 Codex 的本地命令行任务管理工具
- 第一阶段目标：支持添加任务、查看任务和完成任务
- 当前状态：尚未确定技术方案，暂时不要创建程序代码

要求：
1. 使用清晰的 Markdown 结构；
2. 只创建这一个文件；
3. 创建后重新读取文件，确认内容完整；
4. 最后说明你修改了什么，不要继续实现项目。

这段提示词包含目标、范围、限制和完成标准。Codex 不需要猜测你是否希望它顺手写代码。

任务完成后，它应该报告已经创建 PROJECT_BRIEF.md，并说明进行了重新读取或检查。

九、不退出 Codex，也能检查文件

Codex CLI 支持在输入行前加 !，直接运行本地终端命令。输入：

!git status

你应该看到 PROJECT_BRIEF.md 是一个尚未跟踪的新文件。

接着输入：

/diff

/diff 会展示 Git 工作区中的变化，包括尚未被 Git 跟踪的新文件。检查以下内容：

是否只新增了 PROJECT_BRIEF.md；
文件名是否正确；
内容是否与要求一致；
是否出现你没有要求的代码或配置文件。

检查完没问题之后，可以按字母键 "Q" 返回交互式命令行界面。

如果结果不符合要求，比如它私自添加了选型建议，那么你可以直接告诉 Codex：

PROJECT_BRIEF.md 中不要加入技术选型建议。请删除相关内容，只保留已经确认的信息，修改后再次展示差异。

十、使用 `/review` 做一次独立检查

输入：

/review

如果出现审查范围选择，选择“Review uncommitted changes （审查未提交的修改）”。

这次修改非常简单，审查结果很可能是没有发现问题。我们的重点是熟悉流程：Codex 完成修改后，你可以再让审查流程从完整性、风险和遗漏角度检查工作区。

/review 需要当前目录是 Git 仓库。如果没有初始化 Git，该命令可能不会出现，或者提示没有可审查的工作树。

十一、学会在运行过程中补充要求

当 Codex 正在工作时，你不一定要等它结束后再纠正。

在 CLI 中直接输入补充说明并按回车，可以把新要求加入当前任务；
按 Tab 发送，可以把内容排队，等当前任务结束后再处理。

例如，你发现 Codex 正准备创建多余文件，可以立即输入并按回车：

只保留 PROJECT_BRIEF.md，不要创建其他文件。

这叫做对当前任务进行引导。它很适合补充遗漏条件，但不能替代一开始就说清楚关键范围。

如果 Codex 启动了不需要的后台命令，可以使用：

/ps

查看后台终端，再使用：

/stop

停止当前会话启动的后台终端。

十二、批准操作时应该看什么

当你后续要执行一些更复杂的任务时，可能会收到 Codex 请求额外权限的提示，要注意，批准时不要只看“允许”和“拒绝”两个按钮。先读清楚：

它准备执行什么操作；
操作目标是哪个文件或目录；
为什么当前任务需要这项权限；
是否有范围更小的替代方案。

例如，任务只是修改 taskflow 项目，却请求写入整个用户目录，这个范围就不合理。更合适的做法是拒绝请求，并告诉它只在当前工作目录内完成任务。

网络访问也是一样。安装依赖可能需要联网，读取本地文件则通常不需要。权限应该跟着任务需要走，而不是一次性全部打开。

十三、为什么不使用 `--yolo`

Codex CLI 提供 --dangerously-bypass-approvals-and-sandbox，也可以写成 --yolo。它会绕过审批和沙箱限制。

这不是日常学习模式，也不适合直接用于保存个人文件或正式项目的电脑。只有当 Codex 已经运行在专门隔离的虚拟机或容器中，并且外层环境本身提供了可靠限制时，才有讨论它的意义。

本教程默认使用工作区可写、越界操作需要确认的模式。

十四、保存本次练习结果

先退出 Codex：

/exit

回到普通终端后运行：

git status
git diff -- PROJECT_BRIEF.md

对于尚未跟踪的新文件，普通 git diff 可能不会显示内容，这是 Git 的正常行为（想要退出的话，可以在英文输入法状态下按 Q 键退出）。你仍然可以直接打开文件检查，或者先运行：

git add PROJECT_BRIEF.md
git diff --cached

确认内容无误后，可以创建第一次提交：

git commit -m "docs: add TaskFlow project brief"

如果 Git 提示没有配置用户名或邮箱，按照提示配置后重新提交；也可以暂时不提交，下一篇仍然能够继续。

提交只保存在本机，除非你以后主动添加远程仓库并执行推送。

十五、本篇完成检查

继续下一篇之前，请确认：

Codex 从正确的 taskflow 目录启动；
你能使用 /status 检查目录、模型和权限；
你体验了只读模式对写入操作的限制；
你能使用 /permissions 切换到工作区可写模式；
当前只新增了 PROJECT_BRIEF.md；
你能使用 /diff 查看修改；
你知道 /review 需要 Git 仓库；
你知道怎样在任务运行时补充要求；
你没有为练习任务开放整个电脑的写入权限。

下一篇，我们不会急着写程序，而是让 Codex 把 TaskFlow 的模糊想法整理成一份可以执行、可以验收的开发计划。