OpenClaw 입문: 메신저 한 줄로 로컬 LLM 에이전트를 자체 호스팅하는 법

AI 에이전트를 직접 운영하려면 늘 세 가지 장벽이 따라왔습니다. 외부 API 비용, 데이터가 외부 서버에 저장되는 프라이버시 위험, 그리고 에이전트 전용 UI를 별도로 구축해야 하는 번거로움입니다. OpenClaw는 이 세 가지를 한 번에 해결합니다. 익숙한 메신저(Telegram, WhatsApp 등)에 메시지를 한 줄 보내는 것만으로, 로컬에서 실행 중인 LLM이 CSV를 분석하고, 캘린더 일정을 등록하고, 서버 상태를 점검해 결과를 돌려줍니다.

2026년 3월 기준 GitHub 스타 247,000개를 돌파하며 오픈소스 AI 에이전트 분야에서 가장 빠른 성장세를 기록 중인 OpenClaw는, 2025년 11월 오스트리아 개발자 Peter Steinberger가 Clawdbot이라는 이름으로 처음 공개한 뒤 Moltbot을 거쳐 2026년 1월 현재의 이름을 갖게 되었습니다. 폭발적인 성장의 배경에는 단순한 철학이 있습니다. 개발자가 매일 쓰는 메신저를 그대로 에이전트 인터페이스로 삼고, 실행은 Docker 컨테이너 안에 격리해 호스트 시스템을 보호한다는 것입니다.

이 글은 백엔드·풀스택 개발자 또는 DevOps 경험이 있는 분들을 대상으로, OpenClaw의 동작 원리부터 Skills 시스템, 실전 파이프라인 구성, 보안 주의사항까지 폭넓게 살펴봅니다. 이 글을 다 읽고 나면 OpenClaw를 로컬에서 직접 설치하고 첫 번째 자율 에이전트를 구동하는 데 필요한 모든 개념을 갖추게 됩니다.

핵심 개념

OpenClaw의 4가지 동작 축

OpenClaw는 네 가지 핵심 요소가 맞물려 동작합니다.

구성 요소	역할
LLM 백엔드	Claude, GPT-4o, DeepSeek, Gemini 또는 Ollama·LM Studio 같은 로컬 모델
메시징 채널	WhatsApp, Telegram, Signal, Discord, Slack 등 22개+ 플랫폼 (2026년 3월 기준)
Docker 샌드박스	셸 명령·파일 작업을 격리된 컨테이너에서 실행해 호스트 보호
Skills 시스템	`SKILL.md` 파일 기반의 플러그인 아키텍처로 기능 확장

Docker 샌드박스란? 에이전트가 실행하는 모든 명령이 호스트 운영체제와 분리된 컨테이너 안에서만 이루어집니다. 에이전트가 오작동하더라도 실제 서버나 PC에는 영향을 주지 않습니다.

OpenAI-compatible API란? OpenAI가 정의한 /v1/chat/completions 형식의 HTTP API 규격입니다. Ollama, LM Studio, vLLM 등 다양한 로컬·클라우드 LLM 서버가 이 규격을 구현하고 있어, OpenClaw는 base_url만 바꾸면 어떤 모델이든 연결할 수 있습니다.

LLM은 어떻게 어떤 스킬을 호출할지 결정하나요?

OpenClaw의 핵심 메커니즘을 이해하면 Skills 시스템의 동작 방식이 훨씬 명확해집니다. 에이전트가 사용자 메시지를 받으면 다음 과정이 이루어집니다.

SKILL.md 수집: OpenClaw는 워크스페이스·글로벌·번들 스킬 디렉터리에서 모든 SKILL.md를 읽어, LLM에 전달할 시스템 프롬프트에 삽입합니다.
Tool Use 호출: LLM은 삽입된 스킬 설명(트리거 조건, 파라미터 스키마)을 참조해 사용자 의도와 가장 맞는 스킬을 판단하고, Function Calling / Tool Use 형식으로 호출 명령을 생성합니다.
Skills 디스패처 실행: OpenClaw의 Skills 디스패처가 해당 스킬 디렉터리에서 실행 파일(handler.sh, analyze.py 등)을 찾아 Docker 샌드박스 안에서 실행합니다.
결과 반환: 실행 결과(텍스트, 파일)가 메시징 채널로 전달됩니다.

즉, SKILL.md는 LLM이 읽는 "설명서"이고, 같은 디렉터리의 실행 파일(handler.sh 또는 *.py, *.js)이 실제 동작을 담당합니다. 실행 파일은 SKILL.md 안의 Entrypoint 필드로 명시하거나, 관례적으로 handler.sh가 기본 진입점으로 사용됩니다.

Skills 시스템: 에이전트 기능 확장 구조

