Claude Code Router: Định tuyến đa mô hình cho việc lập trình hiệu quả

Khi tôi bắt đầu dùng Claude Code nhiều hơn, tôi nhanh chóng nhận ra hai điều: chất lượng rất tốt, và hóa đơn cũng phản ánh điều đó. Mọi yêu cầu, dù chỉ là một docstring ba dòng hay một đợt tái cấu trúc kiến trúc toàn diện, đều đánh vào cùng một endpoint của Anthropic với cùng mức giá. 

Theo thời gian, phụ thuộc vào một nhà cung cấp không chỉ gây áp lực về chi phí mà còn tạo rủi ro. Nó cũng có nghĩa là giới hạn tốc độ của một mô hình có thể khiến toàn bộ quy trình làm việc của bạn bị đình trệ.

Claude Code Router (CCR) giải quyết trực tiếp cả hai vấn đề. Đây là một proxy mã nguồn mở chặn các yêu cầu Claude Code của bạn trước khi chúng đến bất kỳ nhà cung cấp nào, rồi chuyển hướng từng yêu cầu đến mô hình backend phù hợp nhất với tác vụ đó. 

Trong hướng dẫn này, tôi sẽ dẫn bạn qua toàn bộ thiết lập: cài đặt router, cấu hình các tuyến định tuyến đa nhà cung cấp và tăng cường độ ổn định cho vận hành hằng ngày. Để theo dõi, hãy lấy khóa API cho các nhà cung cấp bạn muốn dùng (DeepSeek, Gemini, OpenRouter, hoặc bất kỳ backend được hỗ trợ nào khác) và mở terminal của bạn. Bắt đầu thôi.

Để tìm cảm hứng về các LLM mới và thế mạnh của chúng, hãy xem các bài hướng dẫn về những mô hình mới nhất dưới đây:

• GPT-5.4
• GPT-5.3 Instant
• Gemini 3.1
• Claude Sonnet 4.6
• Claude Opus 4.6
• Qwen3.5
• MiniMax M2.5

Claude Code Router là gì?

Trước khi đi vào thiết lập, bạn nên hiểu CCR thực chất là gì và tại sao nó hoạt động theo cách như vậy. Nếu bạn chưa làm việc với Claude Code, hãy xem trước Hướng dẫn thực hành Claude Code 2.1 của chúng tôi.

Claude Code Router là một cổng proxy cục bộ. Khi khởi chạy, nó gắn vào một cổng trên máy của bạn (mặc định 127.0.0.1:3456) và đứng giữa client Claude Code và bất kỳ nhà cung cấp LLM bên ngoài nào. Với góc nhìn của Claude Code, nó chỉ đang nói chuyện với một endpoint cục bộ. Bên dưới, CCR quyết định theo thời gian thực yêu cầu đó thực sự sẽ đi đâu.

Vấn đề cốt lõi nó giải quyết là phụ thuộc vào một nhà cung cấp. Khi mọi thứ đều đi qua một nhà cung cấp, bạn kế thừa mọi ràng buộc của họ: 

• Bậc giá
• Giới hạn tốc độ
• Giới hạn cửa sổ ngữ cảnh 

CCR loại bỏ điều đó bằng cách cho phép bạn định nghĩa các quy tắc định tuyến tự động chuyển đổi mô hình dựa trên loại tác vụ, số token, hoặc bất kỳ logic tùy chỉnh nào bạn viết. Quét file nền không cần cùng một mô hình với một phiên suy luận Plan Mode, và với CCR, nó sẽ không dùng cùng một mô hình nữa.

Điểm khác biệt của CCR với API trực tiếp của nhà cung cấp hoặc các bộ tổng hợp trên đám mây nằm ở nơi nó chạy. 

Bởi vì proxy chạy cục bộ, payload yêu cầu của bạn không bao giờ đi qua một dịch vụ tổng hợp bên thứ ba trước khi đến đích. Bạn cũng có quyền kiểm soát chi tiết việc biến đổi yêu cầu, bao gồm sửa đổi header, loại bỏ các trường cache và giới hạn token, thông qua một hệ thống transformer hoạt động hoàn toàn trên máy của bạn. 

