cc-switch 使用教程

Q: 问题：CC Switch 是什么？它支持哪些 AI 命令行工具？

CC Switch 是一款跨平台桌面全能助手，用于集中管理多个 AI 命令行工具。它支持 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes Agent，让你在一个界面中切换和调用这些工具，无需手动配置多个终端环境。 ---

Q: 问题：安装 CC Switch 时提示“无法找到依赖”或“安装失败”，怎么办？

常见原因包括： 系统未安装 Node.js（版本 ≥ 18）：请先安装 Node.js 并确保 node -v 输出正确版本。 缺少 Git：部分工具（如 Claude Code）需要 Git 支持，请安装 Git 并配置环境变量。 权限问题：在 macOS/Linux 上尝试 sudo npm install -g cc-switch，或使用包管理器（如 Homebrew）安装。 网络问题：如果下载依赖超时，可尝试设置 npm 镜像：npm config set registry https://registry.npmmirror.com。 ---

Q: 问题：为什么 CC Switch 无法识别我安装的 Codex 或 OpenCode？

可能原因： 工具未添加到系统 PATH：确保工具安装后，其可执行文件所在目录已加入 PATH（Windows 需重启终端）。 版本不兼容：CC Switch 要求 Codex ≥ 1.2.0、OpenCode ≥ 0.5.0，请更新工具版本。 手动指定路径：在 CC Switch 设置中，直接输入工具完整路径（如 C:\Users\用户名\AppData\Local\Codex\codex.exe）。 ---

Q: 问题：CC Switch 和直接使用终端运行 Claude Code 有什么区别？

统一管理：CC Switch 提供图形界面，可同时管理多个工具，无需在多个终端窗口间切换。 快速切换：一键切换当前使用的 AI 工具，无需重新输入命令或配置环境变量。 日志与监控：内置会话历史、输出日志和资源占用监控，方便调试和对比不同工具的表现。 跨平台：Windows、macOS、Linux 界面一致，减少系统差异带来的配置麻烦。 ---

Q: 问题：使用 CC Switch 时，如何解决“工具响应超时”或“连接断开”？

检查网络：确保电脑能正常访问互联网（部分工具如 Gemini CLI 需要稳定网络）。 更新工具：运行 claude --version 或 gemini --version，确认工具版本为最新。 重启 CC Switch：关闭程序后重新启动，有时能解决临时连接问题。 查看日志：在 CC Switch 设置中开启“调试日志”，日志文件通常位于 ~/.cc-switch/logs/，可提供具体错误信息。 ---

Q: 问题：CC Switch 与其他类似工具（如 Ollama、LM Studio）相比有什么优势？

专注命令行 AI 工具：CC Switch 专门针对 Claude Code、Codex、Gemini CLI 等命令行工具优化，而非通用模型运行器。 多工具并行：支持同时连接多个不同厂商的工具，并在它们之间快速切换，适合对比测试或混合使用。 轻量级：不依赖本地模型下载，仅作为管理界面，资源占用低。 官方支持：唯一官方网站为 ccswitch.io，提供持续更新和社区支持。

📌 本文速覽

cc-switch 是一款跨平台桌面助手，用于统一管理和切换 Claude Code、Codex、OpenCode 等 AI 命令行工具。本教程将带你从安装到实战，快速掌握如何用它提升开发效率。

🎯 入门📖 10 章⏱ ≈91 分鐘讀完🔄 更新於 2026-06-30

源專案：github.com/farion1231/cc-switch★ 107,553

1. 认识 cc-switch：它能解决什么问题？

好嘞，咱们直接开聊。

你有没有遇到过这种情况：电脑上装了 Claude Code、Codex、OpenCode 好几个 AI 命令行工具，每个都有自己的启动方式、配置文件和快捷键。今天想用 Claude 写个文档，明天想用 Codex 改个 bug，结果光在终端里切来切去就花了五分钟，还经常记错命令参数。

这就是 cc-switch 要帮你解决的——它就像一个 AI 工具的“遥控器”，让你不用再跟每个工具的启动命令、配置文件、快捷键较劲。你只需要告诉它“我要用 Claude”，它就能帮你把环境、目录、上下文都准备好，然后直接启动。

为什么你需要它？

想象一下，你正在写一个 React 项目，突然想换个 AI 助手试试。没有 cc-switch 的时候，你得：

关掉当前终端
打开另一个终端
输入 claude 或者 codex 之类的命令
等它加载完
重新设置工作目录

有了 cc-switch，你只需要按一个快捷键，或者敲一个命令，它就能帮你完成上面所有步骤。而且它还能记住你上次用哪个工具、在哪个目录，下次直接恢复现场。

它能做什么？

简单来说，cc-switch 帮你搞定三件事：

统一管理：把你电脑上所有 AI 命令行工具（Claude Code、Codex、OpenCode、Gemini CLI 等）都集中到一个地方。你不需要记住每个工具的安装路径、启动参数，cc-switch 帮你管着。
一键切换：想从 Claude 切到 Codex？按个快捷键，或者敲个 cc-switch codex 就行。它会自动关闭当前工具，启动新的，并且保持你当前的工作目录。
上下文记忆：它记得你上次用哪个工具、在哪个项目目录。下次打开电脑，直接就能接着干，不用重新配置。

一个真实场景

假设你是个全栈开发者，早上用 Claude Code 写后端 API，下午用 Codex 改前端样式。没有 cc-switch 的时候，你可能会：

在终端里敲 claude 启动，发现它默认进了上次的项目
然后手动 cd 到另一个项目目录
再重新设置上下文

有了 cc-switch，你只需要：

早上：cc-switch claude（它会自动进入你上次的后端项目）
下午：cc-switch codex（它会自动切换到前端项目，并保持你上次的对话上下文）

它不做什么？

cc-switch 不是 AI 工具本身，它只是个“管家”。它不会帮你写代码、不会帮你调试 bug，它只负责帮你把 AI 工具准备好，让你能更快地开始干活。

谁适合用？

如果你电脑上装了 2 个以上 AI 命令行工具
如果你经常在不同项目之间切换 AI 助手
如果你觉得每次启动 AI 工具都要敲一堆命令很烦
如果你想让 AI 工具记住你上次的工作状态

那 cc-switch 就是为你准备的。

接下来做什么？

下一章我们会教你下载安装，大概 3 分钟就能搞定。安装完之后，你就能看到 cc-switch 的界面，然后我们会在第 3 章带你 5 分钟跑通第一个 AI 助手切换。

别担心，整个过程很简单，你不需要懂任何编程知识。跟着步骤走就行。

2. 下载与安装：Windows / macOS / Linux 三步搞定

好嘞，咱们直接进入正题。上一章我们聊了 cc-switch 到底能帮你省多少事，现在该动手了。别担心，安装这事儿比装个手机 App 还简单，我保证你五分钟内就能跑起来。

第 2 章：下载与安装：Windows / macOS / Linux 三步搞定

为什么这一章很重要？

你想想，再厉害的瑞士军刀，没打开之前也就是块铁疙瘩。cc-switch 也一样，装好了它才能帮你管理那些 AI 助手。而且不同系统装法略有不同，咱们一次说清楚，省得你后面卡壳。

开始前，你需要确认的事

你的电脑能正常上网（废话，不然你怎么看到这教程的）
系统是 Windows 10/11、macOS 10.15+ 或者 Linux（Ubuntu 20.04+、CentOS 7+ 等主流发行版都行）
如果你用 Linux，最好有 curl 或 wget 命令（一般系统都自带）

第一步：找到下载入口

最靠谱的渠道就是项目官网：ccswitch.io。打开后你会看到一个很清爽的页面，上面有个大大的「Download」按钮。别犹豫，点它。

如果你更喜欢命令行操作，也可以直接去项目的 GitHub Releases 页面（地址在官网底部有链接），那里有所有历史版本。不过咱们新手，用官网下载最新版最省心。

第二步：根据你的系统选对安装包

官网会根据你访问的设备自动推荐版本，但为了保险，咱们手动确认一下：

Windows 用户：下载 .exe 或 .msi 文件。推荐 .exe，双击就能跑。
macOS 用户：下载 .dmg 文件。如果你用的是 Apple Silicon（M1/M2/M3）芯片，注意选 arm64 版本；Intel 芯片选 x64 版本。搞混了也能装，但运行效率会打折扣。
Linux 用户：下载 .AppImage 文件。这个格式的好处是免安装，下载后直接就能用，对新手特别友好。

小提示：如果你在 macOS 上双击 .dmg 后提示「无法验证开发者」，别慌。去「系统设置」→「隐私与安全性」里，找到被拦截的软件，点「仍要打开」就行。这是苹果的安全机制在保护你，不是软件有问题。

第三步：安装（真的就三步）

Windows 用户

双击下载好的 cc-switch-x.x.x-win-x64.exe
如果弹出「Windows 保护了你的电脑」，点「更多信息」→「仍要运行」
安装向导会一路 Next，建议把安装路径保持默认，省得后面找不到
安装完成后，桌面上会出现一个图标，双击打开

预期结果：你会看到一个简洁的窗口，顶部有个搜索框，下面空空的。这就对了，说明安装成功。

macOS 用户

双击 .dmg 文件，会弹出一个窗口，里面有个 cc-switch 图标和一个「Applications」文件夹的快捷方式
把 cc-switch 图标拖进「Applications」文件夹
去「启动台」或「应用程序」里找到它，双击打开

预期结果：第一次打开可能会弹个对话框问你是否确认打开，点「打开」就行。之后你会看到和 Windows 一样的界面。

常见报错：如果双击后闪一下就没了，很可能是权限问题。去「系统设置」→「隐私与安全性」→「辅助功能」里，把 cc-switch 勾上。它需要这个权限来监听全局热键。

Linux 用户

打开终端，进入下载目录（一般是 ~/Downloads）

