OpenAI Codex 团队协作新手指南：单人用顺了，怎么推到小团队不崩

先看一个崩溃现场

三个人，一个仓库，每个人手上都有一份用得挺顺的 Codex。听起来挺美。两周后，真实发生的情况往往是这样：

A 让 Codex 用 pnpm 装依赖，B 的 Codex 习惯用 npm，C 干脆每次都手动改——同一个仓库的 lock 文件来回打架。评审时 A 看 B 写的代码总觉得别扭，因为两人各自的 AGENTS.md 里写的命名规范、错误处理风格根本不一样，谁也没把它当回事。一个拉取请求里混着人写的和 Codex 写的代码，评审的人分不清哪段该重点查。月底账单下来，谁也说不清这个月谁烧了多少额度、哪个项目最贵。更尴尬的是，安全同事突然问「上周那个改鉴权的提交，是 AI 写的还是人写的、它当时还跑了什么命令」——没人答得上来。

这不是 Codex 不好用，恰恰相反，是它太好用了：一个人用的时候，所有规矩都装在你自己脑子里，怎么省事怎么来，从不出问题。可一旦变成好几个人，每个人脑子里的那套规矩互不相同，仓库就成了几套习惯的角力场。

团队化要做的，就是把这些「藏在各自电脑里、各自脑子里的个人约定」，搬到「写进仓库、所有人克隆就自动继承」的明文位置上。下面这些事，本质上都是在拆解上面这个崩溃现场的某一块：

这张表不是要你照着从上到下做满。先看自己的崩溃现场卡在哪一幕，就先补对应那件事——团队化按痛点触发，不按人数触发。后面每一节就是把表里的每一行展开讲透。

第一件事：把项目规则共享出去（共享 AGENTS.md）

崩溃现场最先冒出来、也最好补的一幕，是代码风格各成一派。根因是每个人的规矩只写在自己的全局配置里，互不相干。解法很直接：把项目根的 AGENTS.md 提交进 git，所有人克隆仓库就自动拿到同一套规矩。这是团队化里投入最小、收益最快的一步，也几乎一定是你该先动手的那件事。

AGENTS.md 是 Codex 的指令文件，类似给智能体看的 README。Codex 按三层加载它，越靠近你工作目录的越优先：

团队怎么用好它，三条实操：

1. 项目根那份必须进 git：这是全队共享的单一来源。写清「跑哪个 lint、用哪个包管理器、提交前要做什么、评审看什么」。
2. 改动走拉取请求评审：多个人会改同一份项目根 AGENTS.md，让改动经过评审再合并，避免一个人单方面改了规矩影响全队。
3. 需要临时盖掉某条规则时用就近的子目录 AGENTS.md，而不是去改全局——把覆盖放在离专属工作最近的地方。

项目根那份共享 AGENTS.md 写多细才合适？给新手一个起步骨架的感觉（不必照抄，按你项目改）：

# AGENTS.md## 项目约定- 包管理器统一用 pnpm，不要混用 npm / yarn。- 提交前先跑 `pnpm lint` 和 `pnpm test`，全绿再开拉取请求。- 改了公共工具函数，同步更新 docs/ 下对应说明。## 评审准则- 重点看：输入校验、错误处理、有没有把密钥写进代码。- 不接受没有测试的新功能。

把高频套路共享出去（共享 Skills）

规则共享好了，下一幕痛点是：团队里那些「该怎么做一件复杂事」的套路，全靠老人口口相传，新人反复踩同样的坑。解法是 Skills（技能）——Codex 的可复用工作流，把一件复杂事的标准做法打包好，下次喊一声就跑。团队共享走「项目层」：把仓库里的 .agents/skills 目录提交进 git，团队克隆项目就拿到。

和 AGENTS.md 一样，Skill 也分全局和项目两层：全局放 ~/.agents/skills，项目放仓库里的 .agents/skills。一个 Skill 通常是一个 SKILL.md 文件，加上可选的脚本、参考资料和素材。需要自动安装的依赖，在 agents/openai.yaml 里声明。

