Vai al contenuto principale

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.

Questa pagina elenca ogni parametro di configurazione per la ricerca in memoria di OpenClaw. Per panoramiche concettuali, vedi:

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.
Tutte le impostazioni della ricerca in memoria si trovano sotto 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:
  1. il plugin deve essere abilitato e deve puntare all’id dell’agente corrente
  2. la richiesta deve essere una sessione di chat interattiva persistente idonea
Vedi Active Memory per il modello di attivazione, la configurazione gestita dal plugin, la persistenza della trascrizione e il modello di rollout sicuro.

Selezione del provider

ChiaveTipoPredefinitoDescrizione
providerstringrilevato automaticamenteID 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
modelstringpredefinito del providerNome del modello di embedding
fallbackstring"none"ID dell’adapter di fallback quando quello principale non riesce
enabledbooleantrueAbilita o disabilita la ricerca in memoria

Ordine di rilevamento automatico

Quando provider non è impostato, OpenClaw seleziona il primo disponibile:
1

local

Selezionato se memorySearch.local.modelPath è configurato e il file esiste.
2

github-copilot

Selezionato se è possibile risolvere un token GitHub Copilot (variabile d’ambiente o profilo di autenticazione).
3

openai

Selezionato se è possibile risolvere una chiave OpenAI.
4

gemini

Selezionato se è possibile risolvere una chiave Gemini.
5

voyage

Selezionato se è possibile risolvere una chiave Voyage.
6

mistral

Selezionato se è possibile risolvere una chiave Mistral.
7

deepinfra

Selezionato se è possibile risolvere una chiave DeepInfra.
8

bedrock

Selezionato se la catena di credenziali dell’SDK AWS viene risolta (ruolo dell’istanza, chiavi di accesso, profilo, SSO, identità web o configurazione condivisa).
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:
{
  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",
      },
    },
  },
}

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).
ProviderVariabile d’ambienteChiave di configurazione
BedrockCatena di credenziali AWSNessuna chiave API necessaria
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENProfilo di autenticazione tramite login del dispositivo
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (placeholder)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.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:
remote.baseUrl
string
URL base API personalizzato.
remote.apiKey
string
Sovrascrive la chiave API.
remote.headers
object
Header HTTP aggiuntivi (uniti ai valori predefiniti del provider).
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Configurazione specifica del provider

