OpenClaw 설치 및 초기 설정 가이드: 5분 만에 시작하기

문제가 생겼을 때 가장 빨리 해결하는 방법은 무엇인가요?

설정 중에 막혔다면 여러분의 PC를 직접 볼 수 있는 로컬 AI agent를 사용해 보세요. Discord에서 질문하는 것보다 훨씬 효과적이에요. 대부분의 “해결 안 되는” 케이스는 외부 조력자가 직접 확인하기 어려운 로컬 설정이나 환경 문제인 경우가 많거든요.

Claude Code: https://www.anthropic.com/claude-code/
OpenAI Codex: https://openai.com/codex/

이 도구들은 repo를 읽고, 명령어를 실행하고, 로그를 확인하며 PATH, 서비스, 권한, 인증 파일 같은 시스템 레벨의 설정을 고치도록 도와줍니다. git 설치 방식을 통해 전체 소스 코드를 AI에게 제공해 주세요.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

다음 명령어부터 시작해 보세요 (도움을 요청할 때 실행 결과도 함께 공유해 주시면 좋아요).

openclaw status
openclaw models status
openclaw doctor

OpenClaw를 설치하고 설정하는 권장 방법은 무엇인가요?

OpenClaw는 소스 코드에서 직접 실행하고 온보딩 위저드를 사용하는 방식을 추천해요.

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

위저드가 UI 에셋도 자동으로 빌드해 줄 거예요. 온보딩이 끝나면 보통 18789 포트에서 Gateway를 실행하게 됩니다.

소스 코드 설치 (기여자/개발자용):

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
openclaw onboard

온보딩 후에 대시보드는 어떻게 여나요?

온보딩 위저드가 끝나면 토큰이 포함된 대시보드 URL을 브라우저에서 바로 열어줄 거예요. 터미널에 출력되는 요약 내용에도 전체 링크(토큰 포함)가 표시됩니다. 해당 탭을 그대로 열어두고 사용하세요. 만약 브라우저가 자동으로 실행되지 않았다면, 출력된 URL을 복사해서 같은 장비의 브라우저에 붙여넣으면 됩니다.

로컬호스트와 원격 환경에서 대시보드 인증(토큰)은 어떻게 하나요?

로컬호스트 (같은 장비):

http://127.0.0.1:18789/에 접속하세요.
만약 인증을 요구한다면, openclaw dashboard를 실행한 뒤 출력되는 토큰 링크(?token=...)를 사용하세요.

로컬호스트가 아닌 경우:

Tailscale Serve (권장): loopback 바인딩을 유지하면서 openclaw gateway --tailscale serve를 실행하세요.
Tailnet bind: openclaw gateway --bind tailnet --token "<token>"을 실행하세요.
SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host 명령어를 사용하세요.

어떤 런타임이 필요한가요?

Node.js 22 버전 이상이 필요해요. 패키지 매니저는 pnpm을 추천해요. Gateway에는 Bun을 사용하는 건 추천하지 않아요.

Raspberry Pi에서도 실행되나요?

네, 가능해요. Gateway는 가벼운 편이라 개인용이라면 512MB~1GB RAM, 1 코어, 그리고 약 500MB의 디스크 공간이면 충분해요. Raspberry Pi 4에서도 충분히 실행할 수 있어요.

로그, 미디어, 혹은 다른 서비스들을 함께 돌릴 여유가 필요하다면 2GB RAM을 추천해요.

팁: 사양이 낮은 Pi나 VPS에 Gateway를 호스팅하고, 노트북이나 스마트폰의 nodes를 연결해서 로컬 화면, 카메라, 캔버스로 활용할 수 있어요.

Raspberry Pi 설치를 위한 팁이 있나요?

64-bit OS를 사용하고 Node.js 버전을 22 이상으로 유지하세요.
로그를 확인하고 빠르게 업데이트할 수 있도록 hackable (git) 설치 방식을 권장해요.
처음에는 channels나 skills 없이 시작하고, 하나씩 차근차근 추가해 보세요.
만약 이상한 바이너리 오류가 발생한다면, 보통 ARM 호환성 문제일 가능성이 커요.

”wake up my friend” 화면에서 멈췄거나 온보딩이 진행되지 않아요. 어떻게 하죠?

해당 화면은 Gateway에 접속할 수 있고 인증이 완료된 상태여야 넘어갈 수 있어요.

Gateway를 재시작해 보세요:
Terminal window
```
openclaw gateway restart
```

상태와 인증을 확인하세요:

openclaw status
openclaw models status
openclaw logs --follow

