OpenClaw 빠른 시작: Docker 를 활용한 설치 (Ollama GPU 또는 Claude + CPU)

Ollama 를 사용하여 로컬에서 OpenClaw 설치하기

Page content

OpenClaw 는 Ollama 와 같은 로컬 LLM 런타임 또는 Claude Sonnet 과 같은 클라우드 기반 모델과 함께 실행되도록 설계된 자체 호스팅 AI 어시스턴트입니다.

이 시작 가이드에서는 Docker 를 사용하여 OpenClaw 를 배포하고, GPU 를 사용하는 로컬 모델 또는 CPU 전용 클라우드 모델을 설정하며, AI 어시스턴트가 전체적으로 정상 작동하는지 확인하는 방법을 보여줍니다.

이 가이드를 통해 OpenClaw 의 최소 구성을 수행하여 사용자가 자신의 기기에서 실행되고 응답하는 것을 확인할 수 있습니다.

목표는 간단합니다:

  • OpenClaw 실행
  • 요청 전송
  • 작동 확인

이것은 프로덕션 환경 강화 가이드가 아닙니다.
이것은 성능 튜닝 가이드가 아닙니다.
이것은 실용적인 시작점입니다.

두 가지 옵션이 있습니다:

  • A 경로 — 로컬 GPU: Ollama 사용 (GPU 가 있는 경우 권장)
  • B 경로 — CPU 전용: Anthropic API 를 통한 Claude Sonnet 4.6 사용

두 경로 모두 핵심 설치 과정은 동일합니다.

install openclaw steps GPU vs CPU

OpenClaw 가 처음이거나 시스템 구조에 대한 더 깊은 개요가 필요하시면 OpenClaw 시스템 개요 를 읽어보시기 바랍니다.

시스템 요구 사항 및 환경 설정

OpenClaw 는 외부 서비스에 연결할 수 있는 어시스턴트 스타일의 시스템입니다. 이 빠른 시작을 위해:

  • 가능한 경우 테스트 계정을 사용하세요.
  • 민감한 프로덕션 시스템 연결은 피하세요.
  • Docker 내부에서 실행하세요 (권장).

에이전트 스타일 소프트웨어를 실험할 때 격리는 좋은 기본 설정입니다.

OpenClaw 사전 요구 사항 (Ollama 사용 시 GPU 또는 Claude 사용 시 CPU)

두 경로 모두에 필요한 사항

  • Git
  • Docker Desktop (또는 Docker + Docker Compose)
  • 터미널

A 경로용 (로컬 GPU)

  • 호환 가능한 GPU (NVIDIA 또는 AMD 권장) 가 장착된 머신
  • 설치된 Ollama

B 경로용 (CPU + 클라우드 모델)

  • Anthropic API 키
  • Claude Sonnet 4.6 접근 권한

단계 1 — Docker 로 OpenClaw 설치 (복제 및 시작)

OpenClaw 는 Docker Compose 를 사용하여 시작할 수 있습니다. 이렇게 하면 설정이 격리되고 재현 가능하게 유지됩니다.

저장소 복제

git clone https://github.com/openclaw/openclaw.git
cd openclaw

환경 설정 파일 복사

cp .env.example .env

편집기에서 .env 파일을 엽니다. 선택한 모델 경로에 따라 다음 단계에서 이를 구성합니다.

컨테이너 시작

docker compose up -d

모든 것이 올바르게 시작되면 실행 중인 컨테이너를 확인해야 합니다:

docker ps

이 시점에서 OpenClaw 는 실행 중이지만 아직 모델에 연결되지 않았습니다.

단계 2 — LLM 제공자 설정 (Ollama GPU 또는 Claude CPU)

이제 추론 (Inference) 이 어떻게 작동할지 결정합니다.

A 경로 — Ollama 를 사용한 로컬 GPU

GPU 가 있는 경우 이것이 가장 단순하고 자체적으로 완결된 옵션입니다.

Ollama 설치 또는 확인

더 자세한 설치 가이드가 필요하거나 모델 저장 위치를 구성하려면 다음을 참조하세요:

Ollama 가 설치되지 않은 경우:

curl -fsSL https://ollama.com/install.sh | sh

작동 여부를 확인합니다:

ollama pull llama3
ollama run llama3

모델이 응답하면 추론이 작동 중입니다.

OpenClaw 에서 Ollama 사용 설정

.env 파일에서 다음을 설정합니다:

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434
OLLAMA_MODEL=llama3

컨테이너를 재시작합니다:

docker compose restart

이제 OpenClaw 가 로컬 Ollama 인스턴스로 요청을 라우팅합니다.

