CC-Switch 2026全平台安装指南：一条命令搞定Codex多供应商切换

做 AI 编程的开发者，最近大概率躲不开一个词：CC-Switch。如果你同时在用 OpenAI Codex、DeepSeek、Kimi 这类不同家的模型，并且已经受够了每次切换供应商都要手动改配置文件、改环境变量，那 CC-Switch 就是专门解决这个痛点的工具。它不改变你的 AI 编程流程，只是把“配置切换”这件事集中管理起来，一条命令就能整体切走。这篇文章是 2026 年最新的下载安装与全平台配置指南，覆盖 Windows、macOS、Linux 三个系统，从环境检查到供应商录入，再到和 VS Code、Codex CLI 联动，一次讲完。

如果你在安装 Codex 桌面版或者 ChatGPT 桌面版时遇到“安装未完成”的提示，别急着重装系统，先把本文前半部分的依赖检查做了。多数情况下，安装失败不是工具本身的问题，而是缺了运行库或者代理环境没配好。下面我直接按实操顺序来，每一步都给出命令和解释。

1. CC-Switch 到底解决什么问题

先说个实际场景。我日常写代码会同时在 Codex CLI 里接 DeepSeek 的模型，也会切到 OpenAI 的模型做对比测试。Codex 的配置在~/.codex/config.toml，里面写模型供应商列表，每次切换要不改model字段，要不改model_provider字段。手动改几次还能忍，改多了就容易出问题：base_url 写错、token 漏填、模型名带不带前缀不统一，经常排查半天才发现是配置串了。

CC-Switch 做的事情，就是把“当前使用哪家供应商”这个状态单独保存下来，你把所有供应商信息录进去之后，它帮你修改对应的 Codex 或 Claude Code 配置文件。等于说，你不需要关心底层文件长什么样，只需要告诉它“我现在要用 DeepSeek”，它就帮你把一套完整的配置对准了。

这个思路跟开发环境里的 env 管理工具很像，但 CC-Switch 的定位更垂直：只针对 AI 编程工具的供应商配置。好处是逻辑简单，出问题好排查，也不用理解一整套编译流程。坏处是它不对应某个具体的公司，而是社区维护的开源项目，所以你在官网看到的版本可能跟一些博客里写的不同，属于正常现象。

对应到热搜词里频繁出现“cc-switch 官网”“cc-switch 下载”“cc-switch 怎么用”，说明大家对下载渠道和基础操作最关心。后面几节我就把三个平台的安装和核心用法完整走一遍。

1.1 它管理的是哪些配置文件

在开始安装之前，理解配置文件的位置很重要，后面排查问题会用到。

  • Codex CLI 的配置文件：~/.codex/config.toml，里面包含模型提供商、模型名、API 密钥等。
  • Claude Code 的配置文件：~/.claude/settings.json，里面包含ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN等环境变量。

CC-Switch 在 Windows 下的路径会变成用户主目录下的隐藏目录，比如C:\Users\你的用户名\.codex\config.toml。macOS 和 Linux 下路径基本一致，都是以波浪号开头。安装完 CC-Switch 之后，它自己也会生成一个配置目录，比如~/.cc-switch/config.json，这个文件保存的是你录入的供应商清单，属于 CC-Switch 自己的记忆体，跟你家路由器保存的拨号账号是一个意思。

有一点需要提前说：CC-Switch 不存储大模型供应商的账号密码，它只保存 API 密钥的引用关系。也就是说，你录入信息时填了密钥，它会写进对应的 Codex 配置里，但不会主动上传到任何第三方服务器。密钥的保管责任始终在你手里。

1.2 为什么需要全平台支持

很多类似的配置管理工具一开始只做 macOS，后来才补 Windows。CC-Switch 在 2026 年的版本里把三个平台拉平了，原因很直接：用 AI 编程的人并不仅仅是 Mac 用户，Windows 用户的比例一点都不低。有人用公司发的 Windows 笔记本开发，有人家里的 Linux 机器专门跑模型测试，还有人会在一台 Windows 台式机上装 WSL 来做开发。

