Inicio rápido
Pega esto enopenclaw.json para un valor predeterminado seguro: Plugin activado, limitado a main,
solo sesiones de mensajes directos, modelo heredado de la sesión.
plugins.entries.* (incluido active-memory.config) está en la categoría de
configuración sin reinicio:
el Gateway recarga automáticamente el tiempo de ejecución del Plugin y no se
necesita reinicio manual. Si quieres forzar un reinicio completo de todos modos, ejecuta:
plugins.entries.active-memory.enabled: trueactiva el Pluginconfig.agents: ["main"]incluye solo al agentemainconfig.allowedChatTypes: ["direct"]lo limita a sesiones de mensajes directos (incluye grupos/canales explícitamente)config.model(opcional) fija un modelo de recuperación dedicado; si no se define, hereda el modelo de la sesión actualconfig.modelFallbackse usa solo cuando no se resuelve ningún modelo explícito o heredadoconfig.promptStyle: "balanced"es el valor predeterminado para el modorecent- Active Memory aún se ejecuta solo para sesiones de chat persistentes interactivas aptas (consulta Cuándo se ejecuta)
Cómo funciona
El subagente bloqueante solo puede llamar a las herramientas configuradas de recuperación de memoria (consulta Herramientas de memoria). Si la conexión entre la consulta y la memoria disponible es débil, devuelveNONE y la respuesta principal continúa
sin contexto adicional.
Active Memory es una función de enriquecimiento conversacional, no una función de
inferencia para toda la plataforma:
| Superficie | ¿Ejecuta Active Memory? |
|---|---|
| Sesiones persistentes de Control UI / chat web | Sí, si el Plugin está activado y el agente es objetivo |
| Otras sesiones de canal interactivas en la misma ruta de chat persistente | Sí, si el Plugin está activado y el agente es objetivo |
| Ejecuciones sin interfaz de un solo intento | No |
| Ejecuciones Heartbeat/en segundo plano | No |
Rutas internas genéricas de agent-command | No |
| Ejecución de subagente/ayudante interno | No |
Cuándo se ejecuta
Dos compuertas deben pasar ambas:- Activación por configuración — el Plugin está activado y el id del agente actual está en
config.agents. - Elegibilidad en tiempo de ejecución — la sesión es una sesión de chat persistente interactiva apta, su tipo de chat está permitido y su id de conversación no está filtrado.
Tipos de sesión
config.allowedChatTypes controla qué tipos de conversaciones pueden ejecutar
Active Memory. Valor predeterminado:
direct, group, channel, explicit (sesiones estilo portal
con un id de sesión opaco, por ejemplo agent:main:explicit:portal-123).
Las sesiones de mensajes directos se ejecutan de forma predeterminada; las sesiones de grupo, canal y explícitas
deben incluirse:
config.allowedChatIds y config.deniedChatIds:
allowedChatIdses una lista de permitidos de ids de conversación resueltos. Cuando no está vacía, Active Memory solo se ejecuta para sesiones cuyo id de conversación está en la lista; esto restringe todos los tipos de chat permitidos a la vez, incluidos los mensajes directos. Para conservar todos los mensajes directos mientras restringes solo los grupos, agrega también los ids de pares directos aallowedChatIds, o manténallowedChatTypeslimitado al despliegue de grupo/canal que estás probando.deniedChatIdses una lista de denegados que siempre prevalece sobreallowedChatTypesyallowedChatIds.
chat_id/open_id, id de chat de Telegram, id de canal de Slack). La coincidencia
no distingue mayúsculas de minúsculas. Si allowedChatIds no está vacío y OpenClaw no puede
resolver un id de conversación para la sesión, Active Memory omite el turno
en lugar de adivinar.
Alternancia de sesión
Pausa o reanuda Active Memory para la sesión de chat actual sin editar la configuración:plugins.entries.active-memory.config.enabled ni otra configuración global.
Para pausar/reanudar para todas las sesiones en su lugar, usa la forma global (requiere
propietario u operator.admin):
plugins.entries.active-memory.config.enabled pero
deja plugins.entries.active-memory.enabled activado, para que el comando siga
disponible para volver a activar Active Memory más tarde.
Cómo verlo
De forma predeterminada, Active Memory inyecta un prefijo de prompt no confiable oculto que no se muestra en la respuesta normal. Activa los conmutadores de sesión que coincidan con la salida que quieres:/verbose onañade una línea de estado:🧩 Active Memory: status=ok elapsed=842ms query=recent summary=34 chars/trace onañade un resumen de depuración:🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
/trace raw, el bloque rastreado Model Input (User Role) muestra el prefijo oculto
sin procesar:
Modos de consulta
config.queryMode controla cuánta conversación ve el subagente bloqueante.
Elige el modo más pequeño que aún responda bien a seguimientos; aumenta
timeoutMs a medida que crece el tamaño del contexto, de message a recent a full.
- message
- recent
- full
Solo se envía el último mensaje del usuario.Úsalo cuando quieras el comportamiento más rápido, el sesgo más fuerte hacia la recuperación de
preferencias estables, y los turnos de seguimiento no necesiten contexto
conversacional. Empieza alrededor de
3000-5000 ms para config.timeoutMs.Estilos de prompt
config.promptStyle controla qué tan dispuesto o estricto es el subagente para
devolver memoria:
| Estilo | Comportamiento |
|---|---|
balanced | Valor predeterminado de propósito general para el modo recent |
strict | Menos dispuesto; mínima contaminación desde el contexto cercano |
contextual | Más favorable a la continuidad; el historial de conversación pesa más |
recall-heavy | Muestra memoria con coincidencias más suaves pero aún plausibles |
precision-heavy | Prefiere agresivamente NONE salvo que la coincidencia sea obvia |
preference-only | Optimizado para favoritos, hábitos, rutinas, gustos, hechos personales recurrentes |
config.promptStyle no está definido:
config.promptStyle explícito siempre anula la asignación.
Política de modelo de reserva
Siconfig.model no está definido, Active Memory resuelve un modelo en este orden:
config.modelFallbackPolicy es un campo de compatibilidad obsoleto conservado para
configuraciones más antiguas; ya no cambia el comportamiento en tiempo de ejecución: modelFallback es
estrictamente el último recurso en la cadena anterior, no una conmutación por error en tiempo de ejecución que
sustituye otro modelo cuando el resuelto produce un error.
Recomendaciones de velocidad
Dejarconfig.model sin definir (heredar el modelo de la sesión) es el valor
predeterminado más seguro: sigue tu proveedor, autenticación y preferencias de modelo existentes. Para
menor latencia, usa en su lugar un modelo rápido dedicado: la calidad de recuperación importa,
pero la latencia importa más aquí que en la ruta de respuesta principal, y la superficie de
herramientas es estrecha (solo herramientas de recuperación de memoria).
Buenas opciones de modelos rápidos:
cerebras/gpt-oss-120b, un modelo de recuperación dedicado de baja latenciagoogle/gemini-3-flash, una alternativa de baja latencia sin cambiar tu modelo principal de chat- tu modelo de sesión normal, dejando
config.modelsin definir
Configuración de Cerebras
chat/completions para el
modelo elegido; la visibilidad de /v1/models por sí sola no lo garantiza.
Herramientas de memoria
config.toolsAllow establece los nombres concretos de herramientas que puede
llamar el subagente bloqueante. Los valores predeterminados dependen del proveedor de memoria activa:
plugins.slots.memory | toolsAllow predeterminado |
|---|---|
sin definir / memory-core (integrado) | ["memory_search", "memory_get"] |
memory-lancedb | ["memory_recall"] |
toolsAllow solo acepta nombres concretos de herramientas de memoria: los comodines, las entradas
group:* y las herramientas principales del agente (read, exec, message, web_search y
similares) se filtran silenciosamente antes de que se inicie el subagente oculto.
memory-core integrado
No se necesita untoolsAllow explícito:
Memoria LanceDB
Seleccionar el espacio de memoria es suficiente para que la memoria activa usememory_recall:
Lossless Claw
Lossless Claw es un Plugin externo de motor de contexto (openclaw plugins install @martian-engineering/lossless-claw) con sus propias herramientas de recuperación. Configúralo primero como
motor de contexto; consulta Motor de contexto. Luego
dirige la memoria activa a sus herramientas:
lcm_expand a toolsAllow aquí; Lossless Claw lo usa como una
herramienta de nivel inferior para expansión delegada, no pensada para el subagente
de memoria activa de nivel superior.
Vías de escape avanzadas
No forman parte de la configuración recomendada.config.thinking anula el nivel de pensamiento del subagente (predeterminado "off",
porque la memoria activa se ejecuta en la ruta de respuesta y el tiempo de pensamiento adicional
añade directamente latencia visible para el usuario):
config.promptAppend agrega instrucciones del operador después del prompt predeterminado
y antes del contexto de la conversación; combínalo con un toolsAllow personalizado cuando
un Plugin de memoria no principal necesite un orden de herramientas o una formulación de consultas específicos:
config.promptOverride reemplaza por completo el prompt predeterminado (el contexto de la conversación
se sigue anexando después). No se recomienda salvo que se esté probando deliberadamente
un contrato de recuperación distinto; el prompt predeterminado está ajustado para devolver
NONE o contexto compacto de datos del usuario para el modelo principal:
Persistencia de transcripciones
Las ejecuciones de subagentes bloqueantes crean una transcripción realsession.jsonl durante la
llamada. De forma predeterminada, se escribe en un directorio temporal y se elimina inmediatamente
después de que finaliza la ejecución.
Para conservar esas transcripciones en disco para depuración:
config.transcriptDir. Úsalo
con cuidado: las transcripciones pueden acumularse rápidamente en sesiones con mucha actividad, el modo de consulta
full duplica mucho contexto de conversación y estas transcripciones contienen
contexto de prompt oculto más memorias recuperadas.
Configuración
Toda la configuración de memoria activa vive bajoplugins.entries.active-memory.
| Clave | Tipo | Significado |
|---|---|---|
enabled | boolean | Habilita el plugin en sí |
config.agents | string[] | Ids de agentes que pueden usar memoria activa |
config.model | string | Referencia opcional del modelo de subagente bloqueante; si no se establece, hereda el modelo de la sesión actual |
config.allowedChatTypes | ("direct" | "group" | "channel" | "explicit")[] | Tipos de sesión que pueden ejecutar memoria activa; el valor predeterminado es ["direct"] |
config.allowedChatIds | string[] | Lista de permitidos opcional por conversación aplicada después de allowedChatTypes; las listas no vacías fallan en modo cerrado |
config.deniedChatIds | string[] | Lista de denegados opcional por conversación que anula los tipos de sesión permitidos y los ids permitidos |
config.queryMode | "message" | "recent" | "full" | Controla cuánta conversación ve el subagente bloqueante |
config.promptStyle | "balanced" | "strict" | "contextual" | "recall-heavy" | "precision-heavy" | "preference-only" | Controla cuán dispuesto o estricto es el subagente bloqueante al decidir si devolver memoria |
config.toolsAllow | string[] | Nombres concretos de herramientas de memoria que puede llamar el subagente bloqueante; el valor predeterminado es ["memory_search", "memory_get"], o ["memory_recall"] cuando plugins.slots.memory es memory-lancedb; se ignoran comodines, entradas group:* y herramientas del agente central |
config.thinking | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive" | "max" | Anulación avanzada de razonamiento para el subagente bloqueante; valor predeterminado off para mayor velocidad |
config.promptOverride | string | Reemplazo avanzado del prompt completo; no recomendado para uso normal |
config.promptAppend | string | Instrucciones adicionales avanzadas añadidas al prompt predeterminado o anulado |
config.timeoutMs | number | Tiempo de espera estricto para el subagente bloqueante (rango 250-120000 ms; valor predeterminado 15000) |
config.setupGraceTimeoutMs | number | Presupuesto avanzado adicional de configuración antes de que expire el tiempo de espera de recuperación; rango 0-30000 ms, valor predeterminado 0. Consulta gracia de arranque en frío para obtener orientación de actualización a v2026.4.x |
config.maxSummaryChars | number | Máximo de caracteres en el resumen de memoria activa (rango 40-1000; valor predeterminado 220) |
config.logging | boolean | Emite registros de memoria activa durante el ajuste |
config.persistTranscripts | boolean | Mantiene en disco las transcripciones del subagente bloqueante en lugar de eliminar archivos temporales |
config.transcriptDir | string | Directorio relativo de transcripciones del subagente bloqueante bajo la carpeta de sesiones del agente (valor predeterminado "active-memory") |
config.modelFallback | string | Modelo opcional utilizado solo como último paso en la cadena de fallback de modelos |
config.qmd.searchMode | "inherit" | "search" | "vsearch" | "query" | Anula el modo de búsqueda de QMD usado por el subagente bloqueante; valor predeterminado "search" (búsqueda léxica rápida): usa "inherit" para coincidir con la configuración principal del backend de memoria |
| Clave | Tipo | Significado |
|---|---|---|
config.recentUserTurns | number | Turnos previos del usuario que se deben incluir cuando queryMode es recent (rango 0-4; valor predeterminado 2) |
config.recentAssistantTurns | number | Turnos previos del asistente que se deben incluir cuando queryMode es recent (rango 0-3; valor predeterminado 1) |
config.recentUserChars | number | Máximo de caracteres por turno reciente del usuario (rango 40-1000; valor predeterminado 220) |
config.recentAssistantChars | number | Máximo de caracteres por turno reciente del asistente (rango 40-1000; valor predeterminado 180) |
config.cacheTtlMs | number | Reutilización de caché para consultas idénticas repetidas (rango 1000-120000 ms; valor predeterminado 15000) |
config.circuitBreakerMaxTimeouts | number | Omite la recuperación después de esta cantidad de tiempos de espera consecutivos para el mismo agente/modelo. Se restablece tras una recuperación correcta o cuando expira el enfriamiento (rango 1-20; valor predeterminado 3). |
config.circuitBreakerCooldownMs | number | Durante cuánto tiempo omitir la recuperación después de que se active el disyuntor, en ms (rango 5000-600000; valor predeterminado 60000). |
Configuración recomendada
Empieza conrecent:
/verbose on para la línea de estado y /trace on para el resumen de depuración
durante el ajuste: ambos se envían como seguimiento después de la respuesta principal,
no antes. Luego cambia a message para reducir la latencia, o a full si el contexto
adicional compensa la ejecución más lenta del subagente.
Gracia de arranque en frío
Antes de v2026.5.2, el plugin extendía silenciosamentetimeoutMs en 30000
ms adicionales durante el arranque en frío, de modo que el calentamiento del modelo, la carga del índice de embeddings y la primera
recuperación pudieran compartir un presupuesto mayor. v2026.5.2 movió esa gracia detrás de una
configuración explícita setupGraceTimeoutMs: ahora timeoutMs es el presupuesto de trabajo de recuperación
de forma predeterminada, salvo que optes por activarlo. El hook bloqueante envuelve ese presupuesto en
dos fases fijas: hasta 1500 ms para la verificación previa de sesión/configuración antes de que comience la recuperación,
y luego otros 1500 ms fijos para la resolución de abortos y la recuperación de transcripciones
después de que se detenga el trabajo de recuperación. Ninguna de las dos asignaciones extiende la ejecución del modelo o de las herramientas.
Si actualizaste desde v2026.4.x y ajustaste timeoutMs para el mundo anterior
de gracia implícita (el valor inicial recomendado timeoutMs: 15000 es un
ejemplo), establece setupGraceTimeoutMs: 30000 para restaurar el presupuesto efectivo
anterior a v5.2:
timeoutMs + setupGraceTimeoutMs + 3000 ms (el
presupuesto configurado de trabajo de recuperación, más hasta 1500 ms de preflight,
más una asignación fija de 1500 ms para la finalización posterior a la recuperación).
El ejecutor de recuperación integrado usa el mismo presupuesto de tiempo de espera
efectivo, por lo que setupGraceTimeoutMs cubre tanto el watchdog externo de
construcción del prompt como la ejecución interna de recuperación bloqueante.
Para Gateways con recursos ajustados donde la latencia de arranque en frío es una
compensación aceptada, los valores más bajos (5000-15000 ms) también funcionan: la
compensación es una mayor probabilidad de que la primera recuperación después de un
reinicio del Gateway devuelva vacío mientras termina el calentamiento.
Depuración
Si Active Memory no aparece donde esperas:- Confirma que el Plugin esté habilitado en
plugins.entries.active-memory.enabled. - Confirma que el id del agente actual esté incluido en
config.agents. - Confirma que estés probando mediante una sesión de chat persistente interactiva.
- Activa
config.logging: truey observa los registros del Gateway. - Verifica que la búsqueda de memoria funcione con
openclaw status --deep.
maxSummaryChars. Si Active Memory es demasiado
lenta, reduce queryMode, reduce timeoutMs o reduce los recuentos de turnos recientes y
los límites de caracteres por turno.
Problemas comunes
Active Memory se apoya en la canalización de recuperación del Plugin de memoria configurado, por lo que la mayoría de las sorpresas de recuperación son problemas del proveedor de embeddings, no errores de Active Memory. La ruta predeterminadamemory-core usa memory_search y memory_get;
el slot memory-lancedb usa memory_recall. Si usas otro Plugin de memoria,
confirma que config.toolsAllow nombre las herramientas que ese Plugin realmente
registra.
El proveedor de embeddings cambió o dejó de funcionar
El proveedor de embeddings cambió o dejó de funcionar
Si
memorySearch.provider no está definido, OpenClaw usa embeddings de OpenAI. Define
memorySearch.provider explícitamente para embeddings de Bedrock, DeepInfra, Gemini, GitHub
Copilot, LM Studio, local, Mistral, Ollama, Voyage o compatibles con OpenAI.
Si el proveedor configurado no puede ejecutarse, memory_search puede
degradarse a recuperación solo léxica; los fallos en tiempo de ejecución después de que un proveedor
ya esté seleccionado no recurren automáticamente a una alternativa.Define un memorySearch.fallback opcional solo cuando quieras una alternativa
única deliberada. Consulta Búsqueda de memoria para ver la lista completa
de proveedores y ejemplos.La recuperación se siente lenta, vacía o inconsistente
La recuperación se siente lenta, vacía o inconsistente
- Activa
/trace onpara mostrar el resumen de depuración de Active Memory propiedad del Plugin en la sesión. - Activa
/verbose onpara ver también la línea de estado🧩 Active Memory: ...después de cada respuesta. - Observa los registros del Gateway en busca de
active-memory: ... start|done,memory sync failed (search-bootstrap)o errores de embeddings del proveedor. - Ejecuta
openclaw status --deeppara inspeccionar el backend de búsqueda de memoria y el estado del índice. - Si usas
ollama, confirma que el modelo de embeddings esté instalado (ollama list).
La primera recuperación después de reiniciar el Gateway devuelve `status=timeout`
La primera recuperación después de reiniciar el Gateway devuelve `status=timeout`
En v2026.5.2 y versiones posteriores, si la configuración de arranque en frío (calentamiento del modelo + carga del
índice de embeddings) no ha terminado cuando se dispara la primera recuperación, la ejecución
puede alcanzar el presupuesto
timeoutMs configurado y devolver status=timeout
con salida vacía. Los registros del Gateway muestran active-memory timeout after Nms
cerca de la primera respuesta elegible después de un reinicio.Consulta Gracia de arranque en frío en Configuración recomendada para ver el
valor recomendado de setupGraceTimeoutMs.