给 .AppImage 文件加上执行权限：

chmod +x cc-switch-x.x.x-x86_64.AppImage

直接运行它：
```
./cc-switch-x.x.x-x86_64.AppImage
```

预期结果：终端里会输出一些启动日志，然后界面就弹出来了。如果没弹出来，检查一下终端有没有报错。

实用技巧：每次都要进终端运行太麻烦？你可以把 .AppImage 文件放到一个固定目录（比如 ~/Applications），然后创建一个桌面快捷方式。或者用 ln -s 软链接到 /usr/local/bin，这样在终端里直接输 cc-switch 就能启动。

安装后第一件事：验证一下

不管哪个系统，安装完成后，先做这个操作：

打开 cc-switch
你会看到界面左下角有个齿轮图标（设置）
点进去，看看「版本号」那一栏是不是显示了你下载的版本

如果版本号正常显示，恭喜你，安装成功了！接下来就可以进入下一章，开始添加你的第一个 AI 助手了。

万一翻车了怎么办？

Windows 上安装到一半卡住：多半是杀毒软件在捣乱。暂时关掉实时防护，装完再开。
macOS 上拖不进 Applications：检查一下磁盘空间是不是满了。
Linux 上双击没反应：确认你下载的是 .AppImage 而不是源码包。另外有些发行版需要先装 fuse 库，用包管理器装一下就行：
```
sudo apt install fuse  # Ubuntu/Debian
sudo yum install fuse  # CentOS/RHEL
```

好了，现在你的电脑上已经有了 cc-switch 这个利器。下一章我们就要让它真正干活了——5 分钟跑通第一个 AI 助手切换，到时候你会觉得这安装过程简直不值一提。

3. 5 分钟跑通第一个 AI 助手切换

好嘞，咱们直接进入正题。这一章的目标特别简单：让你在 5 分钟内，亲手用 cc-switch 把一个 AI 助手从“待命”变成“干活”。你不需要理解什么复杂的概念，也不用管背后是怎么实现的，咱们就照着步骤来，跑通一次，你就知道这东西到底有多顺手了。

在开始之前，确保你已经完成了上一章（第 2 章）的安装。 也就是说，你的电脑上已经装好了 cc-switch，并且能在终端里敲 cc-switch 或者 ccs（看你安装时选的别名）不报错。如果你还没装，先回去搞定它，很快的。

好，我们开始。

第一步：看一眼你的“工具箱”

打开你的终端（Terminal），直接敲下面这个命令：

ccs list

（如果你安装时用的是 cc-switch，那就敲 cc-switch list，效果一样。）

按下回车后，你会看到类似这样的输出：

Available tools:
  - claude (not configured)
  - codex (not configured)
  - opencode (not configured)

别慌，看到 not configured 是正常的。这就像你刚买了一个工具箱，里面有几个空位，但还没放工具进去。ccs list 就是让你看一眼，cc-switch 默认认识哪些 AI 助手——Claude Code、Codex、OpenCode 这些都在名单上。

预期结果： 屏幕上列出了几个名字，后面都跟着 (not configured)。这说明 cc-switch 已经安装成功，并且能正常读取它的配置了。

第二步：告诉 cc-switch 你的 AI 助手在哪

现在我们要做一件关键的事：把其中一个 AI 助手“注册”到 cc-switch 里。说白了，就是告诉它：“嘿，我的 Claude Code 放在这个路径下，你帮我记住。”

假设你电脑上已经装好了 Claude Code（如果你还没装，可以先装一个，或者换成你有的其他工具，比如 Codex，步骤完全一样）。我们先用 Claude Code 来演示。

在终端里敲：

ccs add claude

敲完回车，cc-switch 会进入一个交互模式，问你几个问题。别紧张，它问什么你答什么就行。

第一个问题通常是：

Enter the path to the claude executable (or leave blank to search PATH):

这里的意思是：Claude Code 的可执行文件在哪儿？ 如果你已经把 Claude Code 装到了系统 PATH 里（比如用 npm 全局安装的），那直接按回车跳过就行，cc-switch 会自动去 PATH 里找。如果你知道具体路径，比如 /usr/local/bin/claude，那就直接输入路径再回车。

第二个问题可能是：

Give this instance a name (default: claude):

这是让你给这个实例起个名字。如果你只打算用一个 Claude Code，直接按回车用默认名 claude 就行。如果你以后想装多个不同版本的 Claude Code，可以在这里起个有辨识度的名字，比如 claude-v2 或 claude-work。

预期结果： 命令执行完后，没有任何报错信息，终端回到正常的提示符。这就表示注册成功了。

第三步：验证一下，它真的被记住了

再跑一次 ccs list：

ccs list

这次输出应该变了：

Available tools:
  - claude (ready)
  - codex (not configured)
  - opencode (not configured)

看到 claude 后面变成了 (ready) 吗？这就是关键信号——cc-switch 已经知道你的 Claude Code 在哪，并且随时可以启动它了。

常见小问题： 如果还是 (not configured)，说明上一步的 add 命令没成功。检查一下你输入的路径对不对，或者 Claude Code 是不是真的装好了。可以试试在终端里直接敲 claude --version，如果能正常输出版本号，那说明 Claude Code 本身没问题，问题出在 add 这一步的路径上。

第四步：真正切换一次，感受一下

现在，我们来干点实际的——用 cc-switch 启动 Claude Code。

在终端里敲：

ccs use claude

就这么简单。敲完回车，你会看到终端里开始加载 Claude Code 的界面，就像你直接敲 claude 命令一样。区别在于：你现在是通过 cc-switch 这个“遥控器”来启动它的。以后你想切换到 Codex 或者 OpenCode，只需要把命令里的 claude 换成对应的名字就行，比如 ccs use codex。

预期结果： Claude Code 正常启动，你可以开始跟它对话了。如果它报错说找不到命令，那说明 Claude Code 本身的环境有问题，跟 cc-switch 无关。你可以先退出，在终端里直接敲 claude 试试，看能不能正常启动。

第五步：切回来，再切过去

现在，退出 Claude Code（按 Ctrl+C 或者输入 /exit 之类的退出命令），回到终端。

然后，我们再试一次切换，这次换个花样。假设你之前也注册了 Codex（步骤跟第二步一样），那你可以试试：

ccs use codex

瞬间，你的终端就从 Claude Code 切换到了 Codex。整个过程不需要你手动去翻文件夹、改环境变量、或者记住一堆路径。 这就是 cc-switch 的核心价值：一个命令，切换所有。

一个贴近真实场景的小例子

想象一下这个场景：你上午在写一个 Python 后端项目，用的是 Claude Code 来帮你写代码。下午要改一个前端页面，你发现 Codex 对 React 更熟悉。以前你得关掉一个终端，再开一个，或者手动切换目录、改配置。现在呢？

在 Claude Code 的终端里，退出对话。
敲 ccs use codex。
Codex 启动，直接开始干活。

前后不到 10 秒。 而且 cc-switch 还会记住你上次用的是哪个工具，下次你打开终端，它默认就会启动你最后用的那个。

如果你遇到了问题

ccs 命令找不到？ 检查一下安装时有没有把 cc-switch 加到 PATH 里。可以试试重新安装，或者用完整路径运行（比如 ./cc-switch）。
ccs add 之后还是 not configured？ 可能是路径写错了，或者那个 AI 工具本身就没装好。先确保你能在终端里直接运行那个工具（比如 claude --version），然后再试一次 add。
ccs use 之后没反应？ 看看终端有没有报错信息。最常见的原因是那个工具的可执行文件权限不对，或者依赖缺失。用 ccs list 确认一下状态是不是 ready。

好了，到这里，你已经成功跑通了第一个 AI 助手切换。整个过程应该不超过 5 分钟，对吧？下一章我们会聊怎么添加更多工具，以及怎么管理它们——到时候你会发现，cc-switch 的“工具箱”远比你想象的大。

4. 添加与管理多个 AI 工具实例

好了，咱们继续。上一章你体验了一把“一键切换”的快感，感觉是不是挺爽的？但现实是，你电脑里可能不止一个AI助手——比如你既想用Claude Code写长文，又想用Codex快速补全代码，甚至还想试试OpenCode的新功能。这时候，cc-switch的真正威力就来了：它不只是一个“开关”，更是一个“工具库”，让你像管理手机App一样，轻松添加、配置和切换多个AI实例。

这一章，我们就来手把手教你如何把各种AI工具“塞”进cc-switch，然后像玩魔方一样随意组合它们。

前置条件

在开始之前，确保你已经完成了上一章（第3章）的内容，也就是已经成功跑通了第一个AI助手切换。简单来说，你的cc-switch应该已经能正常启动，并且至少有一个AI工具（比如Claude Code）能正常工作。如果你还没搞定，先回去把那个“5分钟”的流程走一遍，别急着跳级。

第一步：添加第一个“新朋友”——以Codex为例

假设你已经在电脑上装好了Codex（如果没装，先去官网装一下，很简单）。现在，我们要把它注册到cc-switch里。

打开cc-switch的主界面。通常你可以在系统托盘或菜单栏找到它的图标，点击一下就能看到主窗口。如果没看到，试试快捷键（默认是Ctrl+Shift+Space，具体看你的设置）。
找到“添加工具”的入口。在主界面上，通常会有一个大大的“+”号按钮，或者一个写着“添加新工具”的菜单项。点击它。
填写工具信息。这时候会弹出一个对话框，让你填写几个关键信息：
- 名称：给它起个你一眼就能认出来的名字，比如“Codex-写代码专用”。
- 命令：这是最关键的一步。你需要告诉cc-switch，启动Codex的命令是什么。通常就是codex或者npx codex。如果你不确定，可以在终端里先试一下，比如输入codex --help，看能不能正常输出。
- 工作目录：这个可以留空，cc-switch会默认使用你当前的项目目录。但如果你想让它每次启动都固定在一个特定文件夹里，就填上路径，比如/Users/你的名字/Projects/my-app。
- 图标（可选）：你可以给它选一个好看的图标，方便在列表里快速识别。
保存并测试。填好后点击“保存”。现在，你应该能在主界面的工具列表里看到“Codex-写代码专用”这个新条目了。点击它，看看能不能正常启动Codex。如果一切顺利，恭喜你，你已经成功添加了第二个AI工具！

