レート制限

Gateway は、複数の独立したレート制限を適用します。これらは異なる 境界を保護し、異なる識別情報をキーとし、異なる形式のエラーで失敗します。 このページでは、そのすべてについて説明します。

概要：

認証試行（認証前）

失敗した認証試行は、リクエストが処理される前にクライアント IP ごとに スロットリングされます。これは、外部公開された Gateway に対するブルートフォース攻撃を防ぐ仕組みです。

• カウントされるのは、誤った 認証情報だけです。認証情報がない場合（トークンを 一度も送信していないクライアント）と認証に成功した場合は割り当てを消費しません。 認証に成功すると、その IP のカウンターがリセットされます。
• デフォルト：60秒間に10回失敗すると、その IP は5分間ロックアウトされます。
• デフォルトでは、loopback（127.0.0.1 / ::1）は除外されるため、ローカル CLI セッションが ロックアウトされることはありません。
• カウンターは認証情報クラスごとにスコープ設定されるため、ある対象への大量の試行が 別の対象を圧迫することはありません。スコープには、共有 Gateway トークン/パスワード、デバイストークン、Node ペアリング、ペアリング済み Node の再承認、 デバイスブートストラップトークン、watchOS チャレンジの発行が含まれます。

ロックアウト中、接続試行は次のエラーで失敗します：

{  "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"  }}

ロックアウト中も、他の IP（loopback を含む）からの試行には影響しません。

openclaw.json の gateway.auth.rateLimit で調整します：

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

Gateway ログに AUTH_RATE_LIMITED が繰り返し記録されている場合、誰かが 認証情報を推測しています。公開運用手順書を参照してください。

ブラウザーオリジン接続

ブラウザーの Origin ヘッダーを含む WebSocket 接続には同じ 制限が適用されますが、loopback の除外は常に無効です。ローカルブラウザー内の 悪意のあるページも信頼されていないクライアントであるため、この経路では localhost が 無制限に試行できることはありません。このような接続が loopback アドレス_から_到達した場合、 失敗は共有 loopback IP ではなく、正規化されたページオリジン（例： browser-origin:https://evil.example）をキーとするため、 オリジンごとに独自のバケットが割り当てられます。loopback 以外のアドレスからの場合、 キーは引き続きクライアント IP です。これは設定できません。

Webhook

HTTP /hooks 受信には独自の失敗リミッターがあります。クライアント IP ごとに 60秒間に20回認証に失敗すると、60秒間ロックアウトされます。 loopback は除外されません。フック認証に成功するとカウンターがリセットされます。スロットリングされた リクエストには、Retry-After ヘッダー（秒）を伴うプレーンな HTTP 429 Too Many Requests が 返されます。制限は固定です。正当な連携がこの制限に達する場合は、 再試行を強めるのではなく、認証情報を修正してください。

コントロールプレーンの書き込み（認証後の安全策）

書き込み側の管理 RPC（config.apply、config.patch、plugins.install、 plugins.setEnabled、plugins.uninstall、update.run、worktrees.*、 gateway.restart.request、...）には、認可の後に追加のレート制限が 適用されます。deviceId+clientIp ごと、メソッドごとに、 60秒間に30リクエストです。

これはセキュリティ境界ではありません。呼び出し元はすでに operator.admin を保持しています。 これは、高コストな操作を大量に実行する制御不能なクライアントまたはエージェントのループを 制限するための安全策です。対話的な使用でこの制限に達することはありません。メソッドごとに 独自のバケットがあるため、Plugin の切り替えによって設定書き込みの割り当てが消費されることはありません。

制限を超えると、リクエストは再試行可能なエラーで失敗します：

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

クライアントは retryAfterMs に従う必要があります。制限は固定（設定不可）です。 バケットは自動的に期限切れとなり、Gateway のメンテナンスによって削除されます。

ACP セッション作成

ACP トランスレーターは、トランスレーターインスタンスごとに、10秒間の ウィンドウ内で新規セッションの作成を120件までに制限します。これを超えると、 待機時間をメッセージに含むエラーでリクエストが失敗します（この経路には構造化された retryAfterMs フィールドはありません）：

<method> の ACP セッション作成レート制限を超えました。<n>秒後に再試行してください。

これにより、ループ内でセッションを作成する制御不能なクライアントが制限されます。通常の IDE や エージェントの使用では、この制限を大幅に下回ります。

再起動のクールダウン

Gateway の再起動リクエストは集約された後、再起動サイクル間に30秒の クールダウンが適用されます。クールダウン中に要求された再起動は拒否されず、 クールダウン終了後に実行されるようスケジュールされます。これは上記のコントロールプレーンのリミッターとは 別です。gateway.restart.request はコントロールプレーンの割り当てスロットを消費し、 その結果発生する再起動はクールダウンにも従います。

運用上の注意

• すべてのリミッターはインメモリかつプロセス単位であり、複数の Gateway 間で 状態を共有しません。Gateway プロセスを置き換えると、Gateway が所有する カウンター（認証ロックアウト、Webhook スロットル、コントロールプレーンのバケット）はクリアされます。 再起動のクールダウンは意図的にプロセス内の再起動サイクルをまたいで維持されます。これが スロットリングの対象であり、プロセスの置き換え時にのみリセットされます。ACP セッション上限は そのトランスレーターインスタンスに属し、Gateway の再起動時ではなく、そのインスタンスが 再作成されたときにリセットされます。
• バケットマップには上限（エントリ数のハード上限と定期的な削除）があるため、 一意なキーを大量に送ってもメモリが無制限に増加することはありません。
• クライアントがリバースプロキシの背後にある場合、実効 IP は解決された クライアント IP です。プロキシヘッダーが実効 IP に影響を与える前にどのように検証されるかについては、 信頼済みプロキシ認証を参照してください。
• 再試行の通知方法は対象によって異なります。Gateway RPC リミッターは retryable: true と retryAfterMs を返し、Webhook 受信は Retry-After ヘッダー付きの HTTP 429 を使用し、ACP は待機時間をエラーメッセージに埋め込みます。 いずれの場合も、すぐに再試行せず、指定された期間だけバックオフしてください。