vibe-config-sync

English | 中文文档

命令： vibe-sync

通过 Git 跨机器同步 AI 编程工具配置。支持 Claude Code（~/.claude/）和 Codex（~/.codex/）。

问题

在多台机器上使用 AI 编程工具时，技能、命令、代理、插件和用户偏好等配置需要在每台机器上手动复制。

安全建议

• 同步仓库强烈建议使用私有仓库。
• 如果使用公开仓库，请不要同步任何敏感信息（API Key、Token、凭据、配置文件或 MCP env 中的密钥等）。

同步内容

默认 provider 为 all（Claude + Codex）。

Claude（data/claude/）

| 内容 | 说明 | |------|------| | settings.json | 插件启用/禁用标志 | | CLAUDE.md | 用户偏好和工作流指南 | | skills/ | 技能定义（SKILL.md + 引用 + 模板） | | commands/ | 自定义斜杠命令 | | agents/ | 代理定义 | | plugins/installed_plugins.json | 插件注册表（已剥离机器路径） | | plugins/known_marketplaces.json | 插件市场来源（已剥离机器路径） | | mcp-servers.json | MCP 服务器配置（从 ~/.claude.json 提取） |

Codex（data/codex/）

| 内容 | 说明 | |------|------| | config.toml | Codex 配置 | | AGENTS.md | Codex 用户偏好与工作流说明 | | commands/ | 用户自定义命令（若存在） | | skills/ | Codex 技能 | | agents/ | Codex 代理 |

不同步（机器特定 / 临时 / 大文件）：缓存、日志、临时/锁文件、会话态、运行期认证材料等。

前置条件

• Node.js 18+
• git
• claude CLI（用于插件同步；随 Claude Code 自动安装）

安装

npm install -g vibe-config-sync

快速开始

机器 A（首次设置）

vibe-sync init          # 初始化并连接 Git 远程仓库
vibe-sync push          # 导出所有 provider 并推送
vibe-sync push --provider claude   # 仅 Claude

机器 B（导入）

vibe-sync init                      # 初始化并从远程仓库拉取
vibe-sync pull                      # 拉取并导入所有 provider
vibe-sync pull --provider claude    # 仅 Claude
vibe-sync pull --no-plugins         # 关闭 Claude 插件阶段

命令

| 命令 | 说明 | |------|------| | vibe-sync init | 初始化同步仓库并连接 Git 远程仓库 | | vibe-sync export | 导出所选 provider（--provider claude|codex|all，默认 all） | | vibe-sync import | 导入所选 provider（--provider claude|codex|all，默认 all） | | vibe-sync import --no-plugins | 跳过 Claude 插件阶段（对 Codex 无影响） | | vibe-sync import --dry-run | 预览将要导入的内容，不实际执行 | | vibe-sync status | 显示所选 provider 的差异 | | vibe-sync push | export + git commit + git push | | vibe-sync pull | git pull + import | | vibe-sync pull --no-plugins | 导入时跳过 Claude 插件阶段 | | vibe-sync pull --dry-run | 预览将要导入的内容（跳过 git pull） | | vibe-sync restore | 列出可用备份（支持 --provider，默认 all） | | vibe-sync restore <timestamp> | 从指定时间戳恢复所选 provider（all 会恢复存在的 provider，缺失则跳过） |

日常工作流

# 在机器 A 上修改配置后
vibe-sync push

# 在机器 B 上拉取最新配置
vibe-sync pull

工作原理

• 按 provider 分目录：同步数据存储在 ~/.vibe-sync/data/claude/ 与 ~/.vibe-sync/data/codex/（旧版 Claude 根目录布局会自动迁移）。

• 导出：按 provider 复制配置。Claude 插件 JSON 会剥离机器路径；Claude MCP 从 ~/.claude.json 提取。Codex config.toml 会做敏感键扫描，检测到敏感字段时必须交互确认后才可导出。非交互模式下若检测到敏感字段，会告警并跳过该文件导出。

• 导入：从 provider 目录恢复到本地。--provider all 按 claude -> codex 顺序执行，采用 fail-fast。Claude 插件 JSON 仅做清单，不直接复制；通过 claude CLI 安装。Claude MCP 只做增量合并（不覆盖同名现有项）。

• 备份：导入前在 ~/.vibe-sync/backups/<provider>/<timestamp>/ 创建 provider 级备份。all 模式下各 provider 独立备份，缺失本地配置则跳过。

同步策略

整体策略为最后写入优先，无冲突检测。没有字段级合并——最近一次导入会覆盖目标。

文件（settings.json、CLAUDE.md）

整文件覆盖。同步仓库版本完全替换本地版本。

目录（skills/、commands/、agents/）

目录级合并 + 文件级覆盖：

| 场景 | 行为 | |------|------| | 仓库有 skills/foo/，本地没有 | foo/ 被添加 | | 双方都有 skills/foo/SKILL.md | 仓库版本覆盖本地 | | 本地有 skills/bar/，仓库没有 | bar/ 被保留（不删除） | | 仓库的 skills/foo/ 缺少本地有的文件 | 本地文件被保留 |

简而言之：新内容会被添加，已有内容会被覆盖，但本地内容不会被删除。

符号链接技能

• 导出：通过 realpathSync 解析符号链接并复制实际文件内容——符号链接本身不会被保留
• 导入：作为普通目录复制，无需重建符号链接。这确保了技能在不同机器上都能正常工作，不受原始符号链接目标路径的影响

插件 JSON

插件 JSON 文件（installed_plugins.json、known_marketplaces.json）在导出时会剥离机器特定路径。导入时不会复制到 ~/.claude/plugins/——而是作为清单使用。claude CLI 被调用来安装每个插件，并在安装过程中写入包含本地路径的正确注册文件。已安装的插件（通过 installPath 检测）会被跳过，以避免冗余的网络操作。

MCP 服务器

MCP 服务器配置存储在 ~/.claude.json 的 mcpServers 键下。导出时，该部分被提取并保存为同步目录中的 mcp-servers.json。如果任何服务器配置包含 env 字段（可能包含 API 密钥等密钥），导出前会提示用户确认。

导入时，MCP 服务器采用仅增量策略——同步仓库中的新服务器会被添加到 ~/.claude.json，但同名的已有服务器不会被覆盖。这保留了机器特定的自定义配置（如本地路径、环境变量）。

Codex 文件

Codex 也遵循相同的最后写入优先策略：

• config.toml：整文件覆盖（不做 schema 校验）
• AGENTS.md：整文件覆盖
• commands/、skills/、agents/：目录合并 + 文件覆盖（不删除本地额外文件）
• 敏感键处理仅发生在导出阶段；导入不会恢复被脱敏的密钥值
• skills/ 中的符号链接会被解析并以真实目录形式同步

实际影响

• 如果两台机器修改了不同的配置然后同步，最后执行 import 的机器会丢失其本地更改（可在 ~/.vibe-sync/backups/claude/ 找到带时间戳的备份进行手动恢复）
• 在一台机器上删除的文件/技能不会在另一台机器上被删除——只有添加和修改会传播
• 符号链接的技能会被解析并作为普通目录复制，因此同步版本是独立于原始符号链接目标的独立快照

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | CLAUDE_HOME | 覆盖 Claude 配置目录 | ~/.claude | | CLAUDE_JSON | 覆盖 Claude 全局配置文件（MCP 服务器） | ~/.claude.json | | CODEX_HOME | 覆盖 Codex 配置目录 | ~/.codex |

许可证

MIT