第二步：批量添加，像搭积木一样

一个工具太孤单，我们再来几个。重复上面的步骤，把OpenCode、Gemini CLI（如果你装了）都加进来。你可以给它们起各种有趣的名字，比如“OpenCode-聊天助手”、“Gemini-翻译官”。

小技巧：如果你有多个项目，每个项目需要不同的AI工具组合，你可以创建“工具组”。比如，为“前端项目”创建一个组，里面只放Codex和OpenCode；为“后端项目”创建另一个组，里面放Claude Code和Gemini CLI。这样切换项目时，你只需要切换组，而不是一个个手动开关。

第三步：管理你的“工具库”——编辑、删除、排序

工具多了，难免要整理一下。cc-switch提供了很直观的管理功能：

编辑：鼠标悬停在某个工具上，通常会出现一个“编辑”或“设置”图标（比如一个齿轮）。点击它，就可以修改名称、命令、工作目录等信息。
删除：如果某个工具你不再需要了，比如你卸载了Codex，那就找到它的条目，点击“删除”按钮（通常是个垃圾桶图标）。放心，这只会从cc-switch的列表里移除，不会真的卸载你的AI工具。
排序：你希望常用的工具排在前面？直接拖拽列表里的条目，就能调整顺序。就像整理手机桌面一样简单。

第四步：实战演练——一个“三合一”工作流

想象一下这个场景：你正在写一个React组件，需要：

用Codex快速生成组件骨架。
用Claude Code检查代码逻辑。
用OpenCode写单元测试。

以前，你得打开三个终端窗口，分别启动三个工具。现在，用cc-switch，你只需要：

在工具列表里点击“Codex-写代码专用”，它就会在终端里启动，你输入需求，生成代码。
关掉Codex（或者让它后台运行），点击“Claude Code-代码审查”，它就会接管终端，你粘贴代码让它分析。
最后，点击“OpenCode-测试助手”，开始写测试。

整个过程行云流水，你甚至不需要离开编辑器。这就是cc-switch带来的“丝滑”体验。

常见问题与排查

添加后点击没反应？
- 检查命令是否正确：在终端里手动输入你填写的命令（比如codex），看能不能正常启动。如果提示“command not found”，说明你填错了，或者Codex没装好。
- 检查工作目录：如果工作目录填错了，比如路径不存在，cc-switch可能无法启动工具。先留空试试。
工具列表里出现了重复的条目？
- 别慌，直接删除多余的就行。cc-switch不会限制你添加重复的工具，但建议保持整洁。
我想让某个工具默认启动在某个项目文件夹里？
- 在编辑工具时，把“工作目录”设置成那个项目的绝对路径。比如/Users/你的名字/Projects/my-react-app。

注意事项

命令不要带路径：除非你明确知道自己在做什么，否则命令最好只写工具名（如codex），而不是完整的路径（如/usr/local/bin/codex）。cc-switch会自动从系统的PATH环境变量里找。
不要同时启动太多工具：每个AI工具都会占用一定的系统资源（尤其是内存）。如果你同时启动了三四个，电脑可能会变卡。建议一次只用一个，或者根据任务切换。
善用“工具组”：这是cc-switch最实用的功能之一。花几分钟创建几个项目专用的工具组，能极大提升你的切换效率。

好了，现在你已经掌握了添加和管理多个AI工具的核心技能。下一章，我们会聊聊如何给这些工具绑定快捷键，让你连鼠标都不用点，就能瞬间切换。准备好了吗？

5. 配置快捷键与全局热键

好的，没问题。这一章我们来聊聊怎么让 cc-switch 真正“听你使唤”——配置快捷键和全局热键。

第 5 章：配置快捷键与全局热键

想象一下，你正全神贯注地写代码，突然想切换到另一个 AI 助手。这时候，你是想用鼠标点开 cc-switch 的窗口，再点几下切换？还是直接按一个组合键，瞬间搞定？答案很明显，对吧？这一章就是教你如何实现后者，把 cc-switch 变成一个真正“秒切”的工具。

为什么要配置快捷键？

简单来说，效率。快捷键和全局热键能让你不离开键盘就完成操作，把切换 AI 助手这件事的“心智负担”降到最低。你不需要思考“我该点哪里”，肌肉记忆会帮你完成一切。对于高频操作，比如在 Claude Code 和 Codex 之间来回切换，这能省下大量时间。

前置条件

在开始配置之前，请确保你已经：

成功安装并运行了 cc-switch。如果你还没装好，请先回到第 2 章。
至少添加了两个 AI 工具实例。比如一个 Claude Code，一个 Codex。这样你才能体会到切换的乐趣。如果还没添加，请参考第 4 章。
知道 cc-switch 的主界面在哪里。通常它会出现在系统托盘（Windows/macOS）或通知区域（Linux）。

第一步：打开设置

cc-switch 的快捷键配置藏在设置里。找到它的方式很简单：

右键点击系统托盘里的 cc-switch 图标。
在弹出的菜单里，选择 “设置” 或 “Preferences”（具体文字取决于你的界面语言，但图标通常是一个齿轮）。

你会看到一个设置窗口，里面有很多选项。别怕，我们只关心“快捷键”或“Hotkeys”这个标签页。

第二步：认识快捷键和全局热键

在开始配置前，我们先区分两个概念：

快捷键 (Shortcuts)：这些快捷键只在 cc-switch 窗口处于激活状态时才生效。比如，你打开了 cc-switch 的切换面板，按 Ctrl+N 可以切换到下一个 AI 工具。它们的作用范围是“应用内”。
全局热键 (Global Hotkeys)：这些热键在任何时候、任何程序里按下都有效。比如，你正在写代码，按 Ctrl+Alt+C，cc-switch 就会立刻弹出切换面板，或者直接切换到下一个工具。它们的作用范围是“系统级”。

我们主要配置的是全局热键，因为这才是真正“秒切”的关键。

第三步：配置你的第一个全局热键

假设你想实现：在任何时候，按下 Ctrl+Shift+Space，都能快速切换到下一个 AI 工具。

在设置窗口的“快捷键”或“Hotkeys”标签页里，找到 “下一个工具” 或 “Next Tool” 这个选项。
点击它旁边的输入框（通常显示“未设置”或“None”）。
现在，同时按下你想要的组合键：Ctrl + Shift + Space。注意，不是输入字母，而是直接按下键盘上的这些键。
你会看到输入框里显示了你刚刚按下的组合键：Ctrl+Shift+Space。
点击“保存”或“应用”按钮。

预期结果：现在，无论你在哪个窗口（浏览器、编辑器、终端），只要按下 Ctrl+Shift+Space，cc-switch 就会立刻切换到列表里的下一个 AI 工具。你可以试试看，是不是很丝滑？

第四步：配置更多常用操作

除了“下一个工具”，你还可以配置其他常用操作的全局热键。比如：

上一个工具 (Previous Tool)：Ctrl+Shift+Z。方便你来回切换。
显示/隐藏切换面板 (Toggle Panel)：Ctrl+Alt+T。按下后，cc-switch 的切换面板会弹出或隐藏，你可以用鼠标或键盘选择工具。
直接切换到指定工具 (Switch to Tool 1, 2, 3...)：Ctrl+Alt+1、Ctrl+Alt+2、Ctrl+Alt+3。如果你有固定的“三件套”，这个最直接。

配置方法都一样：找到对应选项，点击输入框，按下你的组合键，保存。

常见问题与排查

我按了热键，但没反应？
- 检查冲突：你设置的热键可能被其他程序占用了。比如，Ctrl+Shift+Space 在某些输入法里是切换中英文的快捷键。你可以尝试换一个组合键，比如 Ctrl+Alt+Space 或 Win+Shift+C。
- 检查权限：在某些系统（尤其是 macOS）上，cc-switch 可能需要“辅助功能”或“输入监控”权限才能捕获全局热键。你可以在系统设置 -> 隐私与安全性里检查并授权。
- 检查日志：打开 cc-switch 的日志（第 7 章会讲），看看有没有报错信息。日志通常会告诉你热键注册是否成功。
我设置了热键，但切换后没反应？
- 确保你添加的 AI 工具实例是可用的。比如，Claude Code 的 API Key 是否配置正确？Codex 的路径是否正确？如果工具本身有问题，切换过去自然没反应。

一个小例子：打造你的“开发三键客”

假设你日常开发需要三个 AI 助手：Claude Code（写代码）、Codex（查文档）、OpenCode（做实验）。你可以这样配置：

添加这三个工具，并确保它们在 cc-switch 的列表里按你喜欢的顺序排列（比如 Claude Code 是 1，Codex 是 2，OpenCode 是 3）。
配置全局热键：
- Ctrl+Alt+1：切换到 Claude Code
- Ctrl+Alt+2：切换到 Codex
- Ctrl+Alt+3：切换到 OpenCode
配置一个“快速切换”热键：
- Ctrl+Shift+Space：切换到下一个工具（方便你按顺序循环）。

现在，你的工作流会变成这样：

写代码遇到问题，按 Ctrl+Alt+2 瞬间切到 Codex 查文档。
查到思路后，按 Ctrl+Alt+1 切回 Claude Code 继续写。
想验证一个想法，按 Ctrl+Alt+3 切到 OpenCode 做实验。
实验完，按 Ctrl+Shift+Space 切回 Claude Code。

整个过程行云流水，手完全不用离开键盘。这才是高效开发该有的样子。

