2026年 OpenClaw Telegram：ロングポーリングと Webhook はどちらを選ぶ？——リモート物理 Mac での HTTPS リバースプロキシ・登録・409／TLS タイムアウト再現 Runbook（openclaw.json 断片＋FAQ）

2. よくあるつまずき

1. Webhook に必要な「公開 HTTPS」を軽視する。 Telegram は検証可能なチェーンと到達可能な HTTPS（多くの場合ポート 443）を期待します。自己署名・中間欠落・LAN 内だけの DNS は TLS エラーや配信停止として現れます。
2. HTTP 409 をランダムエラーとみなす。 ステージングと本番で同一トークンを共有したり、古いノードが deleteWebhook せず残ったりすると setWebhook が衝突します。根は 登録状態であり OpenClaw の業務ロジックではありません。
3. ロングポーリングを「無料」と思う。 越境 RTT と長時間接続はジッタを増やし、キャリアによっては帯域制御の対象になります。PoC には向くが、本番では健全なエッジ付き Webhook に戻すのが一般的です。

3. 意思決定表：ロングポーリング vs Webhook

ZoneMac リモートノード向けの軽い「アーキテクチャ合意書」として使えます。

4. openclaw.json 断片（例示）

構造の例です。キー名とネストは利用中の OpenClaw バージョンに合わせてください。本番ファイルは必ずバックアップし、既存の gateway や資格情報ブロックとは手でマージしてください。

4.1 Telegram チャンネル：Webhook とローカル待受

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botTokenRef": "env:TELEGRAM_BOT_TOKEN",
      "transport": "webhook",
      "webhook": {
        "publicUrl": "https://bot.example.com/openclaw/telegram/webhook",
        "path": "/openclaw/telegram/webhook",
        "secretTokenRef": "env:TELEGRAM_WEBHOOK_SECRET",
        "maxConnections": 40,
        "dropPendingUpdates": false
      },
      "localServer": {
        "bind": "127.0.0.1",
        "port": 18789,
        "readTimeoutSeconds": 30,
        "writeTimeoutSeconds": 30
      }
    }
  },
  "gateway": {
    "reverseProxy": {
      "trustedProxies": ["10.0.0.0/8"],
      "forwardedHeaders": ["X-Forwarded-For", "X-Forwarded-Proto"]
    }
  }
}

ロングポーリングに切り替える場合は transport を "longPolling"（またはリリースの同等値）にし、timeout や allowed_updates など getUpdates 向けオプションを渡します。Telegram 側に古い Webhook URL が残っていないかも確認してください。

4.2 リバースプロキシ（Caddy スケッチ）

# TLS はエッジで終端し、Mac 上の 127.0.0.1:18789 へプロキシ。
# Host／パスは OpenClaw の登録と一致させる。ボディ上限はゲートウェイの指針に合わせて調整。

bot.example.com {
  reverse_proxy 127.0.0.1:18789 {
    header_up X-Forwarded-Proto {scheme}
    header_up X-Forwarded-For {remote_host}
  }
}

5. 七ステップ Runbook（リモート物理 Mac）

1. 運搬方式を固定する。 アクティブな経路は常に一つ。ロングポーリングから Webhook に切り替えるときは、先にポーリング側を止め二重配信を避ける。
2. TLS を端到端で検証する。 インターネット側からポート 443 を確認。フルチェーン・正しい SNI・ファイアウォール（Telegram の送信元レンジは公式ドキュメント参照）。
3. openclaw.json をマージする。 cp openclaw.json openclaw.json.bak.$(date +%Y%m%d%H%M) のうえ publicUrl、シークレット参照、ローカル bind を設定。
4. 古い Webhook 状態を掃除する。 getWebhookInfo → URL が誤りなら deleteWebhook → 単一の入口から setWebhook で 409 を減らす。
5. リロードしてプロセス健全性を確認する。 ディストリビューションの手順で reload。待受ポートと launchd ログにクラッシュループがないか見る。
6. 正例と負例のテスト。 テストメッセージ送信。secret_token を誤ったリクエストは即失敗すべき。pending_update_count も監視。インジェストの可観測性を強化するなら、同一ブログ内の Prometheus／Grafana 連携記事で /metrics 取得とアラート閾値を併せて整備してください。
7. 記録する。 ドメイン、証明書更新オーナー、setWebhook パラメータ、ロングポーリングへのロールバック手順を Runbook に残す。

6. 409 と TLS タイムアウトの切り分け

7. 引用用の数値・チェック項目

• getUpdates 長時間ポーリング： Bot API では timeout は通常 0〜50 秒。RTT の大きい回線では控えめから。
• ローカル HTTP： 例として 127.0.0.1:18789 はループバックに留め、TLS と公開面はプロキシが担当。SSH ファーストの ZoneMac ノードと整合します。
• Webhook 同時接続： maxConnections はゲートウェイワーカーと上流モデルの QPS に合わせ、受け口だけが速すぎないようにする。

8. FAQ

9. まとめと Mac mini／macOS がこのスタックに合う理由

ロングポーリングと Webhook の選択は「新しさ」ではなく、本番品質の HTTPS と単一の登録ソースを受け入れられるかどうかです。Webhook は可観測性を getWebhookInfo に寄せ、ロングポーリングは外向き経路とプロセス監視に複雑さを残します。

ZoneMac のリモート物理 Mac でこれを回すなら、Mac mini M4 クラスは待機電力がおおよそ数ワット級で、Unix ネイティブのサービス管理と launchd 常駐に馴染みます。同一筐体にリバースプロキシと OpenClaw を置けるため、無人ゲートウェイの再現性が高まります。Gatekeeper・SIP・FileVault による防御面も、長期公開ホストと相性が良いです。

Telegram の受口、TLS、OpenClaw を静音で予測可能な実機に載せたい場合、Mac mini M4 はコストと安定性のバランスが取れた出発点です。ZoneMac で専用の Apple Silicon ノードを借り、本 Runbook を実金属上でリハーサルしてみてください。