Passer au contenu principal

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.

Cette page répertorie chaque paramètre de configuration de la recherche de mémoire OpenClaw. Pour des présentations conceptuelles, consultez :

Memory overview

Fonctionnement de la mémoire.

Builtin engine

Backend SQLite par défaut.

QMD engine

Sidecar local-first.

Memory search

Pipeline de recherche et réglages.

Active memory

Sous-agent de mémoire pour les sessions interactives.
Tous les paramètres de recherche de mémoire se trouvent sous agents.defaults.memorySearch dans openclaw.json, sauf indication contraire.
Si vous cherchez l’interrupteur de la fonctionnalité active memory et la configuration du sous-agent, ils se trouvent sous plugins.entries.active-memory plutôt que sous memorySearch.Active memory utilise un modèle à deux barrières :
  1. le plugin doit être activé et cibler l’ID de l’agent actuel
  2. la requête doit être une session de chat persistante interactive éligible
Consultez Active Memory pour le modèle d’activation, la configuration détenue par le plugin, la persistance des transcriptions et le modèle de déploiement sûr.

Sélection du fournisseur

CléTypeValeur par défautDescription
providerstringauto-détectéID d’adaptateur d’embedding tel que bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai ou voyage ; peut aussi être un models.providers.<id> configuré dont api pointe vers l’un de ces adaptateurs
modelstringvaleur par défaut du fournisseurNom du modèle d’embedding
fallbackstring"none"ID de l’adaptateur de secours lorsque le principal échoue
enabledbooleantrueActiver ou désactiver la recherche de mémoire

Ordre d’auto-détection

Lorsque provider n’est pas défini, OpenClaw sélectionne le premier disponible :
1

local

Sélectionné si memorySearch.local.modelPath est configuré et que le fichier existe.
2

github-copilot

Sélectionné si un jeton GitHub Copilot peut être résolu (variable d’environnement ou profil d’authentification).
3

openai

Sélectionné si une clé OpenAI peut être résolue.
4

gemini

Sélectionné si une clé Gemini peut être résolue.
5

voyage

Sélectionné si une clé Voyage peut être résolue.
6

mistral

Sélectionné si une clé Mistral peut être résolue.
7

deepinfra

Sélectionné si une clé DeepInfra peut être résolue.
8

bedrock

Sélectionné si la chaîne d’identifiants AWS SDK se résout (rôle d’instance, clés d’accès, profil, SSO, identité web ou configuration partagée).
ollama est pris en charge mais n’est pas auto-détecté (définissez-le explicitement).

ID de fournisseurs personnalisés

memorySearch.provider peut pointer vers une entrée models.providers.<id> personnalisée. OpenClaw résout le propriétaire api de ce fournisseur pour l’adaptateur d’embedding tout en préservant l’ID de fournisseur personnalisé pour la gestion du point de terminaison, de l’authentification et du préfixe de modèle. Cela permet aux configurations multi-GPU ou multi-hôtes de dédier les embeddings de mémoire à un point de terminaison local précis :
{
  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",
      },
    },
  },
}

Résolution de la clé API

Les embeddings distants nécessitent une clé API. Bedrock utilise à la place la chaîne d’identifiants par défaut AWS SDK (rôles d’instance, SSO, clés d’accès).
FournisseurVariable d’environnementClé de configuration
BedrockChaîne d’identifiants AWSAucune clé API nécessaire
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENProfil d’authentification via connexion d’appareil
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (placeholder)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
Codex OAuth couvre uniquement le chat et les complétions, et ne satisfait pas les requêtes d’embedding.

Configuration du point de terminaison distant

Pour les points de terminaison personnalisés compatibles OpenAI ou pour remplacer les valeurs par défaut du fournisseur :
remote.baseUrl
string
URL de base API personnalisée.
remote.apiKey
string
Remplacer la clé API.
remote.headers
object
En-têtes HTTP supplémentaires (fusionnés avec les valeurs par défaut du fournisseur).
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Configuration propre au fournisseur

