Split configuration docs into main and settings pages

This commit is contained in:
musi 2026-07-07 07:39:02 +08:00
parent 300096e39e
commit 7216b9dcfa
9 changed files with 332 additions and 47 deletions

View file

@ -2,29 +2,37 @@
title: Claude Code Router Detailed Configuration
pageTitle: Detailed Configuration
eyebrow: Detailed Configuration
lead: Configure the overview dashboard, API keys, server, providers, routing, Agent Config, Fusion, Bots, tray, and the config database location in detail.
lead: "Separate main app pages from settings pages while following the app's actual order: main pages cover overview, providers, Agent Config, routing, Fusion, API keys, logs and observability, server, and extensions; settings pages cover ToolHub, Bots, data, and tray."
---
## Page Structure
Detailed configuration docs are split into standalone pages. Every left-sidebar item opens a page; the right outline is reserved for headings inside the current page.
Detailed configuration docs are split into standalone pages. Every left-sidebar item opens a page; the right outline is reserved for headings inside the current page. Main pages follow the app's left navigation order. Settings pages are grouped separately and follow the settings dialog order.
## Main Pages
| Page | Covers |
| --- | --- |
| Overview Dashboard | System status, account balance, usage widgets, layout editing, and share cards |
| API Keys | Client access keys, expiration, and local limits |
| Server | Host, port, proxy mode, system proxy, network capture, and CA certificate |
| Provider Config | Upstream services, protocol, Base URL, model list, and credentials |
| One click import | Provider deeplink protocol, manifest import, one-click import buttons, and security boundaries |
| Routing Config | Default routing, conditional rules, fallback, and request rewrites |
| Logs & Observability | Request logs, Agent execution traces, tool calls, and tool results |
| Fusion Models | Combine a base model with vision, search, or MCP tools into a new selectable model |
| Agent Config | Agent launch method, model, scope, multi-instance launching, and Bot binding |
| Routing Config | Default routing, conditional rules, fallback, and request rewrites |
| Fusion Models | Combine a base model with vision, search, or MCP tools into a new selectable model |
| API Keys | Client access keys, expiration, and local limits |
| Logs & Observability | Request logs, Agent execution traces, tool calls, and tool results |
| Server | Host, port, proxy mode, system proxy, network capture, and CA certificate |
| Extension Mechanism | Wrapper plugins, core gateway plugins, custom extension creation, and debugging |
## Settings Pages
| Page | Covers |
| --- | --- |
| ToolHub | Collapse many MCP servers into one dynamic tool resolution entry point for agents |
| Bots And IM Agent Relay | Bot forwarding, handoff mode, and platform pages |
| Tray Configuration | Tray icon, balance progress, and tray window widgets |
| Config Database Location | SQLite config database location maintained by the desktop app |
| Tray Configuration | Tray icon, balance progress, and tray window widgets |
## Content Relationships
Overview Dashboard shows system status and usage. API Keys control client access to CCR. Server controls the local gateway listener and proxy features. Provider Config and One click import cover how upstream model services enter CCR. Routing determines where model requests go. Agent Config covers Claude Code, Codex, and ZCode launch, multi-instance usage, and model selection. Fusion covers vision, web search, and MCP tools. Extension Mechanism covers local plugin creation, installation, and debugging. Bots cover IM platform relay. Tray Configuration covers the menu bar icon and tray window.
Overview Dashboard shows system status and usage. Provider Config and One click import cover how upstream model services enter CCR. Agent Config covers Claude Code, Codex, and ZCode launch, multi-instance usage, and model selection. Routing determines where model requests go. Fusion covers vision, web search, and MCP tools. API Keys control client access to CCR. Logs & Observability cover request logs and agent execution traces. Server controls the local gateway listener and proxy features. Extension Mechanism covers local plugin creation, installation, and debugging. ToolHub, Bots, Config Database Location, and Tray Configuration match the corresponding settings pages in the settings dialog.

View file

