Claude Code Router — định tuyến Claude Code đến bất kỳ mô hình nào hoặc bỏ qua router hoàn toàn

Hầu hết người tìm kiếm Claude Code Router muốn một trong hai điều khác nhau: định tuyến Claude Code qua nhiều nhà cung cấp mô hình, hoặc chỉ chạy Claude Code ở nơi rẻ hơn giá niêm yết của Anthropic. Chỉ nhu cầu đầu tiên mới cần router. Claude Code vốn đọc ANTHROPIC_BASE_URL, vì vậy nhu cầu thứ hai chỉ cần ba biến môi trường và hoàn toàn không cần phần mềm bổ sung.

Hướng dẫn này bao quát cả hai cách, với tên biến chính xác, lỗi thông tin xác thực tạo ra 401 âm thầm và danh sách rõ ràng về những gì ngừng hoạt động phía sau bất kỳ gateway nào. Nếu gần đây bạn đã đọc một bài viết khác về CCR, trước tiên hãy chuyển đến Tùy chọn B: config.json mà các bài viết đó yêu cầu bạn chỉnh sửa không còn là cấu hình mà router đọc nữa.

Bạn thực sự cần lựa chọn nào?

Router là một dịch vụ cục bộ: thêm một tiến trình cần chạy, cấu hình và duy trì — và tính đến năm 2026, là một ứng dụng máy tính có giao diện riêng thay vì một tệp để chỉnh sửa. Chi phí đó xứng đáng khi bạn thực sự cần định tuyến đa nhà cung cấp, hạch toán theo từng yêu cầu hoặc lựa chọn mô hình ở cấp subagent. Nếu chỉ cần base URL là đủ thì không.

Tùy chọn A — thay đổi base URL (không cần cài đặt)

Kunavo cung cấp Anthropic Messages API gốc tại /v1/messages, là endpoint mà Claude Code gọi. Hãy trỏ đến đó:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL chỉ là Origin — Claude Code tự thêm /v1/messages, vì vậy không được thêm đường dẫn. Giữ lại các dòng mô hình: mô hình mặc định tích hợp của Claude Code và bí danh opus đều trỏ đến Opus mới nhất, và nếu Kunavo chưa cung cấp mô hình đó, yêu cầu đầu tiên sẽ trả về lỗi 404. Bí danh sonnet yêu cầu Sonnet 5.5, mô hình Kunavo không cung cấp, vì vậy nếu không có dòng ANTHROPIC_DEFAULT_SONNET_MODEL thì /model sonnet, giai đoạn thực thi của opusplan và mọi subagent được đặt thành model: sonnet đều trả về lỗi 404. Bí danh opus được cố định thành Opus 5.5 (claude-opus-5-5), yêu cầu Claude Code v2.1.280 hoặc mới hơn — chạy claude update nếu bản của bạn cũ hơn. Lấy khóa từ bảng điều khiển sau khi đăng ký và nạp $10; khóa chỉ được hiển thị một lần.

Biến thông tin xác thực nào — và tại sao điều đó quan trọng

Claude Code gửi hai biến thông tin xác thực trong các tiêu đề HTTP khác nhau, và khóa nằm trong tiêu đề mà máy chủ không đọc sẽ thất bại với 401:

Ưu tiên ANTHROPIC_AUTH_TOKEN vì một lý do cụ thể: ANTHROPIC_API_KEY cần được phê duyệt một lần trong phiên tương tác, và khóa đã bị từ chối một lần sẽ bị bỏ qua về sau mà không có lời nhắc — một lỗi khó hiểu khi biến đã được đặt rõ ràng nhưng rõ ràng không được sử dụng. Trên Kunavo, tính năng khám phá mô hình không quyết định điều này. Tính năng khám phá mô hình gateway của Claude Code chỉ gửi token bearer khi đã đặt ANTHROPIC_AUTH_TOKEN, và nếu không thì dùng x-api-key; endpoint /v1/models của Kunavo đọc khóa từ cả hai tiêu đề.

Lưu cấu hình cố định

Việc export từ shell chỉ áp dụng cho terminal đó và mọi thứ được khởi chạy từ terminal đó — trình soạn thảo mở từ dock sẽ không thấy chúng, các agent chạy nền cũng vậy. Hãy đặt các giá trị trong tệp cài đặt để áp dụng cho mọi thứ:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Dùng ~/.claude/settings.json cho tất cả dự án. Không bao giờ đặt khóa trong .claude/settings.json của dự án — tệp đó sẽ được commit.

Xác minh trước khi tin tưởng