共享 Skill 有一个比 AGENTS.md 更隐蔽的坑，值得单独拎出来：

对应的两条防御动作：

1. 共享前在多台队友机器上各验证一遍，别只在自己机器上测过就发。把外部依赖写进 agents/openai.yaml 让它自动装，减少环境差异。
2. 建一份 Skills 内部目录：列清这个库里都有哪些 Skill、各自干什么、谁维护。否则库一大，队友根本不知道有什么、该用哪个。

一个团队 Skill 目录的最简结构长这样，新人一眼能看懂库里有什么：

.agents/skills/├── 新建标准服务/│ └── SKILL.md← 一步步建一个符合项目规范的新服务├── 发布前检查/│ └── SKILL.md← 跑完整发布前清单（lint / 测试 / 构建 / 变更日志）└── 排查线上日志/├── SKILL.md└── scripts/← 配套脚本

判断一个套路该不该写成共享 Skill，只有一条标准——它是不是被多个人、反复手动重复。你一个人偶尔用的，留在个人层 ~/.agents/skills 就行；全队每周都要做、还容易做错的（比如「新建一个标准服务」「跑一遍发布前检查」），才值得提交到项目层共享。所以团队化别一上来就把所有套路都塞成共享 Skill：先挑最高频、最容易出错的一两件做出来验证收益，再逐步扩。把一次性的东西硬写成 Skill，正是 Skill 库膨胀失控、然后到处「跑不通」的起点。

让 Codex 把第一道关（Cloud 代码评审）

人写的和 AI 写的代码混在一个拉取请求里、评审分不清重点，是崩溃现场的另一幕。Codex Cloud 能直接在 GitHub 的拉取请求上做代码评审，帮人类把第一道关。配置上你只需要决定一件事：让它「按需触发」还是「自动触发」，评审标准则跟着 AGENTS.md 走。

前提是这个仓库已经接好 Codex Cloud。接好之后，两种触发方式：

• 按需评审：在拉取请求的评论里写 @codex review，Codex 会回应并像团队成员一样留下一条评审意见。
• 自动评审：在设置里打开「Automatic reviews」开关，之后每个拉取请求一打开就自动评审，不用手动 @。

评审时 Codex 只标记 P0、P1 级别的高优先级问题，让评论聚焦真正的风险，而不是淹没在鸡毛蒜皮里。评审标准来自最靠近改动文件的那份 AGENTS.md——在里面写一段「评审准则」即可定制；给某个关键模块加更严的子目录 AGENTS.md，那个模块就会被更仔细地审。评审完想让它直接修，评论 @codex fix the P1 issue，在它有权限时会把修复推回分支。

新手判断三条：

1. 团队 3 人以上、人工评审成为瓶颈时，开自动评审的价值才明显；人少时按需评审就够。
2. 先把项目根 AGENTS.md 的评审准则写好——评审质量直接取决于这份准则，准则空泛，评审也空泛。
3. 先按需、后自动：一开始用 @codex review 让团队熟悉它的评审风格，再切自动评审，避免一上来满屏自动评论造成噪声。

怎么让评审更准？关键是在项目根 AGENTS.md 里写清「这个项目的评审到底看什么」。一段评审准则的起步样子：

## 评审准则（Codex 代码评审参照）- P0 必拦：密钥/令牌硬编码、SQL 拼接注入、绕过鉴权。- P1 关注：缺输入校验、错误被吞掉、新代码没测试。- 本仓 services/payments/ 涉及金额计算，按更严标准审。

写了这段之后，Codex 的评审就不再是泛泛的「代码看起来还行」，而是对着你的真实风险清单逐条挑。

搞清楚谁烧了多少额度（成本与权限治理）

