Sync Agents Settings

同步代理设置

 ](https://www.npmjs.com/package/sync-agents-settings) ](https://www.npmjs.com/package/sync-agents-settings)  ](https://nodejs.org/) ](https://pnpm.io/)    

从以下位置同步MCP服务器配置和指令文件（CLAUDE.md） 克劳德代码 到 双子星命令行工具, Codex CLI, 开源代码, Kiro命令行界面, 光标, 化学CLI, Vibe命令行界面 （米斯特拉尔）， 通义代码, 安培 （源图）， Cline命令行界面, 帆板运动，以及 助手CLI.

README翻译： 🇹🇼繁体中文 | 🇨🇳 简体中文 | 🇯🇵日本语 | 🇰🇷 韩语 支持矩阵： CLI兼容性矩阵

为什么

如果你使用Claude Code作为你的主要AI编码代理，但也在其他代理（Gemini CLI、Codex CLI、OpenCode、Kiro、Cursor、Kimi CLI、Vibe CLI、Qwen Code、Amp、Cline CLI、Windsurf）之间切换，以利用它们的免费层或不同的模型，你知道其中的痛苦——每个工具都有自己的MCP配置格式，逐一设置它们是乏味的。指令文件也是如此——CLAUDE.md、GEMINI.md、AGENTS.md都需要相同的内容，但格式不同。

此工具允许您配置MCP服务器并在Claude Code中编写一次指令，然后使用单个命令在任何地方同步。

快速开始

选项A:Claude代码插件（推荐）

通过marketplace安装为Claude Code插件：

# 1. Add the marketplace
claude plugin marketplace add Leoyang183/sync-agents-settings

# 2. Install the plugin
claude plugin install sync-agents-settings

# Then use slash commands in any conversation:
#   /sync               — sync MCP configs (with dry-run preview)
#   /sync-list          — list all MCP servers
#   /sync-diff          — compare configs between agents
#   /sync-doctor        — detect config drift and parse errors
#   /sync-validate      — validate schema and target capabilities
#   /sync-reconcile     — validate + detect drift + sync only missing
#   /sync-instructions  — sync CLAUDE.md to other agents
#   /report-schema      — print or write report JSON schema markdown

该插件还包括 同步感知技能 当您编辑MCP设置或CLAUDE.md文件时，它会自动建议同步。

选项B:npx命令行界面

无需安装，只需运行 npx:

# List all MCP servers detected from Claude Code
npx sync-agents-settings list

# Preview sync (no files modified)
npx sync-agents-settings sync --dry-run

# Sync to all targets (with automatic backup)
npx sync-agents-settings sync

# Sync CLAUDE.md instructions to all targets
npx sync-agents-settings sync-instructions

选项C：全局安装

# Global install for the `sync-agents` command
npm install -g sync-agents-settings

# Then use directly
sync-agents list
sync-agents sync

用法

# Sync to a specific target
sync-agents sync --target gemini
sync-agents sync --target codex
sync-agents sync --target opencode
sync-agents sync --target kiro
sync-agents sync --target cursor
sync-agents sync --target kimi
sync-agents sync --target vibe
sync-agents sync --target qwen
sync-agents sync --target amp
sync-agents sync --target cline
sync-agents sync --target windsurf

# Sync to Codex project-level config
sync-agents sync --target codex --codex-home ./my-project/.codex

# Sync to Kimi project-level config
sync-agents sync --target kimi --kimi-home ./my-project/.kimi

# Sync to custom home directories
sync-agents sync --target qwen --qwen-home ./my-project/.qwen
sync-agents sync --target amp --amp-home ./my-project/.amp
sync-agents sync --target cline --cline-home ./my-project/.cline
sync-agents sync --target windsurf --windsurf-home ./my-project/.windsurf

# Compare differences
sync-agents diff

# Check drift / parse errors between Claude and targets
sync-agents doctor

# Validate source schema and target capability compatibility
sync-agents validate

# One-shot safe reconcile (validate + doctor + sync missing)
sync-agents reconcile --dry-run

# CI-friendly JSON output
sync-agents reconcile --report json

# CI-friendly JSON output for drift checker
sync-agents doctor --report json

# CI-friendly JSON output for schema/capability validation
sync-agents validate --report json

# CI-friendly JSON output for sync result
sync-agents sync --report json --dry-run

# CI-friendly JSON output for instruction sync
sync-agents sync-instructions --report json --dry-run --global --target gemini

# CI-friendly JSON output for diff result
sync-agents diff --report json --target gemini codex

# Note: all --report json outputs include `schemaVersion: 1`

Report schema reference: `docs/report-schema.md`

# Regenerate report schema documentation
sync-agents report-schema --write docs/report-schema.md

# CI check: ensure report schema doc is up to date
sync-agents report-schema --check

# Auto-fix from doctor (internally runs reconcile)
sync-agents doctor --fix --dry-run

# Auto-fix after validation passes
sync-agents validate --fix --dry-run

# Skip OAuth-only servers (e.g. Slack)
sync-agents sync --skip-oauth

# Skip backup
sync-agents sync --no-backup

# Verbose output
sync-agents sync -v

# Check only specific targets
sync-agents doctor --target gemini codex

# Check Codex project-level config drift
sync-agents doctor --target codex --codex-home ./.codex

# Validate only selected targets and ignore OAuth-only servers
sync-agents validate --target codex opencode --skip-oauth

# Validation semantics:
# - blank-only command/url values are treated as missing
# - OAuth-only servers produce manual-setup warnings without duplicate field errors

# Reconcile selected targets only
sync-agents reconcile --target gemini codex

# Sync instruction files (CLAUDE.md → GEMINI.md / AGENTS.md / Kiro steering / Cursor rules / Aider conventions)
# Targets: gemini, codex, opencode, kimi, vibe, kiro, cursor, aider, qwen, amp
sync-agents sync-instructions

# Sync only global instructions
sync-agents sync-instructions --global

# Sync only project-level instructions
sync-agents sync-instructions --local

# Sync to specific targets
sync-agents sync-instructions --target gemini codex kimi vibe aider qwen amp

# Auto-overwrite without prompts (for CI)
sync-agents sync-instructions --on-conflict overwrite

# Keep legacy behavior: remove standalone @import lines instead of expanding
sync-agents sync-instructions --import-mode strip

# Allow standalone @import to read files outside current project root (use with care)
sync-agents sync-instructions --allow-unsafe-imports

# Preview instruction sync
sync-agents sync-instructions --dry-run

发展

git clone https://github.com/Leoyang183/sync-agents-settings.git
cd sync-agents-settings
pnpm install
pnpm dev list        # Run from source
pnpm test            # Run tests

运作原理

克劳德密码是唯一的真理来源 对于MCP设置，同步到所有支持的目标。

                                                 ┌─→ Gemini Writer    ─→ ~/.gemini/settings.json
                                                 ├─→ Codex Writer     ─→ ~/.codex/config.toml
~/.claude.json ─────┐                            ├─→ OpenCode Writer  ─→ ~/.config/opencode/opencode.json
                     ├─→ Reader ─→ UnifiedMcpServer[] ─┼─→ Kiro Writer      ─→ ~/.kiro/settings/mcp.json
~/.claude/plugins/ ──┘                            ├─→ Cursor Writer    ─→ ~/.cursor/mcp.json
                                                 ├─→ Kimi Writer      ─→ ~/.kimi/mcp.json
                                                 ├─→ Vibe Writer      ─→ ~/.vibe/config.toml
                                                 ├─→ Qwen Writer      ─→ ~/.qwen/settings.json
                                                 ├─→ Amp Writer       ─→ ~/.config/amp/settings.json
                                                 ├─→ Cline Writer     ─→ ~/.cline/data/settings/cline_mcp_settings.json
                                                 └─→ Windsurf Writer  ─→ ~/.codeium/windsurf/mcp_config.json

指令同步(sync-instructions)

将CLAUDE.md指令文件同步到每个目标的本机格式：

                                          ┌─→ ~/.gemini/GEMINI.md             (plain copy)
                                          ├─→ ~/.codex/AGENTS.md              (plain copy)
~/.claude/CLAUDE.md (+ ~/.claude/rules/*.md) ─→ expand @imports ──┼─→ ~/.config/opencode/AGENTS.md    (plain copy)
                                          ├─→ ~/.kimi/AGENTS.md               (plain copy)
                                          ├─→ ~/.vibe/AGENTS.md               (plain copy)
                                          ├─→ ~/.qwen/AGENTS.md               (plain copy)
                                          ├─→ ~/.config/amp/AGENTS.md         (plain copy)
                                          ├─→ ~/.kiro/steering/claude-instructions.md  (+ inclusion: always)
                                          └─→ ⚠ Cursor global not supported  (SQLite)

                                          ┌─→ ./GEMINI.md                     (plain copy)
                                          ├─→ ./AGENTS.md                     (Codex + OpenCode + Kimi + Vibe + Qwen + Amp share)
./.claude/CLAUDE.md (fallback: ./CLAUDE.md) + ./.claude/rules/*.md ─→ expand @imports ──┼─→ .kiro/steering/claude-instructions.md    (+ inclusion: always)
                                          └─→ .cursor/rules/claude-instructions.mdc   (+ alwaysApply: true)

笔记：

• 首选本地源解析 ./.claude/CLAUDE.md，然后回落到 ./CLAUDE.md.
• 额外规则 .claude/rules/**/*.md 自动附加（除非已通过 @import).
• 如果规则文件有frontmatter paths，仅当至少有一个项目文件匹配时，才会包含它。
• @import 处理默认值 inline （扩展）。使用 --import-mode strip 删除独立的导入行。
• 默认情况下，独立 @import 只能读取当前项目根目录内的文件。使用 --allow-unsafe-imports 选择退出。
• 内联进口扩张有护栏(max depth: 20, max files: 200)以避免失控的递归。
• 助手同步也会出现问题 .aider.conf.yml read 所以 CONVENTIONS.md 自动加载（全局/项目遵循同步范围）。
• Kimi CLI当前正在加载 AGENTS.md 从工作目录。 ~/.kimi/AGENTS.md 同步为可重用的全局模板。

当目标文件已存在时，系统将提示您选择： 覆盖, 附加 （保留现有+在下面添加CLAUDE.md），或 跳过.使用 --on-conflict overwrite|append|skip 用于非交互模式。

安全机制：

• 现有服务器永远不会被覆盖（幂等，可以安全地重新运行）
• 自动备份到 ~/.sync-agents-backup/ 默认情况下(--no-backup 跳过）
• --dry-run 预览更改而不写入任何文件

来源：克劳德代码

从两个来源读取MCP服务器：

1. ~/.claude.json → mcpServers 对象（用户配置的服务器）
2. **`~/.claude/plugins/cache//

//.mcp.json** → 启用插件MCP服务器（与 ~/.claude/settings.json enabledPlugins`)

克劳德代码有两个 .mcp.json 格式：

// Format 1: Flat (e.g. context7, firebase)
{ "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } }

// Format 2: Nested under mcpServers (e.g. sentry, stripe)
{ "mcpServers": { "sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" } } }

目标：Gemini CLI

写信给 ~/.gemini/settings.json → mcpServers 对象。

与Claude的主要格式差异：

• 克劳德 type: "http" → 双子座 httpUrl
• 克劳德 type: "sse" → 双子座 url
• 克劳德 command （stdio）→ 双子座 command （相同）
• Env-var语法：Claude ${VAR} → 双子座 $VAR （自动转换）

// Gemini settings.json
{
  "theme": "Dracula",          // existing settings preserved
  "mcpServers": {
    "context7": {              // stdio server
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sentry": {                // http server
      "httpUrl": "https://mcp.sentry.dev/mcp"
    }
  }
}

目标：Codex CLI

写信给 ~/.codex/config.toml 默认情况下为（全局）。使用 --codex-home 写到项目级别 .codex/config.toml 相反。

注： Codex CLI不会合并全局和项目配置。当一个项目 .codex/，Codex只读取该目录。全球 ~/.codex/ 完全被忽略了。

关键格式差异：

• 使用TOML而不是JSON
• command/args stdio（相同概念）
• url 对于HTTP服务器（不需要类型字段）
• env 是一个TOML子表 [mcp_servers..env]

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.sentry]
url = "https://mcp.sentry.dev/mcp"

