claude code离线模式多设备配置同步

Claude Code 完整配置与维护教程

适用设备：Ubuntu 无桌面服务器 / Ubuntu 桌面版 / macOS
配置仓库：https://github.com/luduihang/claude-code-config

---

目录

1. 新设备从零配置
2. 日常使用
3. 添加新供应商/模型
4. 管理 Skills
5. 管理 MCP 服务器
6. 跨设备同步
7. 更新与维护
8. 故障排查
9. 文件结构速查

---

使用 Claude Code 做开发，但 Claude Code 的 API 调用不是免费的——需要接入第三方供应商的
API（DeepSeek、MiniMax），每个供应商的接入地址、模型名、认证方式都不一样。同时我还有三台设备（Ubuntu 服务器、Ubuntu桌面、Mac），每台都要配一遍。

遇到的问题

1. 重复配置地狱 — 每台新设备都要手动编辑 settings.json、配环境变量、改 .claude.json 绕过登录，步骤繁琐且容易出错
2. 渠道切换麻烦 — 想从 DeepSeek 换到 MiniMax，要手动改一堆环境变量，记不住参数
3. 配置无法同步 — 设备 A 配好了新模型或新 Skill，设备 B 和 C 还得手动再配一遍
4. 密钥管理混乱 — API Key 散落在 settings.json、环境变量、脚本里，不知道哪些该提交、哪些不该提交，安全风险大
5. Skills 无法共享 — 自定义的 Skill（比如语音转写规整）写完只能一台设备用

这套方案解决了什么：

之前	之后
新设备手动配 30 分钟	4 条命令 2 分钟搞定
切换渠道要改一堆变量	cc-switch ds-pro 一行
三台设备各自维护配置	GitHub 仓库统一管理，cc-switch update 一键同步
密钥和配置混在一起	密钥在 ~/.claude/secrets/ 本地隔离，配置在仓库安全共享
加新模型要改脚本代码	编辑 models.conf 加几行配置，脚本不动
Skill 只在一台设备	仓库 skills/ 目录统一管理，全设备自动安装
新设备 “not log in” 报错	install.sh 自动处理 .claude.json

本质上就是把 Claude Code 的配置从”每台设备手动维护”变成了”基础设施即代码”——配置写一次，到处复用。

一、新设备从零配置

1.1 前置准备

# 安装 Node.js（Ubuntu）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 Node.js（macOS）
brew install node

1.2 配置 GitHub SSH 密钥

# 生成密钥（一路回车）
ssh-keygen -t ed25519 -C "kipleytaylor11@gmail.com"

# 显示公钥，复制全部内容
cat ~/.ssh/id_ed25519.pub

将公钥添加到 GitHub：https://github.com/settings/ssh/new

1.3 安装 Claude Code

npm install -g @anthropic-ai/claude-code

1.4 克隆配置仓库并一键部署

git clone git@github.com:luduihang/claude-code-config.git ~/claude-code-config
cd ~/claude-code-config
./install.sh

1.5 配置 API 密钥

# DeepSeek 密钥
cat > ~/.claude/secrets/deepseek.env << 'EOF'
ANTHROPIC_API_KEY=sk-你的DeepSeek密钥
EOF

# MiniMax 密钥
cat > ~/.claude/secrets/minimax.env << 'EOF'
ANTHROPIC_AUTH_TOKEN=sk-你的MiniMax密钥
EOF

