OpenClaw 가이드 : 설치부터 자동화·실전 활용 시나리오 30선

# Node.js 포함 모든 것을 자동 설치
curl -fsSL https://openclaw.ai/install.sh | bash

# PowerShell을 관리자 권한으로 실행
iwr -useb https://openclaw.ai/install.ps1 | iex

# npm으로 전역 설치
npm i -g openclaw

# 또는 pnpm 사용
pnpm add -g openclaw

# 설치 확인
openclaw --version

# 방법 A: 설치 스크립트로 Git 방식 선택
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

# 방법 B: 직접 클론
git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable        # pnpm 활성화
pnpm install           # 의존성 설치
pnpm openclaw onboard  # 온보딩 시작

# 소스 수정 후 바로 반영됨 (번들 없이 직접 실행)

# --install-daemon: 부팅 시 자동 시작 데몬으로 등록
openclaw onboard --install-daemon

# Gateway 상태 확인
openclaw gateway status

# 웹 대시보드 열기 (기본 브라우저에서 Control UI 오픈)
openclaw dashboard

# Gateway 시작 / 중지 / 재시작
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

# 버전 확인 및 업데이트
openclaw --version
openclaw update            # 안정 채널로 업데이트
openclaw update --channel dev   # 개발 채널 (최신 기능, 불안정 가능)

# 설정 파일 경로
# macOS/Linux: ~/.openclaw/config.json
# Windows:     %APPDATA%\openclaw\config.json
cat ~/.openclaw/config.json

# 최신 릴리즈 페이지에서 .dmg 다운로드
open https://github.com/openclaw/openclaw/releases/latest

# 또는 curl로 직접
curl -L "https://github.com/openclaw/openclaw/releases/latest/download/OpenClaw.dmg" -o OpenClaw.dmg
open OpenClaw.dmg

# Anthropic(Claude) 설정
openclaw models add anthropic --key sk-ant-xxxxx

# OpenAI(GPT) 설정
openclaw models add openai --key sk-xxxxx

# Google Gemini 설정
openclaw models add google --key AIzaxxxxx

# Groq (무료 티어 제공)
openclaw models add groq --key gsk_xxxxx

# DeepSeek
openclaw models add deepseek --key sk-xxxxx

# Ollama (로컬 서버 — 완전 무료)
openclaw models add ollama --base-url http://localhost:11434

# 여러 공급자 동시 사용 가능
openclaw models list

# Claude Max Proxy 플러그인 설치
openclaw plugins install @openclaw/claude-max-proxy

# 또는 대화 중에 "Claude Max proxy 설정해줘"라고 말하면
# AI가 직접 설치 과정을 안내합니다

# Ollama가 로컬(같은 컴퓨터)에서 실행 중인 경우
openclaw models add ollama --base-url http://localhost:11434

# Ollama가 AI 서버(홈랩)에서 실행 중인 경우
openclaw models add ollama --base-url http://192.168.1.253:11434

# config.json에서 직접 편집하는 방법
# ~/.openclaw/config.json
{
  "providers": {
    "ollama": {
      "baseUrl": "http://192.168.1.253:11434",
      "defaultModel": "qwen2.5:14b"
    }
  }
}

# 기본 모델을 Ollama로 변경 (대화에서)
# "기본 모델을 qwen2.5:14b 로 바꿔줘"라고 말하면 됩니다

{
  "model": {
    // 기본 모델
    "default": "anthropic/claude-sonnet-4-5",

    // Failover 순서: Anthropic 실패 시 Groq으로, 그다음 Ollama로
    "failover": [
      "anthropic/claude-sonnet-4-5",
      "groq/llama-4-scout-17b",
      "ollama/qwen2.5:14b"
    ],

    // 작업 유형별 모델 지정
    "routing": {
      "coding":    "anthropic/claude-sonnet-4-5",
      "analysis":  "google/gemini-2.0-flash",
      "quick":     "groq/llama-4-scout-17b",
      "local":     "ollama/qwen2.5:14b"
    }
  }
}

# Telegram 봇 등록
openclaw channels add telegram --token 1234567890:AAFxxxxxxxxxxxxxxxx

