2026年 OpenClaw Gateway を OpenAI 互換 API として使う：Cursor／スクリプトはリモート物理 Mac にどう繋ぐ？
Cursor や CI スクリプトから無人の物理 Mac 上の OpenClaw を叩く担当者は、Base URL の組み立て・Bearer の転送・リバースプロキシのパス書き換えの三つの継ぎ目で失敗しがちです。本稿では 2026 年時点の OpenAI 互換呼び出し契約、クライアント別の意思決定表、検証 7 ステップ、社内 SLO 草案に貼れる閾値、401／TLS／タイムアウトの FAQ を Runbook 向けに整理します。
1. OpenAI 型クライアントがエッジで壊れる理由
OpenClaw Gateway は主要な LLM API と同じ HTTP 形を話せますが、「OpenAI 互換」は契約です。Base URL、パス（/v1/...）、Authorization: Bearer、TLS の身元が、実際にゲートウェイが検証する内容と一致している必要があります。リモート物理 Mac では SSH トンネル、企業プロキシ、分割 DNS が各レイヤでいずれかのフィールドを書き換えます。
- 二重パス： エッジがすでに
/v1を載せているのにクライアントが/v1/chat/completionsを付けると 404 や黙ったリダイレクトに—Cursor や SDK は最終 URL を隠しがちです。 - Bearer のズレ： CI のシークレットにコピーしたトークンから
Bearer接頭辞が欠けたり、プロキシの Basic 認証と衝突したりすると、ゲートウェイは空または別資格情報を見ます。一方127.0.0.1へのローカル curl は成功し続けます。 - タイムアウトの非対称： 対話ツールは LAN 遅延を前提にしがちですが、越境 RTT と TLS・HTTP/2 の優先度付けで、既定の
read_timeoutを長い生成が超えることがあります。リージョン横断の経路設計は 2026年グローバルチーム向けMacマルチリージョン構築ガイド：遅延最適化と合規性のノード選択マトリックス と併せて読むと、ノード配置と SLO の整合が取りやすいです。
TLS 尾部や転送タイムアウトの切り分けは、App Store 系パイプラインでも同型の論点が出ます。TestFlight 自動アップロードとリモート物理 Mac のタイムアウト／429 の意思決定マトリクス の「経路とタイマ」の考え方を、OpenAI 互換 HTTP に読み替えてください。
2. 意思決定表：Cursor／スクリプト／CI
環境ごとに一行を選び、人間と自動化で Base URL を意図的に分けないでください（サービスメッシュ経由の CI など文書化した例外以外）。
| クライアント | 設定するもの | 典型の落とし穴 |
|---|---|---|
| Cursor（カスタム OpenAI） | Base URL を自前 HTTPS オリジンへ。API キー欄＝ゲートウェイの Bearer 秘密。 | ワークスペース設定とグローバル設定が分岐し、フォルダ一つだけ api.openai.com のまま。 |
| 公式 OpenAI SDK | OPENAI_BASE_URL と OPENAI_API_KEY。最小の chat completion で検証。 |
クラウド向け Org／Project ヘッダが混ざり、Bearer だけを見るゲートウェイを混乱させる。 |
| curl／GitHub Actions | -H "Authorization: Bearer …" と …/v1/chat/completions までの完全 URL。 |
ログではマスクされていても、HTTPS 専用エッジへ HTTP で叩いていると失敗する。 |
3. 接続 Runbook（7 ステップ）
- localhost 証明： Mac 上で
curl -sS -H "Authorization: Bearer $TOKEN" http://127.0.0.1:<port>/v1/models（または文書化された探索ルート）。ここで失敗するなら launchd か bind アドレスを先に直す。 - 外部 URL の凍結： ホスト名とパス接頭辞ポリシーを一つに。例：公開
https://gw.example.comで nginx のlocation /v1/がhttp://127.0.0.1:<port>/v1/へ二重に剥がさず転送。 - Bearer 契約： プロキシが
Authorizationを転送すること。エッジで認証を終わらせるなら、ゲートウェイが期待する秘密と同じものを注入—方式を黙って混ぜない。 - Cursor 整合： curl で通したのと同じ Base URL（スキーム＋ホスト＋任意の接頭辞）を貼る。UI がエラーなら開発者ツールかゲートウェイログで失敗 URL を捕捉。
- スクリプト同値： CI から同一リクエストを
--fail-with-bodyで実行し、401 を顕在化。 - タイムアウト予算： クライアントの
--max-timeとプロキシのproxy_read_timeoutを、高 RTT 経路での長い完了向けに 120 秒以上（モデル SLO に合わせて調整）。 - 継続チェック： LAN 外から毎時
/v1/modelsまたはヘルスを Bearer 付きで叩き、月曜の Cursor より先にアラート。常駐プロセスの安定化パターンは関連する OpenClaw 運用記事と併読してください。
4. 引用用の閾値（社内 SLO 草案向け）
- 401 切り分け SLA： ペアの curl トレースで localhost と公開を 5 分以内に分離—トークン強度より誤経路が支配的なことが多い。
- TLS 再確認： ゲートウェイホストの macOS マイナーアップグレードのたびにエッジ証明書と中間チェーンを再検証—Keychain とプロキシ信頼ストアは同時にズレやすい。
- タイムアウト下限： 越境経路の生成呼び出しでは、アプリとプロキシのアイドルタイマを 観測した初トークン時間 P95 の 2 倍以上にしてから失敗とみなす。
5. FAQ：401／TLS／タイムアウト
HTTP 401 Unauthorized
三つのペイロードを比較：（1）localhost＋Bearer の curl、（2）公開ホスト名＋Bearer の curl、（3）プロキシで捕捉した Cursor／SDK トラフィック。（1）だけ通るならエッジが Authorization を食い替えている。（2）が通って Cursor だけ失敗なら、IDE が古い Base URL を参照—ワークスペース単位でリセット。
TLS／証明書エラー
クライアントが入力するホスト名と証明書のサブジェクトが一致するか確認。http:// から https:// へのリダイレクトでホスト名が変わると SSL: certificate subject name mismatch の典型です。TLS はエッジで一度終端し、localhost への二重 TLS は内部 PKI を運用しない限り避ける。
タイムアウトと「空のハング」
プロキシとクライアントのタイムアウトを同時に引き上げる。ストリーミングが途中で止まる場合は、中間が本体を待つ HTTP/2 バッファになっていないか確認し、curl -N でストリーミング挙動を再現する。
6. ゲートウェイ役に Mac mini クラスが向く理由
リモート Mac 上の OpenAI 互換エッジは、生の TFLOPS より 常時稼働の信頼性が鍵です。Apple Silicon は待機電力がおおよそ数ワット級、macOS は月単位のアップタイムでもクラッシュ率が極めて低く、launchd・ssh・Homebrew といった Unix 系の運用がゲートウェイの Runbook と素直に揃います。ユニファイドメモリは並列 HTTP とローカルツール呼び出しを、DIY x86 で起こりがちな NUMA 驚きなしに捌けます。
Gatekeeper・SIP・FileVault は無人ノードでの不正ソフトリスクを一般的な Windows イメージより下げやすく、管理面が Cursor と CI のシークレットで TLS を終端するときに効きます。タワー型デスクトップを常時見張るより、静音で予測可能な Mac mini M4 に載せ替えたいチームには、コストの見通しが立ちやすい選択肢です。
エージェントや IDE 向けのリモートゲートウェイを本番契約として固めたいなら、macOS に最適化された静かなハードへ載せるのが近道です。ZoneMac の Mac mini 案内で、ローカル PC の「たまたま動いた」からドキュメント化された本番へ進めてください。
OpenClaw 向け 24/7 物理 Mac が必要ですか？
OpenAI 互換 API を安定して公開するためのネットワーク経路と、macOS 上の launchd／TLS スタックをそのまま使える Mac mini ノードをご用意しています。