1. 两个项目互相覆盖问题到底出在哪如果你同时用 Codex 做两个项目很可能遇到过这种场景上午在 A 项目里让 Agent 改了一堆文件下午切到 B 项目继续写结果回头一看A 项目的目录结构被 B 的改动冲掉了或者配置文件被覆盖成另一套。我第一次遇到时以为是编辑器缓存问题重启之后才发现根本不是——Codex 里 AI Agent 的作用域和上下文是严格绑定在你当前打开的 Workspace工作区文件夹上的。换句话说Codex 并不像有些人想的那样“记住所有历史项目”。它认的是你此刻打开的那个文件夹。你打开哪个文件夹Agent 的读写范围、上下文记忆、配置读取就落在哪个文件夹里。如果你始终在同一个大目录下开新项目或者用“打开最近文件”的方式切项目Agent 很容易把上一个项目的上下文带进来写文件时路径一重叠覆盖就发生了。这篇要解决的就是这件事怎么用 Workspace 和 Open Folder按文件夹/仓库把 Codex 的项目隔离开让多项目并行时配置和上下文互不串扰。适合正在用 Codex 做多仓库开发、或者被“项目互相覆盖”坑过一次的人。下面我会给出可复制的目录结构、配置骨架以及切换仓库后的验证步骤最后说明怎么用统一的 Key/API 通道接入避免每个项目重复配密钥。2. 先理解 Codex 的 Workspace 作用域Codex 的 Agent 不是全局的。它启动时会读取当前 Workspace 根目录然后把这个目录当作自己的“工作沙盒”。你让它改文件它默认只在 Workspace 内操作你让它读配置它优先读 Workspace 下的项目级配置。这个设计本身是对的问题出在很多人把多个项目塞进同一个 Workspace或者切换项目时没有真正换 Workspace。我试过把两个仓库放在同一个父目录下然后用“打开文件夹”打开父目录结果 Codex 把两个仓库当成一个项目Agent 在改 A 仓库时上下文里混着 B 仓库的文件索引写路径时一旦相对路径算错就写到隔壁去了。后来我把每个仓库单独作为一个 Workspace 打开覆盖问题再没出现过。所以隔离的核心就一句话一个仓库 一个 Workspace 一次 Open Folder。不要用父目录当 Workspace也不要在同一个 Workspace 里手动切项目。2.1 Workspace 与 Open Folder 的关系Workspace 是 Codex 的工作区概念Open Folder 是你进入某个 Workspace 的动作。你通过“文件 - Open Folder”选择一个文件夹Codex 就把这个文件夹设为当前 Workspace。之后左侧项目栏里出现的是这个 Workspace 下的文件树。你点不同的项目文件夹其实是在同一个 Workspace 内导航并不会切换 Agent 的作用域。这点很关键在左侧项目栏点文件夹不等于换 Workspace。真正换 Workspace 只有两个方式——重新 Open Folder或者在支持多根工作区的编辑器里打开一个新的文件夹作为独立窗口。如果你只是在一个大 Workspace 里点来点去Agent 的上下文始终是那个大 Workspace 的覆盖风险一直在。2.2 为什么配置也会串Codex 会读取项目级配置比如.codex/目录下的设置、AGENTS.md之类的上下文文件。如果你把两个项目放在同一个 WorkspaceCodex 可能只认根目录那一份配置子项目的配置被忽略或者反过来子项目的配置被当成根配置读进来导致另一个项目的行为被改掉。配置串了比文件覆盖更隐蔽因为你不一定马上发现。按仓库隔离之后每个 Workspace 有自己的根配置Codex 读到的就是当前仓库那一套不会跨仓库污染。3. 可复制的目录结构与配置骨架下面这套结构是我现在用的你可以直接抄。核心原则是每个仓库独立目录仓库内放自己的 Codex 配置父目录只用来放仓库不作为 Workspace 打开。~/dev/ ├── repo-a/ │ ├── .codex/ │ │ └── config.toml │ ├── AGENTS.md │ ├── src/ │ └── ... ├── repo-b/ │ ├── .codex/ │ │ └── config.toml │ ├── AGENTS.md │ ├── src/ │ └── ... └── shared/ └── notes.md打开方式Codex 里“文件 - Open Folder”选~/dev/repo-a这就是 Workspace A要切到 B再 Open Folder 选~/dev/repo-b。不要打开~/dev。每个仓库的.codex/config.toml可以放项目级设置。下面是一个最小骨架重点是project_root和context_scope这类字段让 Codex 明确只在本仓库内工作# ~/dev/repo-a/.codex/config.toml [project] name repo-a root . # 限制 Agent 作用域在当前仓库 scope workspace [context] # 只索引本仓库文件避免跨仓库污染 include [src/**, *.md, *.toml] exclude [node_modules/**, dist/**, .git/**] [model] # 统一走 API 通道Key 从环境变量读不写死在仓库里 provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEYAGENTS.md放项目级上下文比如这个仓库的技术栈、目录约定、禁止改动的路径。每个仓库一份内容不同Codex 在当前 Workspace 只会读到当前这份。!-- ~/dev/repo-a/AGENTS.md -- # repo-a 项目约定 - 技术栈TypeScript Node 20 - 源码目录src/ - 禁止改动src/generated/ 下的文件由脚本生成 - 提交前必须跑npm run lint npm testrepo-b 用同样的结构但name、include、AGENTS.md内容换成 B 自己的。这样两个仓库的配置物理隔离Codex 打开哪个就读哪个。3.1 统一 Key/API 通道避免每仓库重复配如果每个仓库都写一份 API Key既容易泄露也容易配错。更好的做法是用环境变量统一管理仓库配置里只引用变量名。TaoToken 提供统一的 API 通道base_url 填https://taotoken.net/apiKey 放在环境变量里# ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEY你的Key这样 repo-a 和 repo-b 的config.toml都写api_key_env TAOTOKEN_API_KEY切换仓库时不用改 Key也不会把 Key 提交进 Git。Key 的获取和管理可以在控制台完成接入文档里有各语言的调用示例需要的话直接看文档对照。4. 切换仓库后的验证步骤配置好之后必须验证切换 Workspace 后上下文和配置确实不串。下面是我每次新建仓库后会跑一遍的检查流程。第一步打开 repo-a让 Codex 读一下当前项目名和配置来源。可以在对话里输入读取当前 Workspace 的 .codex/config.toml告诉我 project.name 和 context.include 的值。预期输出应该是repo-a和[src/**, *.md, *.toml]。如果输出的是 repo-b 的值说明 Workspace 没切干净。第二步在 repo-a 里创建一个只有 A 才有的标记文件比如src/a-marker.txt内容写repo-a-only。然后 Open Folder 切到 repo-b让 Codex 搜索这个文件在当前 Workspace 搜索 a-marker.txt如果找到请输出路径。预期是找不到。如果找到了说明 Codex 的上下文还带着 repo-a 的索引隔离失败。第三步检查配置读取。在 repo-b 里让 Codex 输出当前project.name应该是repo-b。再让它读AGENTS.md的第一行应该是 B 的约定不是 A 的。第四步做一次写操作验证。在 repo-b 里让 Codex 新建src/b-marker.txt然后切回 repo-a确认 repo-a 目录下没有多出b-marker.txt。这一步能直接验证“写文件不会跨仓库”。# 切回 repo-a 后手动确认 ls ~/dev/repo-a/src/ | grep b-marker # 预期无输出 ls ~/dev/repo-b/src/ | grep b-marker # 预期输出 b-marker.txt这四步跑完基本能确认按仓库隔离生效了。如果某一步不符合预期看下一节的排查。4.1 用 API 请求验证通道是否正常配置里的 base_url 和 Key 是否可用可以用一条 curl 验证。注意这里只是验证通道连通性实际调用参数以接入文档为准curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ | head -c 300如果返回模型列表或正常 JSON说明 Key 和通道没问题。如果返回 401检查环境变量是否在当前终端生效如果返回连接错误检查 base_url 是否写成了https://taotoken.net/api不要多加路径。5. 本篇常见错排查错误一打开父目录当 Workspace。表现是两个仓库的文件同时出现在左侧项目栏Agent 改 A 时影响到 B。解决关掉当前 Workspace重新 Open Folder 选具体仓库目录不要选父目录。错误二在左侧项目栏点文件夹就当切换项目。表现是以为切了项目其实 Agent 上下文没变。解决记住只有 Open Folder 或新开窗口才是换 Workspace点文件夹只是导航。错误三配置文件放错位置。表现是 Codex 读不到项目配置或者读到别的项目的。解决.codex/config.toml和AGENTS.md都放在仓库根目录也就是你 Open Folder 选的那个目录下。错误四Key 写死在仓库里。表现是切换仓库后 Key 不对或者 Key 被提交进 Git。解决统一用环境变量TAOTOKEN_API_KEY仓库配置只写变量名。Key 在控制台管理接入方式看文档。错误五切换后没验证就开工。表现是写了一半才发现上下文串了。解决每次新建或切换仓库先跑一遍第 4 节的四步验证确认隔离生效再让 Agent 动手。错误六多个 Codex 窗口共用同一个 Workspace。表现是两个窗口同时写同一个仓库互相覆盖。解决一个仓库同时只开一个 Workspace 窗口要并行就开不同仓库的窗口。6. 接入与后续操作入口按仓库隔离配好之后接下来就是把 Key 和通道接上让每个仓库都能稳定调用。建议的顺序是先在控制台创建或确认 Key然后按接入文档把 base_url 和调用方式对一遍再回到仓库配置里用环境变量引用。这样切换仓库时配置和上下文都是隔离的只有 Key 通道是统一的既安全又省事。如果你还在选模型或调对话参数可以先用模型对话页面试一轮确认返回符合预期再写进项目配置。长期做编码和 Agent 任务的话Coding Plan 更适合按项目持续跑配合上面的 Workspace 隔离多仓库并行会稳很多。需要新建或轮换 Key 时直接进 API Keys 页面操作接入细节对照文档即可。