Hub documentation

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

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

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

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

시작하기

1. 로컬 하드웨어 설정

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

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

2. 호환 가능한 모델 찾기

Llama.cpp 호환 모델을 찾아보세요.

3. llama.cpp 서버 실행

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

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

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

4. 에이전트 연결

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

Pi

Pi는 OpenClaw의 에이전트로, 이제 Hugging Face에 직접 통합되어 수천 개의 호환 모델을 사용할 수 있습니다.

Pi 설치:

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

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

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

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

pi

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

Demo

비전 지원 활성화

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

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

Pi와 호환되는 비전-언어 모델을 탐색합니다.

OpenClaw

OpenClaw는 llama.cpp와 함께 로컬에서 작동합니다. 온보드 명령을 통해 모델을 설정할 수 있습니다:

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가 설치되어 있는지 확인하세요.

npm i node-llama-cpp

메모리 검색을 위해 quantized EmbeddingGemma-300M을 로컬에서 실행하는 예시 스니펫입니다. OpenClaw는 아래 명령어로 모델을 자동으로 다운로드하고 서빙합니다.

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"

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

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

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에 다음을 추가하세요.

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가 표시되면 다른 메모리 플러그인이 사용되지 않는다는 의미입니다. 아래 출력은 로컬 서빙이 활성화되어 있음을 보여줍니다.

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

OpenCode

OpenCode는 llama.cpp와 함께 로컬에서 작동합니다. ~/.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
          }
        }
      }
    }
  }
}

작동 방식

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

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

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

대안: llama-agent

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

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 모델 사용 — 내 컴퓨터에서 모델을 실행하는 방법에 대해 자세히 알아보세요
llama.cpp 가이드 — llama.cpp 설치 및 사용법 상세 설명
Hub의 에이전트 — 에이전트를 Hugging Face 생태계에 연결

Update on GitHub

←HF SDK를 사용하여 에이전트 구축하기 에이전트 라이브러리→