9router

环境要求

• Node.js 与 npm 环境（用于全局安装 9router）
• 可访问的本地端口 20128（默认服务端口）
• Docker 环境（可选，用于容器化部署）
• 需要一款已安装的 AI 编程工具（如 Claude Code、Codex、Cursor、Cline 等）

安装与启动步骤

1. 1全局安装 9router

   使用 npm 全局安装 9router 命令行工具，安装完成后即可通过 9router 命令启动服务。

   npm install -g 9router

   复制

2. 2启动服务

   直接运行 9router 命令，仪表盘会自动在 http://localhost:20128 打开。

   9router

   复制

3. 3连接免费模型提供商

   在仪表盘中进入 Providers，连接 Kiro AI（每月约 50 额度，含 Claude 4.5 等）或无需认证的 OpenCode Free。

4. 4复制 API Key

   在仪表盘页面复制生成的 API Key，后续配置编程工具时需要使用。

5. 5配置编程工具

   在 Claude Code / Codex / Cursor / Cline 等工具的设置里填入端点、API Key 和模型名，即可开始使用。

6. 6Docker 部署（可选）

   使用官方镜像一键启动，数据挂载到 ~/.9router 持久化。默认端口 20128，容器内 HOSTNAME 为 0.0.0.0。

   docker run -d 
     --name 9router 
     -p 20128:20128 
     -v "$HOME/.9router:/app/data" 
     -e DATA_DIR=/app/data 
     decolua/9router:latest

   复制

7. 7从源码运行（可选）

   仓库包为私有的 9router-app，源码/Docker 方式属于本地开发路径。先复制环境变量文件再安装依赖并以开发模式启动。

   cp .env.example .env
   npm install
   PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

   复制

8. 8生产模式启动（可选）

   构建后以生产模式运行，HOSTNAME 设为 0.0.0.0 以便外部访问。

   npm run build
   PORT=20128 HOSTNAME=0.0.0.0 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run start

   复制

关键配置

如何确认成功

浏览器打开 http://localhost:20128/dashboard 能看到仪表盘即启动成功；接口地址为 http://localhost:20128/v1。

常见问题

注意事项

• 全局安装方式（npm install -g 9router）最简单，源码运行属于本地开发路径，仓库包 9router-app 为私有包。
• Docker 容器中 ${DATA_DIR} 与 ~/.9router 指向同一位置，构建时已创建符号链接 /root/.9router -> /app/data。
• 端口、模型名、API Key 请以仪表盘实际显示为准，模型名仅为 README 示例。
• Headroom 服务不可用或报错时，9Router 会 fail open，直接发送原始请求。