AI Code With · Codex 多项目与工程化配置指南

只有一个 Codex 项目时，很多配置问题都不会暴露。一个默认模型、一条 API Key、一个工作目录，能跑就行。

真正开始失控，往往是第二个、第三个项目出现以后：你为了测试环境改了全局配置，另一个项目跟着变；两个 Codex 任务在同一个目录里同时改代码；生产和实验共用一条 Key，费用异常时根本不知道是谁产生的；最后又把 Codex 接进 GitHub Actions，让 CI 拿着高权限 Secret 自动跑。

这些问题看起来分别属于 Profile、API Key、Git 和 CI，实际上都在解决同一件事：把不同项目、不同任务、不同执行环境的影响范围缩小。

多项目管理不是把所有东西复制四份，而是让“配置、凭证、文件和权限”四层边界都能被看见、被验证、被单独关闭。

1. 先画清楚四层隔离：配置、凭证、文件、权限

如果你把 Codex 多项目问题拆成四层，后面的所有选择都会清楚很多。

隔离层	解决什么问题	典型工具 / 方法	常见事故
配置层	不同项目使用不同模型、权限、工具或运行参数	Codex Profile / 显式启动参数	改一个全局配置，另一个项目第二天跟着变化
凭证层	知道哪个项目在调用、异常时只停一部分	项目 / 环境 Key、Secret、环境变量	一个 Key 散落本地、CI、脚本，谁在花钱完全看不出
文件层	并行任务互不覆盖工作区	Git worktree / 独立分支	A 刚改配置，B 按旧结构继续写；lockfile 相互覆盖
权限层	自动化只拥有完成当前任务所需的最小能力	GitHub Actions permissions、Codex permission profile、Secret	CI 为了省事直接给写权限和高权限密钥

这四层不能互相替代。比如 Profile 能切模型，但不能防止两个 Agent 同时修改同一批文件；worktree 能隔离文件，却不会自动隔离数据库、端口和 API Key；CI 里即使仓库权限是只读，高权限运行用户仍可能让 Secret 暴露面变大。

2. 第一层：用 Codex Profile 把环境差异显式化

同一台电脑上跑多个 Codex 项目，最危险的不是配置多，而是你不知道这次到底加载了哪一份。Profile 的意义，就是把“这个项目和默认环境哪里不同”写成一个明确的覆盖层。

当前 Codex v2 Profile 的常见结构，是把基础配置留在 CODEX_HOME 的 config.toml，再为不同用途创建单独的 <name>.config.toml，并通过 --profile 显式选择。

基础配置只放真正共用的东西

# ~/.codex/config.toml

# 只放所有项目都长期共用的默认值

model = "<default-model>"

这里不要把每个项目的特殊模型、权限和临时实验都塞进去。基础层越稳定，后面越容易判断一个项目究竟覆盖了什么。

Profile 只写差异，不要复制整份 config.toml

# ~/.codex/work.config.toml

# 只示意结构，字段和值以当前 Codex 版本为准

model = "<verified-work-model>"

然后显式启动：

codex --profile work

真正需要强调的是“最小覆盖”。如果 Profile 变成完整复制，每次升级或改配置都要同步多份文件，反而更容易制造隐性差异。

Profile 名字不是安全边界，实际生效状态才是

不要因为文件叫 test，就默认它一定连的是测试资源。团队长期维护时，Profile 的含义会漂移，最稳的是启动后检查模型、权限和关键配置是否真的生效。

近期 Codex 的 Profile 机制经历过 v1 到 v2 的迁移，旧教程中的 [profiles.name] 结构不再适合直接照抄；另外，社区近期也出现过“指定的独立 Profile 文件缺失时回退到基础配置”的问题报告。

所以如果一个项目对权限或 Provider 很敏感，别只记住自己敲过 --profile。要让最终状态可观察：启动头信息、/status、有效配置或一个最小测试，至少确认一项。

敏感信息不要塞进 Profile

