@perry-lx/ccfg
v1.0.0
Published
Claude Code Config Manager — 管理 Claude Code settings.json 配置预设的 CLI 工具
Maintainers
perry-lxReadme
ccfg — Claude Code Config Manager
ccfg 是一个命令行工具，用于管理 Claude Code（claude CLI）的 settings.json 配置文件。支持多配置预设的创建、切换、编辑、备份等操作，让你在不同的 AI 模型配置之间快速切换。
为什么需要 ccfg？
Claude Code 的配置文件位于 ~/.claude/settings.json。当需要在不同模型（如 DeepSeek、GLM、GPT）之间切换时，通常需要手动备份、编辑、替换这个 JSON 文件。ccfg 将这一流程自动化：
- 一键切换不同模型的配置预设
- 自动传入
--model参数，无需手动指定 - 内置备份和恢复机制，防止配置丢失
- 跨平台：Windows、macOS、Linux 均可使用
目录
安装
前置条件
- Node.js ≥ 14（通过 npm 安装时需要）
- Claude Code CLI（
claude命令，ccfg 管理的目标）
通过 npm 安装（推荐）
npm install -g @perry-lx/ccfg安装后 ccfg 命令即可全局使用。安装脚本会自动创建所需的目录结构（~/.claude/ 和 ~/.claude/backups/）。
从本地安装
# 在项目根目录执行
npm install -g .手动安装（仅 Windows，无需 Node.js）
把 ccfg.bat 所在目录添加到系统 PATH 即可。此方式不需要 Node.js 环境。
快速上手
# 1. 查看所有可用的配置预设
ccfg list
# 2. 切换到某个预设
ccfg switch deepseek
# 3. 切换并启动 Claude Code
ccfg open deepseek
# 4. 将当前配置保存为一个新预设
ccfg create my-config
# 5. 查看当前配置状态
ccfg info命令速查
| 命令 | 别名 | 简短参数 | 说明 |
|------|------|----------|------|
| ccfg list | ls | — | 列出所有配置预设 |
| ccfg show <名称> | cat | — | 查看指定配置内容 |
| ccfg switch <名称> | use | — | 切换到指定配置 |
| ccfg switch <名称> --run | use ... -r | — | 切换配置并启动 Claude Code |
| ccfg open <名称> | — | — | 切换配置并启动 Claude Code（自动传入模型参数） |
| ccfg edit <名称> | vi | — | 编辑指定配置 |
| ccfg create <名称> | new | — | 从当前设置创建新预设 |
| ccfg create <名称> --from <源> | new ... -f | — | 从已有预设创建新预设 |
| ccfg delete <名称> | rm | — | 删除指定预设 |
| ccfg rename <旧名> <新名> | mv | — | 重命名预设 |
| ccfg backup | bk | — | 备份当前 settings.json |
| ccfg backup delete <文件...> | bk delete ... | — | 删除指定备份（支持多个） |
| ccfg backup delete | bk delete | — | 删除所有备份 |
| ccfg restore <文件> | rs | — | 从备份恢复 |
| ccfg backups | bks | — | 列出所有备份 |
| ccfg diff <名称A> <名称B> | df | — | 比较两个配置预设的差异 |
| ccfg info | i | — | 查看当前配置状态概览 |
| ccfg（无参数） | — | — | 直接启动 Claude Code |
| ccfg --help | -h | — | 显示完整帮助 |
提示：
ccfg open、ccfg switch --run、ccfg（无参数）在启动 Claude Code 时会自动从配置中提取model字段并通过--model参数传入，确保打开的 Claude Code 使用正确的模型，不受上次保存的默认值影响。
使用示例
查看所有配置
$ ccfg list
[*] Available presets:
====================
Total: 3 presets
* deepseek 38 B 2026/05/18 23:42
glm 603 B 2026/05/26 17:51
gpt 1.3 KB 2026/06/01 15:49
[i] Active: deepseek带 * 标记的是当前正在使用的配置。
切换配置
# 切换到 glm 配置
ccfg switch glm
# 切换到 gpt 配置并立即启动 Claude Code
ccfg switch gpt --run
# 使用别名（等价于上面的命令）
ccfg use deepseek
ccfg use glm -r # -r 等于 --run一键切换并启动
# 切换配置并启动 Claude Code（自动传入模型参数）
ccfg open deepseek
ccfg open glm
# 直接启动 Claude Code（使用当前配置，自动传入模型参数）
ccfg查看配置内容
$ ccfg show deepseek
========================================================
Preset: deepseek
File: /Users/用户名/.claude/settings.json.deepseek
========================================================
{
"model": "deepseek-v4-flash"
}
========================================================创建配置预设
# 从当前 settings.json 创建新预设
ccfg create my-config
# 从已有预设复制创建
ccfg create my-config --from deepseek
# 强制覆盖已存在的预设
ccfg create my-config --from glm --force编辑配置
# 使用系统默认编辑器
# Windows → 记事本
# macOS/Linux → $EDITOR 或 vim（保存退出后自动验证 JSON 格式）
ccfg edit glm比较配置差异
$ ccfg diff deepseek glm
[*] Comparing: deepseek <-> glm
====================
[+] env:
- [deepseek]: (not present)
- [glm]: {"ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/paas/v4"}
[+] model:
- [deepseek]: "deepseek-v4-flash"
- [glm]: "opus"JSON 结构化对比，清晰展示两个预设之间每个字段的差异。
备份与恢复
# 备份当前 settings.json（自动生成带时间戳的文件名）
ccfg backup
# 查看所有备份
ccfg backups
# 从备份恢复
ccfg restore settings_backup_deepseek_20260601_120000.json
# 删除指定备份（支持同时删除多个）
ccfg backup delete settings_backup_deepseek_20260601_120000.json
ccfg backup delete settings_backup_1.json settings_backup_2.json
# 删除所有备份（会弹出交互式确认）
ccfg backup delete查看配置状态
$ ccfg info
[*] Claude Code Config Status
====================
Config dir: /Users/用户名/.claude
settings.json: exists (38 B, 2026/05/18 23:42)
Active preset: deepseek
Available: 3 presets
Backups: 2 files
Preset list:
* deepseek
glm
gpt配置目录
ccfg 的配置文件存储在以下位置：
| 操作系统 | 路径 |
|----------|------|
| Windows | %USERPROFILE%\.claude\ |
| macOS / Linux | ~/.claude/ |
目录结构：
~/.claude/
├── settings.json # 当前活动的配置文件
├── settings.json.deepseek # 预设：deepseek
├── settings.json.glm # 预设：glm
├── settings.json.gpt # 预设：gpt
├── backups/
│ ├── settings_backup_deepseek_20260601_120000.json
│ └── ...命名规则
| 文件 | 规则 | 示例 |
|------|------|------|
| 预设文件 | settings.json.<名称> | settings.json.deepseek |
| 备份文件 | settings_backup_<预设名>_<时间戳>.json | settings_backup_deepseek_20260601_120000.json |
| 临时备份 | settings.json.bak | 切换预设时自动生成 |
配置文件格式
settings.json 是标准的 JSON 文件。以下是一些常见的配置项：
{
"model": "模型名称",
"env": {
"ANTHROPIC_BASE_URL": "自定义 API 地址",
"ANTHROPIC_AUTH_TOKEN": "认证令牌"
},
"permissions": {
"allow": [],
"deny": [],
"defaultMode": "bypassPermissions"
},
"skipDangerousModePermissionPrompt": true,
"theme": {
"name": "theme-name"
}
}完整配置项请查阅 Claude Code 官方文档。
跨平台支持
ccfg 提供两种运行方式：
| 入口 | 平台 | 依赖 | 说明 |
|------|------|------|------|
| bin/ccfg.js | Windows / macOS / Linux | Node.js ≥ 14 | 跨平台版本（推荐，通过 npm 安装时自动使用） |
| ccfg.bat | Windows 仅 | 无 | 纯批处理脚本，无需任何运行时 |
npm 包的 bin 入口指向 bin/ccfg.js，通过 npm 安装可在所有平台上使用。
文件结构
ccfg/
├── bin/
│ └── ccfg.js # Node.js CLI 入口（跨平台）
├── src/
│ └── ccfg.js # 核心模块（所有命令实现）
├── ccfg.bat # 纯批处理版本（Windows）
├── postinstall.js # npm 安装后自动配置脚本
├── package.json # npm 包配置
├── .npmignore # npm 发布排除配置
├── LICENSE # MIT 许可证
└── README.md # 本文档常见问题
ccfg open / switch --run 没有启动 Claude Code？
检查你是否从 npm 全局安装了最新版本。之前存在一个 bug（spawn 异步导致主进程提前退出），已在 v1.0.0 中修复：
npm uninstall -g @perry-lx/ccfg
npm install -g @perry-lx/ccfg如果问题依旧，尝试直接运行 claude --version 确认 Claude Code 已正确安装并在 PATH 中。
中文显示乱码？
在 Windows CMD 中正常运行即可。如果使用 Git Bash 等环境，请确保终端编码为 UTF-8。
切换后 Claude Code 配置不生效？
Claude Code 在启动时读取 settings.json，切换配置后需要重启 Claude Code 才能生效。推荐使用：
ccfg switch <名称> -r— 切换配置并自动启动 Claude Codeccfg open <名称>— 切换配置并自动启动（自动传入--model参数）ccfg（无参数）— 直接启动 Claude Code（也会自动传入当前配置的模型参数）
没有 Node.js 环境怎么办？
可以直接使用 ccfg.bat（仅 Windows），它不依赖 Node.js。将 ccfg.bat 所在目录添加到系统 PATH 即可。
ccfg backup delete 命令如何确认？
删除单个备份时会逐文件确认。删除所有备份时会弹出一个交互式确认提示（[y/N]），输入 y 或 yes 确认后才执行删除。
卸载
npm uninstall -g @perry-lx/ccfg卸载后，ccfg 命令将不再可用。已创建的配置预设和备份文件（位于 ~/.claude/）不会被删除。
从源码构建
git clone https://github.com/Perry-LX/ccfg.git
cd ccfg
npm install -g .
# 即可全局使用 ccfg 命令License
MIT