記憶設定參考資料

此頁列出 OpenClaw 記憶搜尋的所有設定選項。如需概念性概覽，請參閱：

所有共用記憶設定都位於 openclaw.json 的頂層 memory 下。搜尋預設值使用 memory.search；各代理程式的搜尋覆寫使用 agents.entries.*.memory.search。

跨對話記憶

若只有受信任的個人代理程式應使用跨對話逐字稿回憶，請針對該代理程式進行設定：

{  agents: {    entries: {      personal: {        memory: {          search: {            rememberAcrossConversations: true,          },        },      },    },  },}

此值遵循一般的 memory.search 繼承規則，並可由各代理程式覆寫。未設定時，只有在全域 session.dmScope 未設定或為 "main"，且沒有任何繫結具有 session.dmScope 覆寫時，才會預設開啟。設定任何 DM 隔離都會使其預設關閉。明確的 true 或 false 一律優先。啟用後即表示啟用工作階段逐字稿索引，並將 sessions 加入代理程式解析後的記憶來源。使用 QMD 時，這也會啟用該代理程式的工作階段匯出；此模式不需要另外設定 memory.qmd.sessions.enabled。

OpenClaw 的內建記憶提供者在內建與 QMD 後端中都支援此受保護路徑。替代記憶提供者仍可使用自己的回憶掛鉤與進階主動記憶工具，但除非目前的提供者支援受保護的私人逐字稿回憶，否則會略過此設定。 openclaw doctor 會回報不支援的提供者，或明確的主動記憶 toolsAllow 清單遺漏 memory_search。

此擷取邊界比一般工作階段搜尋更為狹窄：

• 只有同一代理程式已識別的私人對話符合資格
• 目前正在回答的對話會被排除
• 群組與頻道會從來源和目的地中排除
• 未知的對話類型會以封閉方式失敗
• 沙箱化回憶無法使用特殊的跨對話授權

此設定不會變更 tools.sessions.visibility、工作階段金鑰、逐字稿儲存、傳遞路由，也不會變更 sessions_list、sessions_history 和 sessions_send 的權限。主動記憶會執行有界限的唯讀擷取流程；擷取無法使用或逾時不會阻擋回覆。

提供者選擇

未設定 provider 時，OpenClaw 會使用 OpenAI 嵌入。若要使用 Bedrock、DeepInfra、Gemini、GitHub Copilot、Mistral、Ollama、Voyage、本機 GGUF 模型或 OpenAI 相容的 /v1/embeddings 端點，請明確設定 provider。 仍使用 provider: "auto" 的舊版設定會解析為 openai。

當 provider 未設定、存在舊版 provider: "auto"，或 provider: "none" 刻意選擇僅使用 FTS 的模式時，即使嵌入無法使用，記憶回憶仍可使用詞彙 FTS 排序。

明確指定的非本機提供者會以封閉方式失敗。如果你將 memory.search.provider 設為具體的遠端後端提供者，例如 Bedrock、DeepInfra、Gemini、GitHub Copilot、LM Studio、Mistral、Ollama、OpenAI、Voyage 或 OpenAI 相容的自訂提供者，而該提供者在執行階段無法使用，memory_search 會傳回無法使用的結果，而不會默默改用僅使用 FTS 的回憶。請修正提供者／驗證設定、切換到可連線的提供者，或在你希望刻意僅使用 FTS 回憶時設定 provider: "none"。

自訂提供者 ID

memory.search.provider 可以指向記憶專用提供者轉接器（例如 ollama）的自訂 models.providers.<id> 項目，或指向 OpenAI 相容模型 API（例如 openai-responses／openai-completions）的項目。OpenClaw 會解析該提供者的 api 擁有者以取得嵌入轉接器，同時保留自訂提供者 ID，用於處理端點、驗證與模型前綴。這可讓多 GPU 或多主機設定將記憶嵌入專門交由特定的本機端點處理：

