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 bề mặt hiển thị mức 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 từng Plugin nhà cung cấp thượng nguồn trên máy chủ OpenClaw. Plugin được đóng gói cùng 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 tải 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ụ, bộ đ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 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ử phân giải SecretRef nhưng không bao giờ in giá trị của nó. Để luân chuyển 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 tải 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 xây dựng từ mã nguồn, ClawRouter đã được bao gồm trong runtime gốc. Chỉ chọn Plugin kênh cần đóng gói riêng, chẳng hạn như OPENCLAW_EXTENSIONS=clickclack, slack hoặc msteams; xem các image được xây dựng từ mã nguồn với những Plugin đã chọn. Các triển khai dạng kho lưu trữ/thiết bị phải đóng gói cùng mã nguồn đã được đưa vào thông qua Pipeline tạo sản phẩm riêng thay vì sử dụng image 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 thay thế bước này bằng bước khác:

# Chỉ kiểm tra tình trạng tiến trình ClawRouter; không sử dụng thông tin xác thực hoặc mô hình thượng nguồn.curl -fsS https://clawrouter.internal.example/v1/health # Chỉ kiểm tra mức độ sẵn sàng khi khởi động Gateway OpenClaw; không thực hiện lệnh gọi mô hình.curl -fsS http://127.0.0.1:18789/readyz # Khám phá danh mục theo phạm vi thông tin xác thực.openclaw models list --all --provider clawrouter --json # Phép thăm dò suy luận thực tối thiểu qua nhà cung cấp ClawRouter đã cấu hình.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Bản canary tải công việc sử dụng chính xác tham chiếu mô hình được cấp quyền.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Chỉ trả lời chính xác: CLAWROUTER_CANARY_OK" \  --json

Hãy sử dụng một mô hình được danh mục có phạm vi trả về thay vì sao chép máy móc mô hình ví dụ. 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à canary tác tử là các bằng chứng suy luận.

Để chẩn đoán trực tiếp, hãy gửi 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 phát ra các dòng có dạng:

[model-fetch] bắt đầu provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] phản hồi provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

Plugin gửi các header 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 (<run-id>:model:<n>) của lệnh gọi mô hình sang X-Request-ID, nhờ đó một sự kiện gọi mô hình 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 mã yêu cầu 128 ký tự thì 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 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 header phân bổ tác tử và phiên giữ nguyên giới hạn riêng là 256 ký tự. Mã yêu cầu tự động chứa các ký tự 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 header đượ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 các 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, prompt hoặc nội dung hoàn thành. Sự kiện kiểm tra riêng của 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ã 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 danh sách mô hình ClawRouter cố định thứ hai. Một mô hình trong danh mục được công bố là 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 truyền trực tiếp 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 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 giao thức truyền mới thì trước tiên phải được Plugin hỗ trợ.

Plugin giao thức và 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 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 từng 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/Perplexity; các chính sách phát lại gốc của Anthropic và Google Gemini). Các mô hình Perplexity được viết lại lược đồ nghiêm ngặt: patternProperties và additionalProperties bị loại bỏ và mọi lược đồ đối tượng đều khai báo properties, vì Perplexity từ chối các lược đồ công cụ không có chúng. Nhà cung cấp trong danh mục chỉ cung cấp một định dạng yêu cầu không được hỗ trợ sẽ chủ ý không được công bố là 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 payload 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 bề mặt hiển thị 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 với 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 mà không có cửa sổ phần trăm.

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 trạng thái trực tiếp bằng:

openclaw status --usageopenclaw models status

Ảnh chụp trạng thái nhà cung cấp tương tự có sẵn 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 thực hiện bằng cùng chính sách ClawRouter 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 được giới hạn theo 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, id 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ị ghi nhận nguồn và tương quan yêu cầu tự động được cắt bỏ khoảng trắng, đồng thời bị từ chối nếu chứa ký tự điều khiển trước khi gửi. Giá trị ghi nhận nguồn được giới hạn ở 256 ký tự; id yêu cầu được giới hạn ở 128 ký tự.
• Thông tin chẩn đoán lớp 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.
• Các id mô hình Anthropic và Gemini gốc chỉ được viết lại thành id 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ẽ từ chối theo mặc định và không thể được chọn.

Liên quan