OpenClaw 마스터 온보딩 위자드부터 모델·툴 세부구성 및 자동화

┌─────────────────────────────────────────────────────────┐
│                     OpenClaw Gateway                     │
│                                                          │
│  ┌──────────────┐   ┌────────────┐   ┌───────────────┐  │
│  │   Channels   │   │  Sessions  │   │  Automation   │  │
│  │  Telegram    │   │  Routing   │   │  Cron/Tasks   │  │
│  │  WhatsApp    │   │  Memory    │   │  Hooks        │  │
│  │  Discord     │   │  Context   │   │  Standing     │  │
│  │  Slack +11   │   └─────┬──────┘   └───────────────┘  │
│  └──────┬───────┘         │                              │
│         │          ┌──────▼──────┐                       │
│         └──────────►  Pi Agent   │                       │
│                    │ (AI Core)   │                       │
│                    └──────┬──────┘                       │
│                           │ Model API                    │
└───────────────────────────┼─────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
           Ollama      Anthropic       OpenAI
         (로컬 LLM)    (Claude)       (GPT 등)
                         Groq / OpenRouter / ...

클라이언트:
  ┌──────────────┬───────────────┬──────────────┐
  │ Web Control  │   Mobile Node  │  CLI / API   │
  │   UI :18789  │  (iOS/Android) │              │
  └──────────────┴───────────────┴──────────────┘

# Node 24 설치 (nvm 사용 권장)
nvm install 24 && nvm use 24

# OpenClaw 글로벌 설치
npm install -g openclaw@latest

# 설치 확인
openclaw --version

# 온보딩 실행 (시스템 데몬까지 자동 설치)
openclaw onboard --install-daemon

# Docker Compose로 설치한 경우 온보딩 명령
docker compose run --rm --no-deps \
  --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

# 온보딩 완료 후 게이트웨이 시작
docker compose up -d openclaw-gateway

# 게이트웨이 상태 확인
docker compose logs -f openclaw-gateway

# 정상 기동 메시지 예시:
# [gateway] Listening on 0.0.0.0:18789
# [gateway] Gateway ready — token: oc_gt_xxxxxxxxxxxx
# [gateway] Control UI: http://0.0.0.0:18789

# 현재 설정 전체 조회
openclaw config show

# 특정 항목 조회
openclaw config get agents.defaults.model
openclaw config get channels.telegram

# 값 설정
openclaw config set agents.defaults.model "ollama/gemma4:e4b"
openclaw config set agents.defaults.systemPrompt "You are a helpful assistant."

# 배열 형식 (JSON 문자열로 입력)
openclaw config set channels.telegram.allowFrom '["123456789","987654321"]'

# 항목 삭제 (기본값 복원)
openclaw config unset agents.defaults.systemPrompt

# Docker 환경에서 CLI 실행 방법
docker compose --profile cli run --rm openclaw-cli config show

{
  models: {
    // Model Catalog Mode: "merge"(기본) = 내장 Provider 유지 + 커스텀 추가
    //                     "replace" = 커스텀 Provider만 사용
    catalogMode: "merge",

    providers: {
      ollama: {
        // Docker: 서비스명으로 접근
        baseUrl: "http://ollama:11434",
        // 호스트 Ollama 사용 시 (Docker 외부)
        // baseUrl: "http://host.docker.internal:11434",

        models: [
          {
            id: "gemma4:e4b",
            contextWindow: 131072,   // 128K context
            maxOutputTokens: 8192,
          },
          {
            id: "llama3.1:8b",
            contextWindow: 131072,
          },
          {
            id: "qwen2.5:14b",
            contextWindow: 131072,
          },
          // nomic-embed-text: 임베딩 전용 (채팅에는 사용 안 함)
          {
            id: "nomic-embed-text",
            contextWindow: 8192,
            type: "embedding",
          }
        ]
      }
    },

    agents: {
      defaults: {
        model: {
          primary: "ollama/gemma4:e4b",
          // Failover: primary 실패 시 자동 전환
          fallbacks: ["ollama/llama3.1:8b"],
        }
      }
    }
  }
}

# Primary + Fallback 체인 설정 (CLI)
openclaw config set agents.defaults.model \
  '{"primary":"anthropic/claude-opus-4-6","fallbacks":["openai/gpt-4o","ollama/gemma4:e4b"]}'

# 동작 순서:
# 1. Anthropic Claude Opus 4.6 시도
# 2. 실패 시 → OpenAI GPT-4o 시도
# 3. 실패 시 → Ollama Gemma4 E4B (로컬 최종 보루)

