対象はリモート Macで OpenClaw の
/v1/embeddings と RAG を再現可能にしたい担当者です。概念より手順の固定を優先します。ゲートウェイ硬化と階層キャッシュを併読してください。
現場で詰まりやすい三点
1
シェルと launchd のトークン不一致で /v1/embeddings が四〇一になり、ログだけでは見分けにくい。
2
初回に重み取得や索引構築が走り SLO を壊す。CI と同一キャノニカルパスで温める。
3
監視 POST がスパム化。二・四・八秒バックオフと四〇一との切り分けが要る。
埋め込み経路の決定表
| 方式 | 利点 | 運用メモ |
|---|---|---|
| ローカル GGUF 等 | 外向き課金とレート制限を避けやすい | NVMe 容量と mmap、初回 DL 時間 |
| ホスト API | 冷起動手順が単純 | 四二九 とキー権限の監査 |
モデル IDと次元を CI と固定し、変更はレビューに閉じます。
再現手順（六ステップ）
① npm install -g openclaw、which が専用ユーザー配下か確認。② openclaw onboard --install-daemon で launchd。③ OPENCLAW_GATEWAY_TOKEN を mode 六百で plist とシェルで一致。④ memorySearch と HF_HOME 等を CI と合わせる。⑤ curl で POST /v1/embeddings が二〇〇。⑥ openclaw doctor と gateway status --deep の後、CI で重み・索引をプリフェッチし監視へ JSON は二・四・八秒・三回まで。失敗回復参照。
curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"text-embedding-3-small","input":"ping"}' \
"http://127.0.0.1:${PORT}/v1/embeddings"運用にそのまま貼れる基準値
チェックリスト
- 待受ポートを文書化しリバプロは一本化。
- API キーは embeddings と chat で権限分離、ローテは plist と CI を同 PR。
- Webhook は二・四・八秒にジッターを足し四二九 と四〇一 を分離。
FAQ
Q. status は通るのに embeddings だけ失敗
A. 別ルートかモデルパス未解放。deep と readlink を確認。
Q. プリフェッチ前に本番が走った
A. ファイル存在を必須ゲートにし失敗はキューへ。
まとめ・購入とヘルプへの導線
要点は常駐化、トークンと環境変数の一致、curl 実測、doctor／deep、CI キャッシュと監視の抑制です。