2026 年、クラウド Mac 上の OpenClaw Webhook と Ollama：トークン、ルート、トラブルシュート

外部システムを OpenClaw に接続すると、自動化は「CLI デモ」から「常時オンのチームメイト」へ進化します。2026 年の推奨パターンは、共有シークレットで保護された /hooks/* エンドポイントを公開する HTTP ゲートウェイと、Apple Silicon 上の Ollama によるローカル推論です。HTML/CSS のリファクタを LAN 内に閉じ込められるのは配線が正しい場合に限ります。本稿では Webhook の有効化、wake と agent ルートの選び方、ゲートウェイと同じ Mac での Ollama 検証、アップグレード後も GitHub issue に残るエラーへの対処をまとめます。

フックとシークレットを安全に有効化

上流ドキュメントは hooks.enabled: true と、すべての POST で検証するトークンを要求します。優先は Authorization: Bearer <token> です。レガシー向けに x-openclaw-token もあります。クエリパラメータにシークレットを置かないでください。アクセスログとブラウザ履歴に残ります。

設定変更後はゲートウェイを再起動し、リバースプロキシが TLS を終端するまでリスナーが 127.0.0.1 のみにバインドしていることを確認します。公開前に 本番向けゲートウェイ強化ガイド を読み、ループバック・証明書・トンネル方針を揃えてください。

運用では四半期ごとにトークンをローテーションし、staging で 24 時間検証してから本番へロールし、ロールバック用に旧トークンを短時間だけ残すと安全です。複数リージョンなら環境ごとに別シークレットを使い、テスト用フックが本番エージェントを誤爆しないようにします。

ログにはリクエスト ID とフック種別を含め、ゲートウェイ行と Ollama 行を相関させます。コンプライアンス業界では完全 JSON 本文の debug ログを避けるか、機密フィールドをマスクします。サードパーティ SaaS からの webhook なら、ドキュメントどおりの IP レンジと署名アルゴリズムを再確認し、偽 POST を正当イベントと混同しないでください。

/hooks/wake と /hooks/agent

POST /hooks/wake は「システムを軽く叩く」イベント—CI 完了、カレンダー通知、CMS がフォルダ監視を促す信号などです。POST /hooks/agent は隔離実行向けで、パートナー連携など信頼できない JSON に小さな爆発半径を与えます。

ルート	典型ペイロード	使う場面
/hooks/wake	軽量シグナルとメタデータ	スケジュールジョブ、リポジトリプッシュフック
/hooks/agent	タスク本文とツールヒント	Jira/Linear からのチケット単位自動化

同一ビジネスフローで喚起とツール付きパラメータの両方が必要なら、ゲートウェイ手前にキューでピークを削ぎ、ワーカーが内部 API に振り分けると Ollama を直撃しにくくなります。順序が厳密なパイプラインでは、ペイロードに単調増加シーケンスを載せ、ハンドラ側で重複排除します。

コピペ用 curl 例

ゲートウェイに到達できる任意のホスト（多くは SSH トンネル経由）から実行します。

curl -sS -X POST "https://gateway.example/hooks/wake" \
  -H "Authorization: Bearer $OPENCLAW_HOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"source":"ci","build":"12345"}'

ローカル検証では URL をループバックトンネル（例 https://127.0.0.1:8443/hooks/wake）に差し替えます。HTTP 200 または 204 と JSON 本文を期待します。即時 401 は Bearer の不一致、404 はゲートウェイが古いかパス typo—末尾スラッシュはプロキシによって正規化され差分が出ます。

curl -sS -X POST "https://127.0.0.1:8443/hooks/agent" \
  -H "Authorization: Bearer $OPENCLAW_HOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"task":"Summarize dist/index.html headings","repo":"/Users/build/workspace/site"}'

CI では jq で .status == "accepted" を検証します。ロードバランサが HTTP/2 を終端する場合、重複 POST 再試行 に注意してください。べき等ハンドラは約 5 分 以内の同一 build ID を検出して短絡し、高コストな Ollama プロンプトの二重実行を避けます。

多地域チームはノートとクラウド Mac の両方で同じ curl を実行し、DNS・証明書チェーン・システムプロキシの差を潰します。企業が SSL インスペクションする場合、ルート CA をクラウド Mac のキーチェーンに入れないと curl は成功しても Node プロセスだけ失敗し、「ゲートウェイだけ壊れる」錯覚を生みます。

M シリーズの Ollama：ポート、モデル、フォールバック

Ollama は既定で 127.0.0.1:11434 をリッスンします。OpenClaw を動かす同一 Mac でカタログを確認します。

curl -sS http://127.0.0.1:11434/api/tags | jq '.models[].name'

openclaw.json では qwen2.5:7b のような明示 ID でモデルを固定します。あいまいなエイリアスはスケジューラをクラウド API へフォールバックさせます。npm と Docker デプロイ比較 を直近で読んだなら、コンテナまたはグローバルインストールが Ollama と同一ネットワーク名前空間を共有しているか確認してください。Docker では host.docker.internal:11434 が必要なことが多いです。

スループット目安：Apple Silicon Mac mini では 7B 級で 35〜50 tok/s 前後。重みと Node ゲートウェイ分で最低 8GB の RAM を見込んでください。ネイティブ Ollama API と /v1 の OpenAI 互換面はツール呼び出し挙動が異なり、OpenClaw のプランナーはプロバイダ文字列でトランスポートを選びます。迷ったら短い JSON ツールスキーマで両方を試し、構造化引数か散文かを観察して webhook 運用マニュアルに勝ちパターンを書き留めます。

巨大リポジトリではスキル設定でインデックスパスを制限し、.openclawignore で node_modules とビルド成果物を除外してコンテキストを瘦せます。モデルが diff を途中で切る場合は「ファイル列挙」と「ファイル単位パッチ」の二段にタスクを分割し、フックペイロードでファイル境界を明示するとエージェントの越境修正を減らせます。

2026 年の既知の失敗モード

1. Ollama 成功後の HTTP 404。 上流 issue を追跡：実行は終わるがコールバックが not found。対策：最新パッチへ上げ、リバースプロキシが /hooks/* をそのまま転送することを確認。
2. Ollama ストリームでカスタムヘッダが落ちる。 X-OLLAMA-KEY が必要な保護エンドポイントは、古いビルドが内部ストリームでヘッダを落とすと 403。プロキシで注入するか修正版まで更新。
3. Ollama 設定なのに Anthropic へ。 ゲートウェイプロセス環境 からも curl し、ファイアウォールの穴を捕捉。agents.defaults.model.primary を ollama/model:tag に明示し、フォールバック警告ログを監視。
4. 小型モデルがツールスキーマを拒否。 Gemma 級チェックポイントはツール添付で HTTP 400 を返すことがあり、OpenClaw がツールなしで再試行する—小型ローカルモデルには単純タスクを割り当てる。

いずれかを再現する際は ゲートウェイと Ollama のログを並べて約 30 秒 取得し、タイムスタンプを揃えるとネットワーク・認証・モデル側のどこで壊れたかを一度の反復で切り分けやすくなります。

外部ベクトル DB や検索プラグインを使う場合、webhook が同一秒に大量のインデックス更新を起動して SSD I/O とモデルキューを同時に飽和させないよう、ハンドラに同時実行上限とデッドレターキューを設けます。

レンタル Mac mini でステージングする理由

Webhook とローカル推論は常駐プロセスを伴います：ゲートウェイ、Ollama、ときどきブラウザスキル。クラウド Mac mini は負荷をノートのバッテリーから遠ざけ、OpenClaw プラグインが期待する macOS パスを保ち、リスクの高いアップグレード前に既知良好の openclaw.json をスナップショットできます。実験が壊れても共有オフィス端末を取り戻すより再プロビジョニングが速いです。

SSH でログを tail し、macOS のプライバシー確認が必要なら時折 VNC—同一ノード、二アクセス、追加ハードなし。記録すべき指標：Webhook 週次受理率目標 99.5%、POST から最初のエージェントログ行までの p95（LAN ではしばしば 300〜800ms）、Ollama キュー深度。クラウド 429 が急増したらフック扇が並列エージェントを過剰起動していることが多い—CI でセマフォを入れるか cron を 30〜60 秒 ずらします。

HTML/CSS リポジトリではスキルを静的ビルドと同じ作業ツリーに向け、webhook が触る diff を 1 PR に収めます。典型レイアウトはクラウド Mac の /Users/build/workspace/site で、.openclawignore で node_modules と dist を除外。Slack/Teams を橋渡しする場合は四半期ごとに署名シークレットを回し、security add-generic-password でキーチェーン保管し、デバッグ時の env | grep OPENCLAW 漏えいを防ぎます。

MacHTML のレンタルノードでは顧客ごとにユーザーと LaunchAgent を分離し、一時ファイルの越境読み取りを防げます。コンプライアンスが厳しければゲートウェイアクセスログを追記専用ストレージにエクスポートし、保持期間を明記。多国籍チームは主要ユーザーと同じリージョンのデータセンターを選び、TLS 往復が webhook 尾遅延に与える影響を抑えます。

「成功ドリル」を空マシンから最初の 2xx webhook までの時間・コマンド列・ロールバック手順が揃う形で定義し、メジャーアップグレードのたびに再実行すると週末オンコールの認知負荷が下がります。

FAQ

Ollama が成功したのに HTTP 404 が出るのはなぜ？

一部のゲートウェイビルドは Ollama をプロバイダにした際、実行後コールバックを誤処理します。OpenClaw を更新し、Webhook URL パスが文書どおり /hooks/* であることを確認し、レスポンス段階でゲートウェイログを取得してください。

クエリ文字列のトークンは許可される？

現在のガイダンスはクエリ文字列へのシークレットを拒否します。Authorization: Bearer または x-openclaw-token ヘッダーを使ってください。

Ollama を設定しているのに OpenClaw が Anthropic を呼ぶのはなぜ？

プライマリ文字列が有効な ollama/ 参照でない、またはゲートウェイプロセスからデーモンに到達できないとモデル探索がフォールバックします。curl で疎通を確認し、agents.defaults.model.primary を明示的に固定してください。

MacHTML で Apple Silicon キャパシティを借りれば、webhook エンドポイントと Ollama モデルを 24/7 温めたまま個人 MacBook を過熱させずに済みます。その安定性は取りこぼした CI フックの減少と、大規模リポの HTML/CSS 書き換えにおける予測可能なトークン遅延に直結します。レンタルノードを本番に近いステージングとして扱い、成功ドリルのあと一週間依存関係を凍結してから計画的にアップグレードしてください。