# 멀티 Provider 연결 추가 (온보딩 이후)
openclaw providers add --provider anthropic --key sk-ant-api03-xxx
openclaw providers add --provider groq --key gsk_xxx
openclaw providers add --provider openrouter --key sk-or-xxx

# 등록된 Provider 목록 확인
openclaw providers list

# 사용 가능한 모델 목록 확인
openclaw models list
openclaw models list --provider ollama

{
  channels: {
    telegram: {
      // DM 접근 정책
      // "pairing" (기본): 누구나 페어링 요청 가능 — 공개 봇
      // "allowlist": allowFrom 목록만 접근 — 개인/팀 사용 권장
      // "open": 누구나 즉시 대화 — 공개 서비스용
      dmPolicy: "allowlist",

      // 허용 사용자 목록 (Telegram User ID, 숫자)
      allowFrom: ["123456789"],

      // 그룹 채팅 설정
      groups: {
        "*": {
          // true: 그룹에서 @봇이름 언급 시에만 응답
          requireMention: true,
        }
      },

      // 멘션 패턴 (선택)
      mentionPatterns: ["@mybotname"],

      // 주제(Topics) 있는 그룹에서 주제별 분리
      topicRouting: true,
    }
  }
}

# 1. Discord Developer Portal에서 봇 생성
#    https://discord.com/developers/applications
#    → New Application → Bot → Reset Token → 토큰 복사

# 2. Bot Intent 활성화 (중요!)
#    Bot 탭 → "Message Content Intent" 활성화 (필수)
#    → Privileged Gateway Intents도 확인

# 3. Bot 서버 초대
#    OAuth2 → URL Generator
#    Scopes: bot, applications.commands
#    Bot Permissions: Send Messages, Read Messages, Add Reactions
#    → 생성된 URL로 봇을 서버에 초대

# 4. OpenClaw에 토큰 등록
openclaw channels add --channel discord --token "YOUR_DISCORD_BOT_TOKEN"

# 5. 채널별 응답 설정 (선택)
# 특정 채널 ID에서만 응답
openclaw config set channels.discord.allowChannels '["채널ID1","채널ID2"]'

# 특정 역할에게만 응답
openclaw config set channels.discord.allowRoles '["역할ID"]'

# 채널 목록 확인
openclaw channels list

# 1. Slack App 생성
#    https://api.slack.com/apps → Create New App
#    → From scratch → 앱 이름, 워크스페이스 선택

# 2. Bot Token Scopes 추가 (OAuth & Permissions)
#    app_mentions:read, channels:history, chat:write,
#    im:history, im:read, im:write, users:read

# 3. Event Subscriptions 활성화
#    Request URL: https://your-server.com/webhooks/slack
#    Subscribe to: message.im, app_mention

# 4. Bot Token 복사 (xoxb-로 시작)
openclaw channels add --channel slack --token "xoxb-your-token"

# DM 응답 정책 설정
openclaw config set channels.slack.dmPolicy "allowlist"
openclaw config set channels.slack.allowFrom '["U1234567890"]'  # Slack User ID

# MCP 서버 추가 (CLI)
openclaw mcp add --name "filesystem" --url "http://mcp-filesystem:3000/mcp"
openclaw mcp add --name "github"     --url "https://api.githubcopilot.com/mcp/"
openclaw mcp add --name "n8n"        --url "http://n8n:5678/mcp"
openclaw mcp add --name "caldav"     --url "http://caldav-mcp:8080/mcp"
openclaw mcp add --name "trello"     --url "http://trello-mcp:3001/mcp"

# MCP 서버 목록 확인
openclaw mcp list

# 특정 MCP 서버의 도구 목록 확인
openclaw mcp tools --name filesystem

# MCP 서버 제거
openclaw mcp remove --name filesystem

# openclaw.json으로 직접 설정
# {
#   mcp: {
#     servers: {
#       filesystem: { url: "http://mcp-filesystem:3000/mcp" },
#       github: { url: "https://api.githubcopilot.com/mcp/" },
#     }
#   }
# }

# 방법 A: 자체 호스팅 Firecrawl (Docker Compose)
# docker-compose.yml에 firecrawl 서비스 추가 후:
openclaw config set tools.firecrawl.baseUrl "http://firecrawl:3002"
openclaw config set tools.firecrawl.apiKey  "your-firecrawl-key"

# 방법 B: Firecrawl 클라우드 API
openclaw config set tools.firecrawl.baseUrl "https://api.firecrawl.dev"
openclaw config set tools.firecrawl.apiKey  "fc-xxxxxxxxxxxxx"

