当前位置：首页 > news >正文

Codex 完整避坑指南（2026 版）：沙箱、权限、AGENTS.md、Worktree 七类坑一次讲清

news 2026/7/7 23:20:55

Codex 用不好，多数不是模型问题，而是配置问题——官方最佳实践原文写着：“很多质量问题其实是环境设置问题（wrong directory, missing tools）”。本文把官方 Troubleshooting、Sandboxing、Best Practices 三份文档中的坑点，按国内开发者的踩坑频率重排为七类：环境安装坑、沙箱权限坑、Worktree 坑、提示词坑、AGENTS.md 坑、上下文管理坑、自动化坑，每个坑都给出官方修复方案和一条"防坑规则"。通读一遍大约 10 分钟，能省掉的排查时间以天计。

一、环境安装坑：Linux 用户的第一道墙

坑 1：Linux/WSL2 上沙箱启动警告

症状：启动 Codex 出现沙箱相关 warning，命令执行行为异常。

原因：Codex 在 Linux/WSL2 上依赖bubblewrap实现沙箱，未安装时回退到内置 helper，而 helper 需要非特权用户命名空间（unprivileged user namespace）支持。

修复：

# Debian/Ubuntusudoaptinstallbubblewrap# Fedorasudodnfinstallbubblewrap

Codex 会使用PATH里找到的第一个bwrap。

坑 2：Ubuntu 24.04 装了 bubblewrap 还是报警

症状：bubblewrap已安装，警告依旧。

原因：Ubuntu 24.04 的 AppArmor 默认限制非特权用户命名空间（25.04 已内置修复）。

官方修复路径（优于全局关闭限制）：

sudoaptinstallapparmor-profiles apparmor-utilssudocp/usr/share/apparmor/extra-profiles/bwrap-userns-restrict /etc/apparmor.d/sudoapparmor_parser-r/etc/apparmor.d/bwrap-userns-restrict# 无需重启

不推荐但存在的最后手段：sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0——全局放开安全限制，官方明确说优先加载 AppArmor profile 而不是用这条。

坑 3：CLI 有的功能 App 里没有

症状：CLI 里能用的功能，桌面 App 里找不到。

原因：两者共享同一 agent 和配置，但版本可能不同步，实验性功能通常先到 CLI。

排查：

codex--version/Applications/Codex.app/Contents/Resources/codex--version

两个版本号不一致就是原因。防坑规则：排查"功能消失"先对版本，再查配置。

二、沙箱与权限坑:大多数"Codex 卡住了"的真相

坑 4：Codex 看起来卡死，其实在等你批准

症状：任务停住不动，以为是程序挂了。

官方给的恢复三步：

先检查是否有待批准的 approval 请求（最常见）
跑一条简单命令验证终端状态（git status）
还不行就开一个更小更聚焦的新线程

防坑规则：Codex "卡住"时，第一反应看批准队列，不是重启。

坑 5：权限配置两极分化——要么太严寸步难行，要么直接 full access

背景：Codex 沙箱有三档文件系统模式和三档批准策略：

沙箱模式	能做什么
`read-only`	只能读，改文件/跑命令都要批准
`workspace-write`（默认）	工作区内读写 + 常规本地命令
`danger-full-access`	无任何限制（文件系统 + 网络全放开）

批准策略	行为
`untrusted`	信任集之外的命令都先问
`on-request`（默认搭配）	沙箱内自主干活，越界才问
`never`	从不弹批准

常见错误：嫌弹窗烦，直接上danger-full-access+never（即"full access"）。官方最佳实践明确列为常见错误：“granting full computer access too early”。

正确姿势：

# 官方推荐的本地自动化安全预设codex--sandboxworkspace-write --ask-for-approval on-request

需要扩大可写范围时，用sandbox_workspace_write.writable_roots添加特定目录，而不是掀掉整个沙箱。需要放行特定命令时，用Rules精确允许某个命令前缀——官方原话：“often better than broadly widening access”。

坑 6：网络请求被拦导致任务失败

症状：npm install、pip install等需要联网的命令失败或触发弹窗。

原因：默认权限下 Codex 访问网络前必须请求批准，这是设计行为不是 Bug。

修复：批准即可；高频场景用 Rules 把npm install这类命令加入允许列表。想减少人工批准又不想放开沙箱，设置approvals_reviewer = "auto_review"——让审查 Agent 替你处理升级请求。注意：auto_review只审批越界请求，不改变沙箱边界本身。

三、Worktree 坑：云任务和自动化的高发区

坑 7：代码在 Worktree 里跑不起来

症状：本地好好的项目，Codex 在 worktree 里构建/测试失败。

原因：worktree 是独立目录，只继承 Git 跟踪的文件——.env、node_modules、本地生成的配置统统不在。

官方三条修复：

通过本地环境（local environment）运行 setup 脚本
用.worktreeinclude文件声明需要复制进 worktree 的被忽略文件
把改动 checkout 回常规项目目录再验证

防坑规则：.env和依赖目录不会自动进 worktree，提前写.worktreeinclude。

坑 8：Automation 跑出一堆 Worktree 占磁盘

症状：定时任务运行几周后，磁盘被数十个 worktree 吃掉。

修复：归档不需要的 automation 运行记录；不要随手 pin 运行结果——pin 意味着 worktree 持久保留。

坑 9：多线程并行改同一批文件互相覆盖

官方常见错误列表原文：“parallel threads on the same files without git worktrees”。并行任务要么分不同文件域，要么各自用独立 worktree 隔离。

四、提示词坑：结构缺失导致返工

坑 10：提示词缺"完成标准"，Codex 自己定义"做完了"

