ผู้ให้บริการ llama.cpp

llama-cpp คือ Plugin ผู้ให้บริการภายนอกอย่างเป็นทางการสำหรับการอนุมานข้อความจาก GGUF ภายในโปรเซสบนเครื่องและการฝังเวกเตอร์ โดยลงทะเบียนผู้ให้บริการข้อความ llama-cpp ผู้ให้บริการการฝังเวกเตอร์ local และเป็นเจ้าของรันไทม์เนทีฟ node-llama-cpp

ติดตั้งก่อนใช้การอนุมานบนเครื่องหรือการฝังเวกเตอร์หน่วยความจำบนเครื่อง:

openclaw plugins install @openclaw/llama-cpp-provider

แพ็กเกจ npm หลัก openclaw ไม่มี node-llama-cpp การเก็บ การขึ้นต่อกันแบบเนทีฟไว้ใน Plugin นี้ช่วยป้องกันไม่ให้การอัปเดต npm ตามปกติของ OpenClaw ลบรันไทม์ที่ติดตั้งด้วยตนเองภายในไดเรกทอรีแพ็กเกจ OpenClaw

การอนุมานข้อความบนเครื่อง

เลือก โมเดลบนเครื่อง (llama.cpp) ระหว่างการเริ่มต้นใช้งานแบบโต้ตอบ OpenClaw จะถาม ก่อนดาวน์โหลดโมเดลเริ่มต้น:

hf:bartowski/Qwen_Qwen3-4B-Instruct-2507-GGUF/Qwen_Qwen3-4B-Instruct-2507-Q4_K_M.gguf

ไฟล์ Qwen3 4B Instruct 2507 Q4_K_M มีขนาดประมาณ 2.5 GB ควรเผื่อ RAM ราว 3 GB สำหรับน้ำหนักโมเดล รวมถึงบริบทและค่าใช้จ่ายส่วนเกินของรันไทม์ OpenClaw บริบท เริ่มต้นจะได้รับการกำหนดขนาดโดยอัตโนมัติ โดยมีขีดจำกัด 8,192 โทเค็นเพื่อให้ยังใช้งานได้จริง บนเครื่องที่มีหน่วยความจำ 8 GB กำหนดบริบทที่ใหญ่ขึ้นเฉพาะเมื่อเครื่องมี หน่วยความจำเพียงพอ

การตรวจสอบเพื่อค้นหาระหว่างการเริ่มต้นใช้งานเป็นแบบอ่านอย่างเดียว ระบบจะเสนอ llama.cpp โดยอัตโนมัติ เฉพาะเมื่อไฟล์ GGUF เริ่มต้นหรือไฟล์ที่กำหนดค่าไว้อยู่ในแคชโมเดลแล้ว และ จะไม่ดาวน์โหลดระหว่างการค้นหา Ollama และ LM Studio ยังคงเป็นตัวเลือกบริการบนเครื่อง ที่แยกจากกันและใช้ขั้นตอนการค้นหาของตนเอง การเลือก llama.cpp ด้วยตนเองคือเส้นทางที่จะถามให้ดาวน์โหลดโมเดลเริ่มต้น

ผู้ให้บริการใช้เทมเพลตแชตที่ฝังอยู่ในโมเดล GGUF และการเรียกใช้ฟังก์ชัน แบบเนทีฟของ node-llama-cpp ข้อความจะสตรีมทีละโทเค็น การเรียกใช้เครื่องมือจะส่งกลับ ไปยัง OpenClaw เพื่อดำเนินการ แทนที่จะทำงานภายใน node-llama-cpp

ใช้โมเดล GGUF อื่น

เพิ่มโมเดลลงใน models.providers.llama-cpp ใส่พาธบนเครื่องหรือ URI ไฟล์ hf: แบบเต็ม ไว้ใน params.modelPath:

