OpenClaw 기본 가이드: 메신저로 굴리는 셀프호스팅 AI 비서

OpenClaw는 자기 기기나 VPS에서 직접 돌리는 셀프호스팅(self-hosting) 개인 AI 어시스턴트 게이트웨이다. 핵심 발상은 단순하다. 이미 쓰고 있는 메신저 채널을 그대로 입출력 창구로 삼아, 메시지를 보내면 AI가 응답하고 필요하면 도구를 실행한다. 별도의 전용 클라이언트를 새로 익힐 필요 없이 평소 쓰는 대화창에서 비서를 부린다는 점이 특징이다.

포지셔닝을 분명히 해 둘 필요가 있다. OpenClaw는 코딩 특화 도구가 아니라 메신저로 구동되는 범용 비서다. OpenHands, Cline, Devin 같은 코딩 에이전트와는 결이 다르다. 코드 작업도 시킬 수 있지만, 그것은 범용 능력의 한 갈래일 뿐이다.

제작자는 오스트리아의 Peter Steinberger이고, 마스코트는 우주 바닷가재 Molty다. 이름의 Open은 오픈소스를, Claw는 바닷가재의 집게발을 뜻한다. 라이선스는 MIT이며 Node.js와 TypeScript로 작성됐다. 실행 환경은 Node 24를 권장하고 22.19 이상이면 동작한다.

발표 이후 빠르게 퍼지면서 폭넓은 주목을 받았지만, 그만큼 보안 우려도 함께 제기됐다. 이 가이드는 설치와 구조를 먼저 다룬 뒤, 실제로 켜기 전에 반드시 읽어야 할 보안 항목을 가장 비중 있게 정리한다.

설치 방법은 두 가지다. npm 전역 설치 후 온보딩을 돌리거나, 원라인 스크립트를 쓴다.

# 방법 1: npm 전역 설치
npm install -g openclaw@latest
openclaw onboard --install-daemon

# 방법 2: 원라인 설치 (macOS / Linux)
curl -fsSL https://openclaw.ai/install.sh | bash

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

온보딩 위저드가 모델 프로바이더 선택, API키 입력, Gateway 구성을 차례로 안내한다. 설치가 끝나면 아래 명령으로 상태를 확인한다.

openclaw --version
openclaw doctor          # 환경 점검
openclaw gateway status  # 게이트웨이 데몬 상태

첫 메신저는 Telegram을 권장한다. BotFather에서 /newbot으로 봇토큰을 발급받아 설정에 넣고 페어링을 승인한다.

# 봇토큰을 config의 channels.telegram.botToken 또는 env로 주입
export TELEGRAM_BOT_TOKEN="<봇토큰>"

# 메신저에 표시된 코드로 페어링 승인
openclaw pairing approve telegram <CODE>

LLM은 모델에 종속되지 않는다. Anthropic, OpenAI, MiniMax, OpenRouter를 쓸 수 있다. Claude를 쓰려면 ANTHROPIC_API_KEY를 설정하고, 모델ID에 anthropic/ 프리픽스를 붙여 config의 agents.defaults.model.primary에 지정한다.

OpenClaw의 중심에는 단일 장기실행 Gateway 데몬이 있다. 기본 바인딩은 127.0.0.1:18789이고, 모든 메신저 연결과 세션, 라우팅의 단일 진실원천(single source of truth) 역할을 한다. 이 데몬은 운영체제 서비스로 등록된다. macOS는 launchd, Linux와 WSL2는 systemd, Windows는 Scheduled Task를 쓴다.

앱과 CLI, 웹UI 같은 컨트롤플레인 클라이언트와 노드는 WebSocket으로 데몬에 접속한다. 데몬은 들어오는 채널, 계정, 피어를 격리된 에이전트로 라우팅하고, 세션키별로 작업을 직렬화한다. 에이전트 한 번의 루프는 intake에서 시작해 context assembly, model inference, tool execution, streaming reply, persistence 순으로 흐른다. 지원 메신저는 약 23개로 WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, Matrix 등을 포함한다.

내부에는 Pi라는 미니멀 코딩 에이전트가 들어 있다. Mario Zechner가 만든 것으로, 도구가 Read, Write, Edit, Bash 단 4개이고 시스템 프롬프트가 매우 짧다. Pi의 철학은 자기확장이다. 확장을 설치해 주는 대신, 에이전트에게 스스로 확장하라고 요청하는 방식이다. OpenClaw는 이 Pi의 세션을 직접 임포트한 뒤 그 위에 메시징, 샌드박스 도구, 채널별 프롬프트, 멀티계정, 모델 전환을 얹는다.

기능을 늘리는 단위는 스킬이다. 스킬은 SKILL.md 한 파일과 보조 파일 폴더로 구성되며, SKILL.md의 YAML frontmatter에는 name과 description이 반드시 있어야 한다. 세션이 시작되면 적격 스킬이 컴팩트한 XML 블록으로 시스템 프롬프트에 주입되고, env키는 실행되는 동안에만 주입됐다가 끝나면 복원된다. 스킬은 CLI로 설치한다.

openclaw skills install <slug>

ClawHub는 공개 스킬 레지스트리다. 퍼블리시와 버전 관리, 검색을 지원하며 임베딩 벡터 검색을 제공한다. ClawHub 자체의 보안 이슈는 뒤의 보안 섹션에서 다룬다.

파일 도구는 권한 강도에 따라 네 가지로 나뉜다.