Theo tôi, mô hình thực thi cục bộ này khiến CCR thực sự thực tiễn thay vì chỉ là một cách lách khéo: kết quả là một thiết lập tiết kiệm chi phí hơn, bền bỉ hơn và riêng tư hơn so với việc định tuyến mọi thứ qua một nhà cung cấp đám mây duy nhất.

Kiến trúc và điều kiện tiên quyết của Claude Code Router

Với bức tranh rõ ràng về CCR, hãy xem nó hoạt động bên dưới như thế nào và bạn cần gì trước khi cài đặt.

Mô hình khái niệm cốt lõi

Hiểu kiến trúc của CCR giúp việc cấu hình dễ nắm bắt hơn nhiều, và tôi thấy mẫu proxy sẽ “bật” ngay khi bạn thấy toàn trình từ đầu đến cuối. 

Khi bạn khởi động CCR, nó chặn mọi yêu cầu đi ra từ terminal của bạn trước khi chúng đến endpoint mặc định của Anthropic. Với mỗi yêu cầu, nó sẽ:

1. Kiểm tra yêu cầu.
2. Áp dụng các quy tắc định tuyến của bạn.
3. Biến đổi payload sang định dạng mong đợi của nhà cung cấp mục tiêu.
4. Chuyển tiếp đi. 

Phản hồi quay lại theo cách tương tự, được chuyển đổi về định dạng mà Claude Code mong đợi, vì vậy client không bao giờ biết có gì thay đổi.

Cơ chế then chốt trong quá trình chặn đó là định tuyến dựa trên tác vụ. CCR phân loại yêu cầu đến theo loại và ánh xạ chúng tới mô hình phù hợp. Dưới đây là cách các nhóm tác vụ chính vận hành trong thực tế:

Mỗi loại tác vụ sẽ có công cụ phù hợp, và sau khi cấu hình, không cần can thiệp thủ công nữa. Theo trải nghiệm của tôi, tuyến background mang lại hiệu quả tức thì lớn nhất: các yêu cầu quét file âm thầm đó diễn ra liên tục trong một phiên lập trình, và trước khi có CCR, tôi không hề biết chúng âm thầm cộng dồn nhiều đến vậy.

Điều kiện tiên quyết thiết yếu

Trước khi cài CCR, hãy đảm bảo có sẵn những thứ sau:

• Node.js v18 trở lên làm môi trường runtime

• npm làm trình quản lý gói

• Cài đặt Claude Code ở mức global (npm install -g @anthropic-ai/claude-code)

• Ít nhất một backend mô hình, hoặc một khóa API từ nhà cung cấp bên ngoài được hỗ trợ (DeepSeek, Gemini, OpenRouter, Groq, Volcengine, SiliconFlow, và các nhà cung cấp khác), hoặc một phiên bản Ollama cục bộ với mô hình đã được kéo về, nếu bạn muốn tránh hoàn toàn nhà cung cấp bên ngoài

Bạn không cần tài khoản với mọi nhà cung cấp ngay từ đầu. Một backend hoạt động là đủ để hoàn thành hướng dẫn này, và bạn có thể thêm tiếp sau.

Để so sánh Claude Code với một lựa chọn thay thế phổ biến, tôi khuyên bạn đọc bài viết OpenClaw và Claude Code.

Hướng dẫn từng bước: Thiết lập Claude Code Router

Khi khái niệm và điều kiện tiên quyết đã rõ, hãy xây dựng thiết lập theo từng bước.

Cài đặt và khởi động router

Khi đã có đủ điều kiện, bạn có thể cài CCR ở mức global bằng npm. Trên Linux, tuy nhiên, bạn có thể gặp lỗi quyền khi cài gói global vì npm cố ghi vào /usr/lib/node_modules, thuộc sở hữu của root. Cách khuyến nghị là chuyển hướng thư mục global của npm đến một thư mục mà user của bạn sở hữu sẵn, thay vì chạy lệnh với sudo:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Để thay đổi PATH đó thành vĩnh viễn, hãy thêm dòng export vào ~/.bashrc hoặc ~/.zshrc và tải lại shell của bạn. Sau đó cài CCR:

npm install -g @musistudio/claude-code-router

Lệnh này giúp CLI ccr khả dụng ở mức global trong shell của bạn. Tiếp theo, khởi động dịch vụ router:

ccr start

Mặc định CCR gắn vào http://127.0.0.1:3456. Khi bạn thấy dịch vụ đã gắn vào cổng trong log khởi động, proxy sẵn sàng nhận yêu cầu.

Cấu hình nhà cung cấp nền tảng

Toàn bộ cấu hình CCR nằm trong ~/.claude-code-router/config.json. Trước khi nối nhiều nhà cung cấp, tôi khuyên bạn bắt đầu với một nhà cung cấp đơn lẻ, đã biết hoạt động tốt để loại trừ biến số và xác nhận nền tảng.

OpenRouter là lựa chọn khởi đầu tốt, và cũng là thứ tôi dùng đầu tiên khi thiết lập CCR trên máy mới. Bạn có quyền truy cập hàng chục mô hình, gồm cả một số mô hình free-tier, chỉ với một khóa API, rất lý tưởng để vận hành lớp định tuyến trước khi cam kết với các nhà cung cấp cụ thể. Bạn có thể đăng ký và lấy khóa tại OpenRouter.

Dưới đây là cấu hình tối thiểu dùng OpenRouter:

{
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "YOUR_OPENROUTER_API_KEY",
      "models": ["openai/gpt-oss-120b:free"],
      "transformer": {
        "use": ["openrouter"]
      }
    }
  ],
  "Router": {
    "default": "openrouter,openai/gpt-oss-120b:free"
  }
}

Một vài điểm cần lưu ý:

• api_base_url phải trỏ đến endpoint chat completions đầy đủ của nhà cung cấp, không chỉ domain gốc.

• transformer chỉ định adapter payload dựng sẵn mà CCR sẽ dùng, vì mỗi nhà cung cấp kỳ vọng định dạng yêu cầu khác nhau. Transformer xử lý việc dịch đó một cách im lặng.

• Router.default đặt mô hình dự phòng cho bất kỳ yêu cầu nào không khớp quy tắc cụ thể hơn, theo cú pháp provider,model.

Vì bảo mật, tránh hardcode khóa trực tiếp vào file. CCR hỗ trợ nội suy biến môi trường: thay YOUR_OPENROUTER_API_KEY bằng $OPENROUTER_API_KEY và export biến trong shell. Việc nội suy hoạt động đệ quy trên toàn bộ cấu hình, nên mẫu này mở rộng sạch sẽ khi bạn thêm nhiều nhà cung cấp.

Kết nối Claude Code với proxy

Khi đã có cấu hình, khởi chạy Claude Code qua router chỉ với một lệnh:

ccr code

Vậy là xong. ccr code khởi động proxy và đồng thời mở Claude Code, với môi trường được cấu hình sẵn tự động. Bạn không cần chạy ccr start trước.

Để xác minh định tuyến đang hoạt động, kiểm tra thư mục ~/.claude-code-router/logs/. Một file tên ccr-*.log ở đó xác nhận proxy đã khởi động và đang nhận yêu cầu. Bạn có thể tail để xem yêu cầu theo thời gian thực:

tail -f ~/.claude-code-router/logs/$(ls -t ~/.claude-code-router/logs/ | head -1)

Nhật ký Claude Code Router

Có hai điều đáng biết về việc xác minh. Header của Claude Code luôn hiển thị mô hình Claude mặc định hiện tại, bất kể CCR đang định tuyến đến mô hình nào, vì nó phản ánh phiên tài khoản Anthropic của bạn chứ không phải backend đang hoạt động. Nếu bạn hỏi mô hình "bạn là mô hình nào?", nó cũng sẽ trả lời “Claude Sonnet 4.6”, vì client Claude Code hướng dẫn nó tự nhận như vậy. Cả hai đều không phải tín hiệu đáng tin.

