오픈클로(OpenClaw) 도커 설치방법!

어느 디바이스든 동일하게 설치할 수 있는 도커 환경에서 오픈클로를 설치해보자.
(참고로 디바이스는 맥미니 m4이다)

사전 준비
 - 도커 데스크톱 설치(아래 포스트 참고)

2025.04.13 - [IT/Tech] - 맥미니에 파일서버 만들기 #1 도커 설치

맥미니에 파일서버 만들기 #1 도커 설치

도커를 설치 했다면 도커 컴포즈를 이용해서 오픈클로를 설치해보자
docker-compose.yml 파일이란 일종의 설치설명서라고 보면된다. 왜냐? 이 설명서 파일만 있으면 도커가 설치되어있는 디바이스에서 동일한 구성으로 찍어내듯이 설치가 가능하니까!

1. 폴더 생성

적당한 경로에 openclaw 폴더를 하나 만들었다.

예시
docker
 - (폴더 생성) openclaw

docker-compose.yml 파일경로 이미지

2. 깃허브에서 오픈클로 소스 클론(복사)

(문제) 언젠가는 나오겠지만 작성일자 기준 오픈클로 공식 도커 이미지 없다.
 ✘ Image openclaw/openclaw:latest Error pull ...                           1.2s 
Error response from daemon: pull access denied for openclaw/openclaw, repository does not exist or may require 'docker login'

(해결) 그렇기 때문에 깃허브에서 오픈클로 소스를 복사해서 도커 이미지로 빌드하면 된다
1. (권장) 깃허브에서 공식 파일을 받아서 도커로 설치하는 것!
2. 아래 이미지처럼 도커허브에 올라온 비공식 openclaw 이미지를 설치하는 것!
 * 나는 깃허브를 받아서 설치하기로 결정

도커 데스크톱 캡쳐화면

1. 경로 이동
cd /Volumes/Storage/Data/service/docker

2. openclaw 초기화(파일 삭제)
rm -rf openclaw

3. 깃허브 소스코드 클론 (Clone)
git clone https://github.com/openclaw/openclaw.git

3. openclaw 오픈클로 자동 설치 스크립트 설치

1. 이전 단계에서 클론한 경로로 이동한다
cd openclaw

2. 실행
./docker-setup.sh

이 스크립트는 다음 작업을 자동으로 수행

1. ✅ Gateway 이미지 빌드
2. ✅ 온보딩 마법사 실행
3. ✅ 프로바이더 설정 힌트 출력
4. ✅ Docker Compose를 통한 Gateway 시작
5. ✅ Gateway 토큰 생성 및 .env 파일에 저장

4. 온보딩 마법사 설정

자동 설치 스크립트가 정상적으로 완료되었다면 온보딩 마법사가 자동으로 실행된다.
설정 항목들을 보면서 본인에게 맞는 설정으로 진행

오픈클로 온보딩 마법사