# 봇에서 /start 입력 후 페어링 코드 확인
openclaw channels pair telegram

# 그룹 채팅에서 사용 (봇을 그룹에 초대 후)
# 그룹에서 @봇이름 으로 멘션하거나
# 설정에서 respond_without_mention: true 설정 가능

# 채널 상태 확인
openclaw channels status telegram

# WhatsApp 플러그인 설치 (ClawHub에서 다운로드)
openclaw plugins install @openclaw/whatsapp

# QR 코드 생성
openclaw channels add whatsapp

# 터미널에 QR 코드가 표시됨
# WhatsApp 앱 → 설정 → 연결된 기기 → 기기 연결 → QR 스캔

# 연결 확인
openclaw channels status whatsapp

# ⚠️ 주의: WhatsApp은 공식 API가 아닌 Baileys 라이브러리 사용
# 비즈니스 목적 대량 발송은 WhatsApp 정책 위반 가능

{
  "channels": {
    "telegram": {
      "token": "YOUR_BOT_TOKEN",
      "pairing": {
        // "allowlist": 등록된 사용자만 접근 허용 (권장)
        // "public": 누구나 접근 가능
        // "closed": 모든 접근 차단
        "mode": "allowlist",

        // 허용된 Telegram 사용자 ID 목록
        "allowedUsers": ["your_telegram_user_id"],

        // 페어링 코드 만료 시간 (초)
        "codeExpiresIn": 300
      }
    }
  }
}

{
  "tools": {
    "exec": {
      // 사전 승인된 명령 패턴 (정규식 가능)
      "allowed": [
        "git *",
        "npm *",
        "python3 *",
        "ls *",
        "cat *",
        "echo *"
      ],

      // 절대 실행 금지 명령
      "denied": [
        "rm -rf *",
        "sudo rm *",
        "format *"
      ],

      // 목록에 없는 명령은 사용자 승인 요청
      "requireApprovalForUnknown": true
    }
  }
}

---
name: morning-briefing
description: 매일 아침 날씨·뉴스·일정 요약 브리핑
version: 1.0.0
triggers:
  - schedule: "0 8 * * *"   # 매일 오전 8시
  - command: "/briefing"     # 슬래시 명령으로 수동 실행
channels:
  - telegram                 # Telegram으로 전송
tools:
  - web_search
  - exec
  - message
---

# 아침 브리핑 스킬

## 설명
사용자에게 매일 오전 8시 맞춤 아침 브리핑을 전송합니다.

## 브리핑 구성 순서

1. **날씨 확인**
   - web_search로 오늘 서울 날씨 검색
   - 기온·강수 확률·특이사항 요약

2. **주요 뉴스 (3개)**
   - 기술 뉴스 1개, 국내 뉴스 1개, 사용자 관심사 1개
   - 각 뉴스는 2~3문장으로 요약

3. **오늘 일정**
   - 캘린더 스킬이 있으면 오늘 이벤트 조회
   - 중요 마감일 강조

## 메시지 형식
```
🌅 **오전 브리핑 — {날짜}**

☀️ **날씨**: {날씨 요약}

📰 **오늘의 뉴스**
1. {뉴스1}
2. {뉴스2}
3. {뉴스3}

📅 **오늘 일정**: {일정 요약}

좋은 하루 되세요! 🦞
```

## 주의사항
- 브리핑은 간결하게 (300자 이내 권장)
- 불확실한 정보는 포함하지 말 것

# Telegram/WhatsApp/Discord 등 채팅에서 말하기만 하면 됩니다

나: "매일 아침 8시에 날씨랑 뉴스 요약해서 여기로 보내줘"

AI: "네! 아침 브리핑 스킬을 만들겠습니다."
    (SKILL.md 파일 자동 생성 + 즉시 활성화)
    "내일부터 매일 오전 8시에 브리핑을 보내드릴게요 🦞"

나: "Todoist에서 오늘 할 일 가져오는 스킬 만들어줘"

AI: "Todoist API 연동 스킬을 작성할게요. API 토큰이 있나요?"
    (사용자가 토큰 제공 → 스킬 자동 작성 → 즉시 사용 가능)