{  models: {    mode: "merge",    providers: {      "llama-cpp": {        baseUrl: "local://llama-cpp",        api: "openai-completions",        params: {          modelCacheDir: "~/.node-llama-cpp/models",        },        models: [          {            id: "my-local-model",            name: "My local GGUF",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 8192,            maxTokens: 2048,            params: {              modelPath: "~/Models/my-model.Q4_K_M.gguf",              contextSize: 8192,            },            compat: { supportsTools: true },          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "llama-cpp/my-local-model" },    },  },}

การอนุมานจะไม่ดาวน์โหลดโมเดลที่หายไปโดยปริยาย สำหรับ URI hf: แบบกำหนดเอง ให้ดาวน์โหลด GGUF ลงใน modelCacheDir ก่อน การค้นหาใช้ตัวแก้ไขแคช แบบอ่านอย่างเดียวของ node-llama-cpp เอง รวมถึงรูปแบบการตั้งชื่อที่เก็บ สาขา และไฟล์แบบแบ่งส่วน

การกำหนดค่าการฝังเวกเตอร์หน่วยความจำ

ตั้งค่า memorySearch.provider เป็น 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 มีค่าเริ่มต้นเป็น URI hf: ที่แสดงข้างต้น (embeddinggemma-300m-qat-Q8_0.gguf) ชี้ไปยัง URI hf: อื่นหรือไฟล์ .gguf บนเครื่องเพื่อใช้โมเดลอื่น local.modelCacheDir ใช้แทนที่ตำแหน่งแคชของโมเดลที่ดาวน์โหลด (ค่าเริ่มต้น: ~/.node-llama-cpp/models) และ local.contextSize รับค่าเป็น จำนวนเต็มหรือ "auto"

เมื่อ local.contextSize เป็นตัวเลข ผู้ให้บริการจะส่งข้อกำหนดนั้น ให้กับการจัดวางเลเยอร์ GPU อัตโนมัติของ node-llama-cpp ด้วย ซึ่งช่วยให้ node-llama-cpp จัดวาง โมเดลและบริบทการฝังเวกเตอร์ร่วมกันได้โดยยังคงการตรวจสอบ ความปลอดภัยของหน่วยความจำไว้ เมื่อใช้ "auto" node-llama-cpp จะคงการจัดวางอัตโนมัติตามปกติ

รันไทม์เนทีฟ

ใช้ Node 24 เพื่อให้เส้นทางการติดตั้งแบบเนทีฟราบรื่นที่สุด การเช็กเอาต์ซอร์สที่ใช้ pnpm อาจต้องอนุมัติและสร้างการขึ้นต่อกันแบบเนทีฟใหม่:

pnpm approve-buildspnpm rebuild node-llama-cpp

การวินิจฉัยรันไทม์หน่วยความจำ

เรียกใช้ openclaw memory status --deep หลังจากผู้ให้บริการโหลดแล้วเพื่อตรวจสอบ แบ็กเอนด์และบิลด์ที่เลือก ชื่ออุปกรณ์ เลเยอร์ที่ถ่ายโอนไปยัง GPU ขนาดบริบท ที่ร้องขอ และสแนปช็อต VRAM หรือหน่วยความจำรวมที่สังเกตพบล่าสุด ค่า VRAM มีการประทับเวลาการสังเกต เนื่องจากการอ่านสถานะแบบพาสซีฟจะไม่ โหลดโมเดลใหม่หรือสำรวจอุปกรณ์

ข้อเท็จจริงที่ทราบล่าสุดเดียวกันอาจปรากฏใน openclaw doctor เมื่อ Gateway ที่กำลังทำงานเคยใช้ผู้ให้บริการบนเครื่องแล้ว คำสั่งสถานะหรือ doctor ตามปกติ จะไม่โหลดโมเดลเพียงเพื่อรวบรวมข้อมูลวินิจฉัย

การแก้ไขปัญหา

หาก node-llama-cpp หายไปหรือโหลดไม่สำเร็จ OpenClaw จะรายงานความล้มเหลว พร้อมข้อความต่อไปนี้:

1. ติดตั้ง Plugin: openclaw plugins install @openclaw/llama-cpp-provider
2. ใช้ Node 24 สำหรับการติดตั้ง/อัปเดตแบบเนทีฟ
3. จากการเช็กเอาต์ซอร์สด้วย pnpm: pnpm approve-builds แล้วตามด้วย pnpm rebuild node-llama-cpp

หากต้องการการอนุมานบนเครื่องโดยไม่ใช้การขึ้นต่อกันแบบเนทีฟภายในโปรเซส ให้ใช้ผู้ให้บริการ Ollama หรือ LM Studio แทน หากต้องการการฝังเวกเตอร์บนเครื่องที่ตั้งค่าได้ง่ายกว่า ให้ตั้งค่า memorySearch.provider เป็นผู้ให้บริการการฝังเวกเตอร์ระยะไกล เช่น lmstudio, ollama, openai หรือ voyage แทน