# claude-code-router: quản lý và định tuyến AI tập trung — hướng dẫn cài đặt và dùng

> claude-code-router là gateway AI chạy cục bộ, giúp bạn kết nối nhiều agent như Claude Code, Codex, OpenCode và nhiều provider qua một địa chỉ ổn định. Bạn có thể quản lý API key, model, định tuyến, retry, fallback và log trong một giao diện. Cài bằng ứng dụng desktop khá dễ; bản CLI cần Node.js 22 trở lên.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-30 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/claude-code-router-dinh-tuyen-ai

Claude Code Router (CCR) là một gateway AI cục bộ giúp bạn quản lý nhiều agent, model và nhà cung cấp AI từ một nơi. Thay vì cấu hình riêng Claude Code, Codex, OpenCode hay các công cụ tương thích, bạn cho tất cả đi qua một endpoint ổn định trên máy mình.

CCR phù hợp với lập trình viên dùng nhiều agent, đội nhóm muốn kiểm soát cách request được gửi đi, hoặc người dùng cần đổi provider mà không muốn sửa lại cấu hình của từng ứng dụng. Dự án viết bằng TypeScript, dùng giấy phép MIT và hiện có khoảng 38.139 sao cùng 3.207 fork.

Điểm đáng giá nhất là CCR không chỉ chuyển tiếp request. Nó còn hỗ trợ retry, credential pool, xoay key, model fallback, viết lại request, công cụ MCP, tìm kiếm web, log chi tiết và ước tính chi phí. Bạn có thể bắt đầu bằng ứng dụng desktop trên Windows, macOS hoặc Linux, hoặc chạy bản CLI và Docker.

```repo
- repo | musistudio/claude-code-router
- kind | Ứng dụng
- desc | Claude Code Router gom nhiều agent và nhà cung cấp AI vào một gateway cục bộ để định tuyến, dự phòng và theo dõi request.
- stars | 38k
- lang | TypeScript
- license | MIT
```

## Claude Code Router làm được gì

### Gom nhiều agent về một đầu mối

CCR hỗ trợ Claude Code, Claude Design, Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode, Pi, ZCode và WorkBuddy. Các API client tương thích cũng có thể kết nối qua gateway này.

Lợi ích thực tế là bạn không phải nhớ từng cách khai báo provider của từng agent. Bạn cấu hình provider và model trong CCR, sau đó tạo profile cho agent tương ứng. Khi cần đổi model, bạn đổi trong CCR thay vì mở nhiều file cấu hình.

### Kết nối nhiều provider và giao thức

CCR hỗ trợ OpenAI Chat, OpenAI Responses, Anthropic Messages và Gemini Generate Content hoặc Interactions. Ngoài ra, dự án có preset cho OpenRouter, DeepSeek, SiliconFlow, Moonshot, Kimi Code, Mistral, Z.AI, Bailian và các endpoint tương thích tùy chỉnh.

Bạn có thể thêm provider bằng preset có sẵn hoặc tự nhập custom endpoint. CCR có khả năng dò giao thức, khám phá model và kiểm tra kết nối. Điều này hữu ích khi bạn đang thử nhiều dịch vụ AI hoặc muốn chuyển sang provider khác mà vẫn giữ nguyên quy trình làm việc.

### Định tuyến theo điều kiện

Bạn có thể đặt điều kiện dựa trên header và body của request, dùng prefix, rewrite, retry và fallback theo thứ tự. Ví dụ, một loại request có thể ưu tiên model nhanh, nếu lỗi thì chuyển sang model thứ hai.

Với người làm việc hằng ngày, cơ chế này giúp giảm gián đoạn. Với đội phát triển, nó cho phép tách model theo loại tác vụ mà không cần sửa từng agent.

### Duy trì request khi provider gặp sự cố

CCR hỗ trợ retry, nhiều credential và danh sách model dự phòng. Bạn có thể dùng credential pool hoặc xoay key trong những trường hợp cần phân phối request.

