X-AIO_FrameX-AIO
AI 编程工具Claude Code

使用 CC Switch 配置 Claude Code

以 macOS 为例安装 CC Switch 和 Claude Code，并通过 X-AIO 一键导入供应商配置。

CC Switch 是一款开源的 Claude Code 供应商配置管理工具。本教程面向第一次使用命令行工具的用户，以 macOS、CC Switch 3.20.0 和 Claude Code 2.1.245 为例，完整演示安装、一键导入 X-AIO 配置和首次验证。

Windows 用户请从 CC Switch 的 GitHub Releases 下载 Windows 安装程序，再按照安装向导完成安装。本教程后续以 macOS 为准；Windows、macOS 以及不同 CC Switch 版本中的按钮位置可能略有差异，但总体步骤相同。

中国内地用户请先阅读

Claude Code 官方服务目前不向中国内地用户开放。访问官方下载页面、下载安装组件、首次初始化或使用 Anthropic 官方服务时，可能需要 VPN 或代理；代理只能改善网络连通性，不能保证账号安全、账号可用或避免限制。请遵守所在地法律法规和 Anthropic 服务条款，并自行评估账号风险。

开始前请准备

请先在 Chrome 中登录 X-AIO Tokens Plan API 密钥页面。本教程不会要求你展示完整 API Key；不要点击密钥旁的眼睛图标，也不要把密钥放进截图、聊天或代码仓库。

1. 下载并安装 CC Switch（macOS）

从 CC Switch 官方下载页 或 GitHub Releases 下载。两个链接都是 CC Switch 项目公布的官方渠道。本教程实测版本为 v3.20.0，支持 macOS 12 及以上系统。

在页面底部展开 Assets，下载 CC-Switch-v3.20.0-macOS.dmg。这是同时支持 Apple 芯片和 Intel 芯片的 Universal 安装包；如果页面已经发布新版本，请优先下载最新版的 macOS .dmg 文件。

在 GitHub Assets 中点击 CC Switch macOS DMG 安装包

下载完成后，双击 .dmg 文件，再把 CC Switch 图标拖到 Applications 文件夹。

将 CC Switch 拖入 Applications 文件夹

从“应用程序”中打开 CC Switch。如果 macOS 显示“从互联网下载的 App”提示，请核对应用名称后点击 Open。第一次启动时会看到欢迎窗口，阅读说明后点击 我知道了。

CC Switch 首次启动欢迎窗口

安装安全提示

如果系统提示“应用已损坏”或“无法验证开发者”，请停止安装，并重新从 CC Switch 官方 GitHub Release 下载最新版。不要关闭 Gatekeeper，也不要使用命令绕过 macOS 的安全检查。

2. 将界面切换为简体中文

本教程中的按钮名称均以简体中文界面为准：

  1. 点击 CC Switch 左上角的 设置（齿轮图标）。
  2. 打开 通用。
  3. 在“界面语言”中选择 简体中文。如果已经选中，可以直接返回。

在 CC Switch 设置中选择简体中文

3. 安装 Claude Code

CC Switch 负责管理供应商配置，真正执行编码任务的是 Claude Code。可以直接用 CC Switch 完成安装：

  1. 在 设置 页面打开 关于。
  2. 向下找到“本地环境检查”中的 Claude Code。
  3. 如果“当前版本”显示“未安装”，点击卡片右下角的 安装。
  4. 等待安装完成；期间不要退出 CC Switch。网络无法访问官方下载服务时，可能需要 VPN 或代理。

在 CC Switch 中安装 Claude Code

安装结束后，点击“本地环境检查”右侧的 刷新。Claude Code 卡片出现绿色勾，并显示当前版本号，就说明安装成功。本教程实测的当前版本和最新版本均为 2.1.245；以后看到更高版本号也属于正常情况。

Claude Code 2.1.245 已安装

4. 创建专用 X-AIO API Key

打开 X-AIO API 密钥页面，点击 新建 API 密钥，然后按下面的示例填写：

  1. 密钥用途：CC Switch - Claude Code。
  2. 有效期：90 天。临时设备不建议使用永久密钥。
  3. 核对无误后点击 创建密钥。

为 CC Switch 和 Claude Code 创建 90 天 API Key

创建后不需要复制或展示密钥。接下来直接使用 X-AIO 提供的一键接入功能，把配置交给本机 CC Switch。

5. 一键导入 CC Switch

在刚创建的密钥卡片中找到最右侧的操作区。

这个按钮很小，最容易漏掉

点击密钥操作区最右侧、形状像“分支节点”的 一键接入客户端 图标。它不是复制按钮，也不是眼睛图标。

一键接入链接也属于敏感信息

只在自己的电脑上直接点击一键接入。不要复制、分享或截图一键接入链接，也不要把浏览器地址栏截进图片；链接中包含用于导入的 API Key，泄露链接等同于泄露密钥。

密钥卡片操作区红框内的一键接入客户端图标

在展开的菜单中选择 一键接入 CC Switch（Claude Code）。不要误选下面用于 Codex 的选项。

选择一键接入 CC Switch（Claude Code）

Chrome 随后会询问是否打开外部应用。点击 Open CC Switch，让浏览器把配置交给已经安装的 CC Switch；无需勾选 Always allow。

在 Chrome 中点击 Open CC Switch

CC Switch 打开“确认导入供应商配置”窗口后，逐项核对：

配置项应显示的内容
应用类型Claude
供应商名称X-AIO Tokens Plan
API 端点https://llm-api.x-aio.com
API 密钥保持隐藏，不要点击或展示
备注xaio-v2

API 端点末尾不需要 /anthropic 或 /v1，也不要自行添加其他路径。确认无误后点击 导入。