# 방법 C: SearXNG 자체 호스팅 (추천, 완전 무료)
openclaw config set tools.webSearch.engine  "searxng"
openclaw config set tools.searxng.url       "http://searxng:8080"

# PR 코드 리뷰 Skill

## 언제 사용하나요?
GitHub Pull Request 코드 리뷰 요청 시 이 Skill을 따르세요.

## 리뷰 절차

1. **PR 변경사항 파악**
   - `git diff main...HEAD`로 전체 변경 파악
   - 변경된 파일 목록 확인

2. **코드 품질 체크리스트**
   - [ ] 버그 또는 논리 오류
   - [ ] 성능 병목 가능성
   - [ ] 보안 취약점 (SQL Injection, XSS 등)
   - [ ] 중복 코드 및 리팩토링 기회
   - [ ] 테스트 커버리지

3. **리뷰 결과 형식**
   ```
   ## 코드 리뷰 결과

   ### ✅ 잘된 점
   - ...

   ### ⚠️ 개선 제안
   - 파일명:줄번호 — 문제 설명
     ```언어
     // 개선된 코드
     ```

   ### ❌ 수정 필요
   - 크리티컬 이슈 목록
   ```

## 주의사항
- 비즈니스 로직 변경은 작성자에게 의도 확인 후 코멘트
- 스타일 지적은 린터 설정으로 자동화 권장

# 설치 가능한 Plugin 목록 (ClawHub)
openclaw plugins list --available

# 주요 번들 Plugin 설치 예시
openclaw plugins install memory-wiki      # 영구 메모리 (Markdown wiki)
openclaw plugins install memory-lancedb   # 영구 메모리 (벡터 DB)
openclaw plugins install webhooks         # 외부 서비스 Webhook 수신
openclaw plugins install meeting-notes    # Google Meet 회의록 자동 생성
openclaw plugins install voice-call       # 음성 통화 기능
openclaw plugins install skill-workshop   # GUI에서 Skill 편집

# 설치된 Plugin 목록
openclaw plugins list --installed

# Plugin 비활성화/활성화
openclaw plugins disable memory-wiki
openclaw plugins enable memory-wiki

# Plugin 제거
openclaw plugins remove memory-wiki

# ClawHub에서 커뮤니티 Plugin URL로 직접 설치
openclaw plugins install https://clawhub.openclaw.ai/plugins/some-plugin

# 현재 토큰 확인
openclaw gateway token show

# 토큰 재생성 (기존 모든 클라이언트 연결 끊김)
openclaw gateway token rotate

# Control UI에서 토큰 입력 방법:
# 브라우저 → http://서버IP:18789 → Gateway 토큰 필드에 붙여넣기

# 토큰 포함 대시보드 URL 자동 생성 (복사해서 바로 접속)
openclaw dashboard --no-open

# Docker 환경에서 토큰 확인
docker compose --profile cli run --rm openclaw-cli gateway token show

# 승인 대기 중인 장치 목록
openclaw devices list

# 특정 장치 승인
openclaw devices approve b786149e-492d-431e-b696-e0d93f02d0e5

# 등록된 모든 장치 목록 (승인된 것 포함)
openclaw devices list --all

# 특정 장치 접근 취소
openclaw devices revoke [DEVICE_ID]

# 모든 장치 접근 취소 (토큰 재발급 포함)
openclaw devices revoke --all

# 1. Tailscale 설치
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# 2. Tailscale IP 확인
tailscale ip -4
# 예: 100.64.0.1

# 3. 온보딩 시 Gateway bind address → Tailnet 선택
# 또는 기존 설정 변경
openclaw config set gateway.bind "tailnet"

# 4. Gateway 재시작
openclaw gateway restart

# 5. Tailscale 네트워크 내 어디서나 접근 가능
# http://100.64.0.1:18789

{
  automation: {
    // ── Scheduled Tasks (Cron) ─────────────────────────
    scheduled: [
      {
        id: "morning-briefing",
        name: "아침 브리핑",
        // cron: 초 분 시 일 월 요일
        cron: "0 0 9 * * 1-5",    // 평일 오전 9시
        channel: "telegram",
        prompt: "오늘 날씨(서울)와 IT 주요 뉴스 3건을 한국어로 간결하게 요약해줘.",
        enabled: true,
      },
      {
        id: "weekly-report",
        name: "주간 작업 보고",
        cron: "0 0 18 * * 5",     // 매주 금요일 오후 6시
        channel: "slack",
        prompt: "이번 주 완료된 작업과 다음 주 계획을 정리해줘. workspace의 recent_tasks.md를 참고해.",
        enabled: true,
      }
    ],

    // ── Standing Orders ────────────────────────────────
    standingOrders: [
      {
        id: "error-monitor",
        name: "에러 로그 자동 분석",
        // 채널에서 특정 패턴 감지 시 자동 실행
        trigger: { pattern: "ERROR|Exception|Traceback", channel: "slack" },
        prompt: "다음 에러 로그를 분석하고 원인과 해결책을 제시해줘: {{message}}",
        enabled: true,
      }
    ],

    // ── Hooks ──────────────────────────────────────────
    hooks: {
      onSessionStart: {
        prompt: "새 대화가 시작됐습니다. 간단한 인사와 도움 가능한 내용을 한국어로 안내해줘."
      }
    }
  }
}