配置好快捷键后，你会发现 cc-switch 从一个“需要主动打开的工具”变成了一个“融入你操作习惯的肌肉记忆”。下一章，我们会聊聊如何让 cc-switch 记住你当前的工作目录和项目上下文，让切换更智能。

6. 切换工作目录与项目上下文

好嘞，咱们进入第 6 章。前面几章你已经学会了怎么安装、添加工具、甚至配了快捷键，现在该聊聊一个特别实用、但容易被忽略的功能——切换工作目录和项目上下文。

你可能遇到过这种情况：你正在用 Claude Code 写一个 React 项目，突然老板让你去修一个 Python 脚本的 bug。你总不能把 Claude Code 关掉，再重新打开一个终端 cd 到另一个目录吧？那太原始了。cc-switch 就是来解决这个问题的——让你在多个项目之间“瞬移”，而且每个项目还带着自己的 AI 助手上下文。

为什么需要切换工作目录？

想象一下，你的 AI 助手（比如 Claude Code）就像一个超级聪明的实习生。你告诉它“帮我看看这个项目的代码”，它就会把当前目录下的所有文件都读进脑子里。如果你不切换目录，它就一直以为你在做同一个项目。当你切换到另一个项目时，它脑子里还是上一堆代码，回答就会驴唇不对马嘴。

cc-switch 的“工作目录切换”功能，就是帮你告诉 AI 助手：“嘿，现在咱们换个项目，把脑子清空，重新加载这个新目录的文件。” 这样每个项目都有自己的上下文，互不干扰。

前置条件

在开始之前，确保你已经：

安装并启动了 cc-switch（第 2 章的内容）。
至少添加了一个 AI 工具实例（比如 Claude Code 或 Codex，第 4 章教的）。
你的终端已经打开了 cc-switch 的界面（通常按 Ctrl+Shift+Space 或你配的热键）。

如果你还没搞定这些，先回去补补课，别急着跳。

第一步：查看当前工作目录

先看看你当前在哪个目录下。在 cc-switch 的主界面（就是那个工具列表的界面），通常顶部或底部会显示一行小字，比如：

📁 当前工作目录: /Users/你的名字/projects/my-react-app

如果没看到，别慌。你可以直接按 Ctrl+L（或者你配的快捷键）来查看。这个快捷键会弹出一个信息面板，里面就包含了当前工作目录的路径。

预期结果：你会看到类似 /home/你/项目名 或 C:\Users\你\项目名 这样的路径。记住它，后面有用。

第二步：手动切换工作目录

现在，假设你想切换到另一个项目，比如 /Users/你/projects/python-script。操作很简单：

在 cc-switch 主界面，按 Ctrl+P（或者你配的“切换目录”快捷键）。这会弹出一个输入框。
在输入框里输入目标目录的路径。你可以直接打字，也可以按 Tab 键自动补全（就像在终端里一样）。
输入完路径后，按回车。

预期结果：界面会刷新一下，顶部显示的工作目录变成了你刚输入的那个路径。同时，你当前选中的 AI 工具（比如 Claude Code）会自动重新加载这个新目录的上下文。如果你用的是 Codex，它也会重新扫描这个目录。

小技巧：如果你经常在几个固定项目之间切换，可以把它们的路径记下来，或者用下面的“收藏夹”功能。

第三步：使用“收藏夹”快速切换

每次都手动输入路径太麻烦了，尤其是路径很长的时候。cc-switch 支持“收藏夹”功能，让你一键切换。

添加收藏夹

先切换到你想收藏的目录（用第二步的方法）。
按 Ctrl+D（或者你配的“添加收藏”快捷键）。
弹出一个对话框，让你给这个收藏起个名字。比如输入“React项目”或“Python脚本”。
按回车确认。

预期结果：这个目录就被保存到收藏夹列表里了。下次你想切换时，按 Ctrl+Shift+D（或者你配的“打开收藏夹”快捷键），就会弹出一个列表，里面有你所有收藏的目录。用上下键选择，按回车就切换过去了。

管理收藏夹

如果你收藏多了想删掉，或者改个名字，可以按 Ctrl+Alt+D（或者你配的“管理收藏夹”快捷键）。这会打开一个管理界面，你可以：

删除：选中一个收藏，按 Delete 键。
重命名：选中一个收藏，按 F2 键，然后输入新名字。
排序：用 Ctrl+↑ 和 Ctrl+↓ 调整顺序。

预期结果：收藏夹列表会实时更新，下次打开时就是你调整后的样子。

第四步：切换工作目录时自动加载项目上下文

这是 cc-switch 最酷的地方。当你切换工作目录时，它不只是改个路径，还会自动做几件事：

重新扫描项目文件：AI 助手会重新读取新目录下的所有文件（比如 .py、.js、.tsx 等），更新它的“记忆”。
加载项目配置文件：如果你的项目根目录下有 .claude.json、.codex.json 或 .opencode.json 这类配置文件，cc-switch 会自动读取并应用里面的设置（比如忽略某些文件夹、指定 AI 模型等）。
重置对话历史：默认情况下，切换目录后，AI 助手的对话历史会被清空。这样它就不会把上一个项目的对话内容带到新项目里，避免混淆。

注意：如果你不想清空对话历史（比如你正在调试一个跨项目的 bug），可以在 cc-switch 的设置里关掉这个功能。按 Ctrl+, 打开设置，找到“切换目录时清空对话历史”选项，把它关掉就行。

第五步：实战小例子

假设你同时在做两个项目：

项目 A：一个 React 前端应用，在 /home/你/projects/frontend-app
项目 B：一个 Flask 后端 API，在 /home/你/projects/backend-api

你想让 Claude Code 先帮你看看前端的一个组件，然后马上切换到后端修一个接口。

先确保 Claude Code 已经启动，并且当前工作目录是 /home/你/projects/frontend-app。
在 cc-switch 界面，按 Ctrl+P，输入 /home/你/projects/frontend-app，回车。Claude Code 会加载这个目录的上下文。
你问 Claude Code：“帮我看看 src/components/Header.jsx 这个组件，有没有性能问题？” 它会基于这个目录的文件回答你。
看完之后，你想切换到后端。按 Ctrl+P，输入 /home/你/projects/backend-api，回车。
现在 Claude Code 的上下文变成了后端目录。你问它：“帮我看看 app/routes/users.py 里的 get_user 函数，为什么返回 404？” 它会基于后端的代码回答你，完全不会混淆。

整个过程不需要关闭任何终端，不需要重新启动 AI 助手，就像在 IDE 里切换标签页一样丝滑。

常见问题与排查

切换目录后，AI 助手没反应？

原因：可能是 AI 工具本身卡住了，或者 cc-switch 没成功发送切换指令。
解决：先试试手动在终端里 cd 到目标目录，然后按 Ctrl+R（或者你配的“重新加载”快捷键），强制 AI 助手重新加载上下文。如果还不行，重启一下 cc-switch（按 Ctrl+Q 退出，再重新启动）。

切换目录后，对话历史还在？

原因：你在设置里关了“清空对话历史”选项。
解决：按 Ctrl+, 打开设置，找到那个选项，打开它。或者，你也可以手动按 Ctrl+Shift+H（或者你配的“清空历史”快捷键）来清空。

收藏夹里找不到我添加的目录？

原因：可能你添加时路径写错了，或者目录被移动/删除了。
解决：按 Ctrl+Alt+D 打开收藏夹管理，看看列表里有没有。如果有但路径不对，选中它，按 F2 重命名，或者按 Delete 删掉重新添加。如果列表是空的，说明你之前没成功添加，再试一次第二步。

切换目录后，AI 助手报错“找不到文件”？

原因：目标目录可能没有 AI 助手需要的文件（比如 .git 目录、package.json 等），或者目录权限不对。
解决：先确认目标目录存在且可读。你可以用 ls 或 dir 命令检查一下。如果目录没问题，试试在 cc-switch 里按 Ctrl+R 重新加载一次。

好了，现在你已经掌握了切换工作目录和项目上下文的技巧。这招用熟了，你的开发效率会提升一大截——再也不用在多个终端窗口之间来回切换了。下一章，我们会聊聊怎么用日志和历史记录来排查问题，帮你解决那些“明明操作对了，但就是没反应”的怪事。

7. 使用日志与历史记录排查问题

好，我们直接进入正题。今天这一章，我们来聊聊怎么用 cc-switch 自带的日志和历史记录功能，帮你快速定位问题。别怕，这玩意儿比你想的简单，而且特别实用。

为什么你需要关心日志？

想象一下，你正用 cc-switch 切换到一个 AI 助手，结果它没反应，或者报了个看不懂的错误。这时候，你可能会想：“我是不是哪里操作错了？” 或者 “这工具是不是有 bug？”

别急，cc-switch 其实一直在默默记录它的一举一动。这些记录，就是日志。它们就像黑匣子，能告诉你刚才到底发生了什么。学会看日志，你就能自己当侦探，省去很多瞎猜和求助的时间。

前置条件

在开始之前，确保你已经：

成功安装并运行了 cc-switch。如果还没装，先回去看第 2 章。
至少添加了一个 AI 工具实例（比如 Claude Code 或 Codex）。第 4 章有教。
你的终端或命令行窗口是打开的，并且你能在 cc-switch 的界面里操作。

第一步：找到日志文件

cc-switch 的日志文件默认存放在一个固定的地方，具体路径取决于你的操作系统。别担心，你不需要记住它，因为 cc-switch 提供了一个命令来直接打开它。

打开你的终端，输入：

cc-switch logs

预期结果： 你的系统会用默认的文本编辑器（比如记事本、VS Code 或 TextEdit）打开一个名为 cc-switch.log 的文件。如果文件不存在，它会自动创建一个空的。

小提示： 如果你用的是 macOS 或 Linux，也可以用 tail -f 命令实时查看日志更新，这样你就能看到每次操作后新写入的内容：