# 스킬 목록 검색
openclaw skills search "calendar"

# 특정 스킬 설치
openclaw skills install clawhub/google-calendar
openclaw skills install clawhub/obsidian-notes
openclaw skills install clawhub/github-issues
openclaw skills install clawhub/home-assistant

# 설치된 스킬 목록
openclaw skills list

# 스킬 활성화/비활성화
openclaw skills enable clawhub/google-calendar
openclaw skills disable clawhub/github-issues

# 직접 다운로드한 스킬 폴더에 넣기
# ~/.openclaw/skills/ 아래 폴더 생성 후 SKILL.md 배치하면 자동 인식
mkdir -p ~/.openclaw/skills/my-custom-skill
cp SKILL.md ~/.openclaw/skills/my-custom-skill/

{
  "heartbeat": {
    "enabled": true,

    // 매 30분마다 AI가 깨어나 상황 점검
    "interval": "*/30 * * * *",

    // Heartbeat 시 AI에게 주는 지시
    "prompt": "현재 시각을 확인하고, 다음 사항을 점검하세요:\n1. 30분 내 마감인 할 일이 있는지\n2. 중요한 이메일이 왔는지\n3. 이상한 시스템 이벤트가 없는지\n필요하면 사용자에게 알림을 보내세요.",

    // 알림을 보낼 채널
    "notifyChannel": "telegram",

    // 조용한 시간 (알림 차단)
    "quietHours": {
      "start": "23:00",
      "end": "07:00",
      "timezone": "Asia/Seoul"
    }
  }
}

# 방법 1: 대화로 등록 (가장 쉬움)
# "매일 오전 9시에 오늘 할 일 목록 정리해서 보내줘"
# AI가 cron 작업을 자동으로 추가합니다

# 방법 2: CLI로 직접 등록
openclaw schedule add \
  --name "morning-briefing" \
  --cron "0 8 * * *" \
  --task "날씨, 주요 뉴스 3건, 오늘 일정을 정리해서 Telegram으로 보내줘"

# 방법 3: config.json에 직접 추가
# cron 표현식: 분 시 일 월 요일
# "0 8 * * *"   = 매일 오전 8시
# "0 9 * * 1"   = 매주 월요일 오전 9시
# "0 18 * * 5"  = 매주 금요일 오후 6시
# "*/30 * * * *" = 30분마다

# 등록된 스케줄 목록
openclaw schedule list

# 스케줄 삭제
openclaw schedule remove morning-briefing

{
  "standingOrders": [
    {
      "name": "email-summary",
      "description": "새 이메일 수신 시 자동 요약",
      // 트리거: Gmail 웹훅 또는 폴링
      "trigger": "gmail:new_email",
      "condition": "발신자가 스팸이 아니고 중요 표시가 있을 때",
      "action": "이메일 내용을 2~3문장으로 요약해 Telegram으로 전송",
      "channel": "telegram"
    },
    {
      "name": "system-alert",
      "description": "서버 CPU 90% 초과 시 알림",
      "trigger": "schedule:*/5 * * * *",
      "condition": "CPU 사용률이 90%를 초과할 때",
      "action": "시스템 리소스 상황과 문제 원인을 분석해 알림 발송",
      "channel": "telegram"
    },
    {
      "name": "pr-review",
      "description": "GitHub PR 생성 시 자동 코드 리뷰",
      "trigger": "webhook:github:pull_request:opened",
      "action": "PR 코드를 분석하고 잠재적 이슈를 코멘트로 게시",
      "channel": "github"
    }
  ]
}

{
  "hooks": {
    // 웹훅 수신 엔드포인트
    // http://your-server:18789/webhook/github
    "github": {
      "secret": "your_github_webhook_secret",
      "events": ["push", "pull_request", "issues"],
      "action": "이벤트 내용을 분석하고 중요도에 따라 Telegram 알림"
    },

    "sentry": {
      "events": ["error"],
      "action": "에러 스택 트레이스 분석 → 원인 추론 → 수정 방법 제안 후 알림"
    }
  }
}

# 방법 1: 같은 네트워크 (내부망)
openclaw models add ollama \
  --base-url http://192.168.1.253:11434 \
  --default-model qwen2.5:14b