기본 동작을 정확히 알아야 한다. OpenClaw는 기본적으로 단일 운영자의 풀 OS 권한으로 실행되며, exec가 승인 프롬프트 없이 허용된다. 이것은 버그가 아니라 의도된 UX다. 공식 문서는 OpenClaw가 다수의 적대 사용자를 위한 보안 경계가 아니라고 명시한다. 즉 신뢰하는 한 사람이 자기 환경에서 쓰는 도구를 전제로 설계됐다.

통제 수단은 세 계층이고 전부 opt-in이다. 운영자가 직접 켜지 않으면 적용되지 않는다.

첫째, Sandbox다. agents.defaults.sandbox.mode를 off, non-main, all 중에서 고른다. 기본값은 off다. Docker 백엔드를 쓰면 기본적으로 네트워크가 없고 호스트 env를 상속하지 않는다. 둘째, Tool policy다. tools.allow와 tools.deny로 도구를 제어하며 deny가 항상 우선한다. 다만 이름 단위 필터라는 한계가 있다. exec를 허용한 상태에서 write나 edit를 막아도 셸을 통해 우회할 수 있다. 셋째, Elevated다. tools.elevated로 샌드박스 밖에서 exec를 돌린다.

HITL 승인은 ask:"always"로 켜고, 샌드박싱과 함께 운영자가 명시적으로 활성화해야 한다. 알려진 갭도 있다. GitHub 이슈 #12202에 따르면 모든 에이전트가 동일한 OS 사용자로 무제한 파일 접근 권한을 가지며, 에이전트별 경로 allowlist는 적용되지 않는다. 권한을 좁히려는 의도가 구조적으로 새어 나갈 수 있다는 뜻이다.

OpenClaw를 쓰기로 했다면 이 섹션이 가장 중요하다. 1차 벤더에 해당하는 Microsoft 보안 블로그는 OpenClaw를 지속 자격증명을 가진 신뢰불가 코드 실행으로 규정하고, 일반 워크스테이션에서 격리 없이 쓰기에 부적합하다고 평가했다. 자격증명이 살아 있는 상태에서 검증되지 않은 코드가 돌 수 있다는 점이 위험의 핵심이다.

실제로 두 갈래의 위협이 연구로 드러났다. 하나는 ClawHub 랭킹 조작이다. Silverfort 연구진은 인증과 레이트리밋이 없는 public mutation을 통해 다운로드 수를 조작할 수 있음을 보였다. PoC 악성 스킬이 수 분 내에 카테고리 1위에 오를 수 있었고, 이 문제는 2026-03-16 공개 후 24시간 안에 수정됐다. 다른 하나는 메신저 경유 프롬프트 인젝션이다. Imperva 연구진은 메시지 객체의 필드, 곧 연락처 이름이나 vCard, 위치 라벨에 심어 둔 지시가 LLM 프롬프트로 직렬화되면서 사용자 눈에 보이지 않게 코드가 실행될 수 있음을 보였다. 이 건은 v2026.4.23에서 수정됐다.

안전하게 쓰려면 격리가 출발점이다. 전용 VM이나 별도 기기에서 일회용으로만 돌리고, 최소권한과 단기 스코프드 토큰을 쓰며, 민감 데이터는 아예 가까이 두지 않는다. VM 안에서 다시 Docker로 한 겹 감싸는 구성이 권장된다.

# VM 내부에서 Docker로 한 번 더 격리
docker run \
  --user nobody \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  <image>
# Docker 소켓 마운트는 금지

게이트웨이 자체도 하드닝한다. 바인딩을 루프백으로 묶고 토큰 인증을 걸며, exec는 막고 승인 프롬프트를 항상 띄운다.

# config 하드닝 핵심
gateway.bind: "loopback"
tools.exec.security: "deny"
ask: "always"

# 심층 보안 점검
openclaw security audit --deep

서드파티 스킬은 신뢰불가 코드로 간주한다. 활성화하기 전에 반드시 코드를 직접 읽어 본다.

끝으로 Anthropic 관련 두 건은 보안 사고와 혼동하지 말아야 한다. 첫째, 2026-02-20 Anthropic이 ToS를 명확히 하면서 Claude Free, Pro, Max의 OAuth 토큰을 다른 제품이나 툴에 쓰는 것을 금지했다. 이는 경제성과 약관의 문제이며 트레이드마크 사안이 아니다(The Register 보도). 둘째, 2026-04-10 제작자 본인의 Claude 계정이 의심스러운 활동으로 일시 정지됐다가 수 시간 내에 복구됐다(TechCrunch). 둘 다 OpenClaw의 코드 취약점과는 별개의 일이다.

도구의 성격을 알면 판단이 쉬워진다. 아래는 facts에서 확인된 설계 전제를 정리한 비교다.

정리하면 OpenClaw는 신뢰하는 한 사람이 격리된 환경에서, 잃어도 괜찮은 권한과 토큰만 쥐여 주고 쓰는 도구다. 메신저로 비서를 부린다는 사용 경험은 매력적이지만, exec가 기본 허용이고 통제 수단이 전부 opt-in이라는 점을 받아들일 수 있을 때 비로소 실용적이다.

반대로 일상 작업 기기에 그냥 깔거나, 여러 사람이 공유하거나, 민감 자격증명이 상주하는 환경에 노출하는 구성은 피한다. 이런 조건이라면 설치 전에 격리 구조부터 먼저 갖추는 편이 안전하다.

이름과 사건의 흐름을 시간순으로 정리한다. 정확한 날짜가 확인된 항목만 명시하고, 불확실한 정량은 정성으로 서술한다.

트레이드마크 압박은 1월의 개명 사안으로, 이후의 보안 연구나 계정 정지와는 별개의 맥락임을 다시 짚어 둔다.