Claude Code RouterCCR实战指南为多 Agent 与多 Provider 构建本地模型网关和控制面【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-routerClaude Code Router简称 CCR是当前仓库提供的一款本地模型网关model gateway与控制面control plane它让 Claude Code、Claude Design、Codex、Grok CLI、Kimi CLI、Kilo Code、OpenCode、Pi、ZCode、WorkBuddy 以及兼容 API 客户端共用一个稳定的本地端点而后端的 Provider、模型、账号、路由规则与工具则统一在同一个地方管理。读完本文你将掌握 CCR 的三种安装运行方式桌面应用 / npm CLI / Docker、从“接入 Provider → 启动网关 → 配置 Agent Profile → 查看日志 → 配置路由”的完整上手链路以及其网关端口、服务化命令与路由机制背后的源码级实现原理。为什么需要 CCR从“每客户端一份配置”到“一处统一管控”日常使用编码 Agent 时每个 Agent 客户端往往各自维护一份模型/Key 配置切换模型要反复编辑各自的配置文件某家 Provider 欠费或限流时请求直接中断想要观察“刚才那次请求到底走了谁”更是困难。CCR 的思路是引入一个位于本地的中间控制面把上述问题统一收口。官方 READMEREADME.md给出的典型用途包括统一管理所有 Agent 与 Provider不必再为每个客户端单独维护模型配置不改变工作流即可切换 Provider / 模型无需反复编辑 Agent 配置文件让请求持续可用通过重试retries、凭据池credential pools、密钥轮换key rotation与有序回退模型ordered fallback models保证请求不中断给已有模型叠加能力通过 Fusion视觉、联网搜索、MCP 工具与 ToolHub 扩展模型能力边界看清真实发生的每一笔请求请求日志、路由命中结果、延迟、Token 用量、费用估算与账号状态一目了然。项目自我定位与仓库描述一致One local control plane for every AI agent——路由模型、融合新能力、编排工具同时保持对整个过程的可控可观测。架构速览Agent → CCR :3456 → 选中的 ProviderREADME 用一段 ASCII 架构图给出了最核心的运行链路这里完整保留Claude Code · Claude Design · Codex · Grok CLI · Kimi CLI · Kilo Code · OpenCode · Pi · ZCode · WorkBuddy · Compatible API clients │ ▼ Claude Code Router :3456 Profiles · Routing · Credentials · Tools · Logs │ ▼ Selected provider, model, and account解读这张图上层是一批编码 Agent 客户端它们都指向 CCR 暴露的本地网关地址127.0.0.1:3456网关内部按 ProfilesAgent 配置、Routing路由规则、Credentials凭据、Tools工具、Logs日志完成一次请求的裁决最终把流量转发到命中规则所选的 Provider、模型与账号。从源码看3456并非写死在客户端而是 CCR 默认配置的一部分。packages/core/src/config/default-config.ts 中createDefaultAppConfig()默认HOST: 127.0.0.1、PORT: 3456并在gateway对象中显式声明了内部网关host/port: 3456与一个独立的核心管理端口corePort: 3457同时默认给出Router.fallbackmode: off、空models、retryCount: 1与Router.builtInRulesclaude-code、codex默认启用等路由骨架。也就是说“模型网关 :3456 服务管理面”的二元结构直接体现在默认配置对象里。负责真正对外提供 HTTP 服务的是 packages/core/src/web/management-server.ts 与进程入口 packages/core/src/entrypoints/server.ts后者会解析--host / --port / --gateway / --no-gateway然后启动“管理 Web 服务 可选模型网关”的组合。仓库中还提供了针对网关架构的契约测试例如 packages/core/test/architecture/gateway-service-architecture.test.mjs用于约束各层间的依赖方向。支持的 AgentCCR 面向的客户端不仅限于 Claude Code官方 README 列出的受支持 Agent 按“CLI 还是 App”分为两组AgentCLI / APPClaude CodeCLI APPCodexCLI APPGrok CLICLIKimi CLICLIKilo CodeCLIOpenCodeCLI APPPiCLIZCodeAPPClaude DesignAPPWorkBuddyAPP对应 Agent 图标的资源位于 packages/ui/src/assets/agent-logos/claude-code.png、codex.png、grok.ico、kilo.svg、opencode.ico、pi.svg、zcode.png、workbuddy.png 等。在代码侧packages/cli/src/cli.ts 中对部分 App 型 Agent 有明确的行为约束例如ZCode profiles can only open the app、Claude Design profiles can only be opened from CCR Desktop、Claude App profile 不支持传入 Agent 参数这些约束同样值得在配置前了解。支持的协议与 ProviderCCR 网关侧兼容的协议与上游 API 形态包括OpenAI Chat / Responses、Anthropic Messages、Gemini Generate Content / Interactions并内置了 OpenRouter、DeepSeek、SiliconFlow、Moonshot、Kimi Code、Mistral、Z.AI、Bailian 以及自定义兼容 Provider 的预设。这些预设以目录形式沉淀在 packages/core/src/providers/presets/ 下如 anthropic、openai、gemini、openrouter、deepseek、mistral、moonshot、siliconflow、kimi-coding、zai-global-coding、zai-global-general、zhipu-cn-coding、zhipu-cn-general、bailian、nvidia、minimax 等每个预设目录内是一个 Provider 定义文件。也就是说“README 声称支持”与“仓库内有开箱即用预设”是可以互相印证的。快速开始桌面应用、CLI 与 Docker官方推荐三种运行形态按使用场景选择即可。三者背后是同一套核心先配置 Provider再启动网关然后应用 Agent Profile。方式一桌面应用推荐从 Releases 下载对应平台安装包并启动macOSApple Silicon 与 Intel 分别提供 dmg、WindowsNSIS 安装器、LinuxAppImage。桌面端工程位于 packages/electron/主进程入口为 packages/electron/src/main/main.ts。打开Providers → Add Provider选择内置预设或填写自定义端点输入 API Key选定协议与模型保存。打开Server并点击Start本地模型网关默认监听http://127.0.0.1:3456。打开Agent Config选择 Claude Code、Claude Design、Codex、Grok CLI、Kimi CLI、Kilo Code、OpenCode、Pi、ZCode 或 WorkBuddy选定模型并应用 Profile。开始使用你的 Agent。打开Logs确认命中的 Provider、模型、状态、Token、延迟与错误。完成以上步骤后 Agent 即已连接到 CCR。若要叠加条件路由、重试、请求改写或回退模型再到Routing中进行配置。方式二npm CLI无 Electron 的轻量运行CLI 需要Node.js 22 或更高版本。它启动同一套网关与一个基于浏览器的管理界面npm install -g musistudio/claude-code-router ccr ui然后打开http://127.0.0.1:3458沿用上面Providers → Server → Agent Profiles的流程即可。注意无论管理界面在哪里模型网关始终保持在http://127.0.0.1:3456。除ccr ui外CLI 还提供以下服务类命令用法可见 packages/cli/src/cli.ts 中printStartHelp/printUiHelp/printWebHelp/printStopHelp生成的帮助文本并有一份集成测试 packages/cli/test/integration/cli-help.test.mjs 对其输出做回归校验命令说明ccr start [--host h] [--port p] [--open\|--no-open] [--gateway\|--no-gateway]以后台服务方式启动 CCR并可选打开管理页ccr ui [同 start 选项]需要时先拉起后台服务再在默认浏览器打开管理界面默认--openccr serve别名ccr web前台运行模式ccr serve --no-open常用作无界面启动ccr stop停止由ccr start拉起的后台服务ccr profile-name-or-id [cli\|app] [-- agent args]直接用某个 Profile 启动对应 Agent--之后的部分原样传给 Agent常用选项与默认值--host host管理服务监听地址默认取环境变量CCR_WEB_HOST否则为127.0.0.1--port port管理服务端口默认取环境变量CCR_WEB_PORT否则为3458--open / --no-open是否在浏览器打开管理页面--gateway / --no-gateway--gateway默认会一并启动配置好的模型网关--no-gateway则只启动管理 Web 服务CCR_WEB_AUTH_TOKEN为管理界面与 RPC 提供认证 token。CLI 直接携带 Profile 的用法示例取自 CLI 帮助文本ccr start ccr ui ccr serve --no-open ccr stop ccr Codex ccr default-codex -- --model gpt-5-codex ccr default-codex app方式三Docker容器化部署仓库根目录提供了 docker-compose.yml 与 Dockerfile一条命令即可拉起docker compose up -d --build默认情况下Docker 形态通过http://127.0.0.1:3458对外暴露管理界面与网关路由。如果要把 CCR 暴露到远程访问请务必先阅读 docker/README.md 与仓库 docs 中 Docker 相关指南再操作默认只绑定回环地址、容器内会自动生成并注入认证 token。从容器实现看docker/entrypoint.sh 会完成三件事按环境变量生成/对齐初始配置写入${HOME}/.claude-code-router/config.json或config.sqlite缺省CCR_DATA_DIR/data用随机base64url生成CCR_WEB_AUTH_TOKEN并把它拼入入口 URL再生成一段 Nginx 配置把/pages/home/index.html管理 UI、/api/ccr/rpc管理 RPC、/health网关健康检查以及~ ^/(v1|v1beta|mcp|messages|chat/completions|responses|interactions)模型 API 路由含 SSE 长连接代理设置分别反代到内部的服务端口。随后 docker/pm2.config.cjs 用 PM2 同时托管ccr-core-server与nginx两个进程。容器相关可调环境变量包括CCR_GATEWAY_HOST / CCR_GATEWAY_PORT默认3456、CCR_GATEWAY_CORE_PORT默认3457、CCR_WEB_HOST / CCR_WEB_PORT、CCR_PUBLIC_PORT默认3458与CCR_NO_GATEWAY等。深入CCR 后台服务命令的源码级实现如果你对ccr start之类命令背后做了什么感兴趣packages/cli/src/cli.ts 给出了完整实现几个值得注意的机制后台进程与状态文件ccr start在拿到启动锁service-start.lock后会以detached方式拉起ccr serve --daemon-child ...并等待子进程把运行状态写入配置目录下的service.json含 pid、URL、profileManaged、服务 token 等文件以0o600权限落盘。身份校验子进程会收到环境变量CCR_SERVICE_INSTANCE_TOKEN后续每次 RPC 都会带管理 token通过/api/ccr/rpc校验serviceTokenMatches是否与 pid 匹配避免误操作别的服务。Profile 直启 Agentccr profile会先加载配置loadAppConfig、校验网关可用模型assertAvailableGatewayModels、必要时自动拉起 Profile 网关带租约机制profile-gateway-leases随后根据 Profile 解析启动平面CLI/App、构造子进程启动计划并注入botGatewayProfileEnv等运行环境最终spawn对应 Agent。Profile 能力含applyProfileConfig等实现在 packages/core/src/profiles/service.ts 与 packages/core/src/profiles/launch-core.ts。六大核心能力详解README 用一张能力表概括了 CCR 的全部能力域这里逐项展开并补充仓库内的对应落点AgentsAgent Profile 与多实例能力覆盖Claude Code、Claude Design、Codex、Grok CLI、Kimi CLI、Kilo Code、OpenCode、Pi、ZCode、WorkBuddy 的 Profile模型覆盖model overrides、作用域scopes、环境设置、CLI 与 App 两种启动入口、多实例工作流。Profile 相关实现集中在 packages/core/src/profiles/含 Profile 网关启动 launch-service.ts、模型允许名单 model-allowlist.ts并配有大量单测例如 packages/core/test/unit/profiles/ 下的profile-launch-core.test.mjs、profile-gateway-probe.test.mjs等。Providers预设、凭据池与探测能力覆盖内置预设与自定义端点协议探测protocol probing模型发现model discovery连通性检查在支持处导入本地登录态单 Key 与凭据池。核心实现位于 packages/core/src/providers/其中 credential-pool.ts 对应“凭据池/密钥轮换”probe.ts 对应协议/连通性探测配套测试见 packages/core/test/unit/providers/ 下的provider-probe.test.mjs、credential-pool.test.mjs、provider-url.test.mjs等。Models Routing路由、重写、重试与回退能力覆盖可检索的模型目录按任务选模型的模型描述作用于请求头/请求体的路由条件前缀匹配请求改写rewrites重试有序回退ordered fallbacks。默认配置中Router.fallback.mode为off、retryCount为1Router.builtInRules默认启用claude-code与codex两条内置规则见 packages/core/src/config/default-config.ts。路由执行引擎位于 packages/core/src/routing/执行计划 execution-plan.ts、失败分类 failure-classifier.ts、策略引擎 policy-engine.ts、模型解析 model-resolution.ts 等并提供集成/单元测试佐证例如 packages/core/test/unit/routing/route-script-runtime.test.mjs。Tools ExtensionsFusion、ToolHub 与插件能力覆盖Fusion 模型ToolHub内置浏览器自动化Chrome 登录态导入wrapper 与 core 网关插件本地路由与虚拟模型。对应源码可在 packages/core/src/gateway/features/如 hosted-web-search、model-discovery、cursor-compat 等网关特性与 packages/core/src/mcp/fusion-* 、toolhub-mcp、media-tools-proxy-mcp、network-capture-mcp 等找到插件体系见 packages/core/src/plugins/ 与 packages/electron/bundled-plugins/。Access QuotasCCR 专用客户端 Key能力覆盖为 CCR 生成独立的客户端 Key支持过期时间以及本地请求数、Token 数、图片数的限额。鉴权实现对应 packages/core/src/gateway/auth/api-key-authorizer.ts并有单元测试 packages/core/test/unit/gateway/api-key-authorizer.test.mjs 覆盖。Observability请求日志与追踪能力覆盖请求与响应详情命中 Provider / 模型 / 凭据状态延迟Token费用估算工具调用Agent trace。实现落在 packages/core/src/observability/request-log-* 、route-trace.ts、raw-trace-sync.ts 等并在默认配置中提供observability.requestLogs、requestLogBodyCapture: all、requestLogSuccessSampleRate等开关packages/core/src/config/default-config.ts。AgentClawIM 中继能力覆盖通过企业微信 iLink、WeCom、Slack、Discord、Telegram、LINE、飞书、钉钉中继 Agent 会话。实现见 packages/core/src/agents/bot-gateway/ 与 docs 文档树 docs/src/content/docs/zh/agentclaw/、docs/src/content/docs/en/agentclaw/同时本仓库各 Agent 分支测试packages/core/test/unit/agents/也覆盖了 bot-gateway 环境与网关部分行为。从源码构建桌面应用在仓库根目录安装 Node.js 22执行npm ci安装依赖即可本地打包目标命令产物macOS 本地 DMG/ZIPnpm run build:app:macrelease-local/Windows 本地 NSIS 安装器npm run build:app:winrelease-local/需要注意Windows 应用打包必须在 Windows x64 上执行因为better-sqlite3携带了原生 Electron 模块对应npm run rebuild:sqlite3这类脚本。Release 流水线在推送v*tag 时会分别在 macOS runner 与windows-latest上构建对应平台产物。构建相关的工程化脚本可在根 package.json 中看到build:app:mac、build:app:win、build:docker、models:update、test:*等。下一步如何在仓库中继续深入想看配置项的完整形状阅读 packages/core/src/config/default-config.ts 与 packages/core/src/contracts/app.ts理解网关、路由、观测、Profile 等默认值的出处想看网关如何把请求送往上游packages/core/src/gateway/upstream/executor.ts 与 retry-policy.ts配合默认的代理目标表见 default-config.ts 中DEFAULT_PROXY_TARGETSAnthropic、OpenAI、Gemini、OpenRouter、DeepSeek、Mistral 的路径清单想看管理与 CLI 的测试样例CLI 帮助集成测试 packages/cli/test/integration/cli-help.test.mjs、Web 管理服务单测 packages/core/test/unit/web/web-management-server.test.mjs想读官方成体系的说明文档仓库 docs 目录本身就是文档站源码Astro中英双语正文在 docs/src/content/docs/zh/ 与 docs/src/content/docs/en/包含 install/launch、Provider 配置、Routing/Configuration、Docker、CLI 指南与 troubleshooting 等章节配套页面组件位于 docs/src/pages/想看项目理念与运作细节作者在 blog/ 下撰写了项目初衷及原理blog/zh/项目初衷及原理.md、Router 中能做更多事情、从 CLI 工具风格看工具渐进式披露等文章中英文版本对应 blog/en/。License本项目基于 MIT License 开源详见根目录 LICENSE。【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
