OpenClaw 설치 및 분석: 개인 AI 에이전트의 새로운 기준#

OpenClaw, 무엇이길래 이렇게 핫한가#

요즘 개발자 커뮤니티에서 OpenClaw를 모르는 사람을 찾기가 더 어려울 정도입니다. GitHub 스타가 30만 개를 넘겼고, 출시 첫 주에만 200만 명이 방문했습니다. X(Twitter), Discord, Reddit 할 것 없이 온통 OpenClaw 이야기입니다.

OpenClaw는 한마디로 내 컴퓨터에서 돌아가는 개인 AI 에이전트 플랫폼입니다. 원래 2025년 11월에 “ClawdBot” 이라는 이름의 주말 프로젝트로 시작했다가, 상표권 이슈를 거쳐 “Moltbot” 을 지나, 2026년 1월에 지금의 OpenClaw로 정착했습니다. 이름에 담긴 뜻은 단순합니다. “Claw” 는 프로젝트의 마스코트인 바닷가재(🦞)를 상징하고, “Open” 은 오픈소스와 커뮤니티 주도 개발을 의미합니다.

ChatGPT나 Claude 같은 클라우드 기반 AI와 결정적으로 다른 점은, OpenClaw가 사용자의 머신에서 직접 실행된다는 것입니다. 내 파일 시스템에 접근하고, 브라우저를 조작하고, 셸 명령을 실행하고, 심지어 사용자가 자고 있는 동안에도 예약된 작업을 수행합니다. 그러면서도 WhatsApp, Telegram, Discord, Slack 같은 기존 메신저를 통해 대화하듯 조작할 수 있습니다.

필자는 이 글에서 Docker 환경에 OpenClaw를 설치한 과정과 겪었던 문제들, 그리고 코드를 분석하며 파악한 핵심 구성요소와 주요 특징을 정리했습니다.

OpenClaw 대표 이미지

Docker 환경 설치 과정#

로컬 업무 환경의 리스크를 회피하기 위해, Docker 환경에 OpenClaw를 설치하고 Control UI 접속까지 완료하는 것을 목표로 진행했습니다.

기본 설치 명령#

git clone https://github.com/openclaw/openclaw.git
cd openclaw

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"

./docker-setup.sh

문제 1: 컨테이너 재시작 루프#

설치 과정에서 가장 먼저 부딪힌 문제는 게이트웨이 컨테이너가 재시작 루프에 빠지는 것이었습니다.

Gateway failed to start: Error: non-loopback Control UI requires gateway.controlUi.allowedOrigins

원인은 docker-setup.sh의 실행 순서에 있었습니다. onboard 명령이 실행되면 depends_on 설정 때문에 게이트웨이가 자동 시작되는데, 이 시점에서 gateway.controlUi.allowedOrigins가 아직 미설정 상태라 게이트웨이 시작이 실패합니다. restart: unless-stopped 정책이 걸려 있으니 재시작 루프에 빠지고, 이후 설정 명령들도 줄줄이 실패하는 구조였습니다.

컨테이너를 중지한 뒤 ~/.openclaw/openclaw.json에 직접 두 가지를 수정하여 해결했습니다.

"gateway": {
  "bind": "lan",
  "controlUi": {
    "allowedOrigins": ["http://127.0.0.1:18789"]
  }
}

문제 2: Control UI 접속 시 “pairing required” 에러#

게이트웨이가 정상 기동된 후 브라우저에서 Control UI에 접속하면 “pairing required” 라는 메시지가 나타났습니다.

Control UI는 브라우저에서 디바이스 키(공개키 / 개인키)를 생성하여 게이트웨이에 페어링하는 과정이 필요합니다. 그런데 Docker 환경에서는 HTTP 컨텍스트라 브라우저의 SubtleCrypto API 제약으로 자동 페어링이 안 되고, Docker NAT를 거치면서 게이트웨이가 연결 source IP를 로컬로 인식하지 못하는 문제가 있었습니다.