Profile 是配置差异，不是 Key 仓库。配置文件可能被同步、备份、复制到工单或聊天里，一旦把 API Key 写进去，后续很难追踪泄露范围。

Key 应该由 Secret、环境变量或对应凭证存储提供。Profile 只负责选择哪个 Provider、模型或运行策略。

3. 第二层：API Key 按“工具 + 项目 + 环境”做可识别归因

一开始只有一个项目时，共用一条 Key 完全可以工作。问题是当 Key 被复制到第二个仓库、CI、临时脚本和测试机以后，余额突然变化时你会失去最重要的信息：这次调用到底是谁产生的。

AI Code With 当前 API Key 管理支持为不同用途创建独立密钥，并可设置消费限额、渠道和模型限制。这种能力最适合拿来做 Codex 多项目的“调用归因”，而不是让所有项目共用一串万能 Key。

Key 名称至少回答三个问题

一个实用的命名方式是：

codex-site-dev

codex-data-prod

codex-lab-test

codex-ci-review

看到名字，就应该知道谁在用、用在哪里、出问题时该停哪一条。

临时实验可以使用低额度测试 Key；生产项目尽量独立；只需要少数模型的项目，可以限制模型范围，降低配置串线后误调用其他模型的风险。

不要机械追求“一项目一 Key”

隔离的目标是缩小影响范围，不是追求形式上的颗粒度。平台本身会有当前的 Key 数量与账户限制，具体上限应以你配置当天的控制台为准，不应该把历史文章里的数字写死。

项目数量少时，按项目拆最清楚；项目很多时，可以按风险和生命周期合并：生产独立、长期开发独立、临时实验共用低额度 Key，停更项目及时停用。

每周只做四步核对，已经能解决大部分问题

• 按 Key 看近期费用。

• 确认实际调用的模型与渠道是否符合预期。

• 看最近调用时间，判断是否仍有项目在使用。

• 停用已经没有负责人、没有调用或不再维护的 Key。

后台记录可以把异常缩小到时间、Key、模型和费用，但它不会自动告诉你根因是代码循环、超长上下文还是上游重试。定位到项目以后，仍然需要回项目日志和请求行为继续查。

4. 第三层：并行 Codex 任务不要共享同一个工作目录

配置和 Key 都隔开以后，还有一个更直接的问题：文件。两个 Codex 任务如果在同一个目录同时改代码，真正危险的甚至不是最后 merge 冲突，而是冲突发生之前其中一个任务已经建立在另一个任务的旧状态上。

Git worktree 解决的是文件系统层的隔离。每个 worktree 都有自己的 checkout 和分支，但共享同一个仓库的 Git 元数据，不需要把整个仓库复制很多份。

给每个任务一个独立 worktree

git worktree add ../project-task-a -b codex/task-a main

git worktree add ../project-task-b -b codex/task-b main

git worktree list

然后让每项 Codex 任务只在自己的目录工作。任务说明里写清允许修改的路径、验收命令和禁止触碰的共享配置。

目录名最好能对应任务，而不是 tmp1、tmp2。几天后出问题，清晰名字能直接告诉你哪个目录属于哪个分支。

worktree 只隔离文件，不会帮你隔离端口、数据库和云资源

这点非常容易被忽略。两个 worktree 仍可能抢同一个 3000 端口、同一个开发数据库、同一个 Redis、同一个测试账号，甚至共用用户级依赖缓存。

因此并行前最好列一张共享资源表：哪些资源可以分配不同端口或不同测试数据，哪些只能有一个任务写入。

lockfile、数据库迁移、代码生成结果和全局配置尤其容易冲突。可以按任务分配所有权，或者指定其中一个任务为唯一写入者。

合并前先把每个任务变成“可验证的提交”

git -C ../project-task-a status

git -C ../project-task-a diff --check

# 运行项目自己的测试

# 确认后再 commit

