OpenClaw LINE 연결 튜토리얼

서문

LINE은 일본, 태국, 대만 등 지역에서 가장 주류인 인스턴트 메시징 앱입니다. OpenClaw를 LINE에 연결하면 지능형 챗봇을 만들어 친구의 메시지에 자동 응답하거나 그룹에서 AI 서비스를 제공할 수 있습니다. 이 글에서는 LINE Developers 콘솔 설정부터 단계별로 전체 연동 과정을 완료합니다.

사전 조건

OpenClaw가 설치되어 정상적으로 실행 중
LINE 계정을 보유하고 있음
OpenClaw 서비스가 공인 HTTPS 주소로 접근 가능 (LINE Webhook은 HTTPS 필수)

1단계: LINE Messaging API 채널 생성

1.1 LINE Developers 계정 등록

LINE Developers에 접속합니다
LINE 계정으로 로그인합니다
최초 로그인 시 개발자 약관에 동의하고 Provider를 생성해야 합니다

1.2 Provider 생성

Provider는 채널(Channel)을 관리하는 최상위 조직 단위입니다:

LINE Developers Console에서 Create a new provider를 클릭합니다
Provider 이름을 입력합니다 (예: "My OpenClaw Bot")
Create를 클릭합니다

1.3 Messaging API Channel 생성

Provider 페이지에서 Create a Messaging API channel을 클릭합니다
다음 정보를 입력합니다:

필드	설명	예시
Channel type	Messaging API 선택	Messaging API
Channel name	봇 표시 이름	AI 어시스턴트
Channel description	봇 설명	OpenClaw 기반 지능형 어시스턴트
Category	카테고리 선택	도구/유틸리티
Subcategory	하위 카테고리 선택	챗봇
Email address	연락처 이메일	[email protected]

약관에 동의하고 Create를 클릭합니다

1.4 필요한 자격 증명 획득

생성 완료 후 두 가지 핵심 정보를 기록해야 합니다:

Channel Secret: Basic settings 탭에서 확인할 수 있습니다.

Channel Access Token:

Messaging API 탭으로 이동합니다
하단의 Channel access token 영역까지 스크롤합니다
Issue 버튼을 클릭하여 장기 Token을 생성합니다
복사하여 안전하게 보관합니다

Channel Secret: abc123def456ghi789jkl012
Channel Access Token: eyJhbGciOiJIUzI1NiJ9.xxxxx.xxxxx (매우 긴 문자열)

2단계: Webhook 설정

2.1 Webhook URL 설정

Messaging API 탭에서:

Webhook settings 영역을 찾습니다
Edit 버튼을 클릭합니다
Webhook URL을 입력합니다:

https://your-domain.com/webhook/line

Update를 클릭합니다
Use webhook 스위치를 활성화합니다

2.2 Webhook 검증

Verify 버튼을 클릭하여 Webhook 연결을 테스트합니다. OpenClaw가 이미 설정되어 실행 중이라면 Success가 표시되어야 합니다.

2.3 자동 응답 비활성화

Messaging API 탭에서:

LINE Official Account features 영역을 찾습니다
Auto-reply messages 옆의 Edit 링크를 클릭합니다
LINE Official Account Manager로 이동합니다
자동 응답 메시지를 비활성화합니다 (그렇지 않으면 OpenClaw의 응답과 충돌합니다)
인사 메시지도 비활성화합니다 (선택 사항, LINE의 기본 인사를 유지할 수도 있습니다)

3단계: OpenClaw 설정

3.1 설정 파일 방식

~/.config/openclaw/openclaw.json5를 편집합니다:

{
  channels: {
    line: {
      enabled: true,
      // Channel Secret (Basic settings에서 획득)
      channelSecret: "abc123def456ghi789jkl012",
      // Channel Access Token (Messaging API에서 생성)
      channelAccessToken: "eyJhbGciOiJIUzI1NiJ9.xxxxx.xxxxx",

      // Webhook 경로 (LINE 콘솔 설정과 일치해야 함)
      webhookPath: "/webhook/line",

      // 메시지 처리 설정
      message: {
        // 응답 방식: "reply"는 Reply API 사용 (무료), "push"는 Push API 사용 (유료 가능)
        replyMode: "reply",
        // 그룹 메시지 지원 여부
        groupEnabled: true,
        // 그룹에서의 트리거 방식
        groupTrigger: "mention",  // "mention" | "keyword" | "all"
        // 그룹 트리거 키워드 (groupTrigger가 "keyword"일 때 적용)
        groupKeywords: ["@AI", "/ask"]
      },

      // 응답 형식
      reply: {
        // 긴 메시지 자동 분할
        maxLength: 5000,
        // Flex Message 형식 사용 여부 (더 보기 좋음)
        useFlexMessage: false,
        // 메시지 전송 전 대기 표시
        loadingAnimation: true
      }
    }
  }
}

3.2 환경 변수 방식

export LINE_CHANNEL_SECRET="abc123def456ghi789jkl012"
export LINE_CHANNEL_ACCESS_TOKEN="eyJhbGciOiJIUzI1NiJ9.xxxxx.xxxxx"

3.3 재시작 및 확인

openclaw restart

# 연결 로그 확인
openclaw logs -f --component channel:line

성공 로그:

[INFO] [channel:line] LINE Messaging API 채널이 시작되었습니다
[INFO] [channel:line] Webhook 경로: /webhook/line
[INFO] [channel:line] Bot 이름: AI 어시스턴트
[INFO] [channel:line] 메시지 수신 대기 중...

Reply API와 Push API

