Быстрый старт
Вставьте вopenclaw.json, чтобы получить безопасные настройки по умолчанию: плагин включён, область действия ограничена main,
только сеансы личных сообщений, модель наследуется от сеанса.
plugins.entries.* (включая active-memory.config) относится к категории конфигурации,
не требующей перезапуска:
Gateway автоматически перезагружает среду выполнения плагина, и ручной перезапуск
не требуется. Если всё же нужно принудительно выполнить полный перезапуск, запустите:
plugins.entries.active-memory.enabled: trueвключает плагинconfig.agents: ["main"]включает его только для агентаmainconfig.allowedChatTypes: ["direct"]ограничивает область действия сеансами личных сообщений (для групп и каналов требуется явное включение)config.model(необязательно) закрепляет отдельную модель извлечения воспоминаний; если значение не задано, наследуется модель текущего сеансаconfig.modelFallbackиспользуется только тогда, когда не удаётся определить явно заданную или унаследованную модельconfig.fastModeпри необходимости переопределяет быстрый режим для извлечения воспоминаний, не изменяя основной агентconfig.promptStyle: "balanced"— значение по умолчанию для режимаrecent- Active Memory по-прежнему запускается только для подходящих интерактивных постоянных сеансов чата (см. Когда он запускается)
Принцип работы
Блокирующий подагент может вызывать только настроенные инструменты извлечения воспоминаний (см. Инструменты памяти). Если связь между запросом и доступными воспоминаниями слабая, он возвращаетNONE, а формирование основного ответа продолжается
без дополнительного контекста.
Active Memory — это функция обогащения диалогов, а не функция логического вывода
для всей платформы:
Используйте его, когда сеанс постоянный и ориентирован на пользователя, у агента есть
содержательная долговременная память для поиска, а непрерывность и персонализация важнее
строгой детерминированности промпта: устойчивые предпочтения, повторяющиеся привычки,
долгосрочный контекст, который должен проявляться естественно. Он плохо подходит для
автоматизации, внутренних рабочих процессов, одноразовых задач API и любых ситуаций, где скрытая
персонализация может оказаться неожиданной.
Когда он запускается
Должны пройти обе проверки:- Включение в конфигурации — плагин включён, а идентификатор текущего агента входит в
config.agents. - Соответствие условиям среды выполнения — сеанс является подходящим интерактивным постоянным сеансом чата, его тип чата разрешён, а идентификатор диалога не отфильтрован.
Типы сеансов
config.allowedChatTypes определяет, в каких видах диалогов может запускаться
Active Memory. Значение по умолчанию:
direct, group, channel, explicit (сеансы в стиле портала
с непрозрачным идентификатором сеанса, например agent:main:explicit:portal-123).
Сеансы личных сообщений запускаются по умолчанию; для групп, каналов и явно заданных сеансов
требуется отдельное включение:
config.allowedChatIds и config.deniedChatIds:
allowedChatIds— список разрешённых идентификаторов определённых диалогов. Если он не пуст, Active Memory запускается только для сеансов, идентификатор диалога которых входит в список — это одновременно сужает область действия для всех разрешённых типов чатов, включая личные сообщения. Чтобы сохранить все личные сообщения, ограничив только группы, также добавьте идентификаторы собеседников из личных сообщений вallowedChatIdsлибо оставьтеallowedChatTypesограниченным развёртыванием для тестируемой группы или канала.deniedChatIds— список запрещённых идентификаторов, который всегда имеет приоритет надallowedChatTypesиallowedChatIds.
chat_id/open_id, идентификатор чата Telegram, идентификатор канала Slack). Сопоставление
не учитывает регистр. Если allowedChatIds не пуст и OpenClaw не может
определить идентификатор диалога для сеанса, Active Memory пропускает этот ход,
а не пытается угадать его.
Переключатель сеанса
Приостановите или возобновите Active Memory для текущего сеанса чата без изменения конфигурации:plugins.entries.active-memory.config.enabled или другие глобальные параметры конфигурации.
Чтобы приостановить или возобновить работу для всех сеансов, используйте глобальную форму (требуется
владелец или operator.admin):
plugins.entries.active-memory.config.enabled, но
оставляет plugins.entries.active-memory.enabled включённым, чтобы команда оставалась
доступной для последующего повторного включения Active Memory.
Как увидеть его работу
По умолчанию Active Memory внедряет скрытый недоверенный префикс промпта, который не отображается в обычном ответе. Включите для сеанса переключатели, соответствующие нужному выводу:/verbose onдобавляет строку состояния:🧩 Active Memory: status=ok elapsed=842ms query=recent summary=34 chars/trace onдобавляет отладочную сводку:🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
/trace raw отслеживаемый блок Model Input (User Role) показывает необработанный
скрытый префикс:
Режимы запросов
config.queryMode определяет, какую часть диалога видит блокирующий подагент.
Выбирайте минимальный режим, который всё ещё позволяет корректно отвечать на последующие вопросы; увеличивайте
timeoutMs по мере роста контекста: от message к recent, а затем к full.
- message
- recent
- full
Отправляется только последнее сообщение пользователя.Используйте этот режим, когда требуется максимальная скорость, наиболее выраженный приоритет извлечения устойчивых
предпочтений, а последующим ходам не нужен контекст
диалога. Начните примерно с
3000-5000 мс для config.timeoutMs.Стили промптов
config.promptStyle определяет, насколько охотно или строго подагент
возвращает воспоминания:
Сопоставление по умолчанию, когда
config.promptStyle не задан:
config.promptStyle всегда переопределяет это сопоставление.
Политика резервной модели
Еслиconfig.model не задан, Active Memory определяет модель в следующем порядке:
config.modelFallbackPolicy — устаревшее поле совместимости, сохранённое для
старых конфигураций; оно больше не изменяет поведение среды выполнения — modelFallback
является исключительно последним средством в указанной выше цепочке, а не механизмом переключения при сбое,
который заменяет модель другой, если определённая модель возвращает ошибку.
Рекомендации по скорости
Оставитьconfig.model незаданным (наследовать модель сеанса) — самый безопасный
вариант по умолчанию: он учитывает существующие предпочтения для провайдера, аутентификации и модели. Для
уменьшения задержки вместо этого используйте отдельную быструю модель — качество извлечения
важно, но здесь задержка важнее, чем в основном пути формирования ответа, а набор
инструментов узок (только инструменты извлечения из памяти).
Подходящие варианты быстрых моделей:
cerebras/gpt-oss-120b, отдельная модель с низкой задержкой для извлечения из памятиgoogle/gemini-3-flash, резервный вариант с низкой задержкой без изменения основной модели чата- обычная модель сеанса, если оставить
config.modelнезаданным
Настройка Cerebras
chat/completions для выбранной
модели — одной видимости /v1/models для этого недостаточно.
Инструменты памяти
config.toolsAllow задаёт конкретные имена инструментов, которые может вызывать блокирующий субагент.
Значения по умолчанию зависят от активного провайдера памяти:
Если ни один из настроенных инструментов недоступен или запуск субагента завершается
сбоем, Active Memory пропускает извлечение для этого хода, а основной ответ формируется
без контекста памяти. Для пользовательских инструментов извлечения непустой вывод,
видимый модели, считается результатом извлечения, если только структурированные поля результата
явно не сообщают о пустом результате или сбое.
toolsAllow принимает только конкретные имена инструментов памяти: подстановочные знаки, записи group:*
и основные инструменты агента (read, exec, message, web_search и
аналогичные) автоматически отфильтровываются перед запуском скрытого субагента.
Встроенный memory-core
Явно задаватьtoolsAllow не требуется:
Память LanceDB
Достаточно выбрать слот памяти, чтобы Active Memory использовалаmemory_recall:
Lossless Claw
Lossless Claw — внешний плагин движка контекста (openclaw plugins install @martian-engineering/lossless-claw) с собственными инструментами извлечения. Сначала настройте его
как движок контекста; см. Движок контекста. Затем
укажите Active Memory его инструменты:
lcm_expand в toolsAllow; Lossless Claw использует его как
низкоуровневый инструмент для делегированного развёртывания, не предназначенный для субагента
Active Memory верхнего уровня.
Расширенные обходные механизмы
Не входят в рекомендуемую настройку.config.thinking переопределяет уровень рассуждений субагента (по умолчанию "off",
поскольку Active Memory выполняется в пути формирования ответа, а дополнительное время на рассуждения напрямую
увеличивает видимую пользователю задержку):
config.fastMode переопределяет быстрый режим только для блокирующего субагента памяти.
Используйте true, false или "auto"; оставьте параметр незаданным, чтобы наследовать обычные
значения по умолчанию для агента, сеанса и модели. "auto" использует настроенное
пороговое значение fastAutoOnSeconds модели извлечения:
config.promptAppend добавляет операторские инструкции после стандартного промпта
и перед контекстом беседы — используйте его вместе с пользовательским toolsAllow, когда
плагину памяти, отличному от основного, требуется определённый порядок инструментов или формирование запросов:
config.promptOverride полностью заменяет стандартный промпт (контекст беседы
по-прежнему добавляется после него). Не рекомендуется, если только намеренно
не тестируется другой контракт извлечения — стандартный промпт настроен на возврат
либо NONE, либо компактного контекста с фактами о пользователе для основной модели:
Сохранение транскриптов
Запуски блокирующего субагента создают настоящий транскриптsession.jsonl во время
вызова. По умолчанию он записывается во временный каталог и удаляется сразу
после завершения запуска.
Чтобы сохранять эти транскрипты на диске для отладки:
config.transcriptDir. Используйте эту
возможность осторожно: в активных сеансах транскрипты могут быстро накапливаться, режим запросов full
дублирует значительную часть контекста беседы, а эти транскрипты содержат
скрытый контекст промпта и извлечённые воспоминания.
Конфигурация
Вся конфигурация Active Memory находится вplugins.entries.active-memory.
Полезные поля настройки:
Рекомендуемая настройка
Начните сrecent:
/verbose on для строки состояния и /trace on для отладочной сводки — оба сообщения отправляются после основного ответа, а не
до него. Затем перейдите на message для уменьшения задержки или на full, если дополнительный контекст
оправдывает более медленную работу субагента.
Допуск для холодного запуска
До v2026.5.2 плагин автоматически продлевалtimeoutMs ещё на 30000
мс при холодном запуске, чтобы прогрев модели, загрузка индекса эмбеддингов и первое
извлечение могли использовать общий увеличенный бюджет. В v2026.5.2 этот допуск был перенесён
в явную конфигурацию setupGraceTimeoutMs: теперь по умолчанию timeoutMs является бюджетом
работы извлечения, если этот допуск не включён явно. Блокирующий хук разделяет этот бюджет на
две фиксированные фазы: до 1500 мс на предварительную проверку сеанса и конфигурации перед началом
извлечения, а затем отдельные фиксированные 1500 мс на завершение прерывания и восстановление расшифровки
после остановки работы извлечения. Ни один из этих допусков не продлевает выполнение модели или инструмента.
Если вы обновились с v2026.4.x и настроили timeoutMs для прежнего
режима с неявным льготным периодом (одним из примеров является рекомендуемое начальное значение
timeoutMs: 15000), задайте setupGraceTimeoutMs: 30000, чтобы восстановить эффективный
бюджет, использовавшийся до v5.2:
timeoutMs + setupGraceTimeoutMs + 3000 мс (настроенный
бюджет работы поиска, плюс до 1500 мс на предварительную проверку, плюс фиксированный
допуск 1500 мс на завершение после поиска). Встроенный исполнитель поиска использует
тот же эффективный бюджет тайм-аута, поэтому setupGraceTimeoutMs охватывает как
внешний сторожевой таймер построения промпта, так и внутренний блокирующий запуск поиска.
Для Gateway с ограниченными ресурсами, где задержка холодного запуска считается
приемлемым компромиссом, подойдут и меньшие значения (5000-15000 мс) — ценой этого будет более высокая
вероятность того, что самый первый поиск после перезапуска Gateway вернёт пустой результат,
пока завершается прогрев.
Отладка
Если Active Memory не появляется там, где ожидается:- Убедитесь, что плагин включён в
plugins.entries.active-memory.enabled. - Убедитесь, что идентификатор текущего агента указан в
config.agents. - Убедитесь, что тестирование выполняется через интерактивный постоянный сеанс чата.
- Включите
config.logging: trueи следите за журналами Gateway. - Проверьте работу самого поиска по памяти с помощью
openclaw status --deep.
maxSummaryChars. Если Active Memory работает слишком
медленно, уменьшите queryMode, уменьшите timeoutMs либо сократите количество недавних реплик и
ограничения числа символов на реплику.
Распространённые проблемы
Active Memory использует конвейер поиска настроенного плагина памяти, поэтому большинство неожиданных результатов поиска связано с проблемами поставщика эмбеддингов, а не с ошибками Active Memory. Стандартный путьmemory-core использует memory_search и memory_get;
слот memory-lancedb использует memory_recall. Если используется другой плагин
памяти, убедитесь, что config.toolsAllow содержит имена инструментов, которые этот плагин действительно
регистрирует.
Поставщик эмбеддингов сменился или перестал работать
Поставщик эмбеддингов сменился или перестал работать
Если
memorySearch.provider не задан, OpenClaw использует эмбеддинги OpenAI. Явно задайте
memorySearch.provider для эмбеддингов Bedrock, DeepInfra, Gemini, GitHub
Copilot, LM Studio, local, Mistral, Ollama, Voyage или совместимых с OpenAI.
Если настроенный поставщик не может работать, memory_search может
перейти к поиску только по лексическим совпадениям; после выбора поставщика автоматического
переключения при ошибках во время выполнения не происходит.Задавайте необязательный memorySearch.fallback только для намеренного выбора
единственного резервного варианта. Полный список поставщиков и примеры см. на странице
Поиск по памяти.Поиск кажется медленным, возвращает пустой результат или работает нестабильно
Поиск кажется медленным, возвращает пустой результат или работает нестабильно
- Включите
/trace on, чтобы вывести в сеансе принадлежащую плагину отладочную сводку Active Memory. - Включите
/verbose on, чтобы также видеть строку состояния🧩 Active Memory: ...после каждого ответа. - Следите в журналах Gateway за
active-memory: ... start|done,memory sync failed (search-bootstrap)или ошибками поставщика эмбеддингов. - Запустите
openclaw status --deep, чтобы проверить бэкенд поиска по памяти и состояние индекса. - Если используется
ollama, убедитесь, что модель эмбеддингов установлена (ollama list).
Первый поиск после перезапуска Gateway возвращает `status=timeout`
Первый поиск после перезапуска Gateway возвращает `status=timeout`
В v2026.5.2 и более поздних версиях, если настройка холодного запуска (прогрев модели и загрузка
индекса эмбеддингов) не завершилась к моменту первого запуска поиска, выполнение
может исчерпать настроенный бюджет
timeoutMs и вернуть status=timeout
с пустым выводом. В журналах Gateway рядом с первым подходящим ответом после перезапуска
отображается active-memory timeout after Nms.Рекомендуемое значение setupGraceTimeoutMs см. в разделе
Льготный период холодного запуска главы «Рекомендуемая настройка».