---
title: "使用 cclayer 在多台电脑之间同步 Claude Code 配置（CLAUDE.md、skills、插件、MCP），按团队隔离 git 身份"
description: "cclayer 是一个开源命令行工具，在多台电脑之间同步 Claude Code 的 CLAUDE.md、rules、skills、hooks、settings.json、插件和 MCP server。配置分成公开的基础层和每个团队一个的私有覆盖层，git 提交身份按仓库自动切换，支持 macOS / Linux / Windows，可以用 git 仓库或网盘文件夹同步。"
date: 2026-10-05T07:36:03.000Z
tags: ["cclayer", "Claude Code", "Claude Code 配置同步", "Claude Code 多设备", "Claude Code 多账号", "CLAUDE.md", "Claude Code skills", "Claude Code 插件", "Claude Code MCP", "settings.json", "git 多身份", "dotfiles"]
categories: ["技术"]
canonical: https://www.zhaojian.net/cclayer-sync-claude-code-config-across-machines/
author: 赵健
---

Claude Code 用久了，`~/.claude` 下面会积累不少东西：全局的 `CLAUDE.md`、各种 rules、skills、hooks、`settings.json` 里的权限和插件，还有一堆 MCP server。我平时在好几台电脑上用 Claude Code，每台都要重新配一遍，哪台改了点规则，别的电脑也得跟着手动改，时间一长各台的配置就对不上了。

更麻烦的是项目来自不同的团队。每个团队的 git 提交身份（用户名、邮箱）不一样，有的团队还有自己的规则和 hook，这些东西只应该在这个团队的项目里生效，不能混进别的项目，更不能把公司邮箱提交到自己的开源仓库里。

