9Router 使用教程：把 Claude Code、Codex、Cursor 接到同一個 AI 路由器

9Router 是一個面向 AI 編程工具的本地路由器。它把 Claude Code、Codex、Cursor、Cline、Copilot、OpenCode、OpenClaw 等工具統一接到一個 OpenAI-compatible endpoint，再由 9Router 轉發到不同模型和服務商。

它不是另一個聊天客戶端，而是放在 AI 編程工具與模型服務之間，處理 API 格式、provider 切換、工具輸出耗 token、限流中斷、多帳號管理等問題。

根據專案說明，9Router 支援 40+ provider 和 100+ 模型，提供 RTK Token Saver、自動 fallback、額度追蹤、多帳號輪詢、格式轉換與請求日誌。專案使用 JavaScript 編寫，技術棧包括 Node.js、Next.js、React、Tailwind CSS 和 LowDB，授權為 MIT。

適合解決什麼問題

9Router 最適合你同時使用多個 AI 編程工具和多個模型來源的情況。

例如：

Claude Code 使用訂閱帳號。
Codex 或 Cursor 需要自訂 OpenAI endpoint。
Cline、Continue、RooCode 需要 OpenAI-compatible API。
免費 provider 用來日常嘗試。
GLM、MiniMax、Kimi 等便宜 API 作為備用。
高品質模型只在複雜任務時使用。

沒有 9Router 時，這些配置會分散在不同工具裡。9Router 的思路是讓工具都訪問同一個本地地址，再在路由器中配置 provider、combo 和優先級。

預設本地地址：

1

http://localhost:20128/v1

Dashboard：

1

http://localhost:20128/dashboard

快速安裝

本機使用可以直接透過 npm：

1
2


npm install -g 9router
9router

從原始碼執行：

1
2
3
4
5


git clone https://github.com/decolua/9router.git
cd 9router
cp .env.example .env
npm install
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

生產模式：

1
2


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

npm 包要求 Node.js >=18.0.0。部署到 VPS 或 Docker 時，建議配置 JWT_SECRET、INITIAL_PASSWORD、DATA_DIR、API_KEY_SECRET 等環境變數。

接入 AI 編程工具

常見配置如下：

1
2
3


Base URL: http://localhost:20128/v1
API Key: 從 9Router Dashboard 複製
Model: 在 9Router 中配置的模型名或 combo 名

Codex CLI：

1
2
3
4


export OPENAI_BASE_URL="http://localhost:20128"
export OPENAI_API_KEY="your-9router-api-key"

codex "your prompt"

Cline、Continue、RooCode 可選 OpenAI Compatible：

1
2
3


Base URL: http://localhost:20128/v1
API Key: your-9router-api-key
Model: cc/claude-opus-4-7

模型名前綴取決於已連接的 provider，例如 cc/、cx/、gh/、glm/、minimax/、kr/、vertex/。

RTK Token Saver

AI 編程工具最耗 token 的地方常常是工具輸出，例如：

git diff
git status
grep
find
ls
tree
日誌
大段檔案列表

9Router 內建 RTK Token Saver，會在請求送到模型前壓縮這類內容。專案說明稱很多請求可節省 20%-40% input tokens。

這個功能不要求更換模型，也不改變上層工具使用方式。不過遇到關鍵日誌、完整檔案內容或高風險任務時，仍建議先測試壓縮後的回答品質。

自動 fallback

9Router 可以按優先級組合模型：

1
2
3


1. 訂閱模型
2. 便宜 API
3. 免費 provider

當第一層額度用完、限流或出錯時，自動切到下一層。

1
2
3


1. cc/claude-opus-4-7
2. glm/glm-5.1
3. kr/claude-sonnet-4.5

fallback 會影響輸出一致性。大型重構、協議實作、資料庫遷移等任務，最好固定主模型，失敗時再手動切換。

免費 provider 要謹慎

README 提到 Kiro、OpenCode Free、Vertex 等免費路徑，也提醒部分舊免費層已變化或不再推薦。使用前要確認服務條款、區域限制、第三方工具接入政策、封號風險與額度期限。

