OpenClaw 설치 가이드: 원클릭 설치 + 설정 (Mac/Windows/Linux)

"컵라면을 끓일 수 있다면 OpenClaw도 설치할 수 있습니다. 걸리는 시간도 비슷합니다."

오늘의 목표

Step 0: 어시스턴트가 머물 자리를 고르기

이 설치 가이드의 첫 결정은 간단합니다. 어시스턴트를 정확히 어느 기기에서 실행할지 정하는 것입니다.

권장 VPS 사양: Ubuntu 22.04, CPU 2코어, RAM 4GB, SSD 40GB.

어떤 환경을 골라야 하나요?

• 일단 체험만 해 보기 → 노트북 (가장 쉽지만, 켜져 있을 때만 작동)
• 24시간 가동 원함 → VPS ($5-10/월, 자는 동안에도 실행)
• 24시간 가동이 필요하지만 클라우드는 싫음 → Mac Mini 또는 오래된 PC

어떤 환경을 고르든 OpenClaw의 작업 파일은 보통 ~/.openclaw/workspace/ 에, 설치한 스킬은 보통 ~/.openclaw/skills/ 에 저장됩니다.

이 단계가 끝났는지는 이렇게 확인하면 됩니다. "내 어시스턴트를 계속 온라인 상태로 유지할 정확한 기기는 무엇인가?"

Step 1: 준비물 챙기기

설치를 실행하기 전에 아래 항목을 준비하세요.

Node 22.16 이상 (기본 권장 런타임은 Node 24)

• 필요한 이유: openclaw CLI는 Node.js 위에서 실행됩니다.
• node -v 로 확인하세요. Node 22.16 이상이면 준비 완료입니다.

AI 모델 접근 방식 (하나 선택)

• Claude 구독 (Pro/Max/Team)
  • 필요한 이유: 어시스턴트의 각 응답과 도구 계획에는 여전히 모델 제공자가 필요합니다.
  • 마법사에서 OAuth를 사용하면 API key를 붙여 넣지 않아도 됩니다.
• Anthropic API key
  • 필요한 이유: OpenClaw가 Anthropic을 직접 호출할 때 쓰는 자격 증명입니다.
  • console.anthropic.com 에서 받을 수 있습니다.
• 그 외 지원: OpenAI, Gemini, OpenRouter, Qwen, Mistral 등
  • 필요한 이유: Claude가 아니어도 지원되는 제공자면 어시스턴트를 구동할 수 있습니다.

Telegram Bot Token

1. Telegram을 열고 @BotFather 를 검색합니다.
2. /newbot 을 보내고 이름과 사용자 이름을 정합니다.
3. BotFather가 돌려준 token을 복사합니다.

필요한 이유: 이 token으로 OpenClaw가 봇을 통해 Telegram 메시지를 주고받습니다.

내 Telegram User ID

• Telegram에서 @userinfobot 를 검색해 숫자 ID를 복사합니다.
• 필요한 이유: onboarding에서 나를 admin으로 지정해, 다른 사람이 어시스턴트를 제어하지 못하게 합니다.

정리하면 이 네 가지가 있어야 합니다. 기기 하나, Node 22.16 이상, 모델 자격 경로 하나, Telegram 관련 값 두 개.

Step 2: 설치하기

다음을 실행하세요:

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

공식 원라이너입니다. 필요하면 OpenClaw와 Node를 함께 설치합니다.

수동 설치 방법도 있습니다:

npm install -g openclaw@latest && openclaw onboard

이 방식은 CLI를 직접 설치한 뒤 onboarding 마법사를 열어 ~/.openclaw/workspace/ 아래에 초기 설정을 작성합니다.

플랫폼 가이드: macOS → 플랫폼 가이드: Windows → 플랫폼 가이드: Linux / VPS →

command not found 대신 마법사가 열리고, onboarding 이후 openclaw status 에 실행 중 서비스가 보이면 제대로 된 것입니다.

Step 3: 마법사가 묻는 것

설정 마법사는 다섯 가지를 차례로 묻습니다.

