24/7 の macOS Mac mini で動かす OpenClaw ゲートウェイは、ときにクラッシュせずに凍ります。Slack の入力中表示が止まり、ダッシュボードの RPC プローブは緑なのに、ユーザーには 90 秒以上 返答が届かない——運用者はモデル障害と決めつけがちですが、実際には 読み取りタイムアウト が「終わらないバイト列」を待っているだけか、Wi-Fi の瞬断後に半開きになった TLS が停滞しているケースが混ざります。本稿は読み取り停滞と HTTP 429 を切り分け、再現可能な curl -m 基準を置き、チャネル背圧とゲートウェイログを結びます。429 は応答は来るが退避が必要、という別物なので プロバイダ 429 と Retry-After をセットで読んでください。認証・バインド・ポートの線では ゲートウェイ doctor 診断 が先です。リバースプロキシを前に置く構成では プロキシとトンネルの硬化 でアイドルタイムアウトを端到端で揃えないと、ここで詰めたつもりが入口で再発します。ローカルの並列度と再試行嵐を抑える話は トークン予算とスロットリング と合わせると、読み取り調整だけでは戻らない「擬似ハング」も減ります。
この記事では意思決定マトリクス、監査に耐える数値の出発点、macOS ログの読み方、プラットフォームエンジニア向け FAQ をまとめます。
別の失敗モードを見ているサイン
ダッシュボードが健全でもユーザーが待つなら、多くの場合アプリケーション層の読み取りで詰まっています。ストリーミング JSON でトークンが 300 ms だけ出て沈黙するパターンは、上流がチャンク途中で止まった典型です。
財務向けに説明できるカウンタは四つ：時間あたりの読み取りタイムアウト件数、平均停滞時間、放棄された会話、ラベル「AI が固まった」で再オープンされたチケットです。この四系列が無いと、タイムアウト変更が本当に効いたか証明できません。
インシデント中は機能開発を止め、マスクした tcpdump の要約と TLS セッション ID を凍結し、直近のタイムアウト変更を巻き戻せる状態にしてください。
「非常口」として一時的に上限を上げる場合でもチケット ID を必須にしないと、ローンチ週末に静かに天井が上がり、日曜の請求だけが跳ねる、という運用負債が残ります。
ステージングと本番の connect／first-byte／idle／壁時計の上限を一行ずつ表にし、ブリッジコールで五分以内に差分が説明できるようにしておくと、監査が楽です。
マトリクス：読み取りタイムアウト・429・DNS
| 症状 | 想定クラス | 最初のプローブ |
|---|---|---|
| Retry-After 付き HTTP 429 | レート制限 | プロバイダの退避手順に従う |
| 接続時間より長くステータス行が来ない | 読み取り停滞 | 上流 URL に対する段階的 curl -m |
| 即時 NXDOMAIN | DNS | ゲートウェイホストから dig +trace |
監査に耐える初期タイムアウト
出発点の目安：接続 5 秒、会話型モデルの first-byte 読み取り 45 秒、ストリーミングのチャンクアイドル 12 秒、ユーザー発話あたりの壁時計 180 秒 で構造化されたハンドオフリンクを返す、などです。
読み取りタイムアウト後の再試行は、ベンダーが明示的インシデントを掲げていない限りユーザー発話あたり 2 回 に抑えます。
メンテナンス告知がある場合は、開始 15 分前 から並列度を 20% 下げ、重なった再試行で停滞を増幅しないようにします。
タイムアウト表は Git で版管理し、オンコールがインシデント当時の定数を推測しないようにしてください。
curl 再現レシピ
# 天井を段階的に上げて上流の停滞点を探す
curl -sS -o /dev/null -w '%{http_code} %{time_connect} %{time_starttransfer}\n' \
-H "Authorization: Bearer $TOKEN" \
-m 10 https://api.example.com/v1/models
curl ... -m 30 ...
curl ... -m 60 ...同じ列をゲートウェイホストと踏み台から実行し、time_starttransfer が分岐するなら OpenClaw 本体より経路側が疑わしいです。
-w '%{remote_ip}' で DNS が期待する anycast POP に張り付いているか確認します。
ストリーミングでは --no-buffer と pv を併用し、サーバが止めたのかローカル端末の背圧で詰まったのかを切り分けます。サポートの「何も表示されない」報告で数時間溶かす典型を潰せます。
企業プロキシがチャンクを剥がすと、curl は EOF までバッファします。ゲートウェイの HTTP ライブラリ設定（HTTP/1.1 と HTTP/2）に合わせて再現条件を揃えてください。
macOS、launchd、ディスク圧力
launchd は頑健ですが、詳細ログを垂れ流すとルートボリュームの空きが 12% を切ったときに write() で詰まり、モデルハングに見えることがあります。
diskutil apfs listVolumeGroups でスナップショットを確認し、同一ボリュームグループ上のローカル Time Machine が IOPS を奪っていないか見ます。
TLS セッション再開は断続的な読み取りフリーズを隠します。ベンダー切り分けでは診断クライアントを時々ローテーションし、新規ハンドシェイクを強制してください。
ハード調達が遅れるならクラウド Mac mini で演習しましょう。MacHTML の Apple Silicon は多くの場合 日 $16.9 前後 で SSH/VNC が揃い、ライブキャプチャに向きます。
停滞中のチャネル UX
Slack や Teams は理由が書かれていれば待てます。最初のトークンが 8 秒 来なければ定型文、45 秒 で追加説明、120 秒 でハンドオフリンク、の三段が現実的です。
生のスタックトレースをそのまま貼らないでください。内部ホスト名が混ざります。
多言語ワークスペースではロケールヘッダに合わせて定型文を出し分けます。
プロダクト分析では「最初のトークン無し」と「回答途中のストリーム停滞」を分けてください。前者は接続や認証、後者は読み取りアイドルや上流のチャンク停止にほぼ一対一で写ります。ラベルを誤ると OAuth を掘り当てる一方で本当はタイムアウト表の差分でした、という時間損失が起きます。
外向きステータスページがあるなら、合成プローブの開始転送時間がベースラインの 2 倍 を超えたら黄信号にし、ユーザー可視エラー率が動く前にコミュニケーションを先行させます。
テレメトリと SLO
合成プローブの time_starttransfer ヒストグラムと、ライブゲートウェイ指標を突き合わせ、乖離が 25% を超えたらローカルポリシーのドリフトを疑います。
合成プローブには専用 User-Agent を付け、ファイアウォールが狭い許可でホワイトリストできるようにします。プローブは成功するのに本番だけ失敗する場合は、プローブサブネットと本番 VPC ピア間の MTU や TCP ウィンドウの差も見ます。
読み取り窓を延ばすなら、テナントあたりの最大同時ストリームを下げてリスクを束縛してください。
読み取りタイムアウト率が七日移動平均の 4 倍 を 10 分 超えたらネットワークを先にページし、モデルルーティングは後に回します。
監査ログは 90 日 保持し、ユーザー発話とプロバイダのリクエスト ID を相関 ID で結びます。
四半期ごとに最長待ち上位 35 件を人手レビューしてください。自動バケットは地域ブラウンアウトをローカルバグと誤ラベルしがちです。
Grafana にはタイムアウト定数に触れた Git マージを注釈し、スパイクが意図的変更かを即断できるようにします。
ベンダーが「レイテンシ上昇」とだけ書く窓では、ストリーミングのアイドルを一時的に短くして明示的な再試行コピーを見せ、4 時間以内 にチケット付きロールバックへ戻す、という運用が現実的です。
よくある質問
読み取りタイムアウトは 429 と同じですか？
いいえ。429 にはステータス行があります。読み取り停滞は終端応答がありません。
まずタイムアウトを上げますか？
チケット・上限・ロールバック時刻がある場合に限ります。
物理 Mac mini を使う理由は？
macOS の TLS、launchd、ディスク挙動は Linux CI と一致しません。
Apple Silicon Mac mini は OpenClaw のタイムアウト演習に最も忠実な舞台です。長時間キャプチャでも読みやすいサーマル、ネイティブ Keychain、本番ゲートウェイに近いネットワークスタックが揃います。MacHTML は SSH/VNC 付きのクラウド Mac mini で読み取り方針、doctor プローブ、スロットルの相互作用を別の CapEx なしに検証できます。演習で確保し、証拠が揃ったら解放するのが現実的です。
クラウド Mac mini で OpenClaw タイムアウト演習
Apple Silicon をレンタルし、読み取り停滞の再現、天井調整、doctor とスロットルの検証を実 macOS で行えます。