English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Plugins

Bộ nhớ LanceDB

memory-lancedb là một Plugin bộ nhớ đi kèm, lưu trữ bộ nhớ dài hạn trong LanceDB và dùng embeddings để truy xuất. Plugin này có thể tự động truy xuất các ký ức liên quan trước một lượt mô hình và ghi lại các sự kiện quan trọng sau một phản hồi.

Dùng Plugin này khi bạn muốn có cơ sở dữ liệu vector cục bộ cho bộ nhớ, cần một điểm cuối embedding tương thích với OpenAI, hoặc muốn giữ cơ sở dữ liệu bộ nhớ bên ngoài kho lưu trữ bộ nhớ tích hợp mặc định.

Bắt đầu nhanh

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

Khởi động lại Gateway sau khi thay đổi cấu hình Plugin:

openclaw gateway restart

Sau đó xác minh Plugin đã được tải:

openclaw plugins list

Embeddings dựa trên nhà cung cấp

memory-lancedb có thể dùng cùng các bộ chuyển đổi nhà cung cấp embedding bộ nhớ như memory-core. Đặt embedding.provider và bỏ qua embedding.apiKey để dùng hồ sơ xác thực đã cấu hình của nhà cung cấp, biến môi trường, hoặc models.providers.<provider>.apiKey.

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

Đường dẫn này hoạt động với các hồ sơ xác thực của nhà cung cấp có cung cấp thông tin xác thực embedding. Ví dụ, GitHub Copilot có thể được dùng khi hồ sơ/gói Copilot hỗ trợ embeddings:

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

OpenAI Codex / ChatGPT OAuth (openai-codex) không phải là thông tin xác thực embeddings của OpenAI Platform. Đối với embeddings OpenAI, hãy dùng hồ sơ xác thực khóa API OpenAI, OPENAI_API_KEY, hoặc models.providers.openai.apiKey. Người dùng chỉ có OAuth có thể dùng nhà cung cấp khác có khả năng embedding như GitHub Copilot hoặc Ollama.

Ollama embeddings

Đối với Ollama embeddings, hãy ưu tiên nhà cung cấp embedding Ollama đi kèm. Nhà cung cấp này dùng điểm cuối Ollama /api/embed gốc và tuân theo cùng các quy tắc xác thực/base URL như nhà cung cấp Ollama được ghi tài liệu trong Ollama.

{
  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,
        },
      },
    },
  },
}

Đặt dimensions cho các mô hình embedding không chuẩn. OpenClaw biết số chiều cho text-embedding-3-small và text-embedding-3-large; các mô hình tùy chỉnh cần giá trị này trong cấu hình để LanceDB có thể tạo cột vector.

Với các mô hình embedding cục bộ nhỏ, hãy giảm recallMaxChars nếu bạn thấy lỗi độ dài ngữ cảnh từ máy chủ cục bộ.

Nhà cung cấp tương thích với OpenAI

Một số nhà cung cấp embedding tương thích với OpenAI từ chối tham số encoding_format, trong khi những nhà cung cấp khác bỏ qua tham số đó và luôn trả về vector number[]. Vì vậy memory-lancedb bỏ qua encoding_format trong các yêu cầu embedding và chấp nhận phản hồi dạng mảng số thực hoặc phản hồi float32 được mã hóa base64.

Nếu bạn có một điểm cuối embeddings thô tương thích với OpenAI nhưng không có bộ chuyển đổi nhà cung cấp đi kèm, hãy bỏ qua embedding.provider (hoặc để là openai) và đặt embedding.apiKey cùng với embedding.baseUrl. Cách này giữ nguyên đường dẫn client trực tiếp tương thích với OpenAI.

Đặt embedding.dimensions cho các nhà cung cấp có số chiều mô hình không được tích hợp sẵn. Ví dụ, ZhiPu embedding-3 dùng 2048 chiều:

{
  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,
          },
        },
      },
    },
  },
}

Giới hạn truy xuất và ghi lại

memory-lancedb có hai giới hạn văn bản riêng biệt:

Thiết lập Mặc định Phạm vi Áp dụng cho
recallMaxChars 1000 100-10000 văn bản gửi đến API embedding để truy xuất
captureMaxChars 500 100-10000 độ dài thông điệp assistant đủ điều kiện để ghi lại

