Перейти до основного вмісту

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.

На цій сторінці перелічено всі параметри конфігурації для пошуку в пам’яті OpenClaw. Концептуальні огляди дивіться тут:

Огляд пам’яті

Як працює пам’ять.

Вбудований рушій

Типовий бекенд SQLite.

Рушій QMD

Локальний передусім sidecar.

Пошук у пам’яті

Конвеєр пошуку та налаштування.

Активна пам’ять

Субагент пам’яті для інтерактивних сеансів.
Усі налаштування пошуку в пам’яті розташовані в agents.defaults.memorySearch у openclaw.json, якщо не зазначено інше.
Якщо ви шукаєте перемикач функції активної пам’яті та конфігурацію субагента, вони розташовані в plugins.entries.active-memory, а не в memorySearch.Активна пам’ять використовує модель із двома перевірками:
  1. Plugin має бути ввімкнений і націлений на ідентифікатор поточного агента
  2. запит має бути придатним інтерактивним постійним сеансом чату
Дивіться Active Memory щодо моделі активації, конфігурації, що належить Plugin, збереження транскриптів і безпечного шаблону впровадження.

Вибір провайдера

КлючТипТипове значенняОпис
providerstringвизначається автоматичноID адаптера embedding, як-от bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai або voyage; також може бути налаштованим models.providers.<id>, у якому api вказує на один із цих адаптерів
modelstringтипове значення провайдераНазва моделі embedding
fallbackstring"none"ID резервного адаптера, коли основний не спрацьовує
enabledbooleantrueУвімкнути або вимкнути пошук у пам’яті

Порядок автоматичного визначення

Коли provider не задано, OpenClaw вибирає перший доступний:
1

local

Вибирається, якщо memorySearch.local.modelPath налаштовано й файл існує.
2

github-copilot

Вибирається, якщо можна визначити токен GitHub Copilot (змінна середовища або профіль автентифікації).
3

openai

Вибирається, якщо можна визначити ключ OpenAI.
4

gemini

Вибирається, якщо можна визначити ключ Gemini.
5

voyage

Вибирається, якщо можна визначити ключ Voyage.
6

mistral

Вибирається, якщо можна визначити ключ Mistral.
7

deepinfra

Вибирається, якщо можна визначити ключ DeepInfra.
8

bedrock

Вибирається, якщо ланцюжок облікових даних AWS SDK успішно визначається (роль інстанса, ключі доступу, профіль, SSO, вебідентичність або спільна конфігурація).
ollama підтримується, але не визначається автоматично (задайте його явно).

Власні ідентифікатори провайдерів