@ -0,0 +1,119 @@
---
title: ToolHub
pageTitle: ToolHub
eyebrow: Detailed Configuration
lead: Collapse many MCP servers into one compact entry point, then let the agent resolve the tools it needs for each task before invoking the real backend tool.
---
## When To Use It
As your MCP setup grows, exposing every tool directly to an agent makes the eager tool list large and easier to misuse. ToolHub exposes one `ccr-toolhub` MCP server with two meta tools:
- `tool_hub.resolve`: searches the available MCP tool catalog for the current task.
- `tool_hub.invoke`: calls a real MCP tool that was selected for this task.
Use ToolHub for internal systems, business APIs, browser automation, orders, accounts, stores, coupons, and other external capabilities. Simple local code, file, or conversation tasks usually do not need ToolHub.
## How It Works
1. Enable ToolHub in **Settings → ToolHub**.
2. Select a configured model as the **Resolver model**. It reads the MCP tool catalog and chooses the tools needed for the task.
3. Add or import backend MCP servers. ToolHub supports `stdio`, `streamable-http`, and `sse`.
4. Open Claude Code or Codex from CCR. CCR writes the `ccr-toolhub` MCP server into that agent config.
5. When the agent receives a request about external services, installed MCP capabilities, or business APIs, it calls `tool_hub.resolve` first, then uses `tool_hub.invoke` to run the selected tools.
ToolHub combines MCP servers configured on the ToolHub page with compatible global Agent MCP servers from older configs, and excludes `ccr-toolhub` itself to avoid recursive calls.
## Options
| Option | Description |
| --- | --- |
| Enable ToolHub | Exposes `ccr-toolhub` to agents. If no backend MCP server is available, CCR does not generate a ToolHub MCP config. |
| Resolver model | Choose from configured provider models. Prefer a stable model that understands tool descriptions well. |
| Max tools | Maximum tools returned by one resolve call. Range `1` to `20`, default `10`. |
| Timeout ms | Overall timeout for ToolHub resolving and invocation. Range `8000` to `300000`, default `60000`. |
| MCP servers | Backend tool sources. Each server needs a unique name plus transport, command or URL, environment variables, headers, and timeouts. |
| Import JSON | Imports common MCP JSON shapes. Supports a root object, array, `mcpServers`, or `mcp_servers`. |
## Add MCP Servers
### stdio
Use `stdio` for local command-line MCP servers. Configure:
- **Command**: launch command, such as `npx`, `node`, or `python`.
- **Arguments**: command arguments.
- **Working directory**: optional working directory.
- **Stdio message mode**: keep `content-length` by default; use `newline-json` for line-delimited JSON servers.
- **Environment variables**: variables needed only by this MCP server.
### streamable-http / sse
Remote MCP servers need a URL. Authentication can use:
- **API key**: stored directly in the config.
- **API key env**: read from an environment variable.
- **Headers**: custom request headers.
If a remote server starts slowly or has long-running calls, adjust that server's **Startup timeout** or **Request timeout**.
## JSON Example
The desktop app's SQLite config is the effective source, so prefer editing through the UI. The fields below are useful for backups, migration, or troubleshooting:
```json
{
"toolHub": {
"enabled": true,
"llm": {
"apiKey": "sk-...",
"baseUrl": "https://api.openai.com/v1",
"model": "gpt-5-mini"
},
"maxTools": 10,
"requestTimeoutMs": 60000,
"mcpServers": [
{
"name": "filesystem",
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"env": {},
"stdioMessageMode": "content-length",
"requestTimeoutMs": 30000,
"startupTimeoutMs": 600000
}
]
}
}
```
The import dialog also accepts common MCP JSON:
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
}
}
```
## ToolHub vs Fusion MCP
| Capability | ToolHub | Fusion Custom MCP Tool |
| --- | --- | --- |
| Entry point | Agent-side `ccr-toolhub` MCP server | Capability inside one Fusion model |
| Tool selection | Dynamically resolves a tool bundle for each task | Fixed tools selected in the model config |
| Best for | Many MCP servers, changing tool catalogs, agent-led capability discovery | Adding a known tool set to one model |
| Visibility | Claude Code or Codex configs opened through CCR | Routes or agents that select that Fusion model |
## Troubleshooting
- Agent cannot see ToolHub: make sure ToolHub is enabled, at least one backend MCP server is configured, and reopen Claude Code or Codex from CCR.
- Missing resolver model or API key: select a configured resolver model and confirm the provider credential works.
- No tools are resolved: confirm the MCP server can list tools, improve tool names and descriptions, or increase **Max tools**.
- Calls time out: check ToolHub **Timeout ms** and the backend server request/startup timeouts.
- Import fails: validate JSON, avoid duplicate server names, make sure `stdio` entries have a command and remote entries have a URL.

View file

@ -2,29 +2,37 @@
title: Claude Code Router 详细配置
pageTitle: 详细配置
eyebrow: 详细配置
lead: 深入配置概览仪表盘、API 密钥、服务、供应商、路由、Agent配置、Fusion、Bot、托盘和配置数据库位置。这里是按功能查字段和扩展能力的地方
lead: 按应用中的实际顺序将主页页面和设置页分开说明主页覆盖概览、供应商、Agent配置、路由、Fusion、API 密钥、日志&观测、服务和扩展;设置页覆盖 ToolHub、Bot、数据和托盘
---
## 页面结构
详细配置文档已经拆成独立页面。左侧目录中的每一项都会进入一个页面;当前页面内的标题由右侧大纲负责。
详细配置文档已经拆成独立页面。左侧目录中的每一项都会进入一个页面;当前页面内的标题由右侧大纲负责。主页页面跟随应用左侧主导航顺序;设置页单独分组,并按设置弹窗顺序排列。
## 主页页面
| 页面 | 内容 |
| --- | --- |
| 概览仪表盘 | 系统状态、账户余额、用量组件、布局编辑和分享卡片 |
| API 密钥 | 客户端访问 Key、过期时间和本地限额 |
| 服务配置 | Host、Port、代理模式、系统代理、网络捕获和 CA 证书 |
| 供应商配置 | 上游服务、协议、基础 URL、模型列表和凭据 |
| 一键导入供应商 | Provider deeplink 协议、Manifest 导入、一键导入按钮和安全边界 |
| 路由配置 | 条件规则、fallback 和请求改写 |
| 日志&观测 | 请求日志、Agent 执行追踪、工具调用和工具结果 |
| Fusion 组合模型 | 把基础模型与视觉、搜索、MCP 工具组合成新的可选模型 |
| Agent配置 | Agent 启动方式、模型、作用范围、多开和 Bot 绑定 |
| 路由配置 | 条件规则、fallback 和请求改写 |
| Fusion 组合模型 | 把基础模型与视觉、搜索、MCP 工具组合成新的可选模型 |
| API 密钥 | 客户端访问 Key、过期时间和本地限额 |
| 日志&观测 | 请求日志、Agent 执行追踪、工具调用和工具结果 |
| 服务配置 | Host、Port、代理模式、系统代理、网络捕获和 CA 证书 |
| 扩展机制 | Wrapper plugin、Core gateway plugin、自定义扩展创建和调试 |
## 设置页
| 页面 | 内容 |
| --- | --- |
| ToolHub | 将多个 MCP server 收束成一个 Agent 可用的动态工具检索入口 |
| Bot 与 IM 接力 Agent | Bot 转发、接力模式和平台页面 |
| 托盘配置 | 托盘图标、余额进度条和托盘窗口组件 |
| 配置数据库位置 | 桌面 App 维护的 SQLite 配置数据库位置 |
| 托盘配置 | 托盘图标、余额进度条和托盘窗口组件 |
## 内容关系
概览仪表盘用于查看系统状态和用量;API 密钥控制客户端访问 CCR服务配置控制本地网关监听和代理能力供应商配置和一键导入供应商页面覆盖上游模型服务如何进入 CCR路由决定模型请求的上游去向;Agent配置页面覆盖 Claude Code、Codex 和 ZCode 的启动、多开与模型选择Fusion 页面覆盖图像、搜索和 MCP 工具;扩展机制页面覆盖本地插件的创建、安装和调试Bot 页面覆盖 IM 平台接力;托盘配置覆盖菜单栏图标和托盘窗口
概览仪表盘用于查看系统状态和用量;供应商配置和一键导入供应商页面覆盖上游模型服务如何进入 CCRAgent配置页面覆盖 Claude Code、Codex 和 ZCode 的启动、多开与模型选择;路由决定模型请求的上游去向;Fusion 页面覆盖图像、搜索和 MCP 工具;API 密钥控制客户端访问 CCR日志&观测覆盖请求日志和 Agent 执行链路服务配置控制本地网关监听和代理能力扩展机制覆盖本地插件的创建、安装和调试。ToolHub、Bot、配置数据库位置和托盘配置对应设置弹窗中的同名配置页

View file

@ -0,0 +1,119 @@
---
title: ToolHub
pageTitle: ToolHub
eyebrow: 详细配置
lead: 将多个 MCP server 收束成一个紧凑入口,让 Agent 先按任务检索需要的工具,再通过 ToolHub 调用真实工具。
---
## 适用场景
当你接入的 MCP server 越来越多时,直接把所有工具暴露给 Agent 会让工具列表变长也更容易选错工具。ToolHub 会向 Agent 暴露一个 `ccr-toolhub` MCP server里面只有两个元工具
- `tool_hub.resolve`:根据用户任务和上下文检索可用 MCP 工具。
- `tool_hub.invoke`:调用已经被本轮任务选中的真实 MCP 工具。
它适合把内部系统、业务 API、浏览器自动化、订单/账户/门店/优惠券等工具统一交给 Agent 使用。简单本地代码、文件或普通聊天任务通常不需要经过 ToolHub。
## 工作方式
1. 在 **设置 → ToolHub** 中启用 ToolHub。
2. 选择一个已配置模型作为 **检索模型**。它负责阅读 MCP 工具目录并挑选本轮任务需要的工具。
3. 添加或导入后端 MCP server。ToolHub 支持 `stdio``streamable-http``sse`
4. 从 CCR 打开 Claude Code 或 Codex。CCR 会在对应 Agent 配置中写入 `ccr-toolhub`
5. Agent 遇到外部服务、已安装 MCP 能力或业务 API 相关请求时,先调用 `tool_hub.resolve`,再用 `tool_hub.invoke` 执行选中的工具。
ToolHub 会合并 **ToolHub 页面配置的 MCP servers** 和兼容旧配置中的全局 Agent MCP servers并自动排除 `ccr-toolhub` 自身,避免递归调用。
## 配置项
| 配置项 | 说明 |
| --- | --- |
| 启用 ToolHub | 开启后才会向 Agent 暴露 `ccr-toolhub`。如果没有可用后端 MCP serverCCR 不会生成 ToolHub MCP 配置。 |
| 检索模型 | 从已配置供应商模型中选择。建议选择响应稳定、工具理解能力好的模型。 |
| 最大工具数 | 单次解析最多返回的工具数量,范围 `1``20`,默认 `10`。 |
| 超时毫秒 | ToolHub 解析和调用的总超时时间,范围 `8000``300000`,默认 `60000`。 |
| MCP servers | 后端工具来源。每个 server 需要唯一名称,并配置 transport、命令或 URL、环境变量、headers 和超时。 |
| Import JSON | 导入常见 MCP JSON。支持根对象、数组、`mcpServers``mcp_servers`。 |
## 添加 MCP Server
### stdio
`stdio` 适合本地命令行 MCP server。需要填写
- **Command**:启动命令,例如 `npx``node``python`
- **Arguments**:命令参数。
- **Working directory**:可选工作目录。
- **Stdio message mode**:默认 `content-length`,如果 server 使用逐行 JSON选择 `newline-json`
- **Environment variables**:只放这个 MCP server 需要的变量。
### streamable-http / sse
远程 MCP server 需要填写 URL。鉴权可以使用
- **API key**:直接保存在配置中。
- **API key env**:从环境变量读取。
- **Headers**:添加自定义请求头。
如果远程服务启动慢或请求耗时长,可以单独调高该 server 的 **Startup timeout****Request timeout**
## JSON 示例
桌面 App 的 SQLite 配置是当前生效来源,建议优先通过 UI 修改。下面字段适用于备份、迁移或排查时理解 ToolHub 配置结构:
```json
{
"toolHub": {
"enabled": true,
"llm": {
"apiKey": "sk-...",
"baseUrl": "https://api.openai.com/v1",
"model": "gpt-5-mini"
},
"maxTools": 10,
"requestTimeoutMs": 60000,
"mcpServers": [
{
"name": "filesystem",
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"env": {},
"stdioMessageMode": "content-length",
"requestTimeoutMs": 30000,
"startupTimeoutMs": 600000
}
]
}
}
```
导入 MCP JSON 时也可以使用常见格式:
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
}
}
```
## 与 Fusion MCP 的区别
| 能力 | ToolHub | Fusion 自定义 MCP 工具 |
| --- | --- | --- |
| 使用入口 | Agent 侧的 `ccr-toolhub` MCP server | 某个 Fusion 模型内部能力 |
| 工具选择 | 每个任务动态检索并返回工具包 | 模型配置中固定选择工具 |
| 适合场景 | MCP server 很多、工具目录经常变化、希望 Agent 自主发现能力 | 给某个模型补一组明确工具 |
| 可见范围 | 通过 CCR 打开的 Claude Code 或 Codex 配置 | 选择该 Fusion 模型的路由或 Agent |
## 排查
- Agent 看不到 ToolHub确认已启用 ToolHub、至少配置了一个后端 MCP server并从 CCR 重新打开 Claude Code 或 Codex。
- 提示缺少检索模型或 API Key**检索模型** 中选择已配置模型,并确认供应商凭据可用。
- 解析不到工具:检查 MCP server 是否能正常列出工具,工具名称和描述是否足够清楚,必要时提高 **最大工具数**
- 调用超时:分别检查 ToolHub 的 **超时毫秒** 和单个 MCP server 的 request/startup timeout。
- 导入失败:检查 JSON 是否有效、server 名称是否重复、`stdio` 是否有 command远程 transport 是否有 URL。

