Hub documentation
Local Agents với llama.cpp
Local Agents với llama.cpp
Bạn có thể chạy một coding agent cục bộ, hoàn toàn trên phần cứng của riêng mình. Một số agent mã nguồn mở có thể kết nối với một máy chủ llama.cpp cục bộ để mang đến trải nghiệm tương tự như Claude Code hoặc Codex — nhưng mọi thứ đều chạy trên máy của bạn.
Cách hoạt động
Cấu hình này có hai thành phần chạy cục bộ:
- llama.cpp server — Cung cấp mô hình dưới dạng API tương thích OpenAI trên
localhost. - Agent của bạn — Gửi các prompt đến máy chủ cục bộ, suy luận về các tác vụ và thực thi các hành động.
┌─────────┐ API calls ┌───────────────────┐
│ Agent │ ───────────────▶ │ llama.cpp server │
│ │ ◀─────────────── │ (local model) │
└─────────┘ responses └───────────────────┘
│
▼
Your files,
terminal, etc.Cài đặt máy chủ llama.cpp
1. Cài đặt phần cứng cục bộ của bạn
Cấu hình phần cứng cục bộ của bạn để hệ thống hiển thị các mô hình tương thích với thiết lập của bạn.
Truy cập huggingface.co/settings/hardware và cấu hình hồ sơ phần cứng cục bộ của bạn. Sau đó, chọn llama.cpp trong cài đặt Ứng dụng cục bộ, vì đây sẽ là engine bạn sử dụng.
2. Tìm một Mô hình Tương thích
Duyệt các mô hình GGUF tương thích với Llama. Sau khi chọn, hãy tải mô hình xuống phần cứng của bạn.
Nếu bạn cần nguồn cảm hứng, ứng dụng Llama sẽ gợi ý một số mô hình được điều chỉnh phù hợp với thiết bị phần cứng của bạn (xem Bước 3).
3. Cài đặt Llama App
Bạn có thể dễ dàng cài đặt llama.cpp trên máy của mình:
- Mac và Windows: cài đặt ứng dụng Llama, một ứng dụng desktop tối giản nằm trên khay hệ thống
Sau khi cài đặt ứng dụng, hãy làm theo các bước để bắt đầu sử dụng mô hình yêu thích của bạn, được đề xuất cho hệ thống của bạn.