그래도 계속 멈춰 있다면 다음 명령어를 실행하세요:
Terminal window
```
openclaw doctor
```

온보딩 과정을 다시 거치지 않고 설정을 새 기기(Mac mini)로 옮길 수 있나요?

네, 가능해요. state directory와 workspace를 복사한 다음, Doctor를 한 번 실행하면 됩니다.

새 기기에 OpenClaw를 설치하세요.
기존 기기에서 $OPENCLAW_STATE_DIR (기본값: ~/.openclaw)를 복사하세요.
workspace (기본값: ~/.openclaw/workspace)를 복사하세요.
openclaw doctor를 실행하고 Gateway 서비스를 다시 시작하세요.

이렇게 하면 설정, auth profiles, WhatsApp 인증 정보, 세션, 그리고 memory가 그대로 유지돼요.

최신 버전의 변경 사항은 어디서 확인할 수 있나요?

GitHub changelog를 확인해 보세요: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

stable 버전과 beta 버전의 차이점은 무엇인가요?

Stable과 beta는 별도의 코드 라인이 아니라 npm dist-tags를 의미해요.

latest = stable
beta = 테스트를 위한 초기 빌드

먼저 빌드를 beta로 배포하여 테스트를 진행하고, 문제가 없다고 판단되면 해당 버전을 그대로 latest로 승격시키는 방식을 사용하고 있어요.

beta 버전은 어떻게 설치하나요?

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

수정 가능한(git) 설치를 원하신다면 아래 명령어를 사용하세요.

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

설치와 온보딩은 보통 얼마나 걸리나요?

설치: 2~5분
온보딩: 설정하려는 채널이나 모델 수에 따라 5~15분 정도 걸려요.

설치 프로그램이 멈췄나요? 자세한 피드백을 확인하는 방법

verbose output 옵션을 사용해서 설치 프로그램을 다시 실행해 보세요.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

Windows 설치 중 “git not found” 또는 “openclaw를 찾을 수 없음” 메시지가 뜨는 경우

1) npm error spawn git / git을 찾을 수 없음

Git for Windows를 설치하고 git이 PATH에 추가되어 있는지 확인해 주세요.
PowerShell을 닫았다가 다시 연 다음, 설치 프로그램을 다시 실행하세요.

2) 설치 후 openclaw 명령어를 인식하지 못함

npm global bin 폴더가 PATH에 등록되어 있지 않을 수 있어요.
npm config get prefix 명령어로 경로를 확인해 보세요.
<prefix>\bin 경로가 PATH에 포함되어 있는지 확인이 필요해요.

Windows에서 가장 쾌적하게 설정하고 싶다면, 기본 Windows 환경 대신 WSL2를 사용하는 걸 추천해요.

Linux에서 OpenClaw를 어떻게 설치하나요?

Linux 가이드를 따라 설치한 뒤, 온보딩 마법사를 실행해 주세요.

Linux 빠른 경로 + 서비스 설치: Linux
전체 가이드: Getting Started

VPS에 OpenClaw를 어떻게 설치하나요?

어떤 Linux VPS든 상관없어요. 서버에 설치한 다음, SSH나 Tailscale을 사용해서 Gateway에 접속하면 됩니다.

가이드: Hetzner, Fly.io, exe.dev

OpenClaw가 스스로 업데이트하게 할 수 있나요?

결론부터 말씀드리면 가능은 하지만 추천하지 않아요. 업데이트 과정에서 Gateway가 재시작되면서 활성 세션이 끊길 수 있고, 깨끗한 git checkout이 필요할 수도 있어요. 또한 확인 메시지가 뜨는 경우도 있습니다. 운영자가 직접 shell에서 업데이트를 실행하는 게 더 안전해요.

openclaw update
openclaw update status
openclaw update --channel stable|beta|dev

onboarding wizard는 실제로 어떤 역할을 하나요?

openclaw onboard를 실행하면 다음 과정들을 차근차근 안내해 줘요:

Model/auth setup (Anthropic setup-token, OpenAI Codex OAuth, API keys, local models)
Workspace 위치 + bootstrap 파일
Gateway settings (bind/port/auth/tailscale)
Providers (WhatsApp, Telegram, Discord, Signal, iMessage)
Daemon install (macOS의 LaunchAgent, Linux/WSL2의 systemd user unit)
Health checks 및 skills 선택

이걸 실행하려면 Claude나 OpenAI 구독이 꼭 필요한가요?