Trước tiên hãy kiểm thử trực tiếp endpoint, để khi thất bại bạn biết vấn đề nằm ở cấu hình chứ không phải Claude Code:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Sau đó khởi động claude từ cùng shell và chạy /status. Một dòng Anthropic base URL hiển thị api.kunavo.com và một dòng Auth token nêu tên biến của bạn xác nhận cả hai phần đang hoạt động.

Đặt mô hình tùy chỉnh — chọn slug một cách rõ ràng

Kunavo phân giải slug mô hình bằng đối sánh chính xác và không tạo bí danh cho tên có hậu tố ngày, vì vậy claude-sonnet-4-5-20250929 trả về 404 trong khi claude-sonnet-5 thành công. Luôn đặt ANTHROPIC_MODEL thay vì dựa vào mặc định tích hợp:

Các biến bí danh cho phép định tuyến theo từng tác vụ mà không cần bộ định tuyến: ANTHROPIC_DEFAULT_OPUS_MODEL dùng cho bí danh opus và chế độ lập kế hoạch, ANTHROPIC_DEFAULT_SONNET_MODEL dùng cho sonnet và giai đoạn thực thi của opusplan, còn ANTHROPIC_DEFAULT_HAIKU_MODEL dùng cho haiku cùng các tác vụ chạy nền của Claude Code như tạo phần tóm tắt và tiêu đề. Khi dùng Kunavo, hai thiết lập sau là bắt buộc, vì nếu không cố định, chúng sẽ yêu cầu những model ID mà Kunavo không cung cấp (Sonnet 5.5 và Haiku 5.5 từ v2.1.293): đặt biến Haiku thành claude-haiku-4-5 để các tác vụ chạy nền đó cũng không dùng mô hình chính. (ANTHROPIC_SMALL_FAST_MODEL là cách viết cũ của cùng một thiết lập.)

Tùy chọn: hiển thị mọi mô hình trong bộ chọn

Đặt CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129+) và Claude Code sẽ truy vấn GET /v1/models khi khởi động, thêm những gì tìm thấy vào bộ chọn /model có nhãn Từ gateway. Kunavo cung cấp endpoint đó, vì vậy mọi mô hình Claude được bật đều xuất hiện và /model trở thành menu trực tiếp thay vì danh sách bạn phải tự duy trì. Cả hai biến thông tin xác thực đều dùng được cho tính năng này — xem phần trên.

Tùy chọn B — claude-code-router, theo đúng cách nó hiện hoạt động

Hãy bắt đầu từ đây, vì gần như mọi nội dung viết về CCR đều mô tả một phiên bản không còn tồn tại. Router từng là một tệp JSON và lệnh ccr code. Hiện nay nó là một control plane cục bộ với ứng dụng máy tính, giao diện quản lý, nhật ký yêu cầu và gateway mô hình — và config.json mà mọi hướng dẫn đều hiển thị không còn cấu hình cho nó nữa.

CCR lưu cấu hình thời gian chạy trong ~/.claude-code-router/config.sqlite (%APPDATA%\claude-code-router\config.sqlite trên Windows). Một config.json cũ được đọc một lần, làm nguồn di chuyển, khi chưa tồn tại cấu hình SQLite. Sau lần chạy đầu tiên, chỉnh sửa tệp đó không ảnh hưởng đến cấu hình đang chạy — không có lỗi và cũng không có cảnh báo. Khối Providers mà bạn đã cẩn thận dán vào đơn giản không phải là cấu hình.

Điều đó bao gồm cả trang này trước ngày 2026-09-06: đoạn JSON từng nằm ở đây là sai, và đó là kiểu sai khiến bạn mất cả buổi chiều vì không có gì cho biết nó đã bị bỏ qua. Hiện cấu hình được thực hiện trong giao diện (hoặc để sao lưu, dùng Settings → Export data — không sao chép các tệp SQLite đang hoạt động khi CCR đang chạy).

Cài đặt và khởi chạy

CCR được cung cấp theo hai cách: ứng dụng máy tính từ GitHub Releases (khay hệ thống, tự động cập nhật, tích hợp máy tính) và npm CLI cho các triển khai không giao diện hoặc được giám sát. Cả hai dùng chung một thư mục cấu hình.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Thêm Kunavo gồm một mục nhà cung cấp — Providers → Add provider, preset Other / custom API endpoint, endpoint https://api.kunavo.com, khóa sk-kn- của bạn — và một profile Agent Config → Add profile → Claude Code. Phiên bản hướng dẫn theo từng trường, bao gồm Check Connection và khám phá mô hình, có trên trang tích hợp Claude Code Router. Phần còn lại của mục này đề cập những điều trang đó không bao quát: thông tin xác thực, chi phí và các chế độ lỗi.