{  models: {    providers: {      "ollama-5080": {        api: "ollama",        baseUrl: "http://gpu-box.local:11435",        apiKey: "ollama-local",        models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }],      },    },  },  memory: {    search: {      provider: "ollama-5080",      model: "qwen3-embedding:0.6b",    },  },}

API 金鑰解析

遠端嵌入需要 API 金鑰。Bedrock 則改用 AWS SDK 的預設認證資訊鏈（執行個體角色、SSO、存取金鑰或 Bedrock API 金鑰）。

遠端端點設定

針對不應繼承全域 OpenAI 聊天認證資訊的通用 OpenAI 相容 /v1/embeddings 伺服器，請使用 provider: "openai-compatible"。

{  memory: {    search: {      provider: "openai-compatible",      model: "text-embedding-3-small",      remote: {        baseUrl: "https://api.example.com/v1/",        apiKey: "YOUR_KEY",      },    },  },}

提供者特定設定

{  memory: {    search: {      provider: "openai-compatible",      remote: {        baseUrl: "https://embeddings.example/v1",        apiKey: "${EMBEDDINGS_API_KEY}",      },      model: "asymmetric-embedder",      queryInputType: "query",      documentInputType: "passage",    },  },}

{  memory: {    search: {      provider: "bedrock",      model: "amazon.titan-embed-text-v2:0",    },  },}

{  "Effect": "Allow",  "Action": "bedrock:InvokeModel",  "Resource": "*"}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent mainopenclaw memory index --force --agent main

索引行為

記憶引擎負責同步、批次處理、監看，以及壓縮後的 索引啟發式規則。OpenClaw 會使用受維護的預設值保持這些行為啟用， 而不公開各安裝環境的計時開關。

混合搜尋設定

全部位於 memory.search.query 下：

混合式擷取會保持啟用；內建引擎原則會維持停用 MMR 與時間衰減。

完整範例

{  memory: {    search: {      query: {        maxResults: 6,        minScore: 0.35,      },    },  },}

額外記憶路徑

{  memory: {    search: {      extraPaths: ["../team-docs", "/srv/shared-notes"],    },  },}

路徑可以是絕對路徑或相對於工作區的路徑。目錄會以遞迴方式掃描 .md 檔案。符號連結的處理方式取決於作用中的後端：內建引擎會略過符號連結，而 QMD 則依循底層 QMD 掃描器的行為。

若要進行限定代理程式範圍的跨代理程式逐字稿搜尋，請使用 agents.entries.*.memory.search.qmd.extraCollections，而非 memory.qmd.paths。這些額外集合採用相同的 { path, name, pattern? } 結構，但會依代理程式合併；當路徑指向目前工作區之外時，也可保留明確的共用名稱。如果相同的解析後路徑同時出現在 memory.qmd.paths 與 memory.search.qmd.extraCollections 中，QMD 會保留第一個項目並略過重複項目。

多模態記憶（Gemini）

使用 Gemini Embedding 2，將影像與音訊和 Markdown 一併建立索引：

支援的格式：.jpg、.jpeg、.png、.webp、.gif、.heic、.heif（影像）；.mp3、.wav、.ogg、.opus、.m4a、.aac、.flac（音訊）。

嵌入快取

避免在重新建立索引或更新逐字稿時，再次嵌入未變更的文字。

批次索引

適用於 gemini、openai 與 voyage。對於大量回填，OpenAI 批次處理通常速度最快且成本最低。

並行處理、輪詢與逾時行為由提供者負責。

工作階段記憶搜尋

建立工作階段逐字稿索引，並透過 memory_search 提供：

一般由模型呼叫的工作階段逐字記錄搜尋會遵循 tools.sessions.visibility。預設的 tree 可見性會公開目前的工作階段、由其衍生的工作階段，以及 透過環境群組感知所監看、屬於同一代理程式的群組工作階段。其他 不相關的工作階段需要 agent 可見性（只有在也需要跨代理程式 回憶，且代理程式間政策允許時，才可使用 all）。

