---
read_when:
- Bạn muốn một khóa được quản lý duy nhất cho nhiều nhà cung cấp mô hình
- Bạn cần tính năng khám phá mô hình ClawRouter hoặc báo cáo hạn ngạch trong OpenClaw
summary: Định tuyến các mô hình theo phạm vi thông tin xác thực qua ClawRouter và hiển thị hạn mức được quản lý
title: ClawRouter
x-i18n:
generated_at: "2026-07-12T08:17:12Z"
model: gpt-5.6
postprocess_version: locale-links-v1
provider: openai
source_hash: b9a83253b5de3022bb3d3113427e5183f4ac537161ed75723fec0dafc33ebb00
source_path: providers/clawrouter.md
workflow: 16
---
ClawRouter cung cấp cho OpenClaw một khóa có phạm vi theo chính sách để sử dụng nhiều nhà cung cấp mô hình thượng nguồn. Plugin `clawrouter` đi kèm chỉ khám phá các mô hình được phép đối với khóa đó, định tuyến từng mô hình qua giao thức đã khai báo và báo cáo ngân sách cùng mức sử dụng tổng hợp của khóa trên các giao diện sử dụng của OpenClaw.
Thông tin xác thực thượng nguồn và việc chuyển tiếp dành riêng cho từng nhà cung cấp vẫn nằm trong ClawRouter, vì vậy bạn không bao giờ phải cài đặt hoặc xác thực riêng từng Plugin nhà cung cấp thượng nguồn trên máy chủ OpenClaw. Plugin này được cung cấp kèm OpenClaw (`enabledByDefault: true`); bạn chỉ cần thông tin xác thực ClawRouter đã được cấp.
| Thuộc tính | Giá trị |
| ----------------- | ------------------------------------------------ |
| Nhà cung cấp | `clawrouter` |
| Plugin | đi kèm (được bao gồm trong OpenClaw) |
| Xác thực | `CLAWROUTER_API_KEY` |
| URL mặc định | `https://clawrouter.openclaw.ai` |
| Danh mục mô hình | Theo phạm vi thông tin xác thực qua `/v1/catalog` |
| Hạn mức | Ngân sách và mức sử dụng hằng tháng qua `/v1/usage` |
## Bắt đầu
Yêu cầu quản trị viên ClawRouter cấp thông tin xác thực có chính sách bao gồm
các nhà cung cấp, mô hình và ngân sách hằng tháng mà bạn được phép sử dụng.
Thông tin xác thực chỉ được hiển thị một lần khi cấp.
```bash
export CLAWROUTER_API_KEY="..."
openclaw onboard --auth-choice clawrouter-api-key
openclaw plugins enable clawrouter
```
`clawrouter` được cung cấp kèm và bật theo mặc định. Nếu cấu hình của bạn đặt
`plugins.allow`, hãy thêm `clawrouter` vào danh sách đó trước khi bật. Đối với
bản triển khai tùy chỉnh, hãy đặt `models.providers.clawrouter.baseUrl` thành
địa chỉ gốc của ClawRouter; giá trị mặc định là `https://clawrouter.openclaw.ai`.
```bash
openclaw models list --all --provider clawrouter
```
Hãy sử dụng chính xác các tham chiếu mô hình được trả về như hiển thị. Chúng giữ
nguyên không gian tên thượng nguồn, chẳng hạn như `clawrouter/openai/gpt-5.5`,
`clawrouter/anthropic/claude-sonnet-4-6` hoặc
`clawrouter/google/gemini-3.5-flash`. Nếu `agents.defaults.models` là một
danh sách cho phép trong cấu hình của bạn, hãy thêm từng tham chiếu ClawRouter
đã chọn vào đó.
```bash
openclaw models set clawrouter//
```
Bạn cũng có thể chọn một mô hình được trả về cho một lần chạy bằng
`openclaw agent --model clawrouter// --message "..."`.
## Triển khai không tương tác có quản lý
Giữ khóa proxy trong cơ chế chèn bí mật của khối lượng công việc và chỉ lưu một
SecretRef trong `openclaw.json`. Các trường được quản lý chuẩn là:
| Mục đích | Trường cấu hình hoặc môi trường |
| --------------------- | -------------------------------------------------------------------------- |
| Địa chỉ gốc bộ định tuyến | `models.providers.clawrouter.baseUrl` |
| Thông tin xác thực | `models.providers.clawrouter.apiKey` -> SecretRef môi trường |
| Giá trị bí mật | `CLAWROUTER_API_KEY` trong môi trường tiến trình Gateway |
| Mô hình mặc định | `agents.defaults.model.primary` -> `clawrouter//` |
| Thẻ khối lượng công việc | `models.providers.clawrouter.headers.X-ClawRouter-Project-Id` (không bắt buộc) |
Ví dụ, một trình điều khiển triển khai có thể quản lý bản vá JSON5 này:
```json5
{
plugins: {
entries: { clawrouter: { enabled: true } },
},
models: {
providers: {
clawrouter: {
baseUrl: "https://clawrouter.internal.example",
apiKey: {
source: "env",
provider: "default",
id: "CLAWROUTER_API_KEY",
},
headers: {
"X-ClawRouter-Project-Id": "fakeco",
},
},
},
},
agents: {
defaults: {
model: { primary: "clawrouter/openai/gpt-5.5" },
},
},
}
```
Nếu bản triển khai đặt `plugins.allow`, hãy giữ nguyên các mục hiện có và thêm
`clawrouter`. Xác thực và áp dụng mà không cần trình hướng dẫn tương tác:
```bash
openclaw config patch --file ./clawrouter.patch.json5 --dry-run --json
openclaw config patch --file ./clawrouter.patch.json5
```
Lần chạy thử sẽ phân giải SecretRef nhưng không bao giờ in giá trị của nó. Để
xoay vòng thông tin xác thực, hãy cập nhật Secret bên ngoài cung cấp
`CLAWROUTER_API_KEY` và khởi động lại khối lượng công việc Gateway để tải môi
trường tiến trình mới. Tệp cấu hình và tham chiếu mô hình không thay đổi.
Đối với Gateway Docker độc lập được dựng từ mã nguồn, ClawRouter đã được bao gồm
trong môi trường thời gian chạy gốc. Chỉ chọn Plugin kênh cần được đóng gói riêng,
chẳng hạn như `OPENCLAW_EXTENSIONS=clickclack`, `slack` hoặc `msteams`; xem
[các ảnh được dựng từ mã nguồn với những Plugin đã chọn](/vi/install/docker#source-built-images-with-selected-plugins).
Các bản triển khai dạng kho lưu trữ/thiết bị phải đóng gói cùng mã nguồn đã được
hợp nhất qua quy trình tạo tạo phẩm riêng thay vì sử dụng ảnh OCI.
## Mức sẵn sàng và bằng chứng trực tiếp
Các bước kiểm tra này chứng minh những ranh giới khác nhau; không được dùng bước
này thay cho bước khác:
```bash
# ClawRouter process health only; no credential or upstream model is exercised.
curl -fsS https://clawrouter.internal.example/v1/health
# OpenClaw gateway startup readiness only; no model call is made.
curl -fsS http://127.0.0.1:18789/readyz
# Credential-scoped catalog discovery.
openclaw models list --all --provider clawrouter --json
# Minimal real inference probe through the configured ClawRouter provider.
openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json
# Workload canary using an exact granted model ref.
openclaw agent --agent main \
--model clawrouter/openai/gpt-5.5 \
--message "Reply exactly: CLAWROUTER_CANARY_OK" \
--json
```
Hãy sử dụng một mô hình do danh mục có phạm vi trả về thay vì sao chép ví dụ
một cách máy móc. Phản hồi `/readyz` thành công có nghĩa là Gateway có thể phục
vụ yêu cầu; điều đó không khẳng định ClawRouter, thông tin xác thực của nó hoặc
một nhà cung cấp thượng nguồn đã sẵn sàng. Phép thăm dò mô hình và phép kiểm tra
canary của tác nhân mới là bằng chứng suy luận.
Để chẩn đoán trực tiếp, hãy phát lệnh canary và kiểm tra nhật ký tiêu chuẩn của
Gateway. Chẩn đoán truyền tải mô hình hiện có chỉ chứa siêu dữ liệu sẽ phát ra
các dòng có dạng:
```text
[model-fetch] start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses
[model-fetch] response provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200
```
Plugin gửi các tiêu đề `X-ClawRouter-Client`, `X-ClawRouter-Agent-Id` và
`X-ClawRouter-Session-Id` có giới hạn độ dài khi các mã định danh đó khả dụng.
Plugin cũng ánh xạ `callId` chẩn đoán của lệnh gọi mô hình
(`:model:`) sang `X-Request-ID`, nhờ đó một sự kiện gọi mô hình của
OpenClaw có thể được liên kết với dấu vết kiểm tra chỉ chứa siêu dữ liệu của
ClawRouter. Các giá trị nằm trong giới hạn 128 ký tự của mã yêu cầu sẽ giống
hệt nhau. Các giá trị dài hơn giữ lại hậu tố `:model:` và một hàm băm xác
định để các lệnh gọi riêng biệt vẫn có giới hạn độ dài và có thể liên kết.
Siêu dữ liệu triển khai tĩnh như `X-ClawRouter-Project-Id` có thể được đặt trong
ánh xạ `headers` của nhà cung cấp. Các tiêu đề phân bổ cho tác nhân và phiên giữ
giới hạn riêng là 256 ký tự. Các mã yêu cầu tự động chứa ký tự nằm ngoài tập mã
định danh ASCII của ClawRouter sử dụng cùng dạng xác định có giới hạn.
Các tiêu đề được cấu hình rõ ràng, bao gồm mọi biến thể chữ hoa/chữ thường của
`X-Request-ID`, được ưu tiên hơn giá trị tự động. Chẩn đoán truyền tải ghi lại
siêu dữ liệu định tuyến và phản hồi; không ghi nhật ký thông tin xác thực, mã yêu
cầu, câu lệnh hoặc nội dung hoàn thành. Sự kiện kiểm tra của chính ClawRouter
cung cấp nhà cung cấp thượng nguồn đã chọn và trạng thái lưu giữ nội dung.
## Khám phá mô hình
`GET /v1/catalog` trả về `{ providers: [...] }`, trong đó mỗi mục nhà cung cấp
liệt kê `models[]` riêng (gồm mã định danh thượng nguồn, khả năng và giá) cùng
các tuyến yêu cầu được hỗ trợ. OpenClaw không cung cấp một danh sách cố định thứ
hai gồm các mô hình ClawRouter. Một mô hình trong danh mục được công bố dưới dạng
mô hình OpenClaw khi:
- chính sách của thông tin xác thực cấp quyền cho nhà cung cấp của mô hình;
- mô hình trong danh mục công bố một khả năng LLM được hỗ trợ (`llm.responses`,
`llm.chat`, `llm.messages` hoặc `llm.stream` với tuyến phát luồng tương ứng);
và
- nhà cung cấp cung cấp một tuyến tương ứng cho một trong các phương thức truyền tải bên dưới.
Việc thêm mô hình vào một nhà cung cấp ClawRouter được hỗ trợ không cần bản phát
hành OpenClaw: lần làm mới danh mục tiếp theo (được lưu vào bộ nhớ đệm trong 60
giây cho mỗi phạm vi thông tin xác thực) sẽ khám phá mô hình đó. Mô hình cần một
giao thức truyền dẫn mới thì trước tiên cần được Plugin hỗ trợ.
## Giao thức và Plugin nhà cung cấp
ClawRouter quản lý thông tin xác thực thượng nguồn; danh mục của nó cho OpenClaw
biết cần sử dụng phương thức truyền tải nào, vì vậy bạn không bao giờ phải cài
đặt Plugin xác thực của mọi công ty thượng nguồn.
| Khả năng/tuyến trong danh mục | Phương thức truyền tải OpenClaw |
| ---------------------------------------------------------- | ------------------------------- |
| `llm.responses` (nhà cung cấp tương thích với OpenAI) | `openai-responses` |
| `llm.chat` (nhà cung cấp tương thích với OpenAI) | `openai-completions` |
| `llm.messages` + tuyến `anthropic.messages` | `anthropic-messages` |
| `llm.stream` + tuyến phát luồng `google.generate_content` | `google-generative-ai` |
Plugin cũng áp dụng các chính sách phát lại và lược đồ công cụ tương ứng cho
những họ này (khả năng tương thích lược đồ công cụ OpenAI/DeepSeek/Gemini; các
chính sách phát lại gốc của Anthropic và Google Gemini). Nhà cung cấp trong
danh mục chỉ cung cấp định dạng yêu cầu không được hỗ trợ sẽ chủ ý không được
công bố dưới dạng mô hình văn bản OpenClaw. Hãy chuẩn hóa các nhà cung cấp đó
theo một trong các hợp đồng được hỗ trợ trong ClawRouter thay vì gửi tải trọng
không tương thích.
## Hạn mức và mức sử dụng
Phản hồi `/v1/usage` của ClawRouter cung cấp dữ liệu cho các giao diện mức sử
dụng nhà cung cấp thông thường của OpenClaw: tổng số yêu cầu, token và chi phí,
cùng một cửa sổ ngân sách hằng tháng khi khóa có giới hạn. Các khóa không đo
lường vẫn hiển thị mức sử dụng tổng hợp nhưng không có cửa sổ phần trăm.
Việc tra cứu hạn mức sử dụng cùng khóa có phạm vi như khi khám phá mô hình. Tra
cứu hạn mức thất bại không chặn việc thực thi mô hình.
Kiểm tra ảnh chụp nhanh trực tiếp bằng:
```bash
openclaw status --usage
openclaw models status
```
Cùng ảnh chụp nhanh nhà cung cấp này cũng khả dụng cho `/status` trong cuộc trò
chuyện và giao diện mức sử dụng của OpenClaw. Ngân sách áp dụng cho toàn bộ
chính sách, vì vậy các yêu cầu do một máy khách khác sử dụng cùng chính sách
ClawRouter thực hiện có thể thay đổi tỷ lệ phần trăm còn lại.
## Khắc phục sự cố
| Triệu chứng | Nội dung kiểm tra |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Không có mô hình ClawRouter | Xác nhận Plugin đã được bật và được `plugins.allow` cho phép, sau đó kiểm tra thông tin xác thực còn hoạt động và cấp quyền cho ít nhất một nhà cung cấp sẵn sàng. |
| Thiếu một mô hình ClawRouter đã cấu hình | Kiểm tra khả năng và hỗ trợ tuyến của mô hình trong `/v1/catalog`. Các hợp đồng truyền tải không được hỗ trợ sẽ chủ ý bị lọc. |
| `Unknown model: clawrouter/...` | Thêm chính xác tham chiếu trong danh mục vào `agents.defaults.models` khi ánh xạ cấu hình đó đang được dùng làm danh sách cho phép. |
| `401` hoặc `403` từ danh mục hay mức sử dụng | Cấp lại hoặc điều chỉnh phạm vi thông tin xác thực ClawRouter; OpenClaw không dự phòng bằng khóa của nhà cung cấp thượng nguồn. |
| Lệnh gọi mô hình thất bại sau khi khám phá | Kiểm tra kết nối nhà cung cấp và tình trạng thượng nguồn trong ClawRouter, sau đó thử lại khi trạng thái sẵn sàng đã phục hồi. |
| Mức sử dụng có tổng số nhưng không có phần trăm | Chính sách không được đo lường; hãy thêm ngân sách hằng tháng trong ClawRouter để hiển thị cửa sổ phần trăm. |
## Hành vi bảo mật
- Việc khám phá danh mục chỉ nằm trong phạm vi khóa proxy đã cấu hình và được lưu vào bộ nhớ đệm theo từng phạm vi thông tin xác thực (thư mục tác nhân, thư mục không gian làm việc, mã định danh hồ sơ xác thực và URL cơ sở).
- Khóa proxy chỉ được đính kèm khi gửi yêu cầu; khóa này không được lưu trong siêu dữ liệu mô hình.
- Các giá trị phân bổ nguồn và tương quan yêu cầu tự động được loại bỏ khoảng trắng thừa và bị từ chối nếu chứa ký tự điều khiển trước khi gửi. Giá trị phân bổ nguồn được giới hạn ở 256 ký tự; mã định danh yêu cầu được giới hạn ở 128 ký tự.
- Dữ liệu chẩn đoán truyền tải mô hình chỉ chứa siêu dữ liệu và không bao giờ bao gồm khóa proxy hoặc nội dung mô hình.
- Mã định danh mô hình Anthropic và Gemini gốc chỉ được chuyển đổi thành mã định danh thượng nguồn tương ứng khi gửi yêu cầu.
- Các hàng danh mục không được hỗ trợ hoặc chưa được cấp quyền sẽ bị từ chối theo cơ chế đóng an toàn và không thể được chọn.
## Liên quan
Cấu hình nhà cung cấp và lựa chọn mô hình.
Các giao diện về mức sử dụng và trạng thái của OpenClaw.