Codex 上手：三种沙箱模式与无人值守长任务

你有没有遇过这种情况：让 AI 帮你改一段代码，自己去倒杯水，回来发现它在等你的下一条指令——什么都没做。

Claude Code 是交互式的，你在场，它才真正发力。但有些任务——比如"帮我把这 200 个测试文件都跑一遍并修复所有失败"——你不想盯着屏幕等两个小时。这就是 Codex 擅长的地方。

Codex 是 OpenAI 出的命令行 AI 编程工具，它的设计思路就是：你甩一个任务，去干别的事，回来审产出。沙箱隔离是它的安全底牌——它能在受控环境里放手跑，不用每一步都征求你的意见。

---

Codex 是什么，和 Claude Code 有什么不同

先把两者的差异说清楚，这样你后面选工具不会纠结。

Codex 和 Claude Code 都是终端型 AI 编程工具，都不依附于特定 IDE，都能读写文件和执行命令。但核心侧重不同：

维度	Claude Code	Codex
设计思路	交互式、实时协作	异步、无人值守长任务
沙箱能力	基础权限控制	三档沙箱隔离，按任务风险分级
上下文理解	深度理解整个仓库	任务导向，注重执行而非问答
典型用法	"帮我看这里为什么报错"	"帮我把这批重构任务跑完"
审核方式	每步都可以确认或拒绝	任务跑完你来审产出

换句话说：需要你在场、边问边做的，用 Claude Code；可以甩出去、让它跑完你再看的，用 Codex。

两者不是竞争关系，是互补的。关于 CLI 工具的整体选型，见上一节：工具全景。

---

安装与认证

前提：Node.js

Codex 是 npm 包，需要 Node.js。检查是否已有：

node --version
npm --version

输出类似 v20.x.x 就行，需要 Node.js 18+。版本不够去 nodejs.org 下 LTS 版本覆盖安装。

安装 Codex

npm install -g @openai/codex

全局安装，装完后验证：

codex --version

看到版本号说明安装成功。

认证

Codex 依赖 OpenAI API，需要设置 API Key：

# Linux / Mac
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-xxxxxxxxxxxxxxxx"

API Key 去 platform.openai.com 的"API keys"页面创建。账号注册、充值额度、是否需要订阅，以官方说明为准（截稿 2026-06）。

你应该看到什么

认证配置好后，在你的项目目录运行：

codex

应该进入交互界面，出现提示符，没有报"API key not found"之类的错误。如果第一次启动提示配置引导，跟着走就行。

---

三种沙箱模式

这是 Codex 区别于其他 AI 编程工具最核心的设计。沙箱模式决定了它能在你的系统上做什么、不能做什么，选错模式要么任务跑不完，要么风险超出你的预期。

模式	权限范围	适用场景	风险级别
只读（read-only）	只能读文件，不能写、不能执行	代码审查、分析、生成报告、回答问题	极低，适合陌生代码库
受限写（restricted）	可以写文件，但网络访问和系统命令受限	代码生成、重构、修复 bug、补测试	中等，日常开发主力模式
全权（full）	完整权限，包括网络、系统命令、安装包	需要跑测试套件、安装依赖、部署脚本	较高，信任的项目才用

用 --sandbox 参数指定模式：

# 只读模式
codex --sandbox read-only "帮我分析这个项目的架构，列出主要模块"

# 受限写（默认模式，不传参数也是这个）
codex "把所有 var 声明改成 const 或 let"

# 全权模式
codex --sandbox full "安装依赖，跑测试，修复所有失败的测试用例"

选模式的判断逻辑：

• 你只是想问问题、看代码：只读。
• 你想让它生成或修改代码但不需要它装包、跑命令：受限写（默认就好）。
• 你需要它端到端干完，包括安装依赖、执行脚本、验证结果：全权——但要在你信任的项目里用，别在第三方代码库上直接开全权。

初次用 Codex 的建议：从受限写开始，摸清它的行为模式再考虑全权。

---

跑一个无人值守的长任务

这是 Codex 真正发力的地方。演示一个实际场景：项目里有一批格式不统一的注释，你想让它批量整理成 JSDoc 规范。

启动任务

cd /path/to/your-project

codex --sandbox restricted "把 src/ 目录下所有 .js 文件里的注释都整理成 JSDoc 格式。每个函数加上 @param 和 @returns 标注，没有注释的函数补上简短描述。不要改函数逻辑，只动注释。"

任务描述越具体越好。几个提高成功率的习惯：

• 告诉它不能做什么："不要改函数逻辑"比"只改注释"更清楚。
• 给范围边界：src/ 目录而不是整个项目。
• 说明预期格式：JSDoc 而不是"标准注释"。