月底账单说不清谁用了多少，是团队再大一点就会撞上的一幕。先把一个现实讲在前面：原生 Codex 没有「按团队成员细分用量」的现成报表，这是当前生态的真实空白。好在小团队不用为此上重型方案——账号隔离就够，规模大了再加一层「AI 网关」。

具体做法按团队规模分两档：

3 到 5 人小团队（不必上重型方案）：

1. 每个人用自己的付费会员账号，额度天然独立、互不挤占。
2. 在 ChatGPT Business 工作区里，每个成员有各自独立的 Codex 历史，各自的用量和记录便于自己追溯。
3. 月底按账号人均报销，简单清晰。

团队变大或要做合规审计：

社区主流解法是在 Codex 和模型之间加一层「AI 网关（AI Gateway）」：每个开发者用一个虚拟接口密钥（不是真密钥），所有请求经过网关，网关层做按密钥计费、按团队聚合、按个人限额。常见的开源或商业网关有 LiteLLM、Helicone、Portkey 等。

给危险动作统一装刹车（沙箱标准化与安全合规）

最后一幕崩溃是：危险操作没有统一的刹车，事后还追溯不到 AI 跑过什么。团队安全要做的，就是把每个人各自的权限设置收敛成一套全队标准——所有人用同一档沙箱、越界统一要审批、AI 写的代码可追溯。这件事可以拆成由浅入深的三块来落地。

沙箱标准化。 Codex 有三档沙箱模式：

配合审批策略（approval_policy）：默认是 on-request，Codex 越过沙箱边界（比如改工作区外的文件、要联网）前会先要确认。团队统一用 workspace-write + 合理的审批策略，就能保证「没有人能在不被提示的情况下让 Codex 干越界的事」。

审计与追溯。 用同一套配置约束所有人，配合可观测平台记录 Codex 执行过哪些命令，做到「谁让 AI 跑了什么」事后可查。

AI 代码标识。 给 AI 生成的拉取请求加 [AI] 标签，或用专属的提交作者邮箱，让评审时一眼就知道「这段是 AI 写的」，从而加严审查。

还有一条数据底线必须讲清：OpenAI 公开说明，对商业用户默认不拿你的输入输出训练模型，ChatGPT Business 的数据默认排除在训练之外。商业敏感代码场景，要用 Business 或 Enterprise 档，而不是个人版——这不是优化项，是合规底线。

一个人怎么办：用「轻团队」做法拿团队级产能

读到这里你可能会说：我根本没有团队，一个人撑一摊事（独立开发者、一人公司）。那么前面那些「共享」「治理」「评审流程」对你确实用不上——但「团队级的并行产能」这件事，一个人照样能要，而且不用招人，靠的是 Codex 自带的并行能力。这套做法我习惯叫它「轻团队」，靠三招：

1. 多线程并行（worktree 工作树）：用 Codex 的 worktree 模式同时跑多个互不干扰的任务，相当于「自己 + 几个虚拟队友」同时在干活。
2. 多袋里委托（subagents 子袋里）：在一个任务里让 Codex 派出多个子袋里并行调研、再汇总结果，相当于「自己领头 + 几个研究员」。子袋里用 TOML 文件定义，个人的放 ~/.codex/agents/、项目的放 .codex/agents/，每个文件写清名字、什么时候用、行为指引，靠 /agent 命令管理。
3. 多机调度：多台机器同步同一套配置，定时跑批量任务，相当于管理多个虚拟工位，让机器在你睡觉时也接着干。

把东西放在哪一层，决定将来换工具有多痛

团队选工具时，有一个常被忽略但很现实的问题：将来想换工具，沉淀下来的东西搬得动吗？ 答案取决于你把东西放在了哪一层。

