@musistudio/claude-code-router 1.0.73 → 3.0.0

package/README.md

@@ -1,662 +1,329 @@
-![](blog/images/claude-code-router-img.png)
+<h1 align="center">Claude Code Router Desktop</h1>
 
-[![](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)](README_zh.md)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white)](https://discord.gg/rdftVMaUcS)
-[![](https://img.shields.io/github/license/musistudio/claude-code-router)](https://github.com/musistudio/claude-code-router/blob/main/LICENSE)
-
-<hr>
-
-![](blog/images/sponsors/glm-en.jpg)
-> This project is sponsored by Z.ai, supporting us with their GLM CODING PLAN.    
-> GLM CODING PLAN is a subscription service designed for AI coding, starting at just $3/month. It provides access to their flagship GLM-4.6 model across 10+ popular AI coding tools (Claude Code, Cline, Roo Code, etc.), offering developers top-tier, fast, and stable coding experiences.     
-> Get 10% OFF GLM CODING PLAN：https://z.ai/subscribe?ic=8JVLJQFSKB     
-
-> A powerful tool to route Claude Code requests to different models and customize any request.
-
-> [GLM-4.6 Supports Reasoning and Interleaved Thinking](blog/en/glm-4.6-supports-reasoning.md)
-
-![](blog/images/claude-code.png)
-
-## ✨ Features
-
-- **Model Routing**: Route requests to different models based on your needs (e.g., background tasks, thinking, long context).
-- **Multi-Provider Support**: Supports various model providers like OpenRouter, DeepSeek, Ollama, Gemini, Volcengine, and SiliconFlow.
-- **Request/Response Transformation**: Customize requests and responses for different providers using transformers.
-- **Dynamic Model Switching**: Switch models on-the-fly within Claude Code using the `/model` command.
-- **CLI Model Management**: Manage models and providers directly from the terminal with `ccr model`.
-- **GitHub Actions Integration**: Trigger Claude Code tasks in your GitHub workflows.
-- **Plugin System**: Extend functionality with custom transformers.
-
-## 🚀 Getting Started
-
-### 1. Installation
-
-First, ensure you have [Claude Code](https://docs.anthropic.com/en/docs/claude-code/quickstart) installed:
-
-```shell
-npm install -g @anthropic-ai/claude-code
-```
-
-Then, install Claude Code Router:
-
-```shell
-npm install -g @musistudio/claude-code-router
-```
-
-### 2. Configuration
-
-Create and configure your `~/.claude-code-router/config.json` file. For more details, you can refer to `config.example.json`.
-
-The `config.json` file has several key sections:
-
-- **`PROXY_URL`** (optional): You can set a proxy for API requests, for example: `"PROXY_URL": "http://127.0.0.1:7890"`.
-- **`LOG`** (optional): You can enable logging by setting it to `true`. When set to `false`, no log files will be created. Default is `true`.
-- **`LOG_LEVEL`** (optional): Set the logging level. Available options are: `"fatal"`, `"error"`, `"warn"`, `"info"`, `"debug"`, `"trace"`. Default is `"debug"`.
-- **Logging Systems**: The Claude Code Router uses two separate logging systems:
-  - **Server-level logs**: HTTP requests, API calls, and server events are logged using pino in the `~/.claude-code-router/logs/` directory with filenames like `ccr-*.log`
-  - **Application-level logs**: Routing decisions and business logic events are logged in `~/.claude-code-router/claude-code-router.log`
-- **`APIKEY`** (optional): You can set a secret key to authenticate requests. When set, clients must provide this key in the `Authorization` header (e.g., `Bearer your-secret-key`) or the `x-api-key` header. Example: `"APIKEY": "your-secret-key"`.
-- **`HOST`** (optional): You can set the host address for the server. If `APIKEY` is not set, the host will be forced to `127.0.0.1` for security reasons to prevent unauthorized access. Example: `"HOST": "0.0.0.0"`.
-- **`NON_INTERACTIVE_MODE`** (optional): When set to `true`, enables compatibility with non-interactive environments like GitHub Actions, Docker containers, or other CI/CD systems. This sets appropriate environment variables (`CI=true`, `FORCE_COLOR=0`, etc.) and configures stdin handling to prevent the process from hanging in automated environments. Example: `"NON_INTERACTIVE_MODE": true`.
-
-- **`Providers`**: Used to configure different model providers.
-- **`Router`**: Used to set up routing rules. `default` specifies the default model, which will be used for all requests if no other route is configured.
-- **`API_TIMEOUT_MS`**: Specifies the timeout for API calls in milliseconds.
-
-#### Environment Variable Interpolation
-
-Claude Code Router supports environment variable interpolation for secure API key management. You can reference environment variables in your `config.json` using either `$VAR_NAME` or `${VAR_NAME}` syntax:
-
-```json
-{
-  "OPENAI_API_KEY": "$OPENAI_API_KEY",
-  "GEMINI_API_KEY": "${GEMINI_API_KEY}",
-  "Providers": [
-    {
-      "name": "openai",
-      "api_base_url": "https://api.openai.com/v1/chat/completions",
-      "api_key": "$OPENAI_API_KEY",
-      "models": ["gpt-5", "gpt-5-mini"]
-    }
-  ]
-}
-```
-
-This allows you to keep sensitive API keys in environment variables instead of hardcoding them in configuration files. The interpolation works recursively through nested objects and arrays.
-
-Here is a comprehensive example:
-
-```json
-{
-  "APIKEY": "your-secret-key",
-  "PROXY_URL": "http://127.0.0.1:7890",
-  "LOG": true,
-  "API_TIMEOUT_MS": 600000,
-  "NON_INTERACTIVE_MODE": false,
-  "Providers": [
-    {
-      "name": "openrouter",
-      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
-      "api_key": "sk-xxx",
-      "models": [
-        "google/gemini-2.5-pro-preview",
-        "anthropic/claude-sonnet-4",
-        "anthropic/claude-3.5-sonnet",
-        "anthropic/claude-3.7-sonnet:thinking"
-      ],
-      "transformer": {
-        "use": ["openrouter"]
-      }
-    },
-    {
-      "name": "deepseek",
-      "api_base_url": "https://api.deepseek.com/chat/completions",
-      "api_key": "sk-xxx",
-      "models": ["deepseek-chat", "deepseek-reasoner"],
-      "transformer": {
-        "use": ["deepseek"],
-        "deepseek-chat": {
-          "use": ["tooluse"]
-        }
-      }
-    },
-    {
-      "name": "ollama",
-      "api_base_url": "http://localhost:11434/v1/chat/completions",
-      "api_key": "ollama",
-      "models": ["qwen2.5-coder:latest"]
-    },
-    {
-      "name": "gemini",
-      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
-      "api_key": "sk-xxx",
-      "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
-      "transformer": {
-        "use": ["gemini"]
-      }
-    },
-    {
-      "name": "volcengine",
-      "api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
-      "api_key": "sk-xxx",
-      "models": ["deepseek-v3-250324", "deepseek-r1-250528"],
-      "transformer": {
-        "use": ["deepseek"]
-      }
-    },
-    {
-      "name": "modelscope",
-      "api_base_url": "https://api-inference.modelscope.cn/v1/chat/completions",
-      "api_key": "",
-      "models": ["Qwen/Qwen3-Coder-480B-A35B-Instruct", "Qwen/Qwen3-235B-A22B-Thinking-2507"],
-      "transformer": {
-        "use": [
-          [
-            "maxtoken",
-            {
-              "max_tokens": 65536
-            }
-          ],
-          "enhancetool"
-        ],
-        "Qwen/Qwen3-235B-A22B-Thinking-2507": {
-          "use": ["reasoning"]
-        }
-      }
-    },
-    {
-      "name": "dashscope",
-      "api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
-      "api_key": "",
-      "models": ["qwen3-coder-plus"],
-      "transformer": {
-        "use": [
-          [
-            "maxtoken",
-            {
-              "max_tokens": 65536
-            }
-          ],
-          "enhancetool"
-        ]
-      }
-    },
-    {
-      "name": "aihubmix",
-      "api_base_url": "https://aihubmix.com/v1/chat/completions",
-      "api_key": "sk-",
-      "models": [
-        "Z/glm-4.5",
-        "claude-opus-4-20250514",
-        "gemini-2.5-pro"
-      ]
-    }
-  ],
-  "Router": {
-    "default": "deepseek,deepseek-chat",
-    "background": "ollama,qwen2.5-coder:latest",
-    "think": "deepseek,deepseek-reasoner",
-    "longContext": "openrouter,google/gemini-2.5-pro-preview",
-    "longContextThreshold": 60000,
-    "webSearch": "gemini,gemini-2.5-flash"
-  }
-}
-```
-
-### 3. Running Claude Code with the Router
-
-Start Claude Code using the router:
-
-```shell
-ccr code
-```
-
-> **Note**: After modifying the configuration file, you need to restart the service for the changes to take effect:
->
-> ```shell
-> ccr restart
-> ```
-
-### 4. UI Mode
-
-For a more intuitive experience, you can use the UI mode to manage your configuration:
-
-```shell
-ccr ui
-```
-
-This will open a web-based interface where you can easily view and edit your `config.json` file.
-
-![UI](/blog/images/ui.png)
-
-### 5. CLI Model Management
-
-For users who prefer terminal-based workflows, you can use the interactive CLI model selector:
-
-```shell
-ccr model
-```
-![](blog/images/models.gif)
-
-This command provides an interactive interface to:
-
-- View current configuration:
-- See all configured models (default, background, think, longContext, webSearch, image)
-- Switch models: Quickly change which model is used for each router type
-- Add new models: Add models to existing providers
-- Create new providers: Set up complete provider configurations including:
-   - Provider name and API endpoint
-   - API key
-   - Available models
-   - Transformer configuration with support for:
-     - Multiple transformers (openrouter, deepseek, gemini, etc.)
-     - Transformer options (e.g., maxtoken with custom limits)
-     - Provider-specific routing (e.g., OpenRouter provider preferences)
-
-The CLI tool validates all inputs and provides helpful prompts to guide you through the configuration process, making it easy to manage complex setups without editing JSON files manually.
-
-### 6. Activate Command (Environment Variables Setup)
-
-The `activate` command allows you to set up environment variables globally in your shell, enabling you to use the `claude` command directly or integrate Claude Code Router with applications built using the Agent SDK.
-
-To activate the environment variables, run:
-
-```shell
-eval "$(ccr activate)"
-```
-
-This command outputs the necessary environment variables in shell-friendly format, which are then set in your current shell session. After activation, you can:
-
-- **Use `claude` command directly**: Run `claude` commands without needing to use `ccr code`. The `claude` command will automatically route requests through Claude Code Router.
-- **Integrate with Agent SDK applications**: Applications built with the Anthropic Agent SDK will automatically use the configured router and models.
-
-The `activate` command sets the following environment variables:
-
-- `ANTHROPIC_AUTH_TOKEN`: API key from your configuration
-- `ANTHROPIC_BASE_URL`: The local router endpoint (default: `http://127.0.0.1:3456`)
-- `NO_PROXY`: Set to `127.0.0.1` to prevent proxy interference
-- `DISABLE_TELEMETRY`: Disables telemetry
-- `DISABLE_COST_WARNINGS`: Disables cost warnings
-- `API_TIMEOUT_MS`: API timeout from your configuration
-
-> **Note**: Make sure the Claude Code Router service is running (`ccr start`) before using the activated environment variables. The environment variables are only valid for the current shell session. To make them persistent, you can add `eval "$(ccr activate)"` to your shell configuration file (e.g., `~/.zshrc` or `~/.bashrc`).
-
-#### Providers
-
-The `Providers` array is where you define the different model providers you want to use. Each provider object requires:
-
-- `name`: A unique name for the provider.
-- `api_base_url`: The full API endpoint for chat completions.
-- `api_key`: Your API key for the provider.
-- `models`: A list of model names available from this provider.
-- `transformer` (optional): Specifies transformers to process requests and responses.
-
-#### Transformers
-
-Transformers allow you to modify the request and response payloads to ensure compatibility with different provider APIs.
-
-- **Global Transformer**: Apply a transformer to all models from a provider. In this example, the `openrouter` transformer is applied to all models under the `openrouter` provider.
-  ```json
-  {
-    "name": "openrouter",
-    "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
-    "api_key": "sk-xxx",
-    "models": [
-      "google/gemini-2.5-pro-preview",
-      "anthropic/claude-sonnet-4",
-      "anthropic/claude-3.5-sonnet"
-    ],
-    "transformer": { "use": ["openrouter"] }
-  }
-  ```
-- **Model-Specific Transformer**: Apply a transformer to a specific model. In this example, the `deepseek` transformer is applied to all models, and an additional `tooluse` transformer is applied only to the `deepseek-chat` model.
-
-  ```json
-  {
-    "name": "deepseek",
-    "api_base_url": "https://api.deepseek.com/chat/completions",
-    "api_key": "sk-xxx",
-    "models": ["deepseek-chat", "deepseek-reasoner"],
-    "transformer": {
-      "use": ["deepseek"],
-      "deepseek-chat": { "use": ["tooluse"] }
-    }
-  }
-  ```
-
-- **Passing Options to a Transformer**: Some transformers, like `maxtoken`, accept options. To pass options, use a nested array where the first element is the transformer name and the second is an options object.
-  ```json
-  {
-    "name": "siliconflow",
-    "api_base_url": "https://api.siliconflow.cn/v1/chat/completions",
-    "api_key": "sk-xxx",
-    "models": ["moonshotai/Kimi-K2-Instruct"],
-    "transformer": {
-      "use": [
-        [
-          "maxtoken",
-          {
-            "max_tokens": 16384
-          }
-        ]
-      ]
-    }
-  }
-  ```
-
-**Available Built-in Transformers:**
-
-- `Anthropic`:If you use only the `Anthropic` transformer, it will preserve the original request and response parameters(you can use it to connect directly to an Anthropic endpoint).
-- `deepseek`: Adapts requests/responses for DeepSeek API.
-- `gemini`: Adapts requests/responses for Gemini API.
-- `openrouter`: Adapts requests/responses for OpenRouter API. It can also accept a `provider` routing parameter to specify which underlying providers OpenRouter should use. For more details, refer to the [OpenRouter documentation](https://openrouter.ai/docs/features/provider-routing). See an example below:
-  ```json
-    "transformer": {
-      "use": ["openrouter"],
-      "moonshotai/kimi-k2": {
-        "use": [
-          [
-            "openrouter",
-            {
-              "provider": {
-                "only": ["moonshotai/fp8"]
-              }
-            }
-          ]
-        ]
-      }
-    }
-  ```
-- `groq`: Adapts requests/responses for groq API.
-- `maxtoken`: Sets a specific `max_tokens` value.
-- `tooluse`: Optimizes tool usage for certain models via `tool_choice`.
-- `gemini-cli` (experimental): Unofficial support for Gemini via Gemini CLI [gemini-cli.js](https://gist.github.com/musistudio/1c13a65f35916a7ab690649d3df8d1cd).
-- `reasoning`: Used to process the `reasoning_content` field.
-- `sampling`: Used to process sampling information fields such as `temperature`, `top_p`, `top_k`, and `repetition_penalty`.
-- `enhancetool`: Adds a layer of error tolerance to the tool call parameters returned by the LLM (this will cause the tool call information to no longer be streamed).
-- `cleancache`: Clears the `cache_control` field from requests.
-- `vertex-gemini`: Handles the Gemini API using Vertex authentication.
-- `chutes-glm` Unofficial support for GLM 4.5 model via Chutes [chutes-glm-transformer.js](https://gist.github.com/vitobotta/2be3f33722e05e8d4f9d2b0138b8c863).
-- `qwen-cli` (experimental): Unofficial support for qwen3-coder-plus model via Qwen CLI [qwen-cli.js](https://gist.github.com/musistudio/f5a67841ced39912fd99e42200d5ca8b).
-- `rovo-cli` (experimental): Unofficial support for gpt-5 via Atlassian Rovo Dev CLI [rovo-cli.js](https://gist.github.com/SaseQ/c2a20a38b11276537ec5332d1f7a5e53).
-
-**Custom Transformers:**
-
-You can also create your own transformers and load them via the `transformers` field in `config.json`.
-
-```json
-{
-  "transformers": [
-    {
-      "path": "/User/xxx/.claude-code-router/plugins/gemini-cli.js",
-      "options": {
-        "project": "xxx"
-      }
-    }
-  ]
-}
-```
-
-#### Router
-
-The `Router` object defines which model to use for different scenarios:
-
-- `default`: The default model for general tasks.
-- `background`: A model for background tasks. This can be a smaller, local model to save costs.
-- `think`: A model for reasoning-heavy tasks, like Plan Mode.
-- `longContext`: A model for handling long contexts (e.g., > 60K tokens).
-- `longContextThreshold` (optional): The token count threshold for triggering the long context model. Defaults to 60000 if not specified.
-- `webSearch`: Used for handling web search tasks and this requires the model itself to support the feature. If you're using openrouter, you need to add the `:online` suffix after the model name.
-- `image` (beta): Used for handling image-related tasks (supported by CCR’s built-in agent). If the model does not support tool calling, you need to set the `config.forceUseImageAgent` property to `true`.
-
-- You can also switch models dynamically in Claude Code with the `/model` command:
-`/model provider_name,model_name`
-Example: `/model openrouter,anthropic/claude-3.5-sonnet`
-
-#### Custom Router
-
-For more advanced routing logic, you can specify a custom router script via the `CUSTOM_ROUTER_PATH` in your `config.json`. This allows you to implement complex routing rules beyond the default scenarios.
-
-In your `config.json`:
-
-```json
-{
-  "CUSTOM_ROUTER_PATH": "/User/xxx/.claude-code-router/custom-router.js"
-}
-```
-
-The custom router file must be a JavaScript module that exports an `async` function. This function receives the request object and the config object as arguments and should return the provider and model name as a string (e.g., `"provider_name,model_name"`), or `null` to fall back to the default router.
-
-Here is an example of a `custom-router.js` based on `custom-router.example.js`:
-
-```javascript
-// /User/xxx/.claude-code-router/custom-router.js
-
-/**
- * A custom router function to determine which model to use based on the request.
- *
- * @param {object} req - The request object from Claude Code, containing the request body.
- * @param {object} config - The application's config object.
- * @returns {Promise<string|null>} - A promise that resolves to the "provider,model_name" string, or null to use the default router.
- */
-module.exports = async function router(req, config) {
-  const userMessage = req.body.messages.find((m) => m.role === "user")?.content;
-
-  if (userMessage && userMessage.includes("explain this code")) {
-    // Use a powerful model for code explanation
-    return "openrouter,anthropic/claude-3.5-sonnet";
-  }
-
-  // Fallback to the default router configuration
-  return null;
-};
-```
-
-##### Subagent Routing
-
-For routing within subagents, you must specify a particular provider and model by including `<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>` at the **beginning** of the subagent's prompt. This allows you to direct specific subagent tasks to designated models.
-
-**Example:**
-
-```
-<CCR-SUBAGENT-MODEL>openrouter,anthropic/claude-3.5-sonnet</CCR-SUBAGENT-MODEL>
-Please help me analyze this code snippet for potential optimizations...
-```
-
-## Status Line (Beta)
-To better monitor the status of claude-code-router at runtime, version v1.0.40 includes a built-in statusline tool, which you can enable in the UI.
-![statusline-config.png](/blog/images/statusline-config.png)
-
-The effect is as follows:
-![statusline](/blog/images/statusline.png)
-
-## 🤖 GitHub Actions
-
-Integrate Claude Code Router into your CI/CD pipeline. After setting up [Claude Code Actions](https://docs.anthropic.com/en/docs/claude-code/github-actions), modify your `.github/workflows/claude.yaml` to use the router:
-
-```yaml
-name: Claude Code
-
-on:
-  issue_comment:
-    types: [created]
-  # ... other triggers
-
-jobs:
-  claude:
-    if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      # ... other conditions
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Prepare Environment
-        run: |
-          curl -fsSL https://bun.sh/install | bash
-          mkdir -p $HOME/.claude-code-router
-          cat << 'EOF' > $HOME/.claude-code-router/config.json
-          {
-            "log": true,
-            "NON_INTERACTIVE_MODE": true,
-            "OPENAI_API_KEY": "${{ secrets.OPENAI_API_KEY }}",
-            "OPENAI_BASE_URL": "https://api.deepseek.com",
-            "OPENAI_MODEL": "deepseek-chat"
-          }
-          EOF
-        shell: bash
-
-      - name: Start Claude Code Router
-        run: |
-          nohup ~/.bun/bin/bunx @musistudio/claude-code-router@1.0.8 start &
-        shell: bash
-
-      - name: Run Claude Code
-        id: claude
-        uses: anthropics/claude-code-action@beta
-        env:
-          ANTHROPIC_BASE_URL: http://localhost:3456
-        with:
-          anthropic_api_key: "any-string-is-ok"
-```
-
-> **Note**: When running in GitHub Actions or other automation environments, make sure to set `"NON_INTERACTIVE_MODE": true` in your configuration to prevent the process from hanging due to stdin handling issues.
-
-This setup allows for interesting automations, like running tasks during off-peak hours to reduce API costs.
-
-## 📝 Further Reading
-
-- [Project Motivation and How It Works](blog/en/project-motivation-and-how-it-works.md)
-- [Maybe We Can Do More with the Router](blog/en/maybe-we-can-do-more-with-the-route.md)
-- [GLM-4.6 Supports Reasoning and Interleaved Thinking](blog/en/glm-4.6-supports-reasoning.md)
-
-## ❤️ Support & Sponsoring
-
-If you find this project helpful, please consider sponsoring its development. Your support is greatly appreciated!
-
-[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F31GN2GM)
-
-[Paypal](https://paypal.me/musistudio1999)
+<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>
+
+<p align="center">
+  <img src="blog/images/claude-code-router.png" width="720" alt="Claude Code Router Desktop screenshot" />
+</p>
+
+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.
+
+## Why Use CCR
+
+- Use one local endpoint for multiple agent tools instead of configuring every client separately.
+- 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.
+
+## Features
+
+- **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.
+- **Fusion models**: combine a base model with vision, web search, or MCP tools into a reusable selectable model.
+
+## Documentation
+
+Read the full documentation at [ccrdesk.top](https://ccrdesk.top/).
+
+## Download And Install
+
+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`
+   - macOS Intel: `Claude-Code-Router_<version>-mac-Intel-x64.dmg` or `.zip`
+   - Windows: `Claude Code Router_<version>.exe`
+   - Linux: `Claude Code Router_<version>.AppImage`
+3. Install and launch **Claude Code Router**.
+4. On first launch, CCR creates its local configuration database:
+   - macOS/Linux: `~/.claude-code-router/config.sqlite`
+   - Windows: `%APPDATA%\Claude Code Router\config.sqlite`
+
+CCR stores runtime configuration in SQLite. A legacy `config.json` is read only once for migration when no SQLite config exists.
+
+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
+
+CCR can be configured entirely from the desktop UI. Use this setup order for a clean first run.
+
+### 1. Add a 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 conditional rules, configure request rewrites, and set 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**. 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 **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 **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.
+
+## Acknowledgements
+
+Codex support is powered by [musistudio/codexl](https://github.com/musistudio/codexl).
+
+## Support & Sponsoring
+
+<div align="center">
+
+<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!
-
-
-- [AIHubmix](https://aihubmix.com/)
-- [BurnCloud](https://ai.burncloud.com)
-- [302.AI](https://share.302.ai/ZGVF9w)
-- [Z智谱](https://www.bigmodel.cn/claude-code?ic=FPF9IVAGFJ)
-- @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
-- @\*\*东
-- @\*落
-- @哆\*k
-- @\*涛
-- [@苗大](https://github.com/WitMiao)
-- @\*呢
-- @\d*u
-- @crizcraig
-- s\*s
-- \*火
-- \*勤
-- \*\*锟
-- \*涛
-
-
-(If your name is masked, please contact me via my homepage email to update it with your GitHub username.)
+<div align="center">
+
+<p>A huge thank you to all our sponsors for their generous support.</p>
+
+<table width="100%">
+  <tr>
+    <td align="center" width="330">
+      <a href="https://www.bigmodel.cn/claude-code?ic=FPF9IVAGFJ">
+        <img src="/docs/public/provider-icons/zhipu-cn-general.png" width="42" height="42" alt="Zhipu icon" />
+        <br />
+        <strong>Z智谱</strong>
+      </a>
+    </td>
+    <td align="center" width="330">
+      <a href="https://aihubmix.com/">
+        <img src="https://www.google.com/s2/favicons?domain=aihubmix.com&amp;sz=128" width="42" height="42" alt="AIHubmix icon" />
+        <br />
+        <strong>AIHubmix</strong>
+      </a>
+    </td>
+    <td align="center" width="330">
+      <a href="https://ai.burncloud.com">
+        <img src="https://www.burncloud.com/favicon.png" width="42" height="42" alt="BurnCloud icon" />
+        <br />
+        <strong>BurnCloud</strong>
+      </a>
+    </td>
+    <td align="center" width="330">
+      <a href="https://share.302.ai/ZGVF9w">
+        <img src="https://www.google.com/s2/favicons?domain=302.ai&amp;sz=128" width="42" height="42" alt="302.AI icon" />
+        <br />
+        <strong>302.AI</strong>
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="330">
+      <a href="https://runapi.co/register?aff=IX1t">
+        <img src="/docs/public/provider-icons/runapi.jpg" width="42" height="42" alt="RunAPI icon" />
+        <br />
+        <strong>RunAPI</strong>
+      </a>
+    </td>
+    <td align="center" width="330">
+      <a href="https://teamorouter.com/">
+        <img src="/docs/public/provider-icons/teamorouter.png" width="42" height="42" alt="TeamoRouter icon" />
+        <br />
+        <strong>TeamoRouter</strong>
+      </a>
+    </td>
+  </tr>
+</table>
+
+<h4>Community Sponsors</h4>
+
+<table width="100%">
+  <tr>
+    <td align="center" width="220">@Simon Leischnig</td>
+    <td align="center" width="220"><a href="https://github.com/duanshuaimin">@duanshuaimin</a></td>
+    <td align="center" width="220"><a href="https://github.com/vrgitadmin">@vrgitadmin</a></td>
+    <td align="center" width="220">@*o</td>
+    <td align="center" width="220"><a href="https://github.com/ceilwoo">@ceilwoo</a></td>
+    <td align="center" width="220">@*说</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@*更</td>
+    <td align="center" width="220">@K*g</td>
+    <td align="center" width="220">@R*R</td>
+    <td align="center" width="220"><a href="https://github.com/bobleer">@bobleer</a></td>
+    <td align="center" width="220">@*苗</td>
+    <td align="center" width="220">@*划</td>
+  </tr>
+  <tr>
+    <td align="center" width="220"><a href="https://github.com/Clarence-pan">@Clarence-pan</a></td>
+    <td align="center" width="220"><a href="https://github.com/carter003">@carter003</a></td>
+    <td align="center" width="220">@S*r</td>
+    <td align="center" width="220">@*晖</td>
+    <td align="center" width="220">@*敏</td>
+    <td align="center" width="220">@Z*z</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@*然</td>
+    <td align="center" width="220"><a href="https://github.com/cluic">@cluic</a></td>
+    <td align="center" width="220">@*苗</td>
+    <td align="center" width="220"><a href="https://github.com/PromptExpert">@PromptExpert</a></td>
+    <td align="center" width="220">@*应</td>
+    <td align="center" width="220"><a href="https://github.com/yusnake">@yusnake</a></td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@*飞</td>
+    <td align="center" width="220">@董*</td>
+    <td align="center" width="220">@*汀</td>
+    <td align="center" width="220">@*涯</td>
+    <td align="center" width="220">@*:-）</td>
+    <td align="center" width="220">@**磊</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@*琢</td>
+    <td align="center" width="220">@*成</td>
+    <td align="center" width="220">@Z*o</td>
+    <td align="center" width="220">@*琨</td>
+    <td align="center" width="220"><a href="https://github.com/congzhangzh">@congzhangzh</a></td>
+    <td align="center" width="220">@*_</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@Z*m</td>
+    <td align="center" width="220">@*鑫</td>
+    <td align="center" width="220">@c*y</td>
+    <td align="center" width="220">@*昕</td>
+    <td align="center" width="220"><a href="https://github.com/witsice">@witsice</a></td>
+    <td align="center" width="220">@b*g</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@*亿</td>
+    <td align="center" width="220">@*辉</td>
+    <td align="center" width="220">@JACK</td>
+    <td align="center" width="220">@*光</td>
+    <td align="center" width="220">@W*l</td>
+    <td align="center" width="220"><a href="https://github.com/kesku">@kesku</a></td>
+  </tr>
+  <tr>
+    <td align="center" width="220"><a href="https://github.com/biguncle">@biguncle</a></td>
+    <td align="center" width="220">@二吉吉</td>
+    <td align="center" width="220">@a*g</td>
+    <td align="center" width="220">@*林</td>
+    <td align="center" width="220">@*咸</td>
+    <td align="center" width="220">@*明</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@S*y</td>
+    <td align="center" width="220">@f*o</td>
+    <td align="center" width="220">@*智</td>
+    <td align="center" width="220">@F*t</td>
+    <td align="center" width="220">@r*c</td>
+    <td align="center" width="220"><a href="https://github.com/qierkang">@qierkang</a></td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@*军</td>
+    <td align="center" width="220"><a href="https://github.com/snrise-z">@snrise-z</a></td>
+    <td align="center" width="220">@*王</td>
+    <td align="center" width="220"><a href="https://github.com/greatheart1000">@greatheart1000</a></td>
+    <td align="center" width="220">@*王</td>
+    <td align="center" width="220">@zcutlip</td>
+  </tr>
+  <tr>
+    <td align="center" width="220"><a href="https://github.com/Peng-YM">@Peng-YM</a></td>
+    <td align="center" width="220">@*更</td>
+    <td align="center" width="220">@*.</td>
+    <td align="center" width="220">@F*t</td>
+    <td align="center" width="220">@*政</td>
+    <td align="center" width="220">@*铭</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@*叶</td>
+    <td align="center" width="220">@七*o</td>
+    <td align="center" width="220">@*青</td>
+    <td align="center" width="220">@**晨</td>
+    <td align="center" width="220">@*远</td>
+    <td align="center" width="220">@*霄</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@**吉</td>
+    <td align="center" width="220">@**飞</td>
+    <td align="center" width="220">@**驰</td>
+    <td align="center" width="220">@x*g</td>
+    <td align="center" width="220">@**东</td>
+    <td align="center" width="220">@*落</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">@哆*k</td>
+    <td align="center" width="220">@*涛</td>
+    <td align="center" width="220"><a href="https://github.com/WitMiao">@苗大</a></td>
+    <td align="center" width="220">@*呢</td>
+    <td align="center" width="220">@d*u</td>
+    <td align="center" width="220">@crizcraig</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">s*s</td>
+    <td align="center" width="220">*火</td>
+    <td align="center" width="220">*勤</td>
+    <td align="center" width="220">**锟</td>
+    <td align="center" width="220">*涛</td>
+    <td align="center" width="220">**明</td>
+  </tr>
+  <tr>
+    <td align="center" width="220">*知</td>
+    <td align="center" width="220">*语</td>
+    <td align="center" width="220">*瓜</td>
+    <td align="center" width="220"></td>
+    <td align="center" width="220"></td>
+    <td align="center" width="220"></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
+
+This project is licensed under the [MIT License](LICENSE).