Codex 使用教程：第一次上手，权限和沙箱、常用命令、改代码和审代码

这篇教程接着安装教程讲：Codex 装好了，怎么用它在自己的项目里干活，又不让它乱改东西。

先说结论：

• 第一句话先让它介绍项目，动手之前用 Git 提交一次。 这是官方的建议，改坏了可以退回。
• 权限分两层：沙箱管“能做什么”，审批管“什么时候要问你”。 在 Git 仓库里启动，默认是能改工作目录、要联网或者改目录外面的文件时先问你；不在 Git 仓库里，默认只读。
• 记住几个斜杠命令就够用： /init 写项目规矩，/status 看当前设置，/permissions 调权限，/model 换模型，/diff 看改了什么，/review 让它自审。
• 要接进脚本，用 codex exec。 它默认只读，要改文件得明确给权限。

本文按官方文档整理，本站还没有让 Codex 实际完成一个任务。“沙箱实测”一节在本站的服务器上跑过（2026-11-01，codex-cli 0.166.0，Ubuntu 24.04），那一节写明了。

第一个任务

进入项目目录，启动 Codex：

cd 你的项目
git add -A && git commit -m "交给 Codex 之前"   # 先留一个退路
codex

启动画面显示当前的模型和目录，下面是输入框。先问一句：

介绍一下这个项目：目录结构、怎么运行、测试怎么跑

它会读文件、必要时运行命令，然后回答。接下来可以让它做一件具体的小事，比如修一个已知的 bug、补一个测试。官方的建议是一次只给一件目标明确的事，比“把这个项目优化一下”好得多。

它执行的每条命令、改的每个文件都会显示在对话里。需要你批准的操作会停下来问你，下一节讲什么时候会问。

权限：沙箱和审批

Codex 的安全控制分两层，配合起作用：

层	管什么	设置方式
沙箱（sandbox）	它执行的命令技术上能做什么：能写哪些目录、能不能联网。由操作系统强制执行	--sandbox，或配置文件里的 sandbox_mode
审批（approval）	什么时候必须停下来问你	--ask-for-approval（简写 -a），或配置文件里的 approval_policy

默认是哪一档

启动时 Codex 会看当前目录是不是 Git 仓库：

目录	默认
Git 仓库	Auto：能读文件、在工作目录里改文件和运行命令；要改工作目录外面的文件、要联网时先问你
不是 Git 仓库	只读（read-only）

有的情况下，即使在 Git 仓库里，也会先以只读启动，等你确认信任这个目录（启动时的提示，或者用 /permissions）。

不管哪一档，默认都不能联网。用 /status 可以看到当前的模型、审批策略和哪些目录可写。

常用的几种组合

想要的效果	写法	结果
正常干活（默认）	不加参数，或 --sandbox workspace-write --ask-for-approval on-request	工作目录里随便改；出了工作目录、要联网时问你
只看不改，先讨论方案	--sandbox read-only --ask-for-approval on-request	能读文件、能运行只读的命令，不改东西
让另一个模型替你批	在上一行的基础上加 -c approvals_reviewer=auto_review	需要批准的操作先交给自动审查，它判断风险后放行或拒绝；会多消耗一些用量
完全放开	--dangerously-bypass-approvals-and-sandbox（别名 --yolo）	没有沙箱、不问你。官方标为高风险，不建议用

用到一半想换，输入 /permissions 就能切换，不用重启。

两个容易踩的坑：

• 工作目录里也有改不了的地方。 默认的可写模式下，工作目录里的 .git、.codex、.agents、.aws 这几个目录是只读的，防止它改坏 Git 的数据和自己的配置。
• 旧的 approval_policy = "untrusted" 已经不支持了，配置里留着它，Codex 可能启动不了。官方给的替代写法是 sandbox_mode = "read-only" 加 approval_policy = "on-request"。

沙箱实测

在本站的服务器上（Linux，codex-cli 0.166.0），用 codex sandbox 在沙箱里跑一个小脚本，看三种设置下各项操作能不能成功。-P 选的是内置的权限配置：:read-only 只读，:workspace 可写工作目录。

codex sandbox -P :workspace -- sh t.sh

