Швидкий початок
Вставте вopenclaw.json, щоб отримати безпечні типові налаштування: Plugin увімкнено, область дії обмежено main,
лише сеанси особистих повідомлень, модель успадковується від сеансу.
plugins.entries.* (зокрема active-memory.config) належить до категорії конфігурації, що не потребує
перезапуску:
Gateway автоматично перезавантажує середовище виконання Plugin, тому перезапуск вручну не
потрібен. Якщо все одно потрібно примусово виконати повний перезапуск, запустіть:
plugins.entries.active-memory.enabled: trueвмикає Pluginconfig.agents: ["main"]активує його лише для агентаmainconfig.allowedChatTypes: ["direct"]обмежує його сеансами особистих повідомлень (явно активуйте для груп/каналів)config.model(необов’язково) закріплює окрему модель пошуку в пам’яті; якщо не задано, успадковується модель поточного сеансуconfig.modelFallbackвикористовується лише тоді, коли не вдається визначити явну або успадковану модельconfig.fastModeза потреби перевизначає швидкий режим для пошуку в пам’яті, не змінюючи основного агентаconfig.promptStyle: "balanced"є типовим значенням для режимуrecent- Active Memory усе одно запускається лише для придатних інтерактивних постійних сеансів чату (див. Коли він запускається)
Як це працює
Блокувальний субагент може викликати лише налаштовані інструменти пошуку в пам’яті (див. Інструменти пам’яті). Якщо зв’язок між запитом і доступною пам’яттю слабкий, він повертаєNONE, а створення основної відповіді продовжується
без додаткового контексту.
Active Memory — це функція збагачення розмови, а не загальноплатформна
функція логічного виведення:
Використовуйте цю функцію, коли сеанс постійний і орієнтований на користувача, агент має
змістовну довготривалу пам’ять для пошуку, а безперервність і персоналізація важливіші
за абсолютну детермінованість запиту: сталі вподобання, повторювані звички,
довготривалий контекст, який має з’являтися природно. Вона погано підходить для
автоматизації, внутрішніх виконавців, одноразових завдань API або будь-яких випадків, де прихована
персоналізація була б несподіваною.
Коли він запускається
Мають спрацювати обидві перевірки:- Активація в конфігурації — Plugin увімкнено, а ідентифікатор поточного агента є в
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 задає конкретні назви інструментів, які може викликати блокувальний підагент.
Значення за замовчуванням залежать від активного провайдера пам’яті:
Якщо жоден із налаштованих інструментів недоступний або запуск підагента
завершується невдало, активна пам’ять пропускає пригадування для цього запиту, а основна відповідь
продовжує формуватися без контексту пам’яті. Для спеціальних інструментів пригадування непорожній
видимий моделі результат інструмента вважається свідченням пригадування, якщо поля структурованого результату
явно не повідомляють про порожній результат або помилку.
toolsAllow приймає лише конкретні назви інструментів пам’яті: символи підстановки, записи group:*
та основні інструменти агента (read, exec, message, web_search й
подібні) без повідомлення вилучаються до запуску прихованого підагента.
Вбудований memory-core
Явне значенняtoolsAllow не потрібне:
Пам’ять LanceDB
Для використання активною пам’яттюmemory_recall достатньо вибрати слот пам’яті:
Lossless Claw
Lossless Claw — це зовнішній плагін рушія контексту (openclaw plugins install @martian-engineering/lossless-claw) із власними інструментами пригадування. Спершу налаштуйте його як
рушій контексту; див. Рушій контексту. Потім
спрямуйте активну пам’ять на його інструменти:
lcm_expand до toolsAllow; Lossless Claw використовує його як
низькорівневий інструмент для делегованого розгортання, не призначений для підагента
активної пам’яті верхнього рівня.
Розширені обхідні механізми
Не належать до рекомендованого налаштування.config.thinking перевизначає рівень міркувань підагента (за замовчуванням "off",
оскільки активна пам’ять працює під час формування відповіді, а додатковий час на міркування безпосередньо
збільшує помітну користувачеві затримку):
config.fastMode перевизначає швидкий режим лише для блокувального підагента пам’яті.
Використовуйте true, false або "auto"; залиште значення невстановленим, щоб успадкувати звичайні
налаштування агента, сеансу та моделі. "auto" використовує налаштоване для моделі пригадування
граничне значення fastAutoOnSeconds:
config.promptAppend додає інструкції оператора після стандартного запиту
й перед контекстом розмови — поєднуйте його зі спеціальним toolsAllow, коли
плагіну пам’яті, що не належить до ядра, потрібен певний порядок інструментів або формування запиту:
config.promptOverride повністю замінює стандартний запит (контекст
розмови все одно додається після нього). Не рекомендовано, якщо тільки ви свідомо
не тестуєте інший контракт пригадування — стандартний запит налаштовано на повернення
або NONE, або стислого контексту з фактами про користувача для основної моделі:
Збереження транскриптів
Запуски блокувального підагента створюють справжній транскриптsession.jsonl під час
виклику. За замовчуванням він записується до тимчасового каталогу та видаляється відразу
після завершення запуску.
Щоб зберігати ці транскрипти на диску для налагодження:
config.transcriptDir. Використовуйте це
обережно: транскрипти можуть швидко накопичуватися в активних сеансах, режим запитів full
дублює значну частину контексту розмови, а ці транскрипти містять
прихований контекст запиту та пригадані спогади.
Конфігурація
Уся конфігурація активної пам’яті міститься вplugins.entries.active-memory.
Корисні поля налаштування:
Рекомендоване налаштування
Почніть ізrecent:
/verbose on для рядка стану та /trace on для зведення налагодження —
обидва надсилаються додатковим повідомленням після основної відповіді, а не
до неї. Потім перейдіть на message, щоб зменшити затримку, або на full, якщо додатковий контекст
вартий повільнішого запуску підагента.
Допуск на холодний запуск
До v2026.5.2 Plugin непомітно подовжував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 поверне порожній
результат, поки триває прогрівання.
Налагодження
Якщо активна пам’ять не відображається там, де очікується:- Переконайтеся, що Plugin увімкнено в
plugins.entries.active-memory.enabled. - Переконайтеся, що ідентифікатор поточного агента зазначено в
config.agents. - Переконайтеся, що тестування виконується через інтерактивний постійний сеанс чату.
- Увімкніть
config.logging: trueі стежте за журналами Gateway. - Перевірте роботу самого пошуку в пам’яті за допомогою
openclaw status --deep.
maxSummaryChars. Якщо активна пам’ять працює
надто повільно, зменште queryMode, зменште timeoutMs або скоротіть кількість останніх реплік і
обмеження кількості символів на репліку.
Поширені проблеми
Активна пам’ять використовує конвеєр пригадування налаштованого Plugin пам’яті, тому більшість несподіваних результатів пригадування спричинені проблемами постачальника вбудовувань, а не помилками активної пам’яті. Стандартний шляхmemory-core використовує memory_search і memory_get;
слот memory-lancedb використовує memory_recall. Якщо використовується інший Plugin
пам’яті, переконайтеся, що config.toolsAllow містить назви інструментів, які цей Plugin справді
реєструє.
Постачальника вбудовувань змінено або він припинив працювати
Постачальника вбудовувань змінено або він припинив працювати
Якщо
memorySearch.provider не задано, OpenClaw використовує вбудовування OpenAI. Явно задайте
memorySearch.provider для вбудовувань Bedrock, DeepInfra, Gemini, GitHub
Copilot, LM Studio, локальних вбудовувань, Mistral, Ollama, Voyage або сумісних з OpenAI.
Якщо налаштований постачальник не може працювати, memory_search може
перейти до пошуку лише за лексичними збігами; збої під час виконання після того, як постачальника
вже вибрано, не спричиняють автоматичного переходу на резервний варіант.Задавайте необов’язковий memorySearch.fallback лише тоді, коли потрібен навмисно
обраний єдиний резервний варіант. Повний список постачальників і приклади наведено на сторінці
Пошук у пам’яті.Пригадування здається повільним, порожнім або непослідовним
Пригадування здається повільним, порожнім або непослідовним
- Увімкніть
/trace on, щоб відображати в сеансі належне Plugin зведення налагодження 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 наведено в розділі Пільговий період холодного запуску
під заголовком «Рекомендоване налаштування».