在 CC Switch 中接入

CC Switch 是桌面配置管理工具，可以为不同编程工具保存 TokenFactory 供应商、API Key 和模型配置，并在供应商卡片中显示人民币余额。也可以直接按工具与集成中的独立教程配置工具。

本页覆盖 Claude Code、Codex、OpenCode、OpenClaw、Hermes 和 Pi。工具名称不代表可调用同名厂商的模型；请从 TokenFactory 模型目录选择支持对应接口的国产模型。

1. 安装工具，准备 API Key 和模型

1. 从 CC Switch 官方下载页或 GitHub Releases下载与你的系统、芯片架构对应的安装包并安装。macOS 也可以使用下方 Homebrew 命令。
2. 安装要使用的工具，并启动一次：Claude Code、Codex、OpenCode、OpenClaw、Hermes、Pi。CC Switch 的供应商配置需要配合相应工具使用。
3. 在 TokenFactory 控制台创建 API Key。
4. 到模型文档进入目标模型详情，确认“调用方式”中的接口并复制模型 ID。模型请求按实际用量扣费，发起请求前确认账户余额与消费上限。

brew install --cask cc-switch

Pi 页签由 CC Switch v3.20.0 引入。使用 Pi 时，请安装包含该页签的版本；页签未显示时，也可先检查 CC Switch 设置中的应用显示选项。

2. 添加 TokenFactory 供应商

在 CC Switch 中选择要配置的工具，点击右上角 + / 添加供应商，选择自定义，再填写下面的字段。无需等待 TokenFactory 出现在内置供应商预设中。

先选对 Base URL

工具	本页接入方式	Base URL	最终模型请求路径
Claude Code	Anthropic Messages	https://api.tokenfactory.cn/anthropic	/anthropic/v1/messages
Codex	OpenAI Responses	https://api.tokenfactory.cn/v1	/v1/responses
OpenCode、OpenClaw、Hermes、Pi	OpenAI Chat Completions	https://api.tokenfactory.cn/v1	/v1/chat/completions

Claude Code · Base URL

Codex、OpenCode、OpenClaw、Hermes、Pi · Base URL

Claude Code 会在 /anthropic 后追加 /v1/messages。其余工具在本页配置下追加 /responses 或 /chat/completions，因此必须保留 Base URL 中的 /v1。不要填写完整的模型请求地址，也不要只填 https://api.tokenfactory.cn。

按工具填写

在下面切换工具，查看表单字段。YOUR_API_KEY 使用控制台创建的 Key，YOUR_MODEL_ID 使用模型详情中的真实 ID。

Claude Code

供应商名称：TokenFactory
请求地址：https://api.tokenfactory.cn/anthropic
API 格式：Anthropic Messages
API Key：YOUR_API_KEY
主模型：YOUR_MODEL_ID
Haiku / Sonnet / Opus 模型映射：YOUR_MODEL_ID

Codex

供应商名称：TokenFactory
Base URL：https://api.tokenfactory.cn/v1
上游 API 格式：OpenAI Responses
API Key：YOUR_API_KEY
模型：YOUR_MODEL_ID
wire_api：responses

OpenCode

供应商名称：TokenFactory
供应商 ID：tokenfactory
SDK 包（npm）：@ai-sdk/openai-compatible
Base URL：https://api.tokenfactory.cn/v1
API Key：YOUR_API_KEY
模型 ID：YOUR_MODEL_ID

OpenClaw

供应商名称：TokenFactory
供应商 ID：tokenfactory
API 类型（api）：openai-completions
Base URL：https://api.tokenfactory.cn/v1
API Key：YOUR_API_KEY
模型 ID：YOUR_MODEL_ID

Hermes

供应商名称：TokenFactory
供应商 ID：tokenfactory
API 模式（api_mode）：chat_completions
Base URL：https://api.tokenfactory.cn/v1
API Key：YOUR_API_KEY
模型 ID：YOUR_MODEL_ID

Pi

供应商名称：TokenFactory
供应商 ID：tokenfactory
API 格式（api）：openai-completions
Base URL：https://api.tokenfactory.cn/v1
API Key：YOUR_API_KEY
模型 ID：YOUR_MODEL_ID