# 채팅에서 직접 자동화 등록 (자연어 지시)
사용자: "매일 오전 8시 30분에 오늘 날씨랑 KOSPI 지수 알려줘"
OpenClaw: 자동화 등록 완료! 매일 08:30에 실행됩니다.

사용자: "내 자동화 목록 보여줘"
OpenClaw: [현재 등록된 자동화 목록 표시]

사용자: "morning-briefing 자동화 일시정지해"
OpenClaw: morning-briefing이 비활성화되었습니다.

# CLI로 스케줄 관리
openclaw automation list
openclaw automation run morning-briefing    # 즉시 실행 테스트
openclaw automation disable morning-briefing
openclaw automation enable morning-briefing
openclaw automation delete morning-briefing

# ── 로그 조회 ──────────────────────────────────────────
# NPM 데몬 로그
openclaw logs --follow
openclaw logs --tail 100

# Docker 환경
docker compose logs -f openclaw-gateway
docker compose logs --tail=100 openclaw-gateway

# ── Gateway 상태 확인 ────────────────────────────────
openclaw gateway status
curl -fsS http://127.0.0.1:18789/healthz && echo " Gateway OK"
curl -fsS http://127.0.0.1:18789/readyz  && echo " Gateway Ready"

# ── 채널 연결 상태 ────────────────────────────────────
openclaw channels list
openclaw channels status telegram

# 채팅 테스트 (채널을 통해 자신에게 메시지 전송)
openclaw channels send --channel telegram --to @me --text "ping"

# ── 모델 연결 상태 ────────────────────────────────────
openclaw models list
openclaw models test --model ollama/gemma4:e4b --prompt "hi"

# ── 설정 검증 ─────────────────────────────────────────
openclaw config show
openclaw config validate  # 설정 파일 문법 오류 확인

# ── 전체 진단 리포트 ─────────────────────────────────
openclaw doctor  # 시스템 전체 점검 리포트 생성

# ── NPM 글로벌 설치 업데이트 ─────────────────────────
# 1. 현재 버전 확인
openclaw --version

# 2. Gateway 중지
openclaw gateway stop

# 3. 업데이트
npm update -g openclaw@latest

# 4. 재시작
openclaw gateway start

# ── Docker Compose 업데이트 ───────────────────────────
# 1. 새 이미지 미리 pull (다운타임 없이)
docker compose pull openclaw-gateway

# 2. 무중단 재시작
docker compose up -d --no-deps openclaw-gateway

# 3. 정상 기동 확인
docker compose logs -f openclaw-gateway

# ── 버전 고정 (Watchtower 등 자동 업데이트 방지) ─────
# docker-compose.yml labels에 추가:
# - "com.centurylinklabs.watchtower.enable=false"
#
# 또는 특정 버전 태그 사용:
# image: ghcr.io/openclaw/openclaw:2026.5.x

# ── 설정 백업 ─────────────────────────────────────────
BACKUP_DIR=~/backups/openclaw-$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

# NPM 설치 기준
cp ~/.openclaw/openclaw.json $BACKUP_DIR/
cp ~/.openclaw/.env          $BACKUP_DIR/
cp -r ~/.config/openclaw/    $BACKUP_DIR/auth/

echo "백업 완료: $BACKUP_DIR"

# Docker 볼륨 기준 (서비스 중 백업 가능)
docker run --rm \
  -v /경로/config:/data:ro \
  -v $BACKUP_DIR:/backup \
  alpine tar czf /backup/openclaw-config.tar.gz /data

# ── 다른 서버로 마이그레이션 ─────────────────────────
# 1. 위 방법으로 백업
# 2. 새 서버에 OpenClaw 설치 (onboard 실행)
# 3. openclaw.json 덮어쓰기 (model/channel/automation 설정 유지)
# 4. .env의 OPENCLAW_GATEWAY_TOKEN은 새로 생성 권장
# 5. auth/ 디렉터리 복원 (채널 토큰 재사용)
# 6. gateway restart → 채널 재연결 확인