CC Switch 代理与高可用 —— 本地路由、故障转移、用量统计全攻略

适用版本：CC Switch v3.16.0+ | 最后更新：2026-06-05

CC Switch 的代理与高可用体系是它区别于普通配置管理工具的关键。通过本地代理服务，你可以实现请求监控、应用路由、自动故障转移，以及详细的 Token 用量追踪。

本地代理服务

代理服务在本地启动一个 HTTP 代理，所有 API 请求都通过代理转发。主要用途：记录请求日志、统计 API 用量、支持故障转移、集中管理多个应用的请求。

启动代理

方式一：主界面开关：点击主界面顶部的代理开关按钮。白色为未运行，绿色为运行中。

方式二：设置页面：打开「设置 → 高级 → 代理服务」，点击右上角的开关。

代理配置

修改地址或端口需要先停止代理服务。127.0.0.1 仅本机可访问（推荐），0.0.0.0 允许局域网访问。

运行状态

代理运行时面板显示以下信息：

• 服务地址：http://127.0.0.1:15721，可点击复制
• 当前供应商：各应用当前使用的供应商（如 “Claude: PackyCode”）
• 统计数据：活跃连接数、总请求数、成功率（> 90% 绿色）、运行时长
• 故障转移队列：按应用类型显示队列，包含优先级顺序和健康徽章

工作原理

CLI 工具 → 发送 API 请求 → 本地代理(CC Switch) → 记录日志/统计用量 → 转发请求 → API 供应商 → 返回响应

启动代理并开启应用接管后，CC Switch 会修改应用配置，将端点指向本地代理地址（如 ANTHROPIC_BASE_URL: http://127.0.0.1:15721）。

API 格式转换

代理支持为配置了非 Anthropic 格式的供应商自动进行 API 格式转换：

格式转换需要代理运行并启用应用接管，同时支持流式和非流式请求。

日志记录

每条请求记录包含：时间、应用、供应商、模型、Token（输入/输出）、延迟、状态。在「设置 → 用量」Tab 中查看请求日志。

停止代理

停止代理时，CC Switch 会自动恢复应用配置到原始状态、保存请求日志、关闭所有连接。

应用路由

应用路由让 CC Switch 接管特定应用的 API 请求。开启路由后，API 请求通过本地路由转发，可以记录日志、统计用量、使用故障转移功能。

开启路由

设置 → 高级 → 路由服务 → 应用路由区域。先确保路由服务已启动，再为需要的应用（Claude / Codex / Gemini）开启开关。

路由原理

开启路由后，CC Switch 修改应用配置将 API 端点指向本地路由（http://127.0.0.1:15721），路由收到请求后识别来源、查找当前启用供应商、转发到实际端点、记录日志、返回响应。

路由模式优势

• 切换供应商即时生效，无需重启 CLI 工具
• 非路由模式下切换供应商需要重启 CLI 工具
• 路由模式下切换供应商，路由立即使用新供应商转发请求

路由状态指示

• 路由 Logo 颜色从无色变为绿色
• 供应商卡片：当前启用为蓝色边框，路由活跃为绿色边框

多应用路由

可同时路由多个应用，每个应用独立管理供应商配置、故障转移队列和请求统计。

常见场景

1. 开启路由 + 日志记录监控 API 使用情况
2. 开启路由后切换供应商无需重启 CLI 工具
3. 开启路由是使用故障转移功能的前提

故障转移

故障转移功能在主供应商请求失败时自动切换到备用供应商，确保服务不中断。适用场景：供应商服务不稳定、需要高可用性、长时间运行的任务。

前提条件

1. 启动代理服务
2. 开启应用接管
3. 配置故障转移队列
4. 开启自动故障转移

配置故障转移队列

设置 → 高级 → 故障转移，页面顶部有 Claude / Codex / Gemini 三个 Tab 独立配置。点击「添加供应商」从列表中选择，拖拽调整优先级顺序。主界面也有快捷操作：开启供应商卡片的故障转移开关，供应商自动加入队列。

故障转移流程

请求到达代理 → 发送到当前供应商 → 成功则返回 → 失败则记录失败 → 检查熔断状态 → 熔断则跳过 → 未熔断则增加失败计数 → 尝试队列中下一个供应商 → 全部失败则返回错误

熔断器配置

各应用有独立配置。以下为参数说明：

超时配置：

• 流式首字节超时：通用 60 秒，Claude 90 秒
• 流式静默超时：通用 120 秒，Claude 180 秒（填 0 禁用）
• 非流式超时：通用 600 秒

