AI Agent 配置文件路径参考

主流 AI Agent 的规则文件、提示词文件和配置文件速查，覆盖 Codex、Claude Code、OpenCode、Copilot 的文件名、层级、作用域和常见路径。

#type / howto #status / evergreen #tech / ai #platform / windows #platform / linux

[!info] related notes

相关 MOC: AI MOC

相关笔记: mcp-client-configuration, OpenAI Codex, Claude Code, opencode, github-copilot

AI Agent 配置文件路径参考

简介

这份参考不再只看“配置文件在哪”，而是统一整理四类信息：

规则 / instruction 文件叫什么
有没有单独 prompt 文件体系
是否支持项目级、全局级、局部覆盖
配置文件的名称、层级和常见路径

下面内容按 2026-04-20 可见官方文档 整理。

一张表先看

工具	主要规则 / 提示词文件	全局级	项目级	局部 / 嵌套	主配置文件
Codex	`AGENTS.md` / `AGENTS.override.md`	支持	支持	支持，按目录层级加载	`~/.codex/config.toml` / `.codex/config.toml`
Claude Code	`CLAUDE.md` / `CLAUDE.local.md` / `.claude/rules/.md` / `.claude/commands/.md`	支持	支持	支持，按目录树拼接、规则目录递归发现、slash command 目录加载	`~/.claude/settings.json` / `.claude/settings.json` / `.claude/settings.local.json`
OpenCode	`AGENTS.md`，可兼容 `CLAUDE.md`；agent markdown 在 `.opencode/agents/`；command prompt 在 `.opencode/commands/`	支持	支持	支持，向上遍历；也可通过 `instructions` 引用外部文件	`~/.config/opencode/opencode.json` / `opencode.json`
Copilot (VS Code)	`.github/copilot-instructions.md`、`*.instructions.md`、`AGENTS.md`、`CLAUDE.md`	支持	支持	支持，路径匹配或实验性嵌套	`.vscode/mcp.json` / VS Code 用户 `mcp.json`
Copilot CLI	`.github/copilot-instructions.md`、`.instructions.md`、`AGENTS.md`	支持	支持	支持，cwd / env 指定目录	`~/.copilot/config.json` / `~/.copilot/mcp-config.json`

1. Codex

规则文件 / 指令文件

Codex 官方主推的是 AGENTS.md 体系，而不是单独的 prompt 文件目录。

全局级

~/.codex/AGENTS.md
- 作为所有仓库共享的默认工作约定
~/.codex/AGENTS.override.md
- 用于临时全局覆盖，不想改基础 AGENTS.md 时可用

项目级

仓库里的 AGENTS.md
更细目录里的 AGENTS.md
更细目录里的 AGENTS.override.md

加载规则

从项目根目录一路走到当前工作目录
每个目录最多取 1 个文件
单目录内检查顺序：
- AGENTS.override.md
- AGENTS.md
- project_doc_fallback_filenames 中声明的备用文件名
默认会继承全局 ~/.codex/AGENTS.md
当前目录越近，优先级越高

备用文件名

Codex 支持在 config.toml 里指定备用指令文件名，例如：

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

这意味着如果仓库历史上不用 AGENTS.md，也可以把其他 Markdown 文件纳入 instruction discovery。

Prompt 文件

按当前 Codex 官方公开文档，主路径是：

AGENTS.md
config.toml
skills

也就是说，Codex 当前并没有像 VS Code Copilot 那样单独强调一套 .prompt.md prompt file 体系。这里是基于官方文档结构做的判断。

配置文件

主要文件

用户级：~/.codex/config.toml
项目级：.codex/config.toml
系统级（Unix）：/etc/codex/config.toml

优先级

Codex 配置优先级从高到低是：

CLI flags 和 --config
--profile 指定的 profile
项目级 .codex/config.toml（从项目根到 cwd，离当前目录最近者优先）
用户级 ~/.codex/config.toml
系统级 /etc/codex/config.toml
内置默认值

注意

项目级配置只会在 trusted project 下加载
CLI 和 IDE extension 共享同一套配置层

2. Claude Code

规则文件 / 记忆文件

Claude Code 的规则和记忆文件主线是 CLAUDE.md，而不是 AGENTS.md。

支持的层级