번호	항목	선택값
1	I understand this is powerful and inherently risky. Continue?	Yes
2	Onboarding mode	QuickStart
3	Model/auth provider │  ○ OpenAI │  ○ Anthropic │  ○ Chutes │  ○ vLLM │  ○ MiniMax │  ○ Moonshot AI (Kimi K2.5) │  ● Google (Gemini API key + OAuth) │  ○ xAI (Grok) │  ○ OpenRouter │  ○ Qwen │  ○ Z.AI │  ○ Qianfan │  ○ Copilot │  ○ Vercel AI Gateway │  ○ OpenCode Zen │  ○ Xiaomi │  ○ Synthetic │  ○ Together AI │  ○ Hugging Face │  ○ Venice AI │  ○ LiteLLM │  ○ Cloudflare AI Gateway │  ○ Custom Provider │  ○ Skip for now	Google (Gemini API key + OAuth) 본인의 기호에 맞는 AI모델로 선택하면 된다.
4	Enter Gemini API key 구글 AI스튜디오에서 API키 발급(https://aistudio.google.com)	AI로시작하는 발급받은 API 문자열 입력
5	Default model │  ● Keep current (google/gemini-3-pro-preview) │  ○ Enter model manually │  ○ google/gemini-1.5-flash │  ○ google/gemini-1.5-flash-8b │  ○ google/gemini-1.5-pro │  ○ google/gemini-2.0-flash │  ○ google/gemini-2.0-flash-lite │  ○ google/gemini-2.5-flash │  ○ google/gemini-2.5-flash-lite │  ○ google/gemini-2.5-flash-lite-preview-06-17 │  ○ google/gemini-2.5-flash-lite-preview-09-2025 │  ○ google/gemini-2.5-flash-preview-04-17 │  ○ google/gemini-2.5-flash-preview-05-20 │  ○ google/gemini-2.5-flash-preview-09-2025 │  ○ google/gemini-2.5-pro │  ○ google/gemini-2.5-pro-preview-05-06 │  ○ google/gemini-2.5-pro-preview-06-05 │  ○ google/gemini-3-flash-preview │  ○ google/gemini-3-pro-preview │  ○ google/gemini-flash-latest │  ○ google/gemini-flash-lite-latest │  ○ google/gemini-live-2.5-flash │  ○ google/gemini-live-2.5-flash-preview-native-audio	Keep current (google/gemini-3-pro-preview)
6	Select channel (QuickStart) │  ○ Telegram (Bot API) │  ○ WhatsApp (QR link) │  ○ Discord (Bot API) │  ○ IRC (Server + Nick) │  ○ Google Chat (Chat API) │  ○ Slack (Socket Mode) │  ○ Signal (signal-cli) │  ● iMessage (imsg) (not configured) │  ○ Feishu/Lark (飞书) │  ○ Nostr (NIP-04 DMs) │  ○ Microsoft Teams (Bot Framework) │  ○ Mattermost (plugin) │  ○ Nextcloud Talk (self-hosted) │  ○ Matrix (plugin) │  ○ BlueBubbles (macOS app) │  ○ LINE (Messaging API) │  ○ Zalo (Bot API) │  ○ Zalo (Personal Account) │  ○ Tlon (Urbit) │  ○ Skip for now	iMessage 아이폰이라 그냥 선택해봄
7	imsg CLI path	imsg
8	Selected channels This is still a work in progress. Ensure OpenClaw has Full Disk Access to Messages DB. Grant Automation permission for Messages when prompted. List chats with: imsg chats --limit 20 Docs: imessage Selected channels iMessage — this is still a work in progress. Docs:  imessage Skills status Eligible: 3  Missing requirements: 40 Unsupported on this OS: 7 Blocked by allowlist: 0	안내성 문구로 선택항목 없음
9	Configure skills now? (recommended)	Yes
10	Install missing skill dependencies	Skip for now (Continue without installing dependencies)
11	Set GOOGLE_PLACES_API_KEY for goplaces? Set GEMINI_API_KEY for nano-banana-pro? Set NOTION_API_KEY for notion? Set OPENAI_API_KEY for openai-image-gen? Set OPENAI_API_KEY for openai-whisper-api? Set ELEVENLABS_API_KEY for sag?	No
12	Enable hooks?	Skip for now

온보딩 로그 마지막에 Health check failed (1006)가 뜨는 이유는, 온보딩을 진행한 임시 컨테이너가 작업을 마치고 종료되면서 실제 실행 중인 게이트웨이 서버와의 연결을 스스로 끊었기 때문인데 즉, 설치가 실패한 게 아니라 온보딩 절차가 무사히 종료되었다는 신호이니 안심해도 된다!

Health check failed: gateway closed (1006 abnormal closure (no close frame)): no close reason   Gateway target: ws://127.0.0.1:18789   Source: local loopback   Config: /home/node/.openclaw/openclaw.json   Bind: loopback

자 모든 것이 완료됐으니 Dashboard ready에 있는 URL(http://localhost:18789/#token=전체토큰값)을 웹브라우저에 복붙하자.

Dashboard ready 화면 캡쳐

토큰을 못찾을 때는 아래 명령어를 입력하면 된다

1. docker compose run --rm openclaw-cli dashboard --no-open
또는
2. docker compose run --rm openclaw-cli config get gateway.auth.token

(오류 발생) disconnected (1008): unauthorized: device token mismatch (rotate/reissue device token)

오류화면 이미지

(해결 방법) 오픈클로 게이트웨이를 삭제하고 재시작

# 1. 게이트웨이 컨테이너 내부의 기기 데이터베이스 삭제 (강제 로그아웃 효과)
docker compose exec openclaw-gateway rm -f /home/node/.openclaw/devices.json

# 2. 변경사항 적용을 위해 게이트웨이 재시작
docker compose restart openclaw-gateway