tail -f ~/.cc-switch/logs/cc-switch.log

（Windows 用户可以用 Get-Content -Wait 命令，但 cc-switch logs 命令已经够用了。）

第二步：看懂日志内容

打开日志文件后，你可能会看到一堆类似这样的内容：

[2024-05-20 14:32:15] [INFO] Starting cc-switch v1.2.0
[2024-05-20 14:32:16] [INFO] Loaded configuration from /Users/yourname/.cc-switch/config.json
[2024-05-20 14:32:18] [INFO] Switching to instance: claude-code
[2024-05-20 14:32:18] [INFO] Executing command: /usr/local/bin/claude
[2024-05-20 14:32:19] [ERROR] Process exited with code 1: /usr/local/bin/claude
[2024-05-20 14:32:19] [ERROR] Error details: Failed to connect to API: Connection refused

别被这些符号吓到，它们其实很有规律。每一条日志都包含这几个部分：

时间戳：[2024-05-20 14:32:15] —— 告诉你这件事发生在什么时候。
日志级别：[INFO]、[WARN]、[ERROR] —— 这是最重要的部分。
- INFO：普通信息，比如“我启动了”、“我加载了配置”、“我切换到了某个工具”。这些是正常操作。
- WARN：警告，表示可能有点小问题，但不影响运行。比如“配置文件里有个字段我不认识，我忽略它了”。
- ERROR：错误，说明有东西失败了。比如“切换工具时，那个程序崩溃了”或“网络连接失败了”。
消息内容：Starting cc-switch v1.2.0 —— 具体发生了什么。

实战演练： 假设你刚才切换 Claude Code 失败了，日志里出现了 [ERROR] 行。仔细看，它说 Failed to connect to API: Connection refused。这意味着什么？很可能你的网络有问题，或者 Claude Code 的 API 密钥没配置好。你不需要懂编程，光看这个错误信息，就知道该去检查网络或 API 设置了。

第三步：使用历史记录

除了日志，cc-switch 还记录了你切换过的所有 AI 工具的历史。这在你需要回看之前用了哪个工具、或者想重复某个操作时特别有用。

查看历史记录的命令是：

cc-switch history

预期结果： 终端会打印出最近几次切换的记录，像这样：

# 最近 10 次切换记录
1. 2024-05-20 14:30: claude-code -> codex
2. 2024-05-20 14:28: codex -> opencode
3. 2024-05-20 14:25: opencode -> claude-code
...

小技巧： 如果你只想看最近 5 条记录，可以加个参数：

cc-switch history --limit 5

第四步：用日志排查一个真实问题

我们来模拟一个场景。你正在用 cc-switch 切换到一个叫 my-ai 的工具，结果它没反应。你打开日志，看到：

[ERROR] Process exited with code 127: /usr/local/bin/my-ai

code 127 是什么意思？在 Unix 系统里，这通常意味着“命令未找到”。也就是说，cc-switch 尝试执行 /usr/local/bin/my-ai，但这个文件不存在。

排查步骤：

检查路径：打开 cc-switch 的配置（通常用 cc-switch config 命令或直接编辑 config.json 文件），找到 my-ai 这个实例的 command 字段。它可能写的是 /usr/local/bin/my-ai，但实际你的 my-ai 程序安装在别的地方，比如 /opt/my-ai/bin/my-ai。
修正路径：把 command 改成正确的路径。
验证：重新运行 cc-switch switch my-ai，然后看日志。这次应该变成 [INFO] Executing command: /opt/my-ai/bin/my-ai，然后 [INFO] Process started successfully。

另一个常见错误： 日志里出现 [ERROR] Failed to read configuration file: Permission denied。这说明 cc-switch 没有权限读取它的配置文件。解决办法是检查文件权限，确保你的用户有读取权限（在 macOS/Linux 上用 chmod 命令，Windows 上右键属性里改）。

第五步：清理日志文件

日志文件会随着时间增长，如果你发现它变得很大（比如几百 MB），可以清空它。但别担心，cc-switch 会自动管理，不过你也可以手动操作：

cc-switch logs --clear

预期结果： 日志文件被清空，只留下一条新记录，告诉你“日志已被清空”。

总结一下

日志：用 cc-switch logs 打开，看 [ERROR] 和 [WARN] 级别的信息，能快速定位问题。
历史记录：用 cc-switch history 查看切换记录，方便回看或重复操作。
排查思路：看到错误码（比如 127）或错误消息（比如 Connection refused），先别慌，去检查对应的配置、路径或网络。

下次遇到 cc-switch 不听话，别急着删了重装。先打开日志，它很可能已经告诉你答案了。

8. 自定义主题与界面布局

好嘞，咱们开始聊第 8 章——自定义主题与界面布局。

你可能会想：“一个命令行工具，界面有啥好折腾的？” 但你想啊，每天对着黑底白字或者白底黑字，看久了眼睛真的会抗议。而且，cc-switch 的界面其实挺灵活的，你可以把它调成你最喜欢的颜色、字体大小，甚至让它在不同项目里自动切换不同的“皮肤”。这一章，我们就来把它打扮成你看着最顺眼的样子。

先确认一下你到哪一步了

在开始之前，确保你已经：

安装并初始化了 cc-switch（第 2 章的内容）。
至少添加了一个 AI 工具实例（第 4 章的内容），不然你调了半天界面，发现没东西可切，那多尴尬。
你的终端支持 256 色或真彩色（True Color）。现在大部分终端都支持，如果你用的是 Windows 的旧版 cmd，建议换成 Windows Terminal 或 PowerShell 7+。

第一步：找到“皮肤”文件夹

cc-switch 的主题配置，藏在它自己的配置目录里。打开你的终端，运行：

# 看看 cc-switch 的配置目录在哪
cc-switch config path

这条命令会输出一个路径，比如 ~/.config/cc-switch/（Linux/macOS）或 %APPDATA%\cc-switch\（Windows）。进去之后，你会看到一个 themes 文件夹。如果没有，手动建一个：

mkdir -p ~/.config/cc-switch/themes

预期结果：你得到了一个空文件夹，或者里面已经有一些 .json 文件（如果你之前导入过主题）。这就是我们接下来要折腾的地方。

第二步：创建一个最简单的自定义主题

cc-switch 的主题是一个 JSON 文件。我们先从最基础的开始：改个背景色和文字颜色。

在 themes 文件夹里，新建一个文件，叫 my-first-theme.json，然后写入以下内容：

{
  "name": "我的第一个主题",
  "colors": {
    "background": "#1e1e2e",
    "foreground": "#cdd6f4",
    "accent": "#89b4fa"
  },
  "fonts": {
    "size": 14,
    "family": "monospace"
  }
}

解释一下：

name：主题的名字，随便起，但最好别用中文文件名（有些系统对中文文件名支持不好），但 JSON 里的 name 字段可以用中文。
colors：颜色配置。background 是背景，foreground 是文字，accent 是强调色（比如选中项、按钮高亮）。
fonts：字体大小和字体族。monospace 是等宽字体，几乎所有终端都支持。

保存后，在终端里应用它：

cc-switch theme set my-first-theme

预期结果：你的 cc-switch 界面瞬间变成了柔和的深色背景 + 浅色文字，选中项会带点蓝色高亮。如果没变化，检查一下文件名是不是写对了（不带 .json 后缀也能识别，但建议带上）。

第三步：深入调教——每个角落的颜色

上面那个只是皮毛。cc-switch 允许你控制界面上几乎每一个元素的颜色。比如，你想让“错误信息”变成醒目的红色，“成功信息”变成绿色，“提示信息”变成灰色。

打开 my-first-theme.json，把它改成这样：

{
  "name": "我的第一个主题",
  "colors": {
    "background": "#1e1e2e",
    "foreground": "#cdd6f4",
    "accent": "#89b4fa",
    "error": "#f38ba8",
    "success": "#a6e3a1",
    "warning": "#fab387",
    "info": "#74c7ec",
    "border": "#313244",
    "selection": {
      "background": "#45475a",
      "foreground": "#cdd6f4"
    }
  },
  "fonts": {
    "size": 14,
    "family": "monospace"
  }
}

注意：

selection 是一个对象，控制选中文本时的背景和文字颜色。
颜色值支持十六进制（#RRGGBB）、RGB（rgb(255, 255, 255)）或预定义颜色名（red、blue 等），但十六进制最通用。

保存后，再次运行 cc-switch theme set my-first-theme，你会看到错误信息变成了粉红色，成功信息变成了浅绿色，整个界面更有层次感了。

常见报错：如果你看到 Invalid color value 之类的错误，八成是颜色格式写错了。检查一下十六进制有没有漏掉 #，或者 RGB 值是不是在 0-255 之间。

第四步：布局也能调——不只是颜色

颜色改完了，但你可能觉得列表太挤、标题太大。cc-switch 的布局控制藏在 layout 字段里。

继续编辑你的主题文件，加上布局配置：

{
  "name": "我的第一个主题",
  "colors": {
    "background": "#1e1e2e",
    "foreground": "#cdd6f4",
    "accent": "#89b4fa",
    "error": "#f38ba8",
    "success": "#a6e3a1",
    "warning": "#fab387",
    "info": "#74c7ec",
    "border": "#313244",
    "selection": {
      "background": "#45475a",
      "foreground": "#cdd6f4"
    }
  },
  "fonts": {
    "size": 14,
    "family": "monospace"
  },
  "layout": {
    "padding": {
      "top": 1,
      "bottom": 1,
      "left": 2,
      "right": 2
    },
    "item_spacing": 1,
    "title_height": 3,
    "border_style": "rounded"
  }
}

参数说明：