Managed policy
- macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
- Linux / WSL: /etc/claude-code/CLAUDE.md
- Windows: C:\Program Files\ClaudeCode\CLAUDE.md
项目级
- ./CLAUDE.md
- ./.claude/CLAUDE.md
项目级模块化规则
- ./.claude/rules/**/*.md
用户级
- ~/.claude/CLAUDE.md
用户级模块化规则
- ~/.claude/rules/**/*.md
本地个人项目覆盖
- ./CLAUDE.local.md

加载规则

Claude Code 会从当前工作目录向上走目录树
发现的 CLAUDE.md 和 CLAUDE.local.md 会拼接，不是简单覆盖
同一目录下，CLAUDE.local.md 会追加在 CLAUDE.md 后面
子目录里的 CLAUDE.md / CLAUDE.local.md 默认按需加载，而不是启动时一次性全读
.claude/rules/ 下的 Markdown 规则文件会递归发现
用户级 ~/.claude/rules/ 先加载，项目级 .claude/rules/ 后加载，因此项目规则优先级更高

和 `AGENTS.md` 的关系

Claude Code 不直接读取 AGENTS.md。如果仓库已经有 AGENTS.md，推荐在 CLAUDE.md 里导入：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

配置文件

Settings

用户级：~/.claude/settings.json
项目级共享：.claude/settings.json
项目级本地覆盖：.claude/settings.local.json

MCP

用户级 MCP：~/.claude.json
项目级 MCP：.mcp.json

其他相关目录

用户级 subagents：~/.claude/agents/
项目级 subagents：.claude/agents/
用户级 slash commands：~/.claude/commands/
项目级 slash commands：.claude/commands/

优先级

Claude Code 设置优先级从高到低：

Managed
CLI arguments
Local
Project
User

Prompt / slash command 文件

Claude Code 还支持把 prompt 固化成 slash commands：

用户级：~/.claude/commands/*.md
项目级：.claude/commands/*.md

这类 Markdown 文件会变成 /命令名，适合沉淀 review、fix、handoff 一类高频 prompt。

3. OpenCode

规则文件

OpenCode 的原生规则文件是 AGENTS.md。

项目级

当前项目或父目录中的 AGENTS.md

全局级

~/.config/opencode/AGENTS.md

Claude 兼容回退

如果没有对应的 AGENTS.md，OpenCode 还能回退读取：

项目级：CLAUDE.md
全局级：~/.claude/CLAUDE.md

也可以通过环境变量关闭 Claude Code 兼容层。

加载规则

启动时向上遍历当前目录
查找顺序：
1. 本地向上查找 AGENTS.md / CLAUDE.md
2. 全局 ~/.config/opencode/AGENTS.md
3. ~/.claude/CLAUDE.md
每一类只取第一个命中的文件
如果同目录里 AGENTS.md 和 CLAUDE.md 同时存在，优先 AGENTS.md

外部 instruction files

OpenCode 还支持在 opencode.json 中用 instructions 字段引用额外规则文件：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

特点：

可写在项目级 opencode.json
也可写在全局 ~/.config/opencode/opencode.json
会和 AGENTS.md 一起组合使用
支持远程 URL

Prompt / agent 文件

OpenCode 当前更像通过自定义 agent 来承载可复用 prompt：

全局：~/.config/opencode/agents/*.md
项目级：.opencode/agents/*.md

此外也可以在 opencode.json 中给 agent 配 prompt 字段，并引用外部 prompt 文件。

另外还有一条更像“prompt file”的自定义 command 路径：

全局：~/.config/opencode/commands/*.md
项目级：.opencode/commands/*.md

这类 Markdown 文件会变成 /命令名，本质上是可复用的命令型 prompt 模板。

配置文件

主配置

全局：~/.config/opencode/opencode.json
项目级：opencode.json

TUI 配置

全局：~/.config/opencode/tui.json
项目级：tui.json

其他配置入口

OPENCODE_CONFIG
- 指向自定义配置文件
OPENCODE_TUI_CONFIG
- 指向自定义 TUI 配置文件
OPENCODE_CONFIG_DIR
- 指向自定义配置目录

加载规则

OpenCode 配置是 merge，不是整份替换
项目级配置会覆盖冲突键，但不会抹掉全局里不冲突的键
项目配置会从当前目录向上找，直到最近的 Git 根

4. GitHub Copilot

Copilot 需要区分：

VS Code / GitHub / JetBrains 里的 Copilot
Copilot CLI

它们的 instruction / prompt / config 路径并不完全相同。

4.1 VS Code 中的 custom instructions

Always-on instructions

仓库级：
- .github/copilot-instructions.md
路径级：
- .github/instructions/**/*.instructions.md
- 文件名必须以 .instructions.md 结尾
- 通过 frontmatter 里的 applyTo 指定适用路径
AGENTS.md
- VS Code 支持作为 always-on instructions
- 嵌套 AGENTS.md 目前是实验性能力
CLAUDE.md
- 兼容 Claude 生态
- VS Code 会识别 workspace root、.claude 或用户 home 下的 CLAUDE.md