Tính năng này không làm provider miễn phí hay loại bỏ giới hạn quota. Nó chỉ giúp CCR xử lý các lựa chọn dự phòng theo cấu hình bạn đặt. Chi phí và giới hạn của từng provider vẫn cần được bạn theo dõi riêng.

### Bổ sung công cụ cho model

CCR có Fusion models, ToolHub, tự động hóa trình duyệt tích hợp, nhập trạng thái đăng nhập Chrome, wrapper plugin, core gateway plugin, local routes và virtual models. MCP tools cũng nằm trong nhóm khả năng mà CCR có thể bổ sung cho model hiện có.

Nhờ vậy, bạn có thể mở rộng khả năng của agent mà không nhất thiết phải thay toàn bộ model hoặc ứng dụng đang dùng.

### Theo dõi request và chi phí ước tính

Phần Logs hiển thị provider, model, credential đã được chọn, trạng thái, độ trễ, số token, chi phí ước tính, tool call và agent trace.

Đây là phần rất hữu ích khi một request cho kết quả chậm hoặc thất bại. Bạn có thể kiểm tra CCR thực sự đã route request đi đâu, dùng model nào và lỗi xảy ra ở bước nào.

### Quản lý quyền truy cập và hạn mức

CCR cho phép tạo client key riêng, đặt thời hạn và giới hạn request, token hoặc hình ảnh cục bộ. Tính năng này phù hợp khi nhiều client cùng kết nối đến một gateway hoặc khi bạn muốn kiểm soát mức sử dụng.

### Kết nối AgentClaw với nhiều nền tảng

AgentClaw hỗ trợ relay agent qua Weixin iLink, WeCom, Slack, Discord, Telegram, LINE, Feishu và DingTalk. Tư liệu được cung cấp không mô tả chi tiết từng quy trình kết nối, nên bạn cần xem hướng dẫn riêng trong tài liệu dự án nếu muốn dùng phần này.

## Cần chuẩn bị gì

Bạn có thể chạy CCR trên Windows, macOS hoặc Linux khi dùng ứng dụng desktop. README giới thiệu bản desktop cho cả ba hệ điều hành này.

Nếu dùng bản CLI, bạn cần Node.js phiên bản 22 trở lên. Repo cũng khai báo yêu cầu Node.js 22 trở lên cho quy trình build ứng dụng desktop.

Bạn cần tài khoản hoặc API key của provider mà mình muốn dùng. README cho biết trong màn hình Providers, bạn chọn preset hoặc custom endpoint, nhập API key, chọn protocol và model rồi lưu lại. Tư liệu không nói có một API key mặc định dùng chung cho tất cả provider.

Nếu chọn Docker, bạn cần môi trường Docker phù hợp. README chỉ cung cấp lệnh khởi động Docker Compose, không liệt kê chi tiết phiên bản Docker bắt buộc.

Bạn không cần GPU theo thông tin trong README. Dự án là gateway điều phối request đến provider, không được mô tả là mô hình chạy trực tiếp trên GPU của máy bạn.

Nếu muốn tự build ứng dụng desktop từ mã nguồn, bạn cần Node.js 22 trở lên và chạy `npm ci`. Build gói Windows phải thực hiện trên Windows x64 vì `better-sqlite3` dùng native Electron module.

```note
API key được nhập trong phần Providers. Chỉ thêm provider mà bạn tin cậy, không chia sẻ key trong ảnh chụp màn hình hoặc file cấu hình công khai. CCR có thể route request qua provider bạn chọn, vì vậy hãy kiểm tra chính sách dữ liệu, quota và chi phí của từng provider.
```

## Cài đặt từng bước

```steps
- Chọn cách chạy | Dùng ứng dụng desktop, CLI hoặc Docker
- Thêm provider | Nhập endpoint, protocol, model và API key
- Khởi động gateway | Bật server tại cổng mặc định 3456
- Tạo profile agent | Chọn agent và model rồi áp dụng cấu hình
- Kiểm tra log | Xác nhận provider, model, token và trạng thái request
```

