结论先说
- 跨仓开发首选在主仓库启动并重复传入
--add-dir。例如进入后端目录后运行codex --add-dir ../shop-web --add-dir ../shared-types,即可在单次会话里同时读取并协同修改三个目录。 - 不要为了省事直接挂载整个总工作目录(如
~/workspace)。放开整个父目录会把无关项目全暴露给沙箱且拖慢检索,还容易触发非 Git 仓库校验提示;只精确挂载本次联调涉及的目录最稳妥。 --add-dir的写入权限仍受当前沙箱模式约束。配合--sandbox workspace-write时,挂载进来的目录拥有受控写权限且.git依然受保护;若只想让 Codex 跨仓比对接口而不改动任何代码,加上--sandbox read-only即可。- 每个子仓库的
AGENTS.md与 Git 状态彼此独立。各仓在自己根目录写清构建与类型检查命令,改完后务必分别检查每个仓库的git diff并按依赖顺序独立提交。 - 跨三仓联合检索与全量类型检查会占用较大上下文窗口。国内无外币卡的用户可在本站自助开通 ChatGPT Plus 或高配额的 ChatGPT Pro,团队多人研发可了解 ChatGPT Business 团队定制。

图:本站根据 OpenAI Codex 官方文档:Command line options 整理的示意图
本文根据 OpenAI Codex 官方文档《Command line options》《Sandboxing》《AGENTS.md》整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 前端、后端和公共类型包拆在多个独立 Git 仓库里,经常因为改一个接口字段要在多个窗口来回拷贝定义的开发者;
- 尝试直接在整个父级大目录启动
codex,却发现提示不在受信任仓库内或索引过慢的人; - 希望在保证最小安全边界的前提下,让 Codex 一次完成跨仓契约对齐、联调修改与各自单测校验的工程师。
一、--add-dir 的核心机制与三种跨仓方式对比
默认情况下,Codex 把启动时所在的当前目录视为唯一工作区根目录(沙箱边界细节见 /guides/codex-permissions-sandbox)。当你的前后端和共享契约包平级存放时,直接打开父目录容易遇到非 Git 仓库信任警告(详见 /guides/codex-not-inside-trusted-directory-skip-git-repo-check),而 --add-dir 正是为精确声明多工作区而设计的:
| 启动方式 | 典型命令 | 暴露范围与安全边界 | 检索与维护体验 |
|---|---|---|---|
| 默认单目录 | codex | 仅当前仓库可写,看不到兄弟仓库 | 隔离好,但跨仓字段需手工粘贴 |
精确 --add-dir(推荐) | codex --add-dir ../web --add-dir ../types | 仅主仓与指定挂载目录纳入工作区,各仓 .git 仍只读 | 范围精准,一次会话打通前后端联调 |
| 从总父目录启动 | cd ~/projects && codex | 暴露全部无关仓库,误改风险大 | 易触发非 Git 目录校验且噪音文件过多 |
常用命令写法
假设本地目录结构为 ~/work/shop-api、~/work/shop-web、~/work/shared-types:
bash
# 在后端仓库作为主目录启动,同时挂载前端与共享类型目录
cd ~/work/shop-api
codex --sandbox workspace-write \
--add-dir ../shop-web \
--add-dir ../shared-types
如果只想做一次只读契约巡检(例如检查前端调用字段与后端最新 DTO 是否全部一致,不修改任何文件),可以直接配合非交互模式与只读沙箱:
bash
codex exec --sandbox read-only \
--add-dir ../shop-web \
--add-dir ../shared-types \
"核对 shop-api 的订单响应 DTO、shared-types 定义与 shop-web 页面渲染字段,列出所有字段名或可空类型不一致的位置。"
二、前后端双仓 + 共享类型目录四步联调实战

