四大AI编程Agent配置与日志存放路径全对比

你的Agent刚刚忽略了一条你明明写过的规则。在重写prompt之前，先回答两个问题：它实际读了哪个文件？它又把自己的行为写到了哪里？

答案比表面看起来更复杂，因为这些Agent会互相读取彼此的文件。如果你有 ~/.claude/CLAUDE.md 却没有 ~/.config/opencode/AGENTS.md，OpenCode会把你的Claude文件当作全局规则加载。GitHub Copilot CLI会合并读取仓库中的 AGENTS.md、CLAUDE.md 和 GEMINI.md，而它的文档并未定义这三者之间的优先级。Claude Code从v2.1.277起也会读取 AGENTS.md，但默认仅在路径上没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时才这样做。

以下是四款工具在配置、记忆与日志存放上的完整对比，所有路径均来自各厂商的官方文档或仓库。

指令文件的加载规则

指令文件的优先级是最容易踩坑的地方。下表汇总了三种常见指令文件在四款工具中的实际行为：

指令文件	Claude Code	Codex	Copilot CLI	OpenCode
仓库中 AGENTS.md	仅当路径上无 CLAUDE.md 或 CLAUDE.local.md	读取	合并读取	读取，且优先于 CLAUDE.md
仓库中 CLAUDE.md	读取	仅作为可配置的回退名	合并读取	仅当无 AGENTS.md 时
~/.claude/CLAUDE.md	读取	未列出	未列出	当无全局OpenCode AGENTS.md 时

Copilot CLI是唯一明确定义"无优先级"的工具——它把找到的所有指令文件合并，只去掉完全重复的内容。GitHub的唯一建议是：避免写出相互冲突的指令。这意味着在Copilot CLI中维护多份指令文件时，你需要自己确保内容一致。

为什么 Agent 的规则文件会互相串读？

多家厂商之所以出现交叉读取，源于一个早期的行业默契：AGENTS.md 曾被当作跨工具的通用指令文件名推广。OpenCode、Codex、Copilot CLI 都采纳了这一约定，随后各家又在此基础上叠加了各自的历史文件名（CLAUDE.md、GEMINI.md）。结果是同一份规则可能被多个工具解析，而每个工具的优先级判定逻辑由各自的实现者独立决定。

当多个文件同时存在时，最终进入模型 context 的往往是“拼接结果”而非“胜出结果”。这意味着排查 Agent 行为异常时，不能只检查你最近修改的那个文件，而应确认启动时实际加载了哪些文件、以什么顺序拼接。这也是 InstructionsLoaded 钩子、/debug-config 这类诊断命令存在的意义。

Claude Code

Claude Code的设置分为五层，从高到低依次为：托管设置、claude --settings、.claude/settings.local.json、.claude/settings.json，最后是 ~/.claude/settings.json。另有一个独立文件 ~/.claude.json，存放登录信息、项目信任决策和个人MCP服务器。

MCP服务器有三种作用域：用户级和本地级存放在 ~/.claude.json，项目级存放在仓库根目录的 .mcp.json。

指令从 ~/.claude/CLAUDE.md 以及工作目录及其所有上级目录中的 CLAUDE.md 或 .claude/CLAUDE.md 加载，外加一个被git忽略的 CLAUDE.local.md。项目文件是拼接而非覆盖的，离启动位置最近的文件最后读取。一个容易忽略的陷阱：在一个仅有 AGENTS.md 的仓库中新增 CLAUDE.local.md，会静默地让Claude停止读取 AGENTS.md。

自动记忆存放在 ~/.claude/projects/<project>/memory/ 下，带有 MEMORY.md 索引，启动时只加载前200行或25KB。

会话记录是每个会话一个JSONL文件，位于 ~/.claude/projects/<project>/<session>.jsonl。文件夹名是你的工作目录路径，所有非字母数字字符都被替换为连字符。默认情况下，这些文件在30天后被清理。

在会话中，/context 列出启动时加载的记忆文件，/memory 打开它们。如需查看哪些指令文件被加载及原因，可以使用 InstructionsLoaded 钩子。

安全提醒：官方文档明确指出会话记录是明文且未加密的。如果某个工具读取了 .env 文件，其中的值现在就在JSONL文件里。粘贴会话记录到bug报告前务必三思。

MCP 与 settings 的边界

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，用于让模型以标准化方式调用外部工具与数据源；对 Agent 而言，一个 MCP server 就是一组它可以在会话中动态调用的能力。

之所以要在 Claude Code 里把 MCP 配置分三处存放，是因为三者的作用范围不同：用户级作用于你所有项目，项目级随仓库提交、对团队共享，本地级则只属于你自己的机器且通常被 git 忽略。理解这个分层是排查“为什么这个工具在我机器上可用、在 CI 里却报错”的关键——多半是用户级还是项目级的作用域没对上。

Codex

Codex将状态存放在 CODEX_HOME 下，默认为 ~/.codex。配置优先级从高到低为：CLI标志和 --config 覆盖、项目级 .codex/config.toml、--profile 文件、~/.codex/config.toml、云端托管默认值，最后是 /etc/codex/config.toml。项目级 .codex/ 仅在信任该项目时加载。