核对并导入 X-AIO Tokens Plan 供应商配置

6. 跳过首次安装确认并启用供应商

回到 设置 → 通用，开启 跳过 Claude Code 初次安装确认。这个开关只跳过 Claude Code 的首次安装确认流程，不会替你安装 Claude Code，也不会改变 Anthropic 的地区和账号政策。

开启跳过 Claude Code 初次安装确认

返回 CC Switch 首页，按下面的顺序启用刚导入的配置：

  1. 在页面顶部选择 Claude Code。
  2. 在供应商列表中点击 X-AIO Tokens Plan。
  3. 供应商卡片出现蓝色边框，表示当前已经切换到该供应商。

X-AIO Tokens Plan 已成为 Claude Code 当前供应商

导入和启用是两步

看到“导入成功”并不代表供应商已经启用。必须回到 Claude Code 的供应商列表，再点击一次 X-AIO Tokens Plan 卡片进行切换。CC Switch 通常可以让 Claude Code 热切换供应商；如果当前会话仍在使用旧配置，再退出 Claude Code 并重新启动。

截图中的 default 是 CC Switch 为本机已有配置创建的备份卡片，新安装的用户不一定会看到它，无需手动创建。

7. 在空文件夹中验证配置

Claude Code 可以读取和修改当前目录中的文件。第一次测试请使用自己新建的空文件夹，不要直接在重要项目或个人资料目录中启动。

打开 macOS 的“终端”，依次运行：

mkdir -p /tmp/xaio-claude-code-demo
cd /tmp/xaio-claude-code-demo
ls -A
claude

ls -A 没有输出时，说明测试文件夹为空。macOS 可能会把 /tmp 显示为 /private/tmp，两者指向同一个临时目录。如果命令列出了任何文件，请先不要运行 claude，换一个新的目录名称（例如 xaio-claude-code-demo-2）后重新检查。

如果 Claude Code 询问是否信任当前文件夹，请确认路径末尾是 xaio-claude-code-demo，选择 Yes, I trust this folder，再按回车键。不要在陌生或包含重要文件的目录中确认信任。

Claude Code 首次启动时确认信任空测试目录

进入对话后发送：

请只回复“配置成功”，不要创建或修改任何文件。

收到“配置成功”就说明 Claude Code 已通过当前供应商完成了一次真实请求。

Claude Code 通过 X-AIO Tokens Plan 返回配置成功

输入 /exit 退出 Claude Code，再检查测试文件夹：

ls -A

如果 ls -A 没有输出，说明文件夹仍为空。本教程已使用 Claude Code 2.1.245 完整验证：模型在空目录中正常回复“配置成功”，且没有创建文件。

常见问题

终端提示 claude: command not found

先回到 CC Switch 的 设置 → 关于，在“本地环境检查”中点击 刷新。如果 Claude Code 仍显示未安装，请重新点击 安装；如果已经显示绿色勾，请完全退出并重新打开“终端”，再运行：

claude --version

仍然找不到命令时，先确认 $HOME/.local/bin/claude 是否存在。如果存在，把 $HOME/.local/bin 加入 PATH，再重新打开终端：

export PATH="$HOME/.local/bin:$PATH"
claude --version

确认这样可以运行后，可把同一条 export PATH=... 加入 ~/.zshrc。Windows 用户请关闭并重新打开 PowerShell。

点击一键接入后没有打开 CC Switch

确认 CC Switch 已安装到“应用程序”，并至少手动启动过一次。回到 Chrome 再次点击 一键接入 CC Switch（Claude Code），出现外部应用提示时点击 Open CC Switch。如果系统阻止首次打开，请从“应用程序”手动打开 CC Switch 并处理 macOS 的标准安全提示，不要绕过 Gatekeeper。

启动 Claude Code 后仍要求登录 Anthropic

先确认 CC Switch 中的 跳过 Claude Code 初次安装确认 已开启，并且 X-AIO Tokens Plan 卡片有蓝色边框。供应商通常会即时切换；如果当前会话仍要求登录，请退出 Claude Code，再在测试文件夹中重新运行 claude。

显示导入成功，但 X-AIO 没有启用

返回 CC Switch 首页，在顶部选择 Claude Code，然后点击 X-AIO Tokens Plan 供应商卡片。只有卡片出现蓝色边框后，它才是当前供应商；如果当前 Claude Code 会话没有即时切换，再退出并重新启动。

请求长时间等待或提示网络超时

依次检查当前网络、VPN 或代理是否稳定，再确认 X-AIO API 密钥页面 中的密钥仍在有效期内，并检查 Tokens Plan 账户的可用额度。新建密钥可能需要短暂同步，可以等待约 1 分钟后重试。如果只有 Anthropic 官方页面无法访问，请同时注意上文说明的地区限制和账号风险。

使用 X-AIO Coding Helper 配置 Claude Code

使用 Claude Code 官方安装器和 X-AIO Coding Helper 当前 0.9.x 主线配置 Claude Code，完成四个模型、网关和首次请求验证。

使用 X-AIO Coding Helper 配置 OpenCode

使用 OpenCode 1.18.23 和 X-AIO Coding Helper 当前 0.9.x 主线配置 X-AIO Provider、主模型与小模型，并完成真实请求验证。

On this page

1. 下载并安装 CC Switch（macOS）2. 将界面切换为简体中文3. 安装 Claude Code4. 创建专用 X-AIO API Key5. 一键导入 CC Switch6. 跳过首次安装确认并启用供应商7. 在空文件夹中验证配置常见问题终端提示 claude: command not found点击一键接入后没有打开 CC Switch启动 Claude Code 后仍要求登录 Anthropic显示导入成功，但 X-AIO 没有启用请求长时间等待或提示网络超时