cc-switch/docs/user-manual/en/5-faq/5.3-deeplink.md

5.3 Deep Link Protocol

Overview

CC Switch supports the ccswitch:// deep link protocol, enabling one-click configuration import via links.

Use cases:

• Team configuration sharing
• One-click setup in tutorials
• Quick sync across devices

Online Generator Tool

CC Switch provides an online deep link generator tool:

URL: https://farion1231.github.io/cc-switch/deplink.html

How to Use

1. Open the above URL
2. Select the import type (Provider/MCP/Prompt)
3. Fill in the configuration information
4. Click "Generate Link"
5. Copy the generated deep link
6. Share with others or use on other devices

Protocol Format

V1 Protocol

Uses URL parameter format, easy to read and generate:

ccswitch://v1/import?resource={type}&app={app}&name={name}&...

Common parameters:

Parameter	Required	Description
resource	Yes	Resource type: provider / mcp / prompt / skill
app	Yes	App type: claude / codex / gemini / opencode / openclaw
name	Yes	Name

Provider parameters (resource=provider):

Parameter	Required	Description
endpoint	No	API endpoint URL (supports comma-separated multiple URLs)
apiKey	No	API key
homepage	No	Provider website
model	No	Default model
haikuModel	No	Haiku model (Claude only)
sonnetModel	No	Sonnet model (Claude only)
opusModel	No	Opus model (Claude only)
notes	No	Notes
icon	No	Icon
config	No	Base64-encoded configuration content
configFormat	No	Configuration format: json / toml
configUrl	No	Remote configuration URL
enabled	No	Whether to enable (boolean)
usageScript	No	Usage query script
usageEnabled	No	Whether to enable usage query (default true)
usageApiKey	No	Usage query API Key
usageBaseUrl	No	Usage query base URL
usageAccessToken	No	Usage query access token
usageUserId	No	Usage query user ID
usageAutoInterval	No	Auto query interval (minutes)

Prompt parameters (resource=prompt):

Parameter	Required	Description
content	Yes	Prompt content
description	No	Description
enabled	No	Whether to enable (boolean)

MCP parameters (resource=mcp):

Parameter	Required	Description
apps	Yes	App list (comma-separated, e.g., claude,codex,gemini,opencode)
config	Yes	MCP server configuration (JSON format)
enabled	No	Whether to enable (boolean)

Skill parameters (resource=skill):

Parameter	Required	Description
repo	Yes	Repository (format: owner/name)
directory	No	Directory path
branch	No	Git branch

Example:

ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx

Import Type Examples

Import Provider

ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx

Import MCP Server

ccswitch://v1/import?resource=mcp&apps=claude,codex&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D&name=mcp-fetch

Import Prompt Preset

ccswitch://v1/import?resource=prompt&app=claude&name=%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5&content=%23%20%E8%A7%92%E8%89%B2%0A%E4%BD%A0%E6%98%AF%E4%B8%80%E4%B8%AA%E4%B8%93%E4%B8%9A%E7%9A%84%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5%E4%B8%93%E5%AE%B6

Import Skill

ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main

Generate Deep Links

Manual Generation

1. Prepare parameters
2. Assemble the URL following V1 protocol format
3. URL-encode special characters

Example:

const params = new URLSearchParams({
  resource: 'provider',
  app: 'claude',
  name: 'My Provider',
  endpoint: 'https://api.example.com',
  apiKey: 'sk-xxx'
});

const url = `ccswitch://v1/import?${params.toString()}`;

Online Tool

Using CC Switch's official online deep link generator tool is more convenient.

Using Deep Links

Click the Link

Click a deep link in a browser or other application:

1. The system asks whether to open CC Switch
2. After confirming, CC Switch opens
3. An import confirmation dialog is displayed
4. Confirm the import

Import Confirmation

A confirmation dialog is shown before import, containing:

• Import type
• Configuration preview
• Confirm/Cancel buttons

Security tip: Only import configurations from trusted sources.

Protocol Registration

Automatic Registration

CC Switch automatically registers the ccswitch:// protocol during installation.

Manual Registration

If the protocol is not registered correctly:

macOS: Reinstall the app, or run:

/usr/bin/open -a "CC Switch" --args --register-protocol

Windows: Reinstall the app, or check the registry:

HKEY_CLASSES_ROOT\ccswitch

Linux: Check the MimeType configuration in the .desktop file.

Security Considerations

Sensitive Information

Deep links may contain sensitive information (e.g., API Keys):

• Do not share links containing API Keys in public
• Remove or replace sensitive information before sharing
• Use secure channels to transmit links

Source Verification

Before import, CC Switch will:

1. Validate the data format
2. Display a configuration preview
3. Require user confirmation

Malicious Link Protection

CC Switch checks:

• Whether the data format is valid
• Whether required fields are complete
• Whether configuration values are within reasonable ranges

Example Links

Example: Import Claude Provider

ccswitch://v1/import?resource=provider&app=claude&name=Test%20Provider&apiKey=sk-xxx&endpoint=https%3A%2F%2Fapi.example.com

Example: Import MCP Server

ccswitch://v1/import?resource=mcp&name=mcp-fetch&apps=claude,codex,gemini&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D

Troubleshooting

Link Won't Open

Check:

1. Is CC Switch installed
2. Is the protocol registered correctly
3. Is the link format correct

Import Failed

Possible causes:

• Base64 encoding error
• JSON format error
• Missing required fields

Solutions:

1. Check the original JSON format
2. Re-encode in Base64
3. Ensure all required fields are present