OpenClaw v2026.2 적용 | 본 문서는 OpenClaw 설치를 완료했고, 사용 가능한 Telegram Bot Token(무료 획득)이 있다고 가정합니다.

TL;DR: Telegram은 설정이 가장 간단한 채널입니다: Bot 생성(@BotFather), Token 획득, ~/.openclaw/openclaw.json에 설정, Gateway 시작. 기본적으로 DM 페어링 보호가 활성화되며, 그룹에서는 @멘션 시에만 응답합니다. WhatsApp(QR 로그인), Discord(Bot Token), Slack 설정도 함께 다룹니다.

왜 Telegram부터 시작할까?

채널 비교

Telegram을 선택하는 이유

1. 설정이 가장 간단: Bot 생성 후 Token만 있으면 됨
2. 문서가 가장 완성도 높음: Telegram Bot API는 업계 표준
3. 기능이 가장 풍부: 명령어, 버튼, 인라인 쿼리 등 지원
4. 커뮤니티가 가장 활발: 문제 해결책을 쉽게 찾을 수 있음

Telegram Bot 생성

단계 1: BotFather 찾기

1. Telegram 앱 열기
2. @BotFather 검색(공식 Bot 관리 도구)
3. 대화 시작

sequenceDiagram
    participant U as 사용자
    participant BF as BotFather
    participant TG as Telegram
    
    U->>BF: /newbot
    BF->>U: Bot 표시 이름 입력
    U->>BF: My OpenClaw Assistant
    BF->>U: Bot 사용자명 입력(bot으로 끝나야 함)
    U->>BF: myclaw_bot
    BF->>TG: Bot 생성
    TG-->>BF: Bot 생성 완료
    BF->>U: API Token 반환

단계 2: 새 Bot 생성

BotFather에 명령 전송:

/newbot

안내에 따라 진행:

1. Bot 표시 이름: 예 My OpenClaw(공백 가능)
2. Bot 사용자명: 예 myclaw_bot(반드시 bot으로 끝나야 함)

생성 완료 후 BotFather가 반환:

Done! Congratulations on your new bot...

Use this token to access the HTTP API:
7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your token secure...

⚠️ 중요: API Token을 안전하게 보관하세요. Bot을 완전히 제어할 수 있는 권한을 가집니다.

단계 3: Bot 정보 설정 (선택)

# BotFather에서 Bot 프로필 사진 설정
/setuserpic
# Bot 선택, 이미지 업로드

# Bot 설명 설정
/setdescription
# Bot 선택, 설명 입력

# Bot 소개 설정
/setabouttext
# Bot 선택, 소개 입력

# Bot 명령어 설정
/setcommands
# 명령어 목록 입력, 예:
# start - 시작하기
# help - 도움말
# status - 상태 확인

OpenClaw 설정

방식 A: 환경 변수 (빠른 테스트)

# 환경 변수 설정
export TELEGRAM_BOT_TOKEN="7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Gateway 시작
openclaw gateway

방식 B: 설정 파일 (프로덕션 권장)

~/.openclaw/openclaw.json 편집:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "channels": {
    "telegram": {
      "botToken": "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

방식 C: CLI로 설정

# 대화형 설정
openclaw config set channels.telegram.botToken "7123456789:AAH..."

# 또는 onboard 마법사
openclaw onboard

설정 검증

# 설정 확인
openclaw config get channels.telegram.botToken

# 진단 실행
openclaw doctor

# Gateway 시작(디버그 모드)
openclaw gateway --verbose

성공적으로 시작되면 다음과 비슷한 로그가 보입니다:

[INFO] Gateway starting on port 18789
[INFO] Telegram channel connected
[INFO] Bot: @myclaw_bot
[INFO] Waiting for messages...

보안 설정

DM 페어링 메커니즘

기본적으로 OpenClaw는 DM 페어링 메커니즘(dmPolicy: "pairing")을 사용해 낯선 사람이 Bot을 남용하는 것을 방지합니다.

sequenceDiagram
    participant S as 낯선 사람
    participant B as Bot
    participant G as Gateway
    participant O as 사용자
    
    S->>B: "안녕" 메시지 전송
    B->>G: 메시지 도착
    G->>G: 페어링 상태 확인
    G-->>B: 미페어링, 페어링 코드 반환
    B-->>S: "페어링 필요: 코드 ABC123"
    S->>O: 페어링 코드 전달
    O->>G: openclaw pairing approve telegram ABC123
    G->>G: 화이트리스트에 추가
    G-->>S: 페어링 완료, 대화 가능

DM 정책 설정

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "dmPolicy": "pairing",
      "allowFrom": []
    }
  }
}