padding：界面边缘的内边距。单位是“字符行”或“字符列”，不是像素。
item_spacing：列表项之间的行间距。
title_height：顶部标题栏的高度（行数）。
border_style：边框样式。可选值：none（无边框）、thin（细线）、rounded（圆角）、double（双线）。

保存并应用后，你会发现界面四周有了呼吸空间，列表项之间不再挤在一起，标题栏也变高了。border_style: "rounded" 会让边框角变成圆角，看起来更现代。

实用技巧：如果你觉得 padding 太大，可以调小到 0，但那样会显得很挤。建议 left 和 right 至少留 1 个字符的间距。

第五步：让主题随项目自动切换

这是 cc-switch 的一个隐藏大招：你可以为不同的项目目录绑定不同的主题。

比如，你在做前端项目时喜欢亮色主题，在后端项目时喜欢暗色主题。先创建两个主题文件：

light-theme.json（亮色主题）：

{
  "name": "亮色工作",
  "colors": {
    "background": "#ffffff",
    "foreground": "#1e1e2e",
    "accent": "#1e66f5"
  }
}

dark-theme.json（暗色主题）：

{
  "name": "暗色工作",
  "colors": {
    "background": "#1e1e2e",
    "foreground": "#cdd6f4",
    "accent": "#89b4fa"
  }
}

然后，在你的前端项目目录（比如 ~/projects/frontend-app）里，运行：

cc-switch theme bind light-theme

在你的后端项目目录（比如 ~/projects/backend-api）里，运行：

cc-switch theme bind dark-theme

预期结果：当你 cd 到前端项目目录并启动 cc-switch 时，它会自动加载亮色主题；切换到后端项目时，自动变成暗色主题。这个绑定信息会保存在项目根目录下的 .cc-switch 隐藏文件里（如果你好奇的话）。

注意事项：

绑定只对当前目录生效，不会递归到子目录。如果你在子目录里也想用同样的主题，需要手动再绑定一次，或者把 cc-switch 的启动脚本放在项目根目录。
如果你删除了绑定的主题文件，cc-switch 会回退到默认主题，不会崩溃。

第六步：分享你的主题

折腾了半天，你终于调出了一个满意的主题。想分享给朋友，或者备份一下？很简单，直接把 themes 文件夹里的 .json 文件发给别人就行。

对方拿到后，把它放到自己的 ~/.config/cc-switch/themes/ 目录下，然后运行：

cc-switch theme set 你朋友的主题文件名

实用技巧：你可以在网上搜“cc-switch themes”，有些社区会分享现成的主题包。下载后直接丢进 themes 文件夹就能用，省得自己调色。

一个小例子串起来

假设你是一个全栈开发者，白天写前端（React），晚上写后端（Go）。你希望：

前端项目：亮色主题，字体大一点（16px），方便看代码。
后端项目：暗色主题，字体小一点（13px），节省屏幕空间。

步骤：

创建 frontend-theme.json（亮色、16px）。
创建 backend-theme.json（暗色、13px）。
进入前端项目目录，运行 cc-switch theme bind frontend-theme。
进入后端项目目录，运行 cc-switch theme bind backend-theme。

之后，你只需要 cd 到对应目录，启动 cc-switch，它就会自动切换成你想要的风格。眼睛舒服了，效率也上来了。

常见报错与排查

应用主题后界面没变化：检查一下主题文件是不是 JSON 格式正确（可以用 jsonlint 或在线 JSON 校验工具）。另外，确保你运行了 cc-switch theme set 主题名，而不是只保存了文件。
颜色显示不对（比如变成黑白）：你的终端可能不支持真彩色。试试在终端设置里开启“True Color”或“24-bit color”支持。Windows Terminal 默认支持，macOS 的 iTerm2 需要手动开启。
布局参数不生效：检查 layout 字段的键名是否拼写正确（比如 item_spacing 不是 itemSpacing）。cc-switch 用的是下划线命名法（snake_case）。
主题绑定后不自动切换：确认你绑定的目录是 cc-switch 启动时的当前工作目录。如果你在子目录里启动，绑定可能不生效。建议在项目根目录绑定。

好了，现在你的 cc-switch 已经不只是工具，而是你专属的“皮肤”了。下一章我们会聊聊怎么用日志和记录来排查问题，万一哪天界面突然崩了，你也能快速找到原因。

9. 常见报错与解决方案

好嘞，咱们直接进入正题。这一章专门用来解决你可能会遇到的“翻车”现场。别怕，cc-switch 本身挺稳的，但毕竟要跟一堆不同的 AI 工具和系统打交道，偶尔闹点小脾气很正常。我会把最常见的几个“坑”和对应的“填坑”方法列出来，你按顺序排查，基本都能搞定。

9.1 安装或启动时：`command not found` 或 `cc-switch: 未找到命令`

这是最经典的问题，通常不是 cc-switch 的锅，而是你的系统没找到它。

原因：安装脚本没把 cc-switch 放到系统的 PATH 环境变量里，或者你安装完后忘了重启终端。

排查步骤：

检查安装目录：先确认 cc-switch 到底装哪了。通常它会装在 ~/.local/bin/ 或者 /usr/local/bin/ 下。你可以试试直接运行它的完整路径，比如：
```
~/.local/bin/cc-switch --version
```
如果能输出版本号，说明安装成功，只是没被系统找到。
检查 PATH：运行下面这行命令，看看你的 PATH 里有没有包含安装目录：
```
echo $PATH
```
如果输出里没有 ~/.local/bin 或 /usr/local/bin，那就需要手动加进去。
修复方法：把下面这行加到你的 shell 配置文件里（比如 ~/.bashrc、~/.zshrc 或 ~/.profile）：
```
export PATH="$HOME/.local/bin:$PATH"
```
然后执行 source ~/.bashrc（或对应的配置文件）让改动生效。再试试 cc-switch --version，应该就好了。

小提示：如果你用的是 macOS 或 Linux，安装完后一定要重启终端，或者手动 source 一下配置文件。Windows 用户可能需要重启 PowerShell 或 CMD。

9.2 切换 AI 工具时：`Error: [工具名] not found` 或 `Failed to launch [工具名]`

你明明装了 Claude Code 或 Codex，但 cc-switch 就是找不到它。

原因：cc-switch 默认会去系统 PATH 里找这些工具，但有些工具（比如通过 npm 全局安装的）可能不在标准路径里，或者你安装时用了特殊方式（比如 Docker、npx）。

排查步骤：

手动验证工具是否存在：先直接在终端里运行一下那个工具，比如：
```
claude --version
```
如果这里也报错，说明工具本身没装好，先去搞定工具的安装。
检查 cc-switch 的配置：运行 cc-switch config 或 cc-switch list，看看当前配置里有没有这个工具。如果没有，你需要手动添加。
手动添加工具路径：用 cc-switch add 命令，并指定工具的完整路径。比如：
```
cc-switch add claude --path /home/yourname/.npm-global/bin/claude
```
这样 cc-switch 就能直接找到它了，不再依赖 PATH。

常见报错示例：

Error: codex not found → 用 which codex 找到它的真实路径，然后 cc-switch add codex --path /那个路径/codex。
Failed to launch opencode → 可能是工具启动参数有问题，试试 cc-switch run opencode --debug 看详细日志。

9.3 快捷键或全局热键不生效

你设好了快捷键，但按了没反应。

原因：全局热键需要系统权限，或者快捷键被其他应用占用了。

排查步骤：

检查权限：在 macOS 上，你需要去「系统设置 → 隐私与安全性 → 辅助功能」里，确保 cc-switch 被勾选。在 Linux 上，可能需要安装 xdotool 或 xbindkeys 等依赖。
检查快捷键冲突：试试换一个不常用的组合键，比如 Ctrl+Shift+Alt+F1。如果换完就好了，说明原来的快捷键被别的软件（比如截图工具、输入法）抢了。
重启 cc-switch：有时候热键服务会卡住，重启一下 cc-switch 的后台进程就好：
```
cc-switch restart
```

实用技巧：在设置快捷键时，尽量避开系统级的快捷键（比如 Ctrl+C、Alt+Tab），也避开你常用软件（比如 VS Code、浏览器）的快捷键。

9.4 切换工作目录后，AI 工具不识别项目上下文

你切到了项目目录，但 AI 工具好像还是“失忆”了，不知道当前项目是啥。

原因：cc-switch 只是帮你启动工具，但工具本身可能不会自动读取当前目录。比如 Claude Code 需要你手动指定 --project 参数。

排查步骤：

检查工具是否支持：先看看你用的 AI 工具支不支持通过命令行指定项目目录。比如 Claude Code 支持 claude --project /path/to/project。
配置 cc-switch 的启动参数：在添加工具时，用 --args 参数传进去：
```
cc-switch add claude --args "--project {{current_dir}}"
```
这里的 {{current_dir}} 是 cc-switch 的一个变量，会自动替换成你当前的工作目录。
手动验证：先 cd 到项目目录，然后运行 cc-switch run claude，看看工具启动后是不是直接在那个目录下。

注意事项：不是所有 AI 工具都支持这种参数传递。如果工具本身不支持，那 cc-switch 也没办法。这时候可以考虑用 cc-switch 的“工作目录切换”功能（如果有的话），或者手动在工具里设置。

9.5 日志显示“权限不足”或“无法写入”

cc-switch 的日志文件写不进去了。

原因：日志文件默认放在 ~/.cc-switch/logs/ 下，如果这个目录的权限不对，或者磁盘空间满了，就会报错。

排查步骤：

检查磁盘空间：运行 df -h 看看磁盘是不是满了。如果满了，清理一下。
检查目录权限：
```
ls -la ~/.cc-switch/logs/
```
确保你有读写权限。如果没有，用 chmod 修复：
```
chmod -R 755 ~/.cc-switch/logs/
```
手动清空日志：如果日志文件太大，直接删掉或清空：
```
> ~/.cc-switch/logs/cc-switch.log
```
然后重启 cc-switch。