[mcp_servers.n8n-mcp]
command = "npx"
args = ["n8n-mcp"]

  [mcp_servers.n8n-mcp.env]
  N8N_API_KEY = "your-key"
  N8N_API_URL = "https://your-n8n.example.com"

目标：OpenCode

写信给 ~/.config/opencode/opencode.json → mcp 对象。

关键格式差异：

• 根密钥为 mcp （不是 mcpServers)
• stdio服务器使用 type: "local" 与合并 command 数组（命令+参数组合）
• HTTP/SSE服务器使用 type: "remote"
• 环境变量使用 environment 字段（非 env)

// opencode.json
{
  "model": "anthropic/claude-sonnet-4-5",  // existing settings preserved
  "mcp": {
    "context7": {                          // stdio → local
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"]
    },
    "sentry": {                            // http → remote
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "n8n-mcp": {                           // env → environment
      "type": "local",
      "command": ["npx", "n8n-mcp"],
      "environment": {
        "N8N_API_KEY": "your-key"
      }
    }
  }
}

目标：Kiro CLI

写信给 ~/.kiro/settings/mcp.json → mcpServers 对象。

格式与Claude Code相同。 ${VAR:-default} URL中的语法在同步过程中会自动扩展。

目标：光标

写信给 ~/.cursor/mcp.json → mcpServers 对象。

格式与Claude Code相同。 ${VAR:-default} URL中的语法在同步过程中会自动扩展。

目标：Kimi CLI

写信给 ~/.kimi/mcp.json 默认情况下。使用 --kimi-home 同步到自定义基目录（例如，项目级别 .kimi/).