不要在主目录手动复制文件。更稳的流程是：worktree 内看 diff → 跑测试 → 提交 → 回主分支审查 commit → merge 或 cherry-pick。

如果两个任务有依赖，先合并基础变化，再让后续分支 rebase / 重新验证。不要拿两份旧测试结果当成最终证据。

清理 worktree 也属于交付流程

git worktree remove ../project-task-a

git worktree prune

确认提交已经进入目标分支、目录没有需要保留的未提交变化，再清理。不要直接删文件夹后假装结束，Git 仍可能保留 worktree 记录。

OpenAI 当前也把 worktree 作为 Codex App 并行 agents 的核心能力之一；更大规模的工程实践里，甚至会为每个 worktree 启动独立应用实例、日志和指标环境。worktree 的价值不是“多开几个 Agent”，而是让每个 Agent 有一块不会被旁边任务随手改掉的地面。

5. Key 与 worktree 要配合：一个解决“谁在花钱”，一个解决“谁在改文件”

很多人会问：既然已经按项目拆 Key，还需要 worktree 吗？或者已经 worktree 隔离，还需要不同 Key 吗？

答案是需要，因为它们解决的是两种不同事故。

事故	Key 隔离能不能解决	worktree 能不能解决
不知道哪个项目产生调用费用	能	不能
一个项目 Key 泄露，需要只停该项目	能	不能
两个 Codex 同时覆盖同一文件	不能	能
两个任务抢同一数据库 / 端口	不能	不能，需要额外资源隔离
两个任务最后合并冲突	不能	只能降低混写风险，仍需 Git 合并与测试

多项目环境里，“调用归因”和“文件隔离”是两条独立控制线。

6. 第四层：进入 GitHub Actions 后，先设计权限，再放 Secret，最后才写 Prompt

把 Codex 接进 GitHub Actions 以后，风险等级会明显提高。因为这时不再是你坐在终端前手动确认，而是一个自动化流程拿着仓库内容、运行权限和 API Key 根据事件触发。

当前 OpenAI 官方提供 openai/codex-action@v1。它会安装 Codex CLI，并通过 Responses API 代理运行 codex exec。现在官方文档比早期版本更强调 permission-profile 与 safety-strategy，所以不要只看一段最小 YAML 就以为“contents: read”已经足够。

第一次接入，从只读审查开始

permissions:

contents: read

steps:

- uses: actions/checkout@v5

- name: Run Codex review

uses: openai/codex-action@v1

with:

openai-api-key: ${{ secrets.OPENAI_API_KEY }}

permission-profile: ":read-only"

prompt: |

只检查本次变更的错误处理。

返回发现和证据。

不修改文件。

这里展示的是结构思路，不应该被当成“永远可复制”的完整成品。字段和版本需要以你运行当天的官方 action 文档为准。

如果工作流确实需要修改 checkout，当前官方更推荐使用 permission-profile: ":workspace"，而不是新工作流继续依赖旧的 workspace-write sandbox 习惯。

GitHub permissions 和 Codex permission profile 是两层权限

GitHub 的 permissions 控制 workflow token 能对仓库做什么；Codex 的 permission profile 控制 Codex 命令能访问哪些文件、网络和工作区。

两者都要最小化。只把其中一层收紧，并不意味着另一层自动安全。

Secret 只进入需要它的执行链，不要跟着 Prompt 四处传播

API Key 应放在 GitHub Secret，不写仓库、不放 prompt、不打印到日志。来自 fork 或其他不可信输入的事件尤其需要谨慎，因为外部贡献者能控制代码和部分上下文。

团队如果使用 AI Code With 管理多模型入口，可以单独给 CI 创建一个用途清晰的 Key，并通过控制台限制模型、渠道或额度；但 GitHub 侧仍然必须把 Secret 作为 CI Secret 注入，不能把控制台值复制进 YAML。AI Code With 也不会替 GitHub 判断一个事件是否可信。

