Codex 用不好多数不是模型问题而是配置问题——官方最佳实践原文写着“很多质量问题其实是环境设置问题wrong directory, missing tools”。本文把官方 Troubleshooting、Sandboxing、Best Practices 三份文档中的坑点按国内开发者的踩坑频率重排为七类环境安装坑、沙箱权限坑、Worktree 坑、提示词坑、AGENTS.md 坑、上下文管理坑、自动化坑每个坑都给出官方修复方案和一条防坑规则。通读一遍大约 10 分钟能省掉的排查时间以天计。一、环境安装坑Linux 用户的第一道墙坑 1Linux/WSL2 上沙箱启动警告症状启动 Codex 出现沙箱相关 warning命令执行行为异常。原因Codex 在 Linux/WSL2 上依赖bubblewrap实现沙箱未安装时回退到内置 helper而 helper 需要非特权用户命名空间unprivileged user namespace支持。修复# Debian/Ubuntusudoaptinstallbubblewrap# FedorasudodnfinstallbubblewrapCodex 会使用PATH里找到的第一个bwrap。坑 2Ubuntu 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_userns0——全局放开安全限制官方明确说优先加载 AppArmor profile 而不是用这条。坑 3CLI 有的功能 App 里没有症状CLI 里能用的功能桌面 App 里找不到。原因两者共享同一 agent 和配置但版本可能不同步实验性功能通常先到 CLI。排查codex--version/Applications/Codex.app/Contents/Resources/codex--version两个版本号不一致就是原因。防坑规则排查功能消失先对版本再查配置。二、沙箱与权限坑:大多数Codex 卡住了的真相坑 4Codex 看起来卡死其实在等你批准症状任务停住不动以为是程序挂了。官方给的恢复三步先检查是否有待批准的 approval 请求最常见跑一条简单命令验证终端状态git status还不行就开一个更小更聚焦的新线程防坑规则Codex 卡住时第一反应看批准队列不是重启。坑 5权限配置两极分化——要么太严寸步难行要么直接 full access背景Codex 沙箱有三档文件系统模式和三档批准策略沙箱模式能做什么read-only只能读改文件/跑命令都要批准workspace-write默认工作区内读写 常规本地命令danger-full-access无任何限制文件系统 网络全放开批准策略行为untrusted信任集之外的命令都先问on-request默认搭配沙箱内自主干活越界才问never从不弹批准常见错误嫌弹窗烦直接上danger-full-accessnever即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。坑 8Automation 跑出一堆 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或 ShiftTab最简单让 Codex 反过来采访你需求模糊时先让它提问把需求问清PLANS.md 模板多步骤大任务用五、AGENTS.md 坑写错比不写更糟坑 13把一次性指令堆进 AGENTS.md或把长期规则塞进提示词官方常见错误第一条“stuffing durable rules into prompts instead of AGENTS.md/skills”。分工原则提示词本次任务的目标和约束AGENTS.md仓库布局、构建/测试/lint 命令、代码规范、do-not 规则、如何验证工作Skills:反复复用的提示词模式坑 14AGENTS.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 --filterweb这种项目私有命令就会瞎猜或跳过验证。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——技能定义方法自动化定义时刻表。方法没验证过定时跑只是定时生产垃圾。坑 20MCP 工具装一堆官方建议只加unlock a real workflow的工具。每个 MCP server 都占上下文预算装十个用一个,九个都在稀释注意力。坑 21会话日志裸奔外发排障时会想把~/.codex/sessions的记录发出去求助。官方特别提醒:先检查有没有敏感信息——会话转录里可能有你的密钥、内网地址、业务代码。App 日志位置~/Library/Logs/com.openai.codex/macOS。常见问题QCodex 突然行为异常,最快的自查顺序是什么版本CLI vs App 是否一致→ 目录是不是在预期的项目目录→ 批准队列是否在等 approval→ 新开小线程测试。官方强调多数质量问题其实是这四类环境问题。Qworkspace-write默认模式够安全吗够日常用。它限制写入范围在工作区内,越界和联网都要批准。比它更松的danger-full-access官方名字里就带着 danger——需要它的场景极少。Qreview 面板里出现了不是 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 Practices2026-07-02 实时抓取。Codex 迭代速度快实验性功能先到 CLI建议遇到文档与实际行为不符时先核对版本号。延伸资源Codex 官方 Troubleshootingdevelopers.openai.com/codex/app/troubleshootingCodex 沙箱机制详解developers.openai.com/codex/concepts/sandboxingCodex 官方最佳实践developers.openai.com/codex/learn/best-practicesCodex 配置教程https://developer.qiniu.com/aitokenapi/13417/tools-AI-Coding-api#1