2026年 OpenClaw Gateway マイナーアップグレードと OpenAI 互換エンドポイントの進化：リモート物理 Mac 上の /v1/embeddings とモデル転送の再現可能な移行 Runbook（破壊的変更対照 + 429／次元不一致 FAQ）
グローバルチームが ZoneMac ノードなどリモート物理 Mac上で OpenClaw Gateway を動かし、RAG やオーケストレーションに OpenAI 互換クライアントを載せている場合、マイナーアップグレードで最初に壊れやすいのは /v1/embeddings のルーティングとモデルエイリアス、および下流のモデル転送と HTTP 429 の挙動です。インデックスが静かに壊れるまで本番では気づきにくい問題です。本稿では破壊的変更の対照表、7 ステップの移行 Runbook、Runbook に貼れる数値とチェックリスト、429 とベクトル次元の不一致に絞った FAQ をまとめます。embeddings を変える前に Base URL と Bearer の意味論を固定してください。同一ホストへのセキュアなリモート経路は 2026年 OpenClaw リモートゲートウェイ再現チュートリアル：SSH ローカル転送 vs Tailscale Serve の選び方（Windows/Linux から macOS 物理ノードへの設定・トラブルシュート・FAQ） と併せて読むと、越境経路とゲートウェイ契約の前後がつながります。
1. 対象範囲と読者
OpenAI 型のエコシステムでは チャットと埋め込みが同じ /v1 接頭辞を共有しがちですが、ゲートウェイ側のモデル転送とエイリアス解決こそが マイナーリリースで最も触られやすく、ベクトルストアの次元・インデックス・バッチジョブは自動では移行されません。
要点：ゴールデンな curl による embeddings リクエストとモデル→次元の表を、アップグレード前後で保持してください。スモークは「チャットだけ」からチャット＋embeddings＋バッチ 1 本へ広げてからリリースをマージします。Base URL と Bearer の契約は OpenAI 互換 API・Cursor・リモート物理 Mac（Base URL／Bearer／リバプロ FAQ） で先に固定しておくと、本稿の embeddings／転送の検収と矛盾しません。
2. よくあるつまずき
- 「チャットだけ試した」ことで隠れる制限。 Base URL を上書きして
/v1/chat/completionsだけ検証すると、/v1/embeddingsだけエイリアスが変わった場合、RAG は数日後に次元エラーで落ちます。 - 転送とクォータの隠れコスト。 ゲートウェイが
text-embedding-3-smallをリージョン A やプロバイダ B に写すと、429 と Retry-After の意味が変わります。バックオフのないバッチはスロットルを長引かせます。 - インデックス契約に結びつく安定性。 ベクトル次元・距離指標（コサインと内積）・正規化は同一モデル改訂に束ねる必要があり、上流の次元が静かに変わると即座の 4xx ではなく「検索が悪化」として現れます。
3. 破壊的変更と転送：意思決定表
出荷前にこの表にサインオフしてください。左列はよくあるショートカット、右列は推奨ベースラインです。
| 領域 | 危険なショートカット | 推奨ベースライン |
|---|---|---|
| 破壊的変更 | チャット関連のリリースノートだけ読む | 「embedding」「alias」「router」「breaking」でノートを検索し、影響するモデル文字列をすべて列挙する |
/v1/embeddings |
古いゴールデン curl パスを接頭辞確認なしで流用 | チャットと同じ Base URL のときは明示的な embeddings ゴールデンを追加し、input 配列長の上限を検証する |
| モデル転送 | 上流エイリアスだけ変えてクライアントを更新しない | 公開モデル→上流モデル→期待次元をバージョン管理する |
| HTTP 429 | 同時実行を上げて押し切る | バックオフ・同時実行の分割・Retry-After 待ち。ゲートウェイ枠と上流枠を分けて考える |
| 次元の不一致 | アプリ側でベクトルを切り詰め／パディング | インデックス再構築または新コレクション。同一ストアに新旧次元を混在させない |
| 検収 | localhost の 200 だけ確認 | localhost＋公開 HTTPS＋バッチ経路の三つ。ベクトル長と先頭次元のサンプルを記録する |
4. 七ステップ Runbook（リモート物理 Mac）
- バージョンとノートを固定。 アップグレード前にゲートウェイと上流のダイジェストまたはセマバーを記録し、embeddings・ルーター・エイリアスに触れるリリースノート行を強調する。
- localhost でゴールデン embeddings。 Mac に SSH し、
127.0.0.1へ最小のPOST /v1/embeddingsを送り、modelとinputを指定してdata[0].embedding.lengthを保存する。 - Base URL とマッピングを凍結。 OpenAI 互換ガイドの Base URL 契約に合わせ、
OPENAI_BASE_URLを一つにし、モデルマップを 1 枚にまとめる。 - 二経路の検収。 同一ボディを
127.0.0.1と公開 HTTPS に再生し、公開だけが 429 ならエッジ／WAF・アカウント枠・Retry-Afterを調べる。 - バッチとバックオフ。 オフラインジョブの同時実行は 4 から始め指数バックオフし、各 429 で
request_idをログして上流サポートに渡す。 - ベクトルストアの整合。 新次元へインデックスを移行または再構築し、ウィンドウ中は旧モデルから新テーブルへの書き込みを無効化する。
- アーカイブとアラート。 ゴールデン curl・マッピング表・ロールバックコマンド（前のダイジェストまたはバイナリ）を Runbook に格納し、429 の持続と次元検証失敗でアラートする。
5. 429 と次元不一致の切り分け
設定を変える前に「スロットル」と「契約破壊」を分けてください。
| 症状 | 最初に疑うもの | 検証 |
|---|---|---|
| 429 と Retry-After | 上流またはゲートウェイのクォータ、バッチのバースト | 同時実行を下げ、Retry-After で待つ。単発リクエストとバッチでエラーを比較する |
| localhost は 200、公開は 429 | エッジ／WAF の制限またはアカウント枠のずれ | 公開の出口 IP をプロバイダのダッシュボードと突き合わせ、別リージョンや出口を検討する |
| ベクトル DB が書き込み時に次元エラー | モデルマップ変更で出力幅が変わった | embedding.length とスキーマを突き合わせ、同一テキストを前後で再埋め込みする |
| 検索が悪いが 4xx はない | 次元の混在または指標の不一致 | コレクション単位で分け、クエリと文書の埋め込みを同一モデルと正規化方針に揃える |
6. Runbook 向け引用ファクト
- 契約バンドル： 完全な
/v1/embeddingsURL、model文字列、期待次元、ゲートウェイと上流のバージョン（少なくとも major.minor.patch）をログに残す。 - バッチの初期同時実行： 負荷試験がなければ 同時 4 リクエストから始め 429 率を見て倍増。プロバイダの TPM／RPM と整合させる。
- 共有コマンド： 最小の embeddings
curlを 1 本にまとめ、SDK の統合テストでも同じ環境変数名を使う。
7. FAQ
Q: アップグレード後に次元が 1536→3072 に変わりました。列を広げるだけではダメですか？
いいえ。新しいインデックスとして扱い、全件の再埋め込みか二重書き込み移行が必要です。切り詰めやパディングは類似度と調整済み閾値を壊します。
Q: ゲートウェイログに埋め込み元テキストの生が出ますか？
既定ではマスクされるべきです。切り分けでは一時的にハッシュや長さのみをログし、詳細ログは事後にオフにしてください。
Q: チャット／Base URL の記事との関係は？
その記事は Base URL と Bearer を扱い、本稿はアップグレード後の embeddings と転送の契約です。合わせて OpenAI 互換の移行が完結します（上記のとおり、同一シリーズの Base URL 記事とセットで読んでください）。
8. まとめとノード選定
マイナーアップグレードで「チャットだけ」のスモークが取りこぼすのはembeddings とモデル転送です。ゴールデン curl＋次元表＋三経路の検収があれば、失敗をリリースウィンドウ内に閉じ込められます。
リモート物理 Mac でゲートウェイ・バッチ・ベクトルパイプラインを動かすことは、長寿命の Unix サービスとディスク I/O の安定性が核です。macOS はターミナル、SSH、launchd、Homebrew と相性がよく、API を長期公開する運用でも Gatekeeper と SIP が安心材料になります。Mac mini M4 は Apple Silicon の効率と数ワット級のアイドル電力に向き、マルチリージョンのエッジノードに適します。統合メモリは埋め込みとローカルキャッシュを同居させるときにも有利です。
この移行と切り分けパターンを安定・静音・手間の少ないハードウェアで回したいなら、コストが読みやすい起点のひとつが Mac mini M4 です。ZoneMac でリモート物理 Mac を確保し、チャットと embeddings を同一ゲートウェイ契約に固定してください。
OpenClaw と埋め込みバッチ用のリモート物理 Mac が必要ですか？
ZoneMac は高性能 Mac mini のクラウドレンタルを提供しています。ゲートウェイとスクリプトを同一マシンで動かし、越境クォータの不意打ちを減らせます。