官方提示词四要素：Goal（目标）+ Context（@ 引用相关文件）+ Constraints（约束）+ Done when（完成标准）。

最容易漏的是最后一个。没有"Done when: 所有测试通过 + lint 零报错"，Codex 可能在你认为半成品的状态交卷。

坑 11：推理档位和任务难度不匹配

官方指引：简单明确的任务用 Low，复杂工作用 Medium/High，"长程、agentic、重推理"任务才用 Extra High。反过来的浪费也真实存在——所有任务无脑开最高档，token 账单翻倍、速度变慢，产出未必更好。

坑 12：复杂任务跳过规划直接开跑

官方列为常见错误：“skipping planning on complex tasks”。三个官方工具：

Plan mode：/plan或 Shift+Tab，最简单
让 Codex 反过来采访你：需求模糊时，先让它提问把需求问清
PLANS.md 模板：多步骤大任务用

五、AGENTS.md 坑：写错比不写更糟

坑 13：把一次性指令堆进 AGENTS.md，或把长期规则塞进提示词

官方常见错误第一条：“stuffing durable rules into prompts instead of AGENTS.md/skills”。分工原则：

提示词：本次任务的目标和约束
AGENTS.md：仓库布局、构建/测试/lint 命令、代码规范、do-not 规则、如何验证工作
Skills:反复复用的提示词模式

坑 14：AGENTS.md 写成百科全书

官方建议：“keep it short and accurate”——只在发现 Codex重复犯同一个错之后才加规则（官方说法：错两次就做 retrospective）。上来就写 500 行规范,大部分是噪音。

坑 15：不知道 AGENTS.md 有层级覆盖

三层结构，最近的文件生效：全局~/.codex/→ 仓库根目录 → 子目录专属。Monorepo 里子项目规则写在子目录的 AGENTS.md,不要全堆在根上。用/init脚手架生成再改，别从零手写。

坑 16：没告诉 Codex 怎么跑测试

官方常见错误：“not explaining how to run build/test commands”。Codex 不知道pnpm test --filter=web这种项目私有命令，就会瞎猜或跳过验证。AGENTS.md 里必须有可直接复制执行的命令。

六、上下文管理坑：长会话质量下降的原因

坑 17：一个线程从周一用到周五

官方规则：one thread per task, not per project。线程越长上下文越浑浊。工具箱：

/compact——压缩当前上下文
/resume——恢复历史会话
/fork——工作真正分叉时才 fork
子 Agent——把有边界的子工作外包出去,不污染主线程

坑 18：盯着 Codex 干活

官方常见错误最后一条：“babysitting Codex rather than working in parallel”。正确姿势是给足上下文后放手让它跑，自己去做别的事,回来 review。盯屏幕逐条批准，等于把 Agent 用成了自动补全。

七、自动化与扩展坑

坑 19：手动都没跑稳就上 Automation

官方原则：“schedule only workflows already reliable manually”，以及"skills define the method, automations define the schedule"——技能定义方法，自动化定义时刻表。方法没验证过，定时跑只是定时生产垃圾。

坑 20：MCP 工具装一堆

官方建议只加"unlock a real workflow"的工具。每个 MCP server 都占上下文预算，装十个用一个,九个都在稀释注意力。

坑 21：会话日志裸奔外发

排障时会想把~/.codex/sessions的记录发出去求助。官方特别提醒:先检查有没有敏感信息——会话转录里可能有你的密钥、内网地址、业务代码。App 日志位置：~/Library/Logs/com.openai.codex/（macOS）。

常见问题

Q：Codex 突然行为异常,最快的自查顺序是什么？
版本（CLI vs App 是否一致）→ 目录（是不是在预期的项目目录）→ 批准队列（是否在等 approval）→ 新开小线程测试。官方强调多数"质量问题"其实是这四类环境问题。

Q：workspace-write默认模式够安全吗？
够日常用。它限制写入范围在工作区内,越界和联网都要批准。比它更松的danger-full-access官方名字里就带着 danger——需要它的场景极少。

Q：review 面板里出现了不是 Codex 改的文件？
Git 仓库里 review 面板反映的是完整 Git 状态。切到 “Last turn changes” 视图就只看 Codex 本轮的改动。

Q：国产模型能跑 Codex 吗？
Codex CLI 使用 Responses API 协议,与多数国内平台的 OpenAI chat 兼容接口不同。可行路径：支持 Responses 协议的平台直连，或走协议转换层。若主力工具是 Claude Code 系,七牛云等平台的 Anthropic 兼容端点是更顺的选择——选工具前先确认协议，能省一层转换的坑。

Q：任务经常做一半跑偏,怎么止损？
三件套：提示词加 “Done when” 明确验收标准；AGENTS.md 写清测试命令让它自验证；复杂任务先/plan确认方案再执行。跑偏后别在原线程里纠缠——官方建议直接开更小的新线程。

总结

Codex 的 21 个坑归纳成三句话：环境层（bubblewrap/AppArmor/版本不同步/worktree 文件缺失）在动手前一次配好；权限层记住官方安全预设workspace-write + on-request，用 Rules 和 writable_roots 精确放行而不是 full access；使用层遵守四条官方铁律——提示词带完成标准、长期规则进 AGENTS.md、一个任务一个线程、手动跑稳才自动化。这些全部来自官方文档原文,不是经验玄学——遇到新坑，先查 Troubleshooting 页,再看~/.codex/sessions日志,基本都能定位。

据 OpenAI Codex 官方文档（Troubleshooting / Sandboxing / Best Practices，2026-07-02 实时抓取）。Codex 迭代速度快，实验性功能先到 CLI，建议遇到文档与实际行为不符时先核对版本号。