Codex 的 override 文件让团队少踩坑

把 /AGENTS.override.md 加进 .gitignore，就能把 Codex 的团队覆盖配置管住。

我用 Codex 工作区一段时间了，整体挺顺手，但有个地方一直让我烦：团队里一旦有人临时改了 AGENTS 相关配置，那个“临时”经常就变成了“谁也不知道还在不在”的状态。你以为自己在跑同一套规则，实际上有人本地多了个 override，另一个人没加载到，第三个人还把它顺手提交进去了。结果就是，排查问题的时候大家都在对着同一个仓库说不同的话。

这类问题最恶心的点不在于它难修，而在于它很容易被忽略。配置文件一旦能被版本库追踪，团队就会下意识把它当成正式约定；可有些文件本来就该是本地实验用的，像 /AGENTS.override.md 这种东西，应该更像“我这台机器上的临时补丁”，而不是项目规范的一部分。知乎上这篇关于 Codex 在符号链接工作区里无法加载 AGENTS.md 的修复说明，把这个思路说得很直接：把覆盖文件放进 .gitignore，再用自动升级把后续修复吃进来。这个判断我认同，因为它解决的不是单点 bug，而是团队里最烦人的配置漂移。

别把临时 override 养成“伪标准”

把 /AGENTS.override.md 加进 .gitignore。

这句话看着简单，实际很有分量。它的意思不是“别用 override”，而是“override 可以存在，但别让它进入仓库的正式轨道”。我见过太多团队把临时调试文件、个人实验配置、阶段性 workaround 留在 repo 里，最后每个人都以为那是项目的一部分。等到某天有人清理文件，或者切到别的分支，问题就开始了：为什么这个 agent 读不到规则？为什么本地表现和 CI 不一样？为什么 A 说能复现，B 说不能？

把 /AGENTS.override.md 放进 .gitignore 的价值就在这里。它把“这个文件可以存在”跟“这个文件应该被提交”分开了。前者允许你做本地实验，后者阻止它污染共享状态。说白了，这就是给团队装一个边界。你可以改，但别把改动伪装成正式配置。

我自己最怕的就是那种看起来像文档、实际上是补丁的文件。它们最开始都很无辜，后来就会变成事故现场。今天是为了修一个符号链接工作区的问题，明天就是某个人在别的目录里复制了一份，后天你再看，仓库里已经有三份“看起来差不多”的规则文件了。

怎么落地？很简单。把它当作本地覆盖层来处理，不要让它跟主配置混在一起。然后在 README 或团队约定里明确一句：AGENTS.override.md 只给个人调试、临时实验、局部修补用，不进入正式提交流程。这样做的好处是，团队成员看到这个文件时会下意识知道它不是“标准答案”。

• 把本地覆盖文件加入 .gitignore。
• 在团队规范里说明它只用于临时调试。
• 不要让 CI、发布脚本、正式文档去依赖它。

git status 该替你报警，不该替你装瞎

我很喜欢这个修法里的另一个细节：把新建的 override 文件交给 git status 去暴露，而不是藏起来。很多人对 .gitignore 有误解，以为它的作用就是“让文件消失”。其实更好的用法是：让该消失的东西消失，让该出现的风险出现。这里的逻辑非常朴素，甚至有点土，但土办法往往最管用。

如果一个同事在本地临时加了 /AGENTS.override.md，而这个文件又没有被忽略，那它就很容易被误提交。你今天只是想修个 bug，明天仓库里就多了一个没人注意的本地配置。相反，如果它被 .gitignore 管住了，git status 还能保持干净，真正需要提交的改动也更容易被看见。这个时候，状态输出不是噪音，而是提醒。

我在团队里吃过一次类似的亏。我们当时有个本地调试用的配置文件没忽略，结果一位同事在赶工时顺手提交了。那次提交没炸，但它把一种“本地例外”变成了“仓库默认”。之后每个人都得先理解那份例外，再去判断自己的问题是不是跟它有关。很浪费时间，也很伤协作信任。

怎么应用？我会建议你把这类文件的处理原则写成两条：第一，默认不提交；第二，如果真的需要共享，就显式改成正式配置文件，而不是继续靠 override 混过去。这样团队成员在看到 git status 时，心里会很清楚哪些是临时件，哪些是正式件。

• 让 git status 只暴露真正需要处理的内容。
• 把临时 override 和正式配置分开命名。
• 如果要共享，迁移到明确的主配置文件里。

符号链接工作区的问题，本质上是“发现机制”出了偏差

Codex AGENTS.md 在符号链接工作区无法加载的问题已在 v0.138 版本中修复。

这条信息很关键，因为它说明问题不只是“某个文件读不到”，而是“在特定工作区结构下，发现机制失效了”。符号链接工作区本来就容易把路径、根目录、相对引用这些东西搞复杂。工具如果只按最朴素的文件系统假设去找，就很容易在链接层上翻车。你看着文件明明在那儿，它就是不认；你换个路径，又突然好了。最烦的就是这种“看起来没问题，但就是不工作”的毛病。

我理解这类修复的重点，不是让你手工绕开，而是让工具学会在真实工作区里找对位置。对开发者来说，这意味着你以后不用为了符号链接工作区专门写一堆脆弱的 workaround。更重要的是，它把“文件存在”跟“文件被正确发现”这两个概念分开了。很多工具栽就栽在这里：它们以为自己在读配置，其实只是在读一个理想化的目录结构。

