OpenClaw 빠른 시작: Docker로 설치 (Ollama GPU 또는 Claude CPU)

로컬에 OpenClaw를 Ollama와 함께 설치하세요.

Page content

OpenClaw은 로컬 LLM 런타임(예: Ollama) 또는 클라우드 기반 모델(예: Claude Sonnet)과 함께 실행되는 자체 호스팅 AI 어시스턴트입니다.

이 빠른 시작 가이드는 Docker를 사용하여 OpenClaw을 배포하고, GPU 기반 로컬 모델 또는 CPU만 사용하는 클라우드 모델을 구성하고, AI 어시스턴트가 종단간으로 작동하는지 확인하는 방법을 보여줍니다.

이 가이드는 OpenClaw의 최소한의 설정을 통해, 사용자의 컴퓨터에서 실행되고 응답하는 모습을 확인할 수 있도록 안내합니다.

목표는 간단합니다:

  • OpenClaw을 실행합니다.
  • 요청을 보내봅니다.
  • 작동하는지 확인합니다.

이 가이드는 생산성 강화에 대한 내용이 아닙니다.
이 가이드는 성능 최적화에 대한 내용이 아닙니다.
이 가이드는 실용적인 시작점입니다.

두 가지 선택지가 있습니다:

  • 경로 A — 로컬 GPU Ollama 사용 (GPU가 있다면 권장)
  • 경로 B — CPU만 사용 Claude Sonnet 4.6을 통해 Anthropic API 사용

두 경로 모두 동일한 핵심 설치 과정을 공유합니다.

install openclaw steps GPU vs CPU

OpenClaw에 처음 접하는 경우, 시스템 구조에 대한 더 깊은 개요를 원하시면 다음을 참조하세요: OpenClaw 시스템 개요.

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

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

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

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

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

두 경로 모두에 필요한 사항

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

경로 A (로컬 GPU)

  • 호환되는 GPU가 있는 머신 (NVIDIA 또는 AMD 추천)
  • Ollama 설치

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

  • Anthropic API 키
  • Claude Sonnet 4.6에 대한 접근

단계 1 — Docker를 사용하여 OpenClaw 설치 (클론 및 시작)

Docker Compose를 사용하여 OpenClaw을 시작할 수 있습니다. 이는 설정을 격리하고 재현 가능한 상태로 유지합니다.

저장소 클론

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)

이제 추론이 어떻게 작동할지 결정해야 합니다.

경로 A — 로컬 GPU와 Ollama 사용

GPU가 있다면 이는 가장 간단하고 자체 포함된 옵션입니다.

Ollama 설치 또는 확인

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

Ollama이 설치되지 않았다면:

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

동작을 확인해 보세요:

ollama pull llama3
ollama run llama3

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

Ollama 사용하도록 OpenClaw 구성

.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만 사용하는 머신에서 잘 작동합니다. 중간 계산은 클라우드에서 수행되기 때문입니다.

단계 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 인스턴스를 보유하고 있습니다.

이제 다음과 같은 작업을 수행할 수 있습니다:

  • 메시징 플랫폼 연결
  • 문서 검색 기능 활성화
  • 라우팅 전략 실험
  • 관찰 가능성 및 메트릭 추가
  • 성능 및 비용 행동 조정

시스템이 실행 중이면 더 깊은 아키텍처 논의가 더 의미가 있습니다.

운영 가능하게 만드는 것이 첫 번째 단계입니다.