OpenClaw의 확장성을 담당하는 핵심 메커니즘이 Skills입니다.

my-workspace/
├── skills/
│   ├── weather/
│   │   ├── SKILL.md       # LLM이 읽는 스킬 설명 및 트리거 조건
│   │   └── handler.sh     # 실제 실행 로직 (진입점)
│   └── calendar/
│       ├── SKILL.md
│       └── gcal.py
└── openclaw.config.yml

스킬은 우선순위 계층으로 관리됩니다.

워크스페이스 스킬 — 현재 프로젝트에만 적용되는 커스텀 스킬 (최우선)
글로벌 스킬 — 모든 워크스페이스에 공통으로 적용
번들 스킬 — OpenClaw가 기본으로 제공하는 내장 스킬

공식 스킬 마켓플레이스인 ClawHub(clawhub.ai)에는 2026년 3월 기준 700개 이상의 커뮤니티 스킬이 등록되어 있습니다.

전체 아키텍처 흐름

css

[사용자 메신저]
      │  "내일 오전 10시 회의 잡아줘"
      ▼
[OpenClaw 메시징 어댑터]  ← Telegram / WhatsApp / Slack ...
      │
      ▼
[LLM 추론 엔진]           ← Claude / GPT-4o / Ollama ...
      │  (SKILL.md를 시스템 프롬프트에 삽입 → Tool Use로 스킬 선택)
      │  "calendar.create 스킬 호출"
      ▼
[Skills 디스패처]         ← 해당 스킬 디렉터리의 실행 파일 탐색
      │
      ▼
[Docker 샌드박스]         ← 실제 명령 실행 (gcal API 호출 등)
      │
      ▼
[응답 반환 → 메신저]

실전 적용

핵심 개념을 이해했으니, 실제 파이프라인을 구성하는 세 가지 예시를 살펴보겠습니다.

예시 1: Ollama + Telegram으로 로컬 데이터 분석 봇 만들기

하드웨어 요구사항: llama3.2 모델(3B 파라미터)은 최소 8GB RAM이 필요하며, GPU 없이 CPU 추론도 가능합니다. 8B 이상의 모델을 사용하려면 16GB RAM 이상 환경을 권장합니다.

클라우드 API 비용 없이 로컬 LLM만으로 CSV 데이터를 분석하는 파이프라인입니다.

먼저 환경 변수를 .env 파일에 선언합니다. 설정 파일에 키를 직접 입력하면 버전 관리에 노출될 수 있으므로, 반드시 이 방법을 활용하는 것을 권장합니다.

# .env (프로젝트 루트 — .gitignore에 추가 필수)
TELEGRAM_BOT_TOKEN=your_bot_token_here

그다음, 메인 설정 파일을 작성합니다.

yaml

# openclaw.config.yml
llm:
  provider: ollama
  model: llama3.2
  base_url: http://localhost:11434/v1
 
channels:
  - type: telegram
    token: "${TELEGRAM_BOT_TOKEN}"   # .env에서 자동 로드
 
sandbox:
  engine: docker
  image: openclaw/sandbox:latest
  volumes:
    - ./output:/output               # 분석 결과 파일 저장 경로 마운트
 
skills:
  - path: ./skills/data-analyst

스킬 설명 파일을 만듭니다.

bash

<!-- skills/data-analyst/SKILL.md -->
# Data Analyst Skill
 
## Description
CSV 파일을 받아 pandas로 분석하고 요약 및 시각화 결과를 반환합니다.
 
## Trigger
사용자가 CSV 파일을 업로드하거나 "분석해줘", "요약해줘" 같은 요청을 보낼 때 활성화됩니다.
 
## Entrypoint
analyze.py
 
## Usage
- 파일 첨부 후 "이 데이터 분석해줘" 메시지 전송
- "컬럼별 통계 알려줘", "이상치 찾아줘" 등의 자연어 명령 지원

실제 분석 로직을 작성합니다.

python

# skills/data-analyst/analyze.py
import pandas as pd
import matplotlib.pyplot as plt
import sys, json
 
def analyze(filepath: str) -> dict:
    df = pd.read_csv(filepath)
    summary = {
        "shape": df.shape,
        "columns": list(df.columns),
        "stats": json.loads(df.describe().to_json()),
        "nulls": df.isnull().sum().to_dict(),
    }
    # /output 디렉터리는 openclaw.config.yml의 volumes 설정으로
    # 호스트의 ./output 디렉터리와 마운트됩니다.
    # 이 경로에 저장된 파일은 OpenClaw가 자동으로 메신저로 전송합니다.
    df.hist(figsize=(10, 8))
    plt.tight_layout()
    plt.savefig("/output/histogram.png")
    return summary
 
