llama.cpp로 로컬 에이전트 실행하기

llama.cpp로 로컬 에이전트 실행하기 (Local Agents with llama.cpp)

코딩 에이전트를 전적으로 내 하드웨어에서 실행할 수 있어요. 여러 오픈소스 에이전트가 로컬 llama.cpp 서버에 연결해 Claude Code나 Codex와 비슷한 경험을 제공합니다 — 모든 것이 내 머신에서 실행되죠.

출처: 문서

본문

코딩 에이전트를 전적으로 내 하드웨어에서 실행할 수 있어요. 여러 오픈소스 에이전트가 로컬 llama.cpp 서버에 연결해 Claude Code나 Codex와 비슷한 경험을 주지만, 모든 것이 내 머신에서 실행됩니다.

시작하기 (Getting Started)

1. 내 로컬 하드웨어 설정 (Set Your Local Hardware)

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

huggingface.co/settings/hardware로 가서 로컬 하드웨어 프로필을 구성하세요. 그런 다음 Local Apps 설정에서 llama.cpp를 선택합니다. 이것이 사용할 엔진이 될 거예요.

2. 호환 모델 찾기 (Find a Compatible Model)

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

3. llama.cpp 서버 실행 (Launch the llama.cpp Server)

모델 페이지에서 "Use this model" 버튼을 클릭하고 llama.cpp를 선택하세요. 내 설정에 맞는 정확한 명령어를 보여줄 거예요. 첫 단계는 llama.cpp 서버를 시작하는 것입니다. 예:

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

이것은 모델을 다운로드하고 내 머신에서 OpenAI 호환 API 서버를 시작합니다. 설치 지침은 llama.cpp 가이드를 참고하세요.

4. 에이전트 연결 (Connect Your Agent)

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

Pi

Pi는 OpenClaw 뒤의 에이전트이며, 이제 Hugging Face에 직접 통합되어 수천 개의 호환 모델에 접근할 수 있어요.

Pi 설치:

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

그런 다음 Pi의 설정 파일 ~/.pi/agent/models.json에 내 로컬 모델을 추가하세요:

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

비전 지원 활성화 (Enabling vision support)

비전 지원 모델의 경우 ~/.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 로컬 메모리 검색 (Local Memory Search for OpenClaw)

에이전트의 메모리 검색에 Llama.cpp로 로컬 임베딩 모델을 실행할 수 있어요. 그러려면 node-llama-cpp가 있어야 합니다.

npm i node-llama-cpp

다음은 메모리 검색용으로 양자화된 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 로컬 메모리 검색 (Local Memory Search for 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
          }
        }
      }
    }
  }
}

동작 방식 (How It Works)

이 설정은 로컬에서 실행되는 두 가지 컴포넌트로 구성됩니다:

llama.cpp 서버 — 모델을 localhost에서 OpenAI 호환 API로 서빙합니다.
내 에이전트 — 로컬 서버에 프롬프트를 보내고, 태스크에 대해 추론하며, 작업을 실행하는 에이전트 프로세스.

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

대안: llama-agent (Alternative: 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 서버 모드를 지원해요.

다음 단계 (Next Steps)

AI 모델을 로컬에서 사용하기 — 내 머신에서 모델을 실행하는 방법 더 알아보기
llama.cpp 가이드 — 상세한 llama.cpp 설치와 사용법
Hub의 에이전트 — 에이전트를 Hugging Face 생태계에 연결

더 알아보기 (Learn more)

로컬 코딩 에이전트는 llama.cpp 서버(llama-server -hf ...:Q4_K_M)로 OpenAI 호환 API를 띄우고, Pi·OpenClaw·Hermes Agent·OpenCode 같은 에이전트를 baseUrl: http://127.0.0.1:8080/v1에 연결해 실행해요. 각 에이전트의 설정 파일(models.json, opencode.json, config.yaml 등)에 로컬 모델을 지정하면 됩니다. 메모리 검색용 로컬 임베딩 모델과 yaml 설정도 지원합니다.