빠른 시작
안전한 기본값을 사용하려면openclaw.json에 붙여 넣으십시오. Plugin을 켜고, 범위를 main로 한정하며,
다이렉트 메시지 세션에서만 실행하고, 세션의 모델을 상속합니다.
plugins.entries.*(active-memory.config 포함)는 재시작이 필요 없는
구성 범주에 속합니다.
Gateway가 Plugin 런타임을 자동으로 다시 로드하므로 수동으로 재시작할
필요가 없습니다. 그래도 전체 재시작을 강제로 수행하려면 다음을 실행하십시오.
plugins.entries.active-memory.enabled: true은 Plugin을 켭니다config.agents: ["main"]은main에이전트만 사용하도록 설정합니다config.allowedChatTypes: ["direct"]은 범위를 다이렉트 메시지 세션으로 한정합니다(그룹/채널은 명시적으로 사용 설정해야 합니다)config.model(선택 사항)은 전용 회상 모델을 고정합니다. 설정하지 않으면 현재 세션 모델을 상속합니다config.modelFallback은 명시적 모델이나 상속된 모델을 확인할 수 없을 때만 사용됩니다config.fastMode은 기본 에이전트를 변경하지 않고 회상의 빠른 모드를 선택적으로 재정의합니다config.promptStyle: "balanced"은recent모드의 기본값입니다- Active Memory는 여전히 적격한 대화형 영구 채팅 세션에서만 실행됩니다(실행 조건 참조)
작동 방식
차단 방식 하위 에이전트는 구성된 메모리 회상 도구만 호출할 수 있습니다( 메모리 도구 참조). 쿼리와 사용 가능한 메모리 사이의 연관성이 약하면NONE을 반환하며, 기본 응답은 추가 컨텍스트
없이 진행됩니다.
Active Memory는 플랫폼 전체 추론 기능이 아니라 대화를 보강하는 기능입니다.
세션이 영구적이며 사용자에게 노출되고, 에이전트에 검색할 만한 의미 있는
장기 메모리가 있으며, 원시 프롬프트 결정성보다 연속성/개인화가 더 중요한 경우
사용하십시오. 예를 들면 안정적인 선호 사항, 반복되는 습관, 자연스럽게
드러나야 하는 장기 컨텍스트가 있습니다. 자동화, 내부 작업자, 일회성 API 작업,
또는 숨겨진 개인화가 예상 밖으로 느껴질 수 있는 환경에는 적합하지 않습니다.
실행 조건
다음 두 관문을 모두 통과해야 합니다.- 구성에서 사용 설정 — Plugin이 활성화되어 있고 현재 에이전트 ID가
config.agents에 있습니다. - 런타임 적격성 — 세션이 적격한 대화형 영구 채팅 세션이고, 채팅 유형이 허용되며, 대화 ID가 필터링되지 않았습니다.
세션 유형
config.allowedChatTypes은 Active Memory를 실행할 수 있는 대화 유형을
제어합니다. 기본값:
direct, group, channel, explicit(예: agent:main:explicit:portal-123와 같이
불투명한 세션 ID를 사용하는 포털 스타일 세션).
다이렉트 메시지 세션은 기본적으로 실행되며, 그룹, 채널 및 명시적 세션은
사용하도록 설정해야 합니다.
config.allowedChatIds 및 config.deniedChatIds을 추가하십시오.
allowedChatIds은 확인된 대화 ID의 허용 목록입니다. 비어 있지 않으면 Active Memory는 대화 ID가 목록에 있는 세션에서만 실행됩니다. 즉, 다이렉트 메시지를 포함하여 허용된 모든 채팅 유형의 범위를 한꺼번에 좁힙니다. 그룹만 좁히면서 모든 다이렉트 메시지를 유지하려면 다이렉트 상대방 ID도allowedChatIds에 추가하거나,allowedChatTypes의 범위를 테스트 중인 그룹/채널 배포로 한정하십시오.deniedChatIds은 항상allowedChatTypes및allowedChatIds보다 우선하는 거부 목록입니다.
chat_id/open_id, Telegram 채팅 ID, Slack 채널 ID).
일치는 대소문자를 구분하지 않습니다. allowedChatIds이 비어 있지 않은데
OpenClaw가 세션의 대화 ID를 확인할 수 없으면 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
최신 사용자 메시지만 전송합니다.가장 빠른 동작과 안정적인 선호 사항 회상에 대한 가장 강한 편향을 원하고,
후속 턴에 대화 컨텍스트가 필요하지 않을 때 사용하십시오.
config.timeoutMs에서는 약 3000-5000 ms부터 시작하십시오.프롬프트 스타일
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는 자체 회상 도구가 있는 외부 컨텍스트 엔진 Plugin(openclaw plugins install @martian-engineering/lossless-claw)입니다. 먼저 컨텍스트 엔진으로
설정하십시오. 컨텍스트 엔진을 참조하십시오. 그런 다음
Active Memory가 해당 도구를 가리키도록 설정하십시오.
toolsAllow에 lcm_expand을 추가하지 마십시오. Lossless Claw는
이를 위임된 확장을 위한 하위 수준 도구로 사용하며, 최상위 Active Memory
하위 에이전트용이 아닙니다.
고급 이스케이프 해치
권장 설정에 포함되지 않습니다.config.thinking은 하위 에이전트의 사고 수준을 재정의합니다(기본값은 "off"입니다.
Active Memory는 응답 경로에서 실행되므로 추가 사고 시간은 사용자에게 표시되는
지연 시간에 직접 추가됩니다).
config.fastMode은 차단형 메모리 하위 에이전트에 대해서만 고속 모드를 재정의합니다.
true, false 또는 "auto"을 사용하십시오. 일반 에이전트, 세션 및
모델 기본값을 상속하려면 설정하지 마십시오. "auto"은 회상 모델에 구성된
fastAutoOnSeconds 임계값을 사용합니다.
config.promptAppend은 기본 프롬프트 뒤와 대화 컨텍스트 앞에 운영자 지침을
추가합니다. 비핵심 메모리 Plugin에 특정 도구 순서나 쿼리 구성이 필요한 경우
사용자 지정 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 이전에는 Plugin이 콜드 스타트 중에timeoutMs을 추가로 30000
ms만큼 자동 연장하여 모델 준비, 임베딩 인덱스 로드 및 첫 번째
회상이 하나의 더 큰 예산을 공유할 수 있었습니다. v2026.5.2에서는 해당 유예를 명시적인
setupGraceTimeoutMs 구성 뒤로 이동했습니다. 이제 별도로 활성화하지 않으면 timeoutMs이 기본 회상 작업
예산입니다. 차단 훅은 해당 예산을 두 개의 고정 단계로 감쌉니다. 회상이
시작되기 전 세션/구성 사전 점검에 최대 1500 ms를 사용하고, 회상 작업이 중지된 후 중단 처리와 기록
복구에 별도의 고정 1500 ms를 사용합니다. 두 허용 시간 모두 모델 또는 도구
실행 시간을 연장하지 않습니다.
v2026.4.x에서 업그레이드했고 이전의 암묵적 유예 환경에 맞게 timeoutMs을 조정했다면(권장 시작값인 timeoutMs: 15000이 한 가지 예입니다), v5.2 이전의 유효 예산을 복원하도록 setupGraceTimeoutMs: 30000을 설정하십시오.
timeoutMs + setupGraceTimeoutMs + 3000 ms입니다(구성된 회상 작업 예산에 최대 1500 ms의 사전 점검 시간과 고정된 1500 ms의 회상 후 완료 허용 시간을 더한 값). 내장 회상 실행기는 동일한 유효 시간 제한 예산을 사용하므로, setupGraceTimeoutMs은 외부 프롬프트 빌드 감시 장치와 내부 차단 회상 실행을 모두 포괄합니다.
콜드 스타트 지연 시간을 허용 가능한 절충으로 간주하는 리소스가 제한된 Gateway에서는 더 낮은 값(5000-15000 ms)도 사용할 수 있습니다. 다만 Gateway를 다시 시작한 후 워밍업이 완료되는 동안 첫 번째 회상이 빈 결과를 반환할 가능성이 커집니다.
디버깅
Active Memory가 예상한 위치에 표시되지 않는 경우:plugins.entries.active-memory.enabled에서 Plugin이 활성화되어 있는지 확인하십시오.- 현재 에이전트 ID가
config.agents에 나열되어 있는지 확인하십시오. - 대화형 영구 채팅 세션을 통해 테스트하고 있는지 확인하십시오.
config.logging: true을 활성화하고 Gateway 로그를 확인하십시오.openclaw status --deep을 사용하여 메모리 검색 자체가 작동하는지 확인하십시오.
maxSummaryChars을 더 엄격하게 설정하십시오. Active Memory가 너무 느리면 queryMode 또는 timeoutMs을 낮추거나, 최근 턴 수와 턴당 문자 수 제한을 줄이십시오.
일반적인 문제
Active Memory는 구성된 메모리 Plugin의 회상 파이프라인을 사용하므로, 예상치 못한 회상 결과는 대부분 Active Memory 버그가 아니라 임베딩 제공자 문제입니다. 기본memory-core 경로는 memory_search와 memory_get을 사용하며, memory-lancedb 슬롯은 memory_recall을 사용합니다. 다른 메모리 Plugin을 사용하는 경우 config.toolsAllow이 해당 Plugin에서 실제로 등록하는 도구의 이름을 지정하는지 확인하십시오.
임베딩 제공자가 전환되었거나 작동을 중지함
임베딩 제공자가 전환되었거나 작동을 중지함
memorySearch.provider이 설정되지 않은 경우 OpenClaw는 OpenAI 임베딩을 사용합니다. Bedrock, DeepInfra, Gemini, GitHub
Copilot, LM Studio, 로컬, Mistral, Ollama, Voyage 또는 OpenAI 호환
임베딩을 사용하려면 memorySearch.provider을 명시적으로 설정하십시오. 구성된 제공자를 실행할 수 없는 경우 memory_search은
어휘 기반 검색만 사용하도록 성능이 저하될 수 있습니다. 제공자가 이미 선택된 후 발생하는 런타임 실패에는
자동으로 대체 제공자가 사용되지 않습니다.의도적으로 단일 대체 제공자를 사용하려는 경우에만 선택적 memorySearch.fallback을 설정하십시오.
전체 제공자 목록과 예시는 메모리 검색을 참조하십시오.회상이 느리거나 비어 있거나 일관되지 않음
회상이 느리거나 비어 있거나 일관되지 않음
- 세션에서 Plugin이 소유한 Active Memory 디버그
요약을 표시하려면
/trace on을 활성화하십시오. - 각 응답 후
🧩 Active Memory: ...상태 줄도 확인하려면/verbose on을 활성화하십시오. - 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 값은 권장 설정 아래의 콜드 스타트 유예를 참조하십시오.