### Chọn ứng dụng desktop

Đây là cách được README khuyến nghị nếu bạn muốn có giao diện trực quan. Tải Claude Code Router cho Windows, Linux hoặc macOS rồi mở ứng dụng.

README không cung cấp lệnh tải hoặc cài desktop app trong nội dung được cung cấp. Bạn cần lấy bộ cài từ trang chủ dự án hoặc phần phát hành tương ứng trong repo. Sau khi cài, mở ứng dụng và làm tiếp các bước cấu hình bên dưới.

Ứng dụng desktop phù hợp với người mới vì bạn có thể thêm provider, bật server, chọn agent và xem log bằng giao diện. Bạn không cần tự gõ lệnh để khởi động gateway.

### Thêm provider và API key

Mở mục **Providers → Add Provider**. Chọn một preset có sẵn hoặc chọn custom endpoint. Nhập API key, chọn protocol và các model muốn dùng, sau đó lưu lại.

Không nên điền nhầm API key vào phần tên model hoặc endpoint. Nếu provider dùng giao thức riêng, hãy chọn đúng protocol mà provider hỗ trợ. README cho biết CCR có bước kiểm tra kết nối, nên bạn có thể dùng bước này để phát hiện lỗi key hoặc endpoint trước khi tạo profile agent.

### Khởi động local gateway

Mở mục **Server** và bấm **Start**. Gateway model lắng nghe tại địa chỉ mặc định sau:

```text
http://127.0.0.1:3456
```

`127.0.0.1` nghĩa là gateway mặc định chạy trên chính máy bạn. Khi server đã chạy, các agent được cấu hình để dùng CCR sẽ gửi request qua cổng này.

### Tạo profile cho agent

Mở **Agent Config**. Chọn một agent như Claude Code, Claude Design, Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode, Pi, ZCode hoặc WorkBuddy. Chọn model, sau đó áp dụng profile.

Bạn nên chọn đúng agent mình thực sự đã cài trên máy. CCR quản lý profile và endpoint, nhưng README không nói rằng CCR tự cài toàn bộ agent bên ngoài.

### Kiểm tra bằng Logs

Mở mục **Logs** sau khi agent gửi request. Kiểm tra provider, model, status, token, latency, lỗi và credential đã được chọn.

Nếu request thành công, bạn sẽ thấy thông tin route đã được resolve. Nếu request không đi qua, log thường là nơi đầu tiên cần xem để phân biệt lỗi ở agent, CCR hay provider.

### Cài bản CLI bằng npm

Bản CLI cần Node.js 22 trở lên. Mở Terminal hoặc PowerShell ở vị trí bất kỳ mà tài khoản của bạn có quyền cài package toàn cục, rồi chạy đúng lệnh sau:

```bash
npm install -g @musistudio/claude-code-router
ccr ui
```

Lệnh đầu tiên cài CLI `@musistudio/claude-code-router` trên toàn hệ thống. Cờ `-g` là cài toàn cục, giúp lệnh `ccr` có thể được gọi từ các thư mục khác.

Lệnh thứ hai khởi động giao diện quản lý trên nền tảng web. Mở địa chỉ sau bằng trình duyệt:

```text
http://127.0.0.1:3458
```

Giao diện CLI dùng luồng cấu hình giống bản desktop: **Providers → Server → Agent Profiles**. Management UI chạy ở cổng 3458, còn model gateway vẫn chạy ở cổng 3456.

Nếu PowerShell báo không tìm thấy `npm`, hãy kiểm tra Node.js đã được cài và phiên bản có đạt yêu cầu hay chưa. Nếu cài package thành công nhưng không gọi được `ccr`, hãy kiểm tra thư mục npm global đã có trong PATH của terminal hay chưa. README không cung cấp lệnh sửa PATH cụ thể, nên không nên tự thêm biến môi trường khi chưa xác định cách cài Node.js trên máy.