# 방법 2: Tailscale VPN으로 원격 접근
# AI 서버에 Tailscale 설치 후
openclaw models add ollama \
  --base-url http://100.x.x.x:11434 \  # Tailscale IP
  --default-model qwen2.5:14b

# 방법 3: Cloudflare Tunnel 통해 외부 접근
openclaw models add ollama \
  --base-url https://ollama.yourdomain.com \
  --default-model qwen2.5:14b

# 연결 테스트
openclaw models test ollama

{
  "providers": {
    "comfyui": {
      // AI 서버의 ComfyUI 주소
      "baseUrl": "http://192.168.1.253:8188",

      // 기본 워크플로우 파일 경로
      "defaultWorkflow": "~/.openclaw/workflows/flux_default.json",

      // 이미지 생성 기본 설정
      "defaults": {
        "width": 1024,
        "height": 1024,
        "steps": 20,
        "cfg": 7.0
      }
    }
  }
}

## 사용 예시 (채팅에서)
# "ComfyUI로 석양이 지는 항구 이미지 생성해줘"
# → AI가 ComfyUI API 호출 → 생성된 이미지를 채팅으로 전송

## n8n → OpenClaw 방향 (n8n 이벤트 → AI 처리)

# 1. OpenClaw의 웹훅 수신 URL 확인
openclaw gateway status
# http://서버IP:18789 에서 웹훅 수신

# 2. n8n에서 HTTP Request 노드 추가
# URL: http://192.168.1.253:18789/api/message
# Method: POST
# Body:
{
  "channel": "telegram",
  "message": "n8n 워크플로우가 완료됐습니다: {{ $json.result }}"
}

## OpenClaw → n8n 방향 (AI 명령 → n8n 워크플로우 실행)
# Standing Order 또는 스킬에서 exec 도구로 n8n 웹훅 호출

## SKILL.md에서 n8n 연동 예시
# exec 도구로 curl 명령 실행
# curl -X POST http://192.168.1.253:5678/webhook/my-workflow

---
name: home-assistant
description: Home Assistant 스마트홈 제어
tools: [exec]
---

# Home Assistant 제어 스킬

## 설정
- HA 주소: http://homeassistant.local:8123
- Long-Lived Access Token: (config에서 로드)

## 명령 예시

### 조명 제어
사용자가 "거실 불 꺼줘"라고 하면:
```bash
curl -X POST http://homeassistant.local:8123/api/services/light/turn_off \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "light.living_room"}'
```

### 온도 확인
사용자가 "집 온도 알려줘"라고 하면:
```bash
curl http://homeassistant.local:8123/api/states/sensor.indoor_temperature \
  -H "Authorization: Bearer $HA_TOKEN"
```

## 사용 가능한 엔티티 목록
AI는 사용자 요청에 맞는 엔티티를 선택해 제어합니다.

# Memory Wiki 설치 (마크다운 파일 기반 메모리)
openclaw plugins install @openclaw/memory-wiki

# Memory LanceDB 설치 (벡터 DB 기반 의미 검색 메모리)
openclaw plugins install @openclaw/memory-lancedb

# 대화로 메모리 관리
# "내가 커피를 좋아한다고 기억해줘"
# "아침 미팅은 항상 9시 이후로 잡아야 한다는 걸 저장해"
# "지금까지 내 건강 목표에 대해 뭘 알고 있어?"

# 메모리 파일 직접 확인
cat ~/.openclaw/memory/wiki.md

# 서브 에이전트 생성 (별도 인스턴스)
openclaw agent create --name "email-agent" \
  --model "groq/llama-4-scout-17b" \
  --task "이메일 처리 전담"

openclaw agent create --name "code-agent" \
  --model "anthropic/claude-sonnet-4-5" \
  --task "코드 리뷰 및 개발 전담"

# 에이전트 목록 확인
openclaw agents list

# 에이전트에게 작업 위임 (대화에서)
# "email-agent에게 오늘 받은 이메일 처리 맡겨줘"
# "code-agent에게 최근 PR 리뷰 요청해줘"

# 에이전트 간 통신은 message 도구로

