設定 OpenClaw 主動記憶功能：提升對話回應的精準度與自然感

將這段代碼貼入你的 Agent

如果你想用一套獨立且安全的預設設定來啟動 Active Memory，直接把這段代碼貼進你的 agent 即可：

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          enabled: true,
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallbackPolicy: "default-remote",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

這會為 main agent 開啟外掛，預設限制在 direct-message 類型的會話，並讓它優先繼承當前會話的 model。如果沒有明確指定或繼承到 model，它仍會使用內建的 remote fallback。

接著重啟 Gateway：

openclaw gateway

想在對話中即時觀察它的話：

/verbose on

開啟 Active Memory

最安全的設定步驟如下：

1. 啟用外掛並指定一個對話 agent
2. 只有在調校時才開啟 logging

先在 openclaw.json 加入這些內容：

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          allowedChatTypes: ["direct"],
          modelFallbackPolicy: "default-remote",
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          persistTranscripts: false,
          logging: true,
        },
      },
    },
  },
}

然後重啟 Gateway：

openclaw gateway

這些設定代表：

• plugins.entries.active-memory.enabled: true 會開啟外掛
• config.agents: ["main"] 讓 main agent 加入 Active Memory 的行列
• config.allowedChatTypes: ["direct"] 預設只在 direct-message 類型的會話中保持開啟
• 如果沒設定 config.model，Active Memory 會優先繼承當前會話的 model
• config.modelFallbackPolicy: "default-remote" 確保在沒有指定或繼承 model 時，使用內建的 remote fallback 作為預設值
• config.promptStyle: "balanced" 在 recent 模式下使用預設的通用 prompt 風格
• Active Memory 仍僅在符合條件的互動式持久化聊天會話中執行

如何查看運行狀況

Active Memory 會為 model 注入隱藏的系統上下文。它不會直接把原始的 <active_memory_plugin>...</active_memory_plugin> 標籤顯示給用戶端。

會話切換開關

如果你想在不修改設定檔的情況下，暫停或恢復當前對話的 Active Memory，可以使用外掛指令：

/active-memory status
/active-memory off
/active-memory on

這只會影響當前會話。它不會改變 plugins.entries.active-memory.enabled、agent 目標或其他全域設定。

如果你想透過指令修改設定，並針對所有會話暫停或恢復 Active Memory，請使用全域形式：

/active-memory status --global
/active-memory off --global
/active-memory on --global

全域形式會修改 plugins.entries.active-memory.config.enabled。它會保持 plugins.entries.active-memory.enabled 為開啟狀態，這樣你之後還能用指令把它調回來。

如果你想看 Active Memory 在即時對話中做了什麼，請開啟該會話的 verbose 模式：

/verbose on

開啟 verbose 後，OpenClaw 會顯示：

• 一行 Active Memory 狀態，例如 Active Memory: ok 842ms recent 34 chars
• 一個易讀的除錯摘要，例如 Active Memory Debug: Lemon pepper wings with blue cheese.

這些內容來自餵給隱藏系統上下文的同一次 Active Memory 運算，但它們經過格式化，方便人類閱讀，而不是原始的 prompt 標記。

預設情況下，這個阻斷式的 memory sub-agent 紀錄是暫時的，執行完就會刪除。

範例流程：

/verbose on
what wings should i order?

預期的回覆外觀：

...normal assistant reply...

🧩 Active Memory: ok 842ms recent 34 chars
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.

執行時機

Active memory 的運作主要通過兩個關卡：

1. Config 選項 你必須啟用 Plugin，且目前的 Agent ID 必須出現在 plugins.entries.active-memory.config.agents 中。
2. 嚴格的 Runtime 資格 即使已經啟用並指定了 Agent，Active memory 也只會在符合條件的互動式 Persistent chat session 中執行。

實際的規則如下：

plugin enabled
+
agent id targeted
+
allowed chat type
+
eligible interactive persistent chat session
=
active memory runs

如果其中任何一項不符合，Active memory 就不會執行。

對話類型

config.allowedChatTypes 決定了哪些類型的對話可以執行 Active memory。

預設值是：

allowedChatTypes: ["direct"]

這代表 Active memory 預設會在 Direct-message 風格的 Session 中執行，但除非你手動將其加入清單，否則它不會在群組或頻道 Session 中運作。

範例：

allowedChatTypes: ["direct"]

allowedChatTypes: ["direct", "group"]

allowedChatTypes: ["direct", "group", "channel"]

在哪裡執行

Active memory 是一項強化對話的功能，而不是平台級別的 Inference 功能。

