OpenClaw에 Ollama 로컬 LLM 연동하기

이 글에서 다루는 내용

OpenClaw는 모델 추론 백엔드를 고를 수 있도록 설계돼 있습니다. 기본 설정은 클라우드 LLM API지만, Ollama를 붙이면 같은 머신 안에서 모든 추론을 마치고 대화 기록까지 외부로 나가지 않게 만들 수 있습니다. 이 글은 OpenClaw를 Ollama 기반으로 돌리기 위해 반드시 거쳐야 하는 네 단계 — 모델 선택, 엔드포인트 설정, 도구 호출 검증, 성능 튜닝 — 을 순서대로 정리합니다. 개인정보가 걸린 메시지나 사내망 데이터까지 로컬에서 처리하고 싶은 경우 가장 쓸모 있는 구성입니다.

---

1. 사전 준비 상태 확인

1-1. 필요 구성 요소

본 글은 아래 환경이 이미 갖춰져 있다는 전제에서 출발합니다. 빠진 항목이 있다면 연결된 이전 글을 먼저 확인하고 돌아옵니다.

항목	조건	참고 글
OpenClaw	설치 완료 + 메신저 최소 1개 연결	OpenClaw란 무엇인가
Ollama	설치 완료 + 11434 포트 대기	Ollama 설치 가이드
GPU 가속 (선택)	WSL 사용자는 CUDA 설정 권장	WSL + CUDA + Ollama

1-2. Ollama API 연결 확인

OpenClaw는 Ollama의 REST API로 통신합니다. 먼저 호스트에서 API가 응답하는지 확인합니다.

curl http://localhost:11434/api/tags

예상 출력 보기

{"models":[{"name":"llama3.1:8b","size":4661224676,"modified_at":"..."}]}

응답이 오지 않으면 Ollama 서비스가 내려가 있거나, 외부 바인딩이 필요한 상황입니다. OpenClaw가 다른 컨테이너나 VM에서 도는 구성이라면 OLLAMA_HOST=0.0.0.0:11434로 바인딩을 바꿔야 합니다.

---

2. 에이전트에 적합한 모델 고르기

2-1. 도구 호출 지원이 핵심

OpenClaw는 단순 질의응답이 아니라 이메일 검색, 파일 조작, 브라우저 자동화 같은 도구 호출을 쏟아냅니다. 따라서 연결할 모델은 JSON 포맷의 tool-calling 또는 function-calling을 안정적으로 출력할 수 있어야 합니다. 일반 대화 모델을 그대로 붙이면 응답이 자연어 설명으로만 나와 에이전트가 아무 작업도 실행하지 못합니다.

2-2. 2026년 기준 추천 모델

모델	권장 VRAM	도구 호출	한국어
llama3.1:8b	8GB	안정	보통
qwen2.5:7b	8GB	안정	좋음
mistral-small:22b	16GB	매우 안정	보통
llama3.2:3b	4GB	제한적	보통

💡 처음 연동할 때는 qwen2.5:7b를 권장합니다. 한국어 응답 품질이 비슷한 크기 모델 중 가장 균형이 좋고, tool-calling이 공식 지원됩니다.

2-3. 모델 다운로드

고른 모델을 미리 당겨둡니다. 연동 중에 최초 다운로드가 끼면 타임아웃이 납니다.

ollama pull qwen2.5:7b
ollama list

예상 출력 보기

NAME            ID              SIZE      MODIFIED
qwen2.5:7b      abcd1234        4.7 GB    2 minutes ago

---

3. OpenClaw 프로바이더 설정

3-1. 설정 파일 위치

OpenClaw는 기본 설정 파일을 ~/.openclaw/config.yaml에 둡니다. 이 파일에 LLM 프로바이더 항목을 추가해 추론 백엔드를 교체합니다.

mkdir -p ~/.openclaw
nano ~/.openclaw/config.yaml

3-2. Ollama 프로바이더 등록

Ollama는 OpenAI 호환 엔드포인트를 /v1 경로로 노출합니다. OpenClaw의 openai_compatible 프로바이더 타입을 쓰면 별도 어댑터 없이 바로 연결됩니다.

llm:
  provider: openai_compatible
  base_url: http://localhost:11434/v1
  api_key: ollama     # Ollama는 실제 검증하지 않지만 문자열이 필요
  model: qwen2.5:7b
  temperature: 0.3
  request_timeout: 120

ℹ️ api_key는 실제 인증에 쓰이지 않지만 비워두면 SDK 단계에서 유효성 검사에 걸리므로 임의 문자열을 넣습니다.

3-3. 에이전트 재시작

설정을 반영하려면 OpenClaw 데몬을 재시작합니다.

openclaw stop
openclaw start
openclaw status

예상 출력 보기

