跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

記憶概覽

記憶如何運作。

內建引擎

預設 SQLite 後端。

QMD 引擎

本機優先的 sidecar。

記憶搜尋

搜尋管線與調校。

Active Memory

用於互動式工作階段的記憶子代理。
除非另有註明，所有記憶搜尋設定都位於 openclaw.json 的 agents.defaults.memorySearch 下。
如果你要找的是 Active Memory 功能開關與子代理設定，它位於 plugins.entries.active-memory 下，而不是 memorySearch。Active Memory 使用雙閘門模型：
  1. Plugin 必須已啟用，並以目前的代理 ID 為目標
  2. 請求必須是符合資格的互動式持久聊天工作階段
請參閱 Active Memory，了解啟用模型、Plugin 擁有的設定、逐字稿持久化，以及安全推出模式。

​
Provider 選擇

鍵類型預設值說明
providerstring自動偵測嵌入轉接器 ID，例如 bedrock、deepinfra、gemini、github-copilot、local、mistral、ollama、openai 或 voyage；也可以是已設定的 models.providers.<id>，其 api 指向其中一個轉接器
modelstringprovider 預設值嵌入模型名稱
fallbackstring"none"主要項目失敗時使用的備援轉接器 ID
enabledbooleantrue啟用或停用記憶搜尋

​
自動偵測順序

未設定 provider 時，OpenClaw 會選擇第一個可用項目：
1

local

若已設定 memorySearch.local.modelPath 且檔案存在，則會選取。
2

github-copilot

若可解析 GitHub Copilot token（env var 或 auth profile），則會選取。
3

openai

若可解析 OpenAI key，則會選取。
4

gemini

若可解析 Gemini key，則會選取。
5

voyage

若可解析 Voyage key，則會選取。
6

mistral

若可解析 Mistral key，則會選取。
7

deepinfra

若可解析 DeepInfra key，則會選取。
8

bedrock

若 AWS SDK 憑證鏈可解析（instance role、access keys、profile、SSO、web identity 或 shared config），則會選取。
支援 ollama，但不會自動偵測（請明確設定）。

​
自訂 provider ID

