用 chezmoi 同步多台机器的 Claude Code 配置：完整教程

一处修改，处处同步。新机器一条命令搞定。

一、背景：多机器配置同步的痛点

我有 3 台 Mac：一台 MacBook、两台 Mac Mini。每台都装了 Claude Code，也装了一堆 Skills——gstack、humanizer、marketing skills 等等。以后可能还会加云服务器。

用了一段时间后，问题来了：

在 MacBook 上装的 skill，Mini 上没有
改了 CLAUDE.md 全局配置，另一台还是旧版
换新机器要从头配一遍，每次至少半小时
Skills 更新了，要手动去每台机器 git pull

我需要的是：

✅ 一处修改，所有机器自动同步
✅ Skills 能自动更新
✅ 新机器一条命令搞定
✅ 不同机器可以有不同配置（比如服务器需要额外的 skills）

二、方案选型：为什么选 chezmoi

市面上管理 dotfiles（配置文件）的工具不少，我对比了几种：

方案	优点	缺点
手动复制	简单	累死，容易漏，不可持续
Git 裸仓库	纯 Git，无依赖	配置复杂，冲突处理麻烦
Mackup	macOS 友好	不支持自定义路径，不够灵活
chezmoi	模板、加密、跨平台、支持外部源	有学习曲线

最终选了 chezmoi，原因：

模板支持——不同机器可以渲染出不同配置
external 外部源——可以自动从 GitHub 拉取 skills，还能定期更新
加密支持——API keys 也能安全同步（本文不涉及）
一条命令初始化——新机器 chezmoi init --apply 搞定

三、前置准备

3.1 安装 chezmoi

macOS：

brew install chezmoi

Linux：

sh -c "$(curl -fsLS get.chezmoi.io)"

验证安装：

chezmoi --version
# chezmoi version 2.70.0

3.2 创建 GitHub 仓库

去 GitHub 创建一个仓库，比如 dotfiles。可以是公开的，也可以是私有的。

建议：如果你的 CLAUDE.md 里没有敏感信息，公开仓库更方便（不用配 SSH）。

3.3 初始化 chezmoi

# 初始化（会创建 ~/.local/share/chezmoi 目录）
chezmoi init

# 进入 chezmoi 目录
cd ~/.local/share/chezmoi

# 关联远程仓库（替换成你的）
git remote add origin https://github.com/你的用户名/dotfiles.git

四、理解 Claude Code 的配置结构

在动手之前，先搞清楚 ~/.claude 目录里有什么，哪些需要同步：

~/.claude/
├── CLAUDE.md          ✅ 要同步 - 全局指令
├── settings.json      ✅ 要同步 - 插件和权限配置
├── skills/            ✅ 要同步 - 技能包
│   ├── gstack/
│   ├── humanizer/
│   └── marketingskills/
├── projects/          ❌ 不同步 - 每台机器的项目不同
├── sessions/          ❌ 不同步 - 运行时数据
├── history.jsonl      ❌ 不同步 - 对话历史，太大了
├── cache/             ❌ 不同步 - 缓存
└── debug/             ❌ 不同步 - 调试日志

Skills 的三种来源：

来源	例子	如何同步
Marketplace	obsidian, frontend-design	记录在 settings.json，Claude Code 启动时自动安装
GitHub 公开仓库	gstack, humanizer	用 chezmoi external 自动拉取
私有/自己写的	自己写的 skill	chezmoi add 直接管理，或放私有 repo

五、基础同步：CLAUDE.md 和 settings.json

5.1 添加配置文件

# 添加全局指令文件
chezmoi add ~/.claude/CLAUDE.md

# 添加插件配置
chezmoi add ~/.claude/settings.json

chezmoi 命名规则：

运行上面的命令后，你会发现 chezmoi 目录里多了个 private_dot_claude 文件夹。这是 chezmoi 的命名规则：

dot_ 前缀 = 点开头的文件/目录（.claude → dot_claude）
private_ 前缀 = 文件权限 600（只有自己能读写）

所以 ~/.claude 对应 private_dot_claude。

5.2 查看添加的文件

ls ~/.local/share/chezmoi/private_dot_claude/
# CLAUDE.md  settings.json

5.3 验证