图:本站根据 OpenAI Codex 官方文档:Sandboxing 整理的示意图
把三个目录挂进同一个会话后,最怕模型同时乱改导致编译报错缠成一团。本站建议按以下四步推进:
第一步:在各仓库各自维护简明 AGENTS.md
在 shared-types、shop-api、shop-web 根目录分别放一份简短 AGENTS.md(读取优先级规则见 /guides/codex-agents-md-how-it-reads),只需写明该仓库的类型检查、打包与测试命令(如 pnpm build、pytest -q、npm run typecheck),Codex 切目录验证时就不会猜错脚本。
第二步:把固定联调组合封装为终端快捷函数
每天重复敲两三个相对路径很容易拼错,本站建议写入 ~/.zshrc 或 ~/.bashrc:
bash
codex-shop() {
(cd ~/work/shop-api && codex --sandbox workspace-write \
--add-dir ../shop-web \
--add-dir ../shared-types "$@")
}
如果希望把相关沙箱写根策略长期写入配置模板,也可结合个人或项目级 config.toml 管理(语法参考 /guides/codex-config-toml-complete-guide)。
第三步:提示词里明确「契约先行」的修改顺序
发起联调任务时,明确要求 Codex 严格按依赖上游到下游的顺序分步改并分步验收:
text
请给订单详情接口新增 estimatedDeliveryAt(ISO 字符串,可为空):
1. 先修改 ../shared-types 中的 OrderDetail 类型并运行构建;
2. 再修改当前 shop-api 仓库的序列化逻辑与单测并跑通;
3. 最后修改 ../shop-web 的订单详情卡片展示与类型检查;
若涉及只读参考仓请明确提示,不要自动执行 git commit 或 git push。
第四步:分别核查各仓分支与差异后再依次提交
由于 --add-dir 挂载的是多个独立 Git 仓库,所有改动会分散落盘在各自工作树里。验收完后务必对三个目录分别检查分支名与 git status / git diff,再按「共享包发布或同步 -> 后端合入 -> 前端合入」的顺序分别提 PR。
订阅与账号准备提示:跨仓联调会同时读取前后端接口代码、类型定义与测试夹具,单次任务的上下文体积通常是单仓任务的二到三倍。若 Plus 档在联调密集期容易触发限额,可在本站升级 ChatGPT Pro 充值 或选用 ChatGPT Pro 5x iOS 可覆盖档;新注册账号若遇到手机短信验证受阻,也可查看 Codex 注册手机验证服务。
三、跨仓挂载常见坑与避坑要点
- 切勿混改不相关分支:启动前先确认三个仓库都已切到对应需求分支且工作树干净,否则 Codex 改完后很难把新旧改动从
git diff里拆开。 - 只需要参考某仓库文档或 SDK 源码时写明「只读参考」:当挂载进来的第三个目录是底层公共库、不打算本次修改时,在首条提示词里显式约束「
../legacy-sdk仅作只读参考,禁止修改」,避免模型顺手去改公共依赖源码。 - Windows 路径含空格需加双引号:在 PowerShell 中传参类似
--add-dir "D:\work repos\shop-web",避免空格把单个路径拆成无效参数。
常见问题
问:--add-dir 最多可以同时挂载多少个目录?
答:命令行支持连续传入多个 --add-dir,但本站建议单次联调控制在 2 到 4 个强相关目录内。挂载过多仓库不仅增加误改风险,也会让检索范围变宽、消耗更多上下文配额。
问:挂进来的兄弟仓库里如果也有 AGENTS.md,会被正确识别吗?
答:Codex 在读取或修改某个目录下的文件时,会结合对应路径层级下的指引文件。不过为了万无一失,涉及跨仓强约束(例如禁止修改某个共享目录或要求特定验证顺序)时,最好仍在主会话提示词里重申一遍。
问:国内没有外币信用卡,或者研发团队需要开增值税发票报销,怎么开通适合多仓库联调的 Codex 订阅?
答:可通过本站 AI 会员充值总览 办理 ChatGPT Plus 卡密自助兑换 或高配额 ChatGPT Pro,多人研发团队可直接选择 ChatGPT Business 团队定制。支持支付宝、微信支付及 AlipayHK 付款,无需交出账号密码,可开具增值税发票;实时价格以商品页展示为准,售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。
相关教程
- Codex 权限模式与沙箱机制详解
- Codex 怎么读取 AGENTS.md 与层级优先级
- Codex config.toml 配置文件完全指南
- Codex 报 not inside a trusted directory 与 --skip-git-repo-check 处理
参考资料
- OpenAI Codex 官方文档:Command line options — https://learn.chatgpt.com/docs/developer-commands
- OpenAI Codex 官方文档:Sandboxing — https://learn.chatgpt.com/docs/sandboxing
- OpenAI Codex 官方文档:AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
0 条评论
还没有评论,来抢沙发~