OpenClaw

OpenClaw Embedding Providers👨‍💻

Embeddings are the backbone of how OpenClaw remembers and retrieves context. When you interact with an OpenClaw agent, every piece of memory -- conversation history, user preferences, project context -- gets converted into a numerical vector representation through an embedding model. These vectors are stored in a vector database, and when the agent needs to recall relevant information, it computes the embedding of the current query and finds the closest stored vectors. This is what makes OpenClaw's memory feel intelligent rather than just a keyword search over past conversations.

An embedding provider is the service or model responsible for generating these vectors. OpenClaw supports multiple providers out of the box: OpenAI's embedding models for cloud-based setups, local models for privacy-sensitive or offline workflows, and a custom provider interface for teams that run their own embedding infrastructure. The choice of provider affects retrieval quality, latency, cost, and data privacy -- so it is one of the first configuration decisions you need to make when setting up OpenClaw personalization.

This guide covers how to configure each provider type, how to evaluate which one fits your use case, and how to troubleshoot common issues. For a deeper look at how embeddings integrate with the broader memory system, see the full lesson at /courses/openclaw-personalization/memory-deep-dive/openclaw-personalization-embedding-providers. For context on how memory and sessions work together, see /concepts/openclaw-sessions-memory.

Key Takeaways

  • 1Embedding providers convert text into vector representations that power OpenClaw's memory retrieval. Every memory write goes through the configured embedding model before storage, and every memory query embeds the input to find semantically similar stored memories.
  • 2OpenClaw supports three provider types: OpenAI (cloud API), local models (running on your machine via Ollama or similar runtimes), and custom providers (any HTTP endpoint that returns vectors). You configure the provider in your openclaw.json file.
  • 3The embedding dimension must be consistent across all memories in a project. If you switch providers or models, you need to re-embed all existing memories because vectors from different models are not compatible with each other.
  • 4Local embedding models eliminate API costs and keep all data on your machine, but they require more system resources and may produce lower-quality embeddings than OpenAI's models for general-purpose text.
  • 5OpenClaw uses cosine similarity by default when comparing embedding vectors. This means the direction of the vector matters more than its magnitude, which is why normalized embedding models tend to perform best.
  • 6The embedding provider configuration is separate from the LLM provider configuration. You can use a local embedding model with a cloud LLM, or vice versa -- they are independent choices.

Master openclaw embedding providers

Take the OpenClaw Personalization course with hands-on lessons and challenges.

Examples

Basic OpenAI embedding configuration in openclaw.json

json

This is the most common configuration. The embedding section in openclaw.json tells OpenClaw which model to use for converting text to vectors. The text-embedding-3-small model from OpenAI offers a good balance of quality and cost at 1536 dimensions. The apiKey field supports environment variable interpolation with the ${VAR} syntax, so you never hardcode secrets in the config file. The vectorStore section is separate -- it controls where the resulting vectors are stored, not how they are generated.

Local embedding model configuration with Ollama

json

For users who want to keep all data local, OpenClaw supports Ollama-hosted embedding models. The nomic-embed-text model is a popular choice that produces 768-dimensional vectors and runs efficiently on consumer hardware. The baseUrl points to your local Ollama instance. Before using this configuration, you need to pull the model with 'ollama pull nomic-embed-text'. Note the lower dimension count compared to OpenAI -- this means the local model uses less storage per memory but may capture less semantic nuance.

Custom embedding provider setup

json

Teams running their own embedding infrastructure can point OpenClaw at any HTTP endpoint. The custom provider configuration lets you specify the endpoint URL, authentication headers, and the shape of the request and response payloads. The requestFormat tells OpenClaw how to send text to your endpoint (which JSON field holds the input, and whether it expects a single string or an array). The responseFormat tells OpenClaw where to find the resulting vectors in the response body. This makes OpenClaw compatible with any embedding service that speaks HTTP, including internal microservices, fine-tuned models hosted on cloud GPU instances, or third-party embedding APIs beyond OpenAI.

Checking if embeddings are working with CLI commands

bash

These three CLI commands cover the main debugging workflow. The 'memory status' command shows your current configuration and confirms the provider is connected. The 'memory embed --test' command sends a sample string through your configured provider and returns the vector, confirming the embedding pipeline works end to end. The 'memory search' command performs a full retrieval cycle -- it embeds the query, searches the vector store, and returns the most similar stored memories with their similarity scores. If any of these commands fail, the error message will point to the specific issue (missing API key, unreachable endpoint, dimension mismatch).

MEMORY.md example showing how embeddings power memory retrieval

markdown

