1. 项目概述与核心价值如果你和我一样是个重度依赖AI辅助编程的开发者那你一定对下面这些场景深有体会正沉浸在代码逻辑的构建中Claude突然弹出“配额已用尽”的提示或者为了找到一个性价比高的模型不得不在多个AI服务商的网站和API文档之间反复横跳手动切换配置。每个月花在Claude、Codex等订阅服务上的钱不少但真正高强度编码时还是免不了被限流打断。更别提那些分散在各个角落的免费模型资源了用起来麻烦稳定性也参差不齐。9Router的出现就是为了终结这种混乱和低效。它本质上是一个运行在你本地的、智能的AI模型路由代理。你可以把它想象成一个高度智能的“流量调度中心”。你的所有AI编程工具无论是Cursor、Claude Code还是OpenClaw、Cline都不再直接连接某个特定的AI服务商而是统一连接到9Router。然后由9Router根据你设定的策略——比如“优先用光付费订阅额度超限后自动切换到廉价备份最后用免费模型兜底”——来智能地分配每一个请求。它的核心价值非常明确用最低的成本实现不间断的AI编程体验。对于已经订阅了Claude Pro或Codex的用户它能帮你榨干订阅的每一分价值避免额度浪费对于预算有限的开发者它提供了一套近乎零成本的“免费优先”组合方案而对于追求极致稳定性的团队它通过多层级的故障转移确保了服务的高可用性。接下来我将结合自己深度使用和部署的经验为你拆解它的设计思路、实战配置以及那些官方文档里不会写的避坑技巧。2. 核心架构与智能路由策略解析2.1 三层级智能回退机制成本与稳定的平衡术9Router最核心的“智能”体现在其三层级回退Fallback策略上。这不是简单的故障转移而是一个基于成本、配额和可用性的多目标优化系统。第一层订阅服务Subscription Tier这一层是你的“主力部队”通常是你已经付费的Claude Code、OpenAI Codex、GitHub Copilot等。9Router会实时追踪这些服务的剩余配额如Claude的5小时滚动限额和每周限额。它的策略是优先耗尽这些已付费资源。很多人的订阅费白交了就是因为额度没用完就重置了。9Router的仪表盘会清晰展示每个订阅模型的剩余Token和重置倒计时让你一目了然鼓励你在重置前充分利用。第二层廉价APICheap Tier当订阅额度用尽但任务还不能停时系统会自动切换到成本极低的按量付费API。典型代表是GLM-4.7约$0.6/百万Token和MiniMax M2.1约$0.2/百万Token。这里的“廉价”是相对于直接调用OpenAI或Anthropic的官方API而言的。选择这一层的关键在于重置频率。例如GLM的“码客计划”配额是每日上午10点重置而MiniMax是5小时滚动重置。在配置回退链时可以根据你的使用习惯将重置更频繁的模型放在更靠前的位置以更快地恢复“廉价额度”。第三层免费模型Free Tier这是最后的保障网由iFlow、Qwen、Kiro等提供真正不限量免费调用的服务构成。当廉价API的每日预算可在仪表盘设置用尽或遇到临时故障时请求将落到这一层。虽然这些免费模型的绝对性能可能略逊于顶级付费模型但对于大量的日常代码补全、注释生成、逻辑解释等任务它们完全够用能确保你的编码流程绝不中断。实操心得策略配置的黄金法则不要机械地照搬“订阅→廉价→免费”这个顺序。你应该根据你的实际工作流来定制。例如如果你白天进行高强度的创造性编码需要最强模型晚上只是写写文档或修复简单bug可以配置两个组合Combodaytime-combo:cc/claude-opus-4-6-glm/glm-4.7-if/kimi-k2-thinkingnighttime-combo:gc/gemini-3-flash-preview-if/qwen3-coder-plus然后在不同的IDE配置文件或脚本中切换使用的组合名。这样能在不同场景下都实现成本最优。2.2 统一API网关与协议转换要让五花八门的AI编程工具都能接入9Router扮演了一个协议转换网关的角色。它对外提供标准的OpenAI API兼容接口/v1/chat/completions这意味着任何支持自定义OpenAI端口的工具都能即插即用。当你的工具比如Cursor发送一个OpenAI格式的请求到http://localhost:20128/v1时9Router内部会完成以下关键转换请求路由与组合解析根据请求中指定的模型名称如premium-coding找到对应的模型列表。协议适配将通用的OpenAI API请求格式实时转换为目标供应商的原生API格式。例如发给Claude的请求需要转换成Anthropic的Message格式并添加正确的anthropic-version头发给GLM的请求则需要符合智谱AI的规范。供应商调用与回退按顺序调用组合中的模型API。如果第一个模型返回配额不足、速率限制或网络错误9Router不会把错误直接抛给你而是立即、透明地重试列表中的下一个模型。响应标准化无论底层是哪个供应商返回的响应9Router都会将其重新封装成标准的OpenAI API响应格式再返回给你的工具。因此你的工具完全感知不到背后的复杂切换过程。这种设计带来了巨大的灵活性。你不再需要为每个工具单独配置多个API密钥和端点也不需要修改工具内部的代码。统一管理一处配置全端生效。2.3 多账户负载均衡与配额优化对于拥有多个同一服务商账户的用户例如团队共享的多个Claude Code账号9Router提供了多账户支持与负载均衡功能。你可以在一个供应商如Claude Code下添加多个OAuth账户。9Router支持两种路由模式轮询Round Robin均匀地将请求分发到各个账户能有效平滑单个账户的配额消耗速度避免一个账户被快速打满。优先级Priority设定账户优先级优先使用主账户仅当其配额用尽时才切换到备用账户。这个功能对于小型团队或个人多账号用户来说是个利器。它不仅能作为冗余备份更能通过聚合多个账户的配额实质上为你提供了一个“虚拟”的、额度更大的Claude或Codex服务进一步推迟了向收费API回退的时间点。3. 从零开始详细部署与配置指南3.1 本地开发环境快速上手最快速的体验方式是全局安装。确保你的系统已安装Node.js建议18以上版本。# 1. 全局安装9Router npm install -g 9router # 2. 启动服务 9router执行后默认会在http://localhost:20128启动服务并自动打开浏览器仪表盘。如果自动打开失败手动访问该地址即可。首次登录如果未设置密码默认使用123456。强烈建议在首次登录后立即在仪表盘的设置Settings中修改一个强密码。注意事项端口冲突与防火墙如果端口20128被占用可以通过环境变量PORT指定其他端口例如PORT3000 9router。在Windows上如果遇到防火墙提示需要允许Node.js通过防火墙。在macOS/Linux上通常不会有问题。3.2 生产环境部署Docker推荐对于希望长期运行、或在服务器上部署以便多设备共享的用户Docker是最佳选择。它解决了环境依赖问题便于管理和迁移。首先从GitHub克隆项目并进入目录git clone https://github.com/decolua/9router.git cd 9router关键的步骤是准备环境变量文件。复制示例文件并编辑cp .env.example .env # 使用你喜欢的编辑器如vim、nano编辑 .env 文件以下是.env文件中必须修改的关键配置及其解释# 认证相关生产环境必须修改 JWT_SECRETyour-super-secure-random-string-at-least-32-chars INITIAL_PASSWORDyour-strong-password-here # 服务网络配置 PORT20128 HOSTNAME0.0.0.0 # 允许所有网络接口访问如需仅本地可改为127.0.0.1 NEXT_PUBLIC_BASE_URLhttp://你的服务器IP或域名:20128 # 仪表盘访问地址 # 数据持久化Docker卷映射时容器内路径 DATA_DIR/app/data # 云同步配置如果需要 CLOUD_URLhttps://9router.com # API_KEY_SECRET 和 MACHINE_ID_SALT 可使用默认值或生成新的随机字符串重点解释JWT_SECRET用于签名登录令牌务必使用长且复杂的随机字符串否则有安全风险。NEXT_PUBLIC_BASE_URL这是仪表盘前端用来构建完整URL的地址。如果你通过服务器的IP如http://192.168.1.100:20128或域名访问这里必须对应修改否则OAuth回调会失败。DATA_DIR在Docker内部数据将存储在此路径。我们通过-v参数将主机目录映射到这里实现数据持久化。构建并运行Docker容器# 构建镜像 docker build -t 9router . # 运行容器假设当前就在项目根目录.env文件已配置好 docker run -d \ --name 9router \ -p 20128:20128 \ --env-file ./.env \ -v /path/to/your/9router-data:/app/data \ -v /path/to/your/9router-usage:/root/.9router \ 9router命令参数详解-d后台运行。--name 9router给容器命名便于管理。-p 20128:20128将主机的20128端口映射到容器的20128端口。--env-file ./.env注入我们刚才配置的环境变量文件。-v /path/to/your/9router-data:/app/data这是数据持久化的关键。将主机上的一个目录如/home/user/9router-data挂载到容器的/app/data这样即使容器删除你的供应商配置、组合数据也不会丢失。-v /path/to/your/9router-usage:/root/.9router挂载使用记录和日志的目录。运行后使用docker logs -f 9router查看启动日志确认无报错后即可通过http://你的服务器IP:20128访问仪表盘。3.3 核心供应商连接实战仪表盘启动后左侧导航栏点击“Providers”开始添加供应商。这是发挥9Router威力的第一步。连接免费供应商零成本启动iFlow点击“Connect iFlow”会跳转到iFlow的OAuth授权页面。登录授权后9Router会自动获取并刷新Token。完成后你就能在模型列表里看到if/kimi-k2-thinking、if/glm-4.7等8个免费模型。这是最稳定、模型最全的免费源之一。Gemini CLI点击“Connect Gemini CLI”使用谷歌账号授权。成功后你将获得每月18万次Completion的免费额度每天还有额外1千次模型是gc/gemini-3-flash-preview。对于轻量用户仅此一项可能就够用了。Qwen点击“Connect Qwen”会显示一个设备码。你需要访问它给出的验证网址通常是https://opentools.cn/device输入设备码完成授权。成功后即可使用通义千问的免费代码模型。连接订阅供应商最大化现有投资Claude Code确保你已订阅Claude CodePro或Max。在9Router仪表盘点击连接完成OAuth登录。9Router会自动开始跟踪你的5小时和每周配额。关键点9Router这里获取的是Claude Code的API访问权限而不是网页版Chat的Cookie因此更稳定符合开发者工具的使用规范。OpenAI Codex连接过程类似注意授权回调端口是1455。确保你的Codex订阅是有效的。配置API Key供应商按需付费对于GLM、MiniMax、OpenRouter等需要API Key的供应商点击“Add API Key”选择供应商类型填入你在对应平台申请的API Key即可。安全建议对于这类密钥最好在供应商平台设置用量提醒或预算上限作为双重保障。4. 构建与使用智能组合Combo添加完供应商后就可以构建你的第一个智能组合了。点击左侧“Combos”然后“Create New Combo”。4.1 组合配置策略详解给组合起一个易懂的名字比如my-primary-stack。在模型列表里通过下拉菜单依次添加你想要的模型顺序就是故障转移的优先级。一个兼顾成本、性能和稳定性的经典组合配置如下模型顺序 1. cc/claude-opus-4-6 // 第一优先级付费订阅性能最强 2. glm/glm-4.7 // 第二优先级廉价备份每日重置性价比高 3. if/kimi-k2-thinking // 第三优先级免费兜底无限用量保证不停机配置逻辑日常编码请求首先由Claude Opus处理享受最佳代码生成质量。当Claude的5小时配额用尽仪表盘可实时查看请求会自动无缝切换到GLM-4.7。如果当天GLM的配额也用完了或者GLM服务暂时不可用则会最终落到iFlow的免费Kimi模型上。对你和你的IDE来说整个过程是无感的只是响应速度和质量可能会有细微变化。4.2 在各类开发工具中应用组合配置好组合后你会在组合列表看到它的名字如my-primary-stack。在支持OpenAI API的工具中你需要做两处配置API Base URL指向你的9Router实例通常是http://localhost:20128/v1本地或http://你的服务器IP:20128/v1远程。Model这里不填具体的模型ID而是填写你的组合名称例如my-primary-stack。9Router会识别这是一个组合并按照其内部逻辑进行路由。API Key使用9Router仪表盘“Settings”里生成的通用API Key。这个Key是访问9Router本身的凭证与你后端的各个供应商密钥是分离的更安全。主流工具配置示例Cursor IDE:进入 Settings - Models - Advanced 或 Global Model Settings。OpenAI API Base URL:http://localhost:20128/v1OpenAI API Key:sk_9router_...(从9Router仪表盘复制)Model:my-primary-stack(你的组合名)Claude Code (命令行工具):编辑其配置文件~/.claude/config.json(Linux/macOS) 或%APPDATA%\.claude\config.json(Windows)。{ anthropic_api_base: http://localhost:20128/v1, anthropic_api_key: sk_9router_... // 使用9Router的API Key }在Claude Code中发起对话时在模型选择处输入你的组合名即可。VS Code Continue 插件:在VS Code中安装Continue插件在其配置 (~/.continue/config.json) 中添加模型{ models: [ { title: 9Router Combo, provider: openai, model: my-primary-stack, apiBase: http://localhost:20128/v1, apiKey: sk_9router_... } ] }OpenClaw (跨平台AI助手):这是集成时的一个特例。由于OpenClaw对本地主机localhost的IPv6解析可能存在兼容性问题必须使用127.0.0.1而不是localhost。 在其配置文件~/.openclaw/openclaw.json中配置{ agents: { defaults: { model: { primary: 9router/if/glm-4.7 // 格式为 9router/模型全称 } } }, models: { providers: { 9router: { baseUrl: http://127.0.0.1:20128/v1, // 关键使用127.0.0.1 apiKey: sk_9router, api: openai-completions, models: [ { id: if/glm-4.7, name: glm-4.7 } ] } } } }也可以在OpenClaw的Web仪表盘中直接选择9Router作为模型提供商并配置。5. 高级技巧与成本优化实战5.1 深度解读“成本显示”与真实支出这是新手最容易困惑的地方。9Router仪表盘的“Usage Analytics”里会显示一个“Cost”成本。请务必理解这个数字是估算值不代表9Router向你收费它的计算逻辑是9Router根据你消耗的Token数量按照各供应商公开的官方API价格估算出如果你直接调用这些供应商的API需要花费多少钱。例如你通过9Router使用了iFlow的免费模型处理了100万Token仪表盘可能会显示“成本$0.6”因为GLM-4.7的官方价是$0.6/百万Token。但事实上你使用iFlow是免费的实际支出为$0。这个功能的真正价值在于成本感知让你直观看到自己的AI使用量相当于多少市场价值。方案对比帮你量化“使用9Router的免费/廉价策略”到底为你省了多少钱。优化依据如果你发现某个廉价模型消耗的“估算成本”突然增高可能是时候调整它在组合中的优先级了。真实发生的费用只有两类你向订阅服务商如Anthropic for Claude Code, OpenAI for Codex支付的固定月费。你向按量付费API服务商如智谱AI for GLM, MiniMax充值的费用根据你的调用量扣减。9Router作为一个本地代理没有任何计费系统它只负责路由请求。5.2 多场景组合配置策略根据不同的开发场景配置针对性的组合可以极大提升体验和成本效益。场景一高强度项目开发追求最高质量组合名: project-dev 模型顺序: 1. cc/claude-opus-4-6 // 核心复杂逻辑、架构设计 2. cx/gpt-5.2-codex // 备用顶级模型风格互补 3. glm/glm-4.7 // 日常代码补全、重构 4. if/kimi-k2-thinking // 文档生成、简单查询兜底策略大部分时间由Opus和Codex处理获得最佳输出。当它们配额紧张时GLM-4.7作为优秀的平价替代顶上。免费模型仅用于非关键任务。场景二学习与实验零成本组合名: learning 模型顺序: 1. gc/gemini-3-flash-preview // 优先消耗Google免费额度 2. if/qwen3-coder-plus // 通义千问代码能力扎实 3. if/kimi-k2-thinking // Kimi长上下文优势适合读代码 4. qw/qwen3-coder-flash // 快速响应适合简单问答策略完全利用免费资源。Gemini CLI的18万次/月额度对于学习场景通常足够。多个免费源互为备份确保可用性。场景三团队共享部署稳定与管控在服务器部署9Router供团队使用时配置应更注重稳定性。环境变量务必设置强密码(INITIAL_PASSWORD)和JWT密钥(JWT_SECRET)。启用API密钥认证在.env中设置REQUIRE_API_KEYtrue这样所有对/v1端点的请求都必须携带有效的Bearer Token。可以为每个团队成员在9Router仪表盘生成独立的API Key便于管理和审计。组合策略配置一个稳定的公用组合以免费和廉价模型为主避免因个人滥用导致团队订阅配额过快耗尽。组合名: team-shared 模型顺序: 1. glm/glm-4.7 // 成本可控性能可靠 2. if/kimi-k2-thinking // 免费高可用 3. if/qwen3-coder-plus // 免费风格互补监控定期查看仪表盘的Usage Analytics了解团队整体使用情况。5.3 故障排查与日常维护即使配置得当也可能会遇到问题。以下是常见问题的排查思路问题1所有请求都失败返回“Language model did not provide messages”或超时。检查9Router服务状态首先确认9Router进程是否在运行。本地运行可查看终端日志Docker部署使用docker logs -f 9router。检查网络连接确认你的机器可以访问外网特别是需要连接到的AI供应商API。如果身处特殊网络环境可能需要为9Router配置HTTP代理。在.env文件中设置HTTP_PROXY和HTTPS_PROXY环境变量。检查供应商状态前往仪表盘“Providers”页面查看各个供应商的连接状态。如果有红色感叹号点击“Reconnect”尝试重新授权或更新API Key。问题2特定组合或模型响应慢或频繁回退。查看请求日志在.env中设置ENABLE_REQUEST_LOGStrue然后重启9Router。之后在项目根目录的logs/文件夹下会生成详细的请求和响应日志可以看到每个请求具体路由到了哪个模型以及耗时和响应状态。这是定位性能瓶颈的利器。分析配额前往仪表盘“Usage”页面检查是否是订阅模型的配额已用尽导致请求落到了速度较慢的廉价或免费模型上。调整组合顺序如果某个廉价模型不稳定可以将其在组合中的位置后移或暂时禁用。问题3仪表盘显示的成本估算异常高。确认模型检查你的组合实际使用的是哪个模型。如果一直在用免费的iFlow但仪表盘却按GLM的价格估算这是正常的因为iFlow没有公开报价9Router可能用功能相近的GLM价格做参考。理解估算逻辑记住这只是估算。重点关注Token使用量的趋势而非绝对金额。问题4Docker容器重启后配置丢失。检查数据卷挂载这是最常见的原因。确保docker run命令中的-v参数正确映射到了主机上的持久化目录。使用docker inspect 9router命令查看容器的挂载点信息。备份数据定期备份主机上映射的目录如/path/to/your/9router-data。这个目录下的db.json文件包含了所有配置。日常维护建议定期更新关注项目GitHub仓库获取新版本通常会有新的供应商支持、Bug修复和性能提升。清理日志如果开启了ENABLE_REQUEST_LOGS日志文件会增长很快定期清理或禁用。审查用量每周花几分钟看看Usage Analytics了解自己的使用模式优化组合策略。供应商密钥轮换对于重要的API Key遵循供应商的安全建议定期更新并在9Router中同步更新。6. 安全考量与最佳实践将9Router部署在公网如云服务器以供远程访问时安全至关重要。强制API密钥认证这是最低要求。务必在.env中设置REQUIRE_API_KEYtrue。这样任何向http://你的服务器:20128/v1发起的请求都必须包含有效的Bearer Token从9Router仪表盘获取。使用HTTPS9Router本身不直接提供HTTPS。在生产环境中强烈建议使用Nginx、Caddy等反向代理服务器在9Router前面提供HTTPS终止。这可以加密传输数据防止API密钥被嗅探。一个简单的Nginx配置示例server { listen 443 ssl; server_name ai-router.yourdomain.com; ssl_certificate /path/to/your/cert.pem; ssl_certificate_key /path/to/your/key.pem; location / { proxy_pass http://localhost:20128; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }配置后你的工具中设置的Base URL应改为https://ai-router.yourdomain.com/v1。防火墙限制在云服务器安全组或系统防火墙中只开放必要的端口如HTTPS的443并限制访问来源IP如仅允许你的办公网络IP段。强密码与密钥管理如前所述使用强密码和复杂的JWT_SECRET。不要在代码仓库或公开场合提交你的.env文件。最小权限原则运行9Router的进程或Docker容器应使用非root用户以降低潜在风险。7. 生态整合与未来展望9Router的价值不仅在于其本身的路由能力更在于它建立了一个统一的AI模型接入层。这意味着任何新出现的、支持OpenAI API格式的AI编程工具理论上都可以无缝接入9Router立即获得其背后庞大的多模型、低成本、高可用的算力池。从实际使用来看它极大地降低了个体开发者和中小团队使用先进AI编码助手的门槛和成本。你可以用一套配置在Cursor、VS Code、JetBrains IDE、命令行工具等多种环境中获得一致的、不间断的AI辅助体验。它的开源模式也使得社区可以持续贡献新的供应商适配器。目前已经支持的40多家供应商只是一个开始。随着AI模型市场的进一步分化这种“聚合器”和“优化器”的角色会越来越重要。我个人在深度使用数月后最大的体会是它把我从“管理AI服务”的琐事中解放了出来。我不再需要关心哪个账号还剩多少额度哪个模型今天便宜也不再担心深夜编码时被限流打断思路。它就像是一个不知疲倦的AI资源管家在后台默默地为我安排最优解。虽然初期需要花一些时间理解和配置但一旦跑通带来的效率和成本收益是显而易见的。对于任何认真将AI融入开发工作流的程序员来说9Router都是一个值得投入时间部署和调优的基础设施。