当前 openai/codex-action 的安全文档还特别提醒：GitHub-hosted runner 的权限和进程环境会影响 Secret 暴露面。默认 drop-sudo 是官方推荐的安全策略之一；Windows runner 当前没有同等沙箱能力，官方 action 只支持 unsafe 策略，这不是应该顺手照抄到生产的默认方案。

写权限要和任务一起升级

只读审查只需要读。要让 Codex改文件、提交补丁、更新分支或发评论时，才增加对应权限，并且只增加当前任务真正需要的范围。

一个更稳的工程流程是：Codex 先产出报告或受控补丁 → 人或独立步骤检查 diff 和测试 → 再由受控流程提交。不要为了少一次确认，就让所有事件默认拿到 write。

Prompt 不是“让 AI 自由发挥”，而是 CI 验收合同

“优化一下代码”在 CI 里几乎没有可验收性。更合适的写法应该包含：目标文件或范围、禁止修改的区域、必须运行的检查、输出格式，以及遇到不确定事实时停止。

如果规则很长，可以使用 prompt-file 版本化，但这个规则文件本身同样应该进入 Review。

7. 一个完整现实案例：三个 Codex 项目 + 一个 CI Review 怎么分？

假设团队现在有三个长期项目：官网、内部后台、SEO 自动化；同时 GitHub Actions 里还跑一个 Codex 只读 Review。

如果所有东西都放在默认配置、同一个 Key、同一个工作目录里，短期最省事，长期最难查。一个更实用的结构可以是：

场景	Profile / 启动方式	Key	文件隔离	权限策略
官网开发	web.config.toml / --profile web	codex-web-dev	feature worktree	本地 workspace 范围
后台开发	admin.config.toml / --profile admin	codex-admin-dev	独立 worktree	本地 workspace 范围
SEO 自动化	seo.config.toml / --profile seo	codex-seo-ops	独立目录 / 分支	按任务限制
GitHub PR Review	CI trusted config	codex-ci-review（Secret）	runner checkout	GitHub contents: read + Codex :read-only

注意这里没有为了追求“绝对隔离”给所有东西都复制一整套环境，而是根据风险选择边界：

• 配置差异通过 Profile 显式化。

• 调用归因通过 Key 区分。

• 并行代码任务通过 worktree 隔离。

• CI 使用独立 Secret 和只读权限。

• 最终交付仍以 Git diff、测试和人工 / 受控 Review 为准。

8. 一套够用的日常流程：从启动到合并

1. 先确认当前项目要使用哪个 Profile，不要依赖“上次好像就是这个配置”。

2. 确认对应项目 Key 仍有效、用途和限制没有变化。

3. 如果要并行处理多个任务，为每个任务创建独立 worktree / 分支。

4. 给 Codex 明确任务范围、允许修改路径、禁止碰的共享配置和验收命令。

5. 任务完成后在 worktree 内看 diff、跑测试并提交。

6. 通过 Usage Records 或对应 Provider usage 核对调用是否来自预期 Key / 模型。

7. 回主分支 Review commit，再 merge / cherry-pick。

8. 确认工作树无未提交变化后清理。

9. CI 只在需要时使用独立 Secret 和最小权限执行。

9. 多项目环境最常见的 8 个错误

错误	为什么危险	更稳的做法
所有项目复制同一个 Key	费用、泄露和停用范围都无法归因	按项目 / 风险 / 生命周期拆 Key
Profile 复制完整 config.toml	配置漂移后不知道差异来自哪里	Profile 只保留最小覆盖
把 Key 写进 Profile	配置文件易被同步和分享	环境变量 / Secret / 凭证存储
两个 Codex 同目录并行改	修改相互覆盖，测试结果失效	独立 worktree / 分支
以为 worktree 隔离了所有资源	数据库、端口、云账号仍可能冲突	单独设计共享资源策略
CI 一上来就 contents: write	外部输入直接变成供应链风险	先只读，再按任务升级
Secret 直接写 YAML / prompt	凭证可能进入仓库、日志或输出	只通过 Secret 注入
步骤变绿就算完成	输出范围、测试、安全状态可能仍不合格	最终验收 diff、测试、权限和敏感信息