아니요, 그렇지 않아요. Anthropic이나 OpenAI 같은 서비스의 API keys를 사용하거나, 데이터를 기기에만 보관할 수 있는 local-only models로 OpenClaw를 실행할 수 있습니다. 구독은 해당 서비스에서 인증을 받는 선택적인 방법일 뿐이에요.

AI Setup Assistant

API key 없이 Claude Max 구독을 사용할 수 있나요?

네, 가능해요. API key 대신 setup-token을 사용해서 인증할 수 있어요. 이게 바로 구독형 방식이에요.

Anthropic setup-token 인증은 어떻게 작동하나요?

claude setup-token은 Claude Code CLI를 통해 token string을 생성해요 (웹 콘솔에서는 사용할 수 없어요). 어떤 기기에서든 실행할 수 있죠. 위저드에서 **Anthropic token (paste setup-token)**을 선택하거나, 아래 명령어로 붙여넣으세요.

openclaw models auth paste-token --provider anthropic

Anthropic setup-token은 어디서 찾나요?

Anthropic Console에는 없어요. setup-token은 Claude Code CLI에서 생성돼요.

claude setup-token

출력된 토큰을 복사한 다음, 위저드에서 **Anthropic token (paste setup-token)**을 선택하면 돼요.

왜 Anthropic에서 `HTTP 429: rate_limit_error`가 발생하나요?

현재 정해진 시간 동안의 Anthropic quota/rate limit을 모두 소진했기 때문이에요. Claude subscription을 사용 중이라면 제한이 초기화될 때까지 기다리거나 플랜을 업그레이드하세요. Anthropic API key를 사용 중이라면 Anthropic Console에서 사용량과 결제 상태를 확인해 보세요.

팁: 특정 provider가 rate-limited 상태일 때도 OpenClaw가 계속 응답할 수 있도록 fallback model을 설정해 두는 게 좋아요.

AWS Bedrock을 지원하나요?

네, 지원해요. pi-ai의 Amazon Bedrock (Converse) provider를 통해 manual config로 설정할 수 있어요. Gateway 호스트에 AWS credentials와 region을 제공하고, models config에 Bedrock provider 항목을 추가하면 돼요.

Codex 인증은 어떻게 작동하나요?

OpenClaw는 OAuth(ChatGPT sign-in)를 통해 **OpenAI Code (Codex)**를 지원해요. Wizard가 OAuth flow를 실행할 수 있고, 상황에 맞춰 기본 모델을 openai-codex/gpt-5.2로 설정해 줄 거예요.

Gemini CLI OAuth는 어떻게 설정하나요?

Gemini CLI는 plugin auth flow를 사용해요:

openclaw plugins enable google-gemini-cli-auth
openclaw models auth login --provider google-gemini-cli --set-default

가벼운 채팅용으로 로컬 모델을 써도 괜찮을까요?

보통은 권장하지 않아요. OpenClaw는 큰 context와 강력한 safety 기능이 필요한데, 사양이 낮은 카드는 텍스트가 잘리거나 정보가 유출될 수 있거든요. 꼭 사용해야 한다면, 로컬(LM Studio)에서 실행할 수 있는 가장 큰 MiniMax M2.1 빌드를 사용하세요.

강력히 경고할게요. 모델 크기가 작거나 quantized된 모델은 prompt-injection 위험을 높여요.

설치하려면 Mac mini를 꼭 사야 하나요?

아니요, 그렇지 않아요. OpenClaw는 macOS나 Linux(Windows는 WSL2 사용)에서 실행됩니다. Mac mini는 선택 사항일 뿐이에요. 항상 켜두는 호스트로 쓰려고 구매하는 분들도 있지만, 작은 VPS나 홈 서버, Raspberry Pi급 기기도 충분히 활용할 수 있습니다.

Mac이 꼭 필요한 경우는 오직 macOS 전용 도구를 사용할 때뿐이에요. iMessage를 사용하신다면 BlueBubbles를 추천합니다.

iMessage 지원을 위해 Mac mini가 필요한가요?

Messages 앱에 로그인된 macOS 기기가 하나는 있어야 해요. 꼭 Mac mini일 필요는 없고, 어떤 Mac이든 상관없습니다. iMessage 연동에는 BlueBubbles를 사용하는 것을 추천드려요.

Bun을 사용해도 될까요?

Bun은 추천하지 않아요. 특히 WhatsApp이나 Telegram을 사용할 때 런타임 버그가 발생하는 것을 확인했습니다. 안정적인 Gateway 운영을 위해 Node를 사용해 주세요.

Telegram: `allowFrom`에 무엇을 넣어야 하나요?