Ba thông tin xác thực và lỗi 401 liên quan đến thông tin nào

Đây là nguyên nhân phổ biến nhất khiến một thiết lập đang hoạt động trông như bị hỏng. CCR có ba bí mật riêng biệt và chúng xác thực ba chặng khác nhau:

Cặp cổng cũng thường gây nhầm lẫn: cổng quản lý mặc định là 127.0.0.1:3458 còn gateway mô hình là 127.0.0.1:3456. Base URL trỏ đến 3458 sẽ đến giao diện, không phải gateway. (Docker cố ý gộp cả hai phía sau một endpoint Nginx, nên hướng dẫn Docker trông khác.) Giao diện truy cập được không đồng nghĩa gateway hoạt động: hãy kiểm tra /health trên địa chỉ gateway và xác nhận Server hiển thị Running.

Bản đồ theo từng cấp mới là điểm mấu chốt

Claude Code không yêu cầu một mô hình, mà yêu cầu một cấp — vòng lặp chính cần Sonnet hoặc Opus, còn công việc nền (subagent, tìm kiếm, tóm tắt, tiêu đề cuộc trò chuyện) cần mô hình nhỏ và nhanh. Một profile Claude Code trong Agent Config hiển thị chúng dưới dạng các trường riêng: Model mặc định cùng các ghi đè tùy chọn Fable, Opus, Sonnet và Haiku, mỗi trường nhận một giá trị Provider/model. Để trống một cấp thì Claude Code sẽ chọn cấp đó.

Hãy đọc bảng đó trước khi sao chép sơ đồ phân hạng của người khác, vì sự phân tách rõ ràng là đòn bẩy đầu tiên: claude-sonnet-5 rẻ hơn 50% so với claude-opus-5-5 trên Kunavo ($1,40 / $7,00 so với $2,80 / ). Đòn bẩy thứ hai là hạng Haiku: ở mức $0,70 / $3,50, mô hình này rẻ hơn 2 lần so với Sonnet 5, đồng thời xử lý khối lượng bạn không nhìn thấy — mọi subagent, mọi lượt phân loại tệp và mọi tiêu đề được tạo. claude-sonnet-4-6 không còn là Sonnet giá rẻ: ở mức $2,10 / $10,50, nó đắt hơn Sonnet 5 50%, đó là lý do các đoạn mã ở trên đặt ANTHROPIC_MODEL=claude-sonnet-5.

Định tuyến subagent — điều mà bản đồ cấp không thể làm

Các ghi đè cấp ghim mọi subagent vào một mô hình. CCR có thể tinh chỉnh hơn: khi một yêu cầu Claude Code khớp với route tích hợp, nó chèn danh sách các mô hình khả dụng vào phần mô tả công cụ Agent / Task, và Claude Code thêm tiền tố vào prompt của mỗi agent được tạo bằng một thẻ nêu tên mô hình mà agent muốn dùng:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR loại bỏ thẻ và định tuyến yêu cầu đó tương ứng, vì vậy subagent tìm kiếm có thể chạy trên Haiku trong khi subagent đánh giá chạy trên Opus, được chọn theo từng tác vụ thay vì bị ghim. Công tắc này rất dễ bỏ sót: cơ chế bị tắt cho đến khi ít nhất một mô hình có Mô tả trên trang Models. Nếu không có mô tả, CCR không chèn gì và mọi subagent âm thầm quay về mặc định của profile. Hãy viết mô tả theo mức phù hợp với tác vụ — “tìm kiếm mã, phân loại tệp, subagent song song giá rẻ” cho Haiku, “phân tích kiến trúc, đánh giá rủi ro cao” cho Opus. Khi hoạt động, nhật ký yêu cầu hiển thị builtin:claude-code-subagent làm lý do định tuyến.

Lựa chọn giao thức và chi phí phải trả về bộ nhớ đệm

CCR thăm dò endpoint và chọn giao thức truyền. Cung cấp origin thuần https://api.kunavo.com thì nó dùng Anthropic Messages; cung cấp https://api.kunavo.com/v1 thì nó dùng định dạng tương thích OpenAI. Cả hai bề mặt đều hoạt động với cùng một khóa và bạn có thể ghi đè tính năng tự phát hiện trong Advanced settings.