This MEMORY.md file is what gets embedded and stored as vectors when OpenClaw processes your project context. Each section and bullet point becomes one or more chunks that are individually embedded. When you later ask the agent something like 'set up a new API route,' the embedding provider converts that query into a vector and retrieves the most relevant memories -- in this case, it would surface the 'All API routes return { data, error } shape' preference and the 'Backend: Express API in apps/api' architecture note. The quality of the embedding model directly determines how well the agent retrieves the right context. A better embedding model means the agent remembers the right preferences at the right time.

Common Mistakes

Mistake:

Switching embedding models or providers without re-embedding existing memories. The old vectors were generated by a different model with different dimensions or a different vector space, so similarity comparisons between old and new vectors produce meaningless results.

Fix:

Run 'openclaw memory re-embed' after changing your embedding provider or model. This regenerates all stored vectors using the new model. For large memory stores, use the --batch-size flag to control throughput and avoid rate limits.

Mistake:

Setting the dimensions field in openclaw.json to a value that does not match the actual output dimensions of the chosen model. This causes silent failures or corrupted vector storage because the vectors get truncated or padded.

Fix:

Always check the documentation for your chosen model to confirm its output dimensions. For OpenAI text-embedding-3-small it is 1536, for nomic-embed-text it is 768. The dimensions field must exactly match the model output.

Mistake:

Using a high-dimensional embedding model (like text-embedding-3-large at 3072 dimensions) for a small memory store with only a few dozen entries. The additional dimensions add storage and latency overhead without improving retrieval quality when the dataset is small.

Fix:

For memory stores with fewer than 1,000 entries, a smaller model like text-embedding-3-small (1536 dimensions) or a local model at 768 dimensions performs just as well with lower resource usage. Scale up the model when the memory store grows and retrieval precision becomes a bottleneck.

Mistake:

Hardcoding the API key directly in openclaw.json instead of using environment variable interpolation. This leads to secrets being committed to version control.

Fix:

Always use the ${ENV_VAR} syntax for API keys in openclaw.json and store actual keys in your shell environment or a .env file that is excluded from version control via .gitignore.

Mistake:

Not verifying that the local Ollama server is running before starting OpenClaw with a local embedding provider. OpenClaw will start but memory writes and queries will fail silently or return errors only when the agent tries to use memory.

Fix:

Run 'openclaw memory embed --test' after configuration changes to verify the full embedding pipeline works. For local providers, confirm the Ollama server is running with 'ollama list' before starting OpenClaw.

Best Practices

  • Start with OpenAI text-embedding-3-small for initial setup and development. It offers the best out-of-the-box retrieval quality, requires no local infrastructure, and costs fractions of a cent per thousand embeddings. Switch to local models only when you have a specific need for offline usage, data privacy, or cost optimization at scale.
  • Run 'openclaw memory embed --test' after every configuration change. This single command confirms that your provider is reachable, the API key is valid, the model is available, and the output dimensions match your configuration. It takes a few seconds and prevents silent misconfigurations.
  • Keep the embedding model consistent across all team members working on a shared project. If one person uses text-embedding-3-small and another uses nomic-embed-text, their memory stores will have incompatible vectors. Pin the embedding configuration in the project's openclaw.json and commit it to version control.
  • Use the dimensions field as a sanity check, not just a configuration option. OpenClaw validates that the vectors returned by your provider match the declared dimensions and will warn you if there is a mismatch. This catches misconfigured custom endpoints early.
  • For privacy-sensitive projects, pair a local embedding model with local vector storage. This ensures that no text content or vector data leaves your machine. The combination of Ollama for embeddings and sqlite-vec for storage gives you a fully offline memory system.
  • Monitor embedding latency in production setups. If memory retrieval is adding noticeable delay to agent responses, check whether your embedding provider is the bottleneck. Local models are typically faster for single queries (no network round trip), while cloud providers handle high-throughput batch embedding better.

Summary

Embedding providers are the engine behind OpenClaw's memory retrieval system. They convert text into vector representations that enable semantic search over stored memories, preferences, and project context. OpenClaw supports OpenAI for high-quality cloud embeddings, Ollama for local privacy-preserving setups, and a custom provider interface for teams with their own infrastructure. The key configuration decisions are choosing a provider that matches your privacy and cost requirements, setting the correct dimensions for your chosen model, and verifying the pipeline works with the CLI test commands. When switching models, always re-embed existing memories to maintain retrieval quality. The embedding configuration is independent from the LLM configuration, giving you flexibility to mix cloud and local components based on your needs.

Practice OpenClaw with hands-on challenges

Learn openclaw embedding providers hands-on in your IDE

Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.

Related Concepts

Openclaw Sessions MemoryOpenclaw Soul PersonaOpenclaw Agents

Master OpenClaw with Stanza

Interactive lessons and challenges, right in your code editor.

Check the free courses. No credit card.