• Claude Code：主模型和各档位都填写已选的国产模型 ID，避免工具切换档位后请求未配置的模型。各档位可以使用同一个模型；这些名称只是工具中的角色映射。
• Codex：本页使用模型原生支持的 Responses 接口。只有 Chat Completions 的模型不能直接按此方式接入。CC Switch 另有本地路由转换功能，其兼容性需单独验证，不属于本页配置。
• OpenCode、OpenClaw、Hermes、Pi：先添加 tokenfactory 供应商，再添加模型条目。OpenClaw 和 Pi 的 openai-completions 标识指向 Chat Completions；Hermes 对应标识为 chat_completions。
• 模型能力：如果表单要求填写上下文长度、最大输出或图片能力，按目标模型详情填写，不沿用其他模型预设值。

可以使用 CC Switch 的“获取模型”辅助选择，但仍需确认所选模型支持当前接口。获取模型成功只说明模型列表可读取，不代表聊天、流式输出或工具调用已验证通过。

3. 启用配置并验证

保存后，不同工具的模型选择方式有所区别：

工具	保存后的操作
Claude Code、Codex	在 CC Switch 中启用 TokenFactory，然后重新启动对应工具，确认当前模型。
OpenCode	将供应商添加到配置后，在 OpenCode 的 /models 中选择 tokenfactory 下的目标模型。
OpenClaw	将供应商添加到配置后，将默认模型设为 tokenfactory/YOUR_MODEL_ID；操作方法见 OpenClaw 教程。
Hermes	在 CC Switch 中启用对应供应商和模型，然后重新启动 Hermes 确认选择。CC Switch 会更新 Hermes 的供应商与默认模型配置。
Pi	将供应商添加到配置后，在 Pi 的 /model 中选择目标模型。CC Switch 不会替 Pi 修改默认供应商或默认模型。

OpenCode、OpenClaw、Hermes 和 Pi 可以保留多个供应商配置；供应商存在于配置中，不等于当前会话已选中它。Pi 的供应商管理也不意味着支持 CC Switch 的 Pi 代理接管、故障转移或 MCP 同步。

在对应工具中发起一个不含敏感信息的最小任务，例如“仅回复连接成功，不读取文件、不执行命令”。这会产生一次正常模型调用，按实际用量计费。

依次确认：

1. 当前供应商为 TokenFactory，模型 ID 与刚填写的一致。
2. 工具能收到完整回复，流式输出没有报错或意外中断。
3. 控制台出现对应调用记录；诊断或反馈只保留工具版本、模型 ID、错误码及请求路径，不展示 Key 或请求内容。

纯文本回复成功只验证基础调用。正式用于编码前，还应在空白项目中验证所需的工具调用与文件操作行为；输出中断后的处理见流式与重试。

4. 在 CC Switch 中查看余额

余额查询使用同一 API Key，属于只读查询，不扣费，也不会产生模型调用。它返回当前账户的人民币余额快照；调用趋势、模型用量和资金流水请到控制台查看。

开启自定义查询

1. 在 TokenFactory 供应商卡片中打开用量查询，开启查询开关。
2. 选择自定义模板。
3. 如果供应商的 Base URL 和 API Key 已填写正确，查询面板中的同名可选字段保持空白，使用供应商现有值。
4. 粘贴下面的完整脚本，点击测试脚本，确认人民币单位和账户状态后保存。
5. 按需设置自动查询间隔；设为 0 时关闭自动刷新。

使用自定义模板是为了按人民币展示金额，并保留账户有效状态。官方通用模板示例将单位写成 USD，且 response.is_active || true 会把 false 也当成有效，不能直接套用。

;({
  request: {
    url: '{{baseUrl}}/user/balance',
    method: 'GET',
    headers: {
      Authorization: 'Bearer {{apiKey}}',
      'User-Agent': 'cc-switch/1.0',
    },
  },

  extractor: function (response) {
    if (!response || typeof response.balance === 'undefined') {
      return {
        isValid: false,
        invalidMessage:
          response && response.error && response.error.message
            ? response.error.message
            : '查询失败',
      }
    }

    // 只把人民币余额响应显示为金额，避免把其他单位误作余额。
    if (response.unit !== 'CNY') {
      return {
        isValid: false,
        invalidMessage: '请使用本页的按量 API 地址',
      }
    }

    var balance = response.balance

    if (typeof balance !== 'number' || !Number.isFinite(balance)) {
      return {
        isValid: false,
        invalidMessage: '余额格式错误',
      }
    }

    return {
      isValid: response.is_active === true,
      invalidMessage: response.is_active === true ? undefined : '账户不可用',
      remaining: balance,
      unit: '人民币',
    }
  },
})