if __name__ == "__main__":
    result = analyze(sys.argv[1])
    print(json.dumps(result, ensure_ascii=False, indent=2))

마지막으로 Docker Compose 파일과 실행 명령입니다.

bash

# docker-compose.yml
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    env_file: .env
    volumes:
      - ./openclaw.config.yml:/app/openclaw.config.yml:ro
      - ./skills:/app/skills:ro
      - ./output:/output
    ports:
      - "3000:3000"
    restart: unless-stopped

# 실행
docker compose up -d
 
# 로그 확인
docker compose logs -f openclaw

설정 항목	역할
`llm.provider: ollama`	외부 API 대신 로컬 Ollama 서버 사용
`channels.type: telegram`	Telegram Bot API를 메시징 인터페이스로 연결
`sandbox.volumes`	`/output`을 호스트와 공유해 분석 결과 파일을 메신저로 전달
`SKILL.md Entrypoint`	스킬 실행 시 호출되는 파일(`analyze.py`) 명시
`${TELEGRAM_BOT_TOKEN}`	`.env`에서 로드되는 환경 변수 — 설정 파일에 직접 입력하지 않습니다

예시 2: Cron 기반 정기 보고 에이전트

매일 오전 8시에 날씨·뉴스·서버 상태를 자동으로 WhatsApp으로 보고하는 에이전트입니다.

# .env
WHATSAPP_PHONE_NUMBER=+821012345678

yaml

# openclaw.config.yml (발췌)
channels:
  - type: whatsapp
    phone: "${WHATSAPP_PHONE_NUMBER}"
 
wakeups:
  - name: morning-report
    cron: "0 8 * * *"          # 매일 오전 8시
    message: |
      오늘의 모닝 리포트를 준비해줘:
      1. 서울 날씨 확인
      2. 기술 뉴스 상위 3개 요약
      3. 서버 CPU/메모리 상태 점검
    channel: whatsapp

wakeups란? OpenClaw의 Cron 트리거 기능입니다. 외부 스케줄러(crontab, Airflow 등) 없이 YAML 설정만으로 정기 자동 실행 에이전트를 만들 수 있습니다.

주의: wakeups 설정 후에는 에이전트가 정기적으로 외부 API를 호출하거나 파일을 수정할 수 있습니다. 첫 wakeup은 날씨 조회처럼 읽기 전용 스킬부터 시작하고, docker compose logs -f openclaw로 행동을 충분히 확인한 뒤 쓰기 권한이 있는 스킬을 추가하는 방식을 권장합니다.

예시 3: 브라우저 자동화 — 웹 스크래핑 챗봇

OpenClaw 전용 Chromium 노드를 연결하면 채팅 명령만으로 웹 자동화가 가능합니다.

yaml

# openclaw.config.yml (발췌)
nodes:
  - type: browser
    engine: chromium
    headless: true             # Docker 환경에는 디스플레이가 없으므로 필수
 
skills:
  - path: ./skills/web-scraper

headless: true란? 브라우저를 화면(GUI) 없이 백그라운드에서 실행하는 모드입니다. Docker 컨테이너에는 디스플레이가 없으므로, 브라우저 자동화를 서버 환경에서 사용할 때는 반드시 이 옵션을 활성화해야 합니다.

스킬 설명 파일을 만듭니다.

html

<!-- skills/web-scraper/SKILL.md -->
# Web Scraper Skill
 
## Description
지정된 URL의 웹 페이지에서 콘텐츠를 스크래핑합니다.
 
## Trigger
사용자가 URL을 제공하며 "기사 제목 가져와줘", "스크래핑해줘" 같은 요청을 보낼 때 활성화됩니다.
 
## Entrypoint
scrape.py

실제 스크래핑 로직을 작성합니다.

python

# skills/web-scraper/scrape.py
import sys
import json
from playwright.sync_api import sync_playwright
 
def scrape(url: str, limit: int = 5) -> list[dict]:
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()
        page.goto(url)
        items = page.query_selector_all(".athing .titleline")
        results = []
        for item in items[:limit]:
            anchor = item.query_selector("a")
            if anchor:
                results.append({
                    "title": anchor.inner_text(),
                    "url": anchor.get_attribute("href"),
                })
        browser.close()
    return results
 
if __name__ == "__main__":
    url = sys.argv[1]
    limit = int(sys.argv[2]) if len(sys.argv) > 2 else 5
    result = scrape(url, limit)
    print(json.dumps(result, ensure_ascii=False, indent=2))

html

<!-- 사용 예시 — Telegram 채팅창 -->
사용자: https://news.ycombinator.com 상위 5개 기사 제목 가져와줘
 