我自己在 monorepo、pnpm workspace、link 目录混用的时候，最讨厌的就是这种路径感知问题。你只要把仓库换成一个符号链接入口，很多工具就开始表现得像第一次见到这个项目。表面上是 bug，底层其实是路径解析太天真。v0.138 修掉这个点，至少说明 Codex 的工作区发现逻辑开始更贴近真实开发环境了。

怎么用这个信息指导你自己的项目？如果你也在做 agent、CLI 或代码工具，别假设用户总是在“标准仓库根目录”里跑你。真实世界里，别人会从符号链接、挂载目录、容器卷、子目录入口启动。你要么支持这些入口，要么就老老实实把限制写清楚。含糊其辞最坑人。

如果你是使用者，那就顺手做一个验证：在符号链接工作区里确认 Codex 能不能找到 AGENTS 文件，确认 override 是否按预期生效。别等到团队跑偏了才发现问题。

自动升级比人工盯版本靠谱得多

这篇内容里我最认同的一点，是把修复和升级策略绑在一起看，而不是只看 bug 本身。单独修一次版本问题，当然能救急；但如果团队还停在旧版本上，那修复就只是“某个人已经知道了”，不是“整个团队已经拿到了”。这就是为什么我一直更喜欢把工具升级交给 Renovate 或 Dependabot，而不是靠人肉提醒。

这里的逻辑很现实：Codex 这类工具的行为修复，往往不是一次性的。今天是符号链接工作区，明天可能是别的路径发现问题，后天可能又是配置优先级调整。你不可能指望每个开发者都盯着发布说明，也不该这么要求。自动升级至少能保证一个基本事实：新修复会更快进入团队的日常环境。

我见过很多团队嘴上说“我们会定期升级”，实际上就是等到有人碰到 bug 才想起来看版本。这个模式很脆。你要是今天不自动化，明天就会在 Slack 里反复问“谁能顺手升一下”。然后一拖再拖，最后变成“先别升，等这个分支合完”。结果就是，已知修复被你们自己拖成了未知风险。

怎么做？如果你用 GitHub，可以看 Dependabot；如果你们已经在用 Renovate，就直接给 @openai/codex 配规则。升级策略不需要花哨，核心是两点：尽快拿到修复，尽量减少人工判断成本。你甚至可以把它设成小步快跑，而不是大版本一次性跳跃。这样出问题时回滚也更简单。

• 用 Renovate 或 Dependabot 自动提升级别。
• 把 Codex 相关依赖纳入常规更新队列。
• 优先接收修复型版本，别等到堆出一坨技术债。

把“本地补丁”从“团队约定”里剥离出来

这其实是整件事最值得学的一点。AGENTS.override.md 这个命名本身就透露出意图：它不是主配置，它是覆盖层。覆盖层存在的意义，是让你在不改主配置的前提下做局部调整。可一旦你把它提交进仓库，它就不再只是覆盖层，而会变成一种隐式约定。隐式约定最可怕，因为它没有明确边界，也没有明确负责人。

我更愿意把这类文件看成“个人工作台上的便签”，而不是“项目说明书的一部分”。个人便签可以很多，甚至可以很乱，但它们不该污染团队共识。团队共识应该尽可能少而清晰：哪些文件是正式的，哪些只是本地的，哪些能自动升级，哪些必须人工审查。边界越清楚，工具越不容易把人带沟里。

落地的时候，我会建议你顺手把几件事一起做：

• 明确主配置文件和 override 文件的职责分工。
• 给本地覆盖文件加 .gitignore。
• 把工具版本升级纳入自动化流程。
• 在团队文档里写明：符号链接工作区也要验证。

这样一来，问题就不会被拆成零碎的“谁的机器坏了”“谁忘了提交”“谁没升级版本”，而是会回到一个更健康的状态：规则清楚，路径明确，升级自动化，临时补丁不乱飞。说到底，开发体验里最值钱的不是少敲几行字，而是少猜几次系统到底在干嘛。

你可以直接复制的团队约定

# Codex team setup: keep local overrides out of git, and auto-upgrade Codex

## Files
# Local-only override file for experiments and machine-specific fixes
/AGENTS.override.md

## .gitignore
# Keep local Codex overrides out of version control
/AGENTS.override.md

## Team rule
# - AGENTS.md is the shared source of truth
# - AGENTS.override.md is local-only and must not be committed
# - If an override needs to be shared, promote it into the main AGENTS.md

## Verification checklist
# 1. Open the workspace through a symlinked path
# 2. Confirm Codex loads AGENTS.md correctly
# 3. Create /AGENTS.override.md locally
# 4. Confirm git status stays clean for the override file
# 5. Confirm the override is picked up only on the local machine

## Renovate example
{
  "packageRules": [
    {
      "matchPackageNames": ["@openai/codex"],
      "automerge": false,
      "enabled": true
    }
  ]
}

## Dependabot example
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    allow:
      - dependency-name: "@openai/codex"

## PR note
# When Codex is updated, re-check:
# - symlink workspace loading
# - AGENTS discovery
# - override precedence

我会把这份模板当成起点，而不是终点。你可以按自己的仓库结构改路径，按自己的包管理器改升级规则，但原则别变：本地 override 不进仓库，工具修复靠自动升级，符号链接工作区要单独验证。

原始问题和修复点来自这篇知乎文章：Codex AGENTS.md 在符号链接工作区无法加载的问题已在 v0.138 版本中修复。我上面这套整理是基于它的实战化改写，不是原文逐字复述；真正的价值在于把修复变成团队能直接执行的约定。