所以选工具时不妨先问自己一句「未来换工具的可能性有多大」。可能要换，就把更多规则放进 AGENTS.md（最保险），少依赖 Skills 和 hooks 这类工具私有特性；确定长期绑定一家，再深用它的私有能力换效率。这是一个关于「灵活性 vs 效率」的取舍，没有标准答案，但要在团队化早期就想清楚，别等沉淀了一大堆私有配置才发现搬不动。社区主流的分层策略也印证这一点：项目铁律放 AGENTS.md（保险），复杂工作流写 Skill（成本中等），深度生命周期治理才用 hooks（绑定最深）——按「换工具痛感从低到高」摆放，是相对稳妥的默认选择。

团队化最容易翻车的几个地方

把前面散落的踩坑收成一张反模式清单，团队化时逐条避开：

• 一次性上完整企业配置。正确做法：哪个痛点先烦到你就先补对应那件事，先跑通项目根共享 AGENTS.md 这个最小动作，别一上来铺满。
• 个人偏好混进项目共享文件。正确做法：个人偏好放 ~/.codex/AGENTS.md，项目规则才进仓库。
• 共享 Skill 只在自己机器上测过。正确做法：发布前在多台队友机器各验证，依赖写进 agents/openai.yaml，建内部目录。
• 以为开了自动评审就不用人工评审。正确做法：Codex 评审是初审 + 高优先级过滤，架构、业务、安全的终审仍归人类。
• 临时放开沙箱忘了切回。正确做法：沙箱档位全队统一，临时放开必须写进规则强制切回，绝不让某台机器长期开 danger-full-access。

跑两周后，下一步往哪走

如果你已经动手补了第一件事，给一个落地节奏参考，按周往前推：

• 第 1 周：先让规则共享落地——项目根一份共享 AGENTS.md 进 git，全队克隆即用，观察代码风格各成一派的现象有没有缓解。
• 第 2 周：接 Cloud 代码评审——给一个仓库开按需评审（@codex review），让团队熟悉它的评审风格，把评审准则写进 AGENTS.md。
• 第 3-4 周：按团队真实痛点选下一件——套路靠口口相传就做共享 Skills，额度看不清就补成本治理，有合规要求就做沙箱标准化与审计。

判断进度的标准不是「配了多少」，而是最初那个崩溃现场有没有被一幕幕拆掉：风格还乱不乱、配置还漂不漂、额度说不说得清、AI 代码追不追得到。哪一幕不再发生，对应那件事就算到位了。

收尾时可以拿下面这张清单对照自己的团队现状，逐条勾选：

• [ ] 项目根有一份提交进 git 的共享 AGENTS.md，全队克隆即用。
• [ ] 个人偏好放在 ~/.codex/AGENTS.md，没混进项目共享文件。
• [ ] 共享 Skill 在多台机器验证过，依赖写进 agents/openai.yaml，有内部目录可查。
• [ ] 关键仓库接好 Codex Cloud 代码评审，评审准则写进 AGENTS.md。
• [ ] 成本归集方式明确（小团队账号隔离 / 大团队 AI 网关）。
• [ ] 全队统一 workspace-write 沙箱 + 合理审批策略，没有机器长期开完全访问。
• [ ] AI 生成的代码有标识（[AI] 标签或专属提交邮箱），可追溯。
• [ ] 商业敏感代码用 Business / Enterprise 档，确认数据默认不用于训练。

勾不满也没关系——回头看自己的崩溃现场卡在哪一幕，痛在哪就先补哪条。团队化是逐步推进，不是一次满分。

一句话收官

OpenAI Codex 从单人到团队，难的从来不是工具更复杂，而是把「装在各自脑子里的规矩」变成「写进仓库、全队自动继承的明文制度」。开篇那个三个人一个仓库的崩溃现场，每一幕都对应一件该补的事：风格乱了补共享 AGENTS.md，套路靠传补共享 Skills，评审分不清重点上 Cloud 代码评审，额度算不清做成本治理，危险动作没刹车做沙箱标准化。不按人数、按痛点触发，哪幕先发生就先补哪件，最小动作永远是「项目根放一份共享 AGENTS.md」。就算只有你一个人，也能用「轻团队」三招拿到团队级产能。