直接把 `~/.claude` 扔进 git 仓库也不行：里面有登录状态、会话历史、本机的权限设置，团队的东西又不能放进公开仓库。所以我写了 [cclayer](https://github.com/zhaojiannet/cclayer)，专门解决这个问题。

## cclayer 是什么

cclayer 把 Claude Code 的配置拆成两种「层」：

- **基础层**：每台电脑都一样的东西，`CLAUDE.md`、`rules/`、`skills/`、`output-styles/`、`agents/`、hook 脚本、`settings.json` 里共享的键、插件和 marketplace 清单、MCP 定义。里面没有任何身份信息，可以放公开仓库。
- **覆盖层**：一个团队一个，放这个团队的 git 身份、hook、仓库地址规则（比如 `github.com/acme-inc/*`），以及要写进这些项目的 `.claude/settings.local.json` 和 `CLAUDE.local.md`。覆盖层只在匹配的项目里生效，不往 `~/.claude` 写任何东西。

每台电脑只拉基础层加它需要的覆盖层，`cclayer apply` 一条命令铺好，`cclayer push` 一条命令把本机的改动传回去。

层可以是 git 仓库，也可以直接是网盘同步文件夹里的一个目录，不想碰 git 也能用。

## 安装

macOS 用 Homebrew：

```sh
brew install --cask zhaojiannet/tap/cclayer
```

以后升级：

```sh
brew upgrade --cask cclayer
```

Linux 和 Windows 到 [Releases 页面](https://github.com/zhaojiannet/cclayer/releases) 下载二进制文件。需要先装好 git；插件、MCP 这几步需要 Claude Code 2.1.288 以上。

## 最简单的用法：一个人，几台电脑

没有团队要分开的话，一个基础层就够了。

### 第一台电脑

```sh
cclayer setup
```

`setup` 是一个全屏的配置界面，左栏是各个层和本机设置，右栏是选中项的说明和可改的字段，按下保存之前不会写入任何文件。界面文字支持简体中文、英文、日文，默认跟随系统语言。

![cclayer setup 全屏配置界面截图：左栏是基础层、项目目录、本机克隆位置、自动拉取等设置，右栏是选中项说明，底部是保存并应用、只保存、退出按钮](/uploads/2026/10/cclayer-setup.png)

只需要填两项：

1. **基础层**：填一个目录（比如网盘里的 `~/Dropbox/cclayer/base`）或一个私有 git 仓库地址。目录还不存在的话，保存时会自动生成起步的 `layer.toml`。
2. **项目目录**：放代码的目录，比如 `~/Projects`。

选「保存并应用」，然后把这台电脑现有的配置收进层里：

```sh
cclayer capture --add CLAUDE.md --add rules/ --add skills/
```

路径相对 `~/.claude`。收进去之前每个文件都会先检查一遍，像密钥、邮箱、指向本机家目录的绝对路径这些会被拦下来，并告诉你在哪一行。只有自己用、层也放在私有的地方时，在 `layer.toml` 的 `[layer]` 下面加一行 `private = true`，就不再拦邮箱了。

### 其他电脑

装好 cclayer，同样跑 `cclayer setup`，基础层填同一个地址，保存并应用，第一台电脑的配置就过来了。本机已有、内容又不一样的文件会列出来问你要不要覆盖，覆盖前旧文件会备份到 `~/.local/state/cclayer/backups/`。

### 日常同步

用 git 仓库做层的话：

```sh
cclayer push          # 上传：收集本机改动，列出要提交的内容，确认后提交并推送
cclayer apply --pull  # 下载：拉取最新的层，再铺到本机
```

用网盘目录做层的话，网盘负责同步，改完跑 `cclayer capture`，另一台电脑跑 `cclayer apply` 即可。

还可以把下面这个 SessionStart hook 放进基础层的 `claude/settings.json`，再在 `setup` 里打开「自动拉取」，以后每次打开 Claude Code 会话都会自动拉取并应用：

```json
{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{ "type": "command", "command": "command -v cclayer >/dev/null && cclayer apply --hook || true" }]
    }]
  }
}
```

## 给不同团队配置不同的 git 身份

这是我写 cclayer 的主要原因。先给团队建一个私有仓库，根目录放一个 `layer.toml`，写明身份和要匹配的仓库：

```toml
[layer]
name = "acme"
kind = "overlay"

[identity]
name = "Full Name"
email = "me@acme.example"

[[match]]
remote = "github.com/acme-inc/*"
```

然后在需要的电脑上加这个覆盖层，它会问你怎么配置仓库的访问凭证，再 clone 下来检查一遍：

```sh
cclayer layer add acme git@github.com:you/cclayer-acme.git
```

`apply` 之后，cclayer 会在 `~/.gitconfig` 末尾加一个 include 块，用 git 的 `includeIf "hasconfig:remote.*.url:..."` 让这个身份只在远程地址匹配 `github.com/acme-inc/*` 的仓库里生效，`~/.gitconfig` 里原来的内容一律不动。默认身份（`default_identity`）留空时，没有任何覆盖层匹配的仓库 git 会拒绝提交，不会再出现用错邮箱提交的情况。

匹配规则必须写明主机和组织，不能用通配符代替，免得一个团队的覆盖层认领了别的团队的仓库。

如果想让每个团队的 Claude Code 登录、会话和提示词历史也完全分开，可以打开 profiles 模式，每个覆盖层会有自己的 `~/.claude-profiles/<层名>` 配置目录，`cclayer env` 输出对应的 `CLAUDE_CONFIG_DIR`，配合 direnv 就能进哪个项目用哪套配置。

## 安全方面的处理

同步过来的 hook、skills 都会在本机被 Claude Code 执行，所以 cclayer 在这方面比较谨慎：

- `hooks`、`statusLine`、`enabledPlugins` 这类会执行程序或启用插件的设置，以及 `hooks/`、`skills/` 下的文件、带执行权限的文件，写入前都会先列出内容让你确认，同一内容确认过一次后不再重复问。
- git 配置片段只放行 `pull.rebase`、`push.default` 这类常见设置，alias、`core.hooksPath`、`credential.helper` 等能执行程序的键，要在设备清单里明确信任这个层才行。
- Claude Code 的登录状态、`history.jsonl`、`projects/` 不会被读进层里，`permissions.allow`、`env` 留在本机。
- 层里不允许出现符号链接，写文件时也不会跟随符号链接。

## 常用命令

| 命令 | 作用 |
|---|---|
| `cclayer setup` | 全屏配置界面，首次配置和以后修改都用它 |
| `cclayer apply` | 把各层铺到本机，`--pull` 先拉取 |
| `cclayer capture` | 把本机改动写回层，不提交 |
| `cclayer push` | capture 后提交并推送各层仓库 |
| `cclayer check` | 检查层里有没有不该出现的内容 |
| `cclayer status` | 各层的 git 状态和匹配到的项目 |
| `cclayer keys setup <层>` | 给本机配置层仓库的访问凭证（deploy key 或 HTTPS token） |
| `cclayer layer add <名字> <地址>` | 给本机加一个覆盖层 |
| `cclayer leave <层>` | 从本机移除一个层，清掉它写过的东西 |
| `cclayer doctor` | 检查 Claude Code 和 git 的常见问题 |

更详细的用法，包括 git 仓库的建法、私有仓库的凭证、常见问题，可以看 [cclayer 中文教程](https://github.com/zhaojiannet/cclayer/blob/main/docs/tutorial.zh.md)。

GitHub 项目地址：
[https://github.com/zhaojiannet/cclayer](https://github.com/zhaojiannet/cclayer)