페어링 요청 관리

# 대기 중인 페어링 목록 확인
openclaw pairing list

# 출력 예:
# Channel    Code     User        Created
# telegram   ABC123   @stranger   2026-02-26 10:30:00

# 페어링 승인
openclaw pairing approve telegram ABC123

# 페어링 거절
openclaw pairing reject telegram ABC123

# 페어링된 사용자 확인
openclaw pairing show telegram

화이트리스트 모드

특정 사용자만 메시지 전송 허용:

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "dmPolicy": "open",
      "allowFrom": [123456789, 987654321]
    }
  }
}

💡 Telegram 사용자 ID 확인: @userinfobot에 아무 메시지나 보내면 숫자 ID를 반환합니다.

그룹 설정

기본 그룹 설정

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

다중 그룹 차별 설정

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "groups": {
        "-100123456789": {
          "requireMention": false,
          "name": "업무 그룹"
        },
        "-100987654321": {
          "requireMention": true,
          "name": "일상 그룹"
        },
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

💡 그룹 ID 확인: Bot을 그룹에 추가한 뒤, 그룹에서 아무 메시지나 보내면 Gateway 로그에서 그룹 ID를 확인할 수 있습니다.

그룹에 Bot 추가

1. 그룹 설정에서 “멤버 추가” 클릭
2. Bot 사용자명 검색(예: @myclaw_bot)
3. 추가 선택
4. (선택) Bot을 관리자로 설정해 더 많은 권한 부여

WhatsApp 설정

방식: QR 로그인

WhatsApp은 Web 프로토콜을 사용하며, QR 스캔으로 바인딩합니다:

# 로그인 절차 시작
openclaw channels login whatsapp

# 터미널에 QR 코드 표시
# 휴대폰 WhatsApp으로 스캔:
# 설정 > 연결된 기기 > 기기 연결 > QR 코드 스캔

sequenceDiagram
    participant U as 사용자
    participant C as CLI
    participant W as WhatsApp
    participant G as Gateway
    
    U->>C: openclaw channels login whatsapp
    C->>W: QR 코드 요청
    W-->>C: QR 코드 반환
    C->>U: QR 코드 표시
    U->>W: 휴대폰으로 스캔
    W-->>C: 인증 완료
    C->>G: 인증 정보 저장
    G-->>U: WhatsApp 연결됨

설정 예시

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

WhatsApp 제한사항

Discord 설정

Discord Bot 생성

1. Discord Developer Portal 접속
2. “New Application” 클릭
3. 이름 입력, 예: OpenClaw Assistant
4. “Bot” 페이지에서 “Add Bot” 클릭
5. Token 복사(Application ID 아님)

OAuth2 권한 설정

1. “OAuth2” > “URL Generator” 이동
2. 다음 권한 선택:

3. 생성된 초대 링크 복사
4. 브라우저에서 링크 열어 Bot을 서버에 초대

설정 예시

{
  "channels": {
    "discord": {
      "token": "MTk4NjIyNDgzNDc...",
      "guilds": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

Discord 특성 설정

{
  "channels": {
    "discord": {
      "token": "your_token",
      "commands": {
        "native": true,
        "text": true
      },
      "mediaMaxMb": 25
    }
  }
}

Slack 설정

Slack App 생성

1. Slack API 접속
2. “Create New App” 클릭
3. “From scratch” 선택
4. App 이름 입력, 워크스페이스 선택

OAuth 권한 설정

“OAuth & Permissions” 페이지에서 다음 Bot Token Scopes 추가:

app_mentions:read
channels:history
channels:read
chat:write
files:read
files:write
groups:history
groups:read
im:history
im:read
im:write
mpim:history
mpim:read
mpim:write
reactions:read
reactions:write
users:read

워크스페이스에 설치

1. “Install to Workspace” 클릭
2. 권한 승인
3. Bot User OAuth Token 복사(xoxb-로 시작)

설정 예시

{
  "channels": {
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "signingSecret": "..."
    }
  }
}

Socket Mode 활성화 (권장)

1. “Socket Mode” 페이지에서 활성화
2. App-Level Token 생성
3. OpenClaw에 설정:

{
  "channels": {
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "socketMode": true
    }
  }
}

다중 채널 동시 활성화

전체 설정 예시

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback"
  },
  "channels": {
    "telegram": {
      "botToken": "telegram_bot_token",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"]
    },
    "discord": {
      "token": "discord_token",
      "guilds": {
        "*": { "requireMention": true }
      }
    },
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-..."
    }
  }
}

