Nhà cung cấp llama.cpp

llama-cpp là plugin nhà cung cấp bên ngoài chính thức dành cho embedding GGUF cục bộ. Plugin này đăng ký mã định danh nhà cung cấp embedding local và sở hữu phần phụ thuộc thời gian chạy node-llama-cpp được memorySearch.provider: "local" sử dụng.

Hãy cài đặt plugin trước khi sử dụng embedding bộ nhớ cục bộ:

openclaw plugins install @openclaw/llama-cpp-provider

Gói npm openclaw chính không bao gồm node-llama-cpp. Việc giữ phần phụ thuộc native trong plugin này giúp ngăn các bản cập nhật npm OpenClaw thông thường xóa thời gian chạy được cài đặt thủ công bên trong thư mục gói OpenClaw.

Cấu hình

Đặt memorySearch.provider thành local:

{  agents: {    defaults: {      memorySearch: {        provider: "local",        local: {          modelPath: "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",        },      },    },  },}

local.modelPath mặc định là URI hf: được hiển thị ở trên (embeddinggemma-300m-qat-Q8_0.gguf). Hãy trỏ giá trị này đến một URI hf: khác hoặc tệp .gguf cục bộ để sử dụng mô hình khác. local.modelCacheDir ghi đè vị trí lưu bộ nhớ đệm của các mô hình đã tải xuống (mặc định: ~/.node-llama-cpp/models), còn local.contextSize chấp nhận một số nguyên hoặc "auto".

Khi local.contextSize là một giá trị số, nhà cung cấp cũng chuyển yêu cầu đó cho cơ chế tự động bố trí lớp trên GPU của node-llama-cpp. Điều này cho phép node-llama-cpp bố trí mô hình và ngữ cảnh embedding cùng nhau trong khi vẫn duy trì các bước kiểm tra an toàn bộ nhớ. Với "auto", node-llama-cpp giữ nguyên cơ chế bố trí tự động thông thường.

Thời gian chạy native

Sử dụng Node 24 để quá trình cài đặt native diễn ra thuận lợi nhất. Các bản sao mã nguồn sử dụng pnpm có thể cần phê duyệt và xây dựng lại phần phụ thuộc native:

pnpm approve-buildspnpm rebuild node-llama-cpp

Chẩn đoán thời gian chạy

Chạy openclaw memory status --deep sau khi nhà cung cấp đã được tải để kiểm tra phần phụ trợ và bản dựng đã chọn, tên thiết bị, các lớp được chuyển tải sang GPU, kích thước ngữ cảnh được yêu cầu và ảnh chụp nhanh VRAM hoặc bộ nhớ hợp nhất được quan sát gần nhất. Các giá trị VRAM bao gồm dấu thời gian quan sát vì thao tác đọc trạng thái thụ động không tải lại mô hình hoặc thăm dò thiết bị.

Các thông tin được ghi nhận gần nhất này cũng có thể xuất hiện trong openclaw doctor khi Gateway đang chạy đã sử dụng nhà cung cấp cục bộ. Lệnh trạng thái hoặc lệnh doctor thông thường không tải mô hình chỉ để thu thập dữ liệu chẩn đoán.

Khắc phục sự cố

Nếu thiếu node-llama-cpp hoặc không thể tải phần phụ thuộc này, OpenClaw báo lỗi kèm theo hướng dẫn:

1. Cài đặt plugin: openclaw plugins install @openclaw/llama-cpp-provider.
2. Sử dụng Node 24 cho các lượt cài đặt/cập nhật native.
3. Từ bản sao mã nguồn pnpm: chạy pnpm approve-builds, sau đó chạy pnpm rebuild node-llama-cpp.

Để sử dụng embedding cục bộ dễ dàng hơn mà không cần bước xây dựng native, hãy đặt memorySearch.provider thành một nhà cung cấp embedding từ xa như lmstudio, ollama, openai hoặc voyage.