用户级 instructions

VS Code 还会递归查找：

~/.copilot/instructions
~/.claude/rules
VS Code 用户 profile 对应的 user data 目录

Prompt files

VS Code Copilot 的 prompt files 是独立体系：

工作区：.github/prompts/*.prompt.md
用户级：VS Code profile 的 user data

规则：

文件后缀必须是 .prompt.md
可带 YAML frontmatter
monorepo 下可通过设置启用父仓库发现

4.2 Copilot on GitHub / GitHub agents

GitHub 官方文档目前强调三类仓库级 custom instructions：

.github/copilot-instructions.md
.github/instructions/**/*.instructions.md
AGENTS.md

其中：

.github/copilot-instructions.md 负责 repository-wide
.instructions.md 负责 path-specific
AGENTS.md 负责 agent instructions
对 AGENTS.md，GitHub 文档当前写法是“仓库内可有多个，最近的优先”

4.3 Copilot CLI

Copilot CLI 支持的 instruction files 更像 GitHub / VS Code 规则的本地延伸：

仓库级：
- .github/copilot-instructions.md
- .github/instructions/**/*.instructions.md
- AGENTS.md
可选兼容：
- CLAUDE.md
- GEMINI.md
本地全局：
- $HOME/.copilot/copilot-instructions.md
自定义目录：
- COPILOT_CUSTOM_INSTRUCTIONS_DIRS

CLI 会在这些目录中查找：

AGENTS.md
.github/instructions/**/*.instructions.md

4.4 配置文件

VS Code MCP

全局：VS Code 用户 mcp.json
- Windows 常见位置：%APPDATA%\Code\User\mcp.json
- Linux / WSL 常见位置：~/.config/Code/User/mcp.json
项目级：.vscode/mcp.json

Copilot CLI

通用配置：
- Linux / WSL：~/.copilot/config.json
- Windows：%USERPROFILE%\.copilot\config.json
MCP 配置：
- Linux / WSL：~/.copilot/mcp-config.json
- Windows：%USERPROFILE%\.copilot\mcp-config.json

注意事项

规则文件和配置文件不要混写

规则文件解决“模型应当如何做事”
配置文件解决“客户端如何运行、连什么服务、开什么能力”

最容易混淆的几个点

Codex 主打 AGENTS.md，不是 Copilot 那种 .prompt.md
Claude Code 主打 CLAUDE.md，不是直接读 AGENTS.md
OpenCode 同时支持自己的 AGENTS.md 和 Claude 兼容回退
Copilot 既有 instruction files，也有 prompt files，两套体系要分开看

路径映射与跨平台切换

Windows 用反斜杠路径，Linux / WSL 用正斜杠路径
WSL 文档路径和 Windows 文档路径不要混写
某些工具在 WSL 下会复用 Linux 约定路径，而不是 Windows 用户目录

AI Agent 配置文件路径参考

简介

一张表先看

1. Codex

规则文件 / 指令文件

全局级

项目级

加载规则

备用文件名

Prompt 文件

配置文件

主要文件

优先级

注意

2. Claude Code

规则文件 / 记忆文件

支持的层级

加载规则

和 AGENTS.md 的关系

配置文件

Settings

MCP

其他相关目录

优先级

Prompt / slash command 文件

3. OpenCode

规则文件

项目级

全局级

Claude 兼容回退

加载规则

外部 instruction files

Prompt / agent 文件

配置文件

主配置

TUI 配置

其他配置入口

加载规则

4. GitHub Copilot

4.1 VS Code 中的 custom instructions

Always-on instructions

用户级 instructions

Prompt files

4.2 Copilot on GitHub / GitHub agents

4.3 Copilot CLI

4.4 配置文件

VS Code MCP

Copilot CLI

注意事项

规则文件和配置文件不要混写

最容易混淆的几个点

路径映射与跨平台切换

相关链接

Related notes

和 `AGENTS.md` 的关系