### Chạy bằng Docker Compose

Nếu bạn đã chuẩn bị Docker, mở Terminal tại thư mục repo có `package.json` và chạy:

```bash
npm run docker:compose:up
```

Script này khởi động Docker Compose. README cho biết Docker mặc định expose management UI và gateway routes qua:

```text
http://127.0.0.1:3458
```

Bản Docker cũng dùng cổng 3458 cho giao diện quản lý. README ghi rằng npm script sẽ chuẩn bị local plugin-capable ai-gateway runtime trước khi build image nếu thư mục `../../next-ai/gateway` tồn tại.

Sau khi giao diện mở được, làm tiếp quy trình **Providers → Server → Agent Profiles**. Trước khi expose CCR ra mạng từ xa, hãy đọc Docker deployment guide của dự án và kiểm tra quyền truy cập. Không nên mở gateway trực tiếp ra Internet khi chưa hiểu rõ cơ chế xác thực và giới hạn truy cập.

### Tự build ứng dụng desktop từ mã nguồn

Nếu muốn build từ source, clone repo rồi đi vào thư mục dự án:

```bash
git clone https://github.com/musistudio/claude-code-router.git
cd claude-code-router
```

README yêu cầu Node.js 22 trở lên. Cài dependency đúng theo lệnh sau:

```bash
npm ci
```

Để build bản macOS local DMG hoặc ZIP:

```bash
npm run build:app:mac
```

Kết quả nằm trong thư mục `release-local/`.

Để build installer NSIS cho Windows:

```bash
npm run build:app:win
```

Kết quả cũng nằm trong `release-local/`. Build Windows phải chạy trên Windows x64 vì `better-sqlite3` cung cấp native Electron module. Không nên chạy lệnh build Windows trên macOS hoặc Linux rồi kỳ vọng nhận được installer Windows theo đúng quy trình của README.

## Kiểm tra đã chạy được chưa

Với bản desktop, dấu hiệu đầu tiên là ứng dụng mở được. Sau khi thêm provider, vào **Server** và bấm **Start**. Gateway phải lắng nghe tại `http://127.0.0.1:3456`.

Tiếp theo, vào **Agent Config**, chọn agent và model rồi áp dụng profile. Gửi một request thử từ agent. Mở **Logs** và kiểm tra có request với provider, model, trạng thái, token và latency hay không.

Với bản CLI, sau khi chạy `ccr ui`, mở `http://127.0.0.1:3458`. Nếu giao diện hiện ra, bạn đã khởi động được management UI. Hãy nhớ rằng UI ở cổng 3458 còn model gateway ở cổng 3456.

Với Docker, giao diện quản lý cũng mở tại `http://127.0.0.1:3458` theo README. Sau đó thêm provider, bật server trong giao diện và gửi request thử. Kết quả mong đợi là request xuất hiện trong Logs cùng route đã được resolve.

Nếu tự build desktop, việc lệnh `npm ci` hoàn tất và lệnh build tạo output trong `release-local/` là dấu hiệu quy trình build đã chạy đúng. README không đưa ra màn hình mẫu hoặc thông báo thành công cụ thể hơn.

## Dùng vào việc thật

### Dev dùng Claude Code và Codex trong cùng dự án

Một lập trình viên có thể dùng Claude Code cho tác vụ sửa code và Codex cho một số tác vụ khác. Thay vì cấu hình provider riêng trong hai công cụ, bạn thêm provider vào CCR, khởi động server rồi tạo profile cho từng agent.

Trong **Agent Config**, chọn Claude Code, chọn model phù hợp và áp dụng profile. Lặp lại với Codex. Khi cần đổi provider, bạn đổi trong CCR và giữ nguyên luồng làm việc của hai agent.

Kết quả là cả hai agent cùng đi qua một local endpoint, trong khi bạn vẫn nhìn thấy provider và model thực tế trong Logs.

