CC Switch

CC Switch 是面向 AI 编程 CLI 的桌面配置管理工具，不是 AI 客户端本身，也不会替代 Claude Code、Codex、OpenClaw 或模型服务。新手可以把它理解成 Provider 切换器：先安装真正要用的 CLI，再用 CC Switch 管理 AIDMX、模型和本地代理。

如果你只配置一个工具，先按对应页面直接配置会更容易排错；如果你要在 Claude Code、Codex、OpenClaw 等多个应用之间切换 AIDMX，CC Switch 更适合。

下载和官方入口

入口	用途
CC Switch 官方站点	查看产品入口、下载和功能概览。
CC Switch GitHub 仓库	查看源码、文档、Issues 和 Releases。
CC Switch Releases	下载 Windows、macOS、Linux 安装包。
CC Switch 用户手册	查看 Provider、代理、Deep Link 和应用切换说明。

平台支持

平台	推荐安装方式	说明
Windows	Releases 中的 MSI 或 Portable ZIP	安装后确认 ccswitch:// Deep Link 可被系统打开。
macOS	Homebrew cask 或 Releases 安装包	安装后把 CC Switch.app 放入 Applications 更稳。
Linux	.deb、AppImage 或 Arch 包	AppImage 需要执行权限；常驻应用可能需要重启下游 CLI 才生效。

CC Switch 管理的是下游工具配置。切换 Provider 后，仍需要打开 Claude Code、Codex 或 OpenClaw 发送测试消息，确认真实请求到达 AIDMX。

核心能力

• Provider 管理：为不同 CLI 保存独立 Provider，也可以创建 Universal Provider 同步到多个应用。
• 快速切换：在主窗口或系统托盘里按应用切换当前 Provider。
• 模型发现：对支持 OpenAI /v1/models 的上游，可以尝试拉取模型列表后再选择。
• 本地代理：为需要协议转换、应用接管、故障转移或请求日志的场景提供本地路由层。
• 扩展同步：统一管理 MCP、Prompts、Skills，并同步到支持的应用。
• 会话与用量：查看会话记录、请求日志、用量和自定义价格统计。
• Deep Link：通过 ccswitch:// 链接导入 Provider、MCP、Prompt 或 Skill。

AIDMX 字段速查

字段	推荐值
Provider 名称	AIDMX
API Base URL	https://ai.aidmx.xyz/v1
API Key	在 Token 页面 创建的 Token
Model	以 AIDMX 控制台当前可用模型名为准
Provider 类型	OpenAI Compatible、自定义 OpenAI 兼容服务，或应用中含义相同的选项
完整聊天端点	仅当工具要求完整 Endpoint 时填写 https://ai.aidmx.xyz/v1/chat/completions

如果你在 Claude Code 里接入 AIDMX，要先判断当前路径是否需要 Anthropic Messages 兼容。

AIDMX 的基础地址是 OpenAI 兼容 /v1；当下游工具期望 /v1/messages 时，不要直接把 AIDMX 当作 Anthropic 原生端点使用，优先让 CC Switch 的本地代理或 CCR 等工具负责转换。

安装后检查

1. CC Switch 主窗口能打开。
2. 系统托盘或菜单栏图标能打开应用菜单。
3. ccswitch:// Deep Link 能唤起 CC Switch。
4. 你要管理的下游 CLI 已经单独安装，例如 claude --version、codex --version 或 openclaw --version 能返回结果。

安装方式

macOS

Homebrew 安装：

brew tap farion1231/ccswitch
brew install --cask cc-switch

也可以从 Releases 下载 macOS 压缩包或安装包，解压后把 CC Switch.app 放入 Applications。

Windows

从 Releases 下载：

• CC-Switch-v{version}-Windows.msi
• CC-Switch-v{version}-Windows-Portable.zip

MSI 适合固定安装；Portable 版本解压后运行 CC-Switch.exe 即可。

Linux

Arch 系发行版：

paru -S cc-switch-bin

Debian / Ubuntu 下载 .deb 后安装：

sudo dpkg -i CC-Switch-v{version}-Linux.deb
sudo apt-get install -f

通用桌面环境可下载 .AppImage：

chmod +x CC-Switch-v{version}-Linux.AppImage
./CC-Switch-v{version}-Linux.AppImage

Web 入口

访问 CC Switch 官方站点或 GitHub Releases 选择平台包。安装完成后，浏览器中的 ccswitch:// 链接会交给本机 CC Switch 处理；你也可以从 AIDMX Token 页面打开应用配置入口。

配置 AIDMX