指令来自 ~/.codex/AGENTS.override.md，若不存在则读取 ~/.codex/AGENTS.md。然后Codex从项目根目录向下走到工作目录，每个目录最多取一个文件。当总量达到 project_doc_max_bytes（默认32KB）时停止添加。超出上限的内容永远不会到达模型。

MCP服务器是同一 config.toml 中的 [mcp_servers.<name>] 表。本地记忆默认关闭，开启后存放在 ~/.codex/memories/。会话记录是JSONL rollout文件，位于 $CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl——需要注意，这个布局来自2025年的一个功能请求（openai/codex issue #2288），属于观察到的行为而非文档化契约。

两个内置命令比任何 cat 都更有用：/debug-config 打印配置层顺序和策略来源；codex debug prompt-input 渲染模型看到的精确prompt输入，直接回答"它读了我的AGENTS.md吗"。

GitHub Copilot CLI

用户级配置全部位于 ~/.copilot。settings.json 是主配置，config.json 是内部状态，不要手动编辑。仓库设置放在 .github/copilot/settings.json，个人覆盖放在 .github/copilot/settings.local.json。设置 COPILOT_HOME 环境变量可以移动整个文件夹。

指令文件来源广泛：.github/copilot-instructions.md、按路径匹配的 .github/instructions/**/*.instructions.md、AGENTS.md、CLAUDE.md 或 .claude/CLAUDE.md、GEMINI.md，以及你自己的 ~/.copilot/copilot-instructions.md。Copilot将它们全部合并，去掉完全相同的重复项。

用户级MCP服务器在 ~/.copilot/mcp-config.json 的 mcpServers 键下。项目级服务器在 .mcp.json 或 .github/mcp.json 中，且优先于用户级。每个会话在 ~/.copilot/session-state/ 下有一个文件夹，包含 events.jsonl 事件日志以及计划和检查点。

OpenCode

OpenCode的配置是合并的，后者胜出：远程组织默认值、~/.config/opencode/opencode.json、OPENCODE_CONFIG 指定的文件、项目根目录的 opencode.json、.opencode 目录和 OPENCODE_CONFIG_CONTENT。管理员托管配置覆盖一切。配置文件可以是带注释的JSONC。

规则加载从向上查找 AGENTS.md 开始，以 CLAUDE.md 作为回退，然后是 ~/.config/opencode/AGENTS.md，最后是 ~/.claude/CLAUDE.md。每类中第一个匹配的胜出。设置 OPENCODE_DISABLE_CLAUDE_CODE=1 可以关闭所有 .claude 支持。

数据存放在 ~/.local/share/opencode/：auth.json 中包含API密钥和OAuth令牌，log/ 文件夹保留最近10个文件。从v1.2.0起，会话不再是扁平文件——该版本将它们迁移到一个SQLite数据库 opencode.db。读取会话应使用CLI而非直接查数据库模式。opencode export <id> --sanitize 会脱敏敏感内容，但文档并未承诺脱敏能覆盖一切，附到issue前仍应自行检查。

从扁平文件到 SQLite 的迁移影响

早期 OpenCode 的会话是磁盘上的独立文件，可以直接 grep；v1.2.0 之后统一收进 opencode.db，这带来两个现实后果：一是无法再用 grep -r 跨会话检索，必须经过 opencode export <id> 走 CLI 通道；二是数据库 schema 属于内部实现，官方并未承诺稳定，直接连库查询可能在版本升级后失效。

此外，OpenCode 遵循 XDG 目录规范（~/.config 放配置、~/.local/share 放数据），这与 Claude Code、Codex 把一切塞进 ~/.claude、~/.codex 的做法不同。在写脚本备份或清理时，需要意识到两者的路径习惯并不一致。

哪个会话改动了那个文件？

当某个文件被修改而你不知道是哪个会话所为，可以直接grep会话记录。这对四款工具中的三款有效：Claude Code、Codex和Copilot CLI的会话记录都是可直接搜索的JSONL文件。OpenCode因为使用SQLite，需要先用 opencode export 导出再搜索。

这个技巧在并行运行多个Agent时尤为实用。当每个Agent在独立的worktree中运行时，有几个细节需要注意：Claude Code的记录文件夹按工作目录命名，所以worktree中的会话会落在不同的文件夹；但自动记忆是按git仓库来的，同一仓库的所有worktree共享它。git忽略的 CLAUDE.local.md 只存在于创建它的worktree中。此外，codex resume --last 从主检出运行时，不会找到你在worktree中运行的会话，除非加上 --all。

核心要点

四款主流AI编程Agent在配置、记忆和日志的存放上各有体系，但存在大量交叉读取行为：OpenCode会在缺少自身全局配置时回退到Claude的文件；Copilot CLI无优先级地合并所有指令文件；Claude Code只在没有 CLAUDE.md 时才读 AGENTS.md。理解这些路径和优先级规则，是排查Agent"不听话"问题的第一步。另一个值得警惕的点是会话记录的明文存储——它们是没有经过加密的纯文本，可能包含来自 .env 等文件的敏感值。