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

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

Page content

OpenClaw는 Ollama와 같은 로컬 LLM 런타임이나 Claude Sonnet과 같은 클라우드 기반 모델과 함께 실행하도록 설계된 셀프 호스팅(Self-hosted) AI 어시스턴트입니다.

이 퀵스타트(Quickstart) 가이드는 Docker를 사용하여 OpenClaw를 배포하고, GPU가 탑재된 로컬 모델 또는 CPU 전용 클라우드 모델을 구성하며, AI 어시스턴트가 종단 간(end-to-end)으로 정상 작동하는지 확인하는 방법을 보여줍니다.

이 가이드는 OpenClaw의 최소 구성을 안내하여 사용자가 자신의 컴퓨터에서 실행되고 응답하는 모습을 확인할 수 있도록 합니다.

목표는 단순합니다.

  • OpenClaw를 실행합니다.
  • 요청을 보냅니다.
  • 정상 작동 여부를 확인합니다.

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

두 가지 옵션이 있습니다.

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

두 경로 모두 동일한 핵심 설치 프로세스를 공유합니다.

install openclaw steps GPU vs CPU

OpenClaw를 처음 사용하시거나 시스템 구조에 대한 심층 개요가 필요하시다면 OpenClaw 시스템 개요를 읽어보세요. 더 엄격한 샌드박싱과 정책 제어와 함께 상시 실행되는 어시스턴트를 운영할 계획이라면 NemoClaw 보안 운영 가이드를 따르세요.

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

OpenClaw는 외부 서비스에 연결할 수 있는 어시스턴트 스타일의 시스템입니다. 이 퀵스타트에서는 다음을 권장합니다.

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

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

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에서 실행할 모델을 결정하거나 벤치마크 비교가 필요하거나, 도구 중심 어시스턴트를 위한 적절한 Qwen / Gemma 샘플러 기본값이 필요하시면 다음을 참조하세요.

로드 하에서의 동시성 및 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 인스턴스를 보유하고 있습니다.

이어서 다음 작업을 수행할 수 있습니다.

  • 메시지 플랫폼 연결
  • 문서 검색 활성화
  • 라우팅 전략 실험
  • 가시성(Observability) 및 메트릭 추가
  • 성능 및 비용 동작 조정

시스템이 실행된 이후에 더 깊은 수준의 아키텍처 논의가 더 의미가 있습니다.

운영 가능한 상태로 만드는 것이 첫 번째 단계입니다.

실행된 후 자연스럽게 이어질 다음 기사들은 다음과 같습니다.

  • AI 어시스턴트의 메모리 시스템 — OpenClaw 메모리 플러그인을 튜닝하기 전 작업 메모리, 구조화된 상태 및 검색이 어떻게 결합되는지 설명
  • OpenClaw 플러그인 가이드 — 메모리, 도구, 채널 및 가시성을 위해 어떤 플러그인을 설치해야 하는지, 그리고 라이프사이클이 어떻게 작동하는지 설명
  • OpenClaw 기술(Skills) 가이드 — ClawHub에서 설치할 가치가 있는 기술은 무엇인지, 그리고 에이전트 역할별로 안전하게 게이트(gate)하는 방법을 설명
  • OpenClaw 프로덕션 설정 패턴 — 개발자, 자동화 팀, 연구원, 지원 운영자 등 실제 사용자 유형을 위해 플러그인과 기술이 어떻게 결합되는지 설명

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

구독하기

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