OpenClawゲートウェイのデッドレターキューと安全なツール再実行（2026年版）：ポイズンメッセージ、スキーマ乖離、べき等汲み取り、メトリクス、ログ監査、クラウドMac mini上のmacOSリハーサル

エージェント向けHTTPツールへ扇状に伸びるゲートウェイは、インライン指数バックオフだけでは救えない失敗に必ず遭遇します。契約が一晩でズレたパートナーAPI、ゲートウェイのJSONスキーマと上流マイクロサービスの実装の不一致、長時間続く上流停止。こうした終端系の障害をホットパスに閉じ込めると、モデルストリームの遅延、メモリ圧、トレーススパンの滞留が連鎖します。2026年の成熟したOpenClaw運用では、これらをデッドレターキュー（DLQ）へ隔離し、人または方針ゲートの下で検査・修正・再実行できるようにします。本稿ではDLQ行きの条件、パーティションと保持、再実行がべき等キーと重複排除とどう噛み合うか、サーキットブレーカーが汲み取りをどう止めるか、Prometheusメトリクスで健全性をどう証明するか、そしてマスク付きログとローテーションで監査可能性を保つ方法を整理します。

コストの話を先に置くと、誤った二重再実行が顧客請求を二重に動かし共有CRMを壊すインシデントより、MacHTMLの専用Mac mini（およそ一日16.9米ドル）でDLQ方針を週次リハに載せる方が安価です。小さな金属筐体のままブローカ、ゲートウェイ、スクレイプ用サイドカーを同居でき、ディスク配额とnewsyslogの挙動まで含めて本番に近い形で叩けます。

再試行の隣にDLQが要る理由

再試行は「短時間で直る一過性障害」を前提にします。ツール統合はその前提を日常的に破ります。相手のOpenAPIが夜中にフィールド名を変えて422を返す、ベクトル検索がシャード再配置で十二分間500を吐く、など。これをワーカースレッドプールに閉じ込めると、遅延がモデル側へ伝播し、ユーザー体感の停滞が増え、各保留呼び出しがバッファとスパンを握ったまま解放されません。

DLQは終端失敗を低速レーンへ移し、オペがバッチでペイロードを眺め、スキーマを当て直し、テナントを隔離できます。2026年時点で複数チームが採る実務ルールの一例は、べき等な読み取りに対しインライン再試行を三回・合計2.5秒以内に抑え、エラークラスが未知か上流が非再試行を明示したらDLQへ、というものです。べき等キー無しの書き込みは無限再試行禁止。プランナへ構造化エラーを即返すか、方針で人の承認が要るならDLQへ、の二択にします。

OpenClawの扇状展開は問題を増幅します。一つの計画ステップが六本のツールを同時に叩くことがあり、ツールごとにDLQパーティションを分けないと、ポイズンなCRM探索が、同じRedis裏の健全な電卓ツールの汲み取りまで塞ぐ恐れがあります。

ポイズンとスキーマ失敗

ポイズンとは、コードかデータを変えない限り永遠に成功しないペイロードです。ゲートウェイでのJSONスキーマ検証失敗、出口ポリシーで塞がれたURL、カナリアで消えた能力名への参照などが典型です。これらは即非再試行として分類し、機械可読なfailure_class（例：SCHEMA_REJECT、EGRESS_DENY）を添え、元のトレースID付きでDLQへ入れ、サポートがチケットと突き合わせられるようにします。

スキーマ乖離は特別扱いが要ります。各エンキューにtool_contract_version: 20260425.3のように版を刺し、再実行担当が「失敗が14:00 UTCの修正より前か後か」を判断できるようにします。週次で契約版を上げるチームなら、パーティションあたり保持十四日・容量500MB程度がよく見えます。窓を超えたら自動失効と墓碑メトリクスで、GDPR系の削除証跡と未読失効件数の両方を残します。

部分ポイズンのバッチ（百件中五件だけ検証失敗など）は、バッチ丸ごと拒否ではなく行単位でDLQ化し、残り九十五件のスループットを守ります。

オペが期待するエンベロープ

生のツール引数とは別に、DLQメッセージはエンベロープを持たせます。深夜のページを生き延びる最低限はtenant_id、request_id、idempotency_keyまたは明示的なnull、tool_name、tool_version、first_seen_at、last_error_code、retry_count、failure_class、そして4KB上限のマスク済みHTTPヘッダコピーです。本体が256KBを超えるなら圧縮オブストアへのポインタを付け、ブローカを重くしないようにします。