Ưu tiên dạng Anthropic Messages. Dạng này giữ cache_control trong quá trình truyền, để tính năng lưu bộ nhớ đệm prompt đến được mô hình và input được lưu trong bộ nhớ đệm chỉ tính bằng 10% mức giá input (cách hoạt động) — trên một vòng lặp agent gửi lại tiền tố ổn định ở mỗi bước, đây là khoản tiết kiệm đơn lẻ lớn nhất hiện có. Cần nói rõ rằng router trên đường đi vẫn chỉnh sửa các yêu cầu: CCR loại bỏ thông báo hệ thống tiêu đề thanh toán mà Claude Code chèn vào và thêm danh sách mô hình vào phần mô tả công cụ khi bật định tuyến subagent. Cả hai nằm trước các điểm ngắt bộ nhớ đệm của bạn, vì vậy mỗi thay đổi đối với nội dung đó gây ra một lần bỏ lỡ bộ nhớ đệm trong khi tiền tố mới được làm nóng. Sau đó nội dung ổn định — nhưng đây là lý do thực tế khiến Tùy chọn A lưu bộ nhớ đệm tốt hơn đôi chút so với Tùy chọn B, bên cạnh việc dễ vận hành hơn.

Tuy vậy, ở dạng tương thích OpenAI, tính năng lưu bộ nhớ đệm prompt vẫn đến được mô hình. Với prompt dài, Kunavo tự đặt các điểm ngắt bộ nhớ đệm trên tuyến đó: trên prompt hệ thống, trên các định nghĩa công cụ và trên tin nhắn cuối cùng khi cuộc trò chuyện đã có lượt trả lời của trợ lý. cache_control đi kèm một tin nhắn hoặc một định nghĩa công cụ được giữ nguyên.

Dự phòng: thử lại so với chuyển đổi dự phòng

Mục Default on failure trên trang Routing đáng được thiết lập trước khi bạn cần đến. Retry gửi lại đến cùng mô hình khi gặp 408, 409, 429 và 5xx, tuân theo Retry-After và nếu không có thì lùi theo cấp số nhân từ 1s đến tối đa 30s. Fallback targets duyệt danh sách mô hình dự phòng theo thứ tự và kích hoạt khi gặp bất kỳ 4xx hoặc 5xx nào, với giả định rằng mô hình không tồn tại hoặc nhà cung cấp từ chối có thể chỉ ảnh hưởng đến mục tiêu hiện tại. Các quy tắc riêng có thể ghi đè cài đặt toàn cục. Khi chạy dự phòng, phản hồi chứa x-ccr-fallback-attempts và x-ccr-fallback-model để bạn có thể xác định sau đó.

Xác minh nó thực sự nằm trong đường đi

Khởi chạy Claude Code từ profile, gửi một tin nhắn, sau đó mở Request logs trong CCR. Hàng đó hiển thị request model (những gì Claude Code yêu cầu), resolved provider và resolved model (yêu cầu đã đi đâu) — bộ ba này là bằng chứng. Trong CLI, /model liệt kê các mô hình CCR cung cấp. Nếu Claude Code trả lời nhưng không xuất hiện hàng nhật ký, bạn đã tự khởi động Claude Code thay vì thông qua CCR, và phạm vi của profile là Only opened from CCR.

Một phiên lập trình tốn bao nhiêu

Claude Code gửi lại system prompt, cuộc trò chuyện và ngữ cảnh tệp mới ở mỗi bước, vì vậy mức giá theo token nhanh chóng cộng dồn. Theo mức giá Kunavo trên claude-sonnet-5:

Con số đó thấp hơn khoảng 30% trên mô hình chính, trước khi tính lưu bộ nhớ đệm prompt. Mức giá đầy đủ có trong hướng dẫn định giá Claude API, còn trình tính chi phí sử dụng số lượng token của chính bạn.

Điều vẫn hoạt động — và điều không hoạt động

Việc trỏ Claude Code đến bất kỳ gateway nào sẽ thay đổi một vài thứ. Danh sách ngắn và đáng biết trước khi bạn cam kết:

Ở dòng cuối cùng đó: đếm token là endpoint duy nhất mà đặc tả gateway của chính Anthropic đánh dấu là tùy chọn, và Claude Code sẽ ước tính mức sử dụng ngữ cảnh cục bộ khi endpoint này không có. Hiện Kunavo không cung cấp /v1/messages/count_tokens, vì vậy con số /context của bạn là ước tính chứ không phải số đếm chính xác. Ngoài con số đó, không có gì suy giảm — tính năng tự động nén và chính phiên làm việc vẫn không bị ảnh hưởng.

Khắc phục sự cố

Đường dẫn base URL

…và khi router nằm trên đường dẫn

Các cách khắc phục theo từng lỗi cho chính API nằm trong các trang khắc phục sự cố khóa API không hợp lệ và giới hạn tốc độ.

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