/v1/embeddings 與依賴預拉取寫成 Runbook。本文依 docs.openclaw.ai：npm 全域、openclaw onboard --install-daemon、doctor／閘道狀態、最小權限令牌、重試與 CI 快取。延伸：閘道健康與 LaunchAgent、閘道安全硬化、CI 預拉與版本一致。
痛點：不是「開了閘道」就能穩定 RAG
- 冷啟動與維度不一致：CI 未預拉嵌入模型或索引，首次查詢延遲拖垮流水線。
- 令牌分裂：互動 shell 與
launchd注入的閘道權杖不同，curl測通但服務內仍四零一。 - 無退避的告警：Webhook 對監控重試過猛，放大四二九 或掩蓋真實鑑權錯誤。
決策矩陣：嵌入來源與營運取捨
| 選項 | 適用 | 與 CI 銜接要點 |
|---|---|---|
| 本機／內建向量 | 需控管出站、合規內網 | 同一 HF_HOME 或快取根目錄，job 先預檢檔案存在 |
| 雲端嵌入 API | 快速上線、省 GPU RAM | 最小範圍 API 權杖；CI 乾跑與閘道共用模型名與維度 |
| 混合 | 開發走雲、正式走本機 | 分環境設定檔與索引路徑，禁止混用維度 |
安裝面：全域 npm、PATH 與 sharp
Node 二十四 LTS 或 二十二點一四以上；npm install -g openclaw@latest 後 openclaw --version。找不到指令時把 $(npm prefix -g)/bin 加入 PATH。sharp 建置衝突可設 SHARP_IGNORE_GLOBAL_LIBVIPS=1 再裝。
onboard、守護程序與閘道狀態
openclaw onboard --install-daemon 註冊 LaunchAgent，避免關閉終端即停閘道。接著 openclaw doctor、openclaw gateway status（必要時深層）查行程、埠、鑑權；僅回環時本機 curl，對外走 SSH 或反向代理。
啟用 /v1/embeddings 與環境變數
設定啟用記憶體搜尋與嵌入提供者，走OpenAI 相容 /v1/embeddings。探測：http://127.0.0.1:埠/v1/embeddings 附 Authorization: Bearer。權杖僅閘道／儀表板所需；祕鑰檔 chmod 600，由 launchd EnvironmentVariables 注入。
與遠端 Mac CI：預拉向量與索引
CI 與閘道共用同一快取根目錄（如 HF 快取），離峰預拉嵌入權重與索引；預檢通過再跑會打閘道的 job。節點規格可參考 首頁方案。
告警回傳與失敗重試
預檢／閘道結果以 JSON POST 監控或 IM Webhook；二秒四秒八秒退避加抖動，四二九與四零一分開計次，三次後人工處理。
落地步驟（HowTo 精簡版）
全域 CLI：安裝 Node 後 npm install -g openclaw@latest，修正 PATH。
守護程序：openclaw onboard --install-daemon，記錄埠與權杖來源。
嵌入與 RAG：設定提供者與模型名，注入環境變數而非硬編碼。
本機探測：curl POST /v1/embeddings 帶 Bearer。
健康：openclaw doctor 與 openclaw gateway status。
CI 與告警：共用快取路徑預拉，Webhook 退避回傳摘要。
可引用命令片段
export PATH="$(npm prefix -g)/bin:$PATH"
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw doctor
openclaw gateway status
# 本機探測（埠與 TOKEN 請替換）
curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"your-embed-model","input":"ping"}' \
http://127.0.0.1:18789/v1/embeddings
- 系統需求：Node 二十四（建議）或二十二點一四以上（文件 Install 頁）。
- 驗證鏈：
openclaw --version→doctor→gateway status。 - 退避：Webhook 建議二四八秒階梯並區分四二九與鑑權失敗。
常見狀況（FAQ）
embeddings 逾時？查模型檔／API 與同機 CI 是否搶占 CPU／記憶體。
升級後守護程序仍舊版？重載 LaunchAgent，核對 plist 二進位路徑。
總結：以可複現命令為主；含 BlogPosting、BreadcrumbList、FAQPage、HowTo。