10. AI Code With 在这套体系里应该负责什么，不应该负责什么

如果你通过 AI Code With 给多个 Codex 项目接不同模型，它更适合放在“模型 API 与调用管理层”。

当前公开文档确认，AI Code With 的 Key 可以按用途创建，并支持消费限额、渠道限制和模型限制；Codex 调用经过 AI Code With 时，也可以结合 Usage Records 按 Key、模型、渠道、Token 和费用做归因。

这能减少多个项目分别维护上游模型账户和账单的重复工作，但有几个边界必须说清楚：

• 它不会替 Codex 做 Git worktree 隔离。

• 不会替 GitHub Actions 判断 fork / PR 是否可信。

• 不会自动管理仓库权限、GitHub Secret 或分支合并。

• 不会因为后台统一，就让不同 Profile 自动拥有不同登录身份。

• 调用记录能缩小问题范围，但不能自动判断代码里是不是循环调用。

产品植入最自然的位置，就是它真的能减少重复管理的地方，而不是把所有工程能力都归到同一个产品名下。

11. 发布到正式项目之前，用这份清单自查

□ 基础 config.toml 只保留真正跨项目共用的配置。

□ 每个 Profile 只覆盖必要差异，并确认当前 Codex 版本支持对应字段。

□ 启动后有明确证据证明 Profile 真正生效。

□ API Key 没有写进仓库、Profile 或 prompt。

□ 长期项目的 Key 名称能看出工具、项目和环境。

□ 并行任务已经使用独立 worktree / 分支。

□ 共享端口、数据库、缓存和测试账号已经单独处理。

□ 每个任务合并前都看过 diff 并跑过项目自己的测试。

□ GitHub Actions 从只读任务和最小 permissions 开始。

□ openai/codex-action 的 permission-profile / safety-strategy 按当前官方文档配置。

□ CI API Key 通过 GitHub Secret 注入，并与个人开发 Key 分开。

□ 最终发布不是只看 Action 变绿，还检查输出范围、测试和敏感信息。

12. 最后：真正成熟的多项目 Codex，不是配置最多，而是每一层都能单独停下来

多项目的工程化管理，本质上不是多学几个命令。

Profile 让配置差异显式；Key 让调用来源可归因；worktree 让并行任务不会在同一块地面上互相踩；GitHub Actions 的最小权限让自动化即使出错，也尽量被限制在可控范围。

当这四层都清楚以后，你才真正具备了一个重要能力：任何异常发生时，都能只关闭受影响的那一层，而不是把整台电脑、整个仓库和全部 Key 一起重配。

基础层稳定，覆盖层最小；凭证可归因，文件有边界；自动化先只读，写权限按任务升级。

如果你正在把 Codex 从“偶尔用一下”升级成真正的多项目工作流，这套思路比继续堆更多全局配置更值得先做。

资料来源与核对说明

本文基于四篇原稿合并重写，并对容易变化的 Profile 与 GitHub Action 行为做了当前公开资料核对。Profile、permission profile、Action 输入字段和第三方平台能力都可能随版本更新，实际配置前应以运行当天的官方文档和当前 CLI help 为准。

OpenAI Codex / ChatGPT plan（含 App worktree 说明）：https://help.openai.com/en/articles/11369540

OpenAI codex-action：https://github.com/openai/codex-action

OpenAI codex-action Security：https://github.com/openai/codex-action/blob/main/docs/security.md

AI Code With - 创建 API Key：https://docs.aicodewith.ai/zh/docs/create-api-key

AI Code With 官网：https://aicodewith.ai/zh

Codex 多项目怎么管理？Profile、API Key、Git worktree 与 GitHub Actions 的完整隔离方案