1. 打开 Token 页面，创建或复制一个 API Token。
2. 优先从 Token 行右侧的应用菜单选择 CC Switch，一键导入 Provider。
3. 如果一键导入成功，打开 CC Switch，确认对应应用页签中出现 Provider，且右侧显示"使用中"。
4. Codex 的默认名称通常是 My Codex；如果导入时改过名称，就以你设置的名称为准。
5. 打开对应 CLI，发送一条低风险测试消息。
6. 到 使用日志 确认请求已经到达。

只有一键导入失败、Windows 无法唤起 CC Switch、或打开后没有生成 Provider 时，才手动新增 Provider。手动新增时，在对应应用页签中点击加号，填写名称、API Key、Base URL https://ai.aidmx.xyz/v1 和模型名，保存后再启用。

Claude Code 兼容说明

Claude Code 常见接入路径有两种：

路径	何时使用	配置重点
Anthropic Messages 兼容	上游明确支持 Anthropic /v1/messages	直接使用对应 Anthropic 兼容地址，不要把 OpenAI /v1 强行当作 /messages
OpenAI Chat Completions 路由	上游只提供 OpenAI 兼容 /v1	在 CC Switch 中启用本地代理或应用接管，让代理把 Claude Code 请求转换到 chat completions

如果你看到 404、/messages not found、工具调用字段不兼容或流式响应异常，优先检查是不是把 AIDMX 的 OpenAI Base URL 直接填到了需要 Anthropic 协议的位置。

Deep Link 导入

CC Switch 支持 ccswitch:// 协议。Provider 导入链接的常见形态如下：

ccswitch://v1/import?resource=provider&app=claude&name=AIDMX&endpoint=https%3A%2F%2Faidmx.ltd%2Fv1&model=控制台可用模型&homepage=https%3A%2F%2Faidmx.ltd

参数说明：

参数	说明
resource=provider	导入 Provider
app=claude	目标应用，可按需改为 codex、gemini、opencode、openclaw
name=AIDMX	Provider 显示名称
endpoint	URL 编码后的 https://ai.aidmx.xyz/v1
model	控制台可用模型名
homepage	Provider 主页，可填 https://ai.aidmx.xyz

不要把含有真实 API Key 的 Deep Link 发到公开渠道。若要团队共享，建议只共享不含 apiKey 的链接，让成员在导入确认页自行填写 Token。

应用切换与生效

应用	切换方式	生效提示
Claude Code	主窗口启用 Provider，或托盘 Claude 子菜单切换	通常更接近热切换；如果使用代理或 shell 环境变量，仍建议重开会话验证
Codex	主窗口或托盘 Codex 子菜单切换	常需要关闭并重新打开终端
Gemini CLI	主窗口或托盘 Gemini 子菜单切换	通常会在下一次请求读取配置
OpenCode / OpenClaw	对应应用页签或 Universal Provider 同步	若应用长期驻留，切换后重启对应服务或 CLI 更稳

切换后不要只看 CC Switch UI，最好用下游 CLI 发一条测试消息，再看 AIDMX 使用日志确认真实上游。

成功验证

• AIDMX Provider 在 CC Switch 中显示为当前启用。
• 下游 CLI 能返回模型回复。
• 使用日志 中出现对应请求、模型和耗时。
• 更换到另一个 Provider 后，下游请求不再出现在原 Token 的日志中。

常见失败

保存后仍然走旧服务

先确认是否切换了正确的应用页签。Codex、OpenCode、OpenClaw 等常驻或终端型工具可能需要重启终端、CLI 或 Gateway 才会读取新配置。

Base URL 填 /v1 还是完整 endpoint

大多数 OpenAI 兼容客户端填写 https://ai.aidmx.xyz/v1。只有明确要求"完整聊天补全端点"的工具才填写 https://ai.aidmx.xyz/v1/chat/completions。

Claude Code 报 /messages 或协议错误

这通常说明当前链路期望 Anthropic Messages 协议。请改用 CC Switch 的 OpenAI Chat Completions 路由、本地代理接管，或阅读 CCR 使用 Claude Code Router 转接。

模型列表拉取失败

手动填写 AIDMX 控制台可用模型名即可。模型发现失败不一定代表聊天接口不可用。

Deep Link 无法打开

确认 CC Switch 已安装，并且系统注册了 ccswitch:// 协议。

• macOS：可重装应用或尝试通过 CC Switch 启动参数重新注册。
• Windows：检查 HKEY_CLASSES_ROOT\ccswitch。
• Linux：检查 .desktop 文件中的 MimeType。

官方链接

• CC Switch 官方站点
• CC Switch GitHub 仓库
• CC Switch Releases
• CC Switch 用户手册
• Deep Link 手册

下一步

• 如果不想使用桌面切换工具，参考 手动切换配置。
• 如果主要接入 Claude Code，阅读 Claude Code 和 CCR。
• 对普通 OpenAI 兼容客户端，参考 OpenAI 兼容工具。