에이전트: 잠시만요, 스크래핑 중입니다...
         1. [제목 1] — 링크
         2. [제목 2] — 링크
         3. [제목 3] — 링크
         4. [제목 4] — 링크
         5. [제목 5] — 링크

장단점 분석

장점

항목	내용	활용 포인트
완전한 오픈소스	MIT 라이선스, 100% 자체 호스팅 가능	내부 데이터를 외부 SaaS에 보내지 않아도 됩니다
모델 무관(Model-agnostic)	OpenAI-compatible API를 노출하는 모든 LLM 연결 가능	비용·프라이버시 균형을 직접 조정할 수 있습니다
프라이버시 보장	데이터가 외부 SaaS 서버에 저장되지 않음	민감한 사내 데이터 처리에 적합합니다
풍부한 생태계	ClawHub의 700개+ 스킬, 22개+ 메시징 채널 (2026년 3월 기준)	직접 개발 없이 기능을 빠르게 확장할 수 있습니다
Docker 격리	에이전트 오작동 시 호스트 시스템 보호	실험적인 스킬도 안전하게 테스트할 수 있습니다
친숙한 UX	별도 앱 설치 없이 기존 메신저로 에이전트 제어	팀원이 새 도구를 배울 필요가 없습니다

단점 및 주의사항

항목	내용	대응 방안
거대한 코드베이스	430,000줄+ 코드, 넓은 공격 표면	NanoClaw 또는 ZeroClaw 같은 경량 포크 검토
자격증명 노출 구조	프로세스 수준 크리덴셜 격리 없음	최소 권한 API 키 사용, Vault 등 비밀 관리 도구 연동
장기 메모리 부재	세션이 끊기면 사용자 선호 기억 불가	memU 같은 장기 메모리 특화 에이전트와 조합
자율 행동 리스크	잘못 구성 시 자동 구매·스팸 발송 사례 보고	민감한 스킬은 확인 단계(confirm step) 추가
자체 호스팅 부담	Docker 환경 구성, API 키 관리 등 초기 설정 필요	DigitalOcean 공식 튜토리얼 참고 권장

operator-trust 모델이란? OpenClaw에서 에이전트(LLM)가 연결된 도구와 서비스에 광범위한 접근 권한을 갖는 신뢰 모델입니다. 편리한 반면, 스킬 설정을 잘못했을 때 의도치 않은 작업이 실행될 수 있으므로 권한 범위를 신중하게 설정하는 것이 중요합니다.

실무에서 가장 흔한 실수

API 키를 openclaw.config.yml에 직접 하드코딩하는 경우 — 설정 파일이 버전 관리에 올라가면 키가 노출될 수 있습니다. 반드시 .env 파일에 선언하고 ${VAR_NAME} 방식으로 참조하는 것을 권장합니다. .env는 .gitignore에 추가하는 것도 잊지 않는 것이 좋습니다.
wakeups 설정 후 에이전트의 자율 권한 범위를 확인하지 않는 경우 — 정기 실행 에이전트가 예상치 못한 외부 API를 호출하거나 파일을 수정하는 상황이 발생할 수 있습니다. 처음에는 읽기 전용 스킬(날씨 조회, RSS 요약 등)부터 시작하고, 에이전트 로그로 행동을 충분히 확인한 뒤 쓰기 권한 스킬을 추가하는 방식을 권장합니다.
Docker 없이 직접 실행하려는 경우 — 샌드박스 격리를 우회하면 에이전트 명령이 호스트 파일 시스템에 직접 접근하게 됩니다. OpenClaw의 보안 모델은 Docker 격리를 전제로 설계되어 있으므로, 프로덕션 환경에서는 반드시 Docker 환경에서 운영하는 것을 권장합니다.

마치며

OpenClaw는 메신저·로컬 LLM·Docker 샌드박스를 Skills로 연결한 자체 호스팅 AI 에이전트 플랫폼입니다. 외부 API 비용과 프라이버시 걱정 없이, 개인 개발자도 강력한 자율 에이전트를 구축할 수 있습니다.

지금 바로 시작해볼 수 있는 3단계입니다.

Docker와 Ollama를 먼저 설치합니다. Ollama 공식 사이트(ollama.com)에서 설치 후 ollama pull llama3.2 명령어로 모델을 받아두면 로컬 LLM 환경이 준비됩니다.
OpenClaw 공식 저장소를 클론하고 기본 설정 파일을 만듭니다. git clone https://github.com/openclaw/openclaw 후 openclaw.config.yml에 Telegram 봇 토큰과 Ollama 연결 설정을 입력하면 됩니다.
ClawHub(clawhub.ai)에서 관심 있는 스킬을 하나 골라 워크스페이스에 추가해봅니다. Telegram 봇이 첫 응답을 반환하는 시점이 입문 단계의 성공 마일스톤입니다. 이후 날씨 조회나 RSS 뉴스 요약 같은 간단한 스킬을 하나씩 추가해 나가면 Skills 시스템의 동작 방식을 자연스럽게 체감할 수 있습니다.