脚本依次尝试：写工作目录里的文件、写工作目录外面（家目录下）的文件、写 /tmp、写工作目录里的 .git、访问一个网站。结果（0 是成功，其他是失败）：

操作	:read-only	:workspace	不加 -P
写工作目录	失败	成功	失败
写工作目录外面	失败	失败	失败
写 /tmp	失败	成功	失败
写工作目录里的 .git	失败	失败	失败
联网	失败（解析不了域名）	失败（解析不了域名）	失败（解析不了域名）

和文档一致：可写模式只放开工作目录和临时目录，.git 照样只读，网络默认不通。不加 -P 时 codex sandbox 按只读处理。

同一台服务器上用 codex exec 跑任务，启动信息里显示的是 approval: never、sandbox: read-only，也和文档说的 codex exec 默认只读一致，见本文最后一节。

常用的斜杠命令

在输入框里打 / 会弹出命令列表。最常用的：

命令	作用
/init	在当前目录生成一份 AGENTS.md，写这个仓库的规矩（怎么跑测试、代码风格等），以后每次都会读
/status	看当前的模型、审批策略、可写的目录和剩余的上下文
/permissions	切换权限：只读、可写、要不要问你
/model	换模型和推理强度
/plan	进入计划模式：先让它出方案，你同意了再动手
/mention	指定让它看某个文件或目录
/diff	看它改了什么，包括新建的、Git 还没跟踪的文件
/review	让它审查当前的改动，列出问题
/compact	把前面的对话压缩成摘要，腾出上下文
/new	在同一个会话里开一段新对话
/resume	回到之前保存的对话
/usage	看账号的用量
/goal	给一个大任务设一个持续追踪的目标

AGENTS.md 怎么写才有用，见GPT-6 时代怎么给 Codex 写指令；模型怎么选，见Codex 该选哪个模型。

改完之后：看差异，让它自审

它改完一件事，提交之前做两步：

1. /diff 看改了什么。 不认识的改动问它为什么改。
2. /review 让它审一遍。 可以选审查未提交的改动、某次提交，或者和主分支比。它只报告问题，不动你的工作目录。

没问题再自己 git commit。不满意就 git checkout 退回，或者让它接着改。

接着上次做

想做什么	命令
从列表里挑一个之前的对话继续	codex resume
直接继续最近的一个	codex resume --last
从之前的对话分出一条新的，原来的不动	codex fork

其他几个启动参数

参数	作用
--image 图片路径	把截图、架构图带进第一句话，比如报错截图
--search	让它联网搜索最新的资料，比如新版本的文档。默认用的是 OpenAI 维护的搜索缓存，不直接抓网页
-m 模型名	这一次用指定的模型
-C 目录	指定工作目录

接进脚本：codex exec

不进交互界面，一条命令跑完一个任务：

codex exec "总结这个仓库的结构，列出最容易出问题的五个地方"

运行过程打到 stderr，最后的回答打到 stdout，所以可以直接重定向或者接管道：

codex exec "根据最近 10 次提交写发布说明" | tee release-notes.md

要点：

• 默认只读。 要让它改文件，加 --sandbox workspace-write；danger-full-access 只在隔离的环境（比如一次性的 CI 机器、容器）里用。旧的 --full-auto 已经不支持了。
• 要给程序读的输出，加 --json，stdout 变成一行一个事件的 JSON。只要最后的回答，用 -o 文件名 写进文件。
• 不想在硬盘上留下会话记录，加 --ephemeral。
• 不在 Git 仓库里运行，要加 --skip-git-repo-check。
• 在 CI 里用 API key 时，官方建议只给运行 Codex 的那一步设 CODEX_API_KEY，不要设成整个任务的环境变量，免得仓库里的脚本、依赖读到它。GitHub Actions 有官方的 Codex Action，比自己装 CLI 更安全。

下一步

• Codex 接入中转站：在国内不用 ChatGPT 账号也能用。
• GPT-6 时代怎么给 Codex 写指令：AGENTS.md 和技能怎么写。
• Codex 该选哪个模型：日常用 GPT-6.1 Sol，最难的问题换 Astra。