# Claude Code Harness 플러그인 설치
openclaw plugins install @openclaw/codex-harness

# Codex Computer Use (화면 제어 포함)
openclaw plugins install @openclaw/codex-computer-use

# 대화로 원격 제어 예시
# "~/projects/myapp 에서 테스트 실행해줘"
# → AI가 AI 서버에서 claude-code 실행
# → 진행상황 실시간 전송
# → 완료 시 결과 요약 전송

# 자율 루프 (감시 모드)
# "Sentry에 에러 오면 자동으로 분석하고 PR 만들어줘"

{
  "acp": {
    "enabled": true,

    // 이 인스턴스의 역할
    "role": "orchestrator",

    // 연결된 에이전트들
    "peers": [
      {
        "name": "email-worker",
        "url": "http://localhost:18790",  // 다른 포트의 OpenClaw
        "specialization": "이메일·커뮤니케이션 처리"
      },
      {
        "name": "code-worker",
        "url": "http://192.168.1.254:18789",  // 다른 머신의 OpenClaw
        "specialization": "코드 리뷰·개발 작업"
      }
    ]
  }
}

{
  "gateway": {
    // 수신 포트 (기본 18789)
    "port": 18789,

    // 바인딩 주소
    // "127.0.0.1": 로컬만 (기본) → 보안적으로 가장 안전
    // "0.0.0.0": 모든 인터페이스 → Nginx/Cloudflare로 외부 공개 시
    "host": "127.0.0.1",

    // Control UI (웹 대시보드) 설정
    "controlUi": {
      "enabled": true,
      // 커스텀 UI 경로 (선택)
      "root": null
    },

    // 인증 토큰 (외부 접근 시 필수)
    "authToken": "your_gateway_auth_token_here",

    // CORS 설정 (웹 클라이언트 접근 허용)
    "cors": {
      "enabled": true,
      "origins": ["http://localhost:3000", "https://your-dashboard.com"]
    },

    // TLS 설정 (직접 HTTPS 종료)
    "tls": {
      "enabled": false,
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem"
    },

    // 로그 설정
    "log": {
      "level": "info",  // debug / info / warn / error
      "file": "~/.openclaw/logs/gateway.log"
    }
  }
}

# 1. cloudflared 설치
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cf.deb
sudo dpkg -i cf.deb

# 2. Cloudflare 로그인
cloudflared tunnel login

# 3. 터널 생성
cloudflared tunnel create openclaw-gateway

# 4. Cloudflare Zero Trust 대시보드에서
#    Public Hostname: openclaw.yourdomain.com → http://localhost:18789

# 5. Gateway config.json 업데이트
#    "host": "127.0.0.1"  → localhost만 (Cloudflare가 앞단)

# 6. config.json의 authToken 설정 (외부 접근 보안)

# 이제 어디서든 https://openclaw.yourdomain.com 으로 접속 가능

# Ubuntu 24.04 ARM 설치 후

# Node.js 24 설치 (ARM용)
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

# OpenClaw 설치
npm i -g openclaw

# 온보딩 (데몬 등록 필수)
openclaw onboard --install-daemon

# Gateway를 모든 인터페이스에서 수신하도록 설정
# ~/.openclaw/config.json에서 "host": "0.0.0.0" 으로 변경

# systemd 서비스 상태 확인
systemctl status openclaw-gateway

# 이제 24시간 OpenClaw가 서버에서 실행되며
# 폰에서 Telegram으로 언제든 명령 가능

# 전체 상태 확인
openclaw status

# Gateway 로그 실시간 확인
openclaw gateway logs -f

# 채널 상태 전체 확인
openclaw channels list

# 플러그인 목록 확인
openclaw plugins list

# 설정 파일 유효성 검사
openclaw config validate

# 모든 설정 초기화 (주의! 데이터 삭제됨)
openclaw reset --confirm

# 로그 파일 위치
# ~/.openclaw/logs/gateway.log

# 설정 파일 직접 편집
nano ~/.openclaw/config.json

# 업데이트 채널 확인 및 변경
openclaw update --channel stable   # 안정 버전
openclaw update --channel dev      # 최신 개발 버전