LINE 설정

Hermes 에이전트를 공식 LINE Messaging API를 통해 LINE 봇으로 실행합니다. 어댑터는 plugins/platforms/line/ 아래의 번들된 플랫폼 플러그인으로 존재하며 — 핵심 수정은 필요 없고, 다른 플랫폼처럼 활성화하기만 하면 됩니다.

LINE은 일본, 대만, 태국에서 가장 많이 사용되는 메신저 앱입니다. 사용자가 그곳에 있다면, 이 방법으로 여러분에게 접근합니다.

봇의 응답 방식

컨텍스트	행동
1:1 채팅 (`U` ID)	모든 메시지에 응답
그룹 채팅 (`C` ID)	그룹이 허용 목록에 있을 때 응답합니다
다중 사용자 방 (`R` ID)	방이 허용 목록에 있을 때 응답합니다

수신 텍스트, 이미지, 오디오, 비디오, 파일, 스티커, 위치가 모두 처리됩니다. 발신 텍스트는 무료 응답 토큰을 먼저 사용(단일 사용, 약 60초 유효)하며, 토큰이 만료되면 계량형 Push API로 대체됩니다.

단계 1: LINE 메시징 API 채널 생성

LINE Developers Console로 이동하세요.
프로바이더를 생성한 후, 그 아래에 메시징 API 채널을 만듭니다.
채널의 기본 설정탭에서채널 비밀을 복사하세요.
Messaging API탭에서 아래로 스크롤하여**채널 액세스 토큰(장기)**을 찾고 발급을 클릭합니다. 토큰을 복사합니다.
메시징 API탭에서자동응답 메시지와 인사말 메시지도 비활성화하여 봇의 응답과 충돌하지 않도록 하세요.

2단계: 웹훅 포트 노출

LINE은 공개 HTTPS를 통해 웹후크를 전달합니다. 기본 포트는 8646이며, 필요 시 LINE_PORT로 변경할 수 있습니다.

# Cloudflare Tunnel (recommended for production — fixed hostname)
cloudflared tunnel --url http://localhost:8646

# ngrok (good for dev)
ngrok http 8646

# devtunnel
devtunnel create hermes-line --allow-anonymous
devtunnel port create hermes-line -p 8646 --protocol https
devtunnel host hermes-line

https://... URL을 복사하세요 — 아래에서 웹훅 URL로 설정할 것입니다. 테스트하는 동안 터널을 계속 실행하세요. 운영 환경에서는 웹훅 URL이 재시작 시 변경되지 않도록 고정된 Cloudflare 명명 터널을 설정하세요.

3단계: Hermes 구성

~/.hermes/.env에 추가:

LINE_CHANNEL_ACCESS_TOKEN=YOUR_LONG_LIVED_TOKEN
LINE_CHANNEL_SECRET=YOUR_CHANNEL_SECRET

# Allowlist — at least one of these (or LINE_ALLOW_ALL_USERS=true for dev)
LINE_ALLOWED_USERS=U1234567890abcdef...           # comma-separated U-prefixed IDs
LINE_ALLOWED_GROUPS=C1234567890abcdef...          # optional group IDs
LINE_ALLOWED_ROOMS=R1234567890abcdef...           # optional room IDs

# Required for image / audio / video sends — the public HTTPS base URL
# the tunnel resolves to.  Without it, send_image/voice/video will refuse.
LINE_PUBLIC_URL=https://my-tunnel.example.com

그런 다음 ~/.hermes/config.yaml에서:

gateway:
  platforms:
    line:
      enabled: true

그걸로 충분합니다 — gateway/config.py의 번들 플러그인 스캔이 자동으로 plugins/platforms/line/를 감지합니다. Platform.LINE 열거형 편집도, _create_adapter 등록도 필요 없습니다.

4단계: 웹훅 URL 설정

다시 LINE 콘솔로 돌아가서:

