vrr/claude-code-router
2
0
Fork 0
mirror of https://github.com/musistudio/claude-code-router.git synced 2026-07-10 01:28:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Refresh README for new gateway and provider docs

Browse source
This commit is contained in:
musistudio 2026-07-01 19:51:59 +08:00
parent 054c4fcd94
commit 2cbaaded8f
4 changed files with 500 additions and 348 deletions
Download patch file Download diff file Expand all files Collapse all files

420
README.md
View file

@ -3,6 +3,7 @@
<p align="center">
<a href="README_zh.md"><img alt="Chinese README" src="https://img.shields.io/badge/%F0%9F%87%A8%F0%9F%87%B3-%E4%B8%AD%E6%96%87%E7%89%88-ff0000?style=flat" /></a>
<a href="https://discord.gg/rdftVMaUcS"><img alt="Discord" src="https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white" /></a>
<a href="https://x.com/musistudio2026"><img alt="X" src="https://img.shields.io/badge/X-@musistudio2026-000000?logo=x&logoColor=white" /></a>
<a href="https://github.com/musistudio/claude-code-router/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/musistudio/claude-code-router" /></a>
<a href="https://ccrdesk.top/"><img alt="Documentation" src="https://img.shields.io/badge/Docs-ccrdesk.top-0ea5e9?style=flat" /></a>
</p>
@ -13,12 +14,12 @@
Claude Code Router Desktop is a local gateway and desktop control panel for routing agent requests from Claude Code, Codex, ZCode, and compatible clients to the model provider you actually want to use.
CCR runs on your machine, keeps provider configuration in your local config directory, and exposes a local gateway at `http://127.0.0.1:3456`.
CCR runs on your machine, keeps provider configuration in your local config directory, and exposes the local gateway at `http://localhost:8080` by default.
## Why Use CCR
- Use one local endpoint for multiple agent tools instead of configuring every client separately.
- Route requests with explicit rules instead of editing client configuration by hand.
- Route requests with default routing, conditional rules, fallback targets, and request rewrites instead of editing client configuration by hand.
- Mix providers without changing your workflow. CCR supports OpenAI-compatible APIs, Anthropic Messages, Gemini Generate Content, OpenRouter, DeepSeek, SiliconFlow, Moonshot, Kimi Code, Mistral, Z.AI, Bailian, and custom providers.
- Control cost and reliability with fallback routing, API key rotation, usage statistics, and request logs.
- Manage everything from a desktop UI instead of editing JSON by hand.
@ -26,40 +27,18 @@ CCR runs on your machine, keeps provider configuration in your local config dire
## Features
- **Desktop dashboard**: start or stop the local gateway, inspect usage, configure the tray window, and manage runtime settings.
- **Provider management**: add provider presets or custom endpoints, test connectivity, manage credentials, and monitor supported account balances where available.
- **Routing rules**: configure conditional and model-prefix routing rules with fallback handling.
- **Agent profiles**: configure Claude Code, Codex, and ZCode profiles that point to the CCR gateway.
- **Gateway compatibility**: translate client requests through the local CCR wrapper and the core gateway runtime.
- **Overview dashboard**: inspect system status, usage widgets, account balances, model distribution, and share cards.
- **Provider management**: add provider presets or custom endpoints, probe protocol support, test model connectivity, manage credentials, and monitor supported account balances where available.
- **Routing rules**: configure default routing, conditional and model-prefix rules, fallback handling, and request rewrites.
- **Agent Config**: configure Claude Code, Codex, and ZCode launch entries, models, scopes, and multi-instance app profiles.
- **Gateway compatibility**: translate supported client requests through the local CCR model gateway.
- **Proxy mode**: capture supported API traffic through a local proxy with optional system proxy integration and network capture.
- **Plugins**: install or load wrapper plugins, including routes for Claude Design and Cursor Proxy style integrations.
- **Virtual models**: expose aliases or composed model profiles for clients that expect a specific model name.
- **Provider deeplinks**: import provider configuration through `ccr://provider?...` links after user confirmation.
- **Extensions**: install or load wrapper plugins, including routes for Claude Design and Cursor Proxy style integrations.
- **Fusion models**: combine a base model with vision, web search, or MCP tools into a reusable selectable model.
- **Provider deeplinks**: import provider configuration, manifests, and embeddable one-click provider buttons through `ccr://provider?...` links after user confirmation.
## Download And Install
### npm CLI
Install the CLI package when you want to run CCR without the desktop tray or `ccr://` protocol integration:
```bash
npm install -g claude-code-router
ccr start
```
Common commands:
```bash
ccr start # start the background CCR service and web management UI
ccr stop # stop the background CCR service
ccr <profile-name> cli # launch the saved profile as a CLI
ccr <profile-name> app # launch the saved profile as an app
```
The web management UI listens on `http://127.0.0.1:3458` by default. Use `ccr start --host <host> --port <port>` to change it.
### Desktop App
1. Open the [GitHub Releases page](https://github.com/musistudio/claude-code-router/releases).
2. Download the package for your platform:
- macOS Apple Silicon: `Claude-Code-Router_<version>-mac-Apple-Silicon-arm64.dmg` or `.zip`
@ -73,10 +52,7 @@ The web management UI listens on `http://127.0.0.1:3458` by default. Use `ccr st
CCR stores runtime configuration in SQLite. A legacy `config.json` is read only once for migration when no SQLite config exists.
CCR starts two local services when the gateway is enabled:
- CCR wrapper gateway: `http://127.0.0.1:3456`
- Core gateway runtime: `http://127.0.0.1:3457`
After the service is started from the **Server** page, CCR listens on `http://localhost:8080` by default. The **Server** page controls the gateway `Host`, `Port`, proxy mode, system proxy, network capture, and CA certificate status.
## Quick Start
@ -84,25 +60,25 @@ CCR can be configured entirely from the desktop UI. Use this setup order for a c
### 1. Add a provider
Open **Providers**, click **Add Provider**, then choose a built-in preset or create a custom provider. Fill in the provider name, endpoint, protocol, API key, and model list in the form. Use the connectivity check when available, then save the provider.
Open **Providers**, click **Add Provider**, then choose a built-in preset or **Other / custom API endpoint**. Fill in the provider name, base URL, protocol, API key, and model list. Run protocol probing and model connectivity checks when available, then save the provider.
### 2. Configure routing
Open **Routing** to add explicit rules and configure failure handling.
Open **Routing** to choose the default route, add conditional rules, configure request rewrites, and set fallback behavior.
Use **Add Routing Rule** for request conditions, model-prefix routing, or fallback behavior.
Use **Add Routing Rule** for request conditions, model-prefix routing, or rule-level fallback targets.
### 3. Start the gateway
Open **Server** and click **Start**. Enable auto start if you want CCR to start the local gateway whenever the desktop app opens.
Open **Server** and click **Start**. After the page shows Running, CCR listens on `http://localhost:8080`. Enable **Auto start** if you want CCR to start the local gateway whenever the desktop app opens.
### 4. Connect your agent tool
Open **Profiles** and choose the client you want to use. Configure the Claude Code, Codex, or ZCode profile from the form, select the target model, and apply the profile. For app-based profiles, use the profile action button to open the target app through CCR.
Open **Agent Config** and choose the client you want to use. Configure Claude Code, Codex, or ZCode, select the target model and effect scope, then apply the config. For app entries, use the **Open Agent** action to open the target app through CCR.
### 5. Monitor and adjust
Use **Dashboard** for usage and provider health, the tray window for quick token and account status, **Network Logs** for debugging provider behavior, and **Extensions** for plugin configuration.
Use **Settings → Logs & Observability** to enable request logs and agent observability. Use **Logs** to confirm `request model`, `resolved provider`, `resolved model`, status, tokens, latency, and errors; use the tray window for quick token and account status.
## Provider Deeplink
@ -112,22 +88,29 @@ Provider websites can open CCR and import a model provider with a custom protoco
ccr://provider?name=Example%20AI&base_url=https%3A%2F%2Fapi.example.com%2Fv1&api_key=sk-example&models=example-chat%2Cexample-coder&protocol=openai_chat_completions
```
Supported query parameters:
Supported query parameters include:
- `name`: display name for the provider.
- `base_url`: provider API base URL.
- `base_url`: provider API base URL; required for direct imports.
- `api_key`: optional provider API key.
- `models`: comma-separated or newline-separated model list. You can also repeat `models=...`.
- `protocol`: one of `openai_chat_completions`, `openai_responses`, `anthropic_messages`, or `gemini_generate_content`.
- `icon`: provider icon URL.
- `source`: provider website or config source.
- `manifest`: remote HTTPS manifest URL.
- `usage_url`, `fetch_usage`, `usage_method`, `usage_headers`, `usage_body`: optional account usage fetching configuration.
- `balance`, `balance_unit`, `subscription`, `subscription_limit`, `subscription_reset`, `subscription_unit`, `subscription_window`: optional usage field mappings.
For larger payloads, pass `payload` as URL-encoded JSON or base64url JSON with the same fields. CCR always opens a confirmation dialog before writing a provider imported from an external link.
For larger payloads, pass `payload` as URL-encoded JSON or base64url JSON with the same fields, or pass `manifest` to let CCR fetch a remote provider manifest. Manifest URLs must use HTTPS, return JSON, avoid local or private network hosts, and stay under 128 KB. Parameter names and protocol values must use the exact names above; aliases such as `baseUrl`, `apiKey`, `model`, `type`, or `openai` are not accepted.
## Plugins
CCR always opens a confirmation dialog before writing a provider imported from an external link.
CCR has two plugin layers:
## Extensions
- Core gateway plugins: use `providerPlugins` and `virtualModelProfiles`; these are passed through to the core gateway.
- Wrapper plugins: use top-level `plugins` to extend the Electron wrapper, register local HTTP backends, add gateway routes, and route proxy-mode traffic to plugin backends.
CCR has two extension layers:
- Wrapper plugins: use top-level `plugins` to extend the Electron wrapper, register local HTTP routes, start local HTTP backends, route proxy-mode traffic to plugin backends, add built-in browser entries, and connect provider account meters.
- Core gateway plugins: use `providerPlugins` or `plugins[].coreGateway.providerPlugins` to extend upstream provider, auth, or core gateway behavior. `plugins[].coreGateway.virtualModelProfiles` can inject virtual model profiles.
Example wrapper plugin route:
@ -153,46 +136,19 @@ Example wrapper plugin route:
}
```
Plugin modules export a function or object with `setup(ctx)`. The context supports:
Plugin modules export a function or an object with `setup(ctx)` or `activate(ctx)`. The context supports:
- `ctx.registerGatewayRoute({ method, path, auth, handler })`
- `ctx.registerHttpBackend({ id, host, port, handler })`
- `ctx.registerProxyRoute({ host, paths, upstream, stripPathPrefix, rewritePathPrefix, headers })`
- `ctx.registerApp(app)`
- `ctx.openSqliteStore({ filename, migrate })`
- `ctx.registerProviderAccountConnector(connector)`
- `ctx.registerCoreGatewayProviderPlugin(plugin)`
- `ctx.registerCoreGatewayVirtualModelProfile(profile)`
Local plugin examples are available in [examples/plugins](examples/plugins).
## Development
```bash
npm install
npm run dev
npm run typecheck
npm run build:assets
npm run build:app:mac
npm run build:app:win
```
`npm run build:assets` compiles the Electron main process and renderer assets into `dist/`.
`npm run build` packages the app for the current platform and writes installer artifacts to `release/`.
`npm run build:app:mac` and `npm run build:app:win` package platform-specific app artifacts. Linux AppImage packaging is configured in `electron-builder.json`.
`npm run build:app:mac` creates a local macOS test package in `release-local/` using ad-hoc signing. It is useful with a free Apple Account or Apple Development certificate, but it is not suitable for public distribution because downloaded copies will not pass Gatekeeper notarization checks.
macOS release builds are signed and notarized for distribution. Before running `npm run build:app:mac:release`, the build machine must have a `Developer ID Application` certificate available through the keychain or `CSC_LINK`/`CSC_KEY_PASSWORD`, full Xcode selected with `xcode-select`, and one notarization credential set:
- `APPLE_API_KEY`, `APPLE_API_KEY_ID`, and `APPLE_API_ISSUER`
- `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, and `APPLE_TEAM_ID`
- `APPLE_KEYCHAIN_PROFILE`, optionally with `APPLE_KEYCHAIN`
The macOS packaging hook validates codesigning, the stapled notarization ticket, and Gatekeeper assessment before writing distributable artifacts.
Packaged builds check GitHub Releases for updates through `electron-updater`. For local update feed testing, set `CCR_UPDATE_FEED_URL` to a generic electron-updater feed URL before starting the app. `CCR_UPDATE_ALLOW_PRERELEASE=1` enables prerelease updates.
## Further Reading
- [Project Motivation and How It Works](blog/en/project-motivation-and-how-it-works.md)
@ -200,113 +156,233 @@ Packaged builds check GitHub Releases for updates through `electron-updater`. Fo
## Acknowledgements
Codex support and Bot handoff are powered by [musistudio/codexl](https://github.com/musistudio/codexl).
Codex support is powered by [musistudio/codexl](https://github.com/musistudio/codexl).
## Support & Sponsoring
If you find this project helpful, please consider sponsoring its development. Your support is greatly appreciated.
<div align="center">
[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F31GN2GM)
[Paypal](https://paypal.me/musistudio1999)
<p>If you find this project helpful, please consider sponsoring its development. Your support is greatly appreciated.</p>
<table>
<tr>
<td><img src="/blog/images/alipay.jpg" width="200" alt="Alipay" /></td>
<td><img src="/blog/images/wechat.jpg" width="200" alt="WeChat Pay" /></td>
<td align="center" width="220">
<a href="https://ko-fi.com/F1F31GN2GM">
<img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Support on Ko-fi" />
</a>
<br />
<sub>One-time support via Ko-fi</sub>
</td>
<td align="center" width="220">
<a href="https://paypal.me/musistudio1999">
<img src="https://img.shields.io/badge/PayPal-Sponsor-003087?logo=paypal&logoColor=white" alt="Sponsor with PayPal" />
</a>
<br />
<sub>International sponsorship</sub>
</td>
</tr>
</table>
<table>
<tr>
<td align="center" width="220">
<strong>Alipay</strong>
<br />
<img src="/blog/images/alipay.jpg" width="160" alt="Alipay QR code" />
</td>
<td align="center" width="220">
<strong>WeChat Pay</strong>
<br />
<img src="/blog/images/wechat.jpg" width="160" alt="WeChat Pay QR code" />
</td>
</tr>
</table>
</div>
### Our Sponsors
A huge thank you to all our sponsors for their generous support.
<div align="center">
- [AIHubmix](https://aihubmix.com/)
- [BurnCloud](https://ai.burncloud.com)
- @Simon Leischnig
- [@duanshuaimin](https://github.com/duanshuaimin)
- [@vrgitadmin](https://github.com/vrgitadmin)
- @\*o
- [@ceilwoo](https://github.com/ceilwoo)
- @\*说
- @\*更
- @K\*g
- @R\*R
- [@bobleer](https://github.com/bobleer)
- @\*苗
- @\*划
- [@Clarence-pan](https://github.com/Clarence-pan)
- [@carter003](https://github.com/carter003)
- @S\*r
- @\*晖
- @\*敏
- @Z\*z
- @\*然
- [@cluic](https://github.com/cluic)
- @\*苗
- [@PromptExpert](https://github.com/PromptExpert)
- @\*应
- [@yusnake](https://github.com/yusnake)
- @\*飞
- @董\*
- @\*汀
- @\*涯
- @\*:-）
- @\*\*磊
- @\*琢
- @\*成
- @Z\*o
- @\*琨
- [@congzhangzh](https://github.com/congzhangzh)
- @\*\_
- @Z\*m
- @\*鑫
- @c\*y
- @\*昕
- [@witsice](https://github.com/witsice)
- @b\*g
- @\*亿
- @\*辉
- @JACK
- @\*光
- @W\*l
- [@kesku](https://github.com/kesku)
- [@biguncle](https://github.com/biguncle)
- @二吉吉
- @a\*g
- @\*林
- @\*咸
- @\*明
- @S\*y
- @f\*o
- @\*智
- @F\*t
- @r\*c
- [@qierkang](http://github.com/qierkang)
- @\*军
- [@snrise-z](http://github.com/snrise-z)
- @\*王
- [@greatheart1000](http://github.com/greatheart1000)
- @\*王
- @zcutlip
- [@Peng-YM](http://github.com/Peng-YM)
- @\*更
- @\*.
- @F\*t
- @\*政
- @\*铭
- @\*叶
- @七\*o
- @\*青
- @\*\*晨
- @\*远
- @\*霄
- @\*\*吉
- @\*\*飞
- @\*\*驰
- @x\*g
<p>A huge thank you to all our sponsors for their generous support.</p>
(If your name is masked, please contact me via my homepage email to update it with your GitHub username.)
<table>
<tr>
<td align="center" width="260">
<a href="https://www.bigmodel.cn/claude-code?ic=FPF9IVAGFJ"><strong>Z智谱</strong></a>
</td>
<td align="center" width="260">
<a href="https://aihubmix.com/"><strong>AIHubmix</strong></a>
</td>
</tr>
<tr>
<td align="center" width="260">
<a href="https://ai.burncloud.com"><strong>BurnCloud</strong></a>
</td>
<td align="center" width="260">
<a href="https://share.302.ai/ZGVF9w"><strong>302.AI</strong></a>
</td>
</tr>
</table>
<h4>Community Sponsors</h4>
<table>
<tr>
<td align="center" width="25%">@Simon Leischnig</td>
<td align="center" width="25%"><a href="https://github.com/duanshuaimin">@duanshuaimin</a></td>
<td align="center" width="25%"><a href="https://github.com/vrgitadmin">@vrgitadmin</a></td>
<td align="center" width="25%">@*o</td>
</tr>
<tr>
<td align="center"><a href="https://github.com/ceilwoo">@ceilwoo</a></td>
<td align="center">@*说</td>
<td align="center">@*更</td>
<td align="center">@K*g</td>
</tr>
<tr>
<td align="center">@R*R</td>
<td align="center"><a href="https://github.com/bobleer">@bobleer</a></td>
<td align="center">@*苗</td>
<td align="center">@*划</td>
</tr>
<tr>
<td align="center"><a href="https://github.com/Clarence-pan">@Clarence-pan</a></td>
<td align="center"><a href="https://github.com/carter003">@carter003</a></td>
<td align="center">@S*r</td>
<td align="center">@*晖</td>
</tr>
<tr>
<td align="center">@*敏</td>
<td align="center">@Z*z</td>
<td align="center">@*然</td>
<td align="center"><a href="https://github.com/cluic">@cluic</a></td>
</tr>
<tr>
<td align="center">@*苗</td>
<td align="center"><a href="https://github.com/PromptExpert">@PromptExpert</a></td>
<td align="center">@*应</td>
<td align="center"><a href="https://github.com/yusnake">@yusnake</a></td>
</tr>
<tr>
<td align="center">@*飞</td>
<td align="center">@董*</td>
<td align="center">@*汀</td>
<td align="center">@*涯</td>
</tr>
<tr>
<td align="center">@*:-）</td>
<td align="center">@**磊</td>
<td align="center">@*琢</td>
<td align="center">@*成</td>
</tr>
<tr>
<td align="center">@Z*o</td>
<td align="center">@*琨</td>
<td align="center"><a href="https://github.com/congzhangzh">@congzhangzh</a></td>
<td align="center">@*_</td>
</tr>
<tr>
<td align="center">@Z*m</td>
<td align="center">@*鑫</td>
<td align="center">@c*y</td>
<td align="center">@*昕</td>
</tr>
<tr>
<td align="center"><a href="https://github.com/witsice">@witsice</a></td>
<td align="center">@b*g</td>
<td align="center">@*亿</td>
<td align="center">@*辉</td>
</tr>
<tr>
<td align="center">@JACK</td>
<td align="center">@*光</td>
<td align="center">@W*l</td>
<td align="center"><a href="https://github.com/kesku">@kesku</a></td>
</tr>
<tr>
<td align="center"><a href="https://github.com/biguncle">@biguncle</a></td>
<td align="center">@二吉吉</td>
<td align="center">@a*g</td>
<td align="center">@*林</td>
</tr>
<tr>
<td align="center">@*咸</td>
<td align="center">@*明</td>
<td align="center">@S*y</td>
<td align="center">@f*o</td>
</tr>
<tr>
<td align="center">@*智</td>
<td align="center">@F*t</td>
<td align="center">@r*c</td>
<td align="center"><a href="https://github.com/qierkang">@qierkang</a></td>
</tr>
<tr>
<td align="center">@*军</td>
<td align="center"><a href="https://github.com/snrise-z">@snrise-z</a></td>
<td align="center">@*王</td>
<td align="center"><a href="https://github.com/greatheart1000">@greatheart1000</a></td>
</tr>
<tr>
<td align="center">@*王</td>
<td align="center">@zcutlip</td>
<td align="center"><a href="https://github.com/Peng-YM">@Peng-YM</a></td>
<td align="center">@*更</td>
</tr>
<tr>
<td align="center">@*.</td>
<td align="center">@F*t</td>
<td align="center">@*政</td>
<td align="center">@*铭</td>
</tr>
<tr>
<td align="center">@*叶</td>
<td align="center">@七*o</td>
<td align="center">@*青</td>
<td align="center">@**晨</td>
</tr>
<tr>
<td align="center">@*远</td>
<td align="center">@*霄</td>
<td align="center">@**吉</td>
<td align="center">@**飞</td>
</tr>
<tr>
<td align="center">@**驰</td>
<td align="center">@x*g</td>
<td align="center">@**东</td>
<td align="center">@*落</td>
</tr>
<tr>
<td align="center">@哆*k</td>
<td align="center">@*涛</td>
<td align="center"><a href="https://github.com/WitMiao">@苗大</a></td>
<td align="center">@*呢</td>
</tr>
<tr>
<td align="center">@d*u</td>
<td align="center">@crizcraig</td>
<td align="center">s*s</td>
<td align="center">*火</td>
</tr>
<tr>
<td align="center">*勤</td>
<td align="center">**锟</td>
<td align="center">*涛</td>
<td align="center">**明</td>
</tr>
<tr>
<td align="center">*知</td>
<td align="center">*语</td>
<td align="center">*瓜</td>
<td align="center"></td>
</tr>
</table>
<sub>If your name is masked, please contact me via my homepage email to update it with your GitHub username.</sub>
</div>
## License

418
README_zh.md
View file

@ -3,6 +3,7 @@
<p align="center">
<a href="README.md"><img alt="English README" src="https://img.shields.io/badge/%F0%9F%87%AC%F0%9F%87%A7-English-000aff?style=flat" /></a>
<a href="https://discord.gg/rdftVMaUcS"><img alt="Discord" src="https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white" /></a>
<a href="https://x.com/musistudio2026"><img alt="X" src="https://img.shields.io/badge/X-@musistudio2026-000000?logo=x&logoColor=white" /></a>
<a href="https://github.com/musistudio/claude-code-router/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/musistudio/claude-code-router" /></a>
<a href="https://ccrdesk.top/"><img alt="文档" src="https://img.shields.io/badge/%E6%96%87%E6%A1%A3-ccrdesk.top-0ea5e9?style=flat" /></a>
</p>
@ -13,7 +14,7 @@
Claude Code Router Desktop 是一个本地网关和桌面控制台，用来把 Claude Code、Codex、ZCode 以及兼容客户端的 Agent 请求路由到你真正想使用的模型服务。
CCR 在你的本机运行，Provider 配置保存在本地配置目录，并默认暴露本地网关地址：`http://127.0.0.1:3456`。
CCR 在你的本机运行，Provider 配置保存在本地配置目录，并默认暴露本地网关地址：`http://localhost:8080`。
## 为什么使用 CCR
@ -26,40 +27,18 @@ CCR 在你的本机运行，Provider 配置保存在本地配置目录，并默
## 功能和特性
- **桌面控制台**：启动或停止本地网关，查看用量，配置托盘窗口和运行时设置。
- **Provider 管理**：添加预设或自定义端点，检测连通性，管理凭据，并在可用时查看账号余额。
- **路由规则**：配置默认、后台、thinking、长上下文、图片、Web Search、Subagent、模型前缀和条件路由。
- **Agent Profiles**：为 Claude Code、Codex 和 ZCode 配置指向 CCR 网关的 Profile。
- **网关兼容层**：通过本地 CCR wrapper 和 core gateway runtime 转换客户端请求。
- **概览仪表盘**：查看系统状态、用量组件、账号余额、模型分布和分享卡片。
- **Provider 管理**：添加预设或自定义端点，探测协议支持，检测模型连通性，管理凭据，并在可用时查看账号余额。
- **路由规则**：配置默认路由、条件路由、模型前缀规则、失败降级和请求改写。
- **Agent配置**：为 Claude Code、Codex 和 ZCode 配置启动入口、模型、作用范围和多开 App 配置。
- **网关兼容层**：通过本地 CCR 模型网关转换支持的客户端请求。
- **代理模式**：通过本地代理捕获支持的 API 流量，可选系统代理和网络捕获。
- **插件系统**：安装或加载 wrapper 插件，包括 Claude Design、Cursor Proxy 这类集成路由。
- **虚拟模型**：为客户端暴露模型别名或组合模型配置，适配固定模型名场景。
- **Provider Deeplink**：通过 `ccr://provider?...` 链接导入 Provider 配置，写入前会弹出确认。
- **扩展机制**：安装或加载 wrapper 插件，包括 Claude Design、Cursor Proxy 这类集成路由。
- **Fusion 组合模型**：把基础模型与视觉、联网搜索或 MCP 工具组合成新的可选模型。
- **Provider Deeplink**：通过 `ccr://provider?...` 链接导入 Provider 配置、manifest 和嵌入式一键导入按钮，写入前会弹出确认。
## 下载和安装
### npm CLI
如果你只需要 CLI 版本，不需要桌面 Tray 或 `ccr://` 协议集成，可以安装 npm 包：
```bash
npm install -g claude-code-router
ccr start
```
常用命令：
```bash
ccr start # 后台启动 CCR 服务和 Web 管理端
ccr stop # 停止后台 CCR 服务
ccr <profile-name> cli # 以 CLI 方式启动保存的 profile
ccr <profile-name> app # 以 App 方式启动保存的 profile
```
Web 管理端默认监听 `http://127.0.0.1:3458`。可以用 `ccr start --host <host> --port <port>` 修改监听地址。
### 桌面应用
1. 打开 [GitHub Releases 页面](https://github.com/musistudio/claude-code-router/releases)。
2. 按系统下载对应安装包：
- macOS Apple 芯片：`Claude-Code-Router_<version>-mac-Apple-Silicon-arm64.dmg` 或 `.zip`
@ -73,10 +52,7 @@ Web 管理端默认监听 `http://127.0.0.1:3458`。可以用 `ccr start --host
CCR 的运行配置存储在 SQLite 中。旧版 `config.json` 只会在没有 SQLite 配置时作为迁移来源读取一次。
启用网关后，CCR 会启动两个本地服务：
- CCR wrapper gateway：`http://127.0.0.1:3456`
- Core gateway runtime：`http://127.0.0.1:3457`
从 **服务** 页面启动后，CCR 默认监听 `http://localhost:8080`。**服务** 页面负责配置网关 `Host`、`Port`、代理模式、系统代理、网络捕获和 CA 证书状态。
## 快速开始
@ -84,25 +60,25 @@ CCR 可以完全通过桌面 UI 完成配置。首次使用建议按下面顺序
### 1. 添加 Provider
打开 **Providers**，点击 **Add Provider**，选择内置预设或创建自定义 Provider。按表单填写 Provider 名称、端点、协议、API Key 和模型列表。可用时先运行连通性检测，然后保存 Provider。
打开 **供应商**，点击 **添加供应商**，选择内置预设或 **其他 / 自定义 API 端点**。按表单填写 Provider 名称、基础 URL、协议、API Key 和模型列表。可用时先运行协议探测和模型连通性检查，然后保存 Provider。
### 2. 设置路由
打开 **Routing**，先选择默认路由要使用的 provider/model。然后根据需要设置后台任务、Thinking、长上下文、图片任务和 Web Search 等场景的专用模型。
打开 **路由**，选择默认路由，添加条件规则，配置请求改写和失败降级。
如果需要更细粒度控制，使用 **Add Routing Rule** 添加模型前缀、Subagent、请求条件或 fallback 规则。
如果需要更细粒度控制，使用 **添加路由规则** 添加模型前缀、请求条件或规则级失败降级目标。
### 3. 启动网关
打开 **Server**，点击 **Start** 启动本地网关。如果希望每次打开桌面应用时自动启动网关，可以启用 auto start。
打开 **服务**，点击 **启动**。页面显示运行中后，CCR 会在本机监听 `http://localhost:8080`。如果希望每次打开桌面应用时自动启动网关，可以启用自动启动。
### 4. 连接 Agent 工具
打开 **Profiles**，选择要使用的客户端。通过表单配置 Claude Code、Codex 或 ZCode Profile，选择目标模型并应用配置。对于 App 类型的 Profile，可以使用页面里的操作按钮通过 CCR 打开目标应用。
打开 **Agent配置**，选择要使用的客户端。配置 Claude Code、Codex 或 ZCode，选择目标模型和作用范围，然后应用配置。对于 App 入口，可以使用 **打开 Agent** 操作通过 CCR 打开目标应用。
### 5. 日常查看和调整
使用 **Dashboard** 查看用量和 Provider 状态，使用托盘窗口快速查看 Token 和账号状态，使用 **Network Logs** 调试 Provider 行为，使用 **Extensions** 配置插件。
到 **设置 → 日志与观测** 打开请求日志和 Agent 观测。使用 **日志** 确认 `request model`、`resolved provider`、`resolved model`、状态码、tokens、耗时和错误；使用托盘窗口快速查看 Token 和账号状态。
## Provider Deeplink
@ -112,22 +88,29 @@ Provider 网站可以通过自定义协议打开 CCR 并导入模型服务配置
ccr://provider?name=Example%20AI&base_url=https%3A%2F%2Fapi.example.com%2Fv1&api_key=sk-example&models=example-chat%2Cexample-coder&protocol=openai_chat_completions
```
支持的 query 参数：
支持的 query 参数包括：
- `name`：Provider 展示名称。
- `base_url`：Provider API Base URL。
- `base_url`：Provider API Base URL，直链导入时必填。
- `api_key`：可选 Provider API Key。
- `models`：逗号或换行分隔的模型列表，也可以重复传入 `models=...`。
- `protocol`：`openai_chat_completions`、`openai_responses`、`anthropic_messages` 或 `gemini_generate_content`。
- `icon`：Provider 图标 URL。
- `source`：Provider 官网或配置来源。
- `manifest`：远程 HTTPS manifest URL。
- `usage_url`、`fetch_usage`、`usage_method`、`usage_headers`、`usage_body`：可选账号用量读取配置。
- `balance`、`balance_unit`、`subscription`、`subscription_limit`、`subscription_reset`、`subscription_unit`、`subscription_window`：可选用量字段映射。
更大的 payload 可以通过 URL 编码 JSON 或 base64url JSON 传入 `payload` 字段。CCR 在写入外部链接导入的 Provider 前，总会弹出确认窗口。
更大的 payload 可以通过 URL 编码 JSON 或 base64url JSON 传入 `payload` 字段，也可以传入 `manifest` 让 CCR 拉取远程 Provider manifest。Manifest 必须使用 HTTPS，返回 JSON，不能指向本地或内网地址，体积不能超过 128 KB。参数名和协议值必须使用上面的完整规范名；不再接受 `baseUrl`、`apiKey`、`model`、`type` 或 `openai` 等别名。
## 插件
CCR 在写入外部链接导入的 Provider 前，总会弹出确认窗口。
CCR 有两层插件：
## 扩展机制
- Core gateway plugins：使用 `providerPlugins` 和 `virtualModelProfiles`，会透传给 core gateway。
- Wrapper plugins：使用顶层 `plugins` 扩展 Electron wrapper，注册本地 HTTP 后端、添加 gateway route，或把代理模式流量路由到插件后端。
CCR 有两层扩展：
- Wrapper plugin：使用顶层 `plugins` 扩展 Electron wrapper，注册本地 HTTP 路由、启动本地后端、拦截代理流量、添加内置浏览器入口、连接 Provider 账号用量。
- Core gateway plugin：使用 `providerPlugins` 或 `plugins[].coreGateway.providerPlugins` 扩展上游 Provider、认证方式或 core gateway 内部能力。`plugins[].coreGateway.virtualModelProfiles` 可以注入虚拟模型配置。
Wrapper plugin route 示例：
@ -153,46 +136,19 @@ Wrapper plugin route 示例：
}
```
插件模块需要导出函数或包含 `setup(ctx)` 的对象。上下文支持：
插件模块需要导出函数，或包含 `setup(ctx)` / `activate(ctx)` 的对象。上下文支持：
- `ctx.registerGatewayRoute({ method, path, auth, handler })`
- `ctx.registerHttpBackend({ id, host, port, handler })`
- `ctx.registerProxyRoute({ host, paths, upstream, stripPathPrefix, rewritePathPrefix, headers })`
- `ctx.registerApp(app)`
- `ctx.openSqliteStore({ filename, migrate })`
- `ctx.registerProviderAccountConnector(connector)`
- `ctx.registerCoreGatewayProviderPlugin(plugin)`
- `ctx.registerCoreGatewayVirtualModelProfile(profile)`
本地插件示例见 [examples/plugins](examples/plugins)。
## 开发
```bash
npm install
npm run dev
npm run typecheck
npm run build:assets
npm run build:app:mac
npm run build:app:win
```
`npm run build:assets` 会把 Electron main process 和 renderer assets 编译到 `dist/`。
`npm run build` 会为当前平台打包应用，并把安装包写入 `release/`。
`npm run build:app:mac` 和 `npm run build:app:win` 会分别打包对应平台的应用产物。Linux AppImage 打包配置在 `electron-builder.json` 中。
`npm run build:app:mac` 会在 `release-local/` 生成本地测试用 macOS 包，使用 ad-hoc 签名。它适合免费 Apple Account 或只有 Apple Development 证书的本机测试，但不适合公开分发，因为用户下载后仍无法通过 Gatekeeper 公证检查。
macOS 发布包会使用 Developer ID 签名并提交 Apple 公证。运行 `npm run build:app:mac:release` 前，打包机器必须具备：可用的 `Developer ID Application` 证书（在 keychain 中，或通过 `CSC_LINK`/`CSC_KEY_PASSWORD` 提供）、已通过 `xcode-select` 选择完整 Xcode，以及下面任意一组公证凭据：
- `APPLE_API_KEY`、`APPLE_API_KEY_ID`、`APPLE_API_ISSUER`
- `APPLE_ID`、`APPLE_APP_SPECIFIC_PASSWORD`、`APPLE_TEAM_ID`
- `APPLE_KEYCHAIN_PROFILE`，可选 `APPLE_KEYCHAIN`
macOS 打包 hook 会在产物生成前验证代码签名、公证票据 stapling 和 Gatekeeper 评估，避免发布未公证的安装包。
打包后的应用会通过 `electron-updater` 检查 GitHub Releases。测试本地更新源时，可以在启动应用前设置 `CCR_UPDATE_FEED_URL` 为 generic electron-updater feed URL。`CCR_UPDATE_ALLOW_PRERELEASE=1` 可以启用 prerelease 更新。
## 深入阅读
- [项目动机和工作原理](blog/zh/项目初衷及原理.md)
@ -200,113 +156,233 @@ macOS 打包 hook 会在产物生成前验证代码签名、公证票据 staplin
## 致谢
对 Codex 的支持以及 Bot handoff 来自于 [musistudio/codexl](https://github.com/musistudio/codexl) 这个项目。
对 Codex 的支持来自于 [musistudio/codexl](https://github.com/musistudio/codexl) 这个项目。
## 支持与赞助
如果你觉得这个项目有帮助，欢迎赞助项目开发。非常感谢你的支持。
<div align="center">
[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F31GN2GM)
[Paypal](https://paypal.me/musistudio1999)
<p>如果你觉得这个项目有帮助，欢迎赞助项目开发。非常感谢你的支持。</p>
<table>
<tr>
<td><img src="/blog/images/alipay.jpg" width="200" alt="Alipay" /></td>
<td><img src="/blog/images/wechat.jpg" width="200" alt="WeChat Pay" /></td>
<td align="center" width="220">
<a href="https://ko-fi.com/F1F31GN2GM">
<img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="通过 Ko-fi 赞助" />
</a>
<br />
<sub>通过 Ko-fi 单次赞助</sub>
</td>
<td align="center" width="220">
<a href="https://paypal.me/musistudio1999">
<img src="https://img.shields.io/badge/PayPal-Sponsor-003087?logo=paypal&logoColor=white" alt="通过 PayPal 赞助" />
</a>
<br />
<sub>国际赞助通道</sub>
</td>
</tr>
</table>
<table>
<tr>
<td align="center" width="220">
<strong>支付宝</strong>
<br />
<img src="/blog/images/alipay.jpg" width="160" alt="支付宝收款码" />
</td>
<td align="center" width="220">
<strong>微信支付</strong>
<br />
<img src="/blog/images/wechat.jpg" width="160" alt="微信支付收款码" />
</td>
</tr>
</table>
</div>
### 我们的赞助商
非常感谢所有赞助商的慷慨支持。
<div align="center">
- [AIHubmix](https://aihubmix.com/)
- [BurnCloud](https://ai.burncloud.com)
- @Simon Leischnig
- [@duanshuaimin](https://github.com/duanshuaimin)
- [@vrgitadmin](https://github.com/vrgitadmin)
- @\*o
- [@ceilwoo](https://github.com/ceilwoo)
- @\*说
- @\*更
- @K\*g
- @R\*R
- [@bobleer](https://github.com/bobleer)
- @\*苗
- @\*划
- [@Clarence-pan](https://github.com/Clarence-pan)
- [@carter003](https://github.com/carter003)
- @S\*r
- @\*晖
- @\*敏
- @Z\*z
- @\*然
- [@cluic](https://github.com/cluic)
- @\*苗
- [@PromptExpert](https://github.com/PromptExpert)
- @\*应
- [@yusnake](https://github.com/yusnake)
- @\*飞
- @董\*
- @\*汀
- @\*涯
- @\*:-）
- @\*\*磊
- @\*琢
- @\*成
- @Z\*o
- @\*琨
- [@congzhangzh](https://github.com/congzhangzh)
- @\*\_
- @Z\*m
- @\*鑫
- @c\*y
- @\*昕
- [@witsice](https://github.com/witsice)
- @b\*g
- @\*亿
- @\*辉
- @JACK
- @\*光
- @W\*l
- [@kesku](https://github.com/kesku)
- [@biguncle](https://github.com/biguncle)
- @二吉吉
- @a\*g
- @\*林
- @\*咸
- @\*明
- @S\*y
- @f\*o
- @\*智
- @F\*t
- @r\*c
- [@qierkang](http://github.com/qierkang)
- @\*军
- [@snrise-z](http://github.com/snrise-z)
- @\*王
- [@greatheart1000](http://github.com/greatheart1000)
- @\*王
- @zcutlip
- [@Peng-YM](http://github.com/Peng-YM)
- @\*更
- @\*.
- @F\*t
- @\*政
- @\*铭
- @\*叶
- @七\*o
- @\*青
- @\*\*晨
- @\*远
- @\*霄
- @\*\*吉
- @\*\*飞
- @\*\*驰
- @x\*g
<p>非常感谢所有赞助商的慷慨支持。</p>
（如果你的名字被打码，请通过我的主页邮箱联系我更新为 GitHub 用户名。）
<table>
<tr>
<td align="center" width="260">
<a href="https://www.bigmodel.cn/claude-code?ic=FPF9IVAGFJ"><strong>Z智谱</strong></a>
</td>
<td align="center" width="260">
<a href="https://aihubmix.com/"><strong>AIHubmix</strong></a>
</td>
</tr>
<tr>
<td align="center" width="260">
<a href="https://ai.burncloud.com"><strong>BurnCloud</strong></a>
</td>
<td align="center" width="260">
<a href="https://share.302.ai/ZGVF9w"><strong>302.AI</strong></a>
</td>
</tr>
</table>
<h4>社区赞助者</h4>
<table>
<tr>
<td align="center" width="25%">@Simon Leischnig</td>
<td align="center" width="25%"><a href="https://github.com/duanshuaimin">@duanshuaimin</a></td>
<td align="center" width="25%"><a href="https://github.com/vrgitadmin">@vrgitadmin</a></td>
<td align="center" width="25%">@*o</td>
</tr>
<tr>
<td align="center"><a href="https://github.com/ceilwoo">@ceilwoo</a></td>
<td align="center">@*说</td>
<td align="center">@*更</td>
<td align="center">@K*g</td>
</tr>
<tr>
<td align="center">@R*R</td>
<td align="center"><a href="https://github.com/bobleer">@bobleer</a></td>
<td align="center">@*苗</td>
<td align="center">@*划</td>
</tr>
<tr>
<td align="center"><a href="https://github.com/Clarence-pan">@Clarence-pan</a></td>
<td align="center"><a href="https://github.com/carter003">@carter003</a></td>
<td align="center">@S*r</td>
<td align="center">@*晖</td>
</tr>
<tr>
<td align="center">@*敏</td>
<td align="center">@Z*z</td>
<td align="center">@*然</td>
<td align="center"><a href="https://github.com/cluic">@cluic</a></td>
</tr>
<tr>
<td align="center">@*苗</td>
<td align="center"><a href="https://github.com/PromptExpert">@PromptExpert</a></td>
<td align="center">@*应</td>
<td align="center"><a href="https://github.com/yusnake">@yusnake</a></td>
</tr>
<tr>
<td align="center">@*飞</td>
<td align="center">@董*</td>
<td align="center">@*汀</td>
<td align="center">@*涯</td>
</tr>
<tr>
<td align="center">@*:-）</td>
<td align="center">@**磊</td>
<td align="center">@*琢</td>
<td align="center">@*成</td>
</tr>
<tr>
<td align="center">@Z*o</td>
<td align="center">@*琨</td>
<td align="center"><a href="https://github.com/congzhangzh">@congzhangzh</a></td>
<td align="center">@*_</td>
</tr>
<tr>
<td align="center">@Z*m</td>
<td align="center">@*鑫</td>
<td align="center">@c*y</td>
<td align="center">@*昕</td>
</tr>
<tr>
<td align="center"><a href="https://github.com/witsice">@witsice</a></td>
<td align="center">@b*g</td>
<td align="center">@*亿</td>
<td align="center">@*辉</td>
</tr>
<tr>
<td align="center">@JACK</td>
<td align="center">@*光</td>
<td align="center">@W*l</td>
<td align="center"><a href="https://github.com/kesku">@kesku</a></td>
</tr>
<tr>
<td align="center"><a href="https://github.com/biguncle">@biguncle</a></td>
<td align="center">@二吉吉</td>
<td align="center">@a*g</td>
<td align="center">@*林</td>
</tr>
<tr>
<td align="center">@*咸</td>
<td align="center">@*明</td>
<td align="center">@S*y</td>
<td align="center">@f*o</td>
</tr>
<tr>
<td align="center">@*智</td>
<td align="center">@F*t</td>
<td align="center">@r*c</td>
<td align="center"><a href="https://github.com/qierkang">@qierkang</a></td>
</tr>
<tr>
<td align="center">@*军</td>
<td align="center"><a href="https://github.com/snrise-z">@snrise-z</a></td>
<td align="center">@*王</td>
<td align="center"><a href="https://github.com/greatheart1000">@greatheart1000</a></td>
</tr>
<tr>
<td align="center">@*王</td>
<td align="center">@zcutlip</td>
<td align="center"><a href="https://github.com/Peng-YM">@Peng-YM</a></td>
<td align="center">@*更</td>
</tr>
<tr>
<td align="center">@*.</td>
<td align="center">@F*t</td>
<td align="center">@*政</td>
<td align="center">@*铭</td>
</tr>
<tr>
<td align="center">@*叶</td>
<td align="center">@七*o</td>
<td align="center">@*青</td>
<td align="center">@**晨</td>
</tr>
<tr>
<td align="center">@*远</td>
<td align="center">@*霄</td>
<td align="center">@**吉</td>
<td align="center">@**飞</td>
</tr>
<tr>
<td align="center">@**驰</td>
<td align="center">@x*g</td>
<td align="center">@**东</td>
<td align="center">@*落</td>
</tr>
<tr>
<td align="center">@哆*k</td>
<td align="center">@*涛</td>
<td align="center"><a href="https://github.com/WitMiao">@苗大</a></td>
<td align="center">@*呢</td>
</tr>
<tr>
<td align="center">@d*u</td>
<td align="center">@crizcraig</td>
<td align="center">s*s</td>
<td align="center">*火</td>
</tr>
<tr>
<td align="center">*勤</td>
<td align="center">**锟</td>
<td align="center">*涛</td>
<td align="center">**明</td>
</tr>
<tr>
<td align="center">*知</td>
<td align="center">*语</td>
<td align="center">*瓜</td>
<td align="center"></td>
</tr>
</table>
<sub>如果你的名字被打码，请通过我的主页邮箱联系我更新为 GitHub 用户名。</sub>
</div>
## 许可证

8
package-lock.json generated
View file

@ -9,7 +9,7 @@
"version": "3.0.4",
"license": "MIT",
"dependencies": {
"@the-next-ai/ai-gateway": "^1.0.2",
"@the-next-ai/ai-gateway": "^1.0.3",
"@the-next-ai/bot-gateway-sdk": "^0.1.0",
"better-sqlite3": "^12.11.1",
"electron-updater": "^6.8.9",
@ -2066,9 +2066,9 @@
}
},
"node_modules/@the-next-ai/ai-gateway": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/@the-next-ai/ai-gateway/-/ai-gateway-1.0.2.tgz",
"integrity": "sha512-K0UiXwyC1i6dpPtQWDndJ1SgwI+zmfGpwqFUWhnVico4dxCt9eph5d9mt0RHcEduZOv4MRBdWDHyHMpxDgSUCw==",
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/@the-next-ai/ai-gateway/-/ai-gateway-1.0.3.tgz",
"integrity": "sha512-+cZtmhCB1UbxYpn0EPVHlr4qO6W/yBhMidF/JPYdeNG11uGbxSPY9CnS5rKF1v2B6mrgL65lUzL3VnMK4Iq2Ug==",
"license": "MIT",
"dependencies": {
"diff": "^8.0.3",

2
package.json
View file

@ -52,7 +52,7 @@
"rebuild:sqlite3": "electron-rebuild -f -w better-sqlite3"
},
"dependencies": {
"@the-next-ai/ai-gateway": "^1.0.2",
"@the-next-ai/ai-gateway": "^1.0.3",
"@the-next-ai/bot-gateway-sdk": "^0.1.0",
"better-sqlite3": "^12.11.1",
"electron-updater": "^6.8.9",