Naar hoofdinhoud gaan

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Deze pagina vermeldt elke configuratieknop voor OpenClaw-geheugenzoekopdrachten. Zie voor conceptuele overzichten:

Memory overview

Hoe geheugen werkt.

Builtin engine

Standaard SQLite-backend.

QMD engine

Local-first sidecar.

Memory search

Zoekpijplijn en afstemming.

Active memory

Geheugen-subagent voor interactieve sessies.
Alle instellingen voor geheugenzoekopdrachten staan onder agents.defaults.memorySearch in openclaw.json, tenzij anders vermeld.
Als je zoekt naar de functieschakelaar en subagentconfiguratie voor actief geheugen, die staat onder plugins.entries.active-memory in plaats van memorySearch.Actief geheugen gebruikt een model met twee poorten:
  1. de Plugin moet ingeschakeld zijn en gericht zijn op de huidige agent-id
  2. het verzoek moet een geschikte interactieve permanente chatsessie zijn
Zie Active Memory voor het activeringsmodel, de Plugin-eigen configuratie, transcriptpersistentie en het veilige uitrolpatroon.

Providerselectie

SleutelTypeStandaardBeschrijving
providerstringautomatisch gedetecteerdEmbeddingadapter-id zoals bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai of voyage; kan ook een geconfigureerde models.providers.<id> zijn waarvan api naar een van die adapters wijst
modelstringproviderstandaardNaam van het embeddingmodel
fallbackstring"none"Fallbackadapter-id wanneer de primaire adapter faalt
enabledbooleantrueGeheugenzoekopdrachten in- of uitschakelen

Volgorde voor automatische detectie

Wanneer provider niet is ingesteld, selecteert OpenClaw de eerste beschikbare optie:
1

local

Geselecteerd als memorySearch.local.modelPath is geconfigureerd en het bestand bestaat.
2

github-copilot

Geselecteerd als een GitHub Copilot-token kan worden opgelost (env-var of authprofiel).
3

openai

Geselecteerd als een OpenAI-sleutel kan worden opgelost.
4

gemini

Geselecteerd als een Gemini-sleutel kan worden opgelost.
5

voyage

Geselecteerd als een Voyage-sleutel kan worden opgelost.
6

mistral

Geselecteerd als een Mistral-sleutel kan worden opgelost.
7

deepinfra

Geselecteerd als een DeepInfra-sleutel kan worden opgelost.
8

bedrock

Geselecteerd als de AWS SDK-referentieketen wordt opgelost (instantierol, toegangssleutels, profiel, SSO, webidentiteit of gedeelde configuratie).
ollama wordt ondersteund, maar niet automatisch gedetecteerd (stel het expliciet in).

Aangepaste provider-id’s