# 查看 chezmoi 管理了哪些文件
chezmoi managed
# /Users/你的用户名/.claude/CLAUDE.md
# /Users/你的用户名/.claude/settings.json

六、配置 .chezmoiignore

为了避免把不需要同步的文件也加进去，创建 .chezmoiignore：

cat > ~/.local/share/chezmoi/.chezmoiignore << 'EOF'
# Claude Code 运行时数据，不同步
.claude/sessions
.claude/cache
.claude/history.jsonl
.claude/debug
.claude/telemetry
.claude/backups
.claude/projects
.claude/file-history
EOF

这样即使你不小心运行 chezmoi add ~/.claude，这些目录也会被忽略。

七、用 external 管理 GitHub Skills

这是最有价值的部分——让 chezmoi 自动从 GitHub 拉取 skills，还能定期更新。

7.1 创建 external 配置

cat > ~/.local/share/chezmoi/.chezmoiexternal.toml << 'EOF'
# Claude Code Skills - 从 GitHub 自动安装和更新
# 运行 chezmoi apply 会检查更新（超过 refreshPeriod 自动拉取）
# 强制刷新：chezmoi apply --refresh-externals

# GStack - Garry Tan 的工程团队模拟框架
[".claude/skills/gstack"]
type = "archive"
url = "https://github.com/garrytan/gstack/archive/main.tar.gz"
stripComponents = 1
refreshPeriod = "168h"  # 每周检查一次

# Humanizer - 去除 AI 生成痕迹
[".claude/skills/humanizer"]
type = "archive"
url = "https://github.com/blader/humanizer/archive/main.tar.gz"
stripComponents = 1
refreshPeriod = "168h"

# Marketing Skills - CRO/SEO/文案/增长
[".claude/skills/marketingskills"]
type = "archive"
url = "https://github.com/coreyhaines31/marketingskills/archive/main.tar.gz"
stripComponents = 1
refreshPeriod = "168h"

# Frontend Slides - 创建动画 HTML 演示文稿
[".claude/skills/frontend-slides"]
type = "archive"
url = "https://github.com/zarazhangrui/frontend-slides/archive/main.tar.gz"
stripComponents = 1
refreshPeriod = "168h"
EOF

7.2 配置详解

字段	含义
`[".claude/skills/xxx"]`	目标路径（相对于 home 目录）
`type = "archive"`	下载 tar.gz 压缩包并解压
`url`	GitHub 仓库的 archive 下载地址
`stripComponents = 1`	解压时去掉顶层目录（GitHub archive 会包一层）
`refreshPeriod = "168h"`	168 小时 = 7 天，超过这个时间会检查更新

7.3 应用配置

chezmoi apply

第一次运行会下载所有 skills，稍等片刻。

7.4 验证

ls ~/.claude/skills/
# frontend-slides  gstack  humanizer  marketingskills

八、验证完整配置

在提交之前，验证一切正常：

# 1. 查看 chezmoi 管理的文件
chezmoi managed

# 2. 查看 diff（本地 vs chezmoi 源）
chezmoi diff

# 3. 验证 skills 目录
ls ~/.claude/skills/

# 4. 验证 CLAUDE.md
head -10 ~/.claude/CLAUDE.md

# 5. 验证 settings.json
cat ~/.claude/settings.json

九、提交并推送

cd ~/.local/share/chezmoi

# 添加所有文件
git add .

# 提交
git commit -m "feat: add Claude Code config and skills"

# 推送
git push -u origin main

十、进阶：不同机器不同配置

如果某台机器需要额外的 skills，而其他机器不需要，可以用模板。

10.1 查看每台机器的 hostname

先在每台机器上运行：

hostname

记下来，比如：

MacBook: xiaobei-mbp.local
Mac Mini 1: xiaobei-mini.local
Mac Mini 2: xiaobei-mini2.local

10.2 把 external 配置改成模板

# 重命名为模板文件
mv ~/.local/share/chezmoi/.chezmoiexternal.toml \
   ~/.local/share/chezmoi/.chezmoiexternal.toml.tmpl

10.3 编辑模板

cat > ~/.local/share/chezmoi/.chezmoiexternal.toml.tmpl << 'EOF'
# ============================================
# 所有机器都安装的 Skills
# ============================================

[".claude/skills/humanizer"]
type = "archive"
url = "https://github.com/blader/humanizer/archive/main.tar.gz"
stripComponents = 1
refreshPeriod = "168h"

