You have an OpenAI key in OpenClaw and chat works fine. But semantic memory search does not: searches return nothing, or recall behaves as if the feature were switched off. The agent remembers things in conversation, yet memory_search comes up empty.
Semantic memory search is not powered by the chat model. It is powered by an embeddings model that indexes your memory files, and embeddings are a separate API surface with separate credential requirements. Most of the time, the key you are using was never valid for that surface. This guide walks the four causes in the order they bite, starting with the one that trips up almost everyone.
Before changing anything, read the symptom closely, because it points at the cause. If searches return nothing at all and recall feels disabled, embeddings are almost certainly failing at request time. If searches return keyword matches but miss semantic ones, embeddings are unavailable and recall is falling back to lexical full-text ranking, which is the safety net OpenClaw uses when the embedding provider cannot be reached. And if the agent answers memory questions from what it already holds in context but memory_search itself errors, the provider is configured but failing closed. Each of those three reads maps to a different fix below.
Why a working OpenAI key is not enough
When agents.defaults.memorySearch.provider is not set, OpenClaw uses OpenAI embeddings by default (legacy configs that say provider: "auto" resolve to openai too). That default has a requirement: remote embeddings need a real OpenAI API key, the kind generated in the platform dashboard.
Credentials scoped to chat products do not qualify. If you authenticated through a Codex OAuth flow or a ChatGPT login, your credential covers chat completions but not the embeddings API, so the agent runs and responds perfectly while every embeddings call fails. Older advice in this area sometimes claimed OpenClaw would silently fall back to keyword search; the current behavior is more honest than that. When the configured embeddings provider is unavailable at runtime, memory_search returns an unavailable result instead of quietly pretending, and recall reports the problem instead of hiding it.
Step 1: Check how you authenticated
Look at the auth surface for your providers:
Read the parenthetical counts: a healthy OpenAI setup shows api_key=1 with oauth=0, meaning a real platform key is stored in the auth profile. If you see oauth=1 instead, you authenticated through a product OAuth flow, and embeddings will not work with that credential no matter what else you configure.
Where does the key actually live? On current OpenClaw installs, provider credentials are stored in per-agent auth profiles (a sqlite file under the agent directory, as the effective=profiles:... part of the status output shows), not in plaintext config keys. That is why older guides telling you to paste a key into models.providers.openai.apiKey feel out of date: the supported path today is the auth flow, which writes the credential into the profile store with the right shape. If you have multiple agents, remember that auth is per agent: the agent doing the memory search must be the one with the valid profile.
Step 2: Check the memory search config
Semantic search also has its own configuration block that is easy to confuse with general memory settings. It lives at agents.defaults.memorySearch, not under a memory key:
Four fields matter: enabled (default true), provider (default "openai"), model (provider default), and fallback (default "none"). The capture above is from a real host that deliberately avoids OpenAI for this: it points the provider at local Ollama with nomic-embed-text and a remote.baseUrl of http://localhost:11434. If you want keyword-only search and no embeddings at all, set provider: "none" on purpose; that selects FTS-only recall. If a provider is listed but unreachable, fix the provider rather than expecting a silent fallback, because explicit remote providers fail closed.
Step 3: Add a real API key or switch providers
The fix depends on which direction you want to go. To stay on OpenAI embeddings, add a standard platform key and make sure it is the one OpenClaw uses:
If you would rather not add an OpenAI key at all, pick a different embeddings provider. OpenClaw supports Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, a local GGUF model (local), or any OpenAI-compatible /v1/embeddings endpoint. Local options like Ollama cost nothing per call and keep every memory vector on your machine, which is what the real-host config above demonstrates.
Step 4: Watch the index when you switch
One more trap waits after you fix the provider: switching the embedding provider or model can make the existing SQLite vector index incompatible. OpenClaw does not silently re-embed everything; it pauses vector search and reports an index identity warning instead. Rebuild when you are ready with openclaw memory index --force (per agent: --agent <id>). The deep status command probes provider availability before you waste a cycle on a rebuild against a broken provider.
The full order of operations: authenticate, set the provider, restart the gateway, probe with openclaw memory status --deep, rebuild the index if the provider or model changed, then run a real search and watch the logs for embedding call failures. The diagram puts all four causes on one page:
Two details make the rebuild step predictable. First, the index is a SQLite vector index, and chunk embeddings are cached there too (the cache is on by default), so a full reindex after a provider switch is a one-time cost, not a recurring one. Second, the compatibility guard is broader than provider changes: changing the model, provider settings, memory sources, scope, chunking, or tokenizer can all invalidate the existing index. When that happens, vector search pauses with an index identity warning instead of returning wrong results, which is the correct failure mode; rebuild with openclaw memory index --force and the warning clears. A quick openclaw doctor pass after the change catches config gaps the status output will not show.
Related fixes
Memory behavior sits next to two systems worth checking when recall feels off: exec approval policies control what the agent may run while indexing, and CLI vs gateway config mismatches explain why a config change did not reach the running gateway. New to OpenClaw? Start with The Complete OpenClaw Guide.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting: your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.
About The Author
