OpenClaw 설치 가이드 (1편) — 로컬에서 실행하는 나만의 AI 비서

- 3월 25, 2026

OpenClaw란 무엇인가

OpenClaw는 자신의 서버(또는 PC)에서 직접 실행하는 자체 호스팅(Self-hosted) AI 게이트웨이다. Telegram, WhatsApp, Discord, Slack, iMessage 등 다양한 메신저 플랫폼을 단일 허브로 연결하고, 각 채널로 들어오는 메시지를 AI 에이전트가 처리해 응답한다.

클라우드 기반 AI 서비스와 가장 큰 차이는 모든 데이터가 내 머신에서만 처리된다는 점이다. API 키도, 대화 내용도, 에이전트의 메모리도 외부 서버로 전송되지 않는다. MIT 라이선스 오픈소스로 GitHub에 공개되어 있다.

어떤 일을 할 수 있나

OpenClaw 에이전트는 단순 Q&A를 넘어 실제 작업을 자율적으로 수행한다.

파일 시스템 읽기/쓰기 및 쉘 명령어 실행
Gmail, GitHub, Spotify, Obsidian 등 50개 이상 외부 서비스 연동
스케줄 기반 자동화 (크론 작업)
브라우저 제어 및 웹 스크래핑
대화 기반으로 에이전트 자체 스킬 작성·수정
지속적인 메모리 — 대화 내용을 기억하고 사용자 선호도를 학습

Telegram 봇을 통해 외출 중에도 서버에 명령을 보내고 결과를 받는 방식의 운용이 가능하다.

시스템 요구사항

설치 전에 아래 요건을 확인한다.

운영체제: macOS, Linux, Windows (네이티브 또는 WSL2)
Node.js: v24 권장, 최소 v22.16+ LTS — 인스톨러가 자동으로 처리하므로 미리 설치하지 않아도 됨
AI 모델 API 키: Anthropic, OpenAI, Google 중 하나 이상 (온보딩 과정에서 입력)
네트워크: 포트 18789가 로컬에서 열려 있어야 함 (기본값, 변경 가능)

Windows 사용자의 경우 네이티브 설치도 지원하지만, WSL2 환경을 강력히 권장한다. 안정성과 호환성이 훨씬 높다.

설치 방법 3가지

방법 1: 공식 인스톨러 스크립트 (권장)

가장 간단하고 권장되는 방법이다. 터미널 한 줄로 Node.js 설치부터 OpenClaw 설정까지 자동으로 완료된다.

macOS / Linux / WSL2:

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

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

스크립트 실행이 완료되면 자동으로 온보딩 마법사가 시작된다.

방법 2: npm으로 전역 설치

이미 Node.js가 설치된 환경이라면 npm으로 직접 설치할 수 있다.

npm install -g openclaw@latest
openclaw onboard --install-daemon

--install-daemon 옵션을 주면 시스템 재시작 시 OpenClaw가 자동으로 실행되는 데몬으로 등록된다.

방법 3: 소스에서 빌드 (개발자용)

최신 코드를 직접 사용하거나 커스터마이징이 필요한 경우 GitHub 레포에서 클론해 빌드한다. 의존성 관리에 pnpm을 사용한다.

npm install -g pnpm
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global

온보딩 마법사

인스톨러 스크립트를 사용했다면 자동으로 실행되지만, 수동 실행은 아래 명령어를 입력한다.

openclaw onboard

마법사는 약 2분 안에 아래 설정을 안내한다.

모델 프로바이더 선택: Anthropic / OpenAI / Google 중 선택
API 키 입력: 선택한 프로바이더의 API 키 입력
게이트웨이 설정: 포트, 인증 토큰 자동 생성
데몬 등록: 시스템 재시작 후 자동 실행 여부 선택

설치 확인

온보딩이 완료되면 아래 명령어로 정상 동작을 확인한다.

openclaw --version
openclaw doctor
openclaw gateway status

openclaw doctor는 설치 환경의 문제를 자동으로 진단한다. 정상 설치 시 브라우저에서 http://127.0.0.1:18789/에 접속하면 OpenClaw 웹 대시보드가 표시된다.

설치 디렉토리 구조

설치 후 OpenClaw는 홈 디렉토리에 ~/.openclaw/ 폴더를 생성한다. 주요 디렉토리와 파일의 역할은 다음과 같다.

openclaw.json — 핵심 설정 파일. 채널, 모델, 게이트웨이 옵션을 모두 여기서 관리
agents/ — 에이전트별 디렉토리. 프롬프트, 세션, 인증 정보 저장
workspace/ — 에이전트가 파일 작업을 수행하는 기본 작업 디렉토리
memory/ — 에이전트 장기 메모리 (SQLite 데이터베이스)
credentials/ — API 키 등 민감 정보 (암호화 저장)
logs/ — 게이트웨이 및 에이전트 로그
cron/ — 예약 작업 정의 파일

이 폴더는 기본적으로 소유자만 읽고 쓸 수 있도록 퍼미션이 설정된다(chmod 700).

PATH 문제 해결

설치 후 openclaw 명령어가 인식되지 않는 경우, npm 전역 바이너리 경로가 PATH에 포함되지 않은 것이다. 아래 줄을 ~/.bashrc 또는 ~/.zshrc에 추가하고 터미널을 재시작한다.

export PATH="$(npm prefix -g)/bin:$PATH"

다음 편 예고

2편에서는 설치 후 실제로 활용하기 위한 핵심 단계를 다룬다.

Telegram 봇 생성 및 OpenClaw 연동 전체 과정
openclaw.json 주요 설정 필드 심층 분석
AI 모델 프로바이더(Anthropic, OpenAI 등) API 키 설정 방법
접근 제어 — pairing, allowlist, open 모드 차이

이 블로그 검색

multibagger