> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hostlinku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CC Switch

> 通过 CC Switch 桌面应用程序（macOS、Windows、Linux），以可视化方式管理和更换 Claude Code、Codex CLI 以及 OpenCode 的 Hostlinku 提供商、模型和 API 密钥。

[CC Switch](https://github.com/farion1231/cc-switch) 是一款开源的跨
平台（macOS、Windows、Linux）桌面应用程序，用于通过单一图形界面管理 **Claude Code**、**Codex CLI** 和
**OpenCode** 的配置，通过单一图形界面进行管理。无需手动编辑 `~/.claude/settings.json` 或
`~/.codex/config.toml`，你可以保存 Hostlinku 提供商的配置文件，从
`/v1/models` 自动获取模型列表，并只需单击一下（或通过
*系统托盘*图标）即可切换模型/密钥。

## 安装 CC Switch

请根据您的操作系统选择安装方法：

**macOS (Homebrew)：**

```bash theme={null}
brew tap farion1231/ccswitch
brew install --cask cc-switch
```

或者从
[GitHub Releases](https://github.com/farion1231/cc-switch/releases) 下载 `.dmg` / `.tar.gz` 文件。

**Windows：**

从
[GitHub Releases](https://github.com/farion1231/cc-switch/releases) 下载安装程序 `CC-Switch-v*-Windows.msi` 或便携版 `.zip`。

**Linux：**

```bash theme={null}
# Arch Linux (AUR)
paru -S cc-switch-bin
```

对于 Ubuntu/Debian/Fedora 及其他发行版，请从
[GitHub 发布页面](https://github.com/farion1231/cc-switch/releases) 下载 `.deb`、`.rpm` 或 `.AppImage` 包。

***

## 一键快速导入（深度链接）

CC Switch 支持 `ccswitch://v1/import` 协议。安装 CC Switch 后，在终端中执行
以下命令（或在浏览器中打开该 URL），即可自动填写 Hostlinku 提供商的表单
——您只需在确认对话框中粘贴 API 密钥 `sk-…` 即可。

**导入 Hostlinku 的预设以供 Claude Code 使用：**

```bash theme={null}
# macOS: open "ccswitch://..." | Linux: xdg-open "ccswitch://..." | Windows: start "" "ccswitch://..."
open "ccswitch://v1/import?resource=provider&app=claude&name=Hostlinku&homepage=https%3A%2F%2Fhostlinku.com&endpoint=https%3A%2F%2Fapi.hostlinku.com&model=claude-sonnet-4-6&haikuModel=deepseek-v4-1-flash&sonnetModel=claude-sonnet-4-6&opusModel=claude-opus-4-6"
```

**导入 Hostlinku 的 Codex CLI 预设：**

```bash theme={null}
open "ccswitch://v1/import?resource=provider&app=codex&name=Hostlinku&homepage=https%3A%2F%2Fhostlinku.com&endpoint=https%3A%2F%2Fapi.hostlinku.com%2Fv1&model=gpt-5-5"
```

***

## 通过 CC Switch 连接 Claude Code

### 在 Console 中创建 API 密钥

打开 [console.hostlinku.com](https://console.hostlinku.com) → **API Keys**，创建新密钥（例如
`cc-switch-claude`），然后复制 `sk-…` 的值。

### 在“Claude”选项卡中添加提供商

1. 打开 **CC Switch**，然后在顶部栏中选择 **Claude** 应用。
2. 点击右上角的 **+** 按钮（*Add Provider*），然后选择 **Custom Configuration**。
3. 请填写以下主要字段：

| 字段 | 值 |
| - | - |
| **提供商名称** | `Hostlinku` |
| **网站 URL** | `https://hostlinku.com` |
| **API Key** | `sk-your-api-key` |
| **请求 URL（基础 URL）** | `https://api.hostlinku.com` |
| **API 格式** | `Anthropic Messages (Native)` |

### 自动填充或提取模型列表

在模型配置部分点击 **Auto-Fetch Models** 按钮。CC Switch 将使用您的 API 密钥调用
`GET https://api.hostlinku.com/v1/models`，并显示该 Service Mode 密钥下
所有可用的模型。

或者按照推荐的组合方式编写手册：

| Slot Model Claude Code | Hostlinku 的 Slug 建议 | 注释 |
| - | - | - |
| **默认模型** | `claude-sonnet-4-6` | 编码示例的主要模型。 |
| **Opus 模型** | `claude-opus-4-6` | 用于规划（*plan mode*）及重大重构。 |
| **Sonnet 模型** | `claude-sonnet-4-6` | 每日代码执行。 |
| **Haiku (Fast) 模型** | `deepseek-v4-1-flash` 或 `claude-haiku-4-5` | 后台子代理及成本节约概述。 |

### 启用提供商

点击 **Add**，然后在 **Hostlinku** 卡片上点击 **Enable**（或从 *系统托盘* 菜单中选择）。
CC Switch 会自动将 `env` 代码块写入 `~/.claude/settings.json`。打开新终端并运行
`claude` — 输入 `/status` 以确认 `ANTHROPIC_BASE_URL` 已指向
`https://api.hostlinku.com`。

***

## 通过 CC Switch 连接 Codex CLI

### 选择“Codex”选项卡并添加提供商

1. 在 CC Switch 中，请在顶部栏中选择 **Codex** 应用。
2. 点击 **+**（*添加提供商*）→ **自定义配置**。
3. 请填写以下配置内容：

| 字段 | 值 |
| - | - |
| **提供商名称** | `Hostlinku` |
| **API Key** | `sk-your-api-key` |
| **端点（基础 URL）** | `https://api.hostlinku.com/v1` |
| **模型** | `gpt-5-5`（或 `gpt-6-astra`、`gpt-6-sol`） |

请确保在 `config.toml` 文件底部的预览中，`wire_api` 字段的值为 `"responses"`：

```toml theme={null}
model = "gpt-5-5"
model_provider = "hostlinku"

[model_providers.hostlinku]
name = "Hostlinku"
base_url = "https://api.hostlinku.com/v1"
wire_api = "responses"
```

### 启用并运行 Codex

在 **Hostlinku** 卡片上点击 **Add**，然后点击 **Enable**。CC Switch 会自动更新
`~/.codex/config.toml` 并将 API 密钥保存到 `~/.codex/auth.json` 中。在终端中运行 `codex`
即可开始使用。

按服务模式划分配置文件

您可以在 CC Switch 中创建三个不同的服务商卡片——例如 **Hostlinku (Performance)**、
**Hostlinku (Economy)** 和 **Hostlinku (Dedicated)**——每张卡片均配有相应的 API 密钥。
当需要从节俭模式切换到快速模式时，只需在 CC Switch 中点击所需的卡片，
无需操作终端。

检测环境变量冲突

如果你之前曾在
`~/.zshrc` / `~/.bashrc` 中写过 `export ANTHROPIC_BASE_URL` 或 `export OPENAI_API_KEY`，CC Switch 会显示黄色警告横幅，因为
可能覆盖或与 GUI 配置发生冲突。请从 shell 配置文件中删除旧的 export 语句，
然后重新打开终端，以便 CC Switch 的设置完全生效。

## 故障排除

| 症状 | 原因与解决方案 |
| - | - |
| CC Switch 设置对 Claude Code 无效 | `~/.zshrc` 中仍存在 Anthropic OAuth 登录会话或 `ANTHROPIC_*` 变量。在 `claude` 中运行 `/logout`，并清除 shell 中的旧导出变量。 |
| *自动获取模型*按钮失败 | 请确保 **请求 URL** 填写为 `https://api.hostlinku.com`（不带双斜杠），且 **API 密钥** 已正确填写。 |
| Codex 在启用后会拒绝 shell 工具 | 在 Codex 选项卡中选择的模型必须是 *Responses-native* 的 `gpt-*` 模型（例如 `gpt-5-5`、`gpt-6-astra`、`gpt-6-sol`）。 请勿为 Codex 选择非 OpenAI 模型或 `gpt-5-6-terra`。 |
| `400 not available in Service Mode` | 所选模型在该服务模式 API 密钥下处于非活动状态。请使用 **自动获取模型** 按钮，以便仅显示与该密钥匹配的模型。 |

相关指南：[Claude Code](https://docs.hostlinku.com/zh/integrations/claude-code.md) · [Codex](https://docs.hostlinku.com/zh/integrations/codex-cli.md) ·
[DeepSeek Harness](https://docs.hostlinku.com/zh/integrations/deepseek-harness.md) · [OpenCode](https://docs.hostlinku.com/zh/integrations/opencode.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.