[".claude/skills/gstack"]
type = "archive"
url = "https://github.com/garrytan/gstack/archive/main.tar.gz"
stripComponents = 1
refreshPeriod = "168h"

# ============================================
# 仅 Mini 1（主力开发机）安装的 Skills
# ============================================
{{ if eq .chezmoi.hostname "xiaobei-mini.local" }}
[".claude/skills/frontend-slides"]
type = "archive"
url = "https://github.com/zarazhangrui/frontend-slides/archive/main.tar.gz"
stripComponents = 1
refreshPeriod = "168h"
{{ end }}

# ============================================
# 仅 Mini 2（服务器）安装的 Skills
# ============================================
{{ if eq .chezmoi.hostname "xiaobei-mini2.local" }}
[".claude/skills/server-monitoring"]
type = "archive"
url = "https://github.com/xxx/server-monitoring/archive/main.tar.gz"
stripComponents = 1
refreshPeriod = "168h"
{{ end }}
EOF

模板语法：

{{ if eq .chezmoi.hostname "xxx" }} — 如果 hostname 等于 xxx
{{ end }} — 条件结束
也可以用 {{ if contains .chezmoi.hostname "mini" }} 做模糊匹配

10.4 验证模板

# 查看当前机器会渲染出什么
chezmoi execute-template < ~/.local/share/chezmoi/.chezmoiexternal.toml.tmpl

十一、新机器一键配置

这是最爽的部分——新机器只需要两步：

公开仓库

# 1. 安装 chezmoi
brew install chezmoi  # 或 sh -c "$(curl -fsLS get.chezmoi.io)"

# 2. 一键初始化（替换成你的 GitHub 用户名）
chezmoi init 你的用户名/dotfiles --apply

私有仓库

# 需要用 SSH URL
chezmoi init [email protected]:你的用户名/dotfiles.git --apply

执行完毕后，自动获得：

✅ ~/.claude/CLAUDE.md 全局配置
✅ ~/.claude/settings.json 插件设置
✅ 所有配置的 GitHub skills
✅ Marketplace 插件会在首次启动 Claude Code 时自动安装

十二、日常维护命令

# 查看状态（本地和 chezmoi 源是否一致）
chezmoi status

# 查看差异
chezmoi diff

# 应用更新（本地 → 目标位置）
chezmoi apply

# 从远程拉取 + 应用
chezmoi update

# 强制刷新所有 external skills
chezmoi apply --refresh-externals

# 添加新文件到 chezmoi 管理
chezmoi add ~/.claude/新文件

# 编辑 chezmoi 中的文件（会自动打开编辑器）
chezmoi edit ~/.claude/CLAUDE.md

# 编辑后应用
chezmoi apply

十三、常见问题

Q1: `chezmoi apply` 报权限错误

原因：目标文件被 Claude Code 占用

解决：关闭 Claude Code 再试

# 或者强制覆盖
chezmoi apply --force

Q2: external skills 没有更新

原因：还没到 refreshPeriod（默认 7 天）

解决：强制刷新

chezmoi apply --refresh-externals

Q3: 私有仓库拉取失败

原因：用了 HTTPS，没有认证

解决：改用 SSH

chezmoi init [email protected]:你的用户名/dotfiles.git --apply

Q4: hostname 匹配不上

原因：有些系统 hostname 带 .local 后缀，有些不带

解决：用 contains 代替 eq

{{ if contains .chezmoi.hostname "mini" }}
...
{{ end }}

Q5: 本地改了配置，怎么同步回 chezmoi？

方法 1：重新添加

chezmoi add ~/.claude/CLAUDE.md

方法 2：直接编辑 chezmoi 源

chezmoi edit ~/.claude/CLAUDE.md
# 编辑完后
chezmoi apply

Q6: Marketplace 插件没有自动安装

这是正常的。Marketplace 插件（如 obsidian、frontend-design）存在 settings.json 里，但实际插件需要 Claude Code 启动后才会下载。

chezmoi 只负责同步 settings.json，插件下载是 Claude Code 的事。

十四、完整配置文件参考

目录结构