9Router 管理的是路由，不會改變上游 provider 的規則。

本地與部署建議

個人使用時，最簡單是只監聽 localhost。如果部署到 VPS 或局域網，建議修改預設密碼、設定強 JWT_SECRET、設定 API_KEY_SECRET、不要把 Dashboard 裸露到公網，並對 /v1/* 啟用 Bearer API key。

Docker 示例：

1
2
3
4
5
6
7


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

先在本機跑通 provider、combo、工具接入和日誌，再決定是否遷移到伺服器。

健康檢查不能只看 Dashboard

不要依賴未經文件確認的 /health。先檢查 Web，再檢查帶驗證的相容 API：

1
2
3


curl -fsS http://127.0.0.1:20128/dashboard > /dev/null
curl -fsS http://127.0.0.1:20128/v1/models \
  -H "Authorization: Bearer $NINE_ROUTER_KEY"

第一條失敗時檢查程序、埠、監聽位址或反向代理；只有第二條返回 401/403 時檢查 9Router API Key。最後再送一次最短聊天請求，確認實際 provider 符合 combo 規則。

Docker 使用者也可檢查容器和最新日誌：

1
2


docker ps --filter name=9router
docker logs --tail 100 9router

從日誌判斷上游故障

DATA_DIR 保存 db.json、usage.json 與 log.txt：

1
2


export DATA_DIR="${DATA_DIR:-$HOME/.9router}"
tail -n 100 "$DATA_DIR/log.txt"

401/403：provider 憑證過期、權限不足或 OAuth 授權失效。
429：額度或速率限制，檢查 fallback 是否切到下一層。
5xx、逾時、DNS 或 TLS：較可能是上游或網路路徑問題。
已切換仍失敗：逐一檢查 combo 的每個 provider。

ENABLE_REQUEST_LOGS=true 會增加請求級日誌，也可能寫入敏感資訊。只短暫開啟、限制權限，排錯後關閉。

備份與恢復資料目錄

停止寫入後備份整個目錄：

1
2
3
4


export DATA_DIR="${DATA_DIR:-$HOME/.9router}"
pm2 stop 9router
tar -C "$DATA_DIR" -czf "$HOME/9router-backup-$(date +%Y%m%d-%H%M%S).tgz" .
pm2 start 9router

備份可能包含 provider 憑證和 API Key。恢復時停止服務、把目前目錄移開、解壓到空的 DATA_DIR，驗證後再啟動：

1
2
3
4


python -m json.tool "$DATA_DIR/db.json" > /dev/null
python -m json.tool "$DATA_DIR/usage.json" > /dev/null
pm2 start 9router
tail -n 100 "$DATA_DIR/log.txt"

Docker 應在停止容器時備份映射到 /app/data 的宿主機目錄或 volume，恢復後重新執行 Dashboard、/v1/models 和最短聊天請求驗收。

適合誰用

9Router 適合同時使用多個 AI 編程工具、多個 provider、多個價格層，並希望統一 fallback 策略的重度使用者。如果你只用一個工具和一個模型，它可能反而增加複雜度。

小結

9Router 可以理解為 AI 編程工具的本地閘道。Claude Code、Codex、Cursor、Cline 等工具連到 http://localhost:20128/v1，由它處理模型選擇、格式轉換、token 壓縮、額度追蹤和 fallback。

常見問題

這個專案是什麼？

它是本文介紹的一個 AI 工具專案，重點在於它能做什麼、怎麼使用，以及什麼情況下值得嘗試。

適合誰使用？

主要適合希望把專案接入真實工作流，而不是只閱讀 README 的開發者和 AI 工具使用者。

使用前應該檢查什麼？

先確認安裝方式、支援工具、資料與權限邊界，以及專案是否仍在快速變化。

適合直接用在生產環境嗎？

建議先小範圍測試。確認行為穩定後，再考慮用於敏感或生產任務。