rememberAcrossConversations 不會擴大該設定。它會提供一項 獨立且僅限執行階段的授權，範圍僅限於有界的主動記憶流程期間， 同一代理程式的私人逐字記錄。

下列範例將這些設定放在頂層 memory.search 之下。如果只有一個 代理程式應索引及搜尋工作階段逐字記錄，也可以在該代理程式的 memory.search 覆寫中套用等效設定。

若要讓同一代理程式從閘道回憶私訊：

{  memory: {    search: {      experimental: { sessionMemory: true },      sources: ["memory", "sessions"],    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  memory: {    backend: "qmd",    search: {      experimental: { sessionMemory: true },      sources: ["memory", "sessions"],    },    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

使用 QMD 時，僅設定 sources: ["sessions"] 並不會將逐字記錄匯出至 QMD。還需設定 memory.qmd.sessions.enabled: true。較高層級的 rememberAcrossConversations: true 設定是例外：它會隱含啟用該代理程式所需的 QMD 工作階段匯出。隱含匯出會保持私密： 一律使用預設的內部匯出位置（設定的 sessions.exportDir 僅套用於明確匯出），只會在 該代理程式的跨對話回憶期間進行搜尋，而且一般的 memory_get 無法讀取。明確設定 memory.qmd.sessions.enabled: true 則會維持現有行為，並將 匯出的逐字記錄納入一般記憶語料庫。

SQLite 向量加速（sqlite-vec）

當 sqlite-vec 無法使用時，OpenClaw 會自動改用程序內的餘弦相似度。

索引儲存

內建記憶索引位於每個代理程式的 OpenClaw SQLite 資料庫中： agents/<agentId>/agent/openclaw-agent.sqlite。

QMD 後端設定

設定 memory.backend = "qmd" 以啟用。所有 QMD 設定都位於 memory.qmd 之下：

searchMode: "search" 僅使用詞彙／BM25。對於此模式，OpenClaw 不會執行語意向量就緒探測或 QMD 嵌入維護，包括在 memory status --deep 期間；vsearch 和 query 仍需要 QMD 向量就緒及嵌入。

rerank: false 只會變更 QMD 的 query 模式，且需要 QMD 2.1 或更新版本。在直接命令列介面模式中，OpenClaw 會傳遞 --no-rerank；在由 mcporter 支援的 MCP 模式中，則會將 rerank: false 傳遞給 QMD 的統一查詢工具。若不設定，將使用 QMD 的預設查詢重新排序行為。

OpenClaw 優先採用目前的 QMD 集合與 MCP 查詢格式，但仍會在需要時嘗試相容的集合模式旗標及較舊的 MCP 工具名稱，以維持舊版 QMD 的運作。當 QMD 宣告支援多個集合篩選條件時，同來源集合會以單一 QMD 程序進行搜尋；較舊的 QMD 組建則維持每個集合各自處理的相容路徑。同來源表示持久記憶集合（預設記憶檔案加上自訂路徑）會歸為一組，而工作階段逐字記錄集合仍會維持為另一組，讓來源多樣化仍同時包含這兩種輸入。

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

QMD 會在首次使用記憶時延遲初始化；其介面卡負責重新整理及嵌入排程。

完整 QMD 範例

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 4, timeoutMs: 4000 },      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

夢境整理

夢境整理是在 plugins.entries.memory-core.config.dreaming 之下設定，而不是在 memory.search 之下。

夢境整理會以單次排程掃描方式執行，並將內部的淺層／深層／REM 階段視為實作細節。

有關概念行為與斜線命令，請參閱夢境整理。

使用者設定

範例

{  plugins: {    entries: {      "memory-core": {        subagent: {          allowModelOverride: true,          allowedModels: ["anthropic/claude-sonnet-4-6"],        },        config: {          dreaming: {            enabled: true,            frequency: "0 3 * * *",            model: "anthropic/claude-sonnet-4-6",          },        },      },    },  },}

相關內容

• 設定參考
• 記憶概覽
• 記憶搜尋