Codex 多目录项目：主目录如何决定 Git 和规则发现

来源核对：OpenAI 在 2026 年 7 月 23 日的 Codex changelog 发布本地多目录项目；本文于 2026 年 7 月 27 日对照 Projects and chats 官方文档 复核。

这次更新真正改变了什么

一个本地项目现在可以挂载多个相关文件夹。Codex 可以搜索、读取和编辑所有已挂载目录，但你必须指定一个 primary folder（主目录）。

主目录不是视觉上的排序选项，它决定：

• 新对话的默认工作目录。
• Git 操作和 Pull Request / worktree 工作流面向的主仓库。
• AGENTS.md、Skills 和 config.toml 的自动发现位置。

次要目录仍然可以被搜索、读取和编辑，但 Codex 不会自动发现其中的项目规则文件。

哪些项目适合放在一起

适合使用多目录项目：

• Web 应用与单独维护的文档仓库。
• 前端站点与对应的后端服务。
• 产品代码与同一交付目标下的部署配置。
• 主仓库与需要同步更新的示例或 SDK。

应该拆成不同项目：

• 彼此无关、没有共同交付目标的仓库。
• 权限或敏感级别不同的代码库。
• 希望每个对话只能访问单一仓库的工作。
• 需要各自自动加载不同 AGENTS.md、Skills 或 config.toml 的项目。

官方文档目前说明，远程项目仍只支持一个文件夹。

选择主目录的三个判断标准

1. 提交最终落在哪个仓库

需要创建分支、检查 diff 或发起 Pull Request 的仓库，通常应该设为主目录。

2. 哪套规则必须自动生效

如果任务依赖仓库内的 AGENTS.md、项目 Skills 或 .codex/config.toml，把包含这些文件的仓库设为主目录。不要假设次要目录里的规则会自动合并进来。

3. 哪个目录代表任务的默认语境

新对话会从主目录开始。一个“修改产品并同步文档”的项目，通常以产品仓库为主；一个“根据 API 变更重写文档”的项目，则可能更适合以文档仓库为主。

推荐的跨目录任务写法

主仓库：web-app，负责实现和 Git 提交。
次要目录：product-docs，只允许同步本次行为变化对应的文档。

先读取主仓库规则并确认影响范围；不要把次要目录中的配置当成自动生效规则。
修改后分别列出两个目录的变更，并在各自可用的验证路径中检查结果。

这段说明不能替代沙箱权限，但可以把提交归属、规则来源和允许修改范围说清楚。

容易踩的四个坑

• 以为挂载等于规则继承：次要目录可读写，不代表其中的 AGENTS.md 会自动生效。
• 让 Git 操作指向错误仓库：PR、worktree 和 Git review 以主仓库为目标。
• 把权限边界和目录组织混为一谈：项目和 worktree 负责组织工作，真正的本地读写与网络访问仍由沙箱控制。
• 为了方便一次挂载过多目录：目录越多，可被搜索和误改的范围越大；只挂载同一交付真正需要的文件夹。

今天可以怎么用

从“应用 + 文档”这一类低耦合组合开始。添加目录后先执行一个只读任务，让 Codex 分别说明主目录、可访问目录、自动发现的规则和计划使用的 Git 仓库；这些边界确认无误后，再允许它修改文件。