다음 글: OpenClaw 보안 심화 — 자격증명 격리, 최소 권한 스킬 설계, NanoClaw·ZeroClaw와의 비교로 프로덕션 환경에서 안전하게 운영하는 방법

참고 자료

[공식] OpenClaw GitHub | github.com/openclaw
[공식] OpenClaw 공식 문서 | docs.openclaw.ai
[공식] OpenClaw Skills 문서 | docs.openclaw.ai/tools/skills
[튜토리얼] Using OpenClaw with Ollama: Building a Local Data Analyst | DataCamp
[튜토리얼] How to Run OpenClaw with DigitalOcean | DigitalOcean
[입문] What Is OpenClaw? Complete Guide | Milvus Blog
[입문] OpenClaw Explained: The Free AI Agent Tool Going Viral | KDnuggets
[심화] OpenClaw security: architecture and hardening guide | Nebius
[심화] 6 OpenClaw Competitors That Are Gaining Ground in 2026 | emergent.sh
[심화] Unleashing OpenClaw: The Ultimate Guide | DEV Community

OpenClaw

OpenClaw 입문: 메신저 한 줄로 로컬 LLM 에이전트를 자체 호스팅하는 법

핵심 개념

OpenClaw의 4가지 동작 축

OpenClaw는 네 가지 핵심 요소가 맞물려 동작합니다.

구성 요소	역할
LLM 백엔드	Claude, GPT-4o, DeepSeek, Gemini 또는 Ollama·LM Studio 같은 로컬 모델
메시징 채널	WhatsApp, Telegram, Signal, Discord, Slack 등 22개+ 플랫폼 (2026년 3월 기준)
Docker 샌드박스	셸 명령·파일 작업을 격리된 컨테이너에서 실행해 호스트 보호
Skills 시스템	`SKILL.md` 파일 기반의 플러그인 아키텍처로 기능 확장

Docker 샌드박스란? 에이전트가 실행하는 모든 명령이 호스트 운영체제와 분리된 컨테이너 안에서만 이루어집니다. 에이전트가 오작동하더라도 실제 서버나 PC에는 영향을 주지 않습니다.

OpenAI-compatible API란? OpenAI가 정의한 /v1/chat/completions 형식의 HTTP API 규격입니다. Ollama, LM Studio, vLLM 등 다양한 로컬·클라우드 LLM 서버가 이 규격을 구현하고 있어, OpenClaw는 base_url만 바꾸면 어떤 모델이든 연결할 수 있습니다.

LLM은 어떻게 어떤 스킬을 호출할지 결정하나요?

OpenClaw의 핵심 메커니즘을 이해하면 Skills 시스템의 동작 방식이 훨씬 명확해집니다. 에이전트가 사용자 메시지를 받으면 다음 과정이 이루어집니다.

SKILL.md 수집: OpenClaw는 워크스페이스·글로벌·번들 스킬 디렉터리에서 모든 SKILL.md를 읽어, LLM에 전달할 시스템 프롬프트에 삽입합니다.
Tool Use 호출: LLM은 삽입된 스킬 설명(트리거 조건, 파라미터 스키마)을 참조해 사용자 의도와 가장 맞는 스킬을 판단하고, Function Calling / Tool Use 형식으로 호출 명령을 생성합니다.
Skills 디스패처 실행: OpenClaw의 Skills 디스패처가 해당 스킬 디렉터리에서 실행 파일(handler.sh, analyze.py 등)을 찾아 Docker 샌드박스 안에서 실행합니다.
결과 반환: 실행 결과(텍스트, 파일)가 메시징 채널로 전달됩니다.

Skills 시스템: 에이전트 기능 확장 구조

OpenClaw의 확장성을 담당하는 핵심 메커니즘이 Skills입니다.

my-workspace/
├── skills/
│   ├── weather/
│   │   ├── SKILL.md       # LLM이 읽는 스킬 설명 및 트리거 조건
│   │   └── handler.sh     # 실제 실행 로직 (진입점)
│   └── calendar/
│       ├── SKILL.md
│       └── gcal.py
└── openclaw.config.yml

스킬은 우선순위 계층으로 관리됩니다.

워크스페이스 스킬 — 현재 프로젝트에만 적용되는 커스텀 스킬 (최우선)
글로벌 스킬 — 모든 워크스페이스에 공통으로 적용
번들 스킬 — OpenClaw가 기본으로 제공하는 내장 스킬