实用技巧：如果你经常遇到日志问题，可以设置一个定时任务（cron job）定期清理日志，比如每周清一次。

9.6 界面显示异常或乱码

cc-switch 的界面（如果有 GUI 的话）显示不全、按钮错位、或者出现奇怪的字符。

原因：通常是字体问题、终端编码问题，或者系统缺少某些依赖。

排查步骤：

检查终端编码：确保你的终端用的是 UTF-8 编码。在终端里运行：
```
echo $LANG
```
输出应该包含 UTF-8。如果不是，设置一下：
```
export LANG=en_US.UTF-8
```
检查字体：如果你用的是自定义主题，确保你安装了对应的字体（比如 Nerd Fonts）。cc-switch 的界面可能依赖这些字体来显示图标。
重置为默认主题：如果问题出在主题上，先切回默认主题看看：
```
cc-switch theme default
```

常见报错示例：

界面出现方块或问号 → 字体问题，安装 Nerd Fonts 并设置终端使用它。
按钮点不了 → 可能是窗口大小问题，试试调整终端窗口大小，或者用 cc-switch resize 命令（如果有的话）。

9.7 升级后功能异常

你升级了 cc-switch，但之前能用的功能突然不行了。

原因：升级可能改变了配置文件格式、API 接口，或者删除了某些旧功能。

排查步骤：

查看更新日志：先看看 CHANGELOG 里写了什么。通常升级会说明哪些东西变了。
备份并重置配置：先把旧的配置文件备份一下：
```
cp ~/.cc-switch/config.json ~/.cc-switch/config.json.bak
```
然后删掉它，让 cc-switch 重新生成默认配置：
```
rm ~/.cc-switch/config.json
cc-switch init
```
重新添加工具：如果配置重置后问题解决了，说明是旧配置不兼容。你需要重新添加你的 AI 工具。

实用技巧：升级前养成备份配置的好习惯。cc-switch 的配置文件通常很小，备份一下不费事。

9.8 其他通用排查方法

如果上面的方法都没解决你的问题，别慌，还有几招通用的：

查看详细日志：运行 cc-switch 时加上 --debug 或 --verbose 参数，会输出更详细的日志信息，能帮你定位问题。
```
cc-switch run claude --debug
```
检查系统依赖：cc-switch 可能依赖一些系统工具，比如 curl、git、node 等。确保它们都安装了且版本够新。
重启大法：重启 cc-switch、重启终端、甚至重启电脑。有时候就是这么简单粗暴有效。
去官方渠道求助：如果实在搞不定，可以去 cc-switch 的 GitHub Issues 页面（ccswitch.io 上能找到链接）搜索或提问。记得附上你的系统信息、cc-switch 版本、以及完整的错误日志。

好了，这一章的内容就到这。遇到问题别慌，按上面的步骤一步步来，大部分都能解决。下一章我们会聊聊怎么把 cc-switch 真正融入到你的日常开发工作流里，让它成为你的得力助手。

10. 将 cc-switch 集成到你的开发工作流

好，我们开始。前面几章你已经把 cc-switch 装好了，也学会了怎么添加、切换、配置各种 AI 助手。现在问题来了：这东西怎么真正融入你每天写代码的节奏里？总不能每次想用 AI 都先打开 cc-switch 点一下，再切回终端吧？那也太割裂了。

这一章就是来解决这个问题的。我们会把 cc-switch 塞进你的开发工作流，让它像 Git 或 VS Code 一样，成为你肌肉记忆的一部分。目标是：你脑子里想“我要用 Claude 改这段代码”，手已经下意识完成了切换，整个过程不超过两秒。

前置条件

在开始之前，确保你已经：

安装并运行了 cc-switch（第 2 章）
至少添加了一个 AI 工具实例（第 4 章）
配置好了全局热键（第 5 章）—— 这是集成工作流的核心，没有它你会多花 80% 的时间

如果你还没配热键，先回去把第 5 章看了，配一个你顺手的热键，比如 Ctrl+Shift+A 或 Cmd+Shift+A。别跳过，这一步决定了后面的体验。

第一步：把 cc-switch 塞进你的终端启动流程

最自然的集成方式，就是让 cc-switch 在你打开终端时就自动加载。这样你不需要手动启动它，它就在后台等着。

对于 Bash / Zsh 用户（macOS / Linux）

打开你的 shell 配置文件（~/.bashrc、~/.zshrc 或 ~/.bash_profile），在末尾加上一行：

# 自动启动 cc-switch 后台服务
cc-switch daemon &

保存后，重新加载配置：

source ~/.zshrc

预期结果：下次打开终端，cc-switch 会在后台静默运行。你可以用 ps aux | grep cc-switch 确认它活着。

对于 Windows 用户（PowerShell）

打开你的 PowerShell 配置文件（$PROFILE），加上：

# 自动启动 cc-switch 后台服务
Start-Process -WindowStyle Hidden cc-switch daemon

保存后，执行 . $PROFILE 重载配置。

注意：如果你用的是 Windows Terminal，建议把这条命令加到 Windows Terminal 的启动设置里，而不是 PowerShell 的 profile，否则每次打开新标签都会启动一个新实例。

第二步：用热键实现“一键切换”

这是整个工作流集成的灵魂。假设你配了 Ctrl+Shift+A 作为全局热键，现在你可以在任何地方（VS Code、终端、浏览器）按它，cc-switch 的切换菜单就会弹出来。

但光有菜单还不够，我们得让它更智能。cc-switch 支持上下文感知切换——意思是，它可以根据你当前的工作目录，自动推荐最合适的 AI 工具。

配置上下文感知

打开 cc-switch 的设置界面（通常用热键调出菜单后选“设置”），找到“工作目录关联”或类似选项。这里你可以把特定目录和特定 AI 工具绑定。

举个例子：

你的前端项目都在 ~/projects/frontend/ 下，你想用 Claude Code 来处理
后端项目在 ~/projects/backend/，你想用 Codex

在设置里添加两条规则：

~/projects/frontend/  ->  Claude Code
~/projects/backend/   ->  Codex

预期结果：当你在终端里 cd 到 ~/projects/frontend/，然后按热键，cc-switch 会自动选中 Claude Code，你只需要按回车确认。如果没匹配到规则，它会显示所有工具让你手动选。

实用技巧：别贪多，先只配 2-3 个你最常用的项目目录。配太多反而会乱，等习惯了再加。

第三步：与 VS Code 深度绑定

如果你用 VS Code 写代码，那 cc-switch 可以变成你的“AI 快捷键”。这里有两种玩法：

方法一：通过终端集成