View file

@ -60,25 +60,33 @@ export const docsContent = {
configuration: {
sidebarGroups: [
{
label: "详细配置",
label: "主页页面",
icon: "wand",
items: [
"概览仪表盘",
"供应商配置",
"一键导入供应商",
"路由配置",
"日志&观测",
"Fusion 组合模型",
"Agent配置",
"路由配置",
"Fusion 组合模型",
"API 密钥",
"日志&观测",
"服务配置",
"托盘配置",
"扩展机制",
"Bot 与 IM 接力 Agent",
"配置数据库位置",
],
active: "概览仪表盘",
},
{
label: "设置页",
icon: "book",
items: [
"ToolHub",
"Bot 与 IM 接力 Agent",
"配置数据库位置",
"托盘配置",
],
active: "",
},
],
expandableSidebarItems: ["Fusion 组合模型", "Bot 与 IM 接力 Agent"],
sidebarChildren: {
@ -105,6 +113,7 @@ export const docsContent = {
: "/configuration/fusion-vision/",
: "/configuration/fusion-web-search/",
"自定义 MCP 工具": "/configuration/fusion-mcp-tool/",
ToolHub: "/configuration/toolhub/",
Agent配置: "/configuration/profile/",
"API 密钥": "/configuration/api-keys/",
: "/configuration/server/",
@ -208,25 +217,33 @@ export const docsContent = {
configuration: {
sidebarGroups: [
{
label: "Detailed Configuration",
label: "Main Pages",
icon: "wand",
items: [
"Overview Dashboard",
"Provider Config",
"One click import",
"Routing Config",
"Logs & Observability",
"Fusion Models",
"Agent Config",
"Routing Config",
"Fusion Models",
"API Keys",
"Logs & Observability",
"Server",
"Tray Configuration",
"Extension Mechanism",
"Bots And IM Agent Relay",
"Config Database Location",
],
active: "Overview Dashboard",
},
{
label: "Settings Pages",
icon: "book",
items: [
"ToolHub",
"Bots And IM Agent Relay",
"Config Database Location",
"Tray Configuration",
],
active: "",
},
],
expandableSidebarItems: ["Fusion Models", "Bots And IM Agent Relay"],
sidebarChildren: {
@ -243,6 +260,7 @@ export const docsContent = {
"Built-In Vision": "/en/configuration/fusion-vision/",
"Built-In Web Search": "/en/configuration/fusion-web-search/",
"Custom MCP Tool": "/en/configuration/fusion-mcp-tool/",
ToolHub: "/en/configuration/toolhub/",
"Agent Config": "/en/configuration/profiles/",
"API Keys": "/en/configuration/api-keys/",
Server: "/en/configuration/server/",

View file

@ -291,6 +291,11 @@ const sidebarCloseLabel = locale === "zh" ? "关闭目录" : "Close navigation";
<ul class="sidebar-children directory-children">
{section.groups.map((group) => (
<li class="directory-group">
{(section.groups.length > 1 || group.label !== section.label) && (
<div class="directory-group-label">
<span>{group.label}</span>
</div>
)}
<ul>
{group.items.map((item) => {
const isExpandable = item.children.length > 0;

View file

@ -15,6 +15,7 @@ export function getStaticPaths() {
"fusion-vision": "内置图像能力",
"fusion-web-search": "内置联网搜索",
"fusion-mcp-tool": "自定义 MCP 工具",
toolhub: "ToolHub",
extensions: "扩展机制",
server: "服务配置",
tray: "托盘配置",

View file

@ -15,6 +15,7 @@ export function getStaticPaths() {
"fusion-vision": "Built-In Vision",
"fusion-web-search": "Built-In Web Search",
"fusion-mcp-tool": "Custom MCP Tool",
toolhub: "ToolHub",
extensions: "Extension Mechanism",
server: "Server",
tray: "Tray Configuration",

View file

@ -642,28 +642,26 @@ pre {
}
.directory-group {
margin: 2px 0 9px;
margin: 8px 0 14px;
}
.directory-group:last-child {
margin-bottom: 4px;
}
.directory-group-label {
display: flex;
align-items: center;
gap: 8px;
min-height: 28px;
padding: 7px 8px 3px 0;
color: var(--sidebar-heading);
font-size: 12px;
font-weight: 720;
line-height: 1.35;
.directory-group + .directory-group {
margin-top: 20px;
}
.directory-group-label .group-icon {
width: 14px;
height: 14px;
.directory-group-label {
display: block;
min-height: 20px;
padding: 2px 8px 5px 0;
color: var(--sidebar-subtle);
font-size: 11px;
font-weight: 760;
letter-spacing: 0.04em;
line-height: 1.3;
}
.sidebar-group h2 {
@ -768,7 +766,7 @@ pre {
}
.sidebar-directory .sidebar-children {
padding-left: 24px;
padding-left: 18px;
}
.sidebar-children::before {
@ -786,6 +784,14 @@ pre {
left: 8px;
}
.sidebar-directory .directory-children {
padding-left: 13px;
}
.sidebar-directory .directory-children::before {
display: none;
}
.sidebar-details[open] > .sidebar-children {
margin-bottom: 7px;
}