格式与Claude Code相同。 ${VAR:-default} URL中的语法在同步过程中会自动扩展。

目标：Vibe CLI（米斯特拉尔）

写信给 ~/.vibe/config.toml 默认情况下。使用 --vibe-home 同步到自定义基目录（例如，项目级别 .vibe/).

关键格式差异：

• 使用TOML [[mcp_servers]] （表数组）——每个条目都有一个 name 明确 transport 领域
• 克劳德 "http" → Vibe "streamable-http"克劳德 "sse" → Vibe "http"
• command 是字符串（不是数组）， env 是一个TOML子表
• ${VAR:-default} URL中的语法在同步过程中会自动扩展

[[mcp_servers]]
name = "context7"
transport = "stdio"
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[[mcp_servers]]
name = "supabase"
transport = "streamable-http"
url = "https://mcp.supabase.com/mcp"

目标：Qwen代码

写信给 ~/.qwen/settings.json → mcpServers 对象。使用 --qwen-home 同步到自定义基本目录。

与Gemini相同的转换模式：

• 克劳德 type: "http" → Qwen httpUrl
• 克劳德 type: "sse" → Qwen url
• Env-var语法：Claude ${VAR} → Qwen $VAR （自动转换）

// ~/.qwen/settings.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sentry": {
      "httpUrl": "https://mcp.sentry.dev/mcp"
    }
  }
}

