# 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](https://llama.app/) 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ộ:

1. **llama.cpp server** — Cung cấp mô hình dưới dạng API tương thích OpenAI trên `localhost`.
2. **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.

```shell
┌─────────┐     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](https://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ộ](https://huggingface.co/settings/local-apps), 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](https://huggingface.co/models?apps=llama-app&sort=trending). 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 [Llama app](https://llama.app), 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, 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. ![llama app](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/decision/llama-app.png)
- **Linux (hoặc nếu bạn chỉ muốn dùng dòng lệnh)**: lệnh cài đặt một dòng:
     ```bash
     curl -LsSf https://llama.app/install.sh | sh
     ```

Xác minh cài đặt:

```bash
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](http://localhost:9931/#/models).

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](https://llama.app/docs/serve#serving-multiple-models-router-mode) để 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:

```bash
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 all` chuyể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 0` cho 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 ~/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.

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](https://pi.dev) là tác nhân đứng sau [OpenClaw](https://github.com/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:

```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

Bắt đầu Pi trong thư mục dự án của bạn:

```bash
pi
```

Cấu hình llama.cpp:

```bash
/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](https://github.com/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:

```bash
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.

```bash
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](https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF?show_file_info=embeddinggemma-300M-Q8_0.gguf) 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.

```bash
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.

```bash
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.gguf
```

## Hermes Agent

[Hermes Agent](https://hermes-agent.nousresearch.com/) chạy cục bộ với llama.cpp. Trong `~/.hermes/config.yaml`, hãy thêm các nội dung sau.

```yaml
custom_providers:
  - name: llama cpp (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1
```

### Tì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`.

```bash
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: 1
```

Kiể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.

```bash
$ hermes memory status
# Memory status
#────────────────────────────────────────
#  Built-in:  always active
#  Provider:  (none — built-in only)
```

## OpenCode

[OpenCode](https://opencode.ai) chạy cục bộ với llama.cpp. Định nghĩa một `~/.config/opencode/opencode.json`:

```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](https://github.com/gary149/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](https://github.com/ggerganov/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:

```bash
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_M
```

Vì 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ộ](./local-apps) — 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](./gguf-llamacpp) — Cài đặt và sử dụng llama.cpp chi tiết
- [Các tác tử trên Hub](./agents-overview) — Kết nối các tác tử với hệ sinh thái Hugging Face