~/.local/share/chezmoi/
├── .chezmoiignore              # 忽略规则
├── .chezmoiexternal.toml.tmpl  # External skills 配置（模板）
├── private_dot_claude/
│   ├── CLAUDE.md               # 全局指令
│   └── settings.json           # 插件配置
└── README.md                   # 可选：说明文档

settings.json 示例

{
  "enabledPlugins": {
    "obsidian@obsidian-skills": true,
    "frontend-design@claude-plugins-official": true
  },
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": {
        "source": "github",
        "repo": "anthropics/claude-plugins-official"
      }
    }
  }
}

CLAUDE.md 示例

# Python Web Backend Rules

## 环境要求
- 使用 uv 管理依赖
- 使用 .venv/ 虚拟环境
- 运行命令用 uv run

## 项目结构
app/
  __init__.py
  routes.py
  models.py
main.py
tests/

## 常用命令
- 启动服务: uv run uvicorn app.main:app --reload
- 运行测试: uv run pytest
- 格式化: uv run ruff format .

十五、总结

痛点	解决方案
多机器配置不一致	chezmoi 统一管理，Git 同步
Skills 手动安装麻烦	external 自动从 GitHub 拉取
不同机器要不同配置	模板语法按 hostname 区分
新机器配置耗时	`chezmoi init --apply` 一条命令
Skills 需要手动更新	refreshPeriod 自动检查

一句话总结：

dotfiles 管理器 + GitHub = Claude Code 配置的终极同步方案

附录：推荐的 Claude Code Skills

Skill	用途	GitHub
gstack	模拟完整工程团队（CEO/Designer/QA）	garrytan/gstack
humanizer	去除 AI 生成痕迹	blader/humanizer
marketingskills	CRO/SEO/文案/增长（34个技能）	coreyhaines31/marketingskills
frontend-slides	创建动画 HTML 演示文稿	zarazhangrui/frontend-slides
baoyu-skills	宝玉的技能包（翻译、公众号等）	JimLiu/baoyu-skills

延伸：不止 Claude Code

chezmoi 能管理的远不止 Claude Code 配置。同样的方法可以用来同步：

zshrc / bashrc — 你的 shell 配置
git config — 全局 Git 设置
SSH config — 服务器连接配置
Vim / Neovim — 编辑器配置
tmux — 终端复用器配置
其他任何 dotfiles

一旦用上了 chezmoi，你会发现再也回不去手动复制配置的日子了。

懒人方案

如果你懒得一步步配，可以直接把这篇文章丢给你的 Claude Code 或 OpenClaw（小龙虾），让 AI 帮你搞定：

“帮我按照这篇教程配置 chezmoi，同步我的 Claude Code 配置到 GitHub。”

AI 会帮你创建仓库、添加配置、设置 external——你只需要最后确认一下就行。

如果这篇文章帮到了你，欢迎分享给也在用 Claude Code 的朋友。

用 chezmoi 同步多台机器的 Claude Code 配置：完整教程#

一、背景：多机器配置同步的痛点#

二、方案选型：为什么选 chezmoi#

三、前置准备#

3.1 安装 chezmoi#

3.2 创建 GitHub 仓库#

3.3 初始化 chezmoi#

四、理解 Claude Code 的配置结构#

五、基础同步：CLAUDE.md 和 settings.json#

5.1 添加配置文件#

5.2 查看添加的文件#

5.3 验证#

六、配置 .chezmoiignore#

七、用 external 管理 GitHub Skills#

7.1 创建 external 配置#

7.2 配置详解#

7.3 应用配置#

7.4 验证#

八、验证完整配置#

九、提交并推送#

十、进阶：不同机器不同配置#

10.1 查看每台机器的 hostname#

10.2 把 external 配置改成模板#

10.3 编辑模板#

10.4 验证模板#

十一、新机器一键配置#

公开仓库#

私有仓库#

十二、日常维护命令#

十三、常见问题#

Q1: chezmoi apply 报权限错误#

Q2: external skills 没有更新#

Q3: 私有仓库拉取失败#

Q4: hostname 匹配不上#

Q5: 本地改了配置，怎么同步回 chezmoi？#

Q6: Marketplace 插件没有自动安装#

十四、完整配置文件参考#

目录结构#

settings.json 示例#

CLAUDE.md 示例#

十五、总结#

附录：推荐的 Claude Code Skills#

延伸：不止 Claude Code#

懒人方案#