LINE에는 두 가지 메시지 전송 API가 있으며, 그 차이를 이해하는 것이 중요합니다:

Reply API

트리거 방식: 사용자 메시지 수신 후에만 사용 가능
시간 제한: Reply Token 유효 기간 약 30초
비용: 완전 무료
제한: 각 이벤트당 한 번만 응답 가능

Push API

트리거 방식: 사용자에게 능동적으로 메시지 전송 가능
시간 제한: 제한 없음
비용: 무료 플랜 월 200건, 초과 시 유료
제한: 구독 플랜에 따라 다름

{
  channels: {
    line: {
      message: {
        // 비용 절감을 위해 reply 모드 사용 권장
        replyMode: "reply",
        // 지연 응답이 필요한 경우 (시간이 오래 걸리는 작업 처리) push를 폴백으로 활성화
        fallbackToPush: true
      }
    }
  }
}

메시지 쿼터

플랜	Push API 메시지 수/월	비용
Free	200건	무료
Light	5,000건	약 800 TWD/월
Standard	25,000건	약 4,000 TWD/월
Pro	맞춤형	LINE에 문의

Reply API의 메시지는 쿼터에 포함되지 않으므로 Reply 모드를 우선 사용하는 것을 권장합니다.

Rich Menu 설정

Rich Menu는 LINE Bot 하단의 사용자 정의 메뉴로, 빠른 조작 입구를 제공할 수 있습니다.

Rich Menu 생성

LINE Official Account Manager에서 생성합니다:

채팅 → 리치 메뉴로 이동합니다
생성을 클릭합니다
메뉴 레이아웃을 설계합니다. 일반적인 옵션:

┌─────────┬─────────┬─────────┐
│         │         │         │
│  질문   │  번역   │  요약   │
│         │         │         │
├─────────┼─────────┼─────────┤
│         │         │         │
│  초기화 │  모델   │  도움말 │
│         │         │         │
└─────────┴─────────┴─────────┘

각 영역의 동작 유형을 텍스트로 설정하고 해당 트리거 명령을 입력합니다

API를 통한 Rich Menu 생성

OpenClaw 설정에서 Rich Menu를 정의할 수도 있습니다:

{
  channels: {
    line: {
      richMenu: {
        enabled: true,
        areas: [
          { label: "질문", action: "/ask" },
          { label: "번역", action: "/translate" },
          { label: "요약", action: "/summarize" },
          { label: "대화 초기화", action: "/reset" },
          { label: "모델 전환", action: "/model" },
          { label: "도움말", action: "/help" }
        ]
      }
    }
  }
}

그룹 사용

Bot을 그룹에 추가

LINE에서 그룹을 엽니다
그룹 설정 → 초대를 클릭합니다
Bot을 검색하여 추가합니다

그룹 동작 설정

{
  channels: {
    line: {
      group: {
        // 그룹 참가 시 환영 메시지
        welcomeMessage: "안녕하세요, AI 어시스턴트입니다! @멘션 또는 /ask로 시작하면 질문에 답변해 드립니다.",
        // 그룹에서 퇴장 시 데이터 정리
        cleanOnLeave: true,
        // 그룹별 독립 컨텍스트
        separateContext: true
      }
    }
  }
}

HTTPS 요구사항

LINE Webhook은 HTTPS를 강제합니다. 아직 HTTPS를 설정하지 않은 경우 다음 방법을 사용할 수 있습니다:

방식 1: Nginx 리버스 프록시 + Let's Encrypt

# certbot 설치
sudo apt install certbot python3-certbot-nginx

# 인증서 발급
sudo certbot --nginx -d your-domain.com

방식 2: ngrok 터널 (개발 테스트용)

# ngrok 설치
npm install -g ngrok

# 터널 생성
ngrok http 18789

ngrok에서 생성된 HTTPS 주소를 LINE Webhook URL에 입력합니다.

방식 3: Cloudflare Tunnel

cloudflared tunnel --url http://localhost:18789

문제 해결

Webhook 검증 실패

# OpenClaw가 실행 중인지 확인
openclaw logs --level error

# Webhook 경로가 올바른지 확인
curl -X POST https://your-domain.com/webhook/line -d '{}' -H "Content-Type: application/json"

# SSL 인증서가 유효한지 확인
openssl s_client -connect your-domain.com:443

Bot이 메시지에 응답하지 않음

# Channel Access Token이 유효한지 확인
openclaw logs --component channel:line --level debug

# 일반적인 원인:
# 1. Token이 만료됨 - 새 Token을 발급
# 2. 자동 응답이 비활성화되지 않음 - LINE의 자동 응답이 Reply Token을 소비
# 3. Reply Token 타임아웃 - AI 모델 응답이 너무 느림 (>30초)

Reply Token 타임아웃

AI 모델 응답 시간이 30초를 초과하면 Reply Token이 만료됩니다. 해결 방안:

{
  channels: {
    line: {
      message: {
        replyMode: "reply",
        fallbackToPush: true,  // Reply 실패 시 Push API로 전환
        // 또는 먼저 "처리 중" 응답을 전송
        thinkingMessage: "생각 중입니다, 잠시만 기다려 주십시오..."
      }
    }
  }
}

요약

LINE 연동의 핵심 단계:

LINE Developers에서 Messaging API 채널 생성
Channel Secret과 Channel Access Token 획득
HTTPS Webhook URL 설정
OpenClaw 설정 파일에 자격 증명 입력
LINE의 자동 응답 기능 비활성화
서비스 재시작 및 테스트

비용 절감을 위해 Reply API를 우선 사용하고 Rich Menu를 통해 사용자 경험을 향상시키는 것을 권장합니다.