/v1/embeddings route, warm RAG deps, and CI alert callbacks. Stack: Node 22, non-root service user, firewall-listed egress. See gateway security hardening, tiered model cache, and installation troubleshooting when installs drift.
Pain points this runbook removes
- Cold embeddings: the first query downloads weights or hits an API you never tested from the daemon user, so CI passes while the gateway 500s.
- Split-brain auth:
openclaw onboardwrote a token into one shell profile, butlaunchdloads another file—curlworks interactively and fails from automation. - Silent CI: pipelines finish green even when vector indexes are missing, because nobody posts structured JSON back to your alert webhook with bounded retries.
Decision matrix: where embeddings run
| Mode | Best when | Trade-off |
|---|---|---|
| Hosted API (OpenAI-compatible) | Stable egress, minimal RAM on the Mac | Quota, key rotation, outbound allowlist work |
| Local GGUF via bundled runtime | Air-gapped or predictable cost | Large APFS footprint; warm caches required |
| Ollama or sidecar on loopback | Fast iteration for small teams | Another daemon to upgrade and health-check |
Install, onboard, and install the daemon
Pin Node 22 with your standard toolchain (nvm, fnm, or the official pkg). Install the CLI globally as the same Unix user that will own the gateway—not root:
node -v # expect v22.x npm install -g openclaw which openclaw
Run onboarding with non-interactive flags when your policy allows, and always include --install-daemon so macOS registers a LaunchAgent-style service that survives SSH disconnects. A representative pattern (adjust provider flags to your org) looks like:
openclaw onboard --non-interactive --accept-risk --install-daemon \ --auth-choice anthropic-api-key --anthropic-api-key "$ANTHROPIC_API_KEY"
Write secrets to a file such as ~/.openclaw/.env.gateway with mode 600, then reference it from the plist EnvironmentVariables block—never echo tokens into CI logs. After install, reboot the daemon user session once so PATH and npm global bins match what launchd sees.
Enable memory search and probe /v1/embeddings
Set agents.defaults.memorySearch in openclaw.json to your provider, model, and dimensions. Use a least-privilege API key beside your gateway bearer. Bind the gateway on loopback (for example 127.0.0.1:18765) and terminate TLS in a proxy if exposed. Probe locally:
export OPENCLAW_GATEWAY_TOKEN="$(tr -d '\n' < ~/.openclaw/.env.gateway)"
curl -sS "http://127.0.0.1:18765/v1/embeddings" \
-H "Authorization: Bearer ${OPENCLAW_GATEWAY_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"model":"text-embedding-3-small","input":"healthcheck ping"}' | head -c 400
Expect HTTP 200 and a JSON body with data[0].embedding. If you see 401, compare the token in your shell with the token injected into launchd, strip accidental newlines, reload the daemon, and retry before touching model settings.
openclaw doctor, gateway status, and logs
Run openclaw doctor after upgrades, then openclaw gateway status --deep (or your build’s equivalent). Redirect launchd StandardOutPath / StandardErrorPath to dated logs and grep for 401, EADDRINUSE, or provider errors.
Remote Mac CI: prefetch vectors, then alert back
Add a CI preflight on the same remote Mac pool with the same cache env (HF_HOME, vendor paths, symlinks) as the gateway plist. Warm embeddings and indexes off-peak so release jobs read local files only.
On failure, POST JSON to your observability webhook with 2s / 4s / 8s backoff, jitter, and max three tries—page on repeated 401s instead of retry loops.
Common errors and what to run first
| Symptom | First checks |
|---|---|
EADDRINUSE on gateway port |
lsof -nP -iTCP:18765 -sTCP:LISTEN; stop stale node; align openclaw.json with reverse proxy upstream. |
HTTP 401 on /v1/embeddings |
Diff shell token vs launchd token; chmod 600 env file; reload daemon; verify clock sync. |
| HTTP 429 from provider | Lower concurrent CI prefetch; respect Retry-After; separate prefetch from interactive tests. |
ENOSPC during model pull |
Check symlink target volume with df -h and df -i; move warm tier or evict tmp shards. |
Citable guardrails
- Gateway bearer file mode
600; token rotation tied to HR offboarding and CI secret rotation. - Backoff ladder 2s / 4s / 8s for webhook posts; stop after three failures and alert humans.
- Disk watermark: warn at 80% utilization on the fast tier before embeddings jobs enqueue.
FAQ
Do I need a separate key for embeddings? Yes—scope API keys to embedding models only when vendors allow it, store them beside the gateway env file, and never reuse admin console keys in automation.
Why run CI prefetch if the gateway already pulls models? CI validates the same paths your daemon uses, catches cross-user permission bugs, and shifts bulk downloads out of the critical build path.
Summary, purchase path, and help
Summary: Reproducible embeddings on a remote Mac gateway come from a global npm install, onboard --install-daemon, explicit memorySearch configuration, a passing /v1/embeddings probe, doctor plus deep gateway status, and CI jobs that prefetch weights into shared caches before they gate releases. Wire alert webhooks with bounded retries so failures surface where operators already look.
Rent capacity via purchase, compare pricing, read help, or browse the blog index—no login to view.
Dedicated Apple Silicon keeps embedding caches warm without noisy neighbors.
Need a Stable Remote Mac for OpenClaw?
Rent Mac Mini M4 nodes with fast NVMe for embeddings caches and gateway daemons. Browse help, pricing, and checkout without logging in.