cc-switch 本地代理服务实战指南监听配置、应用接管与 API 格式转换原理【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switchcc-switch 的本地代理服务在127.0.0.1:15721上启动一个 HTTP 代理将 Claude、Codex、Gemini 等应用的 API 请求统一经其转发从而实现请求日志记录、用量统计与供应商故障转移Failover。本文以官方用户手册中的代理服务文档为主体结合 代理服务器实现、代理服务业务层 与 代理类型定义讲清楚服务的启动/停止方式、监听配置、运行状态指标、应用接管的底层机制、API 格式转换与常见问题排查。一、功能定位为什么需要本地代理本地代理服务Proxy Service是 cc-switch 将配置管理升级为流量治理的核心组件主要用途包括记录请求日志为每个 API 请求落一条结构化日志统计 API 用量聚合 Token 消耗与请求耗时支撑用量面板支持故障转移当前供应商连续失败时自动切换到队列中的下一家统一管理多应用请求Claude、Codex、Gemini 等应用共用一个本地入口由 ProviderRouter 按应用类型路由到对应供应商。从源码结构看代理服务器基于 Axum 构建并使用手动 hyper HTTP/1.1 accept 循环以preserve_header_case(true)保留客户端原始请求头的大小写保证转发到上游时的线级头部与不走代理直连完全一致见 server.rs 文件头注释。二、启动代理的两种方式方式 1主界面开关点击主界面顶部的代理服务开关按钮即可启动。开关颜色表示状态白色代理已停止绿色代理运行中。对应前端组件为 ProxyToggle状态轮询由 useProxyStatus 驱动。方式 2设置页打开设置 → 高级 → 代理服务点击面板右上角的开关。该面板由 ProxyTabContent 渲染内部再组合 ProxyPanel 显示运行指标。三、基本配置项与默认值官方文档列出的核心配置配置项说明默认值监听地址代理绑定的 IP 地址127.0.0.1监听端口代理监听的端口15721启用日志是否记录请求日志开启这些默认值在后端 ProxyConfig 的 Default 实现 中可以直接验证impl Default for ProxyConfig { fn default() - Self { Self { listen_address: 127.0.0.1.to_string(), listen_port: 15721, // 使用较少占用的高位端口 max_retries: 3, request_timeout: 600, enable_logging: true, live_takeover_active: false, streaming_first_byte_timeout: 60, streaming_idle_timeout: 120, non_streaming_timeout: 600, } } }数据库层同样将15721作为 schema 默认值持久化见 proxy_config 表定义listen_port INTEGER NOT NULL DEFAULT 15721配置在应用重启后依然生效。源码中更多可配置的超时参数除了文档表格中的三项ProxyConfig 结构体 还包含一组面向长请求的超时参数对大模型流式场景很关键字段含义默认值max_retries最大重试次数3streaming_first_byte_timeout流式首字超时1–120 秒60 秒streaming_idle_timeout流式静默超时两个数据块间的最大间隔60–600 秒填 0 禁用120 秒non_streaming_timeout非流式请求总超时60–1200 秒600 秒这些参数解释了请求超时类故障的排查方向如果模型思考时间较长但网络正常往往是流式静默超时先于上游触发。修改配置的步骤先停止代理服务修改地址/端口前必须停止修改监听地址或端口点击保存重新启动代理。注意地址/端口变更需要先停止服务因为监听器只在启动时绑定一次。从 ProxyServer::start 的实现看启动流程是解析listen_address:listen_port为SocketAddr随后调用tokio::net::TcpListener::bind绑定失败会返回ProxyError::BindFailed——这就是 FAQ 中 Address already in use 报错的来源。监听地址说明地址说明127.0.0.1仅本机可访问推荐0.0.0.0允许局域网内其他设备访问由于代理转发的是带真实凭据的 API 流量源码中的 HTTP 客户端也对代理是否指向回环地址做了专门校验见 http_client.rs 中的proxy_points_to_loopback测试这从实现侧印证了文档仅本机访问推荐的建议。四、运行状态面板代理运行中面板显示以下四类信息。4.1 服务地址http://127.0.0.1:15721面板提供复制按钮一键复制该地址。这个地址就是后续接管各应用时写入的base_url。4.2 当前使用供应商按应用显示当前路由目标Claude: PackyCode Codex: AIGoCode Gemini: Google 官方底层对应 ProxyStatus 中的current_provider字段与active_targets列表每个ActiveTarget记录app_type/provider_name/provider_id。4.3 统计数据指标说明活跃连接数当前正在处理的请求数总请求数启动以来的累计请求数成功率成功请求占比90% 显示绿色≤90% 显示黄色运行时长代理持续运行时间这些指标与 ProxyStatus 结构体 的字段一一对应active_connections、total_requests、success_rate、uptime_seconds另有last_error、failover_count等字段供前端展示最近的错误与切换次数。4.4 故障转移队列代理面板按应用类型显示 Failover 队列前端由 FailoverQueueManager 渲染Claude ├── 1. PackyCode [使用中] ● ├── 2. AIGoCode ● └── 3. 备用 ○ Codex ├── 1. AIGoCode [使用中] ● └── 2. 备用 ●队列元素含义数字表示优先级顺序使用中标签标记当前正在服务的供应商健康徽标反映供应商状态绿色健康连续失败 0 次黄色降级连续失败 1–2 次红色不健康连续失败 ≥3 次。该徽标逻辑对应 ProviderHealthBadge其数据源是 ProviderHealth 结构中的consecutive_failures连续失败计数与is_healthy布尔值熔断判断本身由 ProviderRouter 持有并在跨请求间保持状态见 ProxyState 注释共享的 ProviderRouter持有熔断器状态跨请求保持。五、工作原理5.1 请求流转5.2 应用接管配置改写机制代理启动并启用应用接管后cc-switch 会改写各应用的本地配置把流量指向本地代理Claudesettings.json的 env{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:15721 } }Codexconfig.tomlbase_url http://127.0.0.1:15721/v1Gemini环境变量GOOGLE_GEMINI_BASE_URLhttp://127.0.0.1:15721源码层面有几个值得注意的实现细节占位 Token接管模式下写回 Live 配置的 API Key 使用占位符PROXY_MANAGED避免客户端因缺少 key报错同时不泄露真实 Token见 PROXY_TOKEN_PLACEHOLDER 常量。接管状态按应用独立跟踪ProxyTakeoverStatus 为claude、codex、gemini、grokbuild、opencode、openclaw各维护一个布尔位说明接管是逐应用粒度的可以只接管部分应用。模型覆盖字段的接管接管 Claude 时ANTHROPIC_MODEL等 12 个模型覆盖字段会被移除并改写成稳定的 Claude 角色别名haiku/sonnet/opus/fable再由本地代理映射到当前供应商的真实模型防止模型菜单残留上一家供应商的名称见 CLAUDE_MODEL_OVERRIDE_ENV_KEYS 及其注释。接管前的配置快照写入新配置之前原始 Live 配置会作为LiveBackup含app_type与original_config见 LiveBackup 结构备份到数据库供停止时精确恢复。六、API 格式转换代理对设置了非 Anthropic 格式供应商的场景支持自动 API 格式转换使仅支持 OpenAI 兼容 API 的供应商也能被 Claude Code 使用供应商 API 格式代理行为Anthropic Messages直通不转换OpenAI Chat CompletionsAnthropic 请求转换为 OpenAI Chat 格式响应再逆转换OpenAI Responses APIAnthropic 请求转换为 OpenAI Responses 格式响应再逆转换API 格式在添加/编辑 Claude 供应商时的高级选项中按供应商配置参见添加供应商文档的 API 格式一节。转换的入口实现在 forwarder.rs 与 providers 模块 中按供应商配置的api_format分派不同转换管道。注意格式转换依赖代理处于应用接管启用的运行状态转换同时覆盖流式与非流式两类请求。七、停止代理与恢复行为停止方式方式 1点击主界面开关关闭代理方式 2在代理面板中将开关设为关闭。停止时的三步处理代理停止时cc-switch 依次执行恢复应用配置把各应用配置写回接管前的原始状态保存请求日志将本轮运行的请求记录落库关闭所有连接终止监听并释放端口。从源码看停止走的是带恢复语义的stop_with_restore路径services/proxy.rs内部先停服务、再对每个被接管的应用执行restore_live_config_for_app系列函数用LiveBackup中保存的原始配置覆盖回写。该模块还针对 Codex 的auth.json实现了带硬链接探针的事务式恢复CodexAuthFileTransaction保证恢复配置和用户正在 Codex 内重新登录两个并发操作不会互相覆盖仓库中stop_with_restore*、restore_*相关的测试用例同一文件内restore_waits_for_hot_switch_and_restores_latest_backup等十余个测试覆盖了这些边界场景。八、请求日志启用日志打开代理面板的启用日志开关对应ProxyConfig.enable_logging默认开启。日志字段每条请求记录包含字段说明时间请求发生时间应用Claude / Codex / Gemini供应商实际使用的供应商模型请求的模型名Token输入/输出 Token 数延迟请求耗时状态成功/失败查看日志在设置 → 用量标签页中查看请求日志前端实现见 RequestLogTable。九、常见问题排查9.1 端口被占用错误信息Address already in use。解决方法更换端口例如 5001或结束占用该端口的程序。对应源码中TcpListener::bind失败即抛出BindFailedserver.rs 启动流程因此该报错只会在启动/重启阶段出现。9.2 代理启动失败检查清单端口是否被其他程序占用是否有足够权限部分系统对低端口段有限制防火墙是否拦截了本地回环连接。9.3 请求超时可能原因网络问题供应商服务端问题代理配置错误。排查手段确认网络连通性绕过代理直接访问供应商 API 验证账号/Key 是否有效核对供应商配置尤其是base_url与 API 格式设置并留意流式/非流式超时参数是否过短。十、延伸阅读相关实现代理服务器、代理服务层、代理类型定义、供应商路由器前端面板ProxyPanel、FailoverQueueManager、ProxyTabContent同系列文档4.2 路由、4.3 故障转移、4.4 用量。【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考