这篇文章把新手最容易翻车的地方全列出来了，每个都告诉你为什么会出错、怎么解决。坑1：不写 AGENTS.md，每次都靠嘴解释为什么会出错？Codex 的对话上下文是临时的，关掉会话就没了。你不把项目规范固化成文件，它每次都得从零开始猜。猜错了改出来的东西自然不对。怎么解决？在项目根目录放一个AGENTS.md文件，写清楚这些东西：# 项目规范 ## 构建与运行 - 包管理器：pnpm（不要用 npm 或 yarn） - 构建命令：pnpm build - 测试命令：pnpm test - Lint 命令：pnpm lint ## 目录结构 - src/components/ — React 组件 - src/services/ — API 调用层 - src/utils/ — 工具函数 ## 代码规范 - 使用 TypeScript strict 模式 - 组件使用函数式写法 + Hooks - 禁止使用 any 类型，必须显式声明这个文件支持多层级配置：全局的~/.codex/AGENTS.md管通用规范，项目根目录的管项目级规则，子目录里还能再覆盖。写一次，以后每次对话 Codex 都会自动读取。坑2： 把AGENTS.md写成了CLAUDE.md为什么会出错？很多开发者从 Claude Code 迁移过来，顺手就把 Claude Code 的配置文件CLAUDE.md当成通用规范。但 Codex 读的规则文件名叫AGENTS.md，不是CLAUDE.md，不是CODEX.md，不是RULES.md。这个坑非常隐蔽：文件内容完全正确，格式也没问题，但 Codex 就是无视你的所有规则——因为它根本没读这个文件。我第一次遇到这个问题的时候，排查了整整一个小时才发现文件名写错了。怎么解决？记住这条铁律：# ❌ 错误 — Codex 不会读touchCLAUDE.mdtouchCODEX.md# ✅ 正确 — Codex 只在项目根目录自动加载touchAGENTS.md一个完整的AGENTS.md至少应包含：# AGENTS.md ## 项目概述 这是一套基于 Flask 的后端服务，负责用户认证和订单管理。 ## 必须遵守的规则 - 不要修改 `config/production.yaml` - 任何数据库迁移前先创建备份 - 新功能必须包含单元测试 ## 常用命令 - 启动开发服务：`make dev` - 运行测试：`pytest -v` - 代码检查：`flake8 src/` - 构建 Docker：`docker-compose build`AGENTS.md 的核心价值在于持久化你的项目规则。坑3：GitHub 授权给了全量权限为什么会出错？OAuth 全量授权意味着 Codex 能看到你名下每一个仓库，包括公司的、个人的、甚至已经归档的。一旦 Token 泄露或者会话被劫持，攻击面就是你的整个 GitHub。怎么解决？去 GitHub 的 Developer Settings 里生成一个 Personal Access Token（PAT），只勾选repo和你需要的workflow权限，千万别勾仓库删除和管理员权限。然后在 Codex 的授权页面选择"用 Token 连接"而不是默认的 OAuth。这样即使出了问题，你随时可以在 GitHub 上撤销这个 Token，不影响其他第三方应用。坑4：Token 额度莫名其妙就烧光了为什么会出错？Codex 启动后默认会扫描当前目录下的文件来建立上下文。如果你的项目里有node_modules、dist、.