9Router là gì? Cách dùng 9Router với Claude Code

9Router là một proxy AI mã nguồn mở chạy cục bộ (local), đóng vai trò trung gian giữa các công cụ lập trình như Claude Code, Cursor và các nhà cung cấp mô hình ngôn ngữ lớn (LLM). Thay vì kết nối trực tiếp với từng nhà cung cấp (upstream), bạn trỏ các công cụ này về 9Router để nó định tuyến và quản lý tài nguyên phía sau.

Về cơ bản, công cụ này giải quyết bài toán quản lý hạ tầng API. Nó hợp nhất hàng chục API key vào một cổng kết nối duy nhất, tự động chuyển đổi định dạng request và nén token để giảm chi phí. Đối với những người dùng Claude Code thường xuyên bị ngắt quãng do hết hạn mức (quota), 9Router cung cấp cơ chế dự phòng để duy trì luồng công việc liên tục.

Bạn có thể coi 9Router như một "switchboard" kỹ thuật. Nó không tạo ra token miễn phí vô hạn mà giúp bạn khai thác triệt để các gói đăng ký sẵn có, kết hợp với các API giá rẻ hoặc các tầng miễn phí để tối ưu hóa hiệu suất làm việc mà không cần thay đổi cấu hình thủ công mỗi khi gặp lỗi 429 (Rate Limit).

9Router là gì?

Ở góc độ kỹ thuật, 9Router là một gateway thông minh cung cấp endpoint tương thích chuẩn OpenAI tại địa chỉ http://localhost:20128/v1. Nhờ endpoint này, bất kỳ client AI nào hỗ trợ tùy chỉnh base URL đều tích hợp được dễ dàng. Nó hoạt động như một lớp trừu tượng hóa, tách biệt phần mềm lập trình (client) khỏi các nhà cung cấp mô hình (provider).

Vai trò thực dụng nhất của 9Router là xử lý tình trạng phân mảnh tài khoản. Khi bạn sở hữu đồng thời Claude Pro, tài khoản GitHub Copilot và một vài API key dự phòng, việc chuyển đổi giữa chúng khi hết quota là một cực hình về mặt cấu hình. 9Router gom tất cả lại, cho phép bạn thiết lập các quy tắc định tuyến thông minh để hệ thống tự động xử lý các yêu cầu này ở chế độ nền.

Dự án này hoàn toàn mã nguồn mở (giấy phép MIT), được xây dựng trên Next.js và JavaScript, kết nối tới hơn 40 nhà cung cấp và 100+ mô hình. Bạn có thể triển khai nó trên máy tính cá nhân hoặc chạy trong container Docker để đảm bảo tính cô lập. Mọi dữ liệu cấu hình và API key đều được lưu trữ cục bộ trong cơ sở dữ liệu SQLite tại ${DATA_DIR}/db/data.sqlite, giúp bạn kiểm soát hoàn toàn thông tin xác thực mà không phụ thuộc vào bên thứ ba.

Vì chạy local, 9Router không can thiệp vào nội dung phản hồi trừ khi bạn bật tính năng nén hoặc chỉnh sửa prompt hệ thống. Đây là giải pháp hạ tầng thực tế cho những kỹ sư muốn xây dựng một hệ sinh thái AI ổn định, thay vì phụ thuộc vào một nhà cung cấp duy nhất.

9Router hoạt động như thế nào?

Cơ chế vận hành của 9Router tuân theo một luồng yêu cầu nghiêm ngặt: client (Claude Code) gửi yêu cầu đến endpoint cục bộ, logic định tuyến của 9Router kiểm tra quy tắc, chọn nhà cung cấp phù hợp dựa trên thứ tự ưu tiên hoặc quota, thực hiện "phiên dịch" định dạng, rồi gửi đến upstream tương ứng (Anthropic, OpenAI, Gemini...).

Khả năng "phiên dịch" là một tính năng kỹ thuật quan trọng. 9Router có thể nhận một request định dạng OpenAI từ client nhưng lại thực thi nó trên một mô hình Claude hoặc Gemini. Điều này cho phép bạn sử dụng các công cụ chỉ hỗ trợ một loại API nhất định nhưng thực tế lại chạy được trên nhiều mô hình khác nhau mà không cần can thiệp vào mã nguồn của client.

Hệ thống định tuyến của 9Router được thiết kế theo cấu trúc phân tầng 3 lớp (3-tier fallback) để đảm bảo độ tin cậy:

1. Lớp Subscription (Trả phí gói): Ưu tiên các tài khoản như Claude Pro hoặc Cursor để tận dụng tối đa hạn mức đã thanh toán hàng tháng.
2. Lớp Cheap API (Giá rẻ): Chuyển sang các mô hình giá rẻ như GLM-5.1 (khoảng $0.6/1M tokens) hoặc MiniMax ($0.2/1M tokens) khi các gói trả phí cố định hết quota.
3. Lớp Free (Miễn phí): Sử dụng các tầng miễn phí của Kiro AI hoặc OpenCode Free làm lớp bảo vệ cuối cùng để công việc không bị đình trệ.

Logic fallback này được điều khiển bởi các mã trạng thái (status codes) và heuristics. Khi upstream trả về lỗi 429 hoặc 500, 9Router sẽ tự động kích hoạt cooldown cho tài khoản đó và chuyển sang tài khoản hoặc mô hình tiếp theo trong danh sách ưu tiên. Đây là cách hệ thống duy trì trạng thái "zero downtime" trong suốt quá trình lập trình.

Cài đặt 9Router và kết nối nhà cung cấp đầu tiên

Cách nhanh nhất để cài đặt 9Router là thông qua npm. Bạn chỉ cần thực thi lệnh sau để cài đặt toàn cục và khởi chạy:

npm install -g 9router
9router

Đối với môi trường production hoặc nếu bạn muốn giữ hệ thống sạch sẽ, Docker là lựa chọn tối ưu. Biến môi trường DATA_DIR là bắt buộc để cơ sở dữ liệu và các cấu hình API key được bảo toàn sau khi restart container:

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

Sau khi khởi chạy, bạn truy cập dashboard tại http://localhost:20128. Tại đây, bước đầu tiên là kết nối một nhà cung cấp. Tôi khuyên bạn nên bắt đầu với Kiro AI, tầng miễn phí của nó cấp khoảng 50 credits mỗi tháng cho các mô hình như Claude 4.5, GLM-5 và MiniMax. Đây là điểm khởi đầu tốt để bạn kiểm tra luồng kết nối trước khi cấu hình các API trả phí phức tạp hơn. Nếu muốn nhanh hơn nữa, OpenCode Free không cần đăng nhập.

Trong dashboard, hãy sao chép "Local API Key". Đây là credential duy nhất bạn cần dùng để kết nối mọi công cụ coding về 9Router. Hãy xử lý key này như một thông tin bảo mật, vì bất kỳ ai có nó đều có thể sử dụng các tài khoản AI mà bạn đã kết nối trong dashboard.

Kết nối Claude Code với 9Router

Có một chi tiết khiến rất nhiều người cấu hình sai ngay từ bước đầu. Dashboard của 9Router hiển thị endpoint kèm hậu tố /v1 vì đó là địa chỉ dành cho các client tương thích OpenAI. Nhưng Claude Code thì tự nối thêm /v1/messages vào giá trị ANTHROPIC_BASE_URL. Nghĩa là bạn phải khai báo base URL không có /v1 — nếu thêm vào, request sẽ đi tới /v1/v1/messages và trả về lỗi 404.

Cách nhanh nhất để thử là export biến môi trường ngay trong terminal. Cấu hình này chỉ tồn tại trong phiên làm việc hiện tại, rất tiện khi bạn cần debug nhanh:

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="YOUR_9ROUTER_API_KEY"
export ANTHROPIC_MODEL="ten-combo-cua-ban"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"

Đối với cấu hình lâu dài, bạn cần chỉnh sửa tệp ~/.claude/settings.json và đặt CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY thành "1". Nếu thiếu cờ này, Claude Code sẽ không thể nhận diện được các "Combo" hoặc mô hình tùy chỉnh mà bạn đã tạo trong 9Router thông qua lệnh /model. Cờ này yêu cầu Claude Code từ phiên bản 2.1.129 trở lên.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_9ROUTER_API_KEY",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "model": "ten-combo-cua-ban"
}

Một lưu ý về bảo mật: đừng đặt credential này vào tệp .claude/settings.json của repository, vì tệp đó được commit và chia sẻ cho mọi người clone dự án. Hãy giữ nó ở tệp settings cấp người dùng. Sau khi lưu, hãy khởi động lại Claude Code và gõ /status để kiểm tra dòng Anthropic base URL có trỏ đúng về địa chỉ localhost của 9Router hay không.

Tạo combo fallback cho Claude Code

"Combo" là nơi ý tưởng ba tầng ở trên biến thành một cấu hình cụ thể. Nó cho phép bạn xâu chuỗi nhiều mô hình thành một định danh duy nhất. Khi client yêu cầu mô hình combo này, 9Router sẽ thử lần lượt các mô hình trong danh sách theo thứ tự bạn đã sắp xếp.

Một kịch bản fallback thực dụng thường được thiết lập như sau:

1. Ưu tiên 1: Gói Claude đã đăng ký sẵn — chất lượng cao nhất.
2. Fallback 1: GLM-5.1 — chi phí thấp, khoảng $0.6 cho mỗi 1 triệu tokens.
3. Fallback cuối: Kiro AI — tầng miễn phí 50 credits/tháng.

Thiết lập combo này cực kỳ hữu ích khi bạn chạy các tác vụ nặng như refactor toàn bộ repository. Nếu giữa chừng tài khoản trả phí của bạn hết hạn mức, 9Router sẽ tự động đẩy yêu cầu tiếp theo sang GLM-5.1. Bạn sẽ thấy phản hồi chậm hơn một chút nhưng ngữ cảnh làm việc vẫn được giữ nguyên, khỏi phải giải thích lại toàn bộ project cho một công cụ khác.

Tuy nhiên, fallback chỉ nên kích hoạt khi gặp lỗi kỹ thuật (429, 500) hoặc hết hạn ngạch. Một câu trả lời kém chất lượng không phải là lý do để hệ thống tự động fallback, vì điều đó sẽ làm tiêu tốn token vô ích mà không giải quyết được vấn đề logic của prompt. Bạn nên kiểm soát việc này bằng cài đặt "Fallback-eligible errors" trong dashboard.

RTK và Caveman Mode tiết kiệm token ra sao?

Trong lập trình AI, phần lớn token bị tiêu tốn vào context từ các lệnh CLI — output từ tool chiếm tới 30-50% ngân sách prompt. Tính năng RTK Token Saver của 9Router nén lossless (không mất dữ liệu) các nội dung tool_result. Cụ thể, nó xử lý các output cồng kềnh từ git diff, ls, tree, grep và find. Lượng input token có thể giảm 20-40%: một request 47K token nén còn 28K token, giữ nguyên ngữ cảnh và câu trả lời.

Đối với đầu ra, 9Router tích hợp Caveman Mode với 5 mức độ cường độ khác nhau. Chế độ này ép mô hình phản hồi theo phong cách tối giản, lược bỏ các câu từ xã giao rườm rà. Ở mức cường độ cao nhất, nó có thể cắt giảm tới 65% lượng output token. Cắt bớt output không chỉ tiết kiệm tiền mà còn tăng tốc độ phản hồi đáng kể trong môi trường CLI.