Phiên Claude Code Router

Log là nguồn chân lý duy nhất. Hãy tìm trường "model" trong các mục phản hồi. Nếu bạn thấy tên mô hình đã cấu hình ở đó, ví dụ, "model":"openai/gpt-oss-120b:free", thì định tuyến đang hoạt động.

Nếu bạn muốn CCR chạy thường trực để có thể dùng trực tiếp lệnh claude mà không cần ccr code, hãy thêm dòng này vào ~/.bashrc or ~/.zshrc:

eval "$(ccr activate)"

Chỉ cần chắc chắn rằng ccr start chạy trước trong trường hợp đó, vì activate chỉ đặt biến môi trường và không khởi động dịch vụ.

Triển khai định tuyến đa nhà cung cấp

Khi nền tảng đã được xác thực, hãy mở rộng cấu hình để định tuyến các loại tác vụ khác nhau đến các nhà cung cấp khác nhau. Dưới đây là cấu hình Router đầy đủ hơn:

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

Mỗi khóa ánh xạ một nhóm tác vụ tới cặp "provider,model":

• Tuyến background xử lý quét file và thu thập ngữ cảnh. Những yêu cầu này có thể chuyển an toàn sang mô hình Ollama cục bộ để miễn phí, và đây là thay đổi đơn lẻ giúp giảm mạnh hóa đơn API hàng tháng của tôi. 

• Tuyến think bắt các tác vụ Plan Mode và suy luận phức tạp, nơi một mô hình như deepseek-reasoner xứng đáng với chi phí. 

• Tuyến longContext tự động kích hoạt khi yêu cầu vượt quá số token longContextThreshold (mặc định 60.000), chuyển hướng tới mô hình dung lượng cao mà không cần chuyển đổi thủ công. 

• Với webSearch, lưu ý bản thân mô hình phải hỗ trợ tìm kiếm web gốc. Nếu bạn định tuyến qua OpenRouter, bạn cũng cần thêm hậu tố :online vào tên mô hình (ví dụ, "anthropic/claude-3.5-sonnet:online").

Để tăng khả năng chịu tải giới hạn tốc độ, tính năng custom router của CCR cho phép bạn định nghĩa logic dự phòng bằng JavaScript. Tạo một file tại đường dẫn bạn chọn, tham chiếu nó trong cấu hình với "CUSTOM_ROUTER_PATH": "/path/to/custom-router.js", rồi export một hàm async trả về chuỗi "provider,model" hoặc null để quay về quy tắc mặc định:

module.exports = async function router(req, config) {
  // Primary logic here. Return null to fall back to config-defined rules.
  return null;
};

Đây là nơi bạn triển khai logic retry khi bị rate-limit, ví dụ bằng cách phát hiện phản hồi 429 và tự động định tuyến lại sang nhà cung cấp phụ. Sau mọi thay đổi cấu hình, nhớ khởi động lại dịch vụ để áp dụng:

ccr restart

Vận hành và khắc phục sự cố Claude Code Router

Khi định tuyến đã hoạt động, trọng tâm chuyển sang giữ cho hệ thống dễ quan sát, an toàn và dễ gỡ lỗi khi có sự cố.

Giám sát sử dụng và áp dụng ngân sách

CCR cung cấp hai hệ thống ghi log riêng biệt đáng chú ý:

• Log cấp máy chủ bao quát yêu cầu HTTP, cuộc gọi API và sự kiện máy chủ. Chúng được ghi vào ~/.claude-code-router/logs/ trong các file có tên ccr-*.log. Đây là log bạn sẽ dùng nhiều nhất.

• Log cấp ứng dụng ghi lại quyết định định tuyến và được ghi vào ~/.claude-code-router/claude-code-router.log, dù file này có thể không luôn tồn tại tùy thiết lập và mức log.