# 设置安全权限
chmod 600 ~/.claude/secrets/*.env

1.6 使配置生效并验证

source ~/.bashrc       # Ubuntu
# source ~/.zshrc      # macOS

cc-switch list         # 查看所有可用渠道
cc-switch ds-pro       # 切换到 DeepSeek V4 Pro
cc-switch test         # 测试 API 连通性

claude                 # 启动 Claude Code

---

二、日常使用

2.1 渠道切换命令

命令	说明
cc-switch ds-pro	切换到 DeepSeek V4 Pro（主力）
cc-switch ds-flash	切换到 DeepSeek V4 Flash（快速）
cc-switch mm-m3	切换到 MiniMax M3
cc-switch mm-m2.7	切换到 MiniMax M2.7
cc-switch status	查看当前渠道和环境变量
cc-switch test	测试当前渠道 API 连通性
cc-switch list	列出所有可用供应商
cc-switch update	一键同步最新配置（拉取仓库 + 合并设置 + 安装 Skills）

注意：切换后环境变量立即生效，无需手动 source ~/.bashrc。

2.2 调用 Skills

# 在 Claude Code 对话中
/voice-text-normalize

然后粘贴需要规整的语音转写文本。

---

三、添加新供应商/模型

3.1 方式一：永久添加（同步到所有设备）

步骤 1：编辑仓库中的 models.conf

cd ~/claude-code-config
nano models.conf

添加新 section：

[新供应商ID]
name=供应商显示名称
base_url=https://api.新供应商.com/anthropic
auth_type=api_key            # api_key 或 auth_token
secret_file=新供应商.env      # 对应 ~/.claude/secrets/ 中的文件名
model=模型名称
sonnet_model=模型名称
haiku_model=模型名称
subagent_model=模型名称

步骤 2：提交并推送

git add models.conf
git commit -m "添加新供应商: 新供应商ID"
git push

步骤 3：在每个设备上创建密钥文件

echo "ANTHROPIC_API_KEY=sk-你的密钥" > ~/.claude/secrets/新供应商.env
chmod 600 ~/.claude/secrets/新供应商.env

步骤 4：在其他设备上同步

cc-switch update    # 一键拉取 + 合并

3.2 方式二：仅当前设备（本地覆盖）

nano ~/.claude/secrets/models.local.conf

[本地专属]
name=本地测试模型
base_url=http://localhost:8080/anthropic
auth_type=api_key
secret_file=local.env
model=local-model
sonnet_model=local-model
haiku_model=local-model
subagent_model=local-model

创建对应密钥文件：

echo "ANTHROPIC_API_KEY=sk-xxx" > ~/.claude/secrets/local.env
chmod 600 ~/.claude/secrets/local.env

此配置仅在当前设备生效，不会被提交到 Git。

---

四、管理 Skills

4.1 添加自定义 Skill

步骤 1：在仓库 skills/ 目录创建 .md 文件

cd ~/claude-code-config/skills
nano 你的skill名称.md

Skill 文件格式（必须有 YAML 前置元数据）：

---
name: your-skill-name
description: 简短描述这个 Skill 的功能
---

# Skill 标题

## 使用方式
/your-skill-name

## 规则内容
...

步骤 2：提交推送

cd ~/claude-code-config
git add skills/你的skill名称.md
git commit -m "添加 Skill: 你的skill名称"
git push

步骤 3：当前设备安装

cc-switch update

步骤 4：其他设备同步

cc-switch update    # 自动拉取并安装新 Skills

4.2 更新已有 Skill

cd ~/claude-code-config
nano skills/voice-text-normalize.md    # 编辑内容
git add skills/
git commit -m "更新 Skill: voice-text-normalize"
git push

其他设备：cc-switch update

4.3 删除 Skill

cd ~/claude-code-config
git rm skills/要删除的skill.md
git commit -m "删除 Skill: xxx"
git push

其他设备：cc-switch update（注意：需要手动删除 ~/.claude/skills/ 中的旧文件）

---

五、管理 MCP 服务器

5.1 添加 MCP 服务器（无需密钥）

编辑 claude-settings.json：

cd ~/claude-code-config
nano claude-settings.json

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}

提交推送后，其他设备 cc-switch update 即可。

5.2 添加 MCP 服务器（需要密钥）

在 claude-settings.json 中使用 ${SECRETS:...} 占位符：

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["@anthropic/mcp-supabase"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "${SECRETS:mcp/supabase.env:SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

然后在每台设备上创建密钥文件：

mkdir -p ~/.claude/secrets/mcp
echo "SUPABASE_ACCESS_TOKEN=你的密钥" > ~/.claude/secrets/mcp/supabase.env
chmod 600 ~/.claude/secrets/mcp/supabase.env
cc-switch update

---

六、跨设备同步

6.1 同步机制

设备 A（修改配置）
  │
  ├── 编辑 models.conf / skills / claude-settings.json
  ├── git commit && git push
  │
  ▼
GitHub 私有仓库
  │
  ▼
设备 B / C（拉取配置）
  │
  ├── cc-switch update     ← 一条命令
  │     ├── git pull
  │     ├── 合并 settings.json
  │     ├── 初始化 .claude.json
  │     └── 安装 Skills
  │
  ▼
配置同步完成 ✅

6.2 哪些同步，哪些不同步

同步（GitHub）	不同步（本地）
cc-switch.sh	~/.claude/secrets/*.env（API 密钥）
models.conf	~/.claude/secrets/models.local.conf
claude-settings.json（MCP/权限）	~/.claude/settings.local.json
skills/*.md	~/.claude.json（应用状态）
install.sh	~/.claude_code_env（当前渠道状态）

6.3 密钥跨设备传输

方法一：scp（推荐）

# 从旧设备发送到新设备
scp -r ~/.claude/secrets/ user@新设备IP:~/.claude/secrets/

方法二：手动创建

在新设备上按照 1.5 节手动创建 .env 文件。

---

七、更新与维护

7.1 日常更新同步

cc-switch update

这一条命令完成：

• 拉取仓库最新版本
• 合并 settings.json（保留本地 env 块）
• 安装/更新 Skills 到 ~/.claude/skills/
• 确保 .claude.json onboarding 状态正确

7.2 更新 install.sh 自身

install.sh 更新后，只需 git pull，下次运行 ./install.sh 或 cc-switch update 时自动使用最新版本。

7.3 完全重新部署

cd ~/claude-code-config
git pull
./install.sh        # 幂等，安全重复运行
source ~/.bashrc

7.4 轮换 API 密钥

# 直接编辑密钥文件
nano ~/.claude/secrets/deepseek.env
# 替换为新密钥，保存

# 重新切换使新密钥立即生效
cc-switch ds-pro
cc-switch test

---

八、故障排查

8.1 cc-switch 命令未找到

# 确认 rc 文件中包含 source 命令
grep "cc-switch" ~/.bashrc    # Ubuntu
grep "cc-switch" ~/.zshrc     # macOS

# 如果没有，手动添加
echo 'source ~/claude-code-config/cc-switch.sh' >> ~/.bashrc
echo 'source ~/.claude_code_env 2>/dev/null' >> ~/.bashrc
source ~/.bashrc

8.2 API 测试失败

# 检查当前配置
cc-switch status

# 检查密钥文件是否存在且有内容
ls -la ~/.claude/secrets/
cat ~/.claude/secrets/deepseek.env

# 确保密钥文件权限正确
chmod 600 ~/.claude/secrets/*.env

# 重新切换并测试
cc-switch ds-pro
cc-switch test

8.3 启动 Claude Code 显示 “not log in”

# 运行 update 模式自动修复
./install.sh --update

# 或手动创建
echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

8.4 Skill 不显示

# 确保 skill 已安装到正确的目录
ls -la ~/.claude/skills/

# 如果没有，重新运行同步
cc-switch update

# 或手动复制
cp ~/claude-code-config/skills/*.md ~/.claude/skills/

8.5 Git 操作失败

# 测试 SSH 连接
ssh -T git@github.com

# 确认远程仓库地址
cd ~/claude-code-config
git remote -v
# 应显示: git@github.com:luduihang/claude-code-config.git

---

九、文件结构速查

新设备完整文件布局
────────────────────────────────────────────────────────

~/claude-code-config/          ← GitHub 仓库（git pull/push 同步）
├── install.sh                 ← 一键部署/更新脚本
├── cc-switch.sh               ← 渠道切换 Shell 函数
├── models.conf                ← 供应商配置（改这里加模型）
├── claude-settings.json       ← 共享设置（MCP/权限/Hooks）
├── skills/                    ← 自定义 Skills
│   └── voice-text-normalize.md
└── .gitignore

~/.claude/secrets/             ← 本地密钥（永不提交，手动传输）
├── deepseek.env               ← DeepSeek API Key
├── minimax.env                ← MiniMax API Key
├── models.local.conf          ←（可选）本地模型覆盖
└── mcp/                       ← MCP 密钥
    └── xxx.env

~/.bashrc（末尾 2 行，由 install.sh 自动添加）
  source ~/claude-code-config/cc-switch.sh
  source ~/.claude_code_env 2>/dev/null

~/.claude/
├── settings.json              ← 运行时配置（由 install.sh 生成）
├── skills/                    ← 已安装的 Skills（由 install.sh 复制）
│   └── voice-text-normalize.md
├── settings.local.json        ←（可选）设备本地覆盖
├── .claude.json               ← 应用状态（含 onboarding 标记）
└── plugins/                   ← 插件市场安装的内容

---

快速命令参考

# 部署
git clone git@github.com:luduihang/claude-code-config.git ~/claude-code-config
cd ~/claude-code-config && ./install.sh

# 日常
cc-switch ds-pro          # 切换渠道
cc-switch test            # 测试连通
cc-switch update          # 同步配置

# 新增模型
vim ~/claude-code-config/models.conf    # 编辑配置
git add -A && git commit -m "..." && git push

# 新增 Skill
vim ~/claude-code-config/skills/xxx.md  # 编写 Skill
git add -A && git commit -m "..." && git push
cc-switch update                        # 本机安装

# 轮换密钥
vim ~/.claude/secrets/deepseek.env

---

转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 kipleyarch@gmail.com