LINE Messaging API를 OpenClaw에 연결하기

메시징 앱을 연동할 때마다 API 문서를 뒤지고 복잡한 인증 절차를 거치는 일은 정말 피곤하죠. 특히 보안이 까다로운 LINE 같은 플랫폼은 더 그렇습니다. OpenClaw의 LINE 플러그인을 사용하면 이런 번거로운 과정을 줄이고 핵심 기능에 집중할 수 있어요.

LINE (plugin)

LINE은 LINE Messaging API를 통해 OpenClaw와 연결됩니다. 이 플러그인은 Gateway에서 webhook receiver로 동작하며, 인증을 위해 channel access token과 channel secret을 사용해요.

상태: 플러그인을 통해 지원됩니다. 1:1 메시지, 그룹 채팅, 미디어, 위치 정보, Flex 메시지, 템플릿 메시지, 그리고 quick replies를 지원해요. Reactions와 threads는 지원하지 않습니다.

플러그인 설치

먼저 LINE 플러그인을 설치하세요:

openclaw plugins install @openclaw/line

로컬 환경에서 실행하는 경우(git repo 기준):

openclaw plugins install ./path/to/local/line-plugin

설정하기

LINE Developers 계정을 생성하고 Console을 여세요: https://developers.line.biz/console/
Provider를 생성(또는 선택)하고 Messaging API 채널을 추가하세요.
채널 설정에서 Channel access token과 Channel secret을 복사하세요.
Messaging API 설정에서 Use webhook을 활성화하세요.
Webhook URL을 Gateway 엔드포인트로 설정하세요 (HTTPS 필수):

https://gateway-host/line/webhook

Gateway는 LINE의 webhook verification (GET)과 inbound events (POST)에 응답합니다. 커스텀 경로가 필요한 경우 channels.line.webhookPath 또는 channels.line.accounts.<id>.webhookPath를 설정하고 URL을 그에 맞게 업데이트하세요.

보안 참고 사항:

LINE 서명 검증은 본문 내용에 의존하므로(raw body에 대한 HMAC), OpenClaw는 검증 전에 엄격한 pre-auth body 제한 및 타임아웃을 적용합니다.
OpenClaw는 검증된 raw request bytes를 사용하여 webhook 이벤트를 처리해요. 서명 무결성 보안을 위해 업스트림 미들웨어에서 변환된 req.body 값은 무시합니다.

구성하기

최소 설정 예시입니다:

{
  channels: {
    line: {
      enabled: true,
      channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
      channelSecret: "LINE_CHANNEL_SECRET",
      dmPolicy: "pairing",
    },
  },
}

환경 변수 설정 (기본 계정 전용):

LINE_CHANNEL_ACCESS_TOKEN
LINE_CHANNEL_SECRET

Token/secret 파일 사용 시:

{
  channels: {
    line: {
      tokenFile: "/path/to/line-token.txt",
      secretFile: "/path/to/line-secret.txt",
    },
  },
}

tokenFile과 secretFile은 반드시 일반 파일을 가리켜야 합니다. 심볼릭 링크는 거부됩니다.

다중 계정 설정:

{
  channels: {
    line: {
      accounts: {
        marketing: {
          channelAccessToken: "...",
          channelSecret: "...",
          webhookPath: "/line/marketing",
        },
      },
    },
  },
}

액세스 제어

1:1 메시지(DM)는 기본적으로 pairing 방식을 사용합니다. 알 수 없는 발신자에게는 페어링 코드가 발송되며, 승인될 때까지 해당 메시지는 무시됩니다.

openclaw pairing list line
openclaw pairing approve line <CODE>

허용 목록 및 정책:

channels.line.dmPolicy: pairing | allowlist | open | disabled
channels.line.allowFrom: DM을 허용할 LINE user ID 목록
channels.line.groupPolicy: allowlist | open | disabled
channels.line.groupAllowFrom: 그룹 참여를 허용할 LINE user ID 목록
그룹별 오버라이드: channels.line.groups.<groupId>.allowFrom
런타임 참고: channels.line 설정이 완전히 누락된 경우, 런타임은 그룹 체크 시 groupPolicy="allowlist"를 기본값으로 사용합니다 (channels.defaults.groupPolicy가 설정되어 있더라도 적용됨).

LINE ID는 대소문자를 구분합니다. 유효한 ID 형식은 다음과 같아요:

User: U + 32자리 16진수
Group: C + 32자리 16진수
Room: R + 32자리 16진수

메시지 동작 방식

텍스트는 5000자 단위로 나뉩니다.
Markdown 서식은 제거되며, 코드 블록과 테이블은 가능한 경우 Flex 카드로 변환됩니다.
스트리밍 응답은 버퍼링됩니다. 에이전트가 작업하는 동안 LINE 사용자는 로딩 애니메이션과 함께 완성된 메시지 덩어리를 받게 됩니다.
미디어 다운로드 용량은 channels.line.mediaMaxMb에 의해 제한됩니다 (기본값 10).

채널 데이터 (리치 메시지)

channelData.line을 사용하여 quick replies, 위치 정보, Flex 카드 또는 템플릿 메시지를 보낼 수 있습니다.

{
  text: "Here you go",
  channelData: {
    line: {
      quickReplies: ["Status", "Help"],
      location: {
        title: "Office",
        address: "123 Main St",
        latitude: 35.681236,
        longitude: 139.767125,
      },
      flexMessage: {
        altText: "Status card",
        contents: {
          /* Flex payload */
        },
      },
      templateMessage: {
        type: "confirm",
        text: "Proceed?",
        confirmLabel: "Yes",
        confirmData: "yes",
        cancelLabel: "No",
        cancelData: "no",
      },
    },
  },
}

LINE 플러그인은 Flex 메시지 프리셋을 위한 /card 명령어도 제공해요:

/card info "Welcome" "Thanks for joining!"

ACP 지원

LINE은 ACP (Agent Communication Protocol) 대화 바인딩을 지원합니다:

/acp spawn <agent> --bind here 명령은 하위 스레드를 생성하지 않고 현재 LINE 채팅을 ACP 세션에 바인딩합니다.
설정된 ACP 바인딩과 활성화된 대화 바인딩 ACP 세션은 다른 대화 채널과 마찬가지로 LINE에서 정상적으로 작동합니다.

자세한 내용은 ACP agents 문서를 확인하세요.

아웃바운드 미디어

LINE 플러그인은 에이전트 메시지 도구를 통해 이미지, 비디오, 오디오 파일 전송을 지원합니다. 미디어는 미리보기 및 트래킹 처리가 포함된 LINE 전용 경로를 통해 전송됩니다:

이미지: 자동 미리보기 생성 기능이 포함된 LINE 이미지 메시지로 전송됩니다.
비디오: 명시적인 미리보기 및 content-type 처리와 함께 전송됩니다.
오디오: LINE 오디오 메시지로 전송됩니다.

LINE 전용 경로를 사용할 수 없는 일반적인 미디어 전송의 경우, 기존의 이미지 전용 경로를 사용하게 됩니다.

문제 해결

Webhook 검증 실패: Webhook URL이 HTTPS인지, 그리고 channelSecret이 LINE console의 값과 일치하는지 확인하세요.
인바운드 이벤트 없음: Webhook 경로가 channels.line.webhookPath와 일치하는지, 그리고 LINE에서 Gateway에 접속 가능한지 확인하세요.
미디어 다운로드 오류: 미디어 파일이 기본 제한을 초과하는 경우 channels.line.mediaMaxMb 값을 높이세요.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.