Xem lại log máy chủ thường xuyên giúp bạn có bức tranh rõ về tuyến nào đang kích hoạt, mô hình nào được gọi, và có lỗi nhà cung cấp nào xảy ra hay không. 

Để quan sát theo thời gian thực, CCR còn có công cụ statusline (từ bản v1.0.40 trở đi) bạn có thể bật qua ccr ui. Khi kích hoạt, nó hiển thị trạng thái định tuyến ngay trong terminal khi Claude Code đang chạy, cho bạn thấy nhanh mô hình nào xử lý từng yêu cầu.

Về ngân sách, hàng rào bảo vệ hiệu quả nhất là chính cấu hình định tuyến của bạn. Bằng cách đảm bảo các tuyến background và default trỏ về mô hình rẻ hơn hoặc cục bộ, bạn tránh gọi các mô hình cao cấp cho tác vụ giá trị thấp. Dành think và longContext cho những mô hình xứng đáng chi phí, và giữ ngưỡng token cho longContext cao nhất trong phạm vi quy trình của bạn chịu được. 

Theo kinh nghiệm của tôi, kỷ luật ở cấp cấu hình này đáng tin cậy hơn so với giám sát phản ứng, vì nó ngăn chi tiêu vượt mức trước khi xảy ra thay vì phát hiện sau đó.

Bảo mật thông tin xác thực và kiểm soát truy cập

Quản lý thông tin xác thực xứng đáng được chú ý riêng, đặc biệt khi danh sách nhà cung cấp của bạn tăng lên. Các quy tắc tôi tuân theo rất đơn giản:

• Không bao giờ commit khóa API thô vào config.json nếu file đó được theo dõi trong hệ thống quản lý phiên bản. Luôn dùng nội suy biến môi trường với cú pháp "$PROVIDER_API_KEY", và export khóa từ profile shell của bạn hoặc một trình quản lý bí mật.

• Giữ proxy trên localhost cho thiết lập của từng lập trình viên. Nếu bạn không đặt APIKEY trong cấu hình, CCR tự động buộc máy chủ chỉ gắn vào 127.0.0.1, ngăn truy cập bên ngoài trên máy hoặc mạng dùng chung.

• Đặt một APIKEY cho triển khai nhóm nếu bạn cần mở host ra 0.0.0.0. Mọi client kết nối tới router phải kèm khóa đó trong header Authorization: Bearer hoặc x-api-key.

• Tắt hoặc giảm log nếu bạn định tuyến mã nhạy cảm. Logging được bật mặc định ("LOG": true). Đặt "LOG": false để dừng ghi payload yêu cầu xuống đĩa, hoặc "LOG_LEVEL": "warn" để ẩn log debug chi tiết.

Một cách thực tiễn là giữ tất cả khóa API trong profile shell và tham chiếu chúng qua cú pháp $VAR_NAME trong config.json. Nhờ vậy, bản thân file cấu hình không chứa bí mật nào và có thể chia sẻ hoặc quản lý phiên bản an toàn.

Nếu bạn không chắc khóa có bị ghi vào log hay không, hãy kiểm tra thiết lập mức log trước. Chuyển sang "LOG_LEVEL": "warn" là cách nhanh nhất để giảm nội dung ghi xuống đĩa mà không cần tắt hoàn toàn logging.

Khắc phục lỗi định tuyến thường gặp

Khi có sự cố, một chuỗi chẩn đoán theo lớp sẽ tiết kiệm nhiều thời gian. Tôi thấy tốt nhất là bắt đầu từ lớp ngoài cùng rồi đi vào trong.

Bước 1: Kiểm tra proxy có đang chạy 

Chạy ccr code và tìm xác nhận khởi động dịch vụ. Nếu cổng bị chiếm dụng hoặc dịch vụ khởi động lỗi, bạn sẽ thấy lỗi connection refused trong Claude Code. 

Kiểm tra log máy chủ trong ~/.claude-code-router/logs/ để biết chi tiết. Hầu hết lỗi khởi động là do xung đột cổng hoặc file config.json sai định dạng.