openclaw.json에 dangerouslyDisableDeviceAuth: true를 추가하여 해결했습니다.

"gateway": {
  "controlUi": {
    "allowedOrigins": ["http://127.0.0.1:18789"],
    "dangerouslyDisableDeviceAuth": true
  }
}

이 설정은 디바이스 인증을 비활성화하는 옵션이라 보안 경고가 출력되지만, Docker 로컬 환경에서는 이미 게이트웨이 토큰 인증이 있으므로 실용적으로 문제없습니다.

최종 결과#

항목상태
Docker 게이트웨이 컨테이너정상 실행 중
Telegram 봇 연결연결됨
Control UI (http://127.0.0.1:18789)접속 가능

핵심 구성요소#

코드를 분석하며 파악한 OpenClaw의 핵심 구성요소를 정리합니다.

Gateway (게이트웨이)#

시스템의 중심으로, 모든 메시지의 수신 · 발신과 라우팅을 담당합니다. Node.js 기반 서버로 동작하며, 웹 / 브라우저용 HTTP 경로는 express로, 실시간 양방향 통신은 ws(WebSocket)로 처리합니다. 채널에서 들어온 이벤트를 공통 파이프라인으로 넘겨 세션 관리, 라우팅, 응답 전달을 일관되게 수행합니다.

Channels (채널 커넥터)#

Telegram, Discord, WhatsApp 등 외부 메신저와 OpenClaw를 연결하는 어댑터입니다. 채널마다 독립적인 어댑터로 구현되어 있고, extensions/* 플러그인과 src/channels/plugins/* 런타임을 통해 새로운 채널을 추가할 수 있습니다.

Agent Runtime (에이전트 실행 엔진)#

사용자의 요청을 실제 LLM 호출로 실행하고 응답을 생성합니다. 핵심 라이브러리로 @mariozechner/pi-ai, @mariozechner/pi-agent-core, @mariozechner/pi-coding-agent를 사용합니다. 각각 LLM 스트리밍 및 호출 추상화, 에이전트 이벤트와 메시지 타입 정의, 세션과 도구 실행 관리를 담당합니다.

Agent Loop (에이전트 루프)#

에이전트가 “생각하고, 도구를 쓰고, 다시 생각하는” 반복 과정입니다. 한 번의 LLM 호출로 끝나지 않고, LLM이 도구 호출(tool call)을 요청하면 해당 도구를 실행한 뒤 결과를 다시 LLM에 전달하고, 최종 텍스트 응답이 나올 때까지 반복합니다. 무한 루프 방지를 위해 최대 반복 횟수 제한(MAX_RUN_LOOP_ITERATIONS)과 도구 루프 감지(detectToolCallLoop) 로직이 적용되어 있습니다.

Session & Routing (세션 / 라우팅)#

“누가, 어느 채널에서, 어느 대화방에서 보냈는지"를 기준으로 올바른 대화 맥락에 연결합니다. sessionKey, account, thread / group 정보를 조합해 메시지 경로를 결정하고, 채널-세션 바인딩을 통해 멀티채널 환경에서도 대화 맥락이 뒤섞이지 않도록 보장합니다.

Web UI / 앱 인터페이스#

사용자가 시스템 상태를 확인하고 설정을 변경하는 관리 화면입니다. 웹 UI는 ui/ 디렉터리에서 Lit + Vite 기반으로 구성되어 있고, macOS / iOS / Android 앱은 별도 디렉터리(apps/*)에 분리되어 있으며 동일한 게이트웨이에 연결됩니다.

Extension / Plugin (확장)#

채널, 도구, 메모리, 인증 등의 기능을 필요에 따라 추가할 수 있는 구조입니다. openclaw.plugin.json 매니페스트로 채널 / 프로바이더 / 기능 종류를 선언하고 런타임에 등록합니다. 코어 코드를 크게 수정하지 않고도 기능을 확장할 수 있습니다.

실제 동작 흐름#

전체 구성요소가 어떻게 협력하는지, 메시지가 들어왔을 때의 동작 흐름을 정리하면 다음과 같습니다.

  1. 사용자가 메신저로 메시지를 보냅니다. 채널 모니터가 수신하고, 중복 방지 · 접근 권한 · 미디어 전처리 등 1차 검증을 수행합니다.
  2. 수신 메시지를 표준 컨텍스트로 변환합니다. 채널마다 다른 원본 이벤트 형식을 공통 MsgContext 형태로 정규화합니다.
  3. 세션과 에이전트 라우팅을 결정합니다. 채널, accountId, group / thread, sender 정보를 기반으로 sessionKey와 담당 에이전트를 확정합니다.
  4. 에이전트 루프가 시작됩니다. LLM 호출과 도구 실행을 반복하며, 최종 텍스트 답변이 나올 때까지 이 과정을 이어갑니다.
  5. 응답을 채널에 맞는 형식으로 변환해 전송합니다. 길이 제한, 스레드, 포맷 규칙에 맞춰 가공한 뒤 사용자에게 보냅니다.
  6. 결과를 저장하고 다음 요청에 대비합니다. 세션 상태, 사용량, 라우팅 메타데이터를 저장하여 대화 맥락을 이어갑니다.

주요 특징#

멀티에이전트 협업#

OpenClaw는 하나의 에이전트만 쓰는 것이 아니라, 역할이 다른 여러 에이전트를 만들어 서로 협력하게 할 수 있습니다.

  • 역할별 에이전트 구성: 설정 파일(~/.openclaw/openclaw.json)의 agents.list 배열에 에이전트를 추가하고, 각각에 “리서처”, “코더”, “작성자” 같은 역할을 부여할 수 있습니다. 에이전트마다 사용할 LLM 모델, 사용 가능한 도구, 작업 디렉터리 등을 개별적으로 지정합니다.
  • 에이전트 간 대화(A2A): sessions_send 도구를 통해 에이전트끼리 질문을 주고받을 수 있습니다. 최대 5턴까지 번갈아 응답하는 핑퐁 방식이 지원되며, 대화 턴 수는 maxPingPongTurns로 조절합니다.
  • 보조 에이전트 동적 생성: 에이전트가 작업 중 “이 부분은 전문가가 필요하다"고 판단하면, sessions_spawn 도구로 서브에이전트를 동적으로 생성할 수 있습니다. 일회성 모드(run)와 지속형 모드(session)를 선택할 수 있습니다.
  • 안전장치: 에이전트 간 통신은 기본적으로 비활성화되어 있고, tools.agentToAgent.enabled로 명시적 허용이 필요합니다. 중첩 생성 깊이(maxSpawnDepth)와 세션 접근 범위(tools.sessions.visibility)도 제한할 수 있습니다.

작업 스케줄링 (Heartbeat + Cron)#

사용자가 직접 메시지를 보내지 않아도, 에이전트가 주기적으로 일을 처리하도록 예약할 수 있습니다.

  • Heartbeat(심장박동): 에이전트가 일정 간격(기본 30분)으로 스스로 깨어나서, 확인할 것이 있는지 점검합니다. 워크스페이스에 HEARTBEAT.md 체크리스트를 작성해 두면, 에이전트가 매 주기마다 이 파일을 읽고 항목별로 처리합니다. 특별히 알릴 것이 없으면 HEARTBEAT_OK를 반환하고 사용자에게 메시지를 보내지 않습니다.
  • Cron(정시 예약): “매일 아침 9시”, “매주 월요일” 같이 정확한 시각에 특정 작업을 실행합니다. 메인 대화와 분리된 독립 세션에서 실행되어 대화 기록이 오염되지 않습니다. CLI로 openclaw cron add --name "아침 브리핑" --cron "0 9 * * *" 형태로 등록합니다.
  • 조합 활용: Heartbeat는 30분마다 이메일 · 캘린더 · 알림을 한꺼번에 점검하고, Cron은 정해진 시각의 독립 작업을 맡습니다. 반복 점검은 Heartbeat 한 번으로 묶어 API 비용을 아끼고, 정시 작업은 Cron으로 정확하게 처리하는 구조입니다.

활용 사례#

OpenClaw 공식 문서와 커뮤니티 쇼케이스에서 확인할 수 있는 대표적인 활용 사례들입니다.

일상 업무 자동화#

  • 이메일 · 캘린더 · 뉴스를 종합한 아침 브리핑을 매일 받기
  • 리서치와 초안 작성: 자료 조사, 요약, 이메일이나 문서 초안을 대신 작성하게 하기
  • Cron / Heartbeat로 체크리스트, 알림, 팔로업 자동화

브라우저 자동화#

  • 온라인 장보기: 주간 식단 → 장바구니 담기 → 배송 예약 → 주문 확인까지 브라우저로 자동 처리
  • 웹 양식 채우기, 데이터 수집, 반복적인 웹 작업 위임
  • TradingView 같은 사이트에 로그인하여 차트 캡처 및 기술 분석 수행

개발 및 코딩#

  • Telegram으로 대화하면서 웹사이트 전체를 재구축 (Notion → Astro 마이그레이션, DNS 변경까지 노트북을 열지 않고 완료한 사례)
  • iOS 앱을 Telegram 채팅만으로 개발하고 TestFlight에 배포
  • PR 리뷰: 코드 변경 → PR 생성 → OpenClaw가 diff를 검토하고 Telegram으로 리뷰 결과 전달

스마트홈과 IoT#

  • Home Assistant와 연동해 자연어로 가전 제어
  • 로봇 청소기, 공기청정기 등을 대화로 조작
  • 지붕 카메라로 하늘이 예쁠 때 자동 촬영

멀티에이전트 오케스트레이션#

  • 14개 이상의 에이전트를 하나의 게이트웨이에서 운영하며, Opus 오케스트레이터가 Codex 워커에게 작업을 위임하는 대규모 구성 사례
  • 역할별 에이전트(리서처, 코더, 작성자)를 나눠 각자 전문 분야에서 병렬 작업

건강 · 생활#

  • Oura 링 데이터와 캘린더, 운동 일정을 통합한 개인 건강 어시스턴트
  • 학교 급식 예약 자동화
  • 와인 셀러 관리: CSV 데이터를 기반으로 스킬을 자동 생성하여 와인 재고 관리

크로스 디바이스 협업#

  • 휴대폰에서 Telegram / WhatsApp으로 작업을 지시하고, VPS에서 게이트웨이가 실행한 뒤, 결과를 다시 메신저로 돌려받기
  • Mac, Linux, VPS 등 원하는 곳에서 게이트웨이를 띄우고 어디서든 접근

마치며#

OpenClaw는 단순히 “또 하나의 AI 챗봇"이 아닙니다. 항상 켜진 실행 주체, 실제 도구 사용 능력, 지속 메모리, 멀티에이전트 협업까지 갖춘 개인 AI 에이전트 플랫폼의 새로운 기준이라 할 수 있습니다. 특히 오픈소스로 공개되어 있어 누구나 자신의 환경에 맞게 커스터마이징할 수 있다는 점이 매력적입니다.

OpenClaw가 처음 나와서 사람들이 열광할 때, 오히려 필자는 개인 환경을 서버에 띄워놓고 메신저로 통신한다는 점 외에 뭐가 그렇게 특별할까 싶었습니다. 하지만 실제로 사용해 본 사람들의 다양한 활용 사례를 접하면서 관심이 생겼고, OpenClaw의 에이전트 동작의 기반이 되는 @mariozechner/pi-ai, @mariozechner/pi-agent-core, @mariozechner/pi-coding-agent 라이브러리들에 대해 살펴보면서 그 관심이 더 깊어졌습니다. 결국 이를 기반으로 Ted Factory의 자동화 시스템 일부를 구현하기로 결정했습니다.