記憶設定參考資料

此頁列出 OpenClaw 記憶搜尋的所有設定選項。若要瞭解概念概述，請參閱：

除非另有註明，所有記憶搜尋設定都位於 agents.defaults.memorySearch 的 openclaw.json 中（或每個代理程式的 agents.list[].memorySearch 覆寫設定）。

提供者選擇

未設定 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 排名。

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

自訂提供者 ID

memorySearch.provider 可以指向自訂的 models.providers.<id> 項目，用於記憶專用提供者配接器（例如 ollama），或用於 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" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

API 金鑰解析

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

遠端端點設定

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

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

提供者特定設定

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

{  agents: {    defaults: {      memorySearch: {        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

行內嵌入逾時

索引行為

除非另有註明，所有設定皆位於 memorySearch.sync 下：

混合搜尋設定

所有設定皆位於 memorySearch.query 下：

以及 memorySearch.query.hybrid 下：

完整範例

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          hybrid: {            vectorWeight: 0.7,            textWeight: 0.3,            mmr: { enabled: true, lambda: 0.7 },            temporalDecay: { enabled: true, halfLifeDays: 30 },          },        },      },    },  },}

其他記憶路徑

{  agents: {    defaults: {      memorySearch: {        extraPaths: ["../team-docs", "/srv/shared-notes"],      },    },  },}

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

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

多模態記憶（Gemini）

使用 Gemini Embedding 2 為影像、音訊與 Markdown 一併建立索引：

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

嵌入快取

避免在重新建立索引或更新逐字稿時，再次嵌入未變更的文字。將 maxEntries 保持未設定可使用無上限快取；當磁碟成長比重新建立索引的最高速度更重要時，請設定此值。設定後，一旦快取超過限制，會優先刪除最舊的項目（依最後更新時間排序）。

批次索引

適用於 gemini、openai 和 voyage。對大型回填作業而言，OpenAI 批次通常速度最快且成本最低。

remote.nonBatchConcurrency 控制本機／自行託管提供者，以及未啟用提供者批次 API 時的託管提供者所使用的內嵌嵌入呼叫。Ollama 的非批次索引預設為 1，以免較小型的本機主機負荷過重；在較大型的機器上可設定更高的值。

這與 sync.embeddingBatchTimeoutSeconds 不同，後者控制內嵌嵌入呼叫的逾時時間。

工作階段記憶搜尋（實驗性）

為工作階段逐字稿建立索引，並透過 memory_search 顯示：

工作階段逐字稿的命中結果也遵循 tools.sessions.visibility。預設的 tree 可見性只會公開目前工作階段及其建立的工作階段。若要從其他 工作階段（例如私訊）回想由閘道分派、屬於同一代理程式但不相關的工作階段， 請有意將可見性擴大為 agent（只有在同時需要跨代理程式回想， 且代理程式間政策允許時，才使用 all）。

下方範例將這些設定放在 agents.defaults 下。如果只有一個 代理程式應為工作階段逐字稿建立索引並進行搜尋，也可以在每個代理程式的覆寫設定中 套用等效的 memorySearch 設定。

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

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

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

使用 QMD 時，agents.defaults.memorySearch.experimental.sessionMemory 和 sources: ["sessions"] 本身不會將逐字稿匯出至 QMD。還必須設定 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 組建則會維持每個集合各自處理的相容路徑。「相同來源」表示持久記憶集合（預設記憶檔案及自訂路徑）會歸為一組，而工作階段逐字稿集合會維持為另一個獨立群組，讓來源多樣化仍能同時取得兩種輸入。

mcporter 整合

全部位於 memory.qmd.mcporter 下。透過長時間執行的 mcporter MCP 常駐程式路由 QMD 搜尋，而不是每次查詢都產生 qmd，以降低較大型模型的冷啟動負擔。

需要安裝 mcporter 並將其加入 PATH，還需要已設定可執行 qmd mcp 的 mcporter 伺服器。若是較簡單的本機設定，且可接受每次查詢產生程序的成本，請維持停用。

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

啟用閘道啟動時的 QMD 初始化後，OpenClaw 只會為符合資格的代理啟動 QMD。如果 update.onBoot 為 true，且未設定間隔／嵌入維護，啟動時會使用一次性管理員執行開機重新整理，完成後將其關閉。如果設定了更新或嵌入間隔，啟動時會開啟長期執行的 QMD 管理員，讓其管理監看器與間隔計時器；update.onBoot: false 只會略過開機時的立即重新整理。

完整 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 下設定，而不是在 agents.defaults.memorySearch 下設定。

夢境整理會以單一排程掃描執行，並將內部的淺層／深層／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",          },        },      },    },  },}

相關內容

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