2026 OpenClaw ゲートウェイ冪等キーとリクエスト重複排除（クラウド Mac mini）

エージェントゲートウェイは少なくとも一度届く世界を前提にし、冪等キーが無いと課金やファイル書き込みが二重化して顧客信頼を壊します。2026 年の OpenClaw では副作用の手前に Redis ベースの原子ロックとリプレイ封筒を置きます。JSON Schema ゲートウェイ検証、nginx ローリングドレイン、429 と Retry-After、読取タイムアウト診断 と併せて以下の実装詳細を進めてください。

キー正規化

Idempotency-Key ヘッダまたは JSON の idempotency_key を唯一の契約にします。base64url デコード後のエントロピーが 16 バイト未満なら拒否し、総当たりを防ぎます。ワイヤ長は 128 ASCII 文字を上限にし、ログと LB を守ります。正規化後に SHA-256 を取り、Redis フィールド名に使うとプライバシと安定性が両立します。タプル (tenant_id, route_id, key_hash, schema_version) を必須にし、スキーマ更新時は意図的に旧リプレイを失効させます。

Redis と Lua

初回 SET ... NX EX 172800 が成功したワーカーのみが上流を呼びます。失敗側は封筒を読み返すだけです。夜間バッチが三日目まで合法なら 259200 秒へ延長し、メモリ監視を更新します。

-- 擬似 Lua
if redis.call('SET', key..':claim', pid, 'NX', 'EX', 172800) then
  return 'execute'
else
  return redis.call('GET', key..':envelope')
end

トポロジ比較

方式	利点	欠点	用途
プロセス LRU	超低遅延	分裂脳	ローカル検証
Redis クラスタ	TTL と NX が成熟	ホットキー	本番標準
SQL ロック	監査向き	遅延増	金融規制
etcd リース	メッシュ連携	運用コスト	mesh 導入済み

TTL 172800/259200 秒

48 時間は決済系 API の慣例に一致します。72 時間は週末跨ぎの照合に余裕を持たせます。期限切れ後は新規操作として扱い、SDK はユーザー操作に応じてキーを回転させます。SLA 文書の文言と Redis の EX を一致させ、監査ログにハッシュを残します。

リプレイ封筒

HTTP ステータス、再送可能なヘッダ部分集合、本文の BLAKE3 または SHA-256 を格納します。1 MiB を超える本文はオブジェクトストアに退避し、Redis にはポインタのみを載せます。ストリーミング応答ではチャンク番号を封筒に含め、部分完了を誤認しないようにします。チェックサム不一致率が 0.01% を十分間超えたら重大インシデント扱いで圧縮層やシリアライズ版を疑います。

nginx 連携

TLS 終端でヘッダを正規化し、内部ヘッダにハッシュ派生値を載せ替えます。proxy_read_timeout はゲートウェイの上流予算よりわずかに長くし、ハング診断 の推奨値と揃えます。ドレイン中も Redis エンドポイントを固定し、スリーピークライアントの遅延フラッシュでもキーが失われないようにします。

チェックリスト

1. 変更系ルートを棚卸しし requires_idempotency を付与する。
2. SDK は既定で UUIDv4 を発行し、22 文字未満の手入力キーを拒否する。
3. 本番 Redis は主シャード 3 以上、AOF は everysec を選ぶ。
4. 統合テストで 20 並列重複を送り副作用カウンタが 1 回だけ増えることを確認する。
5. ドレイン中に 50% のポッドを入れ替えつつ重複トラフィックを流すゲームデーを実施する。
6. エラーコードを公開表に載せ、期限切れ・本文不一致・テナント不一致を区別する。
7. ダッシュボードにリプレイ比率・クレーム p99・驱逐キー数を表示する。

観測

idempo_replay_total が 35% を 30 分超えたらクライアントループを疑います。テナントラベルはハッシュバケツ化し、カーディナリティ爆発を避けます。Redis RTT と推論時間を分離して記録し、キャッシュ劣化をモデル遅延と混同しないでください。週次で衝突率をレビューし、異常テナントを人手キューに回します。

課金ゲートウェイでは「冪等ヒット」と「実課金イベント」を別カウンタに分け、粗利を過大計上しないようにします。カスタマーサクセス向けに 7 日移動平均のリプレイ命中率を公開すると、連携先ベンダーの不具合を早期に炙り出せます。

パーティション

Redis 障害時はフェイルクローズかフェイルオープンを明示します。決済系は 503 とバックオフ指示が無難で、内部サンドボックスのみ緩和可能です。クライアントの再試行は最大 5 回、ジッター付きバックオフ上限 32 秒を目安にし、Retry-After があれば従います。詳細は 429 記事 を参照してください。

FAQ

GET にもキーが要る？

通常は不要。副作用のある処理を GET に載せないでください。

ルートを跨いで再利用？

禁止。ストレージキーにルート ID を含めます。

オフラインキューは？

エンキュー時にキーを割り当て、フラッシュ時に再利用します。

Apple Silicon Mac mini は静音で常時稼働の検証に向き、launchd・キーチェーン・パス解決が本番に近いです。macOS 上で Redis と nginx を同居させ、OpenClaw バイナリを実際のユニットファイルで動かすとノート PC検証との差が縮みます。MacHTML のクラウド Mac は約 16.9 USドル/日 で借りられ、顧客トラフィックを汚さず重複負荷試験ができます。

同じホストで TLS ハンドシェイク検証や証明書チェーンの差分も回せるため、SRE とセキュリティが同じ Apple Silicon 画面を共有し、冪等ロールアウトの説明責任を短時間で完結させられます。