mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-23 09:29:13 +08:00
docs: add user manual documentation (#979)
* docs: add user manual documentation Add comprehensive user manual covering getting started, provider management, extensions (MCP/prompts/skills), proxy configuration, and FAQ sections. Includes screenshots and a README index. * fix(docs): align user manual with v3.10.3 codebase - Add OpenCode as 4th supported app throughout all docs - Fix proxy default port 15762 → 15721 - Update Claude presets (9 → 26), Codex (3 → 10), Gemini (3 → 7) - Add OpenCode presets (25 entries) - Fix timeout defaults and ranges (stream first byte 60s/90s, etc.) - Fix circuit breaker defaults with per-app values (Claude vs general) - Fix Skills support: all 4 apps, not just Claude/Codex - Remove non-existent Gemini authMode field - Fix prompt deletion behavior: enabled prompts cannot be deleted - Remove non-existent Legacy deeplink protocol, use V1 only - Fix DB table names (usage_logs → proxy_request_logs) and add missing tables - Fix migration version v3.8.0 → v3.7.0 - Add missing V1 deeplink parameters (config, configFormat, etc.) - Update doc version v3.9.1 → v3.10.3 - Add claude-opus-4-1 to pricing table - Fix recovery wait time range 10-300 → 0-300 --------- Co-authored-by: Jason <farion1231@gmail.com>
This commit is contained in:
Dex Miller
GitHub
196
docs/user-manual/4-proxy/4.2-takeover.md
Normal file
196
docs/user-manual/4-proxy/4.2-takeover.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 4.2 应用接管
|
||||
|
||||
## 功能说明
|
||||
|
||||
应用接管是指让 CC Switch 代理接管特定应用的 API 请求。
|
||||
|
||||
开启接管后：
|
||||
- 应用的 API 请求会通过本地代理转发
|
||||
- 可以记录请求日志和统计用量
|
||||
- 可以使用故障转移功能
|
||||
|
||||
## 前提条件
|
||||
|
||||
使用应用接管功能前，需要先启动代理服务。
|
||||
|
||||
## 开启接管
|
||||
|
||||
### 操作位置
|
||||
|
||||
设置 → 高级 → 代理服务 → 应用接管区域
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 确保代理服务已启动
|
||||
2. 找到「应用接管」区域
|
||||
3. 为需要的应用开启开关
|
||||
|
||||
### 接管开关
|
||||
|
||||
| 开关 | 作用 |
|
||||
|------|------|
|
||||
| Claude 接管 | 接管 Claude Code 的请求 |
|
||||
| Codex 接管 | 接管 Codex 的请求 |
|
||||
| Gemini 接管 | 接管 Gemini CLI 的请求 |
|
||||
| OpenCode 接管 | 接管 OpenCode 的请求 |
|
||||
|
||||
可以同时开启多个应用的接管。
|
||||
|
||||
## 接管原理
|
||||
|
||||
### 配置修改
|
||||
|
||||
开启接管后，CC Switch 会修改应用的配置文件，将 API 端点指向本地代理。
|
||||
|
||||
**Claude 配置变更**：
|
||||
|
||||
```json
|
||||
// 接管前
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
|
||||
}
|
||||
}
|
||||
|
||||
// 接管后
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex 配置变更**：
|
||||
|
||||
```toml
|
||||
# 接管前
|
||||
base_url = "https://api.openai.com/v1"
|
||||
|
||||
# 接管后
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini 配置变更**：
|
||||
|
||||
```bash
|
||||
# 接管前
|
||||
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
|
||||
# 接管后
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
### 请求转发
|
||||
|
||||
代理收到请求后：
|
||||
|
||||
1. 识别请求来源（Claude/Codex/Gemini/OpenCode）
|
||||
2. 查找该应用当前启用的供应商
|
||||
3. 将请求转发到供应商的实际端点
|
||||
4. 记录请求日志
|
||||
5. 返回响应给应用
|
||||
|
||||
## 接管状态指示
|
||||
|
||||
### 主界面指示
|
||||
|
||||
开启接管后，主界面会有以下变化：
|
||||
|
||||
- **代理 Logo 颜色**：从无色变为绿色
|
||||
- **供应商卡片**：当前活跃的供应商显示绿色边框
|
||||
|
||||
### 供应商卡片状态
|
||||
|
||||
| 状态 | 边框颜色 | 说明 |
|
||||
|------|----------|------|
|
||||
| 当前启用 | 蓝色 | 配置文件中的供应商（非代理模式） |
|
||||
| 代理活跃 | 绿色 | 代理实际使用的供应商 |
|
||||
| 普通 | 默认 | 未使用的供应商 |
|
||||
|
||||
## 关闭接管
|
||||
|
||||
### 操作步骤
|
||||
|
||||
1. 在代理面板中关闭对应应用的接管开关
|
||||
2. 或直接停止代理服务
|
||||
|
||||
### 配置恢复
|
||||
|
||||
关闭接管时，CC Switch 会：
|
||||
|
||||
1. 将应用配置恢复到接管前的状态
|
||||
2. 保存当前的请求日志
|
||||
|
||||
## 接管与供应商切换
|
||||
|
||||
### 接管模式下切换供应商
|
||||
|
||||
在接管模式下切换供应商：
|
||||
|
||||
1. 在主界面点击供应商的「启用」按钮
|
||||
2. 代理立即使用新供应商转发请求
|
||||
3. **无需重启 CLI 工具**
|
||||
|
||||
这是接管模式的一大优势：切换供应商即时生效。
|
||||
|
||||
### 非接管模式下切换
|
||||
|
||||
在非接管模式下切换供应商：
|
||||
|
||||
1. 修改配置文件
|
||||
2. 需要重启 CLI 工具才能生效
|
||||
|
||||
## 多应用接管
|
||||
|
||||
可以同时接管多个应用，每个应用独立管理：
|
||||
|
||||
- 独立的供应商配置
|
||||
- 独立的故障转移队列
|
||||
- 独立的请求统计
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景一：用量监控
|
||||
|
||||
开启接管 + 日志记录，监控 API 使用情况。
|
||||
|
||||
### 场景二：快速切换
|
||||
|
||||
开启接管后，切换供应商无需重启 CLI 工具。
|
||||
|
||||
### 场景三：故障转移
|
||||
|
||||
开启接管是使用故障转移功能的前提。
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 性能影响
|
||||
|
||||
代理会增加少量延迟（通常 < 10ms），对于大多数场景可以忽略。
|
||||
|
||||
### 网络要求
|
||||
|
||||
接管模式下，CLI 工具需要能够访问本地代理地址。
|
||||
|
||||
### 配置备份
|
||||
|
||||
开启接管前，CC Switch 会备份原始配置，关闭时恢复。
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 接管后请求失败
|
||||
|
||||
检查：
|
||||
- 代理服务是否正常运行
|
||||
- 供应商配置是否正确
|
||||
- 网络是否正常
|
||||
|
||||
### 关闭接管后配置未恢复
|
||||
|
||||
可能原因：
|
||||
- 代理异常退出
|
||||
- 配置文件被其他程序修改
|
||||
|
||||
解决方法：
|
||||
- 手动编辑供应商，重新保存
|
||||
- 或重新启用再关闭接管
|
||||
Reference in New Issue
Block a user