본문 바로가기
AI

OpenClaw 사용기: 실제 AI 개인 비서 자동화 경험과 설정 방법 총정리

박민서00 2026. 3. 18. 17:50
반응형

 

 

2026년 3월 기준 정리

OpenClaw 설치부터 사용하는 방법까지

이 문서는 OpenClaw를 처음 설치하는 사람을 기준으로, 설치 → 초기 설정 → 대시보드 접속 → 채널 연결 → 기본 사용 → 문제 해결 순서로 정리한 HTML 가이드입니다.

목차
  1. OpenClaw가 무엇인지
  2. 설치 전 준비사항
  3. 설치 방법
  4. 초기 설정(Onboarding)
  5. 대시보드와 Gateway 실행
  6. 기본 사용법
  7. WhatsApp/Telegram 등 채널 연결 개념
  8. 트러블슈팅
  9. 참고 자료

1. OpenClaw가 무엇인지

OpenClaw는 자체 호스팅(self-hosted) 방식의 AI 에이전트 게이트웨이입니다. 한 대의 머신에서 Gateway를 실행해 두면, WhatsApp, Telegram, Discord, iMessage 같은 채널과 연결해서 어디서든 AI 어시스턴트와 대화할 수 있습니다.

핵심 개념

  • Gateway: 메시지, 세션, 라우팅의 중심 프로세스
  • Dashboard: 브라우저에서 채팅/설정/세션을 관리하는 UI
  • Channels: WhatsApp, Telegram, Slack 같은 연결 대상
  • Agent: 실제로 응답을 생성하는 AI 실행 단위

누구에게 적합한가

  • 개인용 AI 비서를 직접 운영하고 싶은 사람
  • 여러 메신저에서 하나의 AI를 쓰고 싶은 사람
  • 데이터와 실행 환경을 직접 통제하고 싶은 개발자

2. 설치 전 준비사항

공식 문서 기준으로 OpenClaw는 다음 환경을 권장합니다.

항목 권장 사항
운영체제 macOS, Linux, Windows
Windows 권장 방식 WSL2에서 실행 권장
Node.js Node 24 권장, Node 22 LTS(22.16+)도 호환용으로 지원
추가 도구 소스 빌드 시 pnpm 필요
권장 설치 방식: 처음이라면 수동 세팅보다 installer script 또는 openclaw onboard 흐름을 쓰는 것이 가장 쉽습니다.

3. 설치 방법

3-1. 가장 쉬운 설치: 공식 설치 스크립트

공식 문서에서 가장 권장하는 방식입니다. Node 감지, 설치, 온보딩까지 한 번에 처리합니다.

macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash
Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

온보딩 없이 바이너리만 설치하려면 다음처럼 실행합니다.

macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
Windows PowerShell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

3-2. npm으로 설치

Node를 이미 직접 관리 중이면 이 방식이 단순합니다.

npm install -g openclaw@latest
openclaw onboard --install-daemon
macOS에서 sharp 빌드 오류가 나면 공식 문서에 나온 것처럼 아래처럼 prebuilt 바이너리를 강제하는 방법이 있습니다. 
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

3-3. pnpm으로 설치

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

3-4. 소스에서 설치

개발 목적이거나 내부 구조를 직접 보고 싶을 때 적합합니다.

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

4. 초기 설정(Onboarding)

OpenClaw의 공식 추천 흐름은 openclaw onboard입니다. 이 단계에서 로컬 또는 원격 Gateway 연결, 인증, 채널, 스킬, 워크스페이스 기본값 등을 안내형으로 설정합니다.

openclaw onboard --install-daemon
처음 대화만 빨리 해보고 싶다면 메신저 채널 연결 없이도 됩니다. 우선 설치 후 openclaw dashboard로 브라우저 UI를 열어 테스트할 수 있습니다.

Onboarding에서 보통 하는 일

  1. Gateway 실행 방식 설정
  2. 인증/토큰 설정
  3. 사용할 모델 또는 제공자 연결
  4. 채널 연동 여부 선택
  5. 기본 워크스페이스/에이전트 설정

5. Dashboard와 Gateway 실행

5-1. Gateway 직접 실행

openclaw gateway --port 18789
# 로그를 자세히 보고 싶으면
openclaw gateway --port 18789 --verbose

5-2. 상태 확인