目标：安培（源图）

写信给 ~/.config/amp/settings.json → "amp.mcpServers" 钥匙。使用 --amp-home 同步到自定义基本目录。

关键格式差异：

• 根密钥为 "amp.mcpServers" （不是 mcpServers)
• url 字段保持原样（与克劳德相同）
• ${VAR} 语法保留（无需转换）

// ~/.config/amp/settings.json
{
  "amp.mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

目标：Cline CLI

写信给 ~/.cline/data/settings/cline_mcp_settings.json → mcpServers 对象。使用 --cline-home 同步到自定义基本目录。

格式与Claude Code相同。 ${VAR:-default} URL中的语法在同步过程中会自动扩展。

// ~/.cline/data/settings/cline_mcp_settings.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

目标：风帆

写信给 ~/.codeium/windsurf/mcp_config.json → mcpServers 对象。使用 --windsurf-home 同步到自定义基本目录。

关键格式差异：

• 克劳德 url → 帆板运动 serverUrl
• Env-var语法：Claude ${VAR} → 帆板运动 ${env:VAR} （自动转换）

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sentry": {
      "type": "http",
      "serverUrl": "https://mcp.sentry.dev/mcp"
    }
  }
}

运输类型映射

备份

每次同步都会自动将所有受影响的配置文件备份到 ~/.sync-agents-backup// 在写入之前，请保留相对于的原始目录结构 ~:

~/.sync-agents-backup/2026-03-20T00-06-08-042Z/
├── .claude.json                  # ← ~/.claude.json
├── .claude/
│   └── settings.json             # ← ~/.claude/settings.json
├── .gemini/
│   └── settings.json             # ← ~/.gemini/settings.json
├── .codex/
│   └── config.toml               # ← ~/.codex/config.toml
├── .config/
│   ├── opencode/
│   │   └── opencode.json         # ← ~/.config/opencode/opencode.json
│   └── amp/
│       └── settings.json         # ← ~/.config/amp/settings.json
├── .kiro/
│   └── settings/
│       └── mcp.json              # ← ~/.kiro/settings/mcp.json
├── .cursor/
│   └── mcp.json                  # ← ~/.cursor/mcp.json
├── .kimi/
│   └── mcp.json                  # ← ~/.kimi/mcp.json
├── .vibe/
│   └── config.toml               # ← ~/.vibe/config.toml
├── .qwen/
│   └── settings.json             # ← ~/.qwen/settings.json
├── .cline/
│   └── data/
│       └── settings/
│           └── cline_mcp_settings.json  # ← ~/.cline/data/settings/cline_mcp_settings.json
└── .codeium/
    └── windsurf/
        └── mcp_config.json       # ← ~/.codeium/windsurf/mcp_config.json

使用 --no-backup 跳过。不存在的目标目录（未安装CLI）将被跳过并发出警告，而不会创建。

配置文件位置

MCP设置

指令文件

Claude代码插件

这个项目既是克劳德代码 插件 和 市场，直接在Claude Code对话中提供斜线命令和上下文技能。

安装

# From GitHub (remote — clones the repo)
claude plugin marketplace add Leoyang183/sync-agents-settings
claude plugin install sync-agents-settings

# Or from local path (symlink — reflects local changes instantly)
claude plugin marketplace add /path/to/sync-agents-settings
claude plugin install sync-agents-settings

斜杠命令

同步感知技能

该插件包含一项技能，可以在编辑MCP设置时自动检测(.claude.json, .mcp.json)或 CLAUDE.md 文件，并建议同步到其他代理。

插件开发

# Validate plugin/marketplace structure
claude plugin validate /path/to/sync-agents-settings

局限性

• OAuth服务器 （例如，Slack with oauth.clientId)仅作为URL同步——您需要在每个CLI中手动进行身份验证
• ${CLAUDE_PLUGIN_ROOT} env变量在其他CLI中无法解析
• Codex CLI不支持 ${VAR:-default} URL中的语法——这些在同步过程中会自动展开（如果设置了env值，则为默认值）
• 重新运行同步将 不覆盖 现有条目（可安全运行多次）
• Codex CLI不会合并全局和项目配置——当 .codex/ 存在于项目中，全局 ~/.codex/ 被忽略
• 如果目标配置目录不存在，sync将跳过该目标（不会创建目录）

星迹


许可证

麻省理工学院