공식 스킬 마켓플레이스인 ClawHub(clawhub.ai)에는 2026년 3월 기준 700개 이상의 커뮤니티 스킬이 등록되어 있습니다.

전체 아키텍처 흐름

css

[사용자 메신저]
      │  "내일 오전 10시 회의 잡아줘"
      ▼
[OpenClaw 메시징 어댑터]  ← Telegram / WhatsApp / Slack ...
      │
      ▼
[LLM 추론 엔진]           ← Claude / GPT-4o / Ollama ...
      │  (SKILL.md를 시스템 프롬프트에 삽입 → Tool Use로 스킬 선택)
      │  "calendar.create 스킬 호출"
      ▼
[Skills 디스패처]         ← 해당 스킬 디렉터리의 실행 파일 탐색
      │
      ▼
[Docker 샌드박스]         ← 실제 명령 실행 (gcal API 호출 등)
      │
      ▼
[응답 반환 → 메신저]

실전 적용

핵심 개념을 이해했으니, 실제 파이프라인을 구성하는 세 가지 예시를 살펴보겠습니다.

예시 1: Ollama + Telegram으로 로컬 데이터 분석 봇 만들기

하드웨어 요구사항: llama3.2 모델(3B 파라미터)은 최소 8GB RAM이 필요하며, GPU 없이 CPU 추론도 가능합니다. 8B 이상의 모델을 사용하려면 16GB RAM 이상 환경을 권장합니다.

클라우드 API 비용 없이 로컬 LLM만으로 CSV 데이터를 분석하는 파이프라인입니다.

# .env (프로젝트 루트 — .gitignore에 추가 필수)
TELEGRAM_BOT_TOKEN=your_bot_token_here

그다음, 메인 설정 파일을 작성합니다.

yaml

# openclaw.config.yml
llm:
  provider: ollama
  model: llama3.2
  base_url: http://localhost:11434/v1
 
channels:
  - type: telegram
    token: "${TELEGRAM_BOT_TOKEN}"   # .env에서 자동 로드
 
sandbox:
  engine: docker
  image: openclaw/sandbox:latest
  volumes:
    - ./output:/output               # 분석 결과 파일 저장 경로 마운트
 
skills:
  - path: ./skills/data-analyst

스킬 설명 파일을 만듭니다.

bash

<!-- skills/data-analyst/SKILL.md -->
# Data Analyst Skill
 
## Description
CSV 파일을 받아 pandas로 분석하고 요약 및 시각화 결과를 반환합니다.
 
## Trigger
사용자가 CSV 파일을 업로드하거나 "분석해줘", "요약해줘" 같은 요청을 보낼 때 활성화됩니다.
 
## Entrypoint
analyze.py
 
## Usage
- 파일 첨부 후 "이 데이터 분석해줘" 메시지 전송
- "컬럼별 통계 알려줘", "이상치 찾아줘" 등의 자연어 명령 지원

실제 분석 로직을 작성합니다.

python

# skills/data-analyst/analyze.py
import pandas as pd
import matplotlib.pyplot as plt
import sys, json
 
def analyze(filepath: str) -> dict:
    df = pd.read_csv(filepath)
    summary = {
        "shape": df.shape,
        "columns": list(df.columns),
        "stats": json.loads(df.describe().to_json()),
        "nulls": df.isnull().sum().to_dict(),
    }
    # /output 디렉터리는 openclaw.config.yml의 volumes 설정으로
    # 호스트의 ./output 디렉터리와 마운트됩니다.
    # 이 경로에 저장된 파일은 OpenClaw가 자동으로 메신저로 전송합니다.
    df.hist(figsize=(10, 8))
    plt.tight_layout()
    plt.savefig("/output/histogram.png")
    return summary
 
if __name__ == "__main__":
    result = analyze(sys.argv[1])
    print(json.dumps(result, ensure_ascii=False, indent=2))

마지막으로 Docker Compose 파일과 실행 명령입니다.

bash

# docker-compose.yml
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    env_file: .env
    volumes:
      - ./openclaw.config.yml:/app/openclaw.config.yml:ro
      - ./skills:/app/skills:ro
      - ./output:/output
    ports:
      - "3000:3000"
    restart: unless-stopped

# 실행
docker compose up -d
 
# 로그 확인
docker compose logs -f openclaw

설정 항목	역할
`llm.provider: ollama`	외부 API 대신 로컬 Ollama 서버 사용
`channels.type: telegram`	Telegram Bot API를 메시징 인터페이스로 연결
`sandbox.volumes`	`/output`을 호스트와 공유해 분석 결과 파일을 메신저로 전달
`SKILL.md Entrypoint`	스킬 실행 시 호출되는 파일(`analyze.py`) 명시
`${TELEGRAM_BOT_TOKEN}`	`.env`에서 로드되는 환경 변수 — 설정 파일에 직접 입력하지 않습니다

