How to Use the OpenClaw Embeddings API

Embeddings are easy to underestimate because they feel less dangerous than chat. In OpenClaw, the /v1/embeddings endpoint still lives on the Gateway HTTP surface, shares Gateway auth, and follows the agent-target model contract. That makes it powerful for internal search and RAG, but it should be operated with the same care as the chat and responses endpoints.

30-second answer

Enable the OpenAI-compatible HTTP surface, call POST /v1/embeddings on the Gateway /v1 base URL, authenticate with the Gateway bearer token or password, and use openclaw/default or openclaw/ as the model target. If you need a specific embedding backend, send x-openclaw-model so the client target stays stable while the backend model can change under operator control.

When this pays off

This is a good fit when an internal documentation search tool, support assistant, or workflow engine already expects OpenAI-compatible embeddings. Instead of giving that system a raw provider key, you can route it through OpenClaw so credentials, model choices, and observability stay under the Gateway. For a buyer, that reduces integration time without losing operational control.

Operator runbook

1. Prove the OpenAI-compatible surface first. The embeddings route is part of the Gateway /v1 surface documented with chat completions, models, and responses. If /v1/models does not work, do not start debugging vector code. Fix endpoint enablement, base URL, and Gateway auth first.
2. Choose the agent target intentionally. Use openclaw/default for the default agent or openclaw/ for a specific configured agent. This keeps client configuration stable even if the underlying provider changes from OpenAI to another embeddings-capable backend later.
3. Keep provider auth on the Gateway host. The docs separate Gateway auth from model-provider auth. Your client authenticates to OpenClaw; OpenClaw resolves provider credentials through environment, auth profiles, or config. That is easier to rotate and much safer than spreading provider keys across every RAG worker.
4. Use x-openclaw-model only when you need an explicit backend override. That header is documented for the OpenAI-compatible surface. It is useful for experiments, but production systems should avoid hidden per-request model drift unless you log it and have a fallback plan.
5. Put the endpoint behind the same private network story as chat. Embeddings can reveal sensitive text through inputs, usage patterns, and logs. Keep it loopback, SSH-tunneled, tailnet-only, or behind a trusted private ingress with real auth rather than exposing it as a public utility route.
6. Track cost and latency. Embeddings often run in batches, so a small integration mistake can become steady spend. Use Gateway usage-cost, diagnostics metrics, or OTLP/Prometheus export to watch token usage and request duration once the integration is live.

Verification

A reliable check is: GET /v1/models returns your OpenClaw target, a tiny embeddings request returns successfully, Gateway logs show the expected provider/model path, and your vector store records the expected number of items. If any step fails, keep the repro small and avoid dumping real customer text into test requests.

Common mistakes

The biggest mistake is treating embeddings as anonymous infrastructure. In practice, the input text may include support tickets, source code, customer records, or internal docs. Another mistake is hardcoding provider model ids into every client. OpenClaw gives you agent-target ids so the operator can rotate the backend without touching every caller.

Turn it into a repeatable operating system

The OpenClaw Playbook helps you turn embeddings into a business-safe workflow: which documents enter the index, who can trigger re-indexing, how to monitor spend, and where to split a customer-facing search surface from the private operator Gateway that can use stronger tools.

Before rollout

Before rollout, decide what text is allowed into the embedding pipeline, how deletion requests are handled, and who owns re-indexing. Embeddings often become invisible infrastructure, so add a simple owner note, retention rule, and cost check before the first customer document enters the system.