在 VS Code 里打开终端（`Ctrl+``），cc-switch 已经在后台运行了。你只需要按热键，菜单就会出现在终端里。这已经很快了，但还不够优雅。

方法二：配置 VS Code 快捷键直接调用

打开 VS Code 的键盘快捷键设置（Ctrl+K Ctrl+S），搜索“terminal.focus”或“workbench.action.terminal.new”，然后添加一个新快捷键绑定：

{
  "key": "ctrl+shift+a",
  "command": "workbench.action.terminal.sendSequence",
  "args": {
    "text": "cc-switch switch\n"
  }
}

预期结果：在 VS Code 里按 Ctrl+Shift+A，终端会自动执行 cc-switch switch 命令，弹出切换菜单。你不需要先点终端再输入命令，一步到位。

注意：这个绑定会覆盖 VS Code 自身的快捷键，确保你之前没把 Ctrl+Shift+A 分配给其他功能。如果冲突了，换个键，比如 Ctrl+Shift+S。

第四步：用别名和函数简化日常操作

如果你经常在终端里手动切换，可以给 cc-switch 的命令起个短别名。打开你的 shell 配置文件，加上：

# cc-switch 别名
alias cs='cc-switch'
alias css='cc-switch switch'
alias csl='cc-switch list'
alias csd='cc-switch daemon'

这样你只需要输入 css 就能切换，csl 就能列出所有工具。

更进一步，你可以写个 shell 函数，让它根据当前目录自动切换：

# 智能切换：根据当前目录自动选择 AI 工具
ai-switch() {
  local dir=$(pwd)
  if [[ "$dir" == *"frontend"* ]]; then
    cc-switch switch claude-code
  elif [[ "$dir" == *"backend"* ]]; then
    cc-switch switch codex
  else
    cc-switch switch
  fi
}

把这个函数加到你的 shell 配置文件里，然后你就可以用 ai-switch 一键切换了。

预期结果：在 ~/projects/frontend/ 下执行 ai-switch，它会自动切换到 Claude Code；在其他目录下，它会弹出菜单让你选。

第五步：与 Git 钩子联动（进阶玩法）

这是给喜欢折腾的人准备的。你可以让 cc-switch 在 Git 操作前后自动切换 AI 工具。比如，每次提交代码前，自动切换到 Codex 来审查 diff。

创建一个 Git 钩子文件 .git/hooks/pre-commit：

#!/bin/bash
# 提交前自动切换到 Codex 审查代码
cc-switch switch codex
echo "已切换到 Codex，准备审查提交内容..."

记得给它执行权限：

chmod +x .git/hooks/pre-commit

预期结果：每次你执行 git commit，终端会自动切换到 Codex，然后你可以用它来审查即将提交的代码。

实用技巧：别把钩子加到所有项目里，只加到那些你确实需要 AI 审查的项目。否则每次提交都切换，你会烦死的。

第六步：用脚本批量切换工作流

假设你有一个典型的开发流程：早上先切换到 Claude Code 写文档，然后切换到 Codex 写代码，最后切换到 OpenCode 做测试。你可以写个脚本一键完成：

#!/bin/bash
# 开发工作流脚本

echo "启动开发工作流..."

# 切换到 Claude Code 写文档
cc-switch switch claude-code
echo "已切换到 Claude Code，开始写文档..."

# 等待用户完成文档工作
read -p "文档写完了吗？按回车继续..."

# 切换到 Codex 写代码
cc-switch switch codex
echo "已切换到 Codex，开始写代码..."

# 等待用户完成编码
read -p "代码写完了吗？按回车继续..."

# 切换到 OpenCode 做测试
cc-switch switch opencode
echo "已切换到 OpenCode，开始测试..."

把这个脚本保存为 dev-workflow.sh，加上执行权限，然后每次开发时运行它。虽然有点傻，但如果你有固定的流程，这能省下不少手动切换的时间。

常见问题与排查

问题 1：热键在 VS Code 里不生效

原因：VS Code 可能拦截了全局热键。检查 VS Code 的键盘快捷键设置，确保没有冲突。如果冲突了，换个热键，或者把 VS Code 的快捷键绑定改成 Ctrl+Shift+A 直接调用终端命令（见第三步的方法二）。

问题 2：后台服务自动启动后没反应

原因：可能是 shell 配置文件加载顺序问题。检查你的 .zshrc 或 .bashrc 里有没有其他命令影响了 cc-switch 的路径。试试在终端里手动执行 cc-switch daemon & 看是否正常。

问题 3：上下文感知切换不生效

原因：工作目录关联规则写错了路径。确保路径是绝对路径，或者用 ~ 开头。另外，规则是精确匹配还是模糊匹配？cc-switch 默认是前缀匹配，所以 ~/projects/frontend/ 会匹配 ~/projects/frontend/my-app/，但不会匹配 ~/projects/frontend-2/。

小例子串起来

假设你是个全栈开发者，手头有两个项目：一个 React 前端（~/work/frontend-app）和一个 Node.js 后端（~/work/backend-api）。你希望：

打开终端时 cc-switch 自动启动
在 frontend-app 目录下按热键直接切换到 Claude Code
在 backend-api 目录下按热键直接切换到 Codex
在 VS Code 里写代码时，按 Ctrl+Shift+A 直接弹出切换菜单

你的配置步骤：

在 .zshrc 里加上 cc-switch daemon &
在 cc-switch 设置里添加两条规则：~/work/frontend-app -> Claude Code，~/work/backend-api -> Codex
在 VS Code 里绑定 Ctrl+Shift+A 到 workbench.action.terminal.sendSequence，参数为 cc-switch switch\n

完成之后，你的日常流程变成：

打开终端 → cc-switch 自动启动（你看不到它，它在后台）
cd ~/work/frontend-app → 按 Ctrl+Shift+A → 菜单自动选中 Claude Code → 回车确认 → 开始用 Claude 写前端代码
切换到 ~/work/backend-api → 按 Ctrl+Shift+A → 菜单自动选中 Codex → 回车确认 → 开始用 Codex 写后端 API

整个过程不到 3 秒，比你手动打开浏览器、登录、粘贴代码快十倍。

现在，cc-switch 已经不再是“一个工具”，而是你开发环境的一部分了。它像你的 IDE 的自动补全一样，安静地待在那里，等你需要的时候，一伸手就能用上。

常見問題

问题：CC Switch 是什么？它支持哪些 AI 命令行工具？

CC Switch 是一款跨平台桌面全能助手，用于集中管理多个 AI 命令行工具。它支持 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes Agent，让你在一个界面中切换和调用这些工具，无需手动配置多个终端环境。

问题：安装 CC Switch 时提示“无法找到依赖”或“安装失败”，怎么办？

常见原因包括：

系统未安装 Node.js（版本 ≥ 18）：请先安装 Node.js 并确保 node -v 输出正确版本。
缺少 Git：部分工具（如 Claude Code）需要 Git 支持，请安装 Git 并配置环境变量。
权限问题：在 macOS/Linux 上尝试 sudo npm install -g cc-switch，或使用包管理器（如 Homebrew）安装。
网络问题：如果下载依赖超时，可尝试设置 npm 镜像：npm config set registry https://registry.npmmirror.com。

问题：如何配置 CC Switch 连接我的 Claude Code 或 Gemini CLI？

启动 CC Switch 后，点击主界面的“添加工具”按钮。
选择要配置的工具（如 Claude Code），输入其可执行文件路径（例如 /usr/local/bin/claude）。
如果工具需要 API 密钥，在对应字段中粘贴密钥（可从工具官方获取）。
点击“保存”，CC Switch 会自动检测并验证连接。如果失败，请检查路径是否正确、工具是否已安装。

问题：为什么 CC Switch 无法识别我安装的 Codex 或 OpenCode？

可能原因：

工具未添加到系统 PATH：确保工具安装后，其可执行文件所在目录已加入 PATH（Windows 需重启终端）。
版本不兼容：CC Switch 要求 Codex ≥ 1.2.0、OpenCode ≥ 0.5.0，请更新工具版本。
手动指定路径：在 CC Switch 设置中，直接输入工具完整路径（如 C:\Users\用户名\AppData\Local\Codex\codex.exe）。

问题：CC Switch 和直接使用终端运行 Claude Code 有什么区别？

统一管理：CC Switch 提供图形界面，可同时管理多个工具，无需在多个终端窗口间切换。
快速切换：一键切换当前使用的 AI 工具，无需重新输入命令或配置环境变量。
日志与监控：内置会话历史、输出日志和资源占用监控，方便调试和对比不同工具的表现。
跨平台：Windows、macOS、Linux 界面一致，减少系统差异带来的配置麻烦。

问题：使用 CC Switch 时，如何解决“工具响应超时”或“连接断开”？

检查网络：确保电脑能正常访问互联网（部分工具如 Gemini CLI 需要稳定网络）。
更新工具：运行 claude --version 或 gemini --version，确认工具版本为最新。
重启 CC Switch：关闭程序后重新启动，有时能解决临时连接问题。
查看日志：在 CC Switch 设置中开启“调试日志”，日志文件通常位于 ~/.cc-switch/logs/，可提供具体错误信息。

问题：CC Switch 是否支持自定义快捷键或主题？

支持。在“设置” → “快捷键”中，你可以为“切换工具”、“发送消息”、“清空会话”等操作绑定自定义快捷键。主题方面，CC Switch 内置了浅色和深色模式，并支持通过 CSS 文件自定义颜色方案（需在设置中导入 .css 文件）。

问题：CC Switch 与其他类似工具（如 Ollama、LM Studio）相比有什么优势？

专注命令行 AI 工具：CC Switch 专门针对 Claude Code、Codex、Gemini CLI 等命令行工具优化，而非通用模型运行器。
多工具并行：支持同时连接多个不同厂商的工具，并在它们之间快速切换，适合对比测试或混合使用。
轻量级：不依赖本地模型下载，仅作为管理界面，资源占用低。
官方支持：唯一官方网站为 ccswitch.io，提供持续更新和社区支持。

cc-switch 使用教程

1. 认识 cc-switch：它能解决什么问题？

2. 下载与安装：Windows / macOS / Linux 三步搞定

第 2 章：下载与安装：Windows / macOS / Linux 三步搞定

为什么这一章很重要？

开始前，你需要确认的事

第一步：找到下载入口

第二步：根据你的系统选对安装包

第三步：安装（真的就三步）

Windows 用户

macOS 用户

Linux 用户

安装后第一件事：验证一下

万一翻车了怎么办？

3. 5 分钟跑通第一个 AI 助手切换

第一步：看一眼你的“工具箱”

第二步：告诉 cc-switch 你的 AI 助手在哪

第三步：验证一下，它真的被记住了

第四步：真正切换一次，感受一下

第五步：切回来，再切过去

一个贴近真实场景的小例子

如果你遇到了问题

4. 添加与管理多个 AI 工具实例

前置条件

第一步：添加第一个“新朋友”——以Codex为例

第二步：批量添加，像搭积木一样

第三步：管理你的“工具库”——编辑、删除、排序

第四步：实战演练——一个“三合一”工作流

常见问题与排查

注意事项

5. 配置快捷键与全局热键

第 5 章：配置快捷键与全局热键

为什么要配置快捷键？

前置条件

第一步：打开设置

第二步：认识快捷键和全局热键

第三步：配置你的第一个全局热键

第四步：配置更多常用操作

常见问题与排查

一个小例子：打造你的“开发三键客”

6. 切换工作目录与项目上下文

为什么需要切换工作目录？

前置条件

第一步：查看当前工作目录

第二步：手动切换工作目录

第三步：使用“收藏夹”快速切换

添加收藏夹

管理收藏夹

第四步：切换工作目录时自动加载项目上下文

第五步：实战小例子

常见问题与排查

切换目录后，AI 助手没反应？

切换目录后，对话历史还在？

收藏夹里找不到我添加的目录？

切换目录后，AI 助手报错“找不到文件”？

7. 使用日志与历史记录排查问题

为什么你需要关心日志？

前置条件

第一步：找到日志文件

第二步：看懂日志内容

第三步：使用历史记录

第四步：用日志排查一个真实问题

第五步：清理日志文件

总结一下

8. 自定义主题与界面布局

先确认一下你到哪一步了

第一步：找到“皮肤”文件夹

第二步：创建一个最简单的自定义主题

第三步：深入调教——每个角落的颜色

第四步：布局也能调——不只是颜色

第五步：让主题随项目自动切换

第六步：分享你的主题

一个小例子串起来

常见报错与排查

9. 常见报错与解决方案

9.1 安装或启动时：command not found 或 cc-switch: 未找到命令

9.2 切换 AI 工具时：Error: [工具名] not found 或 Failed to launch [工具名]

9.3 快捷键或全局热键不生效

9.4 切换工作目录后，AI 工具不识别项目上下文

9.5 日志显示“权限不足”或“无法写入”

9.1 安装或启动时：`command not found` 或 `cc-switch: 未找到命令`

9.2 切换 AI 工具时：`Error: [工具名] not found` 或 `Failed to launch [工具名]`