memorySearch.provider kan verwijzen naar een aangepaste models.providers.<id>-vermelding. OpenClaw lost de api-eigenaar van die provider op voor de embeddingadapter, terwijl de aangepaste provider-id behouden blijft voor endpoint-, auth- en modelprefixafhandeling. Zo kunnen multi-GPU- of multi-host-setups geheugenembeddings toewijzen aan een specifiek lokaal endpoint:
{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

API-sleutelresolutie

Remote embeddings vereisen een API-sleutel. Bedrock gebruikt in plaats daarvan de standaard AWS SDK-referentieketen (instantierollen, SSO, toegangssleutels).
ProviderEnv-varConfiguratiesleutel
BedrockAWS-referentieketenGeen API-sleutel nodig
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENAuthprofiel via apparaatlogin
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (placeholder)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
Codex OAuth dekt alleen chat/completions en voldoet niet voor embeddingverzoeken.

Configuratie van remote endpoints

Voor aangepaste OpenAI-compatibele endpoints of het overschrijven van providerstandaarden:
remote.baseUrl
string
Aangepaste API-basis-URL.
remote.apiKey
string
API-sleutel overschrijven.
remote.headers
object
Extra HTTP-headers (samengevoegd met providerstandaarden).
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Provider-specifieke configuratie

SleutelTypeStandaardBeschrijving
modelstringgemini-embedding-001Ondersteunt ook gemini-embedding-2-preview
outputDimensionalitynumber3072Voor Embedding 2: 768, 1536 of 3072
Het wijzigen van model of outputDimensionality activeert automatisch een volledige herindexering.
OpenAI-compatibele embeddingendpoints kunnen provider-specifieke input_type-verzoekvelden gebruiken. Dit is nuttig voor asymmetrische embeddingmodellen die verschillende labels vereisen voor query- en documentembeddings.
SleutelTypeStandaardBeschrijving
inputTypestringniet ingesteldGedeelde input_type voor query- en documentembeddings
queryInputTypestringniet ingesteldinput_type tijdens query’s; overschrijft inputType
documentInputTypestringniet ingesteldIndex-/document-input_type; overschrijft inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
Het wijzigen van deze waarden beïnvloedt de identiteit van de embeddingcache voor provider-batchindexering en moet worden gevolgd door een geheugenherindexering wanneer het upstreammodel de labels verschillend behandelt.
Bedrock gebruikt de standaard AWS SDK-referentieketen; er zijn geen API-sleutels nodig. Als OpenClaw op EC2 draait met een Bedrock-ingeschakelde instantierol, stel dan alleen de provider en het model in:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
SleutelTypeStandaardBeschrijving
modelstringamazon.titan-embed-text-v2:0Elk Bedrock-embeddingmodel-id
outputDimensionalitynumbermodelstandaardVoor Titan V2: 256, 512 of 1024
Ondersteunde modellen (met familiedetectie en dimensiestandaarden):
Model-idProviderStandaarddimensiesConfigureerbare dimensies
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536
amazon.titan-embed-g1-text-02Amazon1536
amazon.titan-embed-image-v1Amazon1024
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024
cohere.embed-multilingual-v3Cohere1024
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024
Varianten met throughput-suffixen (bijv. amazon.titan-embed-text-v1:2:8k) erven de configuratie van het basismodel.Authenticatie: Bedrock-auth gebruikt de standaardvolgorde voor AWS SDK-referentieresolutie:
  1. Omgevingsvariabelen (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. SSO-tokencache
  3. Referenties voor webidentiteitstokens
  4. Gedeelde referentie- en configuratiebestanden
  5. ECS- of EC2-metadatareferenties
Regio wordt opgelost via AWS_REGION, AWS_DEFAULT_REGION, de baseUrl van de amazon-bedrock-provider, of valt terug op us-east-1.IAM-machtigingen: de IAM-rol of -gebruiker heeft nodig:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Voor least privilege beperk je InvokeModel tot het specifieke model:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
SleutelTypeStandaardBeschrijving
local.modelPathstringautomatisch gedownloadPad naar GGUF-modelbestand
local.modelCacheDirstringnode-llama-cpp-standaardCachemap voor gedownloade modellen
local.contextSizenumber | "auto"4096Grootte van het contextvenster voor de embedding-context. 4096 dekt typische chunks (128–512 tokens) terwijl niet-gewicht-VRAM wordt begrensd. Verlaag naar 1024–2048 op beperkte hosts. "auto" gebruikt het getrainde maximum van het model — niet aanbevolen voor 8B+-modellen (Qwen3-Embedding-8B: 40 960 tokens → ~32 GB VRAM tegenover ~8,8 GB bij 4096).
Standaardmodel: embeddinggemma-300m-qat-Q8_0.gguf (~0,6 GB, automatisch gedownload). Vereist native build: pnpm approve-builds en daarna pnpm rebuild node-llama-cpp.Gebruik de zelfstandige CLI om hetzelfde providerpad te verifiëren dat de Gateway gebruikt:
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
Als provider auto is, wordt local alleen geselecteerd wanneer local.modelPath naar een bestaand lokaal bestand verwijst. hf:- en HTTP(S)-modelverwijzingen kunnen nog steeds expliciet worden gebruikt met provider: "local", maar ze zorgen er niet voor dat auto lokaal selecteert voordat het model op schijf beschikbaar is.

Time-out voor inline embedding

sync.embeddingBatchTimeoutSeconds
number
Overschrijf de time-out voor inline embedding-batches tijdens geheugenindexering.Niet ingesteld gebruikt de providerstandaard: 600 seconden voor lokale/zelfgehoste providers zoals local, ollama en lmstudio, en 120 seconden voor gehoste providers. Verhoog dit wanneer lokale CPU-gebonden embedding-batches gezond maar traag zijn.

Configuratie voor hybride zoeken

Alles onder memorySearch.query.hybrid:
SleutelTypeStandaardBeschrijving
enabledbooleantrueHybride BM25 + vectorzoekopdracht inschakelen
vectorWeightnumber0.7Gewicht voor vectorscores (0-1)
textWeightnumber0.3Gewicht voor BM25-scores (0-1)
candidateMultipliernumber4Vermenigvuldiger voor grootte van kandidaatpool
SleutelTypeStandaardBeschrijving
mmr.enabledbooleanfalseMMR-herordening inschakelen
mmr.lambdanumber0.70 = maximale diversiteit, 1 = maximale relevantie

Volledig voorbeeld

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

Aanvullende geheugenpaden

SleutelTypeBeschrijving
extraPathsstring[]Aanvullende mappen of bestanden om te indexeren
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
Paden kunnen absoluut of relatief ten opzichte van de workspace zijn. Mappen worden recursief gescand op .md-bestanden. Afhandeling van symlinks hangt af van de actieve backend: de ingebouwde engine negeert symlinks, terwijl QMD het gedrag van de onderliggende QMD-scanner volgt. Voor agent-gebonden transcriptzoekopdrachten tussen agents gebruikt u agents.list[].memorySearch.qmd.extraCollections in plaats van memory.qmd.paths. Die extra collecties volgen dezelfde { path, name, pattern? }-vorm, maar ze worden per agent samengevoegd en kunnen expliciete gedeelde namen behouden wanneer het pad buiten de huidige workspace wijst. Als hetzelfde opgeloste pad in zowel memory.qmd.paths als memorySearch.qmd.extraCollections voorkomt, behoudt QMD de eerste vermelding en slaat het het duplicaat over.

Multimodaal geheugen (Gemini)

Indexeer afbeeldingen en audio naast Markdown met Gemini Embedding 2:
SleutelTypeStandaardBeschrijving
multimodal.enabledbooleanfalseMultimodale indexering inschakelen
multimodal.modalitiesstring[]["image"], ["audio"], of ["all"]
multimodal.maxFileBytesnumber10000000Maximale bestandsgrootte voor indexering
Geldt alleen voor bestanden in extraPaths. Standaardgeheugenroots blijven alleen Markdown. Vereist gemini-embedding-2-preview. fallback moet "none" zijn.
Ondersteunde indelingen: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (afbeeldingen); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Embeddingcache

SleutelTypeStandaardBeschrijving
cache.enabledbooleanfalseCache chunk-embeddings in SQLite
cache.maxEntriesnumber50000Maximaal gecachete embeddings
Voorkomt het opnieuw embedden van ongewijzigde tekst tijdens herindexering of transcriptupdates.

Batchindexering

SleutelTypeStandaardBeschrijving
remote.nonBatchConcurrencynumber4Parallelle inline embeddings
remote.batch.enabledbooleanfalseBatch-embedding-API inschakelen
remote.batch.concurrencynumber2Parallelle batchtaken
remote.batch.waitbooleantrueWachten op voltooiing van batch
remote.batch.pollIntervalMsnumberPollinterval
remote.batch.timeoutMinutesnumberBatch-time-out
Beschikbaar voor openai, gemini en voyage. OpenAI-batch is doorgaans het snelst en goedkoopst voor grote backfills. remote.nonBatchConcurrency bepaalt inline embedding-aanroepen die worden gebruikt door lokale/zelfgehoste providers en gehoste providers wanneer batch-API’s van providers niet actief zijn. Ollama gebruikt standaard 1 voor niet-batchindexering om kleinere lokale hosts niet te overbelasten; stel een hogere waarde in op grotere machines. Dit staat los van sync.embeddingBatchTimeoutSeconds, dat de time-out voor inline embedding-aanroepen bepaalt.

Sessiegeheugen zoeken (experimenteel)

Indexeer sessietranscripten en maak ze beschikbaar via memory_search:
SleutelTypeStandaardBeschrijving
experimental.sessionMemorybooleanfalseSessie-indexering inschakelen
sourcesstring[]["memory"]Voeg "sessions" toe om transcripten op te nemen
sync.sessions.deltaBytesnumber100000Bytedrempel voor herindexering
sync.sessions.deltaMessagesnumber50Berichtdrempel voor herindexering
Sessie-indexering is opt-in en wordt asynchroon uitgevoerd. Resultaten kunnen enigszins verouderd zijn. Sessielogs staan op schijf, dus behandel bestandssysteemtoegang als de vertrouwensgrens.

SQLite-vectorversnelling (sqlite-vec)

SleutelTypeStandaardBeschrijving
store.vector.enabledbooleantrueGebruik sqlite-vec voor vectorqueries
store.vector.extensionPathstringmeegeleverdOverschrijf het sqlite-vec-pad
Wanneer sqlite-vec niet beschikbaar is, valt OpenClaw automatisch terug op in-process cosinusgelijkenis.

Indexopslag

SleutelTypeStandaardBeschrijving
store.pathstring~/.openclaw/memory/{agentId}.sqliteIndexlocatie (ondersteunt {agentId}-token)
store.fts.tokenizerstringunicode61FTS5-tokenizer (unicode61 of trigram)

QMD-backendconfiguratie

Stel memory.backend = "qmd" in om dit in te schakelen. Alle QMD-instellingen staan onder memory.qmd:
SleutelTypeStandaardBeschrijving
commandstringqmdPad naar QMD-uitvoerbaar bestand; stel een absoluut pad in wanneer de service-PATH verschilt van je shell
searchModestringsearchZoekopdracht: search, vsearch, query
includeDefaultMemorybooleantrueIndexeer automatisch MEMORY.md + memory/**/*.md
paths[]arrayExtra paden: { name, path, pattern? }
sessions.enabledbooleanfalseIndexeer sessietranscripten
sessions.retentionDaysnumberBewaartermijn van transcripten
sessions.exportDirstringExportdirectory
searchMode: "search" is alleen lexicaal/BM25. OpenClaw voert voor die modus geen semantische gereedheidsprobes voor vectoren of QMD-embeddingonderhoud uit, ook niet tijdens memory status --deep; vsearch en query blijven QMD-vectorgereedheid en embeddings vereisen. OpenClaw geeft de voorkeur aan huidige QMD-collecties en MCP-queryvormen, maar houdt oudere QMD-releases werkend door waar nodig compatibele vlaggen voor collectiepatronen en oudere MCP-toolnamen te proberen. Wanneer QMD ondersteuning voor meerdere collectiefilters meldt, worden collecties met dezelfde bron met één QMD-proces doorzocht; oudere QMD-builds blijven het compatibiliteitspad per collectie gebruiken. Dezelfde bron betekent dat duurzame geheugencollecties samen worden gegroepeerd, terwijl sessietranscriptcollecties een aparte groep blijven, zodat brondifferentiatie nog steeds beide invoeren heeft.
QMD-modeloverschrijvingen blijven aan de QMD-kant, niet in de OpenClaw-configuratie. Als je de modellen van QMD globaal moet overschrijven, stel dan omgevingsvariabelen zoals QMD_EMBED_MODEL, QMD_RERANK_MODEL en QMD_GENERATE_MODEL in de runtime-omgeving van de Gateway in.
SleutelTypeStandaardBeschrijving
update.intervalstring5mVernieuwingsinterval
update.debounceMsnumber15000Bestandswijzigingen debouncen
update.onBootbooleantrueVernieuwen wanneer de langlevende QMD-manager wordt geopend; stuurt ook de opt-in-opstartvernieuwing aan
update.startupstringoffOptionele vernieuwing bij Gateway-start: off, idle of immediate
update.startupDelayMsnumber120000Vertraging voordat de vernieuwing met startup: "idle" wordt uitgevoerd
update.waitForBootSyncbooleanfalseHet openen van de manager blokkeren totdat de initiële vernieuwing is voltooid
update.embedIntervalstringAfzonderlijk embedritme
update.commandTimeoutMsnumberTime-out voor QMD-commando’s
update.updateTimeoutMsnumberTime-out voor QMD-updatebewerkingen
update.embedTimeoutMsnumberTime-out voor QMD-embedbewerkingen
SleutelTypeStandaardBeschrijving
limits.maxResultsnumber6Maximaal aantal zoekresultaten
limits.maxSnippetCharsnumberFragmentlengte begrenzen
limits.maxInjectedCharsnumberTotaal aantal geïnjecteerde tekens begrenzen
limits.timeoutMsnumber4000Zoektime-out
Bepaalt welke sessies QMD-zoekresultaten kunnen ontvangen. Zelfde schema als session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
De meegeleverde standaard staat directe sessies en kanaalsessies toe, terwijl groepen nog steeds worden geweigerd.Standaard is alleen DM. match.keyPrefix komt overeen met de genormaliseerde sessiesleutel; match.rawKeyPrefix komt overeen met de ruwe sleutel inclusief agent:<id>:.
memory.citations geldt voor alle backends:
WaardeGedrag
auto (standaard)Source: <path#line>-voettekst opnemen in fragmenten
onVoettekst altijd opnemen
offVoettekst weglaten (pad wordt intern nog steeds aan de agent doorgegeven)
QMD-bootvernieuwingen gebruiken tijdens het opstarten van de Gateway een eenmalig subprocespad. De langlevende QMD-manager blijft eigenaar van de reguliere bestandswatcher en intervaltimers wanneer geheugenzoekopdrachten worden geopend voor interactief gebruik.

Volledig QMD-voorbeeld

{
  memory: {
    backend: "qmd",
    citations: "auto",
    qmd: {
      includeDefaultMemory: true,
      update: { interval: "5m", debounceMs: 15000 },
      limits: { maxResults: 6, timeoutMs: 4000 },
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

Dreaming

Dreaming wordt geconfigureerd onder plugins.entries.memory-core.config.dreaming, niet onder agents.defaults.memorySearch. Dreaming wordt uitgevoerd als één geplande sweep en gebruikt interne lichte/diepe/REM-fasen als implementatiedetail. Zie Dreaming voor conceptueel gedrag en slash-commando’s.

Gebruikersinstellingen

SleutelTypeStandaardmodelBeschrijving
enabledbooleanfalseDreaming volledig in- of uitschakelen
frequencystring0 3 * * *Optioneel Cron-ritme voor de volledige Dreaming-sweep
modelstringstandaardmodelOptionele modeloverschrijving voor de Dream Diary-subagent

Voorbeeld

{
  plugins: {
    entries: {
      "memory-core": {
        subagent: {
          allowModelOverride: true,
          allowedModels: ["anthropic/claude-sonnet-4-6"],
        },
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
            model: "anthropic/claude-sonnet-4-6",
          },
        },
      },
    },
  },
}
  • Dreaming schrijft machinestatus naar memory/.dreams/.
  • Dreaming schrijft voor mensen leesbare narratieve uitvoer naar DREAMS.md (of bestaande dreams.md).
  • dreaming.model gebruikt de bestaande vertrouwenspoort voor Plugin-subagents; stel plugins.entries.memory-core.subagent.allowModelOverride: true in voordat je dit inschakelt.
  • Dream Diary probeert het één keer opnieuw met het standaardmodel van de sessie wanneer het geconfigureerde model niet beschikbaar is. Vertrouwens- of allowlistfouten worden gelogd en worden niet stilzwijgend opnieuw geprobeerd.
  • Het beleid en de drempels voor de lichte/diepe/REM-fase zijn intern gedrag, geen gebruikersgerichte configuratie.

Gerelateerd