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

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

Page content

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

이 퀵스타트 가이드에서는 Docker를 사용하여 OpenClaw를 배포하고, GPU 기반의 로컬 모델 또는 CPU 전용 클라우드 모델을 구성한 후, AI 어시스턴트가 끝에서 끝(end-to-end)으로 정상 작동하는지 확인하는 방법을 보여줍니다.

이 가이드는 OpenClaw의 최소 구성을 설명하여, 사용자의 기기에서 실행되고 응답하는 과정을 직접 확인할 수 있도록 합니다.

목표는 간단합니다:

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

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

두 가지 옵션이 있습니다:

  • 경로 A — 로컬 GPU (GPU가 있는 경우 권장) Ollama 사용
  • 경로 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가 사용 가능한 경우, 이것이 가장 간단하고 자체 포함(self-contained)된 옵션입니다.

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에서 실행할 모델을 결정하거나 벤치마크 비교가 필요하거나, 도구 중심 어시스턴트에 대한 합리적인 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 인스턴스를 갖게 되었습니다.

여기서부터 다음을 수행할 수 있습니다:

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

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

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

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

  • OpenClaw 플러그인 가이드 — 메모리, 도구, 채널 및 가시성을 위해 설치할 플러그인과 라이프사이클 작동 방식
  • OpenClaw 스킬 가이드 — ClawHub에서 설치할 가치가 있는 스킬과 에이전트 역할별로 안전하게 게이트하는 방법
  • OpenClaw 프로덕션 설정 패턴 — 개발자, 자동화 팀, 연구원 및 지원 운영자 등 실제 사용자 유형을 위해 플러그인과 스킬이 결합되는 방법

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

구독하기

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