CléTypeValeur par défautDescription
modelstringgemini-embedding-001Prend aussi en charge gemini-embedding-2-preview
outputDimensionalitynumber3072Pour Embedding 2 : 768, 1536 ou 3072
Changer de modèle ou modifier outputDimensionality déclenche une réindexation complète automatique.
Les points de terminaison d’embedding compatibles OpenAI peuvent choisir d’utiliser des champs de requête input_type propres au fournisseur. C’est utile pour les modèles d’embedding asymétriques qui nécessitent des libellés différents pour les embeddings de requête et de document.
CléTypeValeur par défautDescription
inputTypestringnon définiinput_type partagé pour les embeddings de requête et de document
queryInputTypestringnon définiinput_type au moment de la requête ; remplace inputType
documentInputTypestringnon définiinput_type d’index/document ; remplace inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
Modifier ces valeurs affecte l’identité du cache d’embedding pour l’indexation par lots du fournisseur et doit être suivi d’une réindexation de la mémoire lorsque le modèle amont traite les libellés différemment.

Configuration d’embedding Bedrock

Bedrock utilise la chaîne d’identifiants par défaut AWS SDK ; aucune clé API n’est nécessaire. Si OpenClaw s’exécute sur EC2 avec un rôle d’instance activé pour Bedrock, définissez simplement le fournisseur et le modèle :
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
CléTypeValeur par défautDescription
modelstringamazon.titan-embed-text-v2:0Tout ID de modèle d’embedding Bedrock
outputDimensionalitynumbervaleur par défaut du modèlePour Titan V2 : 256, 512 ou 1024
Modèles pris en charge (avec détection de famille et dimensions par défaut) :
ID du modèleFournisseurDimensions par défautDimensions configurables
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
Les variantes suffixées par le débit (par exemple, amazon.titan-embed-text-v1:2:8k) héritent de la configuration du modèle de base.Authentification : l’authentification Bedrock utilise l’ordre standard de résolution des identifiants AWS SDK :
  1. Variables d’environnement (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. Cache de jetons SSO
  3. Identifiants de jeton d’identité web
  4. Fichiers d’identifiants et de configuration partagés
  5. Identifiants de métadonnées ECS ou EC2
La région est résolue à partir de AWS_REGION, AWS_DEFAULT_REGION, du baseUrl du fournisseur amazon-bedrock, ou prend par défaut la valeur us-east-1.Autorisations IAM : le rôle ou l’utilisateur IAM a besoin de :
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Pour le moindre privilège, limitez la portée de InvokeModel au modèle précis :
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
CléTypePar défautDescription
local.modelPathstringtéléchargé automatiquementChemin vers le fichier de modèle GGUF
local.modelCacheDirstringvaleur par défaut de node-llama-cppRépertoire de cache pour les modèles téléchargés
local.contextSizenumber | "auto"4096Taille de la fenêtre de contexte pour le contexte de vectorisation. 4096 couvre les fragments typiques (128 à 512 jetons) tout en limitant la VRAM hors poids. Réduisez à 1024-2048 sur les hôtes contraints. "auto" utilise le maximum d’entraînement du modèle, ce qui n’est pas recommandé pour les modèles 8B+ (Qwen3-Embedding-8B : 40 960 jetons -> ~32 Go de VRAM contre ~8,8 Go à 4096).
Modèle par défaut : embeddinggemma-300m-qat-Q8_0.gguf (~0,6 Go, téléchargé automatiquement). Les extractions de source nécessitent toujours l’approbation de compilation native : pnpm approve-builds puis pnpm rebuild node-llama-cpp.Utilisez la CLI autonome pour vérifier le même chemin de fournisseur que celui utilisé par le Gateway :
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
Si provider vaut auto, local n’est sélectionné que lorsque local.modelPath pointe vers un fichier local existant. Les références de modèle hf: et HTTP(S) peuvent toujours être utilisées explicitement avec provider: "local", mais elles ne font pas sélectionner local par auto avant que le modèle soit disponible sur le disque.

Délai d’expiration de la vectorisation en ligne

sync.embeddingBatchTimeoutSeconds
number
Remplacez le délai d’expiration des lots de vectorisation en ligne pendant l’indexation de la mémoire.Non défini, utilise la valeur par défaut du fournisseur : 600 secondes pour les fournisseurs locaux/auto-hébergés tels que local, ollama et lmstudio, et 120 secondes pour les fournisseurs hébergés. Augmentez cette valeur lorsque les lots de vectorisation locaux liés au CPU sont sains mais lents.

Configuration de la recherche hybride

Tout se trouve sous memorySearch.query.hybrid :
CléTypePar défautDescription
enabledbooleantrueActiver la recherche hybride BM25 + vectorielle
vectorWeightnumber0.7Poids des scores vectoriels (0-1)
textWeightnumber0.3Poids des scores BM25 (0-1)
candidateMultipliernumber4Multiplicateur de taille du pool de candidats
CléTypePar défautDescription
mmr.enabledbooleanfalseActiver le reclassement MMR
mmr.lambdanumber0.70 = diversité maximale, 1 = pertinence maximale

Exemple complet

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

Chemins de mémoire supplémentaires

CléTypeDescription
extraPathsstring[]Répertoires ou fichiers supplémentaires à indexer
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
Les chemins peuvent être absolus ou relatifs à l’espace de travail. Les répertoires sont analysés récursivement pour les fichiers .md. La gestion des liens symboliques dépend du backend actif : le moteur intégré ignore les liens symboliques, tandis que QMD suit le comportement du scanner QMD sous-jacent. Pour la recherche de transcriptions inter-agents limitée à un agent, utilisez agents.list[].memorySearch.qmd.extraCollections au lieu de memory.qmd.paths. Ces collections supplémentaires suivent la même forme { path, name, pattern? }, mais elles sont fusionnées par agent et peuvent préserver des noms partagés explicites lorsque le chemin pointe en dehors de l’espace de travail actuel. Si le même chemin résolu apparaît à la fois dans memory.qmd.paths et dans memorySearch.qmd.extraCollections, QMD conserve la première entrée et ignore le doublon.

Mémoire multimodale (Gemini)

Indexez les images et l’audio avec Markdown à l’aide de Gemini Embedding 2 :
CléTypePar défautDescription
multimodal.enabledbooleanfalseActiver l’indexation multimodale
multimodal.modalitiesstring[]["image"], ["audio"] ou ["all"]
multimodal.maxFileBytesnumber10000000Taille maximale de fichier pour l’indexation
S’applique uniquement aux fichiers dans extraPaths. Les racines mémoire par défaut restent limitées au Markdown. Nécessite gemini-embedding-2-preview. fallback doit être "none".
Formats pris en charge : .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (images) ; .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Cache des représentations vectorielles

CléTypePar défautDescription
cache.enabledbooleanfalseMettre en cache les représentations vectorielles des fragments dans SQLite
cache.maxEntriesnumber50000Nombre maximal de représentations vectorielles en cache
Évite de recalculer les représentations vectorielles du texte inchangé lors d’une réindexation ou de mises à jour de transcriptions.

Indexation par lots

CléTypePar défautDescription
remote.nonBatchConcurrencynumber4Représentations vectorielles intégrées parallèles
remote.batch.enabledbooleanfalseActiver l’API de représentations vectorielles par lots
remote.batch.concurrencynumber2Tâches par lots parallèles
remote.batch.waitbooleantrueAttendre la fin du lot
remote.batch.pollIntervalMsnumberIntervalle d’interrogation
remote.batch.timeoutMinutesnumberDélai d’expiration du lot
Disponible pour openai, gemini et voyage. Le traitement par lots OpenAI est généralement le plus rapide et le moins coûteux pour les grands remplissages rétrospectifs. remote.nonBatchConcurrency contrôle les appels de représentations vectorielles intégrés utilisés par les fournisseurs locaux/auto-hébergés et les fournisseurs hébergés lorsque les API de traitement par lots du fournisseur ne sont pas actives. Ollama utilise par défaut 1 pour l’indexation hors lots afin d’éviter de saturer les hôtes locaux plus petits ; définissez une valeur plus élevée sur les machines plus puissantes. Ce paramètre est distinct de sync.embeddingBatchTimeoutSeconds, qui contrôle le délai d’expiration des appels de représentations vectorielles intégrés.

Recherche dans la mémoire de session (expérimental)

Indexez les transcriptions de session et exposez-les via memory_search :
CléTypePar défautDescription
experimental.sessionMemorybooleanfalseActiver l’indexation des sessions
sourcesstring[]["memory"]Ajouter "sessions" pour inclure les transcriptions
sync.sessions.deltaBytesnumber100000Seuil en octets pour la réindexation
sync.sessions.deltaMessagesnumber50Seuil en messages pour la réindexation
L’indexation des sessions est facultative et s’exécute de manière asynchrone. Les résultats peuvent être légèrement obsolètes. Les journaux de session résident sur disque ; considérez donc l’accès au système de fichiers comme la frontière de confiance.

Accélération vectorielle SQLite (sqlite-vec)

CléTypePar défautDescription
store.vector.enabledbooleantrueUtiliser sqlite-vec pour les requêtes vectorielles
store.vector.extensionPathstringbundledRemplacer le chemin de sqlite-vec
Lorsque sqlite-vec n’est pas disponible, OpenClaw revient automatiquement à la similarité cosinus en cours de traitement.

Stockage de l’index

CléTypePar défautDescription
store.pathstring~/.openclaw/memory/{agentId}.sqliteEmplacement de l’index (prend en charge le jeton {agentId})
store.fts.tokenizerstringunicode61Analyseur lexical FTS5 (unicode61 ou trigram)

Configuration du backend QMD

Définissez memory.backend = "qmd" pour l’activer. Tous les paramètres QMD se trouvent sous memory.qmd :
CléTypePar défautDescription
commandstringqmdChemin de l’exécutable QMD ; définissez un chemin absolu lorsque le PATH du service diffère de votre shell
searchModestringsearchCommande de recherche : search, vsearch, query
includeDefaultMemorybooleantrueIndexer automatiquement MEMORY.md + memory/**/*.md
paths[]arrayChemins supplémentaires : { name, path, pattern? }
sessions.enabledbooleanfalseIndexer les transcriptions de session
sessions.retentionDaysnumberConservation des transcriptions
sessions.exportDirstringRépertoire d’exportation
searchMode: "search" est uniquement lexical/BM25. OpenClaw n’exécute pas de sondes de disponibilité vectorielle sémantique ni de maintenance des embeddings QMD pour ce mode, y compris pendant memory status --deep; vsearch et query continuent d’exiger la disponibilité vectorielle QMD et les embeddings. OpenClaw privilégie la collection QMD actuelle et les formes de requête MCP, mais maintient la compatibilité avec les anciennes versions de QMD en essayant, si nécessaire, des indicateurs de motifs de collection compatibles et d’anciens noms d’outils MCP. Quand QMD annonce la prise en charge de plusieurs filtres de collection, les collections de même source sont recherchées avec un seul processus QMD; les anciennes versions de QMD conservent le chemin de compatibilité par collection. Même source signifie que les collections de mémoire durable sont regroupées, tandis que les collections de transcriptions de session restent dans un groupe séparé afin que la diversification des sources conserve toujours les deux entrées.
Les substitutions de modèle QMD restent côté QMD, pas dans la configuration OpenClaw. Si vous devez remplacer les modèles de QMD globalement, définissez des variables d’environnement comme QMD_EMBED_MODEL, QMD_RERANK_MODEL et QMD_GENERATE_MODEL dans l’environnement d’exécution du Gateway.
CléTypePar défautDescription
update.intervalstring5mIntervalle d’actualisation
update.debounceMsnumber15000Anti-rebond des changements de fichiers
update.onBootbooleantrueActualiser lorsque le gestionnaire QMD longue durée s’ouvre; contrôle aussi l’actualisation au démarrage avec opt-in
update.startupstringoffActualisation facultative au démarrage du Gateway: off, idle ou immediate
update.startupDelayMsnumber120000Délai avant l’exécution de l’actualisation startup: "idle"
update.waitForBootSyncbooleanfalseBloquer l’ouverture du gestionnaire jusqu’à la fin de son actualisation initiale
update.embedIntervalstringCadence d’embedding séparée
update.commandTimeoutMsnumberDélai d’expiration pour les commandes QMD
update.updateTimeoutMsnumberDélai d’expiration pour les opérations de mise à jour QMD
update.embedTimeoutMsnumberDélai d’expiration pour les opérations d’embedding QMD
CléTypePar défautDescription
limits.maxResultsnumber6Nombre maximal de résultats de recherche
limits.maxSnippetCharsnumberLimiter la longueur de l’extrait
limits.maxInjectedCharsnumberLimiter le nombre total de caractères injectés
limits.timeoutMsnumber4000Délai d’expiration de la recherche
Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Même schéma que session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
La valeur par défaut livrée autorise les sessions directes et de canal, tout en continuant à refuser les groupes.Par défaut, seuls les DM sont autorisés. match.keyPrefix correspond à la clé de session normalisée; match.rawKeyPrefix correspond à la clé brute incluant agent:<id>:.
memory.citations s’applique à tous les backends:
ValeurComportement
auto (par défaut)Inclure le pied de page Source: <path#line> dans les extraits
onToujours inclure le pied de page
offOmettre le pied de page (le chemin est quand même transmis à l’agent en interne)
Les actualisations QMD au démarrage utilisent un chemin de sous-processus à exécution unique pendant le démarrage du Gateway. Le gestionnaire QMD longue durée reste responsable de l’observateur de fichiers régulier et des minuteurs d’intervalle lorsque la recherche mémoire est ouverte pour une utilisation interactive.

Exemple QMD complet

{
  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 est configuré sous plugins.entries.memory-core.config.dreaming, pas sous agents.defaults.memorySearch. Dreaming s’exécute comme un balayage planifié unique et utilise des phases internes light/deep/REM comme détail d’implémentation. Pour le comportement conceptuel et les commandes slash, consultez Dreaming.

Paramètres utilisateur

CléTypePar défautDescription
enabledbooleanfalseActiver ou désactiver entièrement Dreaming
frequencystring0 3 * * *Cadence cron facultative pour le balayage Dreaming complet
modelstringmodèle par défautRemplacement facultatif du modèle de sous-agent Dream Diary

Exemple

{
  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 écrit l’état machine dans memory/.dreams/.
  • Dreaming écrit la sortie narrative lisible par l’humain dans DREAMS.md (ou le fichier dreams.md existant).
  • dreaming.model utilise la barrière de confiance de sous-agent du Plugin existant; définissez plugins.entries.memory-core.subagent.allowModelOverride: true avant de l’activer.
  • Dream Diary réessaie une fois avec le modèle par défaut de la session lorsque le modèle configuré n’est pas disponible. Les échecs de confiance ou de liste d’autorisation sont journalisés et ne sont pas réessayés silencieusement.
  • La politique et les seuils des phases light/deep/REM sont un comportement interne, pas une configuration destinée à l’utilisateur.

Liens associés