mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-24 12:44:18 +08:00
Align Claude Desktop model mapping with Claude Code three-role tiers
Claude Desktop's 3P validation only accepts claude-{sonnet,opus,haiku}-*
role IDs, so providers must map every tier. Bring the Desktop mapping flow
in line with Claude Code and fix the fallout that broke sub-agent Haiku calls.
- Proxy form: replace the dynamic route list with fixed Sonnet/Opus/Haiku
tiers; blank tiers backfill from the first filled tier (Sonnet first) on
submit and inherit its supports1m flag
- Backend: add a role-keyword fallback in map_proxy_request_model so dated
official names (e.g. claude-haiku-4-5-20251001) resolve to the right tier,
guarded by is_claude_safe_model_id so [1m]-suffixed IDs stay rejected
- Tighten is_claude_safe_model_id / isClaudeSafeRoute to reject degenerate
role IDs like "claude-sonnet-"
- Fix the seed-effect race where normalizing empty routes to three blank
tiers blocked the default-route backfill
- Sync switch hints, placeholders, and the zh/en/ja/zh-TW locales to the
three-role-ID rule
- Update zh/en/ja user manual (2.1, 2.6), calling out legacy Claude IDs
(claude-3-5-sonnet-...) as a rejected example
Tests: 282 frontend + 34 backend claude_desktop; typecheck, clippy, fmt clean.
This commit is contained in:
Jason
@@ -60,8 +60,8 @@ Presets are pre-configured provider templates that only require an API Key to us
|
||||
|
||||
The Claude Desktop panel includes provider presets translated from the Claude Code preset catalog. When adding one, choose between:
|
||||
|
||||
- **Direct mode**: the provider exposes a native Anthropic Messages API that Claude Desktop can reach directly
|
||||
- **Model mapping mode**: non-Claude models are mapped through the CC Switch local gateway into Sonnet / Opus / Haiku routes
|
||||
- **Direct mode**: the provider exposes a native Anthropic Messages API and its model names are Claude Desktop-recognized role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`), so Claude Desktop can reach it directly
|
||||
- **Model mapping mode**: model names outside the three role IDs (legacy Claude IDs, or non-Claude models like DeepSeek / Kimi) are mapped through the CC Switch local gateway into Sonnet / Opus / Haiku routes
|
||||
- **Claude Desktop Official**: restores Claude Desktop's official sign-in mode
|
||||
|
||||
See [2.6 Claude Desktop](./2.6-claude-desktop.md) for the full workflow.
|
||||
|
||||
@@ -7,7 +7,7 @@ The Claude Desktop panel lets you manage Claude Desktop provider configurations
|
||||
Once enabled, you can:
|
||||
|
||||
- Use third-party Anthropic-compatible providers in Claude Desktop
|
||||
- Configure model mapping for non-Claude models such as DeepSeek, Kimi, DouBao, OpenAI, and Gemini
|
||||
- Configure model mapping for models outside the three role IDs: legacy Claude IDs (e.g. `claude-3-5-sonnet`) and non-Claude models like DeepSeek / Kimi / DouBao / OpenAI / Gemini all need it
|
||||
- Reuse Copilot / Codex OAuth account-based providers
|
||||
- Switch between Claude Desktop official mode and third-party providers
|
||||
|
||||
@@ -51,13 +51,13 @@ If you already have many providers configured in Claude Code, this one-click imp
|
||||
Import rules:
|
||||
|
||||
- Existing providers with the same ID are not overwritten
|
||||
- Claude Code providers that can connect directly and use safe model names are imported as direct mode
|
||||
- Providers that need model conversion are imported as model mapping mode when possible
|
||||
- Providers whose model names are the three role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`) and can connect directly are imported as direct mode
|
||||
- Providers whose model names are not the three role IDs (including legacy Claude IDs), or that need format conversion, are imported as model mapping mode when possible
|
||||
- `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` are converted into Desktop Sonnet / Opus / Haiku mappings
|
||||
- The legacy `[1M]` suffix is converted into the `supports1m` flag in the Claude Desktop profile
|
||||
- Providers whose model mapping cannot be inferred are skipped
|
||||
|
||||
After importing, review each provider's model mapping against your actual upstream models. Non-Claude models such as Kimi, DeepSeek, GLM, and DouBao usually need model mapping mode.
|
||||
After importing, review each provider's model mapping against your actual upstream models. Any model that is not a `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` role ID—including non-Claude models like Kimi, DeepSeek, GLM, and DouBao, as well as legacy Claude IDs—usually needs model mapping mode.
|
||||
|
||||
If you already configured providers in Claude Code, prefer **Import existing providers from Claude Code**. This is the easiest migration path to Claude Desktop.
|
||||
|
||||
@@ -71,7 +71,7 @@ You can choose:
|
||||
- **Custom configuration**: manually enter name, endpoint URL, API key, and model settings
|
||||
- **Claude Desktop Official**: restore Claude Desktop official sign-in mode
|
||||
|
||||
For ordinary Anthropic Messages API-compatible providers, you usually only need to:
|
||||
For native Anthropic Messages API providers that already accept Claude Desktop's three role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`), you usually only need to:
|
||||
|
||||
1. Choose a preset or custom provider
|
||||
2. Fill in **API Key**
|
||||
@@ -110,17 +110,17 @@ In direct mode, CC Switch points the Claude Desktop 3P profile to the provider e
|
||||
Use this when:
|
||||
|
||||
- The provider exposes native Anthropic Messages API
|
||||
- Model IDs use `claude-*` or `anthropic/claude-*`
|
||||
- Model IDs are Claude Desktop-recognized role names: `claude-sonnet-*`, `claude-opus-*`, or `claude-haiku-*` (or the same with the `anthropic/claude-` prefix)
|
||||
- No format conversion is needed
|
||||
- CC Switch local routing does not need to stay running while in use
|
||||
|
||||
The "Manually specify Claude Desktop models" option in direct mode is advanced. Most native Claude model providers do not need it because Claude Desktop can fetch `/v1/models` automatically.
|
||||
|
||||
Only fill it in when the provider's `/v1/models` is unavailable, or when the returned model names cannot be recognized by Claude Desktop.
|
||||
Only fill it in when the provider's `/v1/models` is unavailable, or when the returned model names cannot be recognized by Claude Desktop. Manually entered model names must follow the `claude-sonnet-*`, `claude-opus-*`, or `claude-haiku-*` shape (legacy IDs like `claude-3-5-sonnet-…` are rejected).
|
||||
|
||||
### Model Mapping Mode
|
||||
|
||||
Model mapping mode is for providers that expose non-Claude models, such as DeepSeek and Kimi, or when CC Switch needs to convert the API format.
|
||||
Model mapping mode is for providers whose models are not `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` role IDs (including legacy Claude IDs and non-Claude models such as DeepSeek and Kimi), or when CC Switch needs to convert the API format.
|
||||
|
||||
After **Needs model mapping** is enabled, Claude Desktop connects to the CC Switch local gateway:
|
||||
|
||||
@@ -144,7 +144,7 @@ Supported API formats:
|
||||
| OpenAI Responses API | OpenAI Responses-compatible endpoints |
|
||||
| Gemini Native generateContent | Gemini native API |
|
||||
|
||||
In model mapping mode, Claude Desktop only sees `claude-*` style models. Real upstream model names are not written directly into the Claude Desktop profile.
|
||||
In model mapping mode, Claude Desktop only sees the three role routes: `claude-sonnet-*`, `claude-opus-*`, and `claude-haiku-*`. Real upstream model names are not written directly into the Claude Desktop profile.
|
||||
|
||||
## Configure Model Mapping
|
||||
|
||||
@@ -173,7 +173,7 @@ For DeepSeek:
|
||||
|------------|-------------------|-----------------|----|
|
||||
| Sonnet | DeepSeek V4 Pro | `deepseek-v4-pro` | Match provider capability |
|
||||
|
||||
The reason is that Claude Desktop now rejects non-`claude-*` models, so CC Switch local routing performs a model mapping pass.
|
||||
The reason is that Claude Desktop now rejects models outside the Sonnet / Opus / Haiku role families, so CC Switch local routing performs a model mapping pass.
|
||||
|
||||
### Multiple Role Mapping
|
||||
|
||||
@@ -185,7 +185,7 @@ You can configure Sonnet, Opus, and Haiku at the same time:
|
||||
| Opus | Higher quality or complex tasks |
|
||||
| Haiku | Fast, lower-cost model |
|
||||
|
||||
If the provider only has one model, one role is enough. Model mapping mode requires at least one valid mapping.
|
||||
If the provider only has one model, filling in just one role's requested model is enough; blank roles automatically inherit the first filled model (Sonnet first), so the Haiku that sub-agents call is always available. Model mapping mode requires at least one requested model.
|
||||
|
||||
## Local Routing Toggle
|
||||
|
||||
@@ -258,7 +258,7 @@ The Claude Desktop panel may show "Claude Desktop configuration needs attention"
|
||||
| Message | How to handle |
|
||||
|---------|---------------|
|
||||
| Current platform is not supported | Only macOS / Windows currently support writing 3P configuration |
|
||||
| Profile contains non-`claude-*` model names | Switch to the current provider again, or edit the provider to use model mapping |
|
||||
| Profile contains model names outside the Sonnet / Opus / Haiku role families | Switch to the current provider again, or edit the provider to use model mapping |
|
||||
| Model mapping is enabled but no valid route exists | Edit the provider and add at least one model mapping |
|
||||
| Local routing token has not been generated | Switch to the provider again; CC Switch will write a new local token |
|
||||
| Profile URL does not match the current provider | Switch to the current provider again so the profile points to the expected URL |
|
||||
@@ -285,7 +285,7 @@ Edit the provider, fill in **Menu display name** in model mapping, then enable t
|
||||
|
||||
### Why does direct mode fail?
|
||||
|
||||
Direct mode requires the provider to expose native Anthropic Messages API and accept Claude-safe model names used by Claude Desktop. If the provider uses OpenAI, Gemini, or non-Claude model IDs, enable **Needs model mapping**.
|
||||
Direct mode requires the provider to expose native Anthropic Messages API and accept Claude Desktop's three role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`). If the provider uses OpenAI, Gemini, non-Claude model IDs, or legacy Claude IDs (e.g. `claude-3-5-sonnet-…`)—any ID outside the three roles—direct mode fails, so enable **Needs model mapping**.
|
||||
|
||||
### Can I close CC Switch?
|
||||
|
||||
@@ -296,7 +296,7 @@ It depends on the mode:
|
||||
|
||||
### Are real upstream model names written into Claude Desktop?
|
||||
|
||||
Not in model mapping mode. The Claude Desktop profile only stores safe `claude-*` routes and display names. Real upstream model names stay in the CC Switch provider configuration and are mapped when requests pass through the local gateway.
|
||||
Not in model mapping mode. The Claude Desktop profile only stores safe Sonnet / Opus / Haiku role routes and display names. Real upstream model names stay in the CC Switch provider configuration and are mapped when requests pass through the local gateway.
|
||||
|
||||
## Next Steps
|
||||
|
||||
|
||||
@@ -60,8 +60,8 @@
|
||||
|
||||
Claude Desktop パネルには、Claude Code のプリセットカタログから変換されたプロバイダープリセットが含まれます。追加時には次のモードを選択できます：
|
||||
|
||||
- **直結モード**：プロバイダーがネイティブの Anthropic Messages API を提供し、Claude Desktop から直接アクセスできる場合
|
||||
- **モデルマッピングモード**：非 Claude モデルを CC Switch ローカルゲートウェイ経由で Sonnet / Opus / Haiku ルートへマッピング
|
||||
- **直結モード**：プロバイダーがネイティブの Anthropic Messages API を提供し、モデル名が Claude Desktop の認識できる三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）で、Claude Desktop から直接アクセスできる場合
|
||||
- **モデルマッピングモード**：三つの役割 ID 以外のモデル名（旧式 Claude ID や DeepSeek / Kimi などの非 Claude モデル）を CC Switch ローカルゲートウェイ経由で Sonnet / Opus / Haiku ルートへマッピング
|
||||
- **Claude Desktop Official**：Claude Desktop の公式サインインモードへ戻す
|
||||
|
||||
詳しい手順は [2.6 Claude Desktop](./2.6-claude-desktop.md) を参照してください。
|
||||
|
||||
@@ -7,7 +7,7 @@ Claude Desktop パネルでは、CC Switch 上で Claude Desktop のプロバイ
|
||||
有効にすると、次のことができます。
|
||||
|
||||
- Claude Desktop でサードパーティの Anthropic 互換プロバイダーを使う
|
||||
- DeepSeek、Kimi、DouBao、OpenAI、Gemini などの非 Claude モデルにモデルマッピングを設定する
|
||||
- 三つの役割 ID 以外のモデルにマッピングを設定する：旧式 Claude ID（例：`claude-3-5-sonnet`）や DeepSeek / Kimi / DouBao / OpenAI / Gemini などの非 Claude モデルはいずれも必要
|
||||
- Copilot / Codex OAuth のアカウント型プロバイダーを再利用する
|
||||
- Claude Desktop 公式モードとサードパーティプロバイダーを切り替える
|
||||
|
||||
@@ -51,13 +51,13 @@ Claude Code 側に多くのプロバイダーがすでにある場合、この
|
||||
インポートルール：
|
||||
|
||||
- 同じ ID のプロバイダーがすでにある場合は上書きしません
|
||||
- 直接接続でき、モデル名が安全な Claude Code プロバイダーは直結モードとしてインポートされます
|
||||
- モデル変換が必要なプロバイダーは、可能な場合モデルマッピングモードとしてインポートされます
|
||||
- モデル名が三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）で直接接続できるプロバイダーは直結モードとしてインポートされます
|
||||
- モデル名が三つの役割 ID でない（旧式 Claude ID を含む）、または形式変換が必要なプロバイダーは、可能な場合モデルマッピングモードとしてインポートされます
|
||||
- `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` は Desktop の Sonnet / Opus / Haiku マッピングに変換されます
|
||||
- 旧形式の `[1M]` サフィックスは Claude Desktop profile の `supports1m` フラグに変換されます
|
||||
- モデルマッピングを判断できないプロバイダーはスキップされます
|
||||
|
||||
インポート後は、各プロバイダーのモデルマッピングが実際のアップストリームモデルと合っているか確認してください。Kimi、DeepSeek、GLM、DouBao などの非 Claude モデルは通常、モデルマッピングモードが必要です。
|
||||
インポート後は、各プロバイダーのモデルマッピングが実際のアップストリームモデルと合っているか確認してください。`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` の三つの役割 ID 以外のモデル——Kimi、DeepSeek、GLM、DouBao などの非 Claude モデルや旧式 Claude ID を含む——は通常、モデルマッピングモードが必要です。
|
||||
|
||||
すでに Claude Code でプロバイダーを設定している場合は、まず **Claude Code の既存プロバイダーをインポート** を使ってください。Claude Desktop へ移行する最も簡単な方法です。
|
||||
|
||||
@@ -71,7 +71,7 @@ Claude Code 側に多くのプロバイダーがすでにある場合、この
|
||||
- **カスタム設定**：名前、エンドポイント URL、API Key、モデル設定を手動入力する
|
||||
- **Claude Desktop Official**：Claude Desktop の公式サインインモードへ戻す
|
||||
|
||||
通常の Anthropic Messages API 互換プロバイダーでは、基本的に次の手順だけで十分です。
|
||||
Claude Desktop の三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）をすでに受け付けるネイティブ Anthropic Messages API プロバイダーでは、基本的に次の手順だけで十分です。
|
||||
|
||||
1. プリセットまたはカスタムプロバイダーを選ぶ
|
||||
2. **API Key** を入力する
|
||||
@@ -110,17 +110,17 @@ Claude Code 側に多くのプロバイダーがすでにある場合、この
|
||||
適したケース：
|
||||
|
||||
- プロバイダーがネイティブの Anthropic Messages API を公開している
|
||||
- モデル ID が `claude-*` または `anthropic/claude-*`
|
||||
- モデル ID が Claude Desktop の認識できる役割名：`claude-sonnet-*`、`claude-opus-*`、`claude-haiku-*`（または `anthropic/claude-` 接頭辞の同種名）
|
||||
- 形式変換が不要
|
||||
- 使用中に CC Switch のローカルルーティングを起動し続ける必要がない
|
||||
|
||||
直結モードの「Claude Desktop モデルを手動指定」は高度な任意設定です。多くのネイティブ Claude モデルプロバイダーでは不要で、Claude Desktop が `/v1/models` を自動取得します。
|
||||
|
||||
プロバイダーの `/v1/models` が使えない、または返されるモデル名を Claude Desktop が認識できない場合だけ手動で追加してください。
|
||||
プロバイダーの `/v1/models` が使えない、または返されるモデル名を Claude Desktop が認識できない場合だけ手動で追加してください。手動で入力するモデル名は `claude-sonnet-*`、`claude-opus-*`、`claude-haiku-*` の形式である必要があります（`claude-3-5-sonnet-…` のような旧式 ID は拒否されます）。
|
||||
|
||||
### モデルマッピングモード
|
||||
|
||||
モデルマッピングモードは、DeepSeek や Kimi など Claude 系列ではないモデルを提供するプロバイダー、または CC Switch による API 形式変換が必要な場合に適しています。
|
||||
モデルマッピングモードは、プロバイダーのモデルが `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` の三つの役割 ID でない場合（旧式 Claude ID や DeepSeek、Kimi などの非 Claude モデルを含む）、または CC Switch による API 形式変換が必要な場合に適しています。
|
||||
|
||||
**モデルマッピングが必要** をオンにすると、Claude Desktop は CC Switch のローカルゲートウェイへ接続します。
|
||||
|
||||
@@ -144,7 +144,7 @@ CC Switch は次を担当します。
|
||||
| OpenAI Responses API | OpenAI Responses 互換エンドポイント |
|
||||
| Gemini Native generateContent | Gemini ネイティブ API |
|
||||
|
||||
モデルマッピングモードでは、Claude Desktop から見えるのは `claude-*` 形式のモデルだけです。実際のアップストリームモデル名は Claude Desktop profile に直接書き込まれません。
|
||||
モデルマッピングモードでは、Claude Desktop から見えるのは `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` の 3 種類の役割ルートだけです。実際のアップストリームモデル名は Claude Desktop profile に直接書き込まれません。
|
||||
|
||||
## モデルマッピングを設定する
|
||||
|
||||
@@ -173,7 +173,7 @@ DeepSeek を使う場合：
|
||||
|------------|----------------|------------------|----|
|
||||
| Sonnet | DeepSeek V4 Pro | `deepseek-v4-pro` | プロバイダー能力に合わせる |
|
||||
|
||||
理由は、現在の Claude Desktop が非 `claude-*` モデルを拒否するためです。そのため CC Switch のルーティング機能で一度モデルマッピングを行います。
|
||||
理由は、現在の Claude Desktop が Sonnet / Opus / Haiku の役割ファミリー以外のモデルを拒否するためです。そのため CC Switch のルーティング機能で一度モデルマッピングを行います。
|
||||
|
||||
### 複数役割のマッピング
|
||||
|
||||
@@ -185,7 +185,7 @@ Sonnet、Opus、Haiku の 3 つを同時に設定できます。
|
||||
| Opus | 高品質または複雑なタスク |
|
||||
| Haiku | 高速・低コストモデル |
|
||||
|
||||
プロバイダーにモデルが 1 つしかない場合は、1 つの役割だけでも構いません。モデルマッピングモードでは少なくとも 1 件の有効なマッピングが必要です。
|
||||
プロバイダーにモデルが 1 つしかない場合は、1 つの役割のリクエストモデルだけ入力すれば十分です。空欄の役割は最初に入力したモデル（Sonnet 優先）を自動的に引き継ぐため、サブ agent が呼び出す Haiku なども常に利用できます。モデルマッピングモードでは少なくとも 1 つのリクエストモデルが必要です。
|
||||
|
||||
## ローカルルーティング切り替え
|
||||
|
||||
@@ -258,7 +258,7 @@ Claude Desktop パネル上部に「Claude Desktop 設定の確認が必要で
|
||||
| 表示 | 対処方法 |
|
||||
|------|----------|
|
||||
| 現在のプラットフォームは未対応 | 3P 設定の書き込みは現在 macOS / Windows のみ対応 |
|
||||
| profile に非 `claude-*` モデル名がある | 現在のプロバイダーへ再度切り替える、またはモデルマッピングを使うよう編集する |
|
||||
| profile に Sonnet / Opus / Haiku の役割ファミリー以外のモデル名がある | 現在のプロバイダーへ再度切り替える、またはモデルマッピングを使うよう編集する |
|
||||
| モデルマッピングが有効だが有効なルートがない | プロバイダーを編集し、少なくとも 1 件のモデルマッピングを追加する |
|
||||
| ローカルルーティング token が未生成 | そのプロバイダーへ再度切り替えると、CC Switch が新しい token を書き込みます |
|
||||
| profile の URL が現在のプロバイダーと一致しない | 現在のプロバイダーへ再度切り替え、profile を正しい URL に戻します |
|
||||
@@ -285,7 +285,7 @@ Claude Desktop を完全に終了して再起動してください。Claude Desk
|
||||
|
||||
### 直結モードでエラーになるのはなぜ？
|
||||
|
||||
直結モードでは、プロバイダーがネイティブの Anthropic Messages API を提供し、Claude Desktop が使う Claude 安全モデル名を受け入れる必要があります。プロバイダーが OpenAI、Gemini、または非 Claude モデル ID を使う場合は **モデルマッピングが必要** をオンにしてください。
|
||||
直結モードでは、プロバイダーがネイティブの Anthropic Messages API を提供し、Claude Desktop の三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）を受け入れる必要があります。プロバイダーが OpenAI、Gemini、非 Claude モデル ID、または旧式 Claude ID（例：`claude-3-5-sonnet-…`）など三つの役割 ID 以外を使う場合は失敗するため、**モデルマッピングが必要** をオンにしてください。
|
||||
|
||||
### CC Switch を閉じてもよい？
|
||||
|
||||
@@ -296,7 +296,7 @@ Claude Desktop を完全に終了して再起動してください。Claude Desk
|
||||
|
||||
### 実際のアップストリームモデル名は Claude Desktop に書き込まれる？
|
||||
|
||||
モデルマッピングモードでは書き込まれません。Claude Desktop profile には安全な `claude-*` ルートと表示名だけが保存されます。実際のアップストリームモデル名は CC Switch のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。
|
||||
モデルマッピングモードでは書き込まれません。Claude Desktop profile には安全な Sonnet / Opus / Haiku 役割ルートと表示名だけが保存されます。実際のアップストリームモデル名は CC Switch のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。
|
||||
|
||||
## 次のステップ
|
||||
|
||||
|
||||
@@ -60,8 +60,8 @@
|
||||
|
||||
Claude Desktop 面板内置从 Claude Code 预设目录转换而来的供应商预设。添加时可选择：
|
||||
|
||||
- **直连模式**：供应商原生支持 Anthropic Messages API，Claude Desktop 可直接访问
|
||||
- **模型映射模式**：非 Claude 模型通过 CC Switch 本地网关映射为 Sonnet / Opus / Haiku 路由
|
||||
- **直连模式**：供应商原生支持 Anthropic Messages API，且模型名是 Claude Desktop 可识别的三档角色 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`），Claude Desktop 可直接访问
|
||||
- **模型映射模式**：模型名非三档角色 ID（旧式 Claude ID、或 DeepSeek / Kimi 等非 Claude 模型）通过 CC Switch 本地网关映射为 Sonnet / Opus / Haiku 路由
|
||||
- **Claude Desktop Official**：恢复 Claude Desktop 官方登录模式
|
||||
|
||||
完整操作请参阅 [2.6 Claude Desktop](./2.6-claude-desktop.md)。
|
||||
|
||||
@@ -7,7 +7,7 @@ Claude Desktop 面板用于在 CC Switch 中管理 Claude Desktop 的供应商
|
||||
开启后，你可以：
|
||||
|
||||
- 在 Claude Desktop 中使用第三方 Anthropic 兼容供应商
|
||||
- 为 DeepSeek、Kimi、DouBao、OpenAI、Gemini 等非 Claude 模型配置模型映射
|
||||
- 为三档角色 ID 之外的模型配置映射：旧式 Claude ID（如 `claude-3-5-sonnet`）、以及 DeepSeek / Kimi / DouBao / OpenAI / Gemini 等非 Claude 模型都需要
|
||||
- 复用 Copilot / Codex OAuth 账号类供应商
|
||||
- 在 Claude Desktop 官方模式和第三方供应商之间切换
|
||||
|
||||
@@ -51,13 +51,13 @@ Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使
|
||||
导入规则：
|
||||
|
||||
- 已存在同 ID 供应商时不会覆盖
|
||||
- 能直连且模型名安全的 Claude Code 供应商会导入为直连模式
|
||||
- 需要模型转换的供应商会尝试导入为模型映射模式
|
||||
- 模型名为三档角色 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）且能直连的供应商会导入为直连模式
|
||||
- 模型名非三档角色 ID（含旧式 Claude ID）或需要格式转换的供应商会尝试导入为模型映射模式
|
||||
- `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 会转换为 Desktop 的 Sonnet / Opus / Haiku 映射
|
||||
- 旧的 `[1M]` 后缀会转换为 Claude Desktop profile 中的 `supports1m` 标记
|
||||
- 无法判断模型映射的供应商会被跳过
|
||||
|
||||
导入后请检查每个供应商的模型映射是否符合你的实际上游模型。尤其是 Kimi、DeepSeek、GLM、DouBao 这类非 Claude 模型，通常需要使用模型映射模式。
|
||||
导入后请检查每个供应商的模型映射是否符合你的实际上游模型。任何不是 `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` 三档角色 ID 的模型——包括 Kimi、DeepSeek、GLM、DouBao 等非 Claude 模型，以及旧式 Claude ID——通常都需要使用模型映射模式。
|
||||
|
||||
如果你已经在 Claude Code 中配置过供应商，优先使用上面的 **将 Claude Code 中已有的供应商导入**。这是迁移到 Claude Desktop 最省事的路径。
|
||||
|
||||
@@ -71,7 +71,7 @@ Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使
|
||||
- **自定义供应商**：手动填写名称、接口地址、API Key 和模型设置
|
||||
- **Claude Desktop Official**：恢复 Claude Desktop 官方登录模式
|
||||
|
||||
对于普通 Anthropic Messages API 兼容供应商，通常只需要：
|
||||
对于已经接受 Claude Desktop 三档角色 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）的原生 Anthropic Messages API 供应商，通常只需要：
|
||||
|
||||
1. 选择预设或自定义供应商
|
||||
2. 填写 **API Key**
|
||||
@@ -110,17 +110,17 @@ Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使
|
||||
适用场景：
|
||||
|
||||
- 供应商暴露原生 Anthropic Messages API
|
||||
- 模型 ID 使用 `claude-*` 或 `anthropic/claude-*`
|
||||
- 模型 ID 为 Claude Desktop 可识别的角色名：`claude-sonnet-*`、`claude-opus-*`、`claude-haiku-*`（或带 `anthropic/claude-` 前缀的同类名）
|
||||
- 不需要格式转换
|
||||
- 不需要 CC Switch 在使用期间保持本地路由
|
||||
|
||||
直连模式的「手动指定 Claude Desktop 模型列表」是高级选项。多数原生 Claude 模型供应商不需要填写，Claude Desktop 会自动读取 `/v1/models`。
|
||||
|
||||
仅当供应商的 `/v1/models` 不可用，或返回的模型名不能被 Claude Desktop 识别时，再手动添加模型。
|
||||
仅当供应商的 `/v1/models` 不可用，或返回的模型名不能被 Claude Desktop 识别时，再手动添加模型。手动填写的模型名必须是 `claude-sonnet-*`、`claude-opus-*` 或 `claude-haiku-*` 形态（旧式 `claude-3-5-sonnet-…` 会被拒绝）。
|
||||
|
||||
### 模型映射模式
|
||||
|
||||
模型映射模式适合供应商提供的不是 Claude 系列模型（比如 deepseek, kimi 等），或接口格式需要 CC Switch 转换。
|
||||
模型映射模式适合供应商提供的模型不是 `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` 三档角色 ID（包括旧式 Claude ID 和 deepseek、kimi 等非 Claude 模型），或接口格式需要 CC Switch 转换。
|
||||
|
||||
开启「需要模型映射」后，Claude Desktop 会连接到 CC Switch 本地网关：
|
||||
|
||||
@@ -144,7 +144,7 @@ CC Switch 会负责：
|
||||
| OpenAI Responses API | OpenAI Responses 兼容接口 |
|
||||
| Gemini Native generateContent | Gemini 原生接口 |
|
||||
|
||||
模型映射模式下，Claude Desktop 只看到 `claude-*` 形式的模型；真实模型名不会直接写进 Claude Desktop profile。
|
||||
模型映射模式下，Claude Desktop 只看到 `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` 三类角色路由；真实模型名不会直接写进 Claude Desktop profile。
|
||||
|
||||
## 配置模型映射
|
||||
|
||||
@@ -173,7 +173,7 @@ CC Switch 会负责：
|
||||
| -------- | --------------- | ----------------- | ---------------- |
|
||||
| Sonnet | DeepSeek V4 Pro | `deepseek-v4-pro` | 按供应商能力选择 |
|
||||
|
||||
这样做的原因是 Claude Desktop 现在会拒绝非 `claude-*` 模型，所以需要 CC Switch 的路由功能进行一轮模型映射。
|
||||
这样做的原因是 Claude Desktop 现在会拒绝不属于 Sonnet / Opus / Haiku 三类角色的模型，所以需要 CC Switch 的路由功能进行一轮模型映射。
|
||||
|
||||
### 多角色映射
|
||||
|
||||
@@ -185,7 +185,7 @@ CC Switch 会负责：
|
||||
| Opus | 高质量或复杂任务模型 |
|
||||
| Haiku | 快速、低成本模型 |
|
||||
|
||||
如果供应商只有一个模型，也可以只配置一个角色。模型映射模式至少需要一条有效映射。
|
||||
如果供应商只有一个模型，只填写一个角色的实际请求模型也可以；留空的角色会自动沿用第一个已填模型（Sonnet 优先），因此 Haiku 等子 agent 调用始终有模型可用。模型映射模式至少需要填写一个实际请求模型。
|
||||
|
||||
## 本地路由开关
|
||||
|
||||
@@ -258,7 +258,7 @@ Claude Desktop 面板顶部可能出现「Claude Desktop 配置需要检查」
|
||||
| 提示 | 处理方式 |
|
||||
| ------------------------------------ | ------------------------------------------------ |
|
||||
| 当前平台暂不支持 | 目前仅 macOS / Windows 支持写入 3P 配置 |
|
||||
| profile 中存在非 `claude-*` 模型名 | 重新切换当前供应商，或编辑供应商改用模型映射 |
|
||||
| profile 中存在非 Sonnet / Opus / Haiku 角色模型名 | 重新切换当前供应商，或编辑供应商改用模型映射 |
|
||||
| 启用了模型映射但没有有效路由 | 编辑供应商，至少添加一条模型映射 |
|
||||
| 本地路由 token 尚未生成 | 重新切换该供应商，CC Switch 会写入新的本地 token |
|
||||
| profile 指向的地址与当前供应商不一致 | 重新切换当前供应商，让 profile 回到正确地址 |
|
||||
@@ -285,7 +285,7 @@ Claude Desktop 面板顶部可能出现「Claude Desktop 配置需要检查」
|
||||
|
||||
### 直连模式下为什么报错？
|
||||
|
||||
直连模式要求供应商提供原生 Anthropic Messages API，并接受 Claude Desktop 使用的 Claude 安全模型名。如果供应商使用 OpenAI、Gemini 或非 Claude 模型 ID，请开启「需要模型映射」。
|
||||
直连模式要求供应商提供原生 Anthropic Messages API，并接受 Claude Desktop 的三档角色 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）。如果供应商使用 OpenAI、Gemini、非 Claude 模型 ID，或旧式 Claude ID（如 `claude-3-5-sonnet-…`）等任何非三档角色 ID，直连都会失败，请开启「需要模型映射」。
|
||||
|
||||
### 可以关闭 CC Switch 吗？
|
||||
|
||||
@@ -296,7 +296,7 @@ Claude Desktop 面板顶部可能出现「Claude Desktop 配置需要检查」
|
||||
|
||||
### 是否会把真实上游模型名写入 Claude Desktop？
|
||||
|
||||
模型映射模式不会。Claude Desktop profile 中只保存安全的 `claude-*` 路由和显示名；真实上游模型名保存在 CC Switch 的供应商配置中，请求经过本地网关时再映射。
|
||||
模型映射模式不会。Claude Desktop profile 中只保存安全的 Sonnet / Opus / Haiku 角色路由和显示名；真实上游模型名保存在 CC Switch 的供应商配置中，请求经过本地网关时再映射。
|
||||
|
||||
## 下一步
|
||||
|
||||
|
||||
Reference in New Issue
Block a user