脚本仅保留 占位符，真实 Key 填在 CC Switch 的凭据字段中。

查询地址与响应

供应商 Base URL	脚本发出的完整查询地址
https://api.tokenfactory.cn/v1	GET https://api.tokenfactory.cn/v1/user/balance
https://api.tokenfactory.cn/anthropic	GET https://api.tokenfactory.cn/anthropic/user/balance

两个地址都使用 Authorization: Bearer <API Key>。即使模型调用使用 Anthropic Messages，余额查询也使用 Bearer，不使用 x-api-key。

成功响应示例：

{ "is_active": true, "balance": 12.345678, "unit": "CNY" }

字段	含义
is_active	API Key 所属账户是否有效；不代表余额充足或所有模型均可调用。
balance	当前人民币余额，单位为元；零余额或在途调用形成的有限负数都如实展示。
unit	固定为 CNY，脚本将展示单位设为“人民币”。

示例金额不是实际余额。余额查询不会锁定资金；能否调用还取决于模型、账户权限和消费上限。完整 HTTP 契约、失败响应见查询账户余额。

自定义状态栏等其他工具也可使用该接口：先判断 HTTP 状态，再校验金额为有限数值且单位为 CNY；失败时显示“查询失败”，不要把缺失字段当成零余额。

CC Switch 的本地用量看板与账户余额查询是不同功能：前者依赖其收集到的请求或会话记录、定价配置，不应作为 TokenFactory 最终账单；资金核对以控制台流水为准。

常见问题

模型请求返回 404

先核对本页 Base URL 与最终请求路径：Claude Code 用 /anthropic，其余工具按本页方式用 /v1。如果把完整 /chat/completions 或 /responses 填进 Base URL，工具可能再次追加路径。

CC Switch 获取模型或连通性检查成功，不能替代对应工具的实际请求验证。检查路径时不要输出认证头。

认证失败，或模型没有可用供应路线

• 401 / 403：确认 API Key 仍有效、对应账户有调用权限，并检查工具是否读取了其他供应商的配置或环境变量。
• 模型不存在或没有可用供应路线：核对模型 ID 和接口。Claude Code 需要 Anthropic Messages；本页 Codex 需要 Responses；其他工具按本页配置需要 Chat Completions。模型出现在目录中，不代表支持所有接口。
• 切换后仍使用旧模型：重新启动工具并检查当前模型；Pi 需在 /model 中选择，不能只看 CC Switch 中供应商是否已添加。

更多错误码见错误排查。

余额显示为 USD，或提示账户不可用

• 显示 USD：切换到自定义模板并保存本页脚本，不手动把美元数值换算成人民币。
• 提示使用按量 API 地址：响应单位不是 CNY，核对供应商 Base URL 及查询面板是否保留了不同的可选地址。
• 账户不可用：脚本收到 is_active=false 或缺少有效状态；到控制台核对账户，不改成 response.is_active || true 掩盖问题。
• 查询返回 401：确认查询使用 Authorization: Bearer ，并检查是否被查询面板内旧的可选 Key 覆盖。
• 未自动刷新：检查用量查询开关与间隔，确认当前版本对该应用的自动查询条件；先用“测试脚本”核实手动查询。

查询失败不代表模型调用失败，也不应触发模型调用或自动切换计费入口。API Key 泄露后，在控制台禁用并重新创建；反馈截图和导出配置应隐藏凭据与账户资金信息。

版本与验证范围

本页于 2026-09-15 核对 CC Switch 官方手册、发布说明及配置源码，并核对所列工具的 Base URL 拼接方式。尚未完成六个客户端当前版本的逐一模型调用实测；工具的流式输出、工具调用与实际余额卡片展示，仍需按本页步骤在使用版本中验证。

参考资料：

• CC Switch 添加供应商
• CC Switch 用量查询
• CC Switch 配置文件与 Hermes / OpenClaw 配置
• CC Switch v3.20.0：Pi 供应商管理及能力边界
• Pi 自定义模型与供应商