claude-code-router: một cổng chung cho mọi agent AI lập trình — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về musistudio/claude-code-router — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: claude-code-router: quản lý và định tuyến AI tập trung — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Claude Code Router (CCR) là một cổng model cục bộ kèm giao diện quản lý, giúp nhiều agent lập trình như Claude Code, Codex, Kimi CLI, OpenCode dùng chung một endpoint và chuyển qua lại giữa các nhà cung cấp AI. Bạn cài bằng app desktop, bằng npm hoặc bằng Docker. Cách dễ nhất là tải app, thêm nhà cung cấp, bấm Start rồi áp cấu hình cho agent.
Claude Code Router (viết tắt CCR) là một cổng model chạy ngay trên máy bạn. Các agent AI lập trình như Claude Code, Codex hay OpenCode chỉ cần trỏ vào một địa chỉ cục bộ duy nhất. Còn chuyện gọi model nào, của nhà cung cấp nào, bằng key nào thì bạn quản lý ở một chỗ.
Nếu bạn từng dùng nhiều công cụ AI cùng lúc, bạn sẽ biết cái khổ: mỗi công cụ một file cấu hình, mỗi nơi một API key, đổi nhà cung cấp là phải sửa lại từng chỗ. CCR gom hết vào một ứng dụng. Repo này hợp với lập trình viên dùng nhiều agent, người muốn thử model rẻ hơn hoặc nhanh hơn mà không phải cấu hình lại, và nhóm nhỏ muốn chia key có giới hạn cho từng người.
Điểm đáng giá nhất là bạn không cần gõ nhiều lệnh. Có app desktop với giao diện bấm chuột: thêm nhà cung cấp, bấm Start, chọn agent, xong. Repo hiện có khoảng 38.129 sao và 3.206 fork, dùng giấy phép MIT, viết chủ yếu bằng TypeScript và vẫn đang được cập nhật.
musistudio/claude-code-router
Claude Code Router là cổng model chạy trên máy bạn, để Claude Code, Codex, OpenCode… dùng chung một địa chỉ và đổi nhà cung cấp AI mà không sửa cấu hình.
I.CCR làm được gì
Theo tư liệu của tác giả, CCR là một «control plane» (trung tâm điều khiển) cho các agent. Mình tóm lại theo lợi ích bạn nhận được.
A.Một địa chỉ cho nhiều agent
CCR hỗ trợ Claude Code, Claude Design, Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode, Pi, ZCode, WorkBuddy và các client API tương thích. Tất cả cùng nói chuyện với cổng cục bộ. Bạn không phải nhớ mỗi công cụ cấu hình một kiểu.
B.Đổi nhà cung cấp và model dễ dàng
CCR nối được với nhiều giao thức và nhà cung cấp: OpenAI Chat / Responses, Anthropic Messages, Gemini, OpenRouter, DeepSeek, SiliconFlow, Moonshot, Kimi Code, Mistral, Z.AI, Bailian và các endpoint tự thêm. Muốn thử model khác, bạn đổi trong CCR, không cần sửa file cấu hình của từng agent.
C.Chạy tiếp khi một chỗ bị lỗi
Bạn có thể đặt thử lại (retry), nhóm nhiều key (credential pool), xoay key và danh sách model dự phòng theo thứ tự. Nếu model chính hết hạn mức hoặc lỗi, request được chuyển sang model kế tiếp.
D.Thêm khả năng cho model có sẵn
CCR có Fusion (ví dụ thêm khả năng nhìn ảnh, tìm web), MCP tools và ToolHub. Tư liệu cũng nhắc tới trình duyệt tự động tích hợp, nhập trạng thái đăng nhập từ Chrome, plugin cho cổng và model ảo. Phần này khá sâu, bạn cứ bỏ qua lúc mới dùng.
E.Nhìn thấy chuyện gì đã xảy ra
Mục Logs cho biết request đi tới nhà cung cấp nào, model nào, trạng thái ra sao, mất bao lâu, dùng bao nhiêu token, ước tính chi phí. Khi có lỗi, đây là nơi đầu tiên bạn nên xem.
F.Kiểm soát truy cập và hạn mức
Bạn tạo key riêng cho client của CCR, có thời hạn và giới hạn cục bộ về số request, token và ảnh. Nhờ vậy bạn không phải đưa key gốc của nhà cung cấp cho từng người hay từng công cụ.
G.AgentClaw
Tư liệu có nhắc AgentClaw, một dạng chuyển tiếp agent qua Weixin iLink, WeCom, Slack, Discord, Telegram, LINE, Feishu và DingTalk. README chỉ liệt kê, chưa mô tả cách dùng. Muốn dùng, bạn xem thêm tài liệu trên trang chủ dự án.
II.Cần chuẩn bị gì
Tùy cách cài, bạn cần những thứ sau (chỉ theo tư liệu của repo):
- App desktop: có bản cho macOS (Apple Silicon và Intel), Windows và Linux. README không ghi thêm yêu cầu phần cứng nào.
- CLI qua npm: cần Node.js 22 trở lên. File package.json của repo cũng yêu cầu Node từ 22.
- Docker: README dùng lệnh
npm run docker:compose:up, nên bạn cần có Docker và có thể chạy npm trong thư mục repo. README không nói rõ các yêu cầu khác. - Tài khoản và key: bạn cần ít nhất một nhà cung cấp AI cùng API key của nhà đó, vì CCR chỉ là cổng chuyển tiếp, không tự có model.
- Tự build app: cần Node.js 22+ và chạy
npm ci. Bản Windows phải build trên Windows x64 vì module gốcbetter-sqlite3dành cho Electron.
README không nói gì về GPU. Từ cách mô tả, CCR là cổng chuyển request tới nhà cung cấp mà bạn chọn, nhưng tư liệu không khẳng định về yêu cầu phần cứng, nên mình không đoán.
III.Cài đặt từng bước
Bạn có ba đường: app desktop (README khuyên dùng), CLI qua npm và Docker. Người mới nên chọn app desktop.
- Tải appTải CCR cho hệ điều hành của bạn rồi mở app
- Thêm nhà cung cấpVào Providers, chọn Add Provider, nhập API key và chọn model
- Bật cổngVào Server và bấm Start, cổng nghe ở 127.0.0.1:3456
- Áp cấu hình cho agentVào Agent Config, chọn agent và model rồi áp profile
- Dùng thử và xem logMở agent như bình thường, kiểm tra trong Logs
A.Cách 1: App desktop (khuyên dùng)
README ghi cách này gồm các bước sau, không cần lệnh nào:
- Tải CCR cho macOS, Windows hoặc Linux rồi mở app. Link tải nằm trong README và trang chủ dự án, README không ghi tên file cụ thể.
- Vào Providers → Add Provider. Chọn một preset có sẵn hoặc endpoint tự nhập, điền API key, chọn giao thức và model rồi lưu.
- Vào Server và bấm Start. Cổng model cục bộ mặc định nghe ở
http://127.0.0.1:3456. - Vào Agent Config, chọn agent bạn dùng, chọn model rồi áp profile (apply).
- Mở agent như bình thường. Vào Logs để xem nó đã đi qua nhà cung cấp và model nào.
Chỗ người mới hay vấp là quên bấm Start ở mục Server. Chưa Start thì agent chưa có gì để kết nối.
B.Cách 2: CLI bằng npm
Cách này chạy cùng cổng đó và thêm giao diện quản lý trên trình duyệt, không cần Electron. Bạn cần Node.js 22 trở lên. Mở terminal (Terminal trên macOS/Linux, PowerShell trên Windows) rồi chạy:
npm install -g @musistudio/claude-code-router
ccr uiDòng đầu cài CCR toàn cục để gọi được lệnh ccr ở bất kỳ thư mục nào. Dòng thứ hai mở giao diện quản lý. Sau đó bạn mở http://127.0.0.1:3458 trên trình duyệt và làm theo luồng Providers → Server → Agent Profiles như ở cách 1. Cổng model vẫn nằm ở http://127.0.0.1:3456.
Repo có tài liệu CLI riêng (dịch vụ, xác thực, lệnh profile). README dẫn tới mục «Use the CLI» trên trang chủ dự án.
C.Cách 3: Docker
Cách này dành cho người đã quen Docker. Bạn cần tải mã nguồn về trước, rồi chạy lệnh ở thư mục gốc repo:
git clone https://github.com/musistudio/claude-code-router.git
cd claude-code-router
npm run docker:compose:upTheo README, Docker mở giao diện quản lý và các route của cổng qua http://127.0.0.1:3458 theo mặc định. README cũng nhắc script này chuẩn bị một runtime ai-gateway cục bộ trước khi build image, nếu thư mục ../../next-ai/gateway tồn tại. Nếu bạn chỉ clone riêng repo này thì thư mục đó thường không có, và README không nói điều gì xảy ra khi đó. Hãy đọc hướng dẫn triển khai Docker trên trang chủ trước khi mở CCR ra ngoài internet.
CCR giữ API key của các nhà cung cấp. Chỉ chạy ở 127.0.0.1 trên máy của bạn khi mới thử. Đừng mở cổng ra mạng ngoài nếu chưa đọc hướng dẫn Docker và phần xác thực. Hãy dùng key riêng của CCR có giới hạn cho người khác, không đưa key gốc.
D.Tự build app (cho người muốn đóng gói)
Phần này chỉ cần nếu bạn muốn tự tạo bộ cài từ mã nguồn. Cài Node.js 22+ rồi chạy npm ci ở thư mục repo. Sau đó chọn một lệnh:
npm ci
npm run build:app:mac
npm run build:app:winLệnh build:app:mac tạo DMG/ZIP trên macOS. Lệnh build:app:win tạo bộ cài NSIS trên Windows. Cả hai xuất ra thư mục release-local/. Bạn chạy lệnh nào hợp hệ điều hành của mình, không cần chạy cả hai.
IV.Kiểm tra đã chạy được chưa
Theo README, bạn biết CCR chạy được khi:
- Mục Server đã bấm Start và cổng nghe ở
http://127.0.0.1:3456. - Nếu dùng CLI, trình duyệt mở được
http://127.0.0.1:3458và thấy giao diện quản lý. Nếu dùng Docker, địa chỉ này cũng là nơi quản lý. - Sau khi áp profile cho agent và dùng thử một câu hỏi, mục Logs hiện ra request với nhà cung cấp, model, trạng thái, token và độ trễ đã được xác định.
Cách chắc nhất là Logs. Nếu agent trả lời mà Logs trống, nghĩa là agent chưa đi qua CCR. Hãy quay lại Agent Config và áp profile lại.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo những gì README mô tả. Các bước bấm cụ thể có thể hơi khác theo phiên bản app, nên bạn cứ theo tên mục trong giao diện.
A.Dev dùng nhiều agent, mỗi cái một key
Bạn là lập trình viên, hôm nay dùng Claude Code, mai chuyển sang Codex hay OpenCode. Trước đây mỗi công cụ một cấu hình riêng. Với CCR, bạn thêm nhà cung cấp một lần ở Providers, rồi ở Agent Config áp profile cho từng agent. Muốn đổi model, bạn đổi ở CCR, không mở file cấu hình của agent. Kết quả là các agent cùng dùng một nơi quản lý key và model.
Đổi model ở một chỗ, mọi agent đều theo.
Ông T
B.Thử model rẻ hơn mà không đổi thói quen làm việc
Bạn thấy một nhà cung cấp khác rẻ hơn và muốn thử. Bạn thêm nhà đó trong Providers, chọn model, rồi đổi model trong profile của agent đang dùng. Sau vài ngày, bạn mở Logs xem token và chi phí ước tính để so sánh. Nếu không hợp, đổi lại trong vài cú bấm. Lưu ý chi phí ở Logs là ước tính, hóa đơn thật vẫn nằm ở nhà cung cấp.
C.Tránh gián đoạn khi hết hạn mức
Bạn đang làm dở một việc dài thì model chính báo lỗi hoặc hết hạn mức. Trong mục Routing, bạn đặt retry và danh sách model dự phòng theo thứ tự. Khi model chính lỗi, request chuyển sang model kế tiếp. Nếu có nhiều key của cùng nhà cung cấp, bạn gom vào credential pool để xoay vòng. Điều kiện định tuyến dựa trên header và nội dung request, README ghi vậy nhưng không nêu ví dụ, nên bạn thử dần trên cấu hình nhỏ trước.
D.Chia key cho đồng nghiệp có giới hạn
Bạn là chủ một nhóm nhỏ và muốn đồng nghiệp dùng AI nhưng không muốn đưa key gốc. CCR cho tạo key riêng của CCR, có thời hạn và giới hạn cục bộ về request, token, ảnh. Bạn chạy CCR ở một máy chung (ví dụ bằng Docker), đọc kỹ hướng dẫn bảo mật rồi phát key cho từng người. Mỗi người dùng agent của họ trỏ vào CCR. Bạn theo dõi mức dùng trong Logs.
VI.Lỗi hay gặp và cách xử lý
Tư liệu có mục «Troubleshoot common issues» trên trang chủ dự án. Dưới đây là những lỗi rất dễ gặp với loại công cụ cổng cục bộ này.
A.Agent không đi qua CCR, Logs trống
Thường do chưa bấm Start ở mục Server, hoặc chưa áp profile ở Agent Config. Kiểm tra cả hai, rồi khởi động lại agent để nó đọc cấu hình mới.
B.Gõ ccr báo không tìm thấy lệnh
Có thể bạn chưa cài xong hoặc terminal chưa nhận lệnh mới. Chạy lại npm install -g @musistudio/claude-code-router và mở terminal mới. Hãy kiểm tra Node.js đang là bản 22 trở lên, vì CLI yêu cầu như vậy.
C.Báo lỗi xác thực hoặc 401 từ nhà cung cấp
Thường do API key sai, hết hạn hoặc chọn nhầm giao thức cho nhà cung cấp. Vào Providers, kiểm tra lại key, giao thức và model. README có nhắc tính năng kiểm tra kết nối (connectivity check), bạn nên dùng để thử trước khi áp cho agent.
D.Cổng bị chiếm hoặc không mở được giao diện
Cổng mặc định là 3456 cho cổng model và 3458 cho giao diện CLI/Docker. Nếu chương trình khác đang dùng các cổng này, CCR có thể không khởi động được. Hãy tắt chương trình đó rồi thử lại. README không ghi cách đổi cổng ở đây, nên bạn xem mục cấu hình trên trang chủ dự án.
E.Docker không build được
Script docker:compose:up có bước chuẩn bị runtime ai-gateway cục bộ khi thư mục ../../next-ai/gateway tồn tại. Nếu lỗi xảy ra ở bước này, đọc kỹ thông báo và xem hướng dẫn Docker trên trang chủ. Đừng sửa lung tung các file trong repo khi chưa hiểu.
VII.Có nên dùng không
Điểm mạnh: một nơi quản lý nhiều agent và nhiều nhà cung cấp; có app desktop bấm chuột nên người mới cũng làm được; có dự phòng, xoay key, nhật ký chi tiết và giới hạn hạn mức; giấy phép MIT; dự án còn được cập nhật và có cộng đồng lớn.
Giới hạn: CCR không cung cấp model, bạn vẫn phải có API key hoặc tài khoản ở nhà cung cấp. Số tính năng khá nhiều (Fusion, ToolHub, plugin, AgentClaw), nên lúc đầu dễ rối. Hãy chỉ làm bước cơ bản trước. README viết chủ yếu cho người đã quen agent lập trình, và phần Docker nói đến một thư mục ngoài repo nên không dễ với người mới. Tư liệu cũng chưa nói rõ về hiệu năng hay cách đổi cổng.
Khi nào nên chọn cách khác: nếu bạn chỉ dùng một agent với một nhà cung cấp và không cần đổi, cấu hình trực tiếp có thể đủ đơn giản, không cần thêm một lớp ở giữa. Nếu bạn định mở CCR cho nhiều người qua mạng, hãy đọc kỹ phần bảo mật và Docker trước khi làm.
Với người dùng nhiều agent và muốn bớt việc cấu hình lặp đi lặp lại, CCR là một lựa chọn đáng thử. Bạn bắt đầu bằng app desktop, thêm một nhà cung cấp, áp profile cho một agent và theo dõi Logs.
Câu hỏi thường gặp
Claude Code Router có miễn phí không?
Bản thân CCR dùng giấy phép MIT, và README không nói có thu phí. Tuy vậy bạn vẫn cần API key của nhà cung cấp AI mà bạn chọn, và chi phí gọi model do nhà đó tính. README không có thông tin về gói trả phí của CCR.
Cài CCR có khó không?
Cách dễ nhất là tải app desktop, thêm nhà cung cấp, bấm Start rồi áp profile cho agent, không cần gõ lệnh. Nếu muốn dùng CLI thì chỉ có hai lệnh: cài bằng npm rồi chạy `ccr ui`. Docker thì cần quen công cụ hơn.
Chạy được trên Windows không?
Có. README nói có bản app cho macOS, Windows và Linux, và có lệnh build bộ cài Windows. Riêng việc tự build bản Windows phải làm trên Windows x64.
Có cần GPU không?
README không nói về yêu cầu GPU. CCR được mô tả là cổng chuyển request tới nhà cung cấp bạn chọn, nên tư liệu không cho thấy cần GPU. Chưa có thông tin chính thức về phần cứng tối thiểu.
Dữ liệu và API key của tôi có an toàn không?
CCR chạy cục bộ trên máy bạn và mặc định nghe ở 127.0.0.1. README khuyên đọc hướng dẫn Docker trước khi mở CCR ra ngoài. Tư liệu không có đánh giá bảo mật chi tiết hơn, nên hãy giữ ở máy của bạn và dùng key riêng của CCR có giới hạn khi chia cho người khác.
CCR dùng được với những agent nào?
README liệt kê Claude Code, Claude Design, Codex, Grok CLI, Kimi CLI, Kilo Code, OpenCode, Pi, ZCode, WorkBuddy và các client API tương thích. Mỗi agent có profile riêng trong mục Agent Config.
CCR hỗ trợ những nhà cung cấp nào?
README nêu OpenAI Chat / Responses, Anthropic Messages, Gemini, OpenRouter, DeepSeek, SiliconFlow, Moonshot, Kimi Code, Mistral, Z.AI, Bailian và các nhà cung cấp tương thích tự thêm. Bạn có thể chọn preset có sẵn hoặc nhập endpoint tùy chỉnh.


