# llama.cpp를 활용한 로컬 에이전트

코딩 에이전트를 완전히 자체 하드웨어에서 실행할 수 있습니다. 여러 오픈소스 에이전트가 로컬 [llama.cpp](https://github.com/ggerganov/llama.cpp) 서버에 연결하여 Claude Code 또는 Codex와 유사한 경험을 제공하지만, 모든 작업은 사용자의 머신에서 실행됩니다.

## 시작하기

### 1. 로컬 하드웨어 설정

로컬 하드웨어를 설정하여 설정과 호환되는 모델을 표시하도록 하세요.

[huggingface.co/settings/hardware](https://huggingface.co/settings/hardware)로 이동하여 로컬 하드웨어 프로필을 설정하세요. 그런 다음 [Local Apps 설정](https://huggingface.co/settings/local-apps)에서 `llama.cpp`를 선택하세요. 이 엔진을 사용할 것이기 때문입니다.

### 2. 호환 가능한 모델 찾기

[Llama.cpp 호환 모델](https://huggingface.co/models?apps=llama.cpp&sort=trending)을 찾아보세요.

### 3. llama.cpp 서버 실행

모델 페이지에서 **"이 모델 사용"** 버튼을 클릭하고 `llama.cpp`를 선택하세요. 설정에 맞는 정확한 명령어가 표시됩니다. 첫 단계는 llama.cpp 서버를 시작하는 것입니다. 예를 들어

```bash
llama-server -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_M
```

이 명령은 모델을 다운로드하고 로컬 머신에서 OpenAI 호환 API 서버를 시작합니다. 설치 방법은 [llama.cpp 가이드](./gguf-llamacpp)를 참고하세요.

### 4. 에이전트 연결

아래 에이전트 중 하나를 선택하고 설정 지침을 따르세요.

## Pi

[Pi](https://pi.dev)는 [OpenClaw](https://github.com/openclaw)의 에이전트로, 이제 Hugging Face에 직접 통합되어 수천 개의 호환 모델을 사용할 수 있습니다.

Pi 설치:

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

그런 다음 로컬 모델을 `~/.pi/agent/models.json`에 있는 Pi 설정 파일에 추가합니다:

```json
{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "ggml-org-gemma-4-26b-4b-gguf"
        }
      ]
    }
  }
}
```

프로젝트 디렉터리에서 Pi를 시작합니다:

```bash
pi
```

Pi는 로컬 llama.cpp 서버에 연결하여 대화형 에이전트 세션을 제공합니다.

![Demo](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/pi-llama-cpp-demo.gif)

### 비전 지원 활성화

시각 기능이 있는 모델의 경우, `~/.pi/agent/models.json`의 모델 항목에 `"input": ["text", "image"]`를 추가합니다:

```json
"models": [
  {
    "id": "unsloth/Qwen3.6-35B-A3B-GGUF:Q4_K_XL",
    "input": ["text", "image"]
  }
]
```

Pi와 호환되는 [비전-언어 모델](https://huggingface.co/models?pipeline_tag=image-text-to-text&apps=pi)을 탐색합니다.

## OpenClaw

[OpenClaw](https://github.com/openclaw)는 llama.cpp와 함께 로컬에서 작동합니다. 온보드 명령을 통해 모델을 설정할 수 있습니다:

```bash
openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "http://127.0.0.1:8080/v1" \
  --custom-model-id "ggml-org-gemma-4-26b-a4b-gguf" \
  --custom-api-key "llama.cpp" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --accept-risk
```

`openclaw onboard`를 인터랙티브로 실행한 후 `custom-compatibility`를 선택하고 `openai`를 지정하여 동일한 구성을 전달할 수도 있습니다.

### OpenClaw용 로컬 메모리 검색

Llama.cpp를 사용하여 에이전트의 메모리 검색에 로컬 임베딩 모델을 실행할 수 있습니다. 이를 위해 node-llama-cpp가 설치되어 있는지 확인하세요.

```bash
npm i node-llama-cpp 
```

메모리 검색을 위해 [quantized EmbeddingGemma-300M](https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF?show_file_info=embeddinggemma-300M-Q8_0.gguf)을 로컬에서 실행하는 예시 스니펫입니다. OpenClaw는 아래 명령어로 모델을 자동으로 다운로드하고 서빙합니다.

```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"
```

게이트웨이를 다시 시작하고 검증합니다.

```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/)는 llama.cpp와 함께 로컬에서 작동합니다. 기본 설정을 다음과 같이 정의합니다:

```yaml
model:
  provider: custom
  default: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M
  base_url: http://127.0.0.1:8080/v1
  api_key: llama.cpp

custom_providers:
  - name: Local (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1
    api_key: llama.cpp
    model: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M
```

### Hermes Agent를 위한 로컬 메모리 검색

Hermes Agent는 엔드포인트를 통해 시맨틱 검색 모델을 사용합니다. 선호하는 임베딩 모델을 llama.cpp 또는 원하는 추론 엔진으로 8080 엔드포인트에 배포한 후, `~/.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
```

`none - built-in only`가 표시되면 다른 메모리 플러그인이 사용되지 않는다는 의미입니다. 아래 출력은 로컬 서빙이 활성화되어 있음을 보여줍니다.

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

## OpenCode

[OpenCode](https://opencode.ai)는 llama.cpp와 함께 로컬에서 작동합니다. `~/.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
          }
        }
      }
    }
  }
}
```

## 작동 방식

설정은 로컬에서 실행되는 두 가지 구성 요소로 이루어져 있습니다:

1. **llama.cpp 서버** — `localhost`에서 모델을 OpenAI 호환 API로 제공합니다.
2. **에이전트** — 로컬 서버에 프롬프트를 전송하고, 작업을 추론하며, 작업을 실행하는 에이전트 프로세스입니다.

```
┌─────────┐     API calls     ┌──────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └──────────────────┘
     │
     ▼
  Your files,
  terminal, etc.
```

## 대안: llama-agent

[llama-agent](https://github.com/gary149/llama-agent)은 다른 접근 방식을 취합니다. [llama.cpp](https://github.com/ggerganov/llama.cpp)에 에이전트 루프를 직접 내장하여 외부 의존성이 전혀 없는 단일 바이너리로 구성합니다. Node.js도, Python도 필요하지 않으며 컴파일 후 바로 실행할 수 있습니다:

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

도구 호출은 HTTP가 아닌 프로세스 내에서 수행되므로 모델과 에이전트 사이에 네트워크 오버헤드가 없습니다. 또한 서브 에이전트, MCP 서버, HTTP API 서버 모드를 지원합니다.

## 다음 단계

- [로컬에서 AI 모델 사용](./local-apps) — 내 컴퓨터에서 모델을 실행하는 방법에 대해 자세히 알아보세요
- [llama.cpp 가이드](./gguf-llamacpp) — llama.cpp 설치 및 사용법 상세 설명
- [Hub의 에이전트](./agents-overview) — 에이전트를 Hugging Face 생태계에 연결