memorySearch.provider 可以指向自訂 models.providers.<id> 項目。OpenClaw 會解析該 provider 的 api 擁有者以用於嵌入轉接器，同時保留自訂 provider ID 以處理端點、驗證和模型前綴。這讓多 GPU 或多主機設定可以將記憶嵌入專用於特定本機端點： 
{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

​
API key 解析

遠端嵌入需要 API key。Bedrock 則改用 AWS SDK 預設憑證鏈（instance roles、SSO、access keys）。
ProviderEnv var設定鍵
BedrockAWS 憑證鏈不需要 API key
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN透過裝置登入的 auth profile
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY（預留位置）—
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
Codex OAuth 只涵蓋聊天/完成，不滿足嵌入請求。

​
遠端端點設定

用於自訂 OpenAI 相容端點，或覆寫 provider 預設值：
​
remote.baseUrl
string
自訂 API 基礎 URL。
​
remote.apiKey
string
覆寫 API key。
​
remote.headers
object
額外 HTTP 標頭（與 provider 預設值合併）。
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

​
Provider 專用設定

鍵類型預設值說明
modelstringgemini-embedding-001也支援 gemini-embedding-2-preview
outputDimensionalitynumber3072對 Embedding 2：768、1536 或 3072
變更模型或 outputDimensionality 會觸發自動完整重新索引。
OpenAI 相容的嵌入端點可以選擇使用 provider 專用的 input_type 請求欄位。這對需要為查詢和文件嵌入使用不同標籤的非對稱嵌入模型很有用。
鍵類型預設值說明
inputTypestring未設定查詢和文件嵌入共用的 input_type
queryInputTypestring未設定查詢時的 input_type；覆寫 inputType
documentInputTypestring未設定索引/文件的 input_type；覆寫 inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
當上游模型以不同方式處理這些標籤時，變更這些值會影響 provider 批次索引的嵌入快取識別，且之後應重新索引記憶。

​
Bedrock 嵌入設定

Bedrock 使用 AWS SDK 預設憑證鏈，不需要 API key。如果 OpenClaw 在具有 Bedrock 啟用 instance role 的 EC2 上執行，只需設定 provider 和模型：
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
鍵類型預設值說明
modelstringamazon.titan-embed-text-v2:0任何 Bedrock 嵌入模型 ID
outputDimensionalitynumber模型預設值對 Titan V2：256、512 或 1024
支援的模型（含系列偵測和維度預設值）：
模型 IDProvider預設維度可設定維度
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536—
amazon.titan-embed-g1-text-02Amazon1536—
amazon.titan-embed-image-v1Amazon1024—
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024—
cohere.embed-multilingual-v3Cohere1024—
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512—
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024—
具有輸送量後綴的變體（例如 amazon.titan-embed-text-v1:2:8k）會繼承基礎模型的設定。驗證： Bedrock 驗證使用標準 AWS SDK 憑證解析順序：
  1. 環境變數（AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY）
  2. SSO token 快取
  3. Web identity token 憑證
  4. 共用憑證和設定檔
  5. ECS 或 EC2 metadata 憑證
區域會從 AWS_REGION、AWS_DEFAULT_REGION、amazon-bedrock provider baseUrl 解析，或預設為 us-east-1。IAM 權限： IAM 角色或使用者需要：
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
若採最小權限，請將 InvokeModel 範圍限定於特定模型：
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
KeyTypeDefaultDescription
local.modelPathstringauto-downloadedGGUF 模型檔案的路徑
local.modelCacheDirstringnode-llama-cpp default已下載模型的快取目錄
local.contextSizenumber | "auto"4096嵌入情境的情境視窗大小。4096 可涵蓋典型區塊（128–512 個 token），同時限制非權重 VRAM。受限主機可降低至 1024–2048。"auto" 會使用模型訓練時的最大值，不建議用於 8B+ 模型（Qwen3-Embedding-8B：40 960 個 token → 約 32 GB VRAM，相較於 4096 時約 8.8 GB）。
預設模型：embeddinggemma-300m-qat-Q8_0.gguf（約 0.6 GB，自動下載）。原始碼簽出仍需要原生建置核准：pnpm approve-builds，然後執行 pnpm rebuild node-llama-cpp。使用獨立 CLI 驗證 Gateway 使用的相同提供者路徑：
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
如果 provider 是 auto，只有在 local.modelPath 指向現有本機檔案時才會選取 local。hf: 和 HTTP(S) 模型參照仍可搭配 provider: "local" 明確使用，但在模型可於磁碟上使用之前，它們不會讓 auto 選取本機。

​
內嵌嵌入逾時

​
sync.embeddingBatchTimeoutSeconds
number
覆寫記憶體索引期間內嵌嵌入批次的逾時。未設定時會使用提供者預設值：對於 local、ollama 和 lmstudio 等本機/自託管提供者為 600 秒，對於託管提供者為 120 秒。當本機 CPU 密集的嵌入批次狀態正常但速度較慢時，請提高此值。

​
混合搜尋設定

全部位於 memorySearch.query.hybrid 下：
KeyTypeDefaultDescription
enabledbooleantrue啟用混合 BM25 + 向量搜尋
vectorWeightnumber0.7向量分數的權重 (0-1)
textWeightnumber0.3BM25 分數的權重 (0-1)
candidateMultipliernumber4候選池大小乘數
KeyTypeDefaultDescription
mmr.enabledbooleanfalse啟用 MMR 重新排序
mmr.lambdanumber0.70 = 最大多樣性，1 = 最大相關性

​
完整範例

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

​
其他記憶體路徑

KeyTypeDescription
extraPathsstring[]要索引的其他目錄或檔案
{
  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 一起索引：
KeyTypeDefaultDescription
multimodal.enabledbooleanfalse啟用多模態索引
multimodal.modalitiesstring[]—["image"]、["audio"] 或 ["all"]
multimodal.maxFileBytesnumber10000000索引的最大檔案大小
僅適用於 extraPaths 中的檔案。預設記憶根目錄仍僅支援 Markdown。需要 gemini-embedding-2-preview。fallback 必須是 "none"。
支援的格式：.jpg、.jpeg、.png、.webp、.gif、.heic、.heif（圖片）；.mp3、.wav、.ogg、.opus、.m4a、.aac、.flac（音訊）。

​
嵌入快取

KeyTypeDefaultDescription
cache.enabledbooleanfalse在 SQLite 中快取區塊嵌入
cache.maxEntriesnumber50000快取嵌入數量上限
在重新索引或逐字稿更新期間，避免重新嵌入未變更的文字。

​
批次索引

KeyTypeDefaultDescription
remote.nonBatchConcurrencynumber4平行內嵌嵌入
remote.batch.enabledbooleanfalse啟用批次嵌入 API
remote.batch.concurrencynumber2平行批次工作
remote.batch.waitbooleantrue等待批次完成
remote.batch.pollIntervalMsnumber—輪詢間隔
remote.batch.timeoutMinutesnumber—批次逾時
適用於 openai、gemini 和 voyage。對於大型回填，OpenAI 批次通常最快且成本最低。 remote.nonBatchConcurrency 控制本機／自託管供應商，以及未啟用供應商批次 API 時的託管供應商所使用的內嵌嵌入呼叫。Ollama 的非批次索引預設為 1，以避免讓較小的本機主機負載過高；在較大的機器上可設定較高的值。 這與 sync.embeddingBatchTimeoutSeconds 分開，後者控制內嵌嵌入呼叫的逾時。

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

索引工作階段逐字稿，並透過 memory_search 呈現：
KeyTypeDefaultDescription
experimental.sessionMemorybooleanfalse啟用工作階段索引
sourcesstring[]["memory"]新增 "sessions" 以包含逐字稿
sync.sessions.deltaBytesnumber100000重新索引的位元組閾值
sync.sessions.deltaMessagesnumber50重新索引的訊息閾值
工作階段索引為選擇啟用，並以非同步方式執行。結果可能會稍微過期。工作階段記錄儲存在磁碟上，因此請將檔案系統存取視為信任邊界。

​
SQLite 向量加速（sqlite-vec）

KeyTypeDefaultDescription
store.vector.enabledbooleantrue使用 sqlite-vec 進行向量查詢
store.vector.extensionPathstringbundled覆寫 sqlite-vec 路徑
當 sqlite-vec 無法使用時，OpenClaw 會自動退回至程序內餘弦相似度。

​
索引儲存

KeyTypeDefaultDescription
store.pathstring~/.openclaw/memory/{agentId}.sqlite索引位置（支援 {agentId} 權杖）
store.fts.tokenizerstringunicode61FTS5 tokenizer（unicode61 或 trigram）

​
QMD 後端設定

設定 memory.backend = "qmd" 以啟用。所有 QMD 設定都位於 memory.qmd 下：
KeyTypeDefaultDescription
commandstringqmdQMD 可執行檔路徑；當服務 PATH 與你的 shell 不同時，請設定絕對路徑
searchModestringsearch搜尋命令：search、vsearch、query
includeDefaultMemorybooleantrue自動索引 MEMORY.md + memory/**/*.md
paths[]array—額外路徑：{ name, path, pattern? }
sessions.enabledbooleanfalse索引工作階段逐字稿
sessions.retentionDaysnumber—逐字稿保留期限
sessions.exportDirstring—匯出目錄
searchMode: "search" 是僅詞彙/BM25 模式。OpenClaw 不會為該模式執行語意向量就緒探測或 QMD embedding 維護，包括在 memory status --deep 期間；vsearch 與 query 仍然需要 QMD 向量就緒狀態與 embeddings。 OpenClaw 偏好目前的 QMD collection 與 MCP query 形狀，但會在需要時嘗試相容的 collection pattern flags 與較舊的 MCP tool 名稱，以維持較舊 QMD 版本可用。當 QMD 宣告支援多個 collection filters 時，同來源 collections 會以單一 QMD process 搜尋；較舊的 QMD builds 則保留逐 collection 的相容路徑。同來源表示 durable memory collections 會被分組在一起，而 session transcript collections 仍保留為獨立群組，讓 source diversification 仍同時具備兩種輸入。
QMD model overrides 保留在 QMD 端，而不是 OpenClaw config。如果你需要全域覆寫 QMD 的 models，請在 gateway runtime environment 中設定 QMD_EMBED_MODEL、QMD_RERANK_MODEL 與 QMD_GENERATE_MODEL 等 environment variables。
KeyTypeDefaultDescription
update.intervalstring5m重新整理間隔
update.debounceMsnumber15000對檔案變更進行 debounce
update.onBootbooleantrue在長駐 QMD manager 開啟時重新整理；也會控管 opt-in startup refresh
update.startupstringoff選用的 gateway 啟動時重新整理：off、idle 或 immediate
update.startupDelayMsnumber120000startup: "idle" 重新整理執行前的延遲
update.waitForBootSyncbooleanfalse阻擋 manager 開啟，直到其初始重新整理完成
update.embedIntervalstring—獨立的 embed 節奏
update.commandTimeoutMsnumber—QMD commands 的逾時
update.updateTimeoutMsnumber—QMD update operations 的逾時
update.embedTimeoutMsnumber—QMD embed operations 的逾時
KeyTypeDefaultDescription
limits.maxResultsnumber6搜尋結果數上限
limits.maxSnippetCharsnumber—限制 snippet 長度
limits.maxInjectedCharsnumber—限制注入字元總數
limits.timeoutMsnumber4000搜尋逾時
控制哪些 sessions 可以接收 QMD 搜尋結果。Schema 與 session.sendPolicy 相同：
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
隨附的預設值允許 direct 與 channel sessions，同時仍拒絕 groups。預設為僅限 DM。match.keyPrefix 會比對正規化後的 session key；match.rawKeyPrefix 會比對包含 agent:<id>: 的原始 key。
QMD boot refreshes 會在 Gateway 啟動期間使用一次性的 subprocess path。當 memory search 被開啟供互動使用時，長駐 QMD manager 仍負責一般 file watcher 與 interval timers。

​
完整 QMD 範例

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

​
Dreaming

Dreaming 設定於 plugins.entries.memory-core.config.dreaming 之下，而不是 agents.defaults.memorySearch 之下。 Dreaming 會作為單一排程 sweep 執行，並使用內部 light/deep/REM phases 作為 implementation detail。 如需概念行為與 slash commands，請參閱 Dreaming。

​
使用者設定

KeyTypeDefaultDescription
enabledbooleanfalse完整啟用或停用 dreaming
frequencystring0 3 * * *完整 dreaming sweep 的選用 cron 節奏
modelstringdefault model選用的 Dream Diary subagent model override

​
範例

{
  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",
          },
        },
      },
    },
  },
}
  • Dreaming 會將 machine state 寫入 memory/.dreams/。
  • Dreaming 會將人類可讀的敘事輸出寫入 DREAMS.md（或現有的 dreams.md）。
  • dreaming.model 使用既有的 Plugin subagent trust gate；啟用前請先設定 plugins.entries.memory-core.subagent.allowModelOverride: true。
  • 當設定的 model 無法使用時，Dream Diary 會使用 session default model 重試一次。Trust 或 allowlist failures 會被記錄，且不會靜默重試。
  • light/deep/REM phase policy 與 thresholds 是內部行為，不是 user-facing config。

​
相關