1. Mode — 첫 설치라면 QuickStart를 선택합니다.
2. AI Model — 제공자를 고르고 인증합니다.
3. Chat Channel — Telegram을 선택하고 Bot Token을 붙여 넣습니다.
4. Admin Setup — Telegram user ID를 입력합니다.
5. Daemon Install — 예를 선택해 어시스턴트가 백그라운드에서 실행되고 재부팅 후에도 살아나게 합니다.

Linux에서는 보통 systemd 사용자 유닛이고, macOS에서는 보통 LaunchAgent입니다. 구현은 달라도 목표는 같습니다. 기기가 다시 시작되면 OpenClaw도 자동으로 시작되어야 합니다.

Daemon 설치가 오류 없이 끝나고 openclaw status 가 stopped가 아니라 healthy를 보여 주면 이 단계는 통과입니다.

Step 4: 첫 메시지 보내기

마법사가 끝나면 Telegram에서 봇을 찾아 이렇게 보내세요:

안녕, 너는 누구야?

몇 초 안에 답장이 와야 합니다. 지금은 ~/.openclaw/workspace/SOUL.md 같은 파일을 아직 설정하지 않았기 때문에 말투가 다소 평범할 수 있습니다. 그건 Day 3에서 바꿉니다.

추가로 몇 개 더 시도해 보세요:

• "Python quicksort를 작성해 줘"
• "1024의 제곱근은 얼마야?"
• "내 이메일을 확인해 줄 수 있어?" (지금은 아직 안 된다고 답해야 정상입니다.)

Telegram에서 실제 봇 답장이 오고, openclaw logs --follow 에 같은 메시지에 대한 오류가 반복되지 않으면 성공입니다.

최소 성공 기준

오늘 끝나면 최소한 아래 세 가지는 가능해야 합니다.

• openclaw status 를 실행하면 실행 중으로 보인다
• Telegram에 메시지를 보내면 응답이 온다
• 컴퓨터를 껐다 켜도 서비스가 자동으로 다시 시작된다

검증 체크: 재부팅 테스트는 나중으로 미루지 말고 지금 하세요. 자동으로 돌아오지 않으면, 그 문제를 먼저 해결하고 다음 날로 넘어가야 합니다.

자주 쓰는 관리 명령어

아래 명령은 계속 쓰게 됩니다.

openclaw status           # Overall health
openclaw doctor           # Full diagnostic check
openclaw gateway restart  # Restart background service
openclaw logs --follow    # View runtime logs
openclaw configure        # Change model, channel, or any setting

이 명령어가 기본 운영에 충분한지는 두 질문에 빨리 답할 수 있으면 됩니다. "지금 실행 중인가?" 그리고 "로그에는 뭐라고 나오나?"

자주 생기는 문제

포트가 이미 사용 중입니다 — 다른 프로세스가 OpenClaw가 쓰려는 포트를 먼저 잡고 있습니다. openclaw logs --follow 에서 오류를 확인하고 충돌 프로세스를 정리한 뒤 openclaw daemon restart 를 실행하세요. bind 오류가 더 이상 반복되지 않고 openclaw status 가 healthy로 돌아오면 해결된 것입니다.

Telegram 봇이 응답하지 않습니다 — 대개 bot token이 잘못됐거나, Telegram user ID가 없거나, daemon이 시작되지 않았기 때문입니다. openclaw configure 또는 openclaw onboard 를 다시 실행한 뒤 새 테스트 메시지를 보내세요. 봇이 응답하고 로그에 auth failure 대신 수신 메시지가 보이면 해결입니다.

재부팅 후 서비스가 시작되지 않습니다 — daemon 설치 단계가 실패했거나 건너뛰어진 경우가 많습니다. openclaw doctor 를 실행하고, 필요하면 daemon을 다시 설치한 뒤 다시 한 번 재부팅하세요. 로그인 직후나 서버 부팅 직후 openclaw status 가 running이면 해결입니다.

전체 문제 해결 가이드 →

다음 단계

이제 어시스턴트는 대화는 할 수 있지만 아직 성격도 없고 운영 지침도 없습니다. 내일은 ~/.openclaw/workspace/ 의 핵심 파일들, 즉 ~/.openclaw/workspace/SOUL.md, ~/.openclaw/workspace/USER.md, ~/.openclaw/workspace/AGENTS.md, ~/.openclaw/workspace/IDENTITY.md 를 편집하게 됩니다.