Giới hạn tốc độ

Gateway áp dụng một số giới hạn tốc độ độc lập. Chúng bảo vệ các ranh giới khác nhau, dùng các danh tính khác nhau làm khóa và trả về các dạng lỗi khác nhau. Trang này là tài liệu tham chiếu cho tất cả các giới hạn đó.

Tổng quan:

Lần thử xác thực (trước xác thực)

Các lần thử xác thực thất bại bị giới hạn theo từng IP máy khách trước khi xử lý bất kỳ yêu cầu nào. Đây là cơ chế bảo vệ chống vét cạn cho các Gateway được công khai.

• Chỉ thông tin xác thực sai mới được tính. Thông tin xác thực bị thiếu (máy khách chưa từng gửi token) và các lần xác thực thành công không tiêu tốn hạn mức; một lần xác thực thành công sẽ đặt lại bộ đếm cho IP đó.
• Mặc định: 10 lần thất bại trong mỗi 60 giây, sau đó khóa IP đó trong 5 phút.
• Loopback (127.0.0.1 / ::1) được miễn theo mặc định để các phiên CLI cục bộ không thể bị khóa.
• Các bộ đếm được phân phạm vi theo từng lớp thông tin xác thực, vì vậy lưu lượng dồn dập nhắm vào một bề mặt không chiếm chỗ của bề mặt khác. Các phạm vi bao gồm token/mật khẩu Gateway dùng chung, token thiết bị, ghép nối Node, phê duyệt lại Node đã ghép nối, token khởi tạo thiết bị và việc phát hành thử thách watchOS.

Trong thời gian bị khóa, các lần thử kết nối thất bại với:

{  "code": "INVALID_REQUEST",  "message": "unauthorized: too many failed authentication attempts (retry later)",  "retryable": true,  "retryAfterMs": 297000,  "details": {    "code": "AUTH_RATE_LIMITED",    "authReason": "rate_limited",    "recommendedNextStep": "wait_then_retry"  }}

Các lần thử từ những IP khác (bao gồm loopback) không bị ảnh hưởng trong thời gian khóa.

Điều chỉnh tại gateway.auth.rateLimit trong openclaw.json:

{  "gateway": {    "auth": {      "rateLimit": {        "maxAttempts": 10,        "windowMs": 60000,        "lockoutMs": 300000,        "exemptLoopback": true      }    }  }}

Các mục AUTH_RATE_LIMITED lặp lại trong nhật ký Gateway có nghĩa là ai đó đang đoán thông tin xác thực; xem cẩm nang xử lý phơi lộ.

Kết nối từ trình duyệt