ChiaveTipoPredefinitoDescrizione
modelstringgemini-embedding-001Supporta anche gemini-embedding-2-preview
outputDimensionalitynumber3072Per Embedding 2: 768, 1536 o 3072
La modifica del modello o di outputDimensionality attiva una reindicizzazione completa automatica.
Gli endpoint di embedding compatibili con OpenAI possono aderire ai campi di richiesta input_type specifici del provider. È utile per i modelli di embedding asimmetrici che richiedono etichette diverse per embedding di query e documenti.
ChiaveTipoPredefinitoDescrizione
inputTypestringnon impostatoinput_type condiviso per embedding di query e documenti
queryInputTypestringnon impostatoinput_type in fase di query; sovrascrive inputType
documentInputTypestringnon impostatoinput_type di indice/documento; sovrascrive inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
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.

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:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
ChiaveTipoPredefinitoDescrizione
modelstringamazon.titan-embed-text-v2:0Qualsiasi ID modello di embedding Bedrock
outputDimensionalitynumberpredefinito del modelloPer Titan V2: 256, 512 o 1024
Modelli supportati (con rilevamento della famiglia e dimensioni predefinite):
ID modelloProviderDimensioni predefiniteDimensioni configurabili
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
Le varianti con suffisso di throughput (ad esempio 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:
  1. Variabili d’ambiente (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. Cache dei token SSO
  3. Credenziali con token di identità web
  4. File di credenziali e configurazione condivisi
  5. Credenziali dei metadati ECS o EC2
La regione viene risolta da 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:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Per il privilegio minimo, limita l’ambito di InvokeModel al modello specifico:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
ChiaveTipoPredefinitoDescrizione
local.modelPathstringscaricato automaticamentePercorso del file modello GGUF
local.modelCacheDirstringpredefinito di node-llama-cppDirectory cache per i modelli scaricati
local.contextSizenumber | "auto"4096Dimensione 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).
Modello predefinito: 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:
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
Se 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

sync.embeddingBatchTimeoutSeconds
number
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 sotto memorySearch.query.hybrid:
ChiaveTipoPredefinitoDescrizione
enabledbooleantrueAbilita la ricerca ibrida BM25 + vettoriale
vectorWeightnumber0.7Peso per i punteggi vettoriali (0-1)
textWeightnumber0.3Peso per i punteggi BM25 (0-1)
candidateMultipliernumber4Moltiplicatore della dimensione del pool di candidati
ChiaveTipoPredefinitoDescrizione
mmr.enabledbooleanfalseAbilita il riordinamento MMR
mmr.lambdanumber0.70 = massima diversità, 1 = massima rilevanza

Esempio completo

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

Percorsi memoria aggiuntivi

ChiaveTipoDescrizione
extraPathsstring[]Directory o file aggiuntivi da indicizzare
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
I percorsi possono essere assoluti o relativi al workspace. Le directory vengono scansionate ricorsivamente alla ricerca di file .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:
ChiaveTipoPredefinitoDescrizione
multimodal.enabledbooleanfalseAbilita l’indicizzazione multimodale
multimodal.modalitiesstring[]["image"], ["audio"] o ["all"]
multimodal.maxFileBytesnumber10000000Dimensione 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".
Formati supportati: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (immagini); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Cache degli embedding

ChiaveTipoPredefinitoDescrizione
cache.enabledbooleanfalseMemorizza gli embedding dei chunk in SQLite
cache.maxEntriesnumber50000Numero massimo di embedding memorizzati nella cache
Evita di rigenerare gli embedding del testo invariato durante la reindicizzazione o gli aggiornamenti delle trascrizioni.

Indicizzazione batch

ChiaveTipoPredefinitoDescrizione
remote.nonBatchConcurrencynumber4Embedding inline paralleli
remote.batch.enabledbooleanfalseAbilita l’API di embedding batch
remote.batch.concurrencynumber2Job batch paralleli
remote.batch.waitbooleantrueAttendi il completamento del batch
remote.batch.pollIntervalMsnumberIntervallo di polling
remote.batch.timeoutMinutesnumberTimeout del batch
Disponibile per 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 tramite memory_search:
ChiaveTipoPredefinitoDescrizione
experimental.sessionMemorybooleanfalseAbilita l’indicizzazione delle sessioni
sourcesstring[]["memory"]Aggiungi "sessions" per includere le trascrizioni
sync.sessions.deltaBytesnumber100000Soglia in byte per la reindicizzazione
sync.sessions.deltaMessagesnumber50Soglia di messaggi per la reindicizzazione
L’indicizzazione delle sessioni è opt-in e viene eseguita in modo asincrono. I risultati possono essere leggermente obsoleti. I log delle sessioni risiedono su disco, quindi considera l’accesso al filesystem come il confine di attendibilità.

Accelerazione vettoriale SQLite (sqlite-vec)

ChiaveTipoPredefinitoDescrizione
store.vector.enabledbooleantrueUsa sqlite-vec per le query vettoriali
store.vector.extensionPathstringinclusoSovrascrivi il percorso di sqlite-vec
Quando sqlite-vec non è disponibile, OpenClaw ripiega automaticamente sulla similarità coseno in-process.

Archiviazione dell’indice

ChiaveTipoPredefinitoDescrizione
store.pathstring~/.openclaw/memory/{agentId}.sqlitePosizione dell’indice (supporta il token {agentId})
store.fts.tokenizerstringunicode61Tokenizer FTS5 (unicode61 o trigram)

Configurazione del backend QMD

Imposta memory.backend = "qmd" per abilitarlo. Tutte le impostazioni QMD risiedono sotto memory.qmd:
ChiaveTipoPredefinitoDescrizione
commandstringqmdPercorso dell’eseguibile QMD; imposta un percorso assoluto quando il PATH del servizio differisce dalla tua shell
searchModestringsearchComando di ricerca: search, vsearch, query
includeDefaultMemorybooleantrueIndicizza automaticamente MEMORY.md + memory/**/*.md
paths[]arrayPercorsi extra: { name, path, pattern? }
sessions.enabledbooleanfalseIndicizza le trascrizioni delle sessioni
sessions.retentionDaysnumberConservazione delle trascrizioni
sessions.exportDirstringDirectory 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.
ChiaveTipoPredefinitoDescrizione
update.intervalstring5mIntervallo di aggiornamento
update.debounceMsnumber15000Debounce delle modifiche ai file
update.onBootbooleantrueAggiorna quando il gestore QMD a lunga durata si apre; controlla anche l’aggiornamento all’avvio su consenso esplicito
update.startupstringoffAggiornamento opzionale all’avvio del gateway: off, idle o immediate
update.startupDelayMsnumber120000Ritardo prima dell’esecuzione dell’aggiornamento startup: "idle"
update.waitForBootSyncbooleanfalseBlocca l’apertura del gestore finché l’aggiornamento iniziale non è completato
update.embedIntervalstringCadenza separata per gli embedding
update.commandTimeoutMsnumberTimeout per i comandi QMD
update.updateTimeoutMsnumberTimeout per le operazioni di aggiornamento QMD
update.embedTimeoutMsnumberTimeout per le operazioni di embedding QMD
ChiaveTipoPredefinitoDescrizione
limits.maxResultsnumber6Risultati di ricerca massimi
limits.maxSnippetCharsnumberLimita la lunghezza dello snippet
limits.maxInjectedCharsnumberLimita i caratteri iniettati totali
limits.timeoutMsnumber4000Timeout della ricerca
Controlla quali sessioni possono ricevere risultati di ricerca QMD. Stesso schema di session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
Il valore predefinito distribuito consente sessioni dirette e di canale, continuando a negare i gruppi.Il valore predefinito è solo DM. match.keyPrefix corrisponde alla chiave di sessione normalizzata; match.rawKeyPrefix corrisponde alla chiave grezza, incluso agent:<id>:.
memory.citations si applica a tutti i backend:
ValoreComportamento
auto (predefinito)Include il footer Source: <path#line> negli snippet
onInclude sempre il footer
offOmette il footer (il percorso viene comunque passato internamente all’agente)
Gli aggiornamenti all’avvio QMD usano un percorso subprocess monouso durante l’avvio del gateway. Il gestore QMD a lunga durata possiede comunque il file watcher regolare e i timer a intervallo quando la ricerca in memoria viene aperta per l’uso interattivo.

Esempio QMD completo

{
  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 è configurato in plugins.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

ChiaveTipoPredefinitoDescrizione
enabledbooleanfalseAbilita o disabilita completamente Dreaming
frequencystring0 3 * * *Cadenza cron opzionale per la scansione Dreaming completa
modelstringmodello predefinitoOverride opzionale del modello del subagente Dream Diary

Esempio

{
  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 scrive lo stato della macchina in memory/.dreams/.
  • Dreaming scrive l’output narrativo leggibile da persone in DREAMS.md (o nel file dreams.md esistente).
  • dreaming.model usa il gate di fiducia esistente del subagente del plugin; imposta plugins.entries.memory-core.subagent.allowModelOverride: true prima 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.

Correlati