Questa pagina elenca ogni parametro di configurazione per la ricerca in memoria di OpenClaw. Per panoramiche concettuali, vedi: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.
Panoramica della memoria
Come funziona la memoria.
Motore integrato
Backend SQLite predefinito.
Motore QMD
Sidecar local-first.
Ricerca in memoria
Pipeline di ricerca e ottimizzazione.
Active memory
Sotto-agente di memoria per sessioni interattive.
agents.defaults.memorySearch in openclaw.json, salvo indicazione diversa.
Se cerchi l’interruttore della funzionalità Active Memory e la configurazione del sotto-agente, si trovano invece sotto
plugins.entries.active-memory anziché memorySearch.Active memory usa un modello a due gate:- il plugin deve essere abilitato e deve puntare all’id dell’agente corrente
- la richiesta deve essere una sessione di chat interattiva persistente idonea
Selezione del provider
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
provider | string | rilevato automaticamente | ID dell’adapter di embedding come bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai o voyage; può anche essere un models.providers.<id> configurato il cui api punta a uno di questi adapter |
model | string | predefinito del provider | Nome del modello di embedding |
fallback | string | "none" | ID dell’adapter di fallback quando quello principale non riesce |
enabled | boolean | true | Abilita o disabilita la ricerca in memoria |
Ordine di rilevamento automatico
Quandoprovider non è impostato, OpenClaw seleziona il primo disponibile:
github-copilot
Selezionato se è possibile risolvere un token GitHub Copilot (variabile d’ambiente o profilo di autenticazione).
ollama è supportato ma non viene rilevato automaticamente (impostalo esplicitamente).
ID di provider personalizzati
memorySearch.provider può puntare a una voce personalizzata models.providers.<id>. OpenClaw risolve il proprietario api di quel provider per l’adapter di embedding, preservando al tempo stesso l’id del provider personalizzato per la gestione di endpoint, autenticazione e prefissi dei modelli. Questo consente a configurazioni multi-GPU o multi-host di dedicare gli embedding della memoria a uno specifico endpoint locale:
Risoluzione della chiave API
Gli embedding remoti richiedono una chiave API. Bedrock usa invece la catena di credenziali predefinita dell’SDK AWS (ruoli dell’istanza, SSO, chiavi di accesso).| Provider | Variabile d’ambiente | Chiave di configurazione |
|---|---|---|
| Bedrock | Catena di credenziali AWS | Nessuna chiave API necessaria |
| DeepInfra | DEEPINFRA_API_KEY | models.providers.deepinfra.apiKey |
| Gemini | GEMINI_API_KEY | models.providers.google.apiKey |
| GitHub Copilot | COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN | Profilo di autenticazione tramite login del dispositivo |
| Mistral | MISTRAL_API_KEY | models.providers.mistral.apiKey |
| Ollama | OLLAMA_API_KEY (placeholder) | — |
| OpenAI | OPENAI_API_KEY | models.providers.openai.apiKey |
| Voyage | VOYAGE_API_KEY | models.providers.voyage.apiKey |
Codex OAuth copre solo chat/completions e non soddisfa le richieste di embedding.
Configurazione dell’endpoint remoto
Per endpoint personalizzati compatibili con OpenAI o per sovrascrivere i valori predefiniti del provider:URL base API personalizzato.
Sovrascrive la chiave API.
Header HTTP aggiuntivi (uniti ai valori predefiniti del provider).
Configurazione specifica del provider
Gemini
Gemini
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
model | string | gemini-embedding-001 | Supporta anche gemini-embedding-2-preview |
outputDimensionality | number | 3072 | Per Embedding 2: 768, 1536 o 3072 |
Tipi di input compatibili con OpenAI
Tipi di input compatibili con OpenAI
Gli endpoint di embedding compatibili con OpenAI possono aderire ai campi di richiesta
La modifica di questi valori influisce sull’identità della cache degli embedding per l’indicizzazione batch del provider e dovrebbe essere seguita da una reindicizzazione della memoria quando il modello upstream tratta le etichette in modo diverso.
input_type specifici del provider. È utile per i modelli di embedding asimmetrici che richiedono etichette diverse per embedding di query e documenti.| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
inputType | string | non impostato | input_type condiviso per embedding di query e documenti |
queryInputType | string | non impostato | input_type in fase di query; sovrascrive inputType |
documentInputType | string | non impostato | input_type di indice/documento; sovrascrive inputType |
Bedrock
Bedrock
Configurazione degli embedding Bedrock
Bedrock usa la catena di credenziali predefinita dell’SDK AWS: non servono chiavi API. Se OpenClaw viene eseguito su EC2 con un ruolo dell’istanza abilitato per Bedrock, imposta semplicemente provider e modello:| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
model | string | amazon.titan-embed-text-v2:0 | Qualsiasi ID modello di embedding Bedrock |
outputDimensionality | number | predefinito del modello | Per Titan V2: 256, 512 o 1024 |
| ID modello | Provider | Dimensioni predefinite | Dimensioni configurabili |
|---|---|---|---|
amazon.titan-embed-text-v2:0 | Amazon | 1024 | 256, 512, 1024 |
amazon.titan-embed-text-v1 | Amazon | 1536 | — |
amazon.titan-embed-g1-text-02 | Amazon | 1536 | — |
amazon.titan-embed-image-v1 | Amazon | 1024 | — |
amazon.nova-2-multimodal-embeddings-v1:0 | Amazon | 1024 | 256, 384, 1024, 3072 |
cohere.embed-english-v3 | Cohere | 1024 | — |
cohere.embed-multilingual-v3 | Cohere | 1024 | — |
cohere.embed-v4:0 | Cohere | 1536 | 256-1536 |
twelvelabs.marengo-embed-3-0-v1:0 | TwelveLabs | 512 | — |
twelvelabs.marengo-embed-2-7-v1:0 | TwelveLabs | 1024 | — |
amazon.titan-embed-text-v1:2:8k) ereditano la configurazione del modello base.Autenticazione: l’autenticazione Bedrock usa l’ordine standard di risoluzione delle credenziali dell’SDK AWS:- Variabili d’ambiente (
AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY) - Cache dei token SSO
- Credenziali con token di identità web
- File di credenziali e configurazione condivisi
- Credenziali dei metadati ECS o EC2
AWS_REGION, AWS_DEFAULT_REGION, dal baseUrl del provider amazon-bedrock o, per impostazione predefinita, da us-east-1.Autorizzazioni IAM: il ruolo o l’utente IAM necessita di:InvokeModel al modello specifico:Locale (GGUF + node-llama-cpp)
Locale (GGUF + node-llama-cpp)
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
local.modelPath | string | scaricato automaticamente | Percorso del file modello GGUF |
local.modelCacheDir | string | predefinito di node-llama-cpp | Directory cache per i modelli scaricati |
local.contextSize | number | "auto" | 4096 | Dimensione della finestra di contesto per il contesto di embedding. 4096 copre i chunk tipici (128-512 token) limitando al tempo stesso la VRAM non occupata dai pesi. Riduci a 1024-2048 su host con risorse limitate. "auto" usa il massimo addestrato del modello, non consigliato per modelli 8B+ (Qwen3-Embedding-8B: 40 960 token -> ~32 GB di VRAM contro ~8,8 GB a 4096). |
embeddinggemma-300m-qat-Q8_0.gguf (~0,6 GB, scaricato automaticamente). I checkout sorgente richiedono comunque l’approvazione della build nativa: pnpm approve-builds poi pnpm rebuild node-llama-cpp.Usa la CLI autonoma per verificare lo stesso percorso provider usato dal Gateway:provider è auto, local viene selezionato solo quando local.modelPath punta a un file locale esistente. I riferimenti a modelli hf: e HTTP(S) possono comunque essere usati esplicitamente con provider: "local", ma non fanno sì che auto selezioni local prima che il modello sia disponibile su disco.Timeout dell’embedding inline
Sovrascrive il timeout per i batch di embedding inline durante l’indicizzazione della memoria.Se non impostato, usa il predefinito del provider: 600 secondi per provider locali/self-hosted come
local, ollama e lmstudio, e 120 secondi per provider hosted. Aumenta questo valore quando i batch di embedding locali vincolati dalla CPU sono sani ma lenti.Configurazione della ricerca ibrida
Tutto sottomemorySearch.query.hybrid:
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
enabled | boolean | true | Abilita la ricerca ibrida BM25 + vettoriale |
vectorWeight | number | 0.7 | Peso per i punteggi vettoriali (0-1) |
textWeight | number | 0.3 | Peso per i punteggi BM25 (0-1) |
candidateMultiplier | number | 4 | Moltiplicatore della dimensione del pool di candidati |
- MMR (diversità)
- Decadimento temporale (recenza)
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
mmr.enabled | boolean | false | Abilita il riordinamento MMR |
mmr.lambda | number | 0.7 | 0 = massima diversità, 1 = massima rilevanza |
Esempio completo
Percorsi memoria aggiuntivi
| Chiave | Tipo | Descrizione |
|---|---|---|
extraPaths | string[] | Directory o file aggiuntivi da indicizzare |
.md. La gestione dei symlink dipende dal backend attivo: il motore integrato ignora i symlink, mentre QMD segue il comportamento dello scanner QMD sottostante.
Per la ricerca nei transcript tra agenti con ambito agente, usa agents.list[].memorySearch.qmd.extraCollections invece di memory.qmd.paths. Quelle collezioni extra seguono la stessa forma { path, name, pattern? }, ma vengono unite per agente e possono preservare nomi condivisi espliciti quando il percorso punta fuori dal workspace corrente. Se lo stesso percorso risolto appare sia in memory.qmd.paths sia in memorySearch.qmd.extraCollections, QMD mantiene la prima voce e salta il duplicato.
Memoria multimodale (Gemini)
Indicizza immagini e audio insieme al Markdown usando Gemini Embedding 2:| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
multimodal.enabled | boolean | false | Abilita l’indicizzazione multimodale |
multimodal.modalities | string[] | — | ["image"], ["audio"] o ["all"] |
multimodal.maxFileBytes | number | 10000000 | Dimensione massima file per l’indicizzazione |
Si applica solo ai file in
extraPaths. Le radici di memoria predefinite restano solo Markdown. Richiede gemini-embedding-2-preview. fallback deve essere "none"..jpg, .jpeg, .png, .webp, .gif, .heic, .heif (immagini); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).
Cache degli embedding
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
cache.enabled | boolean | false | Memorizza gli embedding dei chunk in SQLite |
cache.maxEntries | number | 50000 | Numero massimo di embedding memorizzati nella cache |
Indicizzazione batch
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
remote.nonBatchConcurrency | number | 4 | Embedding inline paralleli |
remote.batch.enabled | boolean | false | Abilita l’API di embedding batch |
remote.batch.concurrency | number | 2 | Job batch paralleli |
remote.batch.wait | boolean | true | Attendi il completamento del batch |
remote.batch.pollIntervalMs | number | — | Intervallo di polling |
remote.batch.timeoutMinutes | number | — | Timeout del batch |
openai, gemini e voyage. Il batch OpenAI è in genere il più rapido ed economico per backfill di grandi dimensioni.
remote.nonBatchConcurrency controlla le chiamate di embedding inline usate dai provider locali/self-hosted e dai provider ospitati quando le API batch del provider non sono attive. Ollama usa per impostazione predefinita 1 per l’indicizzazione non batch per evitare di sovraccaricare host locali più piccoli; imposta un valore più alto su macchine più grandi.
Questo è separato da sync.embeddingBatchTimeoutSeconds, che controlla il timeout per le chiamate di embedding inline.
Ricerca nella memoria delle sessioni (sperimentale)
Indicizza le trascrizioni delle sessioni e rendile disponibili tramitememory_search:
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
experimental.sessionMemory | boolean | false | Abilita l’indicizzazione delle sessioni |
sources | string[] | ["memory"] | Aggiungi "sessions" per includere le trascrizioni |
sync.sessions.deltaBytes | number | 100000 | Soglia in byte per la reindicizzazione |
sync.sessions.deltaMessages | number | 50 | Soglia di messaggi per la reindicizzazione |
Accelerazione vettoriale SQLite (sqlite-vec)
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
store.vector.enabled | boolean | true | Usa sqlite-vec per le query vettoriali |
store.vector.extensionPath | string | incluso | Sovrascrivi il percorso di sqlite-vec |
Archiviazione dell’indice
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
store.path | string | ~/.openclaw/memory/{agentId}.sqlite | Posizione dell’indice (supporta il token {agentId}) |
store.fts.tokenizer | string | unicode61 | Tokenizer FTS5 (unicode61 o trigram) |
Configurazione del backend QMD
Impostamemory.backend = "qmd" per abilitarlo. Tutte le impostazioni QMD risiedono sotto memory.qmd:
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
command | string | qmd | Percorso dell’eseguibile QMD; imposta un percorso assoluto quando il PATH del servizio differisce dalla tua shell |
searchMode | string | search | Comando di ricerca: search, vsearch, query |
includeDefaultMemory | boolean | true | Indicizza automaticamente MEMORY.md + memory/**/*.md |
paths[] | array | — | Percorsi extra: { name, path, pattern? } |
sessions.enabled | boolean | false | Indicizza le trascrizioni delle sessioni |
sessions.retentionDays | number | — | Conservazione delle trascrizioni |
sessions.exportDir | string | — | Directory di esportazione |
searchMode: "search" è solo lessicale/BM25. OpenClaw non esegue sonde di prontezza vettoriale semantica né manutenzione degli embedding QMD per quella modalità, anche durante memory status --deep; vsearch e query continuano a richiedere la prontezza vettoriale QMD e gli embedding.
OpenClaw preferisce la raccolta QMD corrente e le forme di query MCP, ma mantiene funzionanti le versioni QMD precedenti provando flag compatibili per i pattern di raccolta e nomi di strumenti MCP più vecchi quando necessario. Quando QMD dichiara il supporto per più filtri di raccolta, le raccolte della stessa origine vengono cercate con un solo processo QMD; le build QMD più vecchie mantengono il percorso di compatibilità per raccolta. Stessa origine significa che le raccolte di memoria duratura sono raggruppate insieme, mentre le raccolte delle trascrizioni di sessione restano un gruppo separato, così la diversificazione delle fonti mantiene comunque entrambi gli input.
Gli override dei modelli QMD restano sul lato QMD, non nella configurazione OpenClaw. Se devi sovrascrivere globalmente i modelli di QMD, imposta variabili di ambiente come
QMD_EMBED_MODEL, QMD_RERANK_MODEL e QMD_GENERATE_MODEL nell’ambiente di runtime del gateway.Pianificazione degli aggiornamenti
Pianificazione degli aggiornamenti
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
update.interval | string | 5m | Intervallo di aggiornamento |
update.debounceMs | number | 15000 | Debounce delle modifiche ai file |
update.onBoot | boolean | true | Aggiorna quando il gestore QMD a lunga durata si apre; controlla anche l’aggiornamento all’avvio su consenso esplicito |
update.startup | string | off | Aggiornamento opzionale all’avvio del gateway: off, idle o immediate |
update.startupDelayMs | number | 120000 | Ritardo prima dell’esecuzione dell’aggiornamento startup: "idle" |
update.waitForBootSync | boolean | false | Blocca l’apertura del gestore finché l’aggiornamento iniziale non è completato |
update.embedInterval | string | — | Cadenza separata per gli embedding |
update.commandTimeoutMs | number | — | Timeout per i comandi QMD |
update.updateTimeoutMs | number | — | Timeout per le operazioni di aggiornamento QMD |
update.embedTimeoutMs | number | — | Timeout per le operazioni di embedding QMD |
Limiti
Limiti
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
limits.maxResults | number | 6 | Risultati di ricerca massimi |
limits.maxSnippetChars | number | — | Limita la lunghezza dello snippet |
limits.maxInjectedChars | number | — | Limita i caratteri iniettati totali |
limits.timeoutMs | number | 4000 | Timeout della ricerca |
Ambito
Ambito
Controlla quali sessioni possono ricevere risultati di ricerca QMD. Stesso schema di Il valore predefinito distribuito consente sessioni dirette e di canale, continuando a negare i gruppi.Il valore predefinito è solo DM.
session.sendPolicy:match.keyPrefix corrisponde alla chiave di sessione normalizzata; match.rawKeyPrefix corrisponde alla chiave grezza, incluso agent:<id>:.Citazioni
Citazioni
memory.citations si applica a tutti i backend:| Valore | Comportamento |
|---|---|
auto (predefinito) | Include il footer Source: <path#line> negli snippet |
on | Include sempre il footer |
off | Omette il footer (il percorso viene comunque passato internamente all’agente) |
Esempio QMD completo
Dreaming
Dreaming è configurato inplugins.entries.memory-core.config.dreaming, non in agents.defaults.memorySearch.
Dreaming viene eseguito come una singola scansione pianificata e usa fasi interne light/deep/REM come dettaglio di implementazione.
Per il comportamento concettuale e i comandi slash, consulta Dreaming.
Impostazioni utente
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
enabled | boolean | false | Abilita o disabilita completamente Dreaming |
frequency | string | 0 3 * * * | Cadenza cron opzionale per la scansione Dreaming completa |
model | string | modello predefinito | Override opzionale del modello del subagente Dream Diary |
Esempio
- Dreaming scrive lo stato della macchina in
memory/.dreams/. - Dreaming scrive l’output narrativo leggibile da persone in
DREAMS.md(o nel filedreams.mdesistente). dreaming.modelusa il gate di fiducia esistente del subagente del plugin; impostaplugins.entries.memory-core.subagent.allowModelOverride: trueprima di abilitarlo.- Dream Diary riprova una volta con il modello predefinito della sessione quando il modello configurato non è disponibile. Gli errori di fiducia o allowlist vengono registrati e non vengono riprovati silenziosamente.
- La policy e le soglie delle fasi light/deep/REM sono comportamento interno, non configurazione rivolta all’utente.