예시 2: Cron 기반 정기 보고 에이전트

매일 오전 8시에 날씨·뉴스·서버 상태를 자동으로 WhatsApp으로 보고하는 에이전트입니다.

# .env
WHATSAPP_PHONE_NUMBER=+821012345678

yaml

# openclaw.config.yml (발췌)
channels:
  - type: whatsapp
    phone: "${WHATSAPP_PHONE_NUMBER}"
 
wakeups:
  - name: morning-report
    cron: "0 8 * * *"          # 매일 오전 8시
    message: |
      오늘의 모닝 리포트를 준비해줘:
      1. 서울 날씨 확인
      2. 기술 뉴스 상위 3개 요약
      3. 서버 CPU/메모리 상태 점검
    channel: whatsapp

wakeups란? OpenClaw의 Cron 트리거 기능입니다. 외부 스케줄러(crontab, Airflow 등) 없이 YAML 설정만으로 정기 자동 실행 에이전트를 만들 수 있습니다.

주의: wakeups 설정 후에는 에이전트가 정기적으로 외부 API를 호출하거나 파일을 수정할 수 있습니다. 첫 wakeup은 날씨 조회처럼 읽기 전용 스킬부터 시작하고, docker compose logs -f openclaw로 행동을 충분히 확인한 뒤 쓰기 권한이 있는 스킬을 추가하는 방식을 권장합니다.

예시 3: 브라우저 자동화 — 웹 스크래핑 챗봇

OpenClaw 전용 Chromium 노드를 연결하면 채팅 명령만으로 웹 자동화가 가능합니다.

yaml

# openclaw.config.yml (발췌)
nodes:
  - type: browser
    engine: chromium
    headless: true             # Docker 환경에는 디스플레이가 없으므로 필수
 
skills:
  - path: ./skills/web-scraper

headless: true란? 브라우저를 화면(GUI) 없이 백그라운드에서 실행하는 모드입니다. Docker 컨테이너에는 디스플레이가 없으므로, 브라우저 자동화를 서버 환경에서 사용할 때는 반드시 이 옵션을 활성화해야 합니다.

스킬 설명 파일을 만듭니다.

html

<!-- skills/web-scraper/SKILL.md -->
# Web Scraper Skill
 
## Description
지정된 URL의 웹 페이지에서 콘텐츠를 스크래핑합니다.
 
## Trigger
사용자가 URL을 제공하며 "기사 제목 가져와줘", "스크래핑해줘" 같은 요청을 보낼 때 활성화됩니다.
 
## Entrypoint
scrape.py

실제 스크래핑 로직을 작성합니다.

python

# skills/web-scraper/scrape.py
import sys
import json
from playwright.sync_api import sync_playwright
 
def scrape(url: str, limit: int = 5) -> list[dict]:
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()
        page.goto(url)
        items = page.query_selector_all(".athing .titleline")
        results = []
        for item in items[:limit]:
            anchor = item.query_selector("a")
            if anchor:
                results.append({
                    "title": anchor.inner_text(),
                    "url": anchor.get_attribute("href"),
                })
        browser.close()
    return results
 
if __name__ == "__main__":
    url = sys.argv[1]
    limit = int(sys.argv[2]) if len(sys.argv) > 2 else 5
    result = scrape(url, limit)
    print(json.dumps(result, ensure_ascii=False, indent=2))

html

<!-- 사용 예시 — Telegram 채팅창 -->
사용자: https://news.ycombinator.com 상위 5개 기사 제목 가져와줘
 
에이전트: 잠시만요, 스크래핑 중입니다...
         1. [제목 1] — 링크
         2. [제목 2] — 링크
         3. [제목 3] — 링크
         4. [제목 4] — 링크
         5. [제목 5] — 링크

장단점 분석

장점

항목	내용	활용 포인트
완전한 오픈소스	MIT 라이선스, 100% 자체 호스팅 가능	내부 데이터를 외부 SaaS에 보내지 않아도 됩니다
모델 무관(Model-agnostic)	OpenAI-compatible API를 노출하는 모든 LLM 연결 가능	비용·프라이버시 균형을 직접 조정할 수 있습니다
프라이버시 보장	데이터가 외부 SaaS 서버에 저장되지 않음	민감한 사내 데이터 처리에 적합합니다
풍부한 생태계	ClawHub의 700개+ 스킬, 22개+ 메시징 채널 (2026년 3월 기준)	직접 개발 없이 기능을 빠르게 확장할 수 있습니다
Docker 격리	에이전트 오작동 시 호스트 시스템 보호	실험적인 스킬도 안전하게 테스트할 수 있습니다
친숙한 UX	별도 앱 설치 없이 기존 메신저로 에이전트 제어	팀원이 새 도구를 배울 필요가 없습니다