Bên cạnh đó, chế độ Ponytail (Lazy Senior Dev) đi theo hướng khác: nó ép AI viết mã theo nguyên tắc YAGNI (You Ain't Gonna Need It). AI sẽ ưu tiên thư viện chuẩn (stdlib) và viết code ngắn nhất có thể để giải quyết vấn đề. Kết hợp RTK (giảm đầu vào) với Caveman/Ponytail (giảm đầu ra) tạo thành một vòng tối ưu chi phí cho những phiên làm việc cường độ cao. Nếu bạn muốn giữ nguyên output cho một request cụ thể, có thể tắt bằng header X-9Router-Token-Saver: off.

Kiểm tra hoạt động và xử lý lỗi thường gặp

Để xác định 9Router có đang hoạt động ổn định hay không, lệnh /status và /model bên trong Claude Code là những công cụ đầu tiên bạn cần dùng. Lệnh /status xác nhận base URL, trong khi /model hiển thị danh sách các combo mà 9Router đang "phơi" ra cho client thấy.

Các mã lỗi phổ biến bạn sẽ gặp bao gồm:

• 401 (Unauthorized): Thường do Local API Key trong cấu hình client không khớp với key hiển thị trên dashboard 9Router. Cũng có thể do bạn đặt key vào sai biến — ANTHROPIC_AUTH_TOKEN gửi qua header Authorization: Bearer, còn ANTHROPIC_API_KEY gửi qua x-api-key.
• 404 (Not Found): Gần như luôn là do hậu tố /v1 thừa trong ANTHROPIC_BASE_URL. Hãy bỏ nó đi.
• Model not found: Xảy ra khi bạn quên thêm tiền tố cần thiết trong tên mô hình, ví dụ kr/ cho các mô hình của Kiro.

Quy trình xử lý lỗi chuẩn: đầu tiên hãy kiểm tra dashboard 9Router xem request có hiển thị trong log không. Nếu không thấy, lỗi nằm ở cấu hình client. Nếu thấy request nhưng báo lỗi, hãy kiểm tra trạng thái của nhà cung cấp tương ứng trong dashboard. Cách tiếp cận theo từng tầng này giúp bạn cô lập vấn đề nhanh chóng thay vì thay đổi API key một cách mù quáng. Khi mọi thứ rối, hãy quay về cấu hình tối giản nhất: một nhà cung cấp, một mô hình, không combo.

Những rủi ro và giới hạn cần biết trước

Về mặt bảo mật, toàn bộ credential của bạn nằm trong cơ sở dữ liệu cục bộ dưới DATA_DIR. Hãy coi tệp database và các bản backup của nó là tài sản nhạy cảm, vì chúng chứa quyền truy cập vào mọi tài khoản trả phí bạn đã kết nối. Mật khẩu đăng nhập dashboard mặc định là 123456 (biến INITIAL_PASSWORD) — đổi nó trước tiên. Nếu bạn deploy lên VPS thay vì chạy localhost, hãy bật REQUIRE_API_KEY và đổi JWT_SECRET trước khi mở cổng ra internet.

Các dịch vụ miễn phí luôn biến động, và đây là điểm khiến nhiều hướng dẫn cũ trở nên vô dụng. Tầng miễn phí của iFlow và Qwen Code đã bị ngừng trong năm 2026, còn Gemini CLI bị Google đóng hoàn toàn vào tháng 6/2026. Một chi tiết dễ mất tiền oan: với Vertex AI, khoản credit $300 cho tài khoản GCP mới vẫn còn hiệu lực, nhưng từ tháng 3/2026 endpoint Gemini API không còn trừ vào khoản này nữa — bạn phải gọi đúng endpoint Vertex AI Studio. Một kỹ sư thực dụng luôn có ít nhất một API trả phí làm backup cứng trong combo của mình.

Về phía Anthropic, có một ranh giới bạn nên biết trước khi xây cả quy trình làm việc lên trên 9Router. Anthropic không xác nhận, không bảo trì và không kiểm định các sản phẩm gateway của bên thứ ba, và họ không hỗ trợ việc định tuyến Claude Code sang các mô hình không phải Claude thông qua bất kỳ gateway nào. Ngoài ra, khi biến credential của gateway đang bật, phiên làm việc đó không dùng tới gói đăng ký claude.ai của bạn nữa — toàn bộ lưu lượng được tính phí theo token cho chủ sở hữu credential mà gateway chuyển tiếp. Việc kết nối gói đăng ký cá nhân qua OAuth là quyết định của bạn, nhưng hãy đọc điều khoản hiện hành trước.

Cuối cùng là vấn đề nhất quán về chất lượng. Tự động fallback từ một mô hình mạnh ở Tier 1 sang một mô hình miễn phí ở Tier 3 sẽ thay đổi phong cách lập trình và khả năng suy luận. Bạn cần theo dõi log để chắc rằng code do mô hình fallback sinh ra không để lại nợ kỹ thuật (technical debt) cho dự án, vì năng lực giữa các LLM không giống nhau. Kinh nghiệm thực tế: giữ mô hình mạnh cho phần logic và kiến trúc, đẩy phần boilerplate, viết test hay tài liệu xuống các tầng rẻ hơn.

Khi nào nên dùng 9Router?

Bạn nên dùng 9Router nếu bạn lập trình với AI đủ nhiều để thường xuyên chạm trần tài khoản Pro, hoặc nếu bạn đang quản lý nhiều tài khoản AI khác nhau và muốn đẩy các tác vụ đơn giản sang mô hình giá rẻ. Với các repository có cấu trúc phức tạp, tính năng nén RTK phát huy tác dụng rõ nhất — thay vì gửi hàng chục KB dữ liệu thô từ tree hay git diff, bạn duy trì được cửa sổ ngữ cảnh dài hơn. Ngược lại, nếu bạn hài lòng với một gói đăng ký duy nhất và hiếm khi chạm trần, thêm một lớp hạ tầng để tự vận hành là cái giá không đáng trả.

9Router không phải phép màu tạo ra token miễn phí, mà là một lớp quản lý hạ tầng. Hãy bắt đầu bằng cách cài cục bộ và cấu hình Kiro AI để làm quen với luồng định tuyến, rồi mới xây những combo fallback phức tạp hơn.

Tài liệu tham khảo

• 9Router Claude Code Setup: API Base URL, Model Routing, and Common Errors
• 9Router Setup Guide: Cut AI Coding Costs with Smart LLM Routing — Agus Narestha
• 9Router Setup Guide: Route Claude Code, Codex, and Cursor with Fallback
• 9Router — Free AI Router | Smart Fallback for Claude, Codex & More
• 9Router: Open Source Alternative to GitHub Copilot and Cursor
• 9router/docs/ARCHITECTURE.md at master · decolua/9router
• GitHub — decolua/9router
• How to Make Claude Code Virtually Unlimited With 9Router — Jugal