메시지 라우팅 개요

flowchart TB
    subgraph Users["사용자"]
        WA[WhatsApp 사용자]
        TG[Telegram 사용자]
        DC[Discord 사용자]
        SL[Slack 사용자]
    end
    
    subgraph Gateway["Gateway"]
        MR[메시지 라우터]
        SM[세션 매니저]
    end
    
    subgraph Agent["Pi Agent"]
        AI[AI 코어]
        CTX[공유 컨텍스트]
    end
    
    WA --> MR
    TG --> MR
    DC --> MR
    SL --> MR
    MR --> SM
    SM --> AI
    AI --> CTX

모든 채널이 동일한 Agent를 공유하며, 컨텍스트는 통합 관리됩니다. 즉:

• Telegram에서 한 질문을 WhatsApp에서 이어서 논의할 수 있음
• 채널별 사용자가 동일한 기억을 공유할 수 있음
• 채널별로 독립적인 세션 격리 정책 적용 가능

세션 관리 명령어

모든 채널 공통 명령어(채팅에서 전송):

문제 해결

Telegram Bot 무응답

증상: 메시지 전송 후 응답 없음

확인 단계:

# 1. Gateway 실행 여부 확인
curl http://127.0.0.1:18789/health

# 2. Bot Token 확인
openclaw config get channels.telegram.botToken

# 3. 상세 로그 확인
openclaw gateway --verbose

# 4. doctor 진단
openclaw doctor

일반 원인:

WhatsApp QR 스캔 실패

증상: 스캔 후 실패 표시

해결 방법:

# QR 코드 재생성
openclaw channels logout whatsapp
openclaw channels login whatsapp

# 네트워크 확인
ping web.whatsapp.com

# 인증 캐시 삭제
rm -rf ~/.openclaw/credentials/whatsapp*

Discord Bot 권한 없음

증상: 서버에서 Bot이 응답하지 않거나 권한 없음

해결 방법:

1. Bot 역할 권한 확인
2. Bot이 서버에 초대되었는지 확인
3. 올바른 OAuth URL로 Bot 재초대

# 로그에서 권한 오류 확인
openclaw gateway --verbose 2>&1 | grep -i permission

설정 미적용

증상: 설정 변경 후 동작이 바뀌지 않음

해결 방법:

# 1. Gateway 재시작
openclaw gateway --restart

# 2. 캐시 삭제
rm -rf ~/.openclaw/cache/*

# 3. 설정 파일 문법 검증
cat ~/.openclaw/openclaw.json | jq .

# 4. 설정 우선순위 확인
openclaw config list

보안 모범 사례

1. Token 보안

# Token을 버전 관리에 커밋하지 마세요
echo ".openclaw/" >> .gitignore

# 환경 변수로 민감 정보 저장
export TELEGRAM_BOT_TOKEN="your_token"

# Token 정기 교체(BotFather에서)
# /revoke 명령으로 Token 재생성 가능

2. 접근 제어

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": [],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

3. 로그 감사

# 상세 로그 활성화
openclaw gateway --verbose

# 세션 기록 확인
openclaw sessions list
openclaw sessions show <session-id>

# 명령 실행 감사
grep "bash" ~/.openclaw/logs/gateway.log

다음 단계

첫 채널 설정을 마쳤습니다. 이제 다음을 진행하세요:

1. 대화 테스트 → 설정한 채널에서 메시지 전송
2. Skills 설치 → AI 기능 확장
3. 다중 채널 설정 → 채널 추가

본 편 요약:

• Telegram Bot 생성 및 설정 방법 파악
• DM 페어링과 그룹 설정 이해
• WhatsApp, Discord, Slack 설정 방법 학습
• 다중 채널 동시 활성화 방식 이해
• 일반적인 문제 해결 방법 파악

업데이트 기록:

• 2026-02-26: 초판 발행, OpenClaw v2026.2 기준

시리즈 네비게이션:

• ← 이전: 환경 구축과 첫 실행
• → 다음: Gateway 핵심 개념 해설