### Nhóm phát triển cần fallback khi model lỗi

Một nhóm đang chạy tác vụ lập trình quan trọng có thể cấu hình model chính và model dự phòng theo thứ tự. Trong **Routing**, thêm điều kiện, retry và ordered fallback models theo nhu cầu.

Khi model hoặc credential đầu tiên gặp lỗi, CCR có thể thử lại hoặc chuyển sang lựa chọn tiếp theo theo cấu hình. Người dùng vẫn cần kiểm tra quota và chi phí của tất cả model dự phòng.

Kết quả phù hợp là request ít bị dừng đột ngột hơn, còn Logs cho biết route cuối cùng đã dùng provider nào.

### Nhân viên văn phòng cần một agent có khả năng mở rộng

Một nhân viên dùng agent để xử lý công việc có thể kết nối agent vào CCR, sau đó bổ sung MCP tools, ToolHub hoặc khả năng tự động hóa trình duyệt nếu cấu hình của dự án hỗ trợ.

Bạn bắt đầu bằng việc thêm provider, chọn model, tạo Agent Profile rồi kiểm tra một request đơn giản. Sau đó mới bật từng tool cần thiết và theo dõi tool call trong Logs.

Cách này giúp biết request nào chỉ gọi model, request nào sử dụng tool và request nào có độ trễ cao hơn.

### Người quản lý muốn theo dõi mức sử dụng

Một nhóm có nhiều client có thể tạo CCR client key riêng, đặt thời hạn và giới hạn request, token hoặc hình ảnh cục bộ. Mỗi client dùng key tương ứng thay vì chia sẻ một cấu hình không kiểm soát.

Trong quá trình vận hành, xem Logs để theo dõi token, latency, chi phí ước tính, trạng thái và credential. Đây là dữ liệu hỗ trợ kiểm tra mức sử dụng, nhưng chi phí ước tính trong CCR không thay thế hóa đơn chính thức từ provider.

> Một endpoint ổn định giúp bạn đổi model và provider mà không phải đổi cả quy trình làm việc.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Không mở được giao diện CLI

Hãy kiểm tra Node.js có từ phiên bản 22 trở lên không, package CLI đã cài thành công chưa và lệnh `ccr ui` có đang chạy trong terminal hay không. Nếu terminal báo không nhận diện `ccr`, kiểm tra PATH của npm global.

README không cung cấp lệnh sửa PATH cụ thể. Vì vậy, hãy kiểm tra cách cài Node.js và npm trên hệ điều hành của bạn trước khi sửa biến môi trường thủ công.

### Gateway chưa chạy ở cổng 3456

Với desktop, mở **Server** và bấm **Start**. Với CLI hoặc Docker, kiểm tra tiến trình khởi động vẫn còn chạy và giao diện quản lý có mở được không.

Đừng nhầm cổng 3458 của management UI với cổng 3456 của model gateway. Hai cổng này phục vụ hai phần khác nhau.

### Provider báo lỗi kết nối hoặc request thất bại

Vào **Providers**, kiểm tra API key, custom endpoint, protocol và model. Dùng tính năng kiểm tra kết nối nếu có trong giao diện. Nếu provider giới hạn quota hoặc key hết quyền, CCR không thể tự tạo quyền mới.

Bạn cũng nên mở **Logs** để xem status, provider, model và credential đã được chọn. Những thông tin này giúp xác định lỗi nằm ở cấu hình CCR hay ở provider.

### Agent không nhận profile

Kiểm tra bạn đã chọn đúng agent trong **Agent Config**, đã chọn model và bấm áp dụng profile chưa. CCR quản lý cấu hình kết nối, nhưng README không nói CCR tự cài Claude Code, Codex hoặc các agent khác.

Nếu agent bên ngoài chưa được cài hoặc không được hỗ trợ đúng cách, hãy kiểm tra tài liệu riêng của agent đó.

