2026年 OpenClaw Gateway：OpenAI 互換 HTTP API 実践——/v1/chat/completions の有効化、認証、SSH ローカルポート転送によるイントラネット／RAG 連携の再現チェックリスト＋FAQ
ゲートウェイを「どの OpenAI SDK からも叩ける標準 HTTP エンドポイント」として扱う：専用リモート Mac では互換レイヤー・Bearer 認証・SSH トンネルを同じ runbook に載せます。イントラネット／RAG との切り分けと、runbook に貼れるトリアージ FAQ をまとめます。ローカル推論を併用する場合のクォータとタイムアウトは OpenClaw + Ollama ハイブリッド推論とゲートウェイ 429／OOM の切り分け（専用リモート Mac） も参照してください。
1. 目的と範囲
本チェックリストは次の 3 点を扱います。① ゲートウェイ上で公開 API と同形の /v1/chat/completions を出すこと。② Bearer トークンで認証し、待ち受け面を必要最小に保つこと。③ データセンター内 Mac のループバックだけで聞いているゲートウェイを、SSH のローカルポート転送でノート PC から安全に届け、OpenAI ベース URL をトンネル先に向けること。
本稿の対象外：公開向けリバースプロキシと自動 TLS、マルチテナント課金、ベクトル DB の網羅比較——これらは別途アーキテクチャレビュー向けです。
2. OpenAI 互換 HTTP と /v1/chat/completions の有効化
ゲートウェイ設定（または相当する環境変数）で OpenAI 互換 HTTP を有効にし、互換レイヤの意味論がビルドと一致しているか確認します。
- パス：
POST /v1/chat/completions。本文にmodel、messages、任意でstream。 - 応答： 非ストリーミングは JSON。ストリーミングは
text/event-stream形式の SSE 行（フィールドはバージョン依存——リリースノートに従う）。 - モデルマッピング： OpenAI 風モデル名を実バックエンド（クラウド API、ローカル Ollama、ハイブリッド経路）に割り当て。ハードコードを散らさず、設定のエイリアス表に一本化する。
本番のコツ： 既定は 127.0.0.1 にバインドし、localhost 側のリバースプロキシまたは SSH からだけ露出させる。0.0.0.0 にする場合はファイアウォール、mTLS またはプロキシ認証を足し、変更は runbook に記録する。プロセス分割時の LaunchAgent 共存は
OpenClaw macOS デュアル LaunchAgent と専有リモート Mac の SSH ヘッドレス運用
を参照。
3. 認証：Bearer、ローテーション、ログ
互換レイヤは通常 Authorization: Bearer <token> を想定します。推奨は次のとおりです。
OPENCLAW_GATEWAY_TOKEN（またはプロジェクト相当）を専用ユーザー／LaunchAgent の環境に注入し、CI と手元デバッグをシークレットストアと揃える。- ローテーションでは新しい秘密を先に書き込み、その後
launchctl unload/loadまたはゲートウェイ再起動——クライアントだけ新トークンに更新済みで、プロセスが旧トークンしか検証しない「半開き」状態を避ける。 - Bearer 全文は既定でログに出さない。短いプレフィックス＋リクエスト ID を残し、上流モデル側ログと突き合わせる。
4. SSH ローカルポート転送：イントラネットのゲートウェイをノートへ
ゲートウェイがリモート Mac のループバックのみで待ち受ける場合、開発マシンで（ホスト・ユーザー・ポートは置き換え）：
ssh -N -L 18080:127.0.0.1:18789 user@remote-mac.exampleSDK のベース URL を http://127.0.0.1:18080/v1 に向け（末尾スラッシュの挙動はクライアント依存）、すべての呼び出しに Bearer を付与する。トンネルが不安定なら ControlMaster で接続を再利用するか autossh を前段に置き、SSH を誰が使い鍵をいつ回すかを文書化する。
5. イントラネットと RAG の接続パターン
よくある分離：検索・再ランキングは社内向けベクトルサービスに残し、生成はゲートウェイのチャット互換レイヤに通す。注意点は次のとおりです。
- 同居： 埋め込みとチャットが同一ホストなら
127.0.0.1呼び出しで遅延を抑える。ホストを分ける場合は内部 DNS を使い、検索とモデル呼び出しでタイムアウトを分けて一方の SLA が他方に埋もれないようにする。 - 資格情報： ベクトル API 用キーとゲートウェイ Bearer は分離する。CI 用と手動デバッグ用も分けると監査が楽になる。
- コンテキスト上限：
messagesに詰める前に切り詰め／要約し、暗黙の 413 やクラウド請求の跳ね上がりを防ぐ。
6. 再現可能な受入チェックリスト
| 手順 | 作業 | 合格条件 |
|---|---|---|
| A | 非ストリーミング curl で /v1/chat/completions |
HTTP 200 と JSON に choices[0].message（フィールド名はビルド依存） |
| B | 意図的に Bearer を省略 | 401／403 とリクエスト ID 付きログ |
| C | SSH トンネル後、ノートから呼び出し | Mac 上ループバックと同機能（RTT を除く） |
| D | E2E：RAG 検索＋チャット | 合意した SLO 内の遅延・エラー率。失敗を検索／生成に帰属可能 |
7. FAQ
Q: curl は通るのに SDK が「Invalid URL」と言う。
A: ベース URL に /v1 が二重になっていないか、トンネルと HTTPS／HTTP の不一致、システム HTTP プロキシの介入を確認する。
Q: ストリーミングが途中で止まる。
A: ゲートウェイと上流のタイムアウトを揃える。SSH に ServerAliveInterval を設定する。中間が SSE をバッファしていないか確認する。
Q: ゲートウェイを共有しつつトークンを漏らしたくない。
A: サポートされていれば人／プロジェクト別のサブトークンを発行するか、リバースプロキシで OIDC を終端する。Bearer を公開リポジトリにコミットしない。
ゲートウェイと互換 API を Mac mini で載せる理由
OpenAI 形式の HTTP、SSH トンネル、軽量な RAG サイドカーは、安定した予測可能な OS とネットワークスタックがあると運用が楽です。macOS は launchd・ネイティブ OpenSSH・揃った Unix ツールチェーンがあり、専用リモート Mac mini ではリスナーアドレス・ログパス・トークン付き環境を単一ユーザ文脈に固定しやすく、障害時は SSH で即再現できます。ゲートウェイ・構造化ログ・小さなローカルモデルを同居させるときも、Apple Silicon のユニファイドメモリと Neural Engine が熱やファン音との戦いを減らします。
同価格帯の小型 PC と比べ、Mac mini M4 は待機電力がわずか数ワット程度に収まりやすく、Gatekeeper・SIP・FileVault により無人ノードのマルウェア面も狭めやすいです。この互換レイヤと SSH 運用を、静音で省電力かつ監査しやすいハードに載せたい場合、2026 年時点でも Mac mini M4 は有力な起点です。トップページでプランを比較し、イントラネットと RAG の受け渡しを再現可能にしてください。日々の OpenClaw 運用と SSH の組み合わせは 2026年 OpenClaw 企業向け統合：リモート Mac mini SSH で「開発アシスタント」を構築する方法 も参照。