OpenClaw 빠른 시작: Docker 설치 (Ollama GPU 또는 Claude + CPU)
Ollama 를 사용하여 OpenClaw 를 로컬로 설치합니다
OpenClaw 는 Ollama 와 같은 로컬 LLM 런타임 또는 Claude Sonnet 과 같은 클라우드 기반 모델과 함께 실행하도록 설계된 자체 호스팅 AI 어시스턴트입니다.
이 빠른 시작 가이드에서는 Docker 를 사용하여 OpenClaw 를 배포하는 방법, GPU 기반 로컬 모델 또는 CPU 전용 클라우드 모델을 구성하는 방법, 그리고 AI 어시스턴트가 정상적으로 작동하는지 종단 간 (end-to-end) 확인하는 방법을 보여줍니다.
이 가이드는 OpenClaw 의 최소 설정을 안내하여 여러분이 자신의 기기에서 실행되고 응답하는 것을 직접 확인할 수 있도록 합니다.
목표는 단순합니다:
- OpenClaw 실행.
- 요청 전송.
- 작동 확인.
이것은 프로덕션 환경 강화 가이드가 아닙니다. 이것은 성능 튜닝 가이드도 아닙니다. 이것은 실용적인 시작점입니다.
두 가지 옵션이 있습니다:
- 경로 A — 로컬 GPU: Ollama 사용 (GPU 가 있는 경우 권장)
- 경로 B — CPU 전용: Anthropic API 를 통한 Claude Sonnet 4.6 사용
두 경로 모두 핵심 설치 프로세스가 동일합니다.
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 인스턴스를 보유하고 있습니다.
이제 다음을 할 수 있습니다:
- 메시징 플랫폼 연결
- 문서 검색 기능 활성화
- 라우팅 전략 실험
- 가시성 및 지표 추가
- 성능 및 비용 동작 튜닝
시스템이 실행된 후에 더 깊은 수준의 아키텍처 논의가 더 잘 이해됩니다.
작동 상태로 만드는 것이 첫 번째 단계입니다.
더 많은 AI 시스템 사례 연구는 AI 시스템 섹션에서 확인하세요.
