OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Plugin guides

記憶 LanceDB

memory-lancedb 是官方的外部外掛，使用向量搜尋將長期記憶儲存於 LanceDB。它可在模型執行一輪前自動回想相關記憶，並在回應後自動擷取重要事實。

可將它用於本機向量資料庫、與 OpenAI 相容的嵌入端點，或預設內建記憶後端以外的 記憶儲存區。

安裝

bash
openclaw plugins install @openclaw/memory-lancedb

此外掛已發佈至 npm；並未內建於 OpenClaw 執行階段 映像中。安裝時會寫入外掛項目、啟用外掛，並將 plugins.slots.memory 切換為 memory-lancedb。如果目前由另一個外掛占用 記憶插槽，該外掛會停用並顯示警告。

快速開始

json5
{  plugins: {    slots: {      memory: "memory-lancedb",    },    entries: {      "memory-lancedb": {        enabled: true,        config: {          embedding: {            provider: "openai",            model: "text-embedding-3-small",          },          autoRecall: true,          autoCapture: false,        },      },    },  },}

變更外掛設定後請重新啟動閘道，接著確認外掛已載入：

bash
openclaw gateway restartopenclaw plugins list

嵌入設定

embedding 為必填，且必須至少包含一個欄位。provider 預設為 openai；model 預設為 text-embedding-3-small。

欄位 類型 備註
embedding.provider 字串 轉接器 ID，例如 openai、github-copilot、ollama。預設為 openai。
embedding.model 字串 預設為 text-embedding-3-small。
embedding.apiKey 字串 選填；支援 ${ENV_VAR} 展開。
embedding.baseUrl 字串 選填；支援 ${ENV_VAR} 展開。
embedding.dimensions 整數 (>=1) 不在內建表格中的模型必填（請見下文）。

有兩種請求路徑：

  • 提供者轉接器路徑（預設）：設定 embedding.provider，並省略 embedding.apiKey/embedding.baseUrl。此外掛會透過 memory-core 所使用的同一組記憶嵌入 轉接器，解析提供者已設定的驗證設定檔、環境變數或 models.providers.<provider>.apiKey。此路徑適用於 github-copilot、ollama 以及任何其他內建且支援嵌入的提供者。
  • 直接與 OpenAI 相容的用戶端路徑：不設定 embedding.provider （或設定為 "openai"），並設定 embedding.apiKey 與 embedding.baseUrl。此路徑適用於 沒有內建提供者轉接器、與 OpenAI 相容的原始嵌入端點。

OpenAI Codex / ChatGPT OAuth 並非 OpenAI Platform 的嵌入認證資訊。 若要使用 OpenAI 嵌入，請使用 OpenAI API 金鑰驗證設定檔、OPENAI_API_KEY 或 models.providers.openai.apiKey。僅使用 OAuth 的使用者應選擇其他 支援嵌入的提供者，例如 github-copilot 或 ollama。

json5
{  plugins: {    entries: {      "memory-lancedb": {        enabled: true,        config: {          embedding: {            provider: "github-copilot",            model: "text-embedding-3-small",          },        },      },    },  },}

部分與 OpenAI 相容的嵌入端點會拒絕 encoding_format 參數；其他端點則會忽略它，並一律傳回 number[]。memory-lancedb 會從請求中省略 encoding_format，並接受浮點數陣列或 以 base64 編碼的 float32 回應，因此這兩種回應格式都無須額外設定即可使用。

維度

OpenClaw 僅內建 text-embedding-3-small (1536) 與 text-embedding-3-large (3072) 的維度。其他任何模型都需要明確設定 embedding.dimensions，LanceDB 才能建立向量欄，例如 維度為 2048 的 ZhiPu embedding-3：

json5
{  plugins: {    entries: {      "memory-lancedb": {        enabled: true,        config: {          embedding: {            apiKey: "${ZHIPU_API_KEY}",            baseUrl: "https://open.bigmodel.cn/api/paas/v4",            model: "embedding-3",            dimensions: 2048,          },        },      },    },  },}

Ollama 嵌入