介面	是否執行 Active memory？
Control UI / Web chat persistent sessions	是，如果 Plugin 已啟用且 Agent 已被指定
相同 Persistent chat 路徑上的其他互動式頻道 Session	是，如果 Plugin 已啟用且 Agent 已被指定
Headless one-shot 執行	否
Heartbeat/背景執行	否
通用的內部 agent-command 路徑	否
Sub-agent/內部 Helper 執行	否

為什麼要使用它

在以下情況，我推薦你使用 Active memory：

• Session 是持續性的且面向使用者，同時 Agent 擁有值得搜尋的有意義長期記憶
• 連貫性和個人化體驗比單純的 Prompt 確定性更重要

它非常適合處理：

• 穩定的偏好設定與重複的習慣
• 應該自然呈現的長期使用者 Context

但它不適合用於：

• 自動化流程
• 內部 Worker
• One-shot API 任務
• 隱藏的個人化會讓人感到意外的地方

運作原理

執行時的運作流程如下：

flowchart LR
  U["User Message"] --> Q["Build Memory Query"]
  Q --> R["Active Memory Blocking Memory Sub-Agent"]
  R -->|NONE or empty| M["Main Reply"]
  R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
  I --> M["Main Reply"]

這個阻斷式記憶子代理（blocking memory sub-agent）只能使用：

• memory_search
• memory_get

如果連線不穩，它應該回傳 NONE。

查詢模式

config.queryMode 決定了阻斷式記憶子代理能看到多少對話內容。

Prompt 風格

config.promptStyle 控制了阻斷式記憶子代理在決定是否回傳記憶時，是偏向積極還是嚴格。

可用的風格包括：

• balanced：適用於 recent 模式的通用預設值
• strict：最不積極；當你不希望受到鄰近上下文干擾時最適合
• contextual：對連貫性最友善；當對話歷史紀錄較為重要時最適合
• recall-heavy：即便匹配程度較弱但仍屬合理時，也更願意提取記憶
• precision-heavy：除非匹配非常明顯，否則會強烈傾向回傳 NONE
• preference-only：針對喜好、習慣、例行公事、口味以及重複出現的個人事實進行優化

當未設定 config.promptStyle 時的預設對應關係：

message -> strict
recent -> balanced
full -> contextual

如果你明確設定了 config.promptStyle，該覆寫設定將會優先生效。

範例：

promptStyle: "preference-only"

模型備援策略

如果 config.model 未設定，Active Memory 會依序嘗試解析模型：

explicit plugin model
-> current session model
-> agent primary model
-> optional built-in remote fallback

config.modelFallbackPolicy 控制最後一個步驟。

預設值：

modelFallbackPolicy: "default-remote"

其他選項：

modelFallbackPolicy: "resolved-only"

如果你希望在沒有明確或繼承模型可用時，讓 Active Memory 直接跳過提取流程，而不是退而求其次使用內建的遠端預設值，請使用 resolved-only。

進階逃生艙

這些選項刻意不放在推薦設定中。

config.thinking 可以覆蓋阻斷式記憶子代理（blocking memory sub-agent）的思考等級：

thinking: "medium"

預設值：

thinking: "off"

不要預設啟用這個功能。Active Memory 運行在回覆路徑上，所以額外的思考時間會直接增加使用者感受到的延遲。

config.promptAppend 會在預設的 Active Memory 提示詞之後、對話上下文之前，加入額外的操作指令：

promptAppend: "Prefer stable long-term preferences over one-off events."

config.promptOverride 會替換掉預設的 Active Memory 提示詞。OpenClaw 之後仍然會附加對話上下文：

promptOverride: "You are a memory search agent. Return NONE or one compact user fact."

除非你是在刻意測試不同的檢索契約（recall contract），否則不建議自訂提示詞。預設提示詞已經針對主模型回傳 NONE 或精簡的使用者事實上下文進行了優化。

message

只會發送最新的使用者訊息。

Latest user message only

適用場景：

• 你想要最快的反應速度
• 你希望對穩定偏好檢索有最強的偏向
• 後續對話不需要對話上下文

推薦超時時間（timeout）：

• 從 3000 到 5000 ms 開始嘗試

recent

發送最新的使用者訊息加上一小段最近的對話結尾。

Recent conversation tail:
user: ...
assistant: ...
user: ...

Latest user message:
...

適用場景：

• 你想在速度和對話基礎（conversational grounding）之間取得更好的平衡
• 後續問題通常依賴於最後幾輪對話

推薦超時時間（timeout）：

• 從 15000 ms 左右開始嘗試

full

完整的對話都會發送到阻斷式記憶子代理。

Full conversation context:
user: ...
assistant: ...
user: ...
...

適用場景：

• 最強的檢索品質比延遲更重要
• 對話中包含很久以前的重要設定

推薦超時時間（timeout）：

• 相比 message 或 recent 應大幅增加
• 從 15000 ms 或更高開始，具體取決於對話串的大小