16GB GPU 에서 실행할 모델을 선택하거나 벤치마크 비교가 필요하시면 다음을 참조하세요:

부하 하의 동시성 및 CPU 동작을 이해하려면:

B 경로 — Claude Sonnet 4.6 을 사용한 CPU 전용

GPU 가 없는 경우 호스팅된 모델을 사용할 수 있습니다.

API 키 추가

.env 파일에서:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=your_api_key_here
ANTHROPIC_MODEL=claude-sonnet-4-6

재시작:

docker compose restart

이제 OpenClaw 는 추론에 Claude Sonnet 4.6 을 사용하며, 오케스트레이션은 로컬에서 실행됩니다.

이 설정은 무거운 모델 계산이 클라우드에서 발생하므로 CPU 전용 머신에서 잘 작동합니다.

여기서 Anthropic 모델을 사용하는 경우, 이 Claude 구독 정책 변경 사항 이 OpenClaw 가 Claude 플랜 재사용 대신 API 기반 청구가 필요한 이유를 설명합니다.

단계 3 — 첫 번째 프롬프트로 OpenClaw 테스트

컨테이너가 실행 중이고 모델이 구성된 후 어시스턴트를 테스트할 수 있습니다.

설정 방식에 따라 다음을 통해 테스트할 수 있습니다:

  • 웹 인터페이스
  • 메신저 통합
  • 로컬 API 엔드포인트

기본 API 테스트를 위해:

curl http://localhost:3000/health

정상 상태 응답을 확인해야 합니다.

이제 간단한 프롬프트를 전송합니다:

curl -X POST http://localhost:3000/chat   -H "Content-Type: application/json"   -d '{"message": "Explain what OpenClaw does in simple terms."}'

구조화된 응답을 받으면 시스템이 작동 중입니다.

방금 실행한 작업

이 시점에서 다음과 같이 설정이 완료되었습니다:

  • 실행 중인 OpenClaw 인스턴스
  • 설정된 LLM 제공자 (로컬 또는 클라우드)
  • 작동하는 요청-응답 루프

GPU 경로를 선택했다면 추론이 Ollama 를 통해 로컬에서 발생합니다.

CPU 경로를 선택했다면 추론은 Claude Sonnet 4.6 을 통해 발생하며, 오케스트레이션, 라우팅, 메모리 처리는 로컬 Docker 컨테이너 내부에서 실행됩니다.

표면적인 상호작용은 간단해 보일 수 있습니다. 그러나 그 아래에서는 여러 구성 요소가 요청을 처리하기 위해 조정합니다.

OpenClaw 설치 및 런타임 문제 해결

모델 응답 없음

  • .env 구성을 확인하세요.
  • 컨테이너 로그를 확인하세요:
docker compose logs

Ollama 접근 불가

  • Ollama 가 실행 중인지 확인하세요:
ollama list
  • 기본 URL 이 환경과 일치하는지 확인하세요.

유효하지 않은 API 키

  • ANTHROPIC_API_KEY 를 다시 확인하세요.
  • .env 업데이트 후 컨테이너를 재시작하세요.

GPU 사용 안됨

  • GPU 드라이버가 설치되었는지 확인하세요.
  • Docker 가 GPU 접근 권한을 활성화했는지 확인하세요.

OpenClaw 설치 후 다음 단계

이제 작동하는 OpenClaw 인스턴스가 있습니다.

이제 다음과 같이 진행할 수 있습니다:

  • 메신저 플랫폼 연결
  • 문서 검색 활성화
  • 라우팅 전략 실험
  • 관측 가능성 및 메트릭 추가
  • 성능 및 비용 동작 튜닝

시스템이 실행되면 더 깊은 아키텍처 논의가 더 의미를 가집니다.

작동하게 만드는 것이 첫 번째 단계입니다.

실행된 후 자연스러운 다음 글들은 다음과 같습니다:

  • OpenClaw 플러그인 가이드 — 메모리, 도구, 채널, 관측 가능성을 위해 어떤 플러그인을 설치해야 하는지, 그리고 생명주기가 어떻게 작동하는지
  • OpenClaw 스킬 가이드 — ClawHub 에서 설치할 가치가 있는 스킬은 무엇이며, 에이전트 역할별로 안전하게 제한하는 방법
  • OpenClaw 프로덕션 설정 패턴 — 개발자, 자동화 팀, 연구원, 지원 운영자 등 실제 사용자 유형별로 플러그인과 스킬이 어떻게 결합되는지

더 많은 AI 시스템 사례 연구를 보려면 AI 시스템 섹션을 참조하세요.

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.