단점 및 주의사항

항목	내용	대응 방안
거대한 코드베이스	430,000줄+ 코드, 넓은 공격 표면	NanoClaw 또는 ZeroClaw 같은 경량 포크 검토
자격증명 노출 구조	프로세스 수준 크리덴셜 격리 없음	최소 권한 API 키 사용, Vault 등 비밀 관리 도구 연동
장기 메모리 부재	세션이 끊기면 사용자 선호 기억 불가	memU 같은 장기 메모리 특화 에이전트와 조합
자율 행동 리스크	잘못 구성 시 자동 구매·스팸 발송 사례 보고	민감한 스킬은 확인 단계(confirm step) 추가
자체 호스팅 부담	Docker 환경 구성, API 키 관리 등 초기 설정 필요	DigitalOcean 공식 튜토리얼 참고 권장

operator-trust 모델이란? OpenClaw에서 에이전트(LLM)가 연결된 도구와 서비스에 광범위한 접근 권한을 갖는 신뢰 모델입니다. 편리한 반면, 스킬 설정을 잘못했을 때 의도치 않은 작업이 실행될 수 있으므로 권한 범위를 신중하게 설정하는 것이 중요합니다.

실무에서 가장 흔한 실수

API 키를 openclaw.config.yml에 직접 하드코딩하는 경우 — 설정 파일이 버전 관리에 올라가면 키가 노출될 수 있습니다. 반드시 .env 파일에 선언하고 ${VAR_NAME} 방식으로 참조하는 것을 권장합니다. .env는 .gitignore에 추가하는 것도 잊지 않는 것이 좋습니다.
wakeups 설정 후 에이전트의 자율 권한 범위를 확인하지 않는 경우 — 정기 실행 에이전트가 예상치 못한 외부 API를 호출하거나 파일을 수정하는 상황이 발생할 수 있습니다. 처음에는 읽기 전용 스킬(날씨 조회, RSS 요약 등)부터 시작하고, 에이전트 로그로 행동을 충분히 확인한 뒤 쓰기 권한 스킬을 추가하는 방식을 권장합니다.
Docker 없이 직접 실행하려는 경우 — 샌드박스 격리를 우회하면 에이전트 명령이 호스트 파일 시스템에 직접 접근하게 됩니다. OpenClaw의 보안 모델은 Docker 격리를 전제로 설계되어 있으므로, 프로덕션 환경에서는 반드시 Docker 환경에서 운영하는 것을 권장합니다.

마치며

지금 바로 시작해볼 수 있는 3단계입니다.

Docker와 Ollama를 먼저 설치합니다. Ollama 공식 사이트(ollama.com)에서 설치 후 ollama pull llama3.2 명령어로 모델을 받아두면 로컬 LLM 환경이 준비됩니다.
OpenClaw 공식 저장소를 클론하고 기본 설정 파일을 만듭니다. git clone https://github.com/openclaw/openclaw 후 openclaw.config.yml에 Telegram 봇 토큰과 Ollama 연결 설정을 입력하면 됩니다.
ClawHub(clawhub.ai)에서 관심 있는 스킬을 하나 골라 워크스페이스에 추가해봅니다. Telegram 봇이 첫 응답을 반환하는 시점이 입문 단계의 성공 마일스톤입니다. 이후 날씨 조회나 RSS 뉴스 요약 같은 간단한 스킬을 하나씩 추가해 나가면 Skills 시스템의 동작 방식을 자연스럽게 체감할 수 있습니다.

다음 글: OpenClaw 보안 심화 — 자격증명 격리, 최소 권한 스킬 설계, NanoClaw·ZeroClaw와의 비교로 프로덕션 환경에서 안전하게 운영하는 방법

참고 자료

[공식] OpenClaw GitHub | github.com/openclaw
[공식] OpenClaw 공식 문서 | docs.openclaw.ai
[공식] OpenClaw Skills 문서 | docs.openclaw.ai/tools/skills
[튜토리얼] Using OpenClaw with Ollama: Building a Local Data Analyst | DataCamp
[튜토리얼] How to Run OpenClaw with DigitalOcean | DigitalOcean
[입문] What Is OpenClaw? Complete Guide | Milvus Blog
[입문] OpenClaw Explained: The Free AI Agent Tool Going Viral | KDnuggets
[심화] OpenClaw security: architecture and hardening guide | Nebius
[심화] 6 OpenClaw Competitors That Are Gaining Ground in 2026 | emergent.sh
[심화] Unleashing OpenClaw: The Ultimate Guide | DEV Community