### Docker khởi động nhưng thiếu plugin runtime

README ghi npm script sẽ chuẩn bị local plugin-capable ai-gateway runtime trước khi build image nếu `../../next-ai/gateway` tồn tại. Nếu thư mục này không tồn tại, hành vi build có thể khác với môi trường đầy đủ.

Kiểm tra cấu trúc thư mục và đọc Docker deployment guide trước khi expose CCR từ xa. Không tự thêm đường dẫn hoặc biến môi trường không được tài liệu xác nhận.

## Có nên dùng không

CCR đáng dùng nếu bạn đang sử dụng nhiều agent hoặc nhiều provider và muốn gom cấu hình về một nơi. Các điểm mạnh rõ nhất là local endpoint ổn định, profile cho nhiều agent, retry và fallback, quản lý credential, routing theo điều kiện, MCP và ToolHub, cùng phần Logs khá nhiều thông tin.

Bản desktop phù hợp với người mới vì thao tác chính nằm trong giao diện. Bản CLI phù hợp với người quen terminal và muốn chạy gateway không cần Electron. Docker phù hợp với người đã có quy trình triển khai container.

Giới hạn là CCR không cung cấp model hoặc API key miễn phí. Bạn vẫn phải tự có quyền truy cập provider, tự chịu quota và chi phí. Tư liệu cũng không mô tả chi tiết mọi provider, cách bảo vệ gateway khi expose ra Internet, hay cách xử lý toàn bộ agent bên ngoài.

Nếu bạn chỉ dùng một agent và một provider, CCR có thể thêm một lớp cấu hình không cần thiết. Nếu bạn cần chạy model hoàn toàn cục bộ trên máy mà không gửi request đến provider bên ngoài, README được cung cấp chưa cho thấy đây là mục tiêu chính của dự án.

Nhìn chung, CCR phù hợp với người muốn kiểm soát nhiều agent và model qua một gateway cục bộ. Hãy bắt đầu bằng bản desktop, cấu hình một provider, kiểm tra Logs rồi mới thêm routing, fallback và công cụ mở rộng.

## Câu hỏi thường gặp

### Claude Code Router có miễn phí không?

Repo dùng giấy phép MIT. Tuy nhiên README không nói rằng các provider hoặc API key đều miễn phí. Bạn vẫn có thể phát sinh chi phí và giới hạn quota từ provider mà mình cấu hình.

### Có cần GPU để chạy Claude Code Router không?

README không yêu cầu GPU. CCR được mô tả là gateway và control plane cục bộ để route request đến provider, không phải mô hình chạy trực tiếp trên GPU của máy.

### Có chạy được trên Windows không?

Có. README giới thiệu ứng dụng desktop cho Windows và có lệnh build installer Windows. Quy trình build Windows phải chạy trên Windows x64 vì better-sqlite3 có native Electron module.

### Bản CLI cần Node.js phiên bản nào?

CLI yêu cầu Node.js 22 trở lên. Bạn cài package toàn cục bằng npm rồi chạy lệnh `ccr ui` để mở giao diện quản lý trên trình duyệt.

### Dữ liệu và API key có an toàn không?

Gateway mặc định lắng nghe trên `127.0.0.1`, tức là trên máy cục bộ. README không đưa ra cam kết bảo mật chi tiết cho từng provider, vì vậy bạn cần tự bảo vệ API key và thận trọng trước khi expose CCR ra mạng từ xa.

### CCR khác gì so với việc cấu hình từng agent riêng?

CCR gom agent, provider, model, credential, routing và log vào một nơi. Bạn có thể đổi provider hoặc model mà không phải sửa cấu hình của từng agent, đồng thời dùng retry, fallback và theo dõi request.

### Có thể dùng Docker không?

Có. README cung cấp lệnh `npm run docker:compose:up`, sau đó management UI và gateway routes được expose qua `http://127.0.0.1:3458` theo cấu hình mặc định.