{
  "dlq_version": 1,
  "request_id": "req_9f2c…",
  "idempotency_key": "idem_7a91…",
  "tool": {"name": "crm_search", "contract": "20260425.3"},
  "failure_class": "UPSTREAM_TIMEOUT",
  "retry_count": 3,
  "last_http_status": 504,
  "first_seen_at": "2026-04-25T01:12:04Z",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

秘密は本文に直書きせず、金庫パス参照に置き換えます。OAuth更新成果物を載せていた呼び出しなら、vault://tenant/42/oauthのようにし、ディスクスナップショット流出が即クラウド資格情報事故にならないようにします。

再実行安全とべき等契約

べき等なしの再実行は請求メール二通の温床です。再実行は元のべき等キーをTTL内で再利用するか—金融系ツールなら多くの場合24〜72時間—、意図的な二度目であることが下流に伝わるsupersedes_request_id付きの新キーを発行します。Redis TTLや衝突安全ストレージの型はべき等の記事に譲ります。

手動汲み取りは依存先ごとに毎秒一件から始め、五分間エラー率が0.5%未満なら段階的に上げます。当番二人が同時に速度を倍加しないよう、オペレータ単位の同時実行上限も併設します。変更系ツールはエンベロープに二人承認フラグを要し、CIからの自動再実行は専用サービスアカウントに分離し、鍵は三十日で回し、行動メトリクスは人間の汲み取りとカードinalityを分けます。

ブレーカーと汲み取りの協調

上流サーキットが開いたままDLQを汲み取るのは、回復途上の相手へ再ポイズンを撒く行為です。実務ではブレーカゲージを見て、サーキットブレーカー解説の半開成功プローブ拍に乗ってから汲み取りジョブを有効化し、再び開いたら自動停止、が基本形です。状態DRAIN_PAUSED_BREAKER_OPEN遷移でSlackへ飛ばしdlq_drain_paused_totalを増やす、という単純な機械でも効きます。

429とRetry-Afterが付くなら、クライアント流量と同様にDLQ汲み取りもヘッダ冷却を尊重し、ワーカー間の群れを避けるため最大250msのジッタを足します。

Prometheusと遅延SLO

最低限、ツールパーティション別dlq_depthゲージ、dlq_ingress_total{failure_class}、dlq_replay_success_total、dlq_replay_failure_total、初回失敗から成功再実行までのdlq_age_secondsヒストグラム、コンプライアンス報告用dlq_expired_totalを出します。ボードはPrometheusの記事で組んだものへ直結させます。

SLO例：DLQメッセージの95%が四十八時間以内に成功再実行か明示的オペ処分。単一テナントで十五分窓dlq_depthが一万を超えたらページ。多くは上流停止がクライアントエラーに化けたサインです。

ログ、個人情報マスク、監査

再実行は業務ロジックの再駆動です。オペ身份、時刻、旧新べき等キー、引数差分のマスク済みログを残します。小さなMac mini実機でディスクが溢れないよう、マスクとlogrotateの型に合わせ、暴走汲み取りがJSONギガバイトを吐いても回るようにします。

macOSではゲートウェイログを50MB・七世代のnewsyslogがよく使われます。DLQ保持と回転周期を揃え、ブローカから失効後もファイルで相関できるようにします。

比較：再試行列・DLQ・アウトボックス

観点	ホット再試行列	DLQ	トランザクションアウトボックス
遅延予算	ミリ秒台	分〜日	DBコミットに束縛
人のレビュー	稀	前提	任意
順序保証	キー単位ベストエフォート	パーティション内FIFO	単一ライターで強い
向く所	一過性5xxの塊	ポイズン、長停止、方針ホールド	自社DBへの正確一度副作用

番号付き運用手順

1. 深度急増がスクレイプ誤検知でないか、ブローカUIとdlq_depthを突き合わせる。
2. 五件サンプルし、failure_classが同一ならチケットは一本化する。
3. サーキット状態とエラー予算を確認してから汲み取りを有効化する。
4. 毎秒一件で開始しdlq_replay_failure_totalを監視する。
5. 完了後にメトリクスをスナップし、インシデント記録へ添付する。

よくある質問

DLQとホット再試行は同一Redis群でよいか

ハードは共有できてもキー空間とメモリ方針は分離し、DLQ背圧がホット再試行メタを追い出さないようにします。

べき等キーの寿命は

想定する最長の法務紛争窓に合わせます。B2Bではツール72時間、請求連携30日といった併用が見えます。

エージェントが無人再実行してよいか

読み取り専用でべき等が実証済みなら限定的に。それ以外はオペ意図を要し、自律ループを避けます。

信頼できるDLQはキュー機構だけでなく観測可能性とmacOSに近いリハが一体です。MacHTMLで借りたMac mini（およそ一日16.9米ドル）は、ネイティブmacOSと静かな筐体、Apple Siliconの余裕を同時に持ち、本番前に汲み取り脚本、LaunchAgent、マスク済みログをまとめて検証するのに向きます。