这两年我本机常驻了好几个编码智能体Claude Code、Codex CLI、Cursor最近又加了一个轻量的 Hermes Agent。项目切换多了以后我发现自己陷进了一件特别没意思的事情——每换一个工具就得把同一套 MCP 工具和技能从头写一遍。明明连的是同一个数据库、同一套本地脚本、同一条发布流程配置却要复制到四个不同角落。这个“0 配置同步方案”就是把我从这种重复劳动里捞出来的东西。它适合谁适合那些同时使用多个 agent、又不想维护多份配置的开发者。哪怕你只用其中两个把思路跑通也能省下大量折腾时间。我照着这套方法跑了两个月新增一个工具现在只需要改一个文件剩下全是脚本的事。1. 先搞清楚为什么每个 Agent 都要“单独配一遍”1.1 MCP、技能、规则是三件不同的事很多人把 MCP、技能、规则混在一起说但它们其实是三个层次。MCP 是 Model Context Protocol负责把外部能力“插”给 agent。数据库、浏览器、文件系统、第三方 API都可以通过 MCP server 暴露。你的 agent 说的“我会用文件工具”本质是连接了一个 filesystem MCP server。技能是更高一层的东西。Claude 系里常见的 SKILL.md就是给 agent 一份操作手册让它遇到某种场景时按特定流程执行。比如“PDF 转结构化文本”“发布版本前跑全套检查”这些是多步骤的工作流不是一个单独的工具调用。规则和记忆则是约束层。CLAUDE.md、AGENTS.md、.cursor/rules这些东西用来固定 agent 的行为风格、编码规范、禁止事项。这三者在配置层面的诉求是一样的都需要在某个文件里声明。于是问题就变成了你家一共装了四个 agent每个都有自己的声明位置和语法。1.2 各大工具的配置文件到底长什么样我先列一张自己在实际使用中整理的对照表不保证覆盖所有历史版本但当前主流的用法基本都在。AgentMCP 配置位置配置格式技能/规则位置Claude Code全局~/.claude.json项目级.mcp.jsonJSON字段是mcpServers技能在~/.claude/skills/名字/SKILL.md规则是CLAUDE.mdCodex CLI~/.codex/config.tomlTOML字段是mcp_servers规则是AGENTS.mdCursor项目.cursor/mcp.json全局~/.cursor/mcp.jsonJSON字段是mcpServers规则在.cursor/rules/*.mdcHermes Agent~/.hermes/config.jsonJSON字段是mcpServers技能目录~/.hermes/skills看到这个表你应该就有感觉了MCP 的配置其实大同小异但格式有 JSON 和 TOML字段有mcpServers和mcp_servers作用域有全局和项目之分。技能和规则更是各有各的目录约定。1.3 为什么不能直接复制一份文件通吃最早我想偷懒想把 Claude Code 的mcpServers配置原样复制给 Cursor。结果立刻碰到四个问题。格式不通。Codex 读的是 TOMLCursor 和 Claude Code 读的是 JSON让 JSON 直接给 TOML 用解析都会崩。键名不同。Claude Code 叫mcpServersCodex 里叫mcp_servers差一个下划线程序就不认识。作用域不同。Claude Code 的.mcp.json是项目级的如果放到全局完全不生效Cursor 的全局配置和项目配置又是两套逻辑混用会让你排查半天。解析行为不同。Claude Code 里env字段可以直接给 server 注入环境变量Codex 的 TOML 里如果你要多环境变量语法又不一样。命令数组的处理也有坑有的地方需要args是字符串数组有的则需要你写成一条 shell 命令。这个差异决定了硬方案不行。你不能靠“复制同一份文件”来实现统一只能做一个“翻译层”一份中央配置派生出四个 agent 各自能认的格式。2. 0 配置的核心思路中央注册表 自动生成 软链同步2.1 方案设计目标我想做的不是“零配置文件”因为那不可能agent 本身就要求路径上存在一个文件。我理解的 0 配置是你不需要再一个工具一个工具地手工写配置改配置的动作收敛到一个地方。设计目标有三个。单一事实来源。所有 agent 的能力声明也就是 MCP server、技能、规则只存在一份中央配置里。生成物可丢弃。每个 agent 自己的配置都只是脚本产物可以被重新生成。你手改生成物没意义因为下一次同步会覆盖掉。全局与项目级兼顾。MCP 通常是本机级别的所有 agent 都能用技能和规则往往需要进入具体项目所以要靠软链把中央目录接到项目里。2.2 目录结构把所有配置收敛到一个地方我最终在~/.agents下搭了这样一个结构。~/.agents/ ├── mcp/ │ └── registry.json # 统一 MCP server 注册表 ├── skills/ │ ├── pdf-toolkit/ │ │ └── SKILL.md │ └── release-helper/ │ └── SKILL.md ├── rules/ │ ├── coding-style.md # 通用编码规范 │ └── cursor/ │ └── project-rules.mdc # Cursor 专用规则 └── sync/ └── sync_agents.py # 同步脚本registry.json是唯一需要手工维护的文件。技能目录里每个子目录就是一个技能一个 SKILL.md 加配套脚本。规则目录则根据各个 agent 的约定拆成子目录方便软链到不同位置。2.3 为什么选“生成式同步”而不是“共享同一文件”有人会问既然技能可以软链为什么 MCP 配置不用软链比如把~/.claude.json直接软链到~/.cursor/mcp.json这个想法听起来很美但实际跑不通。一方面Claude Code 的~/.claude.json不只是 MCP 配置它还存了历史会话、项目白名单、各种状态。把这个文件共享给 Cursor等于让 Cursor 去解析一个它不认识的复杂 JSON 文件问题会比解决的还多。另一方面Codex 读的是 TOML你没法把一个 JSON 文件通过软链变成 TOML 语法。就算强行链接解析器直接报错。所以正确姿势是中央注册表保持中性格式比如 JSON然后写一个生成器脚本按当前 registry 输出每个 agent 能识别的具体配置。这就是“0 配置”的真正含义你不需要每次手工写但底层配置文件是存在的只是由脚本自动出现。3. 动手实现把你本机所有 Agent 的 MCP 和技能串起来3.1 第一步建立统一 MCP 注册表先建好~/.agents/mcp/registry.json。我用一个很简单的例子说明。{ mcpServers: { time: { type: stdio, command: npx, args: [-y, mcp-server-time] }, sqlite: { type: stdio, command: npx, args: [-y, mcp-server-sqlite, --db, ~/data/demo.db] }, internal-events: { type: sse, url: http://127.0.0.1:8787/mcp } } }三个 server 分别对应两种启动模式stdio 本地进程比如npx拉起一个 Node 服务SSE 远程连接适合已经常驻本机的服务。为什么命令和参数要分开因为不同 agent 对命令数组的解析不一样。你如果写成command: npx -y mcp-server-time有的 agent 会尝试找一个名字里带空格的程序直接 ENOENT 报错。拆开写是最保险的。另外要避免在 registry 里写相对路径或$HOME因为不同配置文件里~/的展开机制不一定一样。SQLite 这个例子里我用的是~/data/demo.db实际最好预先展开成绝对路径或者把展开逻辑统一交给同步脚本。3.2 第二步写一个同步脚本一键生成各工具的配置这是整套方案的心脏。我写了一个sync_agents.py作用很简单读registry.json生成四种配置覆盖前自动备份。#!/usr/bin/env python3 统一 MCP 注册表同步到本地全部 agent import json import shutil from pathlib import Path HOME Path.home() BASE HOME / .agents MCP_REGISTRY BASE / mcp/registry.json TARGETS { claude: HOME / .claude.json, cursor: HOME / .cursor/mcp.json, hermes: HOME / .hermes/config.json, } CLAUDE_FALLBACK_MCP HOME / .claude/mcp.json CODEX_CONFIG HOME / .codex/config.toml def load_registry(): with open(MCP_REGISTRY, r, encodingutf-8) as f: return json.load(f) def backup(path: Path): if path.exists(): bak path.with_suffix(path.suffix .bak) shutil.copy2(path, bak) print(fbackup: {path} - {bak}) def write_json(path: Path, data: dict): path.parent.mkdir(parentsTrue, exist_okTrue) with open(path, w, encodingutf-8) as f: json.dump(data, f, indent2, ensure_asciiFalse) print(fwritten: {path}) def sync_json_target(target: Path, data: dict, merge_key: str | None None): backup(target) if merge_key and target.exists(): try: existing json.loads(target.read_text(encodingutf-8)) except json.JSONDecodeError: existing {} existing[merge_key] data[mcpServers] write_json(target, existing) else: write_json(target, {mcpServers: data[mcpServers]}) def sync_codex(data: dict): backup(CODEX_CONFIG) lines [] for name, cfg in data[mcpServers].items(): lines.append(f[mcp_servers.{name}]) if cfg.get(type) sse: lines.append(ftype sse) lines.append(furl {cfg[url]}) else: lines.append(fcommand {cfg[command]}) args , .join(json.dumps(a) for a in cfg.get(args, [])) lines.append(fargs [{args}]) lines.append() CODEX_CONFIG.parent.mkdir(parentsTrue, exist_okTrue) CODEX_CONFIG.write_text(\n.join(lines), encodingutf-8) print(fwritten: {CODEX_CONFIG}) def main(): data load_registry() for name, path in TARGETS.items(): sync_json_target(path, data, merge_keymcpServers) sync_codex(data) print(sync done) if __name__ __main__: main()这段代码有几个值得说的地方。第一Claude Code 的主配置是~/.claude.json里面并不只有 MCP 配置所以我用merge_key只更新mcpServers字段不碰其他内容。这比直接覆盖安全得多。第二Codex 的部分我直接生成一个新的config.toml。如果你的config.toml里还配置了模型、代理等别的东西这个脚本会覆盖所以我加了一行备份。如果你有多段配置最好的办法是用tomli-w这类库做字段级合并我为了展示核心逻辑没有把代码写得那么长。第三Hermes Agent 这种轻量 agent它的全局配置其实就是纯 JSON我这里直接按mcpServers结构输出。不同版本的 agent 如果字段名不一样你只需要改sync_json_target里的merge_key。跑一次python3 ~/.agents/sync/sync_agents.py四个 agent 的 MCP 配置全部生成完毕。新增一个 server 时改 registry再跑一次完事。3.3 第三步技能和规则文件的软链同步MCP 配置可以用脚本生成技能和规则更适合用软链接。因为技能本质是一个目录里面可能有脚本、参考文件软链能让所有 agent 直接看到同一个目录。Claude Code 这边这样接ln -sfn ~/.agents/skills ~/.claude/skills如果~/.claude/skills原本有内容先把它合并进~/.agents/skills再做软链不要直接覆盖。Cursor 的规则是项目级的但你可以把项目的.cursor/rules变成一条软链ln -sfn ~/.agents/rules/cursor ~/你的项目/.cursor/rules这样你在中央目录里维护规则项目里自动生效。唯一需要注意的是一个项目如果已经有自己的本地规则你把整个目录替换掉会丢内容。更好的做法是保留项目目录单独软链规则文件ln -sf ~/.agents/rules/cursor/project-rules.mdc ~/你的项目/.cursor/rules/project-rules.mdcCodex 的规则用AGENTS.md在每个项目根目录里同样做一条软链ln -sf ~/.agents/rules/coding-style.md ~/你的项目/AGENTS.md这里有一个小心得规则文件这类东西最好用ln -sf而不是cp。因为用软链中央目录改一处所有项目都同步用复制改一次就得重新分发一次。有人担心软链在 git 仓库里会被同事拉下来变成无效链接这确实存在但编码智能体的规则本身就是个人辅助居多至少我自己跑下来没遇到实际问题。3.4 第四步验证每个 Agent 是否真正识别配置写完不验证等于白写。我每次同步完会做一套固定检查。所有 agent 必须先重启会话。MCP server 列表在启动时加载你改完配置文件老会话里可能还挂着一堆旧连接。在 agent 自己的 MCP 面板里看 server 状态。Claude Code 里可以用/mcp这类内置命令列出已注册的 serverCursor 在设置里有 MCP 页面Codex 和 Hermes 也有各自的列表命令。如果某个 server 显示连接失败优先看它启动时用的命令是不是本地可用。用一条强制调用外部工具的 prompt 做实测。我会对time这个 server 发一句“调用 time 工具告诉我当前时间”。如果 agent 能给出时间说明链路是通的如果回答“没有 time 工具”那多半是 MCP 配置没被读到。看一眼日志有没有spawn ENOENT。这个错误几乎都是命令路径不对比如npx不在 agent 的 PATH 里或者配置里写了不存在的命令。这套验证跑通畅以后你再改 registry 里的任何 server都只需要三步改注册表、跑同步脚本、重启 agent。4. 填坑实录配置同步里最常见的 6 个问题4.1 问题速查表配置同步看起来简单实际用起来总有些奇怪情况。我把踩过的坑整理成一张表按症状、原因、解法排列。症状原因解法改完 registry 后 agent 不识别新 server会话没重启MCP 列表是启动时缓存的重启 agent 会话再看 MCP 面板生成的 JSON 文件报解析错误手工往 registry 里写了注释JSON 标准不允许改用 .jsonc 风格或把注释放到额外字段Claude Code 配置被同步脚本覆盖后丢了历史记录直接用整份 JSON 覆盖了~/.claude.json改用 merge_key 只更新mcpServers字段多个 agent 共享同一个本地 MCP server端口冲突每个 agent 启动的都是独立进程都尝试监听同一端口本地 server 改成单例常驻agent 用 SSE 连接Windows 下软链失败没有管理员权限或者路径分隔符不对用mklink /D脚本里统一用 Path 类处理路径npx每次下载不同版本工具不稳定MCP server 包版本漂移固定版本号比如version后缀有几个点值得展开。~/.claude.json被覆盖是我最开始踩过的大坑。这个文件除了 MCP还保存着认证、会话白名单等状态你要是直接把整份文件替换了轻则丢历史记录重则要重新登录。所以脚本里必须做字段级合并不能整个文件覆盖。JSON 注释问题也很有迷惑性。你写 registry 的时候想加个说明随手来个// 这个是线上数据库微调一下这段文本然后发现至少三个 agent 解析失败。JSON 标准不允许注释我的处理方式是把注释写进一个_notes字段列表里展示 name 和用途既不影响解析又保留了可读性。4.2 几条比问题表更有价值的经验问题表能帮你急救但真正让你少走弯路的是下面几条使用习惯。命名要稳定。MCP server 的名字会在 agent 的上下文里出现我用短横线风格比如internal-events不用空格和中文。原因很简单某些 CLI 在解析参数时碰到空格会直接把 server 名拆成两个参数排查起来非常难受。生成物永远不要手改。脚本产出的配置文件比如~/.claude.json的mcpServers字段、Codex 的config.toml我从来不手工编辑。你手改一次下次同步就会把它冲掉然后你还困惑“我明明改了怎么没了”。正确流程是所有变更只发生在 registry生成物只是结果。升级 agent 前先同步一次。我有一次升级 Codex CLI 后发现 MCP 全不生效了排查到最后发现是它新版本改了配置字段命名。从那以后我的习惯是升级任何 agent 之前先跑一次 sync这样能快速区分是同步脚本的问题还是 agent 版本自身的问题。日志比面板靠谱。很多 agent 的 MCP 面板只显示“已连接”但实际工具可能根本没加载成功。真正靠谱的是去看 agent 启动日志里的 MCP 初始化记录。比如spawn ENOENT这种错误面板上不一定有但日志里一定写得明明白白。5. 这套方案还能怎么延伸如果你觉得只同步自己一台机器还不够这套结构其实很容易扩展。可以把~/.agents整个目录扔进一个私有 git 仓库配置和技能都纳入版本管理。换新电脑时clone 下来跑一次sync_agents.py所有 agent 的能力立刻恢复。你改了 registry 以后git diff 能看到每次到底改动什么比记忆“我上周到底给哪一个工具加了什么”可靠得多。团队协作也能用。把中央目录放到内部仓库里同事拉下来以后执行脚本就能获得团队标准能力集合。当然这需要你们对 MCP server 的可信度、版本和启动参数达成一致至少不会出现“我本地连的是测试库你本地连的是线上库”这种手滑事故。新增一个 agent 的成本也会降到很低。我后来接入 Hermes Agent 的时候整个过程就是在TARGETS里加一行路径写一个生成函数跑一次脚本验证。真正的配置逻辑一行都没动只是在翻译层多适配了一种格式。任何一个新 agent只要它支持读取某个位置的某种格式配置理论上都能被这套结构接进来。如果你希望更进一步可以在sync_agents.py里加一个 hook在每次生成后自动执行每个 agent 的配置重载命令。这样连“重启 agent 会话”都不用做真正达到改一个文件、全部生效的效果。不过这个要看各个 agent 是否支持配置热重载我目前没全跑通暂时还停留在半自动阶段。最后分享一个让我最舒服的小习惯。我在 shell 里加了一个别名一条命令完成“打开 registry → 保存后跑同步 → 打印变更摘要”。所有 agent 的能力都在同一个文件里管理新增工具、调整参数、查看差异都变成了一件不费脑子的例行公事。当你维护的智能体越来越多能把这些重复劳动交给脚本你的注意力才能真正回到写代码这件事上。