重试配置：通用默认 3 次，Claude 默认 6 次，Gemini 默认 5 次。

熔断器三状态：

• 关闭（Closed）：正常状态，允许请求
• 开启（Open）：熔断状态，跳过此供应商
• 半开（Half-Open）：到达恢复等待时间后发送试探请求；试探成功回关闭，失败回开启

健康状态指示

供应商卡片上显示健康状态徽章：

• 🟢 绿色「健康」：连续失败 0 次
• 🟡 黄色「警告」：连续失败 1-2 次
• 🔴 红色「不健康/熔断」：连续失败 ≥ 3 次

故障转移日志

每次故障转移记录时间、原供应商、新供应商、失败原因，可在用量统计的请求日志中查看。

用量统计

用量统计功能记录和分析 API 请求数据，帮助了解使用情况、估算费用、分析模式、排查问题。

数据来源

v3.13 起 Codex 改用 JSONL 会话日志精确解析，替代原先的估算；Gemini 通过会话日志精确同步；Claude 同样支持从会话日志导入。用量面板支持按应用筛选（Claude / Codex / Gemini）。

打开用量统计

设置 → 用量 Tab

统计概览（筛选驱动 Hero）

v3.15.0 起，用量页顶部为筛选驱动的 Hero 卡，切换日期范围、应用、供应商或模型筛选时，以下指标同步更新：

• 总请求数
• 真实消耗 Tokens（输入 + 输出 + 缓存创建 + 缓存读取的缓存归一化总量）
• 缓存命中率（缓存读取 Token 在可缓存输入中的占比）
• 估算费用
• 成功率

趋势图表

请求趋势：折线图展示请求数量变化，可按小时/天查看。

Token 趋势：输入 Token（蓝）、输出 Token（绿）、缓存创建 Token（橙）、缓存命中 Token（紫）、成本（红色虚线）。

• 今日按小时显示（24 个数据点），7 天/30 天按天显示。

详细数据

请求日志：每条请求包含时间、供应商、模型、输入/输出 Token、缓存读取/创建 Token、总费用、耗时信息（总耗时、首 Token 时间、流式/非流式徽章）、状态码。支持按应用类型、状态码、供应商、模型、时间范围筛选。

供应商统计：按供应商分组，显示请求数、成功数、失败数、成功率、总 Token、估算费用。

模型统计：按模型分组，显示请求数、输入/输出 Token、平均延迟、估算费用。

定价配置

设置 → 高级 → 定价配置。可为每个模型设置输入/输出/缓存读取/缓存创建价格（每百万 Token）。

模型 ID 匹配规则：在匹配定价前，CC Switch 会对请求中的模型 ID 做标准化处理——去掉供应商前缀、版本后缀、日期后缀等。因此定价配置中应填写清洗后的模型 ID，而不是原始完整模型名。

CC Switch 预设了常用模型（Claude、OpenAI/GPT、Gemini、DeepSeek、StepFun、Kimi、MiniMax、GLM、Doubao、MiMo 等）的官方价格，涵盖美元和人民币。如使用中转服务，价格可能不同，可自定义修改。

模型检查（Stream Check）

模型检查功能用于验证供应商配置的模型是否可用，通过发送实际 API 请求测试模型是否存在、API Key 是否有效、端点是否正常响应、响应延迟、流式响应首字节时间（TTFB）。v3.13.0 起覆盖 Claude / Codex / Gemini / OpenCode / OpenClaw，包括 OpenClaw 全部协议变体和 OpenCode npm 包映射。

配置测试模型

设置 → 高级 → 模型测试，为每个应用配置测试模型（建议使用 Haiku / Mini / Flash 等低成本型号）。

检查参数

测试结果

• 🟢 健康：响应正常，延迟在阈值内
• 🟡 降级：响应正常但延迟超过阈值
• 🔴 不可用：请求失败或超时

与故障转移集成

开启代理服务后，系统会定期对故障转移队列中的供应商执行健康检查，不健康的供应商会被暂时跳过。当供应商从熔断状态恢复时，会先执行模型检查验证可用性。

最佳实践

故障转移队列配置建议

1. 主供应商：最稳定、最快的供应商
2. 第一备用：次优选择
3. 第二备用：保底选择

熔断器策略

成功标志：代理服务运行中（顶部开关为绿色），故障转移队列配置完成，供应商卡片显示健康状态，用量看板有数据。