- Linux (or if you only want the command line): lệnh cài đặt một dòng:
curl -LsSf https://llama.app/install.sh | sh
Xác minh cài đặt:
llama --version
4. Khởi động router
Nếu bạn đã cài đặt ứng dụng desktop, llama serve đã đang chạy. Bạn có thể kiểm tra bằng cách truy cập danh sách model trên localhost:9931.
Nếu không, hãy khởi động llama serve. Việc truyền một mô hình sẽ khởi động chế độ đơn mô hình thay vì chế độ router. Xem hướng dẫn máy chủ llama.cpp để biết cách cấu hình router.
Bạn có hai lựa chọn:
- Tải tự động: mặc định, các mô hình được tải theo yêu cầu.
- Tải thủ công: thêm
--no-models-autoload, sau đó dùng/llamađể tải các model trước khi chọn chúng.
Để tải tự động, chỉ cần chạy:
llama serve
Trong hầu hết các trường hợp, bạn không cần thêm bất kỳ cờ nào vì các giá trị mặc định thường đã hợp lý. Đối với việc sử dụng nâng cao, dưới đây là một số cờ có thể bạn quan tâm:
-ngl allchuyển tất cả các lớp sang GPU. Bỏ qua tham số này để sử dụng tính năng tự động chuyển lớp sang GPU.-c 32768đặt kích thước ngữ cảnh theo số token. Sử dụng-c 0cho toàn bộ cửa sổ ngữ cảnh của mô hình, điều này có thể yêu cầu bộ nhớ lớn hơn đáng kể. Ngữ cảnh được chia sẻ giữa các slot máy chủ song song.--models-dir ~/modelsphát hiện các tệp GGUF cục bộ từ một thư mục cục bộ tùy chỉnh.
Mặc dù lệnh ở trên thường là tất cả những gì bạn cần, nhưng dưới đây là một số cờ phổ biến để sử dụng với llama serve:
| Cờ | Nó hoạt động như thế nào |
|---|---|
-ngl all | offloads tất cả các lớp sang GPU |
-c 32768 | đặt kích thước ngữ cảnh theo số token |
--models-dir ~/models | phát hiện các tệp GGUF cục bộ từ một thư mục cục bộ tùy chỉnh |
5. Kết nối Agent của bạn
Chọn một trong các tác nhân bên dưới và làm theo các hướng dẫn cài đặt.
Pi
Pi là tác nhân đứng sau OpenClaw và hiện đã được tích hợp trực tiếp vào Hugging Face, cho phép bạn truy cập hàng nghìn mô hình tương thích.
Cài đặt Pi:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Bắt đầu Pi trong thư mục dự án của bạn:
pi
Cấu hình llama.cpp:
/login llama.cpp
Chạy /llama để tải một mô hình, sau đó chạy /model để chọn mô hình đã tải cho phiên hiện tại.
OpenClaw
OpenClaw chạy cục bộ với llama.cpp. Bạn có thể đặt model của mình thông qua lệnh onboard:
openclaw plugins install @openclaw/llama-cpp-provider openclaw onboard
Tìm kiếm bộ nhớ cục bộ cho OpenClaw
Bạn có thể chạy các mô hình nhúng cục bộ bằng Llama.cpp cho việc tìm kiếm bộ nhớ của agent. Để làm điều này, hãy đảm bảo bạn đã cài đặt node-llama-cpp.
npm i node-llama-cpp
Dưới đây là một đoạn mã mẫu để chạy EmbeddingGemma-300M đã lượng tử hóa cục bộ cho tìm kiếm bộ nhớ. OpenClaw tự động tải xuống và phục vụ mô hình bằng lệnh bên dưới.
openclaw config set agents.defaults.memorySearch.provider local
openclaw config set agents.defaults.memorySearch.local.modelPath "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"Khởi động lại gateway và xác thực.
openclaw gateway restart
openclaw memory status
# Memory Search (main)
# Provider: local (requested: local)
# Model: hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.ggufHermes Agent
Hermes Agent chạy cục bộ với llama.cpp. Trong ~/.hermes/config.yaml, hãy thêm các nội dung sau.
custom_providers:
- name: llama cpp (127.0.0.1:8080)
base_url: http://127.0.0.1:8080/v1Tìm kiếm bộ nhớ cục bộ cho Hermes Agent
Hermes Agent sử dụng các mô hình tìm kiếm ngữ nghĩa thông qua các endpoint. Khi bạn đã triển khai mô hình embedding mong muốn trên endpoint 8080 bằng llama.cpp hoặc bộ máy suy luận bạn chọn, hãy thêm nội dung sau vào ~/.hermes/config.yaml.
auxiliary:
session_search:
base_url: "http://127.0.0.1:8080/v1"
api_key: "no-key-required"
model: "local-llama" # your model alias
timeout: 90
max_concurrency: 1Kiểm tra xem điều này có hoạt động không, none - built-in only cho thấy không có plug-in bộ nhớ nào khác được sử dụng. Đầu ra bên dưới cho thấy việc phục vụ cục bộ đang hoạt động.
$ hermes memory status
# Memory status
#────────────────────────────────────────
# Built-in: always active
# Provider: (none — built-in only)OpenCode
OpenCode chạy cục bộ với llama.cpp. Định nghĩa một ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"llama.cpp": {
"npm": "@ai-sdk/openai-compatible",
"name": "llama-server (local)",
"options": {
"baseURL": "http://127.0.0.1:8080/v1"
},
"models": {
"gemma-4-26b-4b-it": {
"name": "Gemma 4 (local)",
"limit": {
"context": 128000,
"output": 8192
}
}
}
}
}
}Phương án thay thế: llama-agent
llama-agent theo đuổi một cách tiếp cận khác — nó tích hợp vòng lặp agent trực tiếp vào llama.cpp dưới dạng một binary duy nhất với zero external dependencies. Không cần Node.js, không cần Python, chỉ cần compile và chạy:
git clone https://github.com/gary149/llama-agent.git
cd llama-agent
# Build
cmake -B build
cmake --build build --target llama-agent
# Run (downloads the model automatically)
./build/bin/llama-agent -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_MVì các cuộc gọi công cụ diễn ra trong tiến trình thay vì qua HTTP, nên không có chi phí mạng giữa mô hình và tác tử. Nó cũng hỗ trợ các tác tử con, các máy chủ MCP và chế độ máy chủ API HTTP.
Các bước tiếp theo
- Sử dụng Mô hình AI cục bộ — Tìm hiểu thêm về việc chạy mô hình trên máy của bạn
- Hướng dẫn llama.cpp — Cài đặt và sử dụng llama.cpp chi tiết
- Các tác tử trên Hub — Kết nối các tác tử với hệ sinh thái Hugging Face