你应该看到什么

任务启动后，Codex 开始跑，终端会输出进度——它在读哪些文件、在改什么。这时候你可以：

• 继续盯着看（如果任务短）。
• 最小化终端，去干别的（这才是无人值守的用法）。

任务跑完，终端会打印完成提示和摘要，列出修改了哪些文件、做了哪些操作。

如果是真的长任务（跑测试套件、处理大量文件），可以用 nohup 或 tmux 让它在后台保持运行，防止终端关闭中断任务：

# 用 tmux 保活
tmux new -s codex-task
codex --sandbox full "跑所有测试，修复失败项，任务完成后输出摘要"
# Ctrl+B, D 挂起 tmux，稍后 tmux attach -t codex-task 回来查看

---

怎么审阅产出

无人值守的代价是你需要主动审阅，而不能依赖每步确认。以下是一个靠谱的审阅流程：

第一关：看 git diff

Codex 修改文件后，用 git 看改动：

git diff
git diff --stat   # 看哪些文件被动了、多少行

重点关注：有没有改到它不该改的地方？范围是否符合你的指令？

第二关：跑测试

如果项目有测试套件，一定要在审阅产出时跑一遍：

npm test
# 或者你的测试命令

Codex 改代码可能引入边角情况的问题，测试是你最快的验证手段。

第三关：抽查几个修改点

不用每行都看，但挑几处有代表性的改动翻一翻——特别是改动量大的文件，或者你觉得逻辑比较复杂的函数。

产出不满意怎么办

不满意别直接 git checkout . 丢掉——先分析是哪里跑偏了（指令不清楚？权限不够？任务太复杂？），再补一条更精确的指令让它修。对话是连续的，它记得前面做了什么。

---

故障排查表

症状	原因	解法
codex: command not found	npm 全局目录不在 PATH	npm config get prefix 取路径，加进 PATH，重开终端
API key not found / 401 错误	环境变量没设或 Key 无效	echo $OPENAI_API_KEY 确认值存在；Key 以 sk- 开头且完整
任务跑到一半停住不动	遇到权限不足或网络阻断	检查沙箱模式是否匹配需求；受限模式遇到需要网络的操作会卡
改了不该改的文件	任务描述范围不够明确	git checkout 回滚；重写指令加上"只处理 xxx 目录"之类的边界
全权模式装了意外的包	指令没有明确限制	检查 package.json diff；不需要的包 npm uninstall 移除
报 Node.js version not supported	Node 版本低于要求	升级到 Node.js LTS，去官网下覆盖安装
任务描述很清楚但产出质量差	任务本身太复杂，一次说不清	拆成更小的子任务，逐步推进；复杂任务分多轮跑比一次性更可靠

---

常见问题

Q：Codex 要花钱吗？

使用 Codex 工具本身免费，但调用背后的模型消耗 OpenAI API 额度。具体计费方式以 OpenAI 官方说明 为准（截稿 2026-06）。

Q：沙箱模式是绝对安全的吗？

沙箱提供了有意义的隔离，但不是绝对防护。受限模式在大多数场景下足够用。如果你在跑第三方或不信任的代码库，建议在虚拟机或 Docker 容器里额外隔一层。

Q：和 Claude Code 同时装没问题吗？

没问题。两个工具互不干扰，都是独立的 npm 包，按需用哪个用哪个。很多人的工作流是：日常交互用 Claude Code，批量任务交给 Codex。关于如何选择，详见 2.2 Claude Code 上手。

Q：Codex 能看懂中文指令吗？

可以。用中文描述任务它能理解，但输出语言可能是英文——如果需要中文输出，在任务描述里加"用中文输出"即可。

Q：任务跑到一半我想中断怎么办？

Ctrl+C 中断当前操作。已经修改的文件不会自动回滚，用 git status 和 git checkout 处理中间状态。

---

动手挑战

学完理论，马上试一个最小的真实任务感受沙箱：

1. 找一个有几个 .js 或 .ts 文件的小项目（或者 git clone 一个开源小库）。
2. 用受限写模式跑：codex "给 src/ 目录下所有函数加上类型注释"。
3. 任务结束后，用 git diff 看它改了什么，判断质量是否符合预期。
4. 如果不满意，写一条更精确的指令，看第二次产出有没有改善。

这个挑战的核心不是结果有多完美，而是建立"描述任务 → 审阅产出 → 迭代指令"这个无人值守工作流的肌肉记忆。

---

下一步

Codex 上手后，2.4 Cursor 上手 会覆盖图形界面路线的代表工具——如果你更喜欢在 IDE 里工作，那篇是对应的入口。

回到 AI 编程教程全景 确认自己在整条路线里的位置。

---

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。