通常情況下，超時時間應隨上下文大小增加：

message < recent < full

對話紀錄持久化

Active memory 的阻斷式記憶子代理在執行時，會產生一個真實的 session.jsonl 紀錄。

預設情況下，該紀錄是暫存的：

• 它被寫入暫存目錄
• 僅用於該次阻斷式記憶子代理執行
• 執行結束後立即刪除

如果你想將這些阻斷式記憶子代理的紀錄保留在磁碟上以便偵錯或檢查，請明確開啟持久化功能：

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          persistTranscripts: true,
          transcriptDir: "active-memory",
        },
      },
    },
  },
}

啟用後，Active Memory 會將紀錄儲存在目標代理 sessions 資料夾下的一個獨立目錄中，而不是主使用者對話紀錄路徑。

預設佈局概念上如下：

agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl

你可以透過 config.transcriptDir 更改相對子目錄。

請謹慎使用：

• 在繁忙的 session 中，阻斷式記憶子代理紀錄會迅速累積
• full 查詢模式可能會重複大量的對話上下文
• 這些紀錄包含隱藏的提示詞上下文和檢索到的記憶

設定

所有 active memory 的設定都在這裡：

plugins.entries.active-memory

最重要的欄位如下：

Key	Type	Meaning
enabled	boolean	啟用外掛程式
config.agents	string[]	可以使用 active memory 的 Agent ID
config.model	string	選填的 blocking memory sub-agent 模型參考；未設定時，active memory 會使用目前的 session 模型
config.queryMode	"message" | "recent" | "full"	控制 blocking memory sub-agent 能看到多少對話內容
config.promptStyle	"balanced" | "strict" | "contextual" | "recall-heavy" | "precision-heavy" | "preference-only"	控制 blocking memory sub-agent 在決定是否回傳記憶時的積極或嚴格程度
config.thinking	"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive"	blocking memory sub-agent 的進階思考覆寫；預設為 off 以追求速度
config.promptOverride	string	進階的完整 prompt 替換；一般使用不建議修改
config.promptAppend	string	附加在預設或覆寫 prompt 後面的進階額外指令
config.timeoutMs	number	blocking memory sub-agent 的硬性逾時時間
config.maxSummaryChars	number	active-memory 摘要中允許的最大總字元數
config.logging	boolean	在調整參數時輸出 active memory 日誌
config.persistTranscripts	boolean	將 blocking memory sub-agent 的逐字稿保留在磁碟上，而不是刪除暫存檔
config.transcriptDir	string	Agent sessions 資料夾下的 blocking memory sub-agent 逐字稿相對路徑

實用的調優欄位：

Key	Type	Meaning
config.maxSummaryChars	number	active-memory 摘要中允許的最大總字元數
config.recentUserTurns	number	當 queryMode 為 recent 時，要包含的先前使用者輪次
config.recentAssistantTurns	number	當 queryMode 為 recent 時，要包含的先前 Assistant 輪次
config.recentUserChars	number	每個近期使用者輪次的最大字元數
config.recentAssistantChars	number	每個近期 Assistant 輪次的最大字元數
config.cacheTtlMs	number	重複相同查詢時的快取重複使用時間

推薦設定

建議先從 recent 開始。

{
  plugins: {
    entries: {
      "active-memory": {
        enabled: true,
        config: {
          agents: ["main"],
          queryMode: "recent",
          promptStyle: "balanced",
          timeoutMs: 15000,
          maxSummaryChars: 220,
          logging: true,
        },
      },
    },
  },
}

如果你想在調整時觀察即時行為，請在 session 中使用 /verbose on，不需要去找獨立的 active-memory 除錯指令。

接著可以嘗試：

• 如果你想要更低的延遲，改用 message
• 如果你覺得為了額外的上下文，讓 blocking memory sub-agent 慢一點也值得，那就改用 full

除錯

如果你發現 active memory 沒有出現在預期的位置，請檢查以下幾點：

1. 確認 plugins.entries.active-memory.enabled 下的 plugin 已啟用。
2. 確認目前的 agent id 有列在 config.agents 中。
3. 確認你正在透過互動式的持續對話（persistent chat session）進行測試。
4. 開啟 config.logging: true 並觀察 Gateway 的 logs。
5. 使用 openclaw memory status --deep 驗證 memory search 本身是否運作正常。

如果 memory 命中結果太雜亂，可以縮減：

• maxSummaryChars

如果 active memory 太慢，建議：

• 調低 queryMode
• 調低 timeoutMs
• 減少最近的對話輪數（turn counts）
• 減少每輪的字元限制（char caps）

相關頁面

• Memory Search
• Memory 設定參考
• Plugin SDK 設定