Bước 2: Kiểm tra tên mô hình khớp nhau

Lỗi cấu hình phổ biến nhất là không khớp giữa tên mô hình trong Providers và trong Router. Cả hai phải giống hệt nhau. 

Nếu khác nhau, CCR sẽ gửi yêu cầu không có trường model, và bạn sẽ thấy lỗi Missing model in request body. Sau khi sửa cấu hình, luôn chạy ccr restart để tải lại.

Bước 3: Kiểm tra thiết lập phía nhà cung cấp

Nếu tên mô hình đúng nhưng yêu cầu vẫn thất bại với 404, hãy kiểm tra cài đặt tài khoản nhà cung cấp. Ví dụ, OpenRouter có chính sách quyền riêng tư mặc định chặn mô hình miễn phí gửi dữ liệu đến nhà cung cấp bên thứ ba. Bạn sẽ thấy lỗi như No endpoints found matching your data policy. 

Cách khắc phục là truy cập cài đặt quyền riêng tư OpenRouter và bật sử dụng mô hình miễn phí. Các nhà cung cấp khác có thể có các nút gạt ở cấp tài khoản tương tự cần kiểm tra nếu bạn gặp lỗi 4xx bất ngờ.

Bước 4: Kiểm tra cấu hình transformer

Nếu yêu cầu đến được nhà cung cấp nhưng phản hồi sai định dạng hoặc gọi tool thất bại, nguyên nhân thường là thiếu hoặc dùng sai transformer. Hãy đối chiếu nhà cung cấp của bạn với danh sách transformer dựng sẵn và đảm bảo transformer đúng nằm trong mảng "use".

Trong hầu hết trường hợp, làm theo bốn bước này theo thứ tự sẽ nhanh chóng cô lập vấn đề. Log máy chủ ghi lại cả yêu cầu gửi đi và phản hồi thô từ nhà cung cấp, cho bạn mọi thứ cần để hiểu sự cố xảy ra ở đâu.

Kết luận

Giờ đây bạn đã có hạ tầng định tuyến đa nhà cung cấp hoạt động dựa trên Claude Code. Các tác vụ nền chạy trên mô hình cục bộ nhanh, công việc nặng suy luận định tuyến sang mô hình chuyên biệt, và yêu cầu ngữ cảnh dài được xử lý bởi nhà cung cấp dung lượng lớn — tất cả đều tự động dựa trên các quy tắc do bạn kiểm soát. 

Lợi ích tức thì là chi phí API thấp hơn, không còn điểm lỗi đơn trong giới hạn tốc độ, và linh hoạt hoán đổi nhà cung cấp mà không phải đụng đến quy trình làm việc.

Để giữ thiết lập hiệu quả theo thời gian, hãy xem nhật ký định tuyến định kỳ. Log máy chủ sẽ cho thấy tuyến nào kích hoạt thường xuyên nhất và liệu các mô hình đắt đỏ có đang được gọi cho tác vụ mà mô hình rẻ hơn có thể xử lý hay không. Điều chỉnh longContextThreshold và quy tắc dự phòng dựa trên sử dụng thực tế hiệu quả hơn nhiều so với đặt một lần rồi bỏ đó.

Cuối cùng, nếu công việc của bạn liên quan đến mã sở hữu độc quyền, tôi rất khuyến nghị định tuyến các yêu cầu đó đến LLM cục bộ qua Ollama. Đây là điều tôi luôn làm cho mọi dự án khách hàng có mã chưa phát hành. Thêm nó làm nhà cung cấp chỉ mất chưa đến một phút, và các truy vấn nhạy cảm nhất của bạn sẽ không bao giờ rời khỏi máy.

Với những ai muốn nâng tầm phát triển ứng dụng AI, tôi rất khuyến nghị đăng ký lộ trình kỹ năng AI Engineering with LangChain. Nội dung giảng dạy có tư duy AI-native, giúp bạn tiếp cận một gia sư AI cá nhân dạy đúng các kỹ năng bạn cần để trở thành chuyên gia về thiết kế quy trình AI.