請使用內建的 Ollama 提供者轉接器路徑（embedding.provider: "ollama"）。 它會呼叫 Ollama 原生的 /api/embed 端點，並遵循與 Ollama 提供者相同的驗證／基底 URL 規則。

json5
{  plugins: {    slots: {      memory: "memory-lancedb",    },    entries: {      "memory-lancedb": {        enabled: true,        config: {          embedding: {            provider: "ollama",            baseUrl: "http://127.0.0.1:11434",            model: "mxbai-embed-large",            dimensions: 1024,          },          recallMaxChars: 400,          autoRecall: true,          autoCapture: false,        },      },    },  },}

mxbai-embed-large 不在內建維度表中，因此必須設定 dimensions。 若使用小型本機嵌入模型，且本機伺服器傳回上下文長度錯誤，請降低 recallMaxChars。

回想與擷取限制

設定 預設值 範圍 適用對象
recallMaxChars 1000 100-10000 傳送至嵌入 API 以供回想的文字。
captureMaxChars 500 100-10000 符合自動擷取資格的訊息長度。
customTriggers [] 0-50 個項目，每項 <=100 個字元 讓自動擷取將訊息納入考量的常值詞組。

recallMaxChars 限制 before_prompt_build 自動回想查詢、 memory_recall 工具、memory_forget 查詢路徑以及 openclaw ltm search。自動回想會嵌入該輪最新的使用者訊息；只有在沒有使用者訊息時，才會改用完整提示詞，避免將頻道 中繼資料和大型提示詞區塊納入嵌入請求。

captureMaxChars 會檢查該輪 agent_end 事件中的使用者訊息是否夠短，以判定能否納入自動擷取考量；它不會影響 回想查詢。

customTriggers 會新增不使用規則運算式的常值自動擷取詞組。內建 觸發詞涵蓋常見的英文、捷克文、中文、日文及韓文記憶 詞組（remember、prefer、记住、覚えて、기억해 等）。

自動擷取也會拒絕看似封裝／傳輸中繼資料、 提示詞注入酬載或已注入的 <relevant-memories> 上下文的文字， 且每輪代理程式最多擷取 3 筆記憶。

每筆記憶都由一個代理程式擁有。回想、重複偵測、擷取、 列出、原始查詢及刪除作業，都會先強制檢查擁有者，再傳回或 修改資料列。在其 agents.entries.* 項目中設定 memory.search.enabled: false 的代理程式，或繼承頂層已停用搜尋設定的代理程式，也不會取得任何 memory_recall、memory_store 或 memory_forget 工具，且不會參與自動回想或 擷取，即使外掛層級的 autoRecall/autoCapture 旗標已開啟亦然。

命令

只要安裝 memory-lancedb，它就會註冊 ltm 命令列介面命名空間 （不僅限於它占用作用中記憶插槽時）：

bash
openclaw ltm list [--agent <id>] [--limit <n>] [--order-by-created-at]openclaw ltm search <query> [--agent <id>] [--limit <n>]openclaw ltm stats [--agent <id>]

ltm query 會直接對 LanceDB 資料表執行非向量查詢：

bash
openclaw ltm query --agent research --cols id,text,createdAt --limit 20openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc
旗標 預設值 備註
--agent <id> 已設定的預設代理程式 選取私人代理程式命名空間。可用於 list、search、query 及 stats。
--cols <columns> id,text,importance,category,createdAt 以逗號分隔的欄位允許清單。
--filter <condition> 無 對輸出欄位進行一次比較，例如 category = 'preference' 或 importance >= 0.8。字串值必須加上引號。
--limit <n> 10 正整數。
--order-by <column>:<asc|desc> 無 篩選器執行後在記憶體中排序；排序欄位會自動加入投影，若未要求該欄位，則會從輸出中移除。

代理程式會從作用中的記憶外掛取得三個工具：

  • memory_recall：對已儲存的記憶進行向量搜尋。
  • memory_store：儲存事實、偏好、決策或實體（會拒絕看似提示詞注入酬載的文字； 略過近似重複的儲存內容）。
  • memory_forget：依 memoryId 或 query 刪除（若單一相符項目的分數高於 90%， 便會自動刪除；否則列出候選 ID 以供消除歧義）。

