Hub documentation
llama.cpp를 활용한 로컬 에이전트
llama.cpp를 활용한 로컬 에이전트
코딩 에이전트를 로컬에서, 전적으로 자체 하드웨어만으로 실행할 수 있습니다. 여러 오픈소스 에이전트가 로컬 llama.cpp 서버에 연결하여 Claude Code나 Codex와 유사한 경험을 제공하지만, 모든 작업은 사용자의 머신에서 수행됩니다.
작동 방식
설정은 로컬에서 실행되는 두 가지 구성 요소로 이루어져 있습니다:
- llama.cpp 서버 —
localhost에서 모델을 OpenAI 호환 API로 제공합니다. - 에이전트 — 로컬 서버에 프롬프트를 전송하고, 작업을 추론하며, 작업을 실행합니다.
┌─────────┐ API calls ┌───────────────────┐
│ Agent │ ───────────────▶ │ llama.cpp server │
│ │ ◀─────────────── │ (local model) │
└─────────┘ responses └───────────────────┘
│
▼
Your files,
terminal, etc.llama.cpp 서버 설정
1. 로컬 하드웨어 설정
로컬 하드웨어를 설정하여 설정과 호환되는 모델을 표시하도록 하세요.
huggingface.co/settings/hardware로 이동하여 로컬 하드웨어 프로필을 설정하세요. 그런 다음 Local Apps 설정에서 llama.cpp를 선택하세요. 이 엔진을 사용할 것이기 때문입니다.
2. 호환 가능한 모델 찾기
Llama와 호환되는 GGUF 모델을 찾아보세요. 선택 후 해당 모델을 하드웨어에 다운로드하세요.
영감이 필요하시다면, Llama 앱은 하드웨어 장치에 맞게 조정된 몇 가지 모델을 제안합니다(3단계 참조).
3. Llama 앱 설치
llama.cpp를 머신에 쉽게 설치할 수 있습니다:
- Mac 및 Windows: 시스템 트레이에 상주하는 미니멀한 데스크톱 앱인 Llama 앱을 설치합니다.
앱 설치 후, 시스템에 권장되는 선호 모델을 사용하도록 안내된 단계를 따르세요.

- Linux (or if you only want the command line): 한 줄 설치 명령어:
curl -LsSf https://llama.app/install.sh | sh
설정을 확인합니다:
llama --version
4. 라우터 시작
데스크톱 앱을 설치했다면 llama serve가 이미 실행 중입니다. localhost:9931에서 모델 목록을 확인하여 이를 검증할 수 있습니다.
아니면 llama serve를 시작합니다. 모델을 전달하면 라우터 모드 대신 단일 모델 모드가 시작됩니다. 라우터 구성에 대한 내용은 llama.cpp 서버 가이드를 참조하세요.
두 가지 옵션이 있습니다:
- 자동 로딩: 기본적으로 모델은 필요할 때 로드됩니다.
- 수동 로딩:
--no-models-autoload를 추가한 후, 모델을 선택하기 전에/llama를 사용하여 모델을 로드합니다.
자동 로딩을 사용하려면 다음을 실행하세요:
llama serve
대부분의 경우 기본값이 적절하므로 추가 플래그가 필요하지 않습니다. 고급 사용법에 관심이 있으시다면, 아래에 몇 가지 유용한 플래그 예시를 소개합니다:
-ngl all은 모든 레이어를 GPU로 오프로드합니다. 자동 GPU 오프로드를 사용하려면 생략하세요.-c 32768은 토큰 단위의 컨텍스트 크기를 설정합니다. 모델의 전체 컨텍스트 윈도우를 사용하려면-c 0을 사용하세요. 이 경우 훨씬 더 많은 메모리가 필요할 수 있습니다. 컨텍스트는 병렬 서버 슬롯 간에 공유됩니다.--models-dir ~/models는 사용자 지정 로컬 디렉터리에서 로컬 GGUF 파일을 검색합니다.
위 명령만으로도 충분하지만, llama serve와 함께 사용할 수 있는 일반적인 플래그는 다음과 같습니다:
| 플래그 | 기능 |
|---|---|
-ngl all | 모든 레이어를 GPU로 offload합니다 |
-c 32768 | 토큰 단위의 컨텍스트 크기를 설정합니다 |
--models-dir ~/models | discovers local GGUF files from a custom local directory |
5. 에이전트 연결
아래 에이전트 중 하나를 선택하고 설정 지침을 따르세요.
Pi
Pi는 OpenClaw의 에이전트로, 이제 Hugging Face에 직접 통합되어 수천 개의 호환 모델을 사용할 수 있습니다.
Pi 설치:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
프로젝트 디렉터리에서 Pi를 시작합니다:
pi
llama.cpp 구성:
/login llama.cpp
/llama를 실행하여 모델을 로드한 다음, /model을 실행하여 현재 세션에 로드된 모델을 선택합니다.
OpenClaw
OpenClaw는 llama.cpp와 함께 로컬에서 작동합니다. 온보드 명령을 통해 모델을 설정할 수 있습니다:
openclaw plugins install @openclaw/llama-cpp-provider openclaw onboard
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.ggufHermes Agent
Hermes Agent는 llama.cpp와 함께 로컬에서 작동합니다. ~/.hermes/config.yaml에 다음을 추가하세요.
custom_providers:
- name: llama cpp (127.0.0.1:8080)
base_url: http://127.0.0.1:8080/v1Hermes 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: 1none - 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-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 생태계에 연결