ClawRouter

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.

Bắt đầu

export CLAWROUTER_API_KEY="..."openclaw onboard --auth-choice clawrouter-api-keyopenclaw plugins enable clawrouter

openclaw models list --all --provider clawrouter

openclaw models set clawrouter/<provider>/<model>

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à:

Ví dụ, một trình điều khiển triển khai có thể quản lý bản vá JSON5 này:

{  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:

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --jsonopenclaw 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. 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:

# 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:

[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 (<run-id>:model:<n>) 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:<n> 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.

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:

openclaw status --usageopenclaw 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ố

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