儲存空間

LanceDB 資料預設儲存於 ~/.openclaw/memory/lancedb。可使用 dbPath 覆寫：

json5
{  plugins: {    entries: {      "memory-lancedb": {        enabled: true,        config: {          dbPath: "~/.openclaw/memory/lancedb",          embedding: {            apiKey: "${OPENAI_API_KEY}",            model: "text-embedding-3-small",          },        },      },    },  },}

此外掛會維護一個 LanceDB 資料表，並在每一 資料列上儲存正規化的代理程式擁有者。這是儲存邊界，而不是搜尋後篩選器：代理程式擁有權會在 向量排名前套用，也會納入列出、查詢、計數和刪除 述詞。ltm query --filter 可接受一項針對 公開輸出欄位且經過驗證的比較。儲存區會將此比較與 強制擁有者述詞分開建構，因此篩選器無法將查詢範圍擴大至其他 代理程式。

在導入每個代理程式的擁有權前所建立的資料庫，沒有可靠的資料列來源資訊。 升級時，openclaw doctor --fix 會將這些舊版資料列一次性指派給 已設定的預設代理程式。在該移轉完成之前，執行階段存取會採取失敗關閉； 其他代理程式永遠不會繼承舊有的共用資料列。

storageOptions 接受用於 LanceDB 儲存後端（例如 S3 相容物件儲存）的字串鍵值組，並支援 ${ENV_VAR} 展開：

json5
{  plugins: {    entries: {      "memory-lancedb": {        enabled: true,        config: {          dbPath: "s3://memory-bucket/openclaw",          storageOptions: {            access_key: "${AWS_ACCESS_KEY_ID}",            secret_key: "${AWS_SECRET_ACCESS_KEY}",            endpoint: "${AWS_ENDPOINT_URL}",          },          embedding: {            apiKey: "${OPENAI_API_KEY}",            model: "text-embedding-3-small",          },        },      },    },  },}

執行階段相依套件與平台支援

memory-lancedb 相依於原生 @lancedb/lancedb 套件，且該套件由外掛套件擁有（不屬於 OpenClaw 核心發行套件）。閘道啟動時不會修復外掛相依套件；若缺少原生相依套件或載入失敗，請重新安裝或更新外掛套件，然後重新啟動閘道。

@lancedb/lancedb 未針對 darwin-x64（Intel Mac）發布原生版本。在該平台上，外掛會在載入時記錄 LanceDB 無法使用；請使用預設記憶後端、在支援的平台／架構上執行閘道，或停用 memory-lancedb。

疑難排解

輸入長度超過上下文長度

嵌入模型拒絕了回憶查詢：

text
memory-lancedb: 回憶失敗：錯誤：400 輸入長度超過上下文長度

降低 recallMaxChars，然後重新啟動閘道：

json5
{  plugins: {    entries: {      "memory-lancedb": {        config: {          recallMaxChars: 400,        },      },    },  },}

若使用 Ollama，也請使用其原生嵌入端點，確認可從閘道主機連線至嵌入伺服器：

bash
curl http://127.0.0.1:11434/api/embed \  -H "Content-Type: application/json" \  -d '{"model":"mxbai-embed-large","input":"hello"}'

不支援的嵌入模型

若未設定 embedding.dimensions，系統只知道內建 OpenAI 嵌入模型的維度（text-embedding-3-small、text-embedding-3-large）。對於任何其他模型，請將 embedding.dimensions 設為該模型回報的向量大小。

外掛已載入，但未出現任何記憶

確認 plugins.slots.memory 指向 memory-lancedb，然後執行：

bash
openclaw ltm statsopenclaw ltm search "recent preference"

若已停用 autoCapture，外掛仍會回憶現有記憶，但不會自動儲存新記憶。請使用 memory_store 工具，或啟用 autoCapture。

相關內容

Was this useful?
On this page

On this page