channels.telegram.allowFrom에는 메시지를 보내는 실제 사용자의 Telegram 사용자 ID(숫자 형태 권장)나 @username을 입력하면 돼요. 봇의 사용자 이름(username)이 아니라는 점에 주의하세요.

ID를 찾는 방법은 다음과 같습니다:

봇에게 DM을 보낸 뒤, openclaw logs --follow 명령어를 실행하고 from.id 항목을 확인하세요.
https://api.telegram.org/bot<bot_token>/getUpdates API를 호출하고 message.from.id 항목을 확인하세요.

하나의 WhatsApp 번호를 여러 명이 서로 다른 OpenClaw instance로 사용할 수 있나요?

네, multi-agent routing을 통해 가능해요. 각 발신자의 WhatsApp DM을 서로 다른 agentId에 바인딩하면 돼요. 그러면 사용자마다 각자 자신만의 workspace와 session store를 가질 수 있어요.

”빠른 채팅” agent와 “코딩용 Opus” agent를 따로 실행할 수 있나요?

네, 가능해요. multi-agent routing을 사용해 보세요. 각 agent에 고유한 기본 model을 할당한 다음, inbound routes를 각 agent에 연결하면 돼요.

Hackable (git) 설치와 npm 설치의 차이점은 무엇인가요?

Hackable (git) install: 전체 소스 코드를 체크아웃하며, 직접 수정이 가능해요. 기여자들에게 가장 적합한 방식이죠. 로컬에서 직접 빌드를 실행하고 코드나 문서를 패치할 수 있어요.
npm install: 전역 CLI 설치 방식이에요. 별도의 repo 없이 “그냥 실행”하고 싶은 분들에게 딱이에요. 업데이트는 npm dist-tags를 통해 제공돼요.

나중에 npm 설치와 git 설치 방식을 서로 바꿀 수 있나요?

네, 가능해요. 다른 방식을 설치한 다음, Doctor를 실행해서 gateway 서비스가 새로운 entrypoint를 가리키도록 설정하면 돼요. 이 과정에서 데이터는 삭제되지 않아요. 단지 OpenClaw 코드 설치 경로만 바뀔 뿐이에요.

Gateway를 제 노트북에서 실행해야 할까요, 아니면 VPS에서 실행해야 할까요?

24시간 내내 안정적으로 작동하길 원한다면 VPS를 사용하세요. 가장 간편하게 시작하고 싶고, 노트북이 절전 모드로 들어가거나 재부팅되는 상황이 괜찮다면 로컬에서 실행해도 좋아요.

노트북 (로컬 Gateway)

장점: 서버 비용이 들지 않고 로컬 파일에 직접 접근할 수 있으며, 브라우저 창을 실시간으로 확인할 수 있어요.
단점: 절전 모드나 네트워크 끊김 시 연결이 해제되고, OS 업데이트나 재부팅으로 인해 작업이 중단될 수 있어요.

VPS / 클라우드

장점: 항상 켜져 있는 안정적인 네트워크를 제공하며, 노트북 절전 모드 문제를 걱정할 필요가 없어요.
단점: 보통 GUI 없이 실행되어 스크린샷을 활용해야 하고, 원격으로만 파일에 접근할 수 있어요.

OpenClaw를 전용 머신에서 실행하는 것이 얼마나 중요한가요?

필수 사항은 아니지만, 안정성과 환경 격리를 위해 권장해요.

전용 호스트 (VPS/Mac mini/Pi): 항상 켜져 있고 작업 중단이 거의 없어요.
공용 노트북/데스크탑: 테스트 목적이나 직접 사용 중일 때는 전혀 문제없어요.

최소 VPS 사양과 추천 OS는 무엇인가요?

OpenClaw는 가볍게 설계되었어요.

최소 사양: 1 vCPU 및 1GB RAM, 약 500MB의 디스크 공간
권장 사양: 1-2 vCPU, 2GB RAM 이상

OS는 Ubuntu LTS (또는 최신 Debian/Ubuntu 계열)를 사용하세요.

OpenClaw를 VM에서 실행할 수 있나요? 사양은 어떻게 되나요?

네, 가능해요. VM도 VPS와 똑같이 취급하면 돼요. 항상 켜져 있어야 하고 외부에서 접속이 가능해야 하며, Gateway와 활성화할 채널들을 구동할 수 있는 충분한 RAM이 필요해요.

최소 사양: 1 vCPU, 1GB RAM
권장 사양: 2GB RAM 이상

Windows를 사용 중이라면 WSL2가 가장 쉬운 VM 방식의 설정이에요.

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.