Các kết nối WebSocket mang tiêu đề Origin của trình duyệt sử dụng cùng các giới hạn nhưng chế độ miễn loopback luôn tắt — một trang độc hại trong trình duyệt cục bộ vẫn là máy khách không đáng tin cậy, vì vậy localhost không được miễn trừ trên đường dẫn đó. Khi kết nối như vậy đến từ một địa chỉ loopback, các lần thất bại của nó được khóa theo nguồn gốc trang đã chuẩn hóa (ví dụ: browser-origin:https://evil.example) thay vì IP loopback dùng chung, vì vậy mỗi nguồn gốc có một nhóm hạn mức riêng; từ các địa chỉ không phải loopback, khóa vẫn là IP máy khách. Không thể cấu hình hành vi này.

Webhook

Đầu vào HTTP /hooks có bộ giới hạn thất bại riêng: 20 lần xác thực thất bại trong mỗi 60 giây cho mỗi IP máy khách, sau đó khóa 60 giây. Loopback không được miễn. Xác thực hook thành công sẽ đặt lại bộ đếm. Các yêu cầu bị giới hạn nhận HTTP 429 Too Many Requests dạng văn bản thuần với tiêu đề Retry-After (giây). Các giới hạn là cố định; nếu một tích hợp hợp lệ chạm ngưỡng này, hãy sửa thông tin xác thực thay vì thử lại dồn dập hơn.

Lệnh ghi trên mặt phẳng điều khiển (cơ chế dự phòng sau xác thực)

Các RPC quản trị phía ghi (config.apply, config.patch, plugins.install, plugins.setEnabled, plugins.uninstall, update.run, worktrees.*, gateway.restart.request, ...) còn bị giới hạn tốc độ bổ sung sau khi ủy quyền: 30 yêu cầu trong mỗi 60 giây, cho mỗi phương thức, cho mỗi deviceId+clientIp.

Đây không phải là ranh giới bảo mật — các bên gọi đã có operator.admin — mà là cơ chế dự phòng nhằm giới hạn các vòng lặp máy khách hoặc tác tử mất kiểm soát liên tục gọi các thao tác tốn kém. Việc sử dụng tương tác không bao giờ chạm ngưỡng này; mỗi phương thức có nhóm hạn mức riêng, vì vậy việc bật/tắt một Plugin không tiêu tốn hạn mức của các lệnh ghi cấu hình.

Khi vượt ngưỡng, yêu cầu thất bại với lỗi có thể thử lại:

{  "code": "UNAVAILABLE",  "message": "rate limit exceeded for config.patch; retry after 35s",  "retryable": true,  "retryAfterMs": 34539,  "details": { "method": "config.patch", "limit": "30 per 60s" }}

Máy khách nên tuân thủ retryAfterMs. Giới hạn là cố định (không thể cấu hình); các nhóm hạn mức tự hết hạn và được tác vụ bảo trì Gateway dọn dẹp.

Tạo phiên ACP

Trình chuyển đổi ACP giới hạn việc tạo phiên ở mức 120 phiên mới trong mỗi khoảng 10 giây cho mỗi thực thể trình chuyển đổi. Việc vượt ngưỡng khiến yêu cầu thất bại với một lỗi có thông báo chứa thời gian chờ (không có trường retryAfterMs có cấu trúc trên đường dẫn này):

Đã vượt quá giới hạn tốc độ tạo phiên ACP cho <method>; hãy thử lại sau <n> giây.

Điều này giới hạn các máy khách mất kiểm soát tạo phiên trong vòng lặp; việc sử dụng IDE và tác tử thông thường luôn thấp hơn nhiều so với ngưỡng này.

Thời gian chờ khởi động lại

Các yêu cầu khởi động lại Gateway được gộp lại, sau đó áp dụng thời gian chờ 30 giây giữa các chu kỳ khởi động lại. Yêu cầu khởi động lại trong thời gian chờ sẽ được lên lịch sau khi thời gian đó kết thúc thay vì bị từ chối. Cơ chế này tách biệt với bộ giới hạn mặt phẳng điều khiển ở trên: gateway.restart.request tiêu tốn một vị trí trong hạn mức mặt phẳng điều khiển và lần khởi động lại phát sinh phải tuân theo thời gian chờ.

Ghi chú vận hành

• Tất cả bộ giới hạn đều nằm trong bộ nhớ và áp dụng cho từng tiến trình; nhiều Gateway không chia sẻ trạng thái. Việc thay thế tiến trình Gateway sẽ xóa các bộ đếm do Gateway sở hữu (khóa xác thực, giới hạn Webhook, các nhóm hạn mức mặt phẳng điều khiển). Thời gian chờ khởi động lại được thiết kế để tồn tại qua các chu kỳ khởi động lại trong tiến trình — đó chính là đối tượng mà nó giới hạn — và chỉ được đặt lại cùng tiến trình. Giới hạn phiên ACP thuộc về thực thể trình chuyển đổi của nó và được đặt lại khi thực thể đó được tạo lại, không phải khi Gateway khởi động lại.
• Các ánh xạ nhóm hạn mức có giới hạn (giới hạn cứng về số mục cùng với việc dọn dẹp định kỳ), vì vậy lưu lượng dồn dập với các khóa duy nhất không thể làm bộ nhớ tăng vô hạn.
• Khi máy khách ở sau proxy ngược, IP hiệu lực là IP máy khách đã phân giải; xem xác thực proxy đáng tin cậy để biết cách các tiêu đề proxy được xác thực trước khi có thể ảnh hưởng đến IP đó.
• Tín hiệu thử lại khác nhau tùy bề mặt: các bộ giới hạn RPC của Gateway trả về retryable: true cùng với retryAfterMs, đầu vào Webhook sử dụng HTTP 429 với tiêu đề Retry-After, còn ACP nhúng thời gian chờ vào thông báo lỗi. Trong mọi trường hợp, hãy chờ theo khoảng thời gian được chỉ định thay vì thử lại ngay lập tức.