채널을 열고 → Messaging API 탭으로 이동하세요.
웹훅 설정 → 웹훅 URL에서 https://<your-tunnel>/line/webhook를 붙여넣으세요 (/line/webhook 경로를 참고하세요 — 어댑터가 해당 경로를 청취합니다).
확인을 클릭하세요. LINE이 URL에 핑을 보내면, 200이 보여야 합니다.
웹훅 사용을 켬으로 전환하세요.

5단계: 게이트웨이를 실행하세요

hermes gateway

에이전트 로그에 다음과 같이 표시됩니다:

LINE: webhook listening on 0.0.0.0:8646/line/webhook (public: https://my-tunnel.example.com)

LINE 앱에서 봇을 친구로 추가하세요(채널의 Messaging API 탭에 있는 QR 코드를 스캔)하고 메시지를 보내세요.

느린 LLM 응답

LINE의 응답 토큰은 단일 사용이며, 수신 이벤트 후 약 60초 후에 만료됩니다. 느린 LLM은 제시간에 응답할 수 없으며, 이는 일반적으로 유료 푸시 API 호출을 강제하게 됩니다.

LLM이 여전히 LINE_SLOW_RESPONSE_THRESHOLD초(기본값 45) 이상 실행 중일 때, 어댑터는 템플릿 버튼 버블을 보내기 위해 원래 응답 토큰을 사용합니다:

🤔 아직 생각 중입니다. 준비되면 답을 가져오려면 아래를 누르세요.

[ 답변 받기 ]

사용자는 편할 때 답변 받기를 탭합니다 — 해당 포스트백은 새로운 답변 토큰을 전달하며, 어댑터는 이를 사용하여 캐시된 답변(여전히 무료)을 전송합니다.

상태 기계: PENDING → READY → DELIVERED, 취소된 실행에 대해서는 ERROR 추가 (/stop 후에 고아 PENDING은 "실행이 완료되기 전에 중단되었습니다."로 해결되어 지속적인 버튼이 반복되지 않음).

포스트백 버튼을 비활성화하고 항상 푸시-폴백을 사용하려면:

LINE_SLOW_RESPONSE_THRESHOLD=0

포스트백 흐름이 안정적으로 작동하려면, 임계값에 도달하기 전에 reply token을 소비하는 중간 대화를 줄이세요:

# ~/.hermes/config.yaml
display:
  interim_assistant_messages: false
  platforms:
    line:
      tool_progress: off

크론 / 알림 전달

LINE_HOME_CHANNEL=Uxxxxxxxxxxxxxxxxxxxx     # default delivery target

deliver: line가 있는 크론 작업은 LINE_HOME_CHANNEL로 라우팅됩니다. 어댑터는 독립 실행형 푸시 전용 송신기를 제공하므로 크론이 게이트웨이와 별도의 프로세스에서 실행되더라도 크론 작업이 작동합니다.

환경 변수 참조

변수	필수	기본값	설명
`LINE_CHANNEL_ACCESS_TOKEN`	예	—	장수 채널 액세스 토큰
`LINE_CHANNEL_SECRET`	예	—	채널 시크릿 (HMAC-SHA256 웹훅 검증)
`LINE_HOST`	no	`0.0.0.0`	웹훅 바인드 호스트
`LINE_PORT`	no	`8646`	웹훅 바인드 포트
`LINE_PUBLIC_URL`	미디어용	—	공용 HTTPS 기본 URL; 이미지/음성/동영상 전송에 필요
`LINE_ALLOWED_USERS`	중 하나	—	쉼표로 구분된 사용자 ID (U로 시작)
`LINE_ALLOWED_GROUPS`	~중 하나	—	쉼표로 구분된 그룹 ID(C로 시작)
`LINE_ALLOWED_ROOMS`	중 하나	—	쉼표로 구분된 방 ID (R로 시작)
`LINE_ALLOW_ALL_USERS`	개발 전용	`false`	허용 목록 전체 건너뛰기
`LINE_HOME_CHANNEL`	no	—	기본 크론 / 알림 전송 대상
`LINE_SLOW_RESPONSE_THRESHOLD`	no	`45`	포스트백 버튼이 실행되기 직전 (`0` = 비활성화됨)
`LINE_PENDING_TEXT`	no	🤔 아직 생각 중…	게시 버튼 옆에 표시되는 버블 텍스트
`LINE_BUTTON_LABEL`	no	답을 얻다	버튼 레이블
`LINE_DELIVERED_TEXT`	no	이미 답장함 ✅	이미 전달된 버튼을 다시 탭할 때 응답
`LINE_INTERRUPTED_TEXT`	no	실행이 완료되기 전에 중단되었습니다.	`/stop` 고아 버튼이 눌렸을 때 응답

문제 해결

웹훅 검증에서 '잘못된 서명(invalid signature)'입니다. Channel secret가 잘못 복사되었거나, 터널이 요청 본문을 변경했습니다. 먼저 curl -i https://<tunnel>/line/webhook/health로 확인하세요 — 그러면 {"status":"ok","platform":"line"}가 반환되어야 합니다.

봇은 그룹에서 아무 것도 받지 않습니다. LINE_ALLOWED_GROUPS에 C... 그룹 ID가 포함되어 있는지 확인하세요. 그룹 ID를 찾으려면 테스트 메시지를 보내고 ~/.hermes/logs/gateway.log에서 LINE: rejecting unauthorized source을 검색하세요 — 거부된 소스 사전에 ID가 있습니다.

send_image가 'LINE_PUBLIC_URL must be set' 오류로 실패합니다. LINE의 메시징 API는 바이너리 업로드를 허용하지 않습니다 — 이미지, 오디오, 비디오는 HTTPS URL을 통해 접근 가능해야 합니다. LINE_PUBLIC_URL을 터널의 공개 호스트명으로 설정하면 어댑터가 /line/media/<token>/<filename>에서 파일을 자동으로 제공할 것입니다.

포스트백 버튼이 전혀 나타나지 않습니다. LLM이 LINE_SLOW_RESPONSE_THRESHOLD보다 빠르게 응답했거나, 다른 버블(도구 진행, 스트리밍)이 먼저 응답 토큰을 사용했을 수 있습니다. '느린 LLM 응답' 아래의 억제 블록을 참조하세요.

"다른 프로필에서 이미 사용 중입니다." 동일한 채널 액세스 토큰이 다른 실행 중인 Hermes 프로필에 연결되어 있습니다. 다른 게이트웨이를 중지하거나 별도의 채널을 사용하세요.

제한 사항

청크당 단일 말풍선. 각 LINE 텍스트 말풍선은 5000자로 제한되며, 한 Reply/Push 호출당 최대 5개의 말풍선이 전송됩니다. 더 긴 응답은 줄임표(...)로 잘립니다.
원본 메시지 편집 금지. LINE에는 메시지 편집 API가 없습니다 — 스트리밍 응답은 항상 새로운 버블을 보내며 이전 메시지를 편집하지 않습니다.
마크다운 렌더링 없음. 굵게(**), 기울임(*), 코드 블록, 및 제목은 문자 그대로 렌더링됩니다. 어댑터는 전송 전에 이를 제거합니다; URL은 유지됩니다 ([label](url)가 label (url)으로 변경됨).
로딩 표시기는 DM 전용입니다. LINE은 그룹 및 채팅방에 대한 채팅/로딩 API를 허용하지 않으므로, 입력 표시기는 1:1 채팅에서만 표시됩니다.

봇의 응답 방식​

단계 1: LINE 메시징 API 채널 생성​

2단계: 웹훅 포트 노출​

3단계: Hermes 구성​

4단계: 웹훅 URL 설정​

5단계: 게이트웨이를 실행하세요​

느린 LLM 응답​

크론 / 알림 전달​

환경 변수 참조​

문제 해결​

제한 사항​