recallMaxChars kiểm soát tự động truy xuất, công cụ memory_recall, đường dẫn truy vấn memory_forget, và openclaw ltm search. Tự động truy xuất ưu tiên thông điệp người dùng mới nhất trong lượt và chỉ quay về prompt đầy đủ khi không có thông điệp người dùng nào. Điều này giữ siêu dữ liệu kênh và các khối prompt lớn khỏi yêu cầu embedding.

captureMaxChars kiểm soát việc một phản hồi có đủ ngắn để được xem xét ghi lại tự động hay không. Nó không giới hạn embeddings của truy vấn truy xuất.

Lệnh

Khi memory-lancedb là Plugin bộ nhớ đang hoạt động, nó đăng ký namespace CLI ltm:

openclaw ltm list
openclaw ltm search "project preferences"
openclaw ltm stats

Plugin này cũng mở rộng openclaw memory bằng tiểu lệnh query không dùng vector chạy trực tiếp trên bảng LanceDB:

openclaw memory query --cols id,text,createdAt --limit 20
openclaw memory query --filter "category = 'preference'" --order-by createdAt:desc
  • --cols <columns>: danh sách cho phép cột, phân tách bằng dấu phẩy (mặc định là id, text, importance, category, createdAt).
  • --filter <condition>: mệnh đề WHERE kiểu SQL; giới hạn ở 200 ký tự và chỉ cho phép chữ số, toán tử so sánh, dấu ngoặc kép, dấu ngoặc đơn, và một tập nhỏ dấu câu an toàn.
  • --limit <n>: số nguyên dương; mặc định 10.
  • --order-by <column>:<asc|desc>: sắp xếp trong bộ nhớ được áp dụng sau bộ lọc; cột sắp xếp được tự động đưa vào phép chiếu.

Agents cũng nhận các công cụ bộ nhớ LanceDB từ Plugin bộ nhớ đang hoạt động:

  • memory_recall để truy xuất dựa trên LanceDB
  • memory_store để lưu các sự kiện, tùy chọn, quyết định và thực thể quan trọng
  • memory_forget để xóa các ký ức khớp

Lưu trữ

Theo mặc định, dữ liệu LanceDB nằm trong ~/.openclaw/memory/lancedb. Ghi đè đường dẫn bằng dbPath:

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

storageOptions chấp nhận các cặp khóa/giá trị chuỗi cho backend lưu trữ LanceDB và hỗ trợ mở rộng ${ENV_VAR}:

{
  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",
          },
        },
      },
    },
  },
}

Phụ thuộc runtime

memory-lancedb phụ thuộc vào gói gốc @lancedb/lancedb. OpenClaw đóng gói xem gói đó là một phần của gói Plugin. Quá trình khởi động Gateway không sửa các phụ thuộc của Plugin; nếu thiếu phụ thuộc, hãy cài đặt lại hoặc cập nhật gói Plugin và khởi động lại Gateway.

Nếu một bản cài đặt cũ ghi log lỗi thiếu dist/package.json hoặc thiếu @lancedb/lancedb trong khi tải Plugin, hãy nâng cấp OpenClaw và khởi động lại Gateway.

Nếu Plugin ghi log rằng LanceDB không khả dụng trên darwin-x64, hãy dùng backend bộ nhớ mặc định trên máy đó, chuyển Gateway sang nền tảng được hỗ trợ, hoặc tắt memory-lancedb.

Khắc phục sự cố

Độ dài đầu vào vượt quá độ dài ngữ cảnh

Điều này thường có nghĩa là mô hình embedding đã từ chối truy vấn truy xuất:

memory-lancedb: recall failed: Error: 400 the input length exceeds the context length

Đặt recallMaxChars thấp hơn, rồi khởi động lại Gateway:

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

Đối với Ollama, cũng xác minh máy chủ embedding có thể truy cập được từ máy chủ Gateway:

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

Mô hình embedding không được hỗ trợ

Nếu không có dimensions, chỉ các số chiều embedding OpenAI tích hợp sẵn mới được biết. Đối với mô hình embedding cục bộ hoặc tùy chỉnh, hãy đặt embedding.dimensions thành kích thước vector do mô hình đó báo cáo.

Plugin tải nhưng không có ký ức nào xuất hiện

Kiểm tra rằng plugins.slots.memory trỏ đến memory-lancedb, rồi chạy:

openclaw ltm stats
openclaw ltm search "recent preference"

Nếu autoCapture bị tắt, Plugin sẽ truy xuất các ký ức hiện có nhưng sẽ không tự động lưu ký ức mới. Dùng công cụ memory_store hoặc bật autoCapture nếu bạn muốn ghi lại tự động.

Liên quan