openclaw gateway status
openclaw status
openclaw logs --follow

정상 상태의 기준은 대체로 다음과 같습니다.

  • Runtime: running
  • RPC probe: ok

5-3. Dashboard 열기

openclaw dashboard

공식 문서 기준으로 온보딩 후에는 대시보드 링크가 자동으로 열리며, 이후에도 openclaw dashboard 명령으로 다시 열 수 있습니다. 로컬 기본 주소 예시는 http://127.0.0.1:18789/입니다.

UI에서 인증을 요구하면 gateway.auth.token 또는 OPENCLAW_GATEWAY_TOKEN 값을 사용해 로그인할 수 있습니다.

6. 기본 사용법

6-1. CLI로 에이전트에게 메시지 보내기

openclaw agent --message "Ship checklist" --thinking high

6-2. 특정 번호/대상으로 메시지 보내기

openclaw message send --to +1234567890 --message "Hello from OpenClaw"

6-3. 상태 점검 명령 모음

명령어 용도
openclaw status 전체 요약 상태 확인
openclaw gateway status Gateway 실행/프로브 상태 확인
openclaw logs --follow 실시간 로그 확인
openclaw doctor 설정/서비스/채널 상태 진단
openclaw channels status --probe 채널 연결 readiness 확인

6-4. 설정 파일 위치

기본 설정 파일은 보통 아래 경로를 사용합니다.

~/.openclaw/openclaw.json

7. WhatsApp / Telegram 등 채널 연결

OpenClaw는 하나의 Gateway에 여러 채널을 붙일 수 있습니다. 일반적으로는 온보딩 중에 연결하거나, 나중에 openclaw channels 계열 명령으로 로그인/로그아웃/상태 확인을 진행합니다.

7-1. 채널 공통 관리

openclaw channels login
openclaw channels logout
openclaw channels status --probe

7-2. Pairing 승인

보안 기본값으로 일부 채널은 pairing 모드를 사용합니다. 이 경우 처음 DM을 보내는 사용자는 짧은 코드를 받게 되고, 서버에서 승인을 해야 실제 메시지가 처리됩니다.

openclaw pairing list <channel>
openclaw pairing approve <channel> <CODE>

예를 들어 WhatsApp에서는 다음과 같이 사용할 수 있습니다.

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
Pairing 코드는 만료 시간이 있으며, 문서 기준으로 대기 중인 요청 수에도 제한이 있습니다. 실제 운영 전에는 allowlist와 DM 정책을 꼭 점검하는 편이 안전합니다.

8. 트러블슈팅

공식 문서에서 제안하는 기본 점검 순서는 다음과 같습니다.

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

자주 보는 상황별 체크

Gateway가 안 뜰 때

  • openclaw gateway --port 18789로 직접 실행
  • 포트 충돌 시 openclaw gateway --force 고려
  • openclaw gateway status에서 running / RPC ok 확인

채널이 로그아웃된 것 같을 때

  • openclaw channels logout
  • openclaw channels login
  • openclaw channels status --probe

메시지가 안 들어올 때

  • 연결된 폰/클라이언트가 온라인인지 확인
  • allowlist / group 정책 확인
  • pairing 승인이 필요한지 확인

설치 직후 가장 먼저 할 일

  • openclaw onboard --install-daemon
  • openclaw dashboard
  • openclaw doctor

9. 초보자용 추천 시작 순서

  1. 설치 스크립트로 설치
  2. openclaw onboard --install-daemon 실행
  3. openclaw dashboard로 로컬 UI 접속
  4. openclaw agent --message "테스트"로 기본 응답 확인
  5. 그 다음 WhatsApp/Telegram 같은 채널을 하나씩 연결
  6. 마지막으로 openclaw doctor와 openclaw channels status --probe로 안정성 점검

10. 참고 자료

반응형

'AI' 카테고리의 다른 글

Paperclip 완전 가이드: 설치부터 Docker·API·어댑터·운영 전략까지 한눈에 보는 paperclipai/paperclip  (0) 2026.03.31
OpenClaw 플러그인 추천 10선: 생산성·보안·메모리 확장까지 실전 가이드  (1) 2026.03.18
OpenClaw 사용 사례 10가지: AI 개인 비서 자동화 실전 활용법 총정리  (0) 2026.03.18

'AI' Related Articles

티스토리툴바