memorySearch.provider може вказувати на власний запис models.providers.<id>. OpenClaw визначає власника api цього провайдера для адаптера embedding, зберігаючи власний ідентифікатор провайдера для обробки кінцевої точки, автентифікації та префікса моделі. Це дає змогу конфігураціям із кількома GPU або кількома хостами виділити embeddings пам’яті для конкретної локальної кінцевої точки:
{
  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-ключа

Віддалені embeddings потребують API-ключа. Bedrock натомість використовує типовий ланцюжок облікових даних AWS SDK (ролі інстансів, SSO, ключі доступу).
ПровайдерЗмінна середовищаКлюч конфігурації
Bedrockланцюжок облікових даних AWSAPI-ключ не потрібен
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENПрофіль автентифікації через вхід із пристрою
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (заповнювач)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
Codex OAuth охоплює лише чат/завершення й не задовольняє запити embedding.

Конфігурація віддаленої кінцевої точки

Для власних OpenAI-сумісних кінцевих точок або перевизначення типових значень провайдера:
remote.baseUrl
string
Власний базовий URL API.
remote.apiKey
string
Перевизначити API-ключ.
remote.headers
object
Додаткові заголовки HTTP (об’єднуються з типовими значеннями провайдера).
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Конфігурація для окремих провайдерів

КлючТипТипове значенняОпис
modelstringgemini-embedding-001Також підтримує gemini-embedding-2-preview
outputDimensionalitynumber3072Для Embedding 2: 768, 1536 або 3072
Зміна моделі або outputDimensionality запускає автоматичне повне переіндексування.
OpenAI-сумісні кінцеві точки embedding можуть увімкнути специфічні для провайдера поля запиту input_type. Це корисно для асиметричних моделей embedding, яким потрібні різні мітки для embeddings запитів і документів.
КлючТипТипове значенняОпис
inputTypestringне заданоСпільний input_type для embeddings запитів і документів
queryInputTypestringне заданоinput_type під час запиту; перевизначає inputType
documentInputTypestringне заданоinput_type індексу/документа; перевизначає inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
Зміна цих значень впливає на ідентичність кешу embedding для пакетного індексування провайдера, і після неї слід виконати переіндексування пам’яті, якщо upstream-модель обробляє мітки по-різному.

Конфігурація embedding Bedrock

Bedrock використовує типовий ланцюжок облікових даних AWS SDK — API-ключі не потрібні. Якщо OpenClaw працює на EC2 з роллю інстанса з доступом до Bedrock, просто задайте провайдера й модель:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
КлючТипТипове значенняОпис
modelstringamazon.titan-embed-text-v2:0Будь-який ID моделі embedding Bedrock
outputDimensionalitynumberтипове значення моделіДля Titan V2: 256, 512 або 1024
Підтримувані моделі (з визначенням сімейства та типовими розмірностями):
ID моделіПровайдерТипові розмірностіНалаштовувані розмірності
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
Варіанти із суфіксом пропускної здатності (наприклад, amazon.titan-embed-text-v1:2:8k) успадковують конфігурацію базової моделі.Автентифікація: автентифікація Bedrock використовує стандартний порядок визначення облікових даних AWS SDK:
  1. Змінні середовища (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. Кеш токенів SSO
  3. Облікові дані токена вебідентичності
  4. Спільні файли облікових даних і конфігурації
  5. Облікові дані метаданих ECS або EC2
Регіон визначається з AWS_REGION, AWS_DEFAULT_REGION, baseUrl провайдера amazon-bedrock або за замовчуванням встановлюється на us-east-1.Дозволи IAM: роль або користувач IAM потребує:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Для мінімальних привілеїв обмежте InvokeModel конкретною моделлю:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
КлючТипТиповоОпис
local.modelPathstringавтоматично завантажуєтьсяШлях до файлу моделі GGUF
local.modelCacheDirstringтипове для node-llama-cppКаталог кешу для завантажених моделей
local.contextSizenumber | "auto"4096Розмір контекстного вікна для контексту embedding. 4096 покриває типові фрагменти (128-512 токенів), водночас обмежуючи VRAM не для ваг. Зменште до 1024-2048 на обмежених хостах. "auto" використовує навчений максимум моделі — не рекомендовано для моделей 8B+ (Qwen3-Embedding-8B: 40 960 токенів → ~32 ГБ VRAM проти ~8.8 ГБ за 4096).
Типова модель: embeddinggemma-300m-qat-Q8_0.gguf (~0.6 ГБ, автоматично завантажується). Вихідні checkout-и все ще потребують схвалення нативного складання: pnpm approve-builds, потім pnpm rebuild node-llama-cpp.Використовуйте окремий CLI, щоб перевірити той самий шлях провайдера, який використовує Gateway:
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
Якщо provider має значення auto, local вибирається лише тоді, коли local.modelPath вказує на наявний локальний файл. Посилання на моделі hf: і HTTP(S) усе ще можна явно використовувати з provider: "local", але вони не змушують auto вибрати local до того, як модель стане доступною на диску.

Тайм-аут inline embedding

sync.embeddingBatchTimeoutSeconds
number
Перевизначає тайм-аут для inline embedding пакетів під час індексування пам’яті.Якщо не задано, використовується типове значення провайдера: 600 секунд для локальних/self-hosted провайдерів, таких як local, ollama і lmstudio, та 120 секунд для hosted провайдерів. Збільште це значення, коли локальні CPU-bound embedding пакети справні, але повільні.

Конфігурація гібридного пошуку

Усе в memorySearch.query.hybrid:
КлючТипТиповоОпис
enabledbooleantrueУвімкнути гібридний пошук BM25 + векторний пошук
vectorWeightnumber0.7Вага для векторних оцінок (0-1)
textWeightnumber0.3Вага для оцінок BM25 (0-1)
candidateMultipliernumber4Множник розміру пулу кандидатів
КлючТипТиповоОпис
mmr.enabledbooleanfalseУвімкнути повторне ранжування MMR
mmr.lambdanumber0.70 = макс. різноманітність, 1 = макс. релевантність

Повний приклад

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

Додаткові шляхи пам’яті

КлючТипОпис
extraPathsstring[]Додаткові каталоги або файли для індексування
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
Шляхи можуть бути абсолютними або відносними до workspace. Каталоги рекурсивно скануються на файли .md. Обробка symlink залежить від активного backend: вбудований рушій ігнорує symlink, тоді як QMD дотримується поведінки базового сканера QMD. Для agent-scoped пошуку транскриптів між агентами використовуйте agents.list[].memorySearch.qmd.extraCollections замість memory.qmd.paths. Ці додаткові колекції мають таку саму форму { path, name, pattern? }, але об’єднуються для кожного агента й можуть зберігати явні спільні назви, коли шлях вказує за межі поточного workspace. Якщо той самий resolved path з’являється і в memory.qmd.paths, і в memorySearch.qmd.extraCollections, QMD зберігає перший запис і пропускає дублікат.

Мультимодальна пам’ять (Gemini)

Індексуйте зображення й аудіо разом із Markdown за допомогою Gemini Embedding 2:
КлючТипТиповоОпис
multimodal.enabledbooleanfalseУвімкнути мультимодальне індексування
multimodal.modalitiesstring[]["image"], ["audio"] або ["all"]
multimodal.maxFileBytesnumber10000000Максимальний розмір файлу для індексування
Застосовується лише до файлів у extraPaths. Корені пам’яті за замовчуванням залишаються лише для Markdown. Потрібен gemini-embedding-2-preview. fallback має бути "none".
Підтримувані формати: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (зображення); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (аудіо).

Кеш embedding

КлючТипЗа замовчуваннямОпис
cache.enabledbooleanfalseКешувати embedding фрагментів у SQLite
cache.maxEntriesnumber50000Максимальна кількість кешованих embedding
Запобігає повторному embedding незміненого тексту під час повторного індексування або оновлень транскриптів.

Пакетне індексування

КлючТипЗа замовчуваннямОпис
remote.nonBatchConcurrencynumber4Паралельні inline embedding
remote.batch.enabledbooleanfalseУвімкнути API пакетного embedding
remote.batch.concurrencynumber2Паралельні пакетні завдання
remote.batch.waitbooleantrueЧекати завершення пакета
remote.batch.pollIntervalMsnumberІнтервал опитування
remote.batch.timeoutMinutesnumberТайм-аут пакета
Доступно для openai, gemini і voyage. Пакетний режим OpenAI зазвичай найшвидший і найдешевший для великих ретроспективних заповнень. remote.nonBatchConcurrency керує inline-викликами embedding, які використовуються локальними/self-hosted провайдерами та hosted провайдерами, коли пакетні API провайдера не активні. Для непакетного індексування Ollama за замовчуванням використовує 1, щоб не перевантажувати менші локальні хости; задайте більше значення на потужніших машинах. Це окремо від sync.embeddingBatchTimeoutSeconds, який керує тайм-аутом для inline-викликів embedding.

Пошук у пам’яті сеансів (експериментально)

Індексуйте транскрипти сеансів і надавайте їх через memory_search:
КлючТипЗа замовчуваннямОпис
experimental.sessionMemorybooleanfalseУвімкнути індексування сеансів
sourcesstring[]["memory"]Додайте "sessions", щоб включити транскрипти
sync.sessions.deltaBytesnumber100000Пороговий обсяг байтів для повторного індексування
sync.sessions.deltaMessagesnumber50Порогова кількість повідомлень для повторного індексування
Індексування сеансів є опціональним і виконується асинхронно. Результати можуть бути трохи застарілими. Журнали сеансів зберігаються на диску, тому вважайте доступ до файлової системи межею довіри.

Векторне прискорення SQLite (sqlite-vec)

КлючТипЗа замовчуваннямОпис
store.vector.enabledbooleantrueВикористовувати sqlite-vec для векторних запитів
store.vector.extensionPathstringbundledПеревизначити шлях sqlite-vec
Коли sqlite-vec недоступний, OpenClaw автоматично повертається до косинусної подібності в межах процесу.

Сховище індексу

КлючТипЗа замовчуваннямОпис
store.pathstring~/.openclaw/memory/{agentId}.sqliteРозташування індексу (підтримує токен {agentId})
store.fts.tokenizerstringunicode61Токенізатор FTS5 (unicode61 або trigram)

Конфігурація backend QMD

Задайте memory.backend = "qmd", щоб увімкнути. Усі налаштування QMD розташовані в memory.qmd:
КлючТипЗа замовчуваннямОпис
commandstringqmdШлях до виконуваного файлу QMD; задайте абсолютний шлях, коли PATH сервісу відрізняється від вашої оболонки
searchModestringsearchКоманда пошуку: search, vsearch, query
includeDefaultMemorybooleantrueАвтоматично індексувати MEMORY.md + memory/**/*.md
paths[]arrayДодаткові шляхи: { name, path, pattern? }
sessions.enabledbooleanfalseІндексувати транскрипти сеансів
sessions.retentionDaysnumberТермін зберігання транскриптів
sessions.exportDirstringКаталог експорту
searchMode: "search" є лише лексичним/BM25. OpenClaw не запускає перевірки готовності семантичних векторів або обслуговування QMD-вбудовувань для цього режиму, зокрема під час memory status --deep; vsearch і query і далі потребують готовності QMD-векторів і вбудовувань. OpenClaw віддає перевагу поточним колекціям QMD і формам запитів MCP, але зберігає сумісність зі старішими випусками QMD, за потреби пробуючи сумісні прапорці шаблонів колекцій і старіші назви інструментів MCP. Коли QMD оголошує підтримку кількох фільтрів колекцій, колекції з одного джерела шукаються одним процесом QMD; старіші збірки QMD зберігають шлях сумісності для кожної колекції. Одне джерело означає, що колекції сталої пам’яті групуються разом, тоді як колекції транскриптів сесій залишаються окремою групою, щоб диверсифікація джерел і далі мала обидва входи.
Перевизначення моделей QMD залишаються на боці QMD, а не в конфігурації OpenClaw. Якщо потрібно глобально перевизначити моделі QMD, задайте змінні середовища, як-от QMD_EMBED_MODEL, QMD_RERANK_MODEL і QMD_GENERATE_MODEL, у середовищі виконання gateway.
КлючТипТиповоОпис
update.intervalstring5mІнтервал оновлення
update.debounceMsnumber15000Усунення брязкоту змін файлів
update.onBootbooleantrueОновлювати, коли відкривається довгоживучий менеджер QMD; також обмежує добровільне стартове оновлення
update.startupstringoffНеобов’язкове оновлення під час запуску gateway: off, idle або immediate
update.startupDelayMsnumber120000Затримка перед виконанням оновлення startup: "idle"
update.waitForBootSyncbooleanfalseБлокувати відкриття менеджера, доки не завершиться його початкове оновлення
update.embedIntervalstringОкрема періодичність вбудовування
update.commandTimeoutMsnumberТайм-аут для команд QMD
update.updateTimeoutMsnumberТайм-аут для операцій оновлення QMD
update.embedTimeoutMsnumberТайм-аут для операцій вбудовування QMD
КлючТипТиповоОпис
limits.maxResultsnumber6Максимальна кількість результатів пошуку
limits.maxSnippetCharsnumberОбмежити довжину фрагмента
limits.maxInjectedCharsnumberОбмежити загальну кількість вставлених символів
limits.timeoutMsnumber4000Тайм-аут пошуку
Керує тим, які сесії можуть отримувати результати пошуку QMD. Та сама схема, що й session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
Типове значення, що постачається, дозволяє прямі сесії та сесії каналів, але й далі забороняє групи.Типово дозволено лише DM. match.keyPrefix зіставляє нормалізований ключ сесії; match.rawKeyPrefix зіставляє сирий ключ, включно з agent:<id>:.
memory.citations застосовується до всіх бекендів:
ЗначенняПоведінка
auto (типово)Додавати нижній колонтитул Source: <path#line> у фрагменти
onЗавжди додавати нижній колонтитул
offНе додавати нижній колонтитул (шлях усе одно передається агенту внутрішньо)
Оновлення QMD під час завантаження використовують одноразовий шлях підпроцесу під час запуску gateway. Довгоживучий менеджер QMD і далі володіє звичайним спостерігачем за файлами та таймерами інтервалів, коли пошук у пам’яті відкрито для інтерактивного використання.

Повний приклад QMD

{
  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 налаштовується в plugins.entries.memory-core.config.dreaming, а не в agents.defaults.memorySearch. Dreaming виконується як одне заплановане сканування та використовує внутрішні фази light/deep/REM як деталь реалізації. Концептуальну поведінку та slash-команди див. у Dreaming.

Налаштування користувача

КлючТипТиповоОпис
enabledbooleanfalseПовністю увімкнути або вимкнути dreaming
frequencystring0 3 * * *Необов’язкова cron-періодичність для повного сканування dreaming
modelstringтипова модельНеобов’язкове перевизначення моделі субагента Dream Diary

Приклад

{
  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 записує машинний стан у memory/.dreams/.
  • Dreaming записує читабельний для людини наративний вивід у DREAMS.md (або наявний dreams.md).
  • dreaming.model використовує наявний довірчий шлюз субагента plugin; задайте plugins.entries.memory-core.subagent.allowModelOverride: true, перш ніж його вмикати.
  • Dream Diary повторює спробу один раз із типовою моделлю сесії, коли налаштована модель недоступна. Помилки довіри або allowlist журналюються й не повторюються непомітно.
  • Політика фаз light/deep/REM і пороги є внутрішньою поведінкою, а не користувацькою конфігурацією.

Пов’язане