OpenClaw agent: running
LLM provider : openai_compatible (qwen2.5:7b @ http://localhost:11434/v1)
Memory store : ~/.openclaw/memory.db
Connectors   : telegram, slack

상태 출력에서 provider 줄이 Ollama 주소로 나오면 연결 준비가 끝난 것입니다.

---

4. 첫 대화와 도구 호출 검증

4-1. 간단 질문으로 스모크 테스트

메신저에서 OpenClaw 봇에게 평이한 질문을 하나 던져봅니다.

사용자  ▸ 지금 시간 알려줘.
OpenClaw▸ 현재 시각은 15:42입니다.

이 대화가 정상적으로 성립한다면 LLM 연결 자체는 문제 없습니다. 응답이 전혀 없거나 타임아웃이 난다면 3-2절의 base_url과 3-3절의 status 출력을 다시 확인합니다.

4-2. 도구 호출이 제대로 잡히는지 확인

OpenClaw에서는 도구가 호출됐는지가 더 중요합니다. 파일 검색 같이 도구를 쓰는 요청을 보내 로그를 확인합니다.

사용자  ▸ 다운로드 폴더에서 오늘 받은 파일 목록 보여줘.

openclaw logs --tail 50

예상 출력 보기

[agent] planning tools for intent=file_listing
[agent] tool_call filesystem.list args={"path":"~/Downloads","filter":"today"}
[tool]  filesystem.list returned 4 entries
[llm]   completion tokens=182 latency=1.9s

로그에 tool_call이 보이면 모델이 JSON 포맷으로 도구 호출을 제대로 뽑아낸 것입니다. parse error나 no tool_call이 반복되면 2-2절 모델 표에서 도구 호출 안정성이 더 높은 모델로 바꿉니다.

4-3. GPU 사용량 모니터링

별도 셸에서 GPU 점유가 실제로 올라가는지 확인합니다.

watch -n 0.5 nvidia-smi
ollama ps

응답 중 GPU-Util이 튀고 ollama ps의 PROCESSOR 칼럼이 100% GPU로 나온다면 로컬 GPU 가속으로 OpenClaw가 돌고 있는 것입니다.

---

5. 성능과 안정성 튜닝

5-1. 컨텍스트 길이 확장

OpenClaw는 에이전트 루프마다 시스템 프롬프트·도구 스키마·대화 기록을 모두 모델에 밀어 넣습니다. 기본 2048 토큰으로는 도구가 2~3개만 붙어도 금방 잘려서 계획이 꼬입니다. Ollama 모델 파일을 커스터마이즈해 컨텍스트를 늘립니다.

cat > Modelfile <<'EOF'
FROM qwen2.5:7b
PARAMETER num_ctx 8192
EOF
ollama create qwen2.5-openclaw -f Modelfile

새 모델 이름을 config.yaml의 model에 반영하고 OpenClaw를 재시작합니다.

5-2. KEEP_ALIVE로 모델 상주 유지

기본값으로는 Ollama가 유휴 상태 5분 뒤 VRAM에서 모델을 내립니다. 그 직후 메시지가 오면 재로딩으로 수 초가 지연됩니다. 에이전트처럼 자주 짧게 호출되는 구성에서는 상주 시간을 늘리는 편이 유리합니다.

export OLLAMA_KEEP_ALIVE=30m
sudo systemctl restart ollama

systemd 환경이라면 systemctl edit ollama로 Environment="OLLAMA_KEEP_ALIVE=30m"을 영구 등록하는 편이 깔끔합니다.

5-3. 병렬 요청 수 조정

메신저 여러 개를 동시에 붙여 쓰면 요청이 겹칩니다. 병렬 요청 수를 늘리면 응답 지연이 줄어듭니다.

export OLLAMA_NUM_PARALLEL=2

⚠️ 병렬 수를 늘리면 VRAM 소비도 거의 비례해 늘어납니다. 7B 모델 기준 8GB VRAM이면 2 이상은 무리입니다.

---

트러블슈팅

문제 1: Connection refused / 401 Unauthorized

OpenClaw 로그에 연결 거부가 뜨면 대부분 base_url 경로 끝에 /v1이 빠졌거나 포트가 틀린 경우입니다. 401이 뜨면 api_key 값이 아예 비어 있는 경우가 많습니다. 임의 문자열이라도 채워둡니다.

문제 2: 도구 호출이 파싱되지 않음

로그에 tool_call parse error가 반복된다면 모델이 JSON 대신 자연어로 도구 호출을 설명하고 있는 상태입니다. 해결 순서는 다음과 같습니다.

• 도구 호출이 안정적인 모델로 교체 (qwen2.5:7b 또는 mistral-small:22b)
• temperature를 0.1~0.3으로 낮춰 출력 변동성 축소
• 컨텍스트 길이 확장 (5-1절 참고)

문제 3: 응답이 눈에 띄게 느림

원인은 대부분 VRAM 부족으로 인한 부분 오프로딩입니다. ollama ps의 PROCESSOR가 60% GPU / 40% CPU처럼 쪼개져 있다면 더 작은 양자화(q4_K_M)나 더 작은 모델로 전환합니다. 그래도 느리면 컨텍스트 길이를 줄이는 것도 체감 효과가 큽니다.

문제 4: 한국어 답변 품질이 떨어짐

Llama 계열 기본 모델은 영어 비중이 높은 편이라, 한국어 어조나 존댓말 정확도가 낮을 수 있습니다. 이 경우 Qwen 계열이 가장 현실적인 대안입니다. 더 고급 튜닝이 필요하다면 system 프롬프트에 "항상 한국어로 존댓말로 답합니다"를 명시적으로 넣어두면 눈에 띄게 개선됩니다.

---

마무리

OpenClaw의 추론 백엔드를 Ollama로 바꾸는 작업 자체는 config.yaml 다섯 줄로 끝나지만, 실제 운영에서 체감 품질을 결정하는 건 "도구 호출 안정성"과 "컨텍스트 길이"입니다. 한 번 qwen2.5:7b 정도로 세팅을 잡아두면 메신저 프롬프트의 맥락이 외부로 흘러 나가지 않고도 파일·이메일·일정 같은 실제 작업을 에이전트에 맡길 수 있습니다.

 

• 공식 문서: Ollama OpenAI 호환 API 문서
• 공식 저장소: OpenClaw GitHub
• 관련 글: OpenClaw란 무엇인가? 내 기기에서 돌아가는 오픈소스 AI 비서
• 관련 글: WSL2에 Ollama와 CUDA 설치해서 로컬 LLM GPU 가속 돌리기