所以这版教程我会按平台拆开写，尽量考虑不同平台的细节差异。比如 Windows 下路径分隔符是反斜杠，一些命令行工具需要加./前缀；macOS 首次运行需要处理“已损坏”提示；Linux 下Node.js 的安装源不同会导致版本差异。这些细节不处理，安装过程很容易卡住。

2. 安装前的环境检查与依赖准备

不管哪个平台，装之前先做三件事：确认系统架构、确认 Node.js 环境、确认命令行终端能正常使用。虽然 CC-Switch 有些版本提供界面化安装包，但底层依然依赖 Node.js 运行时，所以这一步省不掉。

2.1 用一条命令检查系统信息

我见过很多人装不上软件，最后发现是下载了错误的架构版本。CC-Switch 的安装包通常分x64和arm64两种，Apple Silicon 的 Mac 必须下arm64，Windows 上大多数 Intel 和 AMD 处理器用x64，而 Windows on ARM 的机器比较少见，下载前要确认清楚。

macOS 终端执行：

uname -m

Linux 执行：

uname -m

Windows 在 PowerShell 里执行：

[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture

输出如果是arm64，就找对应的 arm64 安装包；如果是x86_64或AMD64，就选 x64。这个判断直接影响后面的安装是否成功，比任何依赖都重要。

2.2 Node.js 版本与 npm 镜像

CC-Switch 当前版本要求 Node.js 18 以上。这个要求不算高，但很多老机器上装的是 Node 16，运行时会直接报语法错误。

检查 Node 版本：

node -v npm -v

CentOS 或 Ubuntu 自带的包管理器通常安装的是比较旧的版本，建议直接到 Node.js 官网下载 LTS 版本，或者用 nvm 管理版本。我自己的习惯是用 nvm，因为后面在多个 Node 版本之间切换项目时非常从容。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

安装完成后重新打开终端，执行nvm install 20就可以装一个稳定版本。如果网络下载慢，可以考虑配置一下 npm 镜像，但这属于可选优化项，默认源在国内某些网络环境下确实慢，但一般多等一会儿也能完成。

注意：如果你之前装过其他 AI 编程工具，环境里可能已经存在一套 Node 和 Python 环境。CC-Switch 安装过程中不需要 Python，但是后续配置供应商时，某些模型服务商提供的命令行工具可能需要 Python 3.9 以上。建议顺手检查一下python3 --version。

2.3 Windows 特有的运行库问题

Windows 平台上安装 CC-Switch，最容易踩的坑是缺少 Visual C++ Redistributable。它本身不是 CC-Switch 的依赖，但安装包里的某些原生模块编译需要 MSVC 运行库。

解决办法是到微软官网下载最新的 “Visual C++ Redistributable for Visual Studio 2015-2022” 安装包，以及 “.NET Desktop Runtime”。官方安装包在安装时一般会有提示，如果没提示也可以主动装一遍。

另外，Windows 的 PowerShell 默认执行策略是 Restricted，直接运行一些.ps1脚本会被拦截。你需要在管理员权限下执行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

这里RemoteSigned的意思是本地脚本可以运行，从网上下载的脚本需要签名。设置完之后，CC-Switch 的安装脚本和后续的升级命令都不会再被 PowerShell 拦下来。

3. Windows 平台安装教程

Windows 用户安装 CC-Switch 主要有两种方式：下载官方安装包，或者通过 npm 全局安装。两条路我分别说清楚，推荐普通用户用安装包，喜欢命令行的用 npm。

3.1 方式一：官方安装包

从 CC-Switch 官网或 GitHub Releases 页面下载 Windows 安装包。文件名一般是CC-Switch-版本号-win-x64.exe。下载完成后双击运行。

安装流程跟普通 Windows 软件没有区别，但有两个地方要注意：

第一，安装目录尽量不要放在带中文或空格的路径下。比如D:\Program Files没问题，但如果自己创建一个文件夹叫“工具”，后续某些 shell 脚本可能因为编码问题找不到路径。推荐统一放到C:\Users\你的用户名\AppData\Local\Programs\cc-switch，或者自己建一个纯英文目录。

第二，安装过程中如果杀毒软件弹出提示，不要直接点“允许”或“阻止”就完事，先看一下报毒的是哪个文件。CC-Switch 是开源项目，不存在恶意代码，但某些国产杀软对命令行工具误报率偏高。确认文件来源是 GitHub Releases 或官网后，可以加入信任列表。

安装完成后，开始菜单里会出现 CC-Switch 的快捷方式，点击即可启动图形界面。如果你下载的是命令行版本，打开 PowerShell，输入：

cc-switch --version

看到版本号输出说明安装成功。

3.2 方式二：npm 全局安装

如果你已经在用 npm 管理其他前端工具，直接全局安装是最方便的方式。PowerShell 里执行：

npm install -g cc-switch

等到输出added xxx packages后，验证一下：

cc-switch --help

如果提示“无法识别”，说明 npm 的全局安装目录没有加入 PATH。解决方法是找到 npm 的全局目录：

npm prefix -g

然后把输出的路径手动加到系统环境变量 Path 里。修改完环境变量需要重启终端，否则不生效。

npm 方式更新的好处特别明显。以后升级版本只需要执行：

npm update -g cc-switch

不需要再重新下载安装包，对经常跟进新版的开发者非常友好。

3.3 Windows 下首次启动的验证方法

启动之后，先别急着录入供应商，验证一下工具是否正常工作。命令行执行：

cc-switch doctor

这个命令会检查系统环境、目录权限和配置文件的读写状态。正常情况会输出几行绿色或普通颜色的 “OK”。

如果出现红色报错，比如“EACCES: permission denied”，说明当前用户对~/.codex目录没有写权限。在 Windows 上，这个目录通常在C:\Users\你的用户名\.codex，右键查看属性，确认当前用户的权限是不是“完全控制”。这一步卡住的概率不小，因为 Codex CLI 自己创建这个目录时可能用了默认权限，而后续切换配置需要写入，遇到权限问题就必须手动放开。

4. macOS 平台安装教程

macOS 平台的安装步骤跟 Windows 类似，但有几个“mac 专属”问题必须提前说明，免得你折腾老半天还找不到原因。

4.1 下载安装包与“已损坏”的处理

从官网下载.dmg文件后，双击挂载，然后把 CC-Switch 拖到 Applications 文件夹。第一次打开如果提示“已损坏，无法打开”，通常并不是文件真的坏了，而是系统安全策略拦住了未经 App Store 认证的应用。

解决方法：打开“系统设置-隐私与安全性”，滚动到最下方，看到“仍要打开”按钮，点击并确认。这一步是 macOS 的标准操作，不是 CC-Switch 独有的问题。

如果连“仍要打开”都没有出现，可以在终端执行：

sudo xattr -rd com.apple.quarantine /Applications/CC-Switch.app

把隔离属性去掉后再次打开。这个命令在 Intel 和 Apple Silicon 上都适用，但 Apple Silicon 上如果遇到其他权限提示，还需要去“系统设置-隐私与安全性-完全磁盘访问权限”里把终端或 CC-Switch 添加为允许访问的应用。

4.2 Homebrew 安装方式

用 Homebrew 安装会更符合 macOS 用户的使用习惯。在终端执行：

brew install cc-switch

如果你没有 Homebrew，先装：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成之后，Homebrew 会自动把可执行文件软链接到/opt/homebrew/bin或/usr/local/bin，这两个目录一般已经在 PATH 里，直接执行：

cc-switch --version

4.3 Apple Silicon 的路径注意事项

M 系列芯片的 Mac 上，Homebrew 的安装目录是/opt/homebrew，而 Intel Mac 是/usr/local。如果你在 M 系列 Mac 上执行which cc-switch发现是在/opt/homebrew/bin，那就对了。如果显示not found，可以在~/.zshrc里加上：

export PATH="/opt/homebrew/bin:$PATH"

然后执行source ~/.zshrc让配置生效。

macOS 上还有一个常见问题：终端工具的配置目录~/.codex默认是隐藏目录，在 Finder 里看不到，但终端能正常访问。这不是工具出了问题，别去折腾显示隐藏文件的设置。

5. Linux 平台安装教程

Linux 用户安装 CC-Switch 的路径要多一点，但也最灵活。我这里按 Ubuntu/Debian 系和 CentOS/RHEL 系分别说明，顺便讲一下没有图形界面的服务器怎么配置。

5.1 在 Ubuntu/Debian 上安装

先确认系统包管理器是最新的：

sudo apt update sudo apt upgrade -y

然后用 npm 全局安装，或者下载.deb安装包。.deb方式适合不喜欢 npm 的用户：

sudo dpkg -i cc-switch_版本号_amd64.deb

安装后会生成/usr/bin/cc-switch，直接执行即可。如果下载的是.AppImage文件，需要先赋予执行权限：

chmod +x CC-Switch-版本号.AppImage ./CC-Switch-版本号.AppImage

AppImage 的好处是免安装，一个文件直接运行，适合在 U 盘或者临时环境里使用，缺点是每次运行都要手动给执行权限。

5.2 在 CentOS/RHEL 上安装

CentOS 默认的 Node.js 版本通常很低，可能只有 16，所以要先解决 Node 版本问题。

sudo yum install -y nodejs npm

如果node -v显示版本低于 18，推荐使用 nvm 安装新版本。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.bashrc nvm install 20 nvm alias default 20

然后安装 CC-Switch：

npm install -g cc-switch

另外提醒一点：服务器上如果禁用了外网访问，npm 安装会失败。你需要提前下载好 npm 包，或者在公司内网搭一个 npm 私服。这不是 CC-Switch 特殊的问题，而是所有 npm 包共有的安装前提。

5.3 无图形界面环境下的命令行配置

无桌面环境的 Linux 服务器上，没有图形界面可以点，但 CC-Switch 命令行模式完全够用。

cc-switch list cc-switch use deepseek

第一条命令列出所有已录入的供应商和当前使用的供应商，第二条命令切换到指定供应商。这个模式下，每次切换都会检查配置文件是否能正常访问，如果~/.codex目录不存在，它会提示你先运行一次 Codex CLI，或者手动创建目录。

提醒：Linux 上如果当前用户是 root，程序默认读取的路径是/root/.codex而不是/home/用户名/.codex。很多人在这上面吃过亏，明明配置写了，切换却不生效，一查发现读错了目录。

6. 核心配置与供应商管理

安装只是第一步，真正决定 CC-Switch 好不好用的，是供应商管理。这一节我把配置文件读写逻辑、添加供应商、多供应商切换完整过一遍。

6.1 配置文件读写逻辑

CC-Switch 的工作流程可以拆成三步：

  1. 读取 CC-Switch 自己的配置目录~/.cc-switch/config.json，拿到供应商清单。
  2. 根据你选中的供应商，拼装出 Codex 或 Claude Code 需要的那一段配置。
  3. 写入~/.codex/config.toml或~/.claude/settings.json。

所以，这本质上是一个“配置生成器”。它不会侵入操作系统，也不会常驻后台。每次切换都是读、组装、写三个动作，逻辑非常干净。

这意味着如果哪天你发现 CC-Switch 不生效了，先别急着卸载重装，直接打开对应的配置文件，看看里面的 base_url 和模型名是不是对的。如果配置文件里是正确的，那就说明 CC-Switch 没劫持你的修改，还能正常使用；如果配置文件还是旧的，再看是不是 CC-Switch 的配置目录出了问题。

6.2 添加一个供应商：以 DeepSeek 为例

这里我用 DeepSeek 作为例子，因为它是目前国内开发者用得比较多、且兼容 OpenAI 协议的模型服务商。添加供应商有两种方式。

第一种，命令行交互式添加。执行：

cc-switch add

然后按提示输入供应商名称、API 地址、模型名和 API Key。以 DeepSeek 为例，填写内容大致是：

  • 名称：deepseek
  • Base URL：https://api.deepseek.com/v1
  • 模型：deepseek-chat
  • API Key：填你自己的密钥

第二种，直接编辑配置文件。在~/.cc-switch/config.json里手动添加一段：

{ "name": "deepseek", "baseURL": "https://api.deepseek.com/v1", "model": "deepseek-chat", "apiKey": "sk-xxx" }

两种方式本质一样，图形界面或者交互式命令更不容易写错 JSON，手动编辑快但容易漏逗号。

添加完成之后，执行：

cc-switch list

看到 deepseek 出现在列表里，并且前面没有星号，说明已经录入成功。

6.3 多供应商切换实战

假如你录入了三条供应商：openai、deepseek、kimi。想从 openai 切到 deepseek，只需要：

cc-switch use deepseek

切换完成后，再执行：

cc-switch current

确认当前生效的是 deepseek。此时打开~/.codex/config.toml，会发现model_provider已经自动变成 deepseek，相关的 base_url 和模型名也同步更新。

这里有一个细节值得注意：CC-Switch 在切换时，会不会覆盖我正在用的对话上下文？答案是不会。它只改配置文件，不改 Codex 的会话历史。所以切换后再执行codex命令，会以新配置启动一个新的会话，但之前的会话记录还在，不会丢。

如果你的 Codex 里同时运行着多个会话，切换配置后需要重启 Codex CLI 才能让新配置生效。图形界面版的 Codex 可能不会自动检测配置文件变化，所以养成“切完重启会话”的习惯比较稳妥。

7. 与 Codex、VS Code 配合使用的进阶技巧

绝大多数人用 CC-Switch，都是为了让 Codex 或 VS Code 里的 AI 插件能更顺利地切换后端。这一节专门讲配合使用的姿势。

7.1 Codex CLI 的配置联动

Codex CLI 在 2026 年的版本里已经支持多供应商配置，通过~/.codex/config.toml来维护。文件结构大致长这样：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

如果你的 Codex 安装目录里没有config.toml，先手动跑一次:

codex --version

让它自动生成默认配置，然后再用 CC-Switch 接管。

另外，很多人不知道 Codex 还支持--config参数指定配置文件路径。如果你不想动默认配置，可以给不同项目准备不同配置，在项目根目录执行：

codex --config ~/.codex/config-deepseek.toml

不过，CC-Switch 本身只管理默认配置文件，如果你用了自定义配置文件，切换操作只作用于默认配置那一份。这个要提前有心理预期。

7.2 VS Code 里的使用经验

VS Code 本身不直接调用 CC-Switch，但很多 AI 插件会读取 Codex 的配置文件。也就是说，你在终端里用cc-switch use deepseek切换之后，重新加载 VS Code 窗口，插件就会使用新的供应商。

如果你的插件没有重新加载配置，按Ctrl+Shift+P，输入 “Reload Window”，回车即可。这个操作比重启 VS Code 快得多。

还有人喜欢在 VS Code 的终端面板里直接执行切换命令，好处是切换完不用切窗口。我个人的做法是：给终端面板单独开一个 shell profile，默认加载好 CC-Switch 的路径和命令别名，然后在这个终端里执行切换，快速又稳定。

一个比较隐蔽的问题：VS Code 的集成终端可能继承了一些额外的环境变量，比如OPENAI_API_KEY。当 Codex 同时读到环境变量和配置文件里的env_key时，某些版本会优先读环境变量，导致你明明切到了 DeepSeek，实际请求还是发给了 OpenAI。解决思路是检查一下系统里有没有设置过OPENAI_API_KEY这类变量，如果有，要么删掉，要么在切换后手动确认一下该变量是否指向了正确的密钥。

7.3 与 Claude Code 的配合

如果你还用 Claude Code，那么 CC-Switch 对应的配置文件是~/.claude/settings.json。里面通常包含：

{ "env": { "ANTHROPIC_BASE_URL": "https://api.xxx.com", "ANTHROPIC_AUTH_TOKEN": "sk-xxx", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

这里ANTHROPIC_AUTH_TOKEN是 Claude Code 读取的密钥字段，而 Codex 用的是配置文件里的env_key，两者机制不同，但 CC-Switch 会帮你处理这个差异。只需要在录入供应商时注意，要选择对应的目标工具类型是 Codex 还是 Claude Code。

如果你同时使用 Codex 和 Claude Code，而且共用同一个供应商 API，需要在录入时分别添加两条记录：一条标记为 Codex 用，一条标记为 Claude Code 用。因为两个工具的配置文件格式完全不同，不能共用一条记录直接派的。

8. 局域网代理与自定义扩展场景

前面提到的都是本地单机使用。有些场景下，你可能希望同一台机器上的多个终端，甚至局域网里的其他设备都能共用同一个 AI 供应商配置，这就轮到局域网代理功能登场了。注意，这里说的是局域网内开发协作场景的代理，不是用来访问任何受限资源的，功能本身完全合法。

8.1 开启局域网访问

CC-Switch 在较新版本里提供了本地服务模式，可以在某个端口起一个小服务，让局域网内的其他设备也能看到当前配置的供应商列表，并执行切换。常用场景是：你的开发机跑着一个 Codex 服务供其他同事的电脑连接，或者你用一台 Linux 服务器统一管理团队里的 AI 供应商配置。

开启方式：

cc-switch serve --host 0.0.0.0 --port 8756

--host 0.0.0.0表示监听所有网卡，局域网内的其他设备可以通过http://开发机IP:8756访问。如果只想让本机访问，去掉--host参数，让它默认监听 127.0.0.1 即可。

开启后，局域网里另一台机器可以在命令行里配置：

cc-switch remote add http://192.168.1.100:8756

然后通过cc-switch use deepseek来触发远端配置切换。这个模式适合团队内部用一个公共账号统一管理密钥的场景，省得每台机器都配一遍 API Key。

不过要提醒的是，局域网代理服务默认没有鉴权。如果团队内有其他人，建议在服务器前面套一层简单的访问控制，或者只在可信网络环境开启。生产环境里最好用反向代理加访问口令，别直接裸奔。

8.2 自定义供应商参数

有些模型服务商并不完全兼容 OpenAI 协议，比如某些聚合平台需要自定义请求头，或者模型名要带特定前缀。CC-Switch 支持在供应商配置里追加自定义字段。

在交互式添加时，选择 “高级选项”，填入额外的 header 参数，比如：

HTTP-Referer: https://your-site.com X-Title: my-app

如果是手动编辑 JSON，可以加一个extraHeaders字段：

{ "name": "custom-provider", "baseURL": "https://api.example.com/v1", "model": "gpt-4o-mini", "apiKey": "sk-custom", "extraHeaders": { "HTTP-Referer": "https://your-site.com", "X-Title": "my-app" } }

这个功能在我对接一些国内模型聚合平台时特别有用，很多平台要求带来源标识才能使用免费额度或提高速率限制。没有这个功能，每次切到这些平台都要手动改配置文件。

8.3 多用户切换时的冲突处理

开发和测试经常同时进行，多个人同时通过局域网代理操作时，会出现配置互相覆盖的情况。比如你在切换 deepseek，同事那边同时切到了 kimi，最后写入的配置会覆盖之前的。

CC-Switch 的服务端在处理并发写入时，用的是“最后一次写入覆盖”的策略。要避免这个问题，建议团队内部约定一个使用规则：比如只有负责配置管理的人才可以执行切换，其他人都用只读模式。CC-Switch 支持--readonly参数运行服务端，开启后其他设备只能查看配置，不能切换。

cc-switch serve --host 0.0.0.0 --port 8756 --readonly

这样既能满足查看需求，又不会把配置改乱。

9. 常见问题与排查技巧

这一节我把实际操作中踩过的坑、以及社区里反馈比较多的问题整理成一个速查表，方便你遇到问题时直接对照处理。

9.1 高频问题速查表

问题现象可能原因排查方法
Windows 安装后命令找不到npm 全局路径没加入 PATH执行npm prefix -g，把输出目录加进系统 Path
macOS 打开提示“已损坏”隔离属性未去除执行sudo xattr -rd com.apple.quarantine /Applications/CC-Switch.app
Linux 下切换后不生效读取了错误的用户目录确认是/root/.codex还是/home/用户/.codex
切换后 Codex 仍请求旧供应商环境变量覆盖了配置文件检查OPENAI_API_KEY等环境变量是否残留
配置文件被改乱JSON 语法错误导致回滚先执行cc-switch doctor检查配置完整性
局域网设备无法访问服务防火墙拦截或 host 绑定错误确认--host 0.0.0.0参数，然后检查系统防火墙
安装时提示 “EACCES permission denied”当前用户无写权限给对应目录授权或使用管理员终端执行

9.2 安装 Codex/其他工具时 “未完成”的处理

热搜词里反复出现 “codex windows安装未完成”“chatgpt windows安装未完成”，这里顺带说一下。多数情况下，这类安装程序跑到一半退出，是下面几个原因：

  • 网络连接不稳定，下载大文件中断。解决方法是使用断点续传良好的下载工具，或者重新下载安装包。
  • 系统缺少必要的运行库，尤其是 Visual C++ Redistributable。
  • 安装程序权限不足。Windows 下右键“以管理员身份运行”，macOS 下确认磁盘镜像挂载正常。
  • 安全软件拦截了安装进程。这个比较隐蔽，需要去杀毒软件隔离区里找记录。

要是你确认这些问题都没有，但安装还是失败，不妨打开 Windows 事件查看器或者 macOS 的统一日志，找到安装程序对应的错误码，再根据错误码搜索解决方案。这一步看起来很麻烦，其实比反复重装更省时间。

9.3 配置不生效的独家排查思路

这里分享一个我自己摸索出来的排查顺序。当你执行了cc-switch use foo，但打开 Codex 后发现还是旧配置，按下面顺序检查：

  1. 先执行cc-switch current，确认 CC-Switch 认为当前生效的是哪个供应商。
  2. 再打开~/.codex/config.toml，看里面的model_provider字段是不是变了。
  3. 如果配置文件变了但 Codex 没生效，重启 Codex 进程。
  4. 如果配置文件没变，执行cc-switch doctor看有没有目录权限方面的报错。

这套顺序能定位 90% 以上的问题。大多数人卡在第二步到第三步之间，以为切换成功就等于 Codex 会立刻读取新配置，实际上很多 CLI 工具启动时才读取配置文件，不重启不生效。

9.4 备份与回滚建议

修改配置文件之前，最好先备份一份原始配置。CC-Switch 本身会在切换前自动生成备份文件，放在~/.cc-switch/backups/目录下。如果你手动编辑过配置文件，一定要养成先复制一份的习惯。

回滚命令：

cc-switch rollback

它会恢复到切换之前的那份配置。如果你执行了好几次切换，想恢复到更早的版本，可以直接访问备份目录，把对应时间戳的配置文件复制回原位置。我之前有次手滑删掉了一个供应商，就是靠备份目录救回来的。

这种细节平时不起眼，真出问题时比任何高级功能都管用。

最后说一点体会

用 CC-Switch 大半年，我最大的感受是它把一个“低频但必须正确”的操作变得不再费脑子。以前切换供应商，我要记着不同工具的配置格式，每次小心翼翼防止改错。现在统一交给它管，反而有时间更关注模型选型和代码质量本身。如果你跟我一样在多个 AI 编程供应商之间反复横跳，花十分钟把环境配好，后面省下的时间一定超出预期。最后再分享一个小建议：刚装好 CC-Switch 时，先别急着导入所有供应商，只录一两个常用的，跑通整个切换流程，确认无误后再批量添加。这样即使出现问题，范围也被控制得很小，排查起来从容得多。