Hermes/OpenClaw에 카카오톡 연동하기

Hermes나 OpenClaw를 사용하다 보면 텔레그램뿐 아니라 카카오톡에서도 에이전트를 사용하고 싶어집니다. 공식 봇을 새로 만드는 방식보다, 내가 사용하는 카카오톡 계정으로 채팅방을 조회하고 메시지를 보내는 방식이 필요한 경우도 있습니다.

이 글에서는 Hermes Agent를 사용했지만, CLI를 실행할 수 있는 다른 에이전트 도구에서도 같은 방식으로 연동할 수 있습니다.

처음에는 Agent Messenger 오픈소스와 카카오톡 자동화 사례를 참고해, 카카오톡 연동 후 채팅방 목록을 확인하고 테스트 메시지까지 보내는 것을 목표로 시작했습니다.

실제로는 처음부터 순조롭게 연결되지는 않았습니다. 첫 시도에서는 카카오톡 연동에 필요한 설치를 끝내지 못해 작업이 멈췄고, 이후에는 패키지명과 실행 파일명의 차이, 라이브러리 버전과 Bun의 bson 호환 문제를 차례로 확인해야 했습니다. 결국 기존에 성공했던 agent-messenger@2.20.4 + Bun 조합으로 환경을 맞춘 뒤 로그인과 메시지 발송까지 진행할 수 있었습니다.

설치보다 중요한 것은 로그인 성공, 채팅방 조회, 테스트 발송, 발송 결과 재확인을 순서대로 검증하는 일이었습니다. 이 글에서는 다른 에이전트에게 그대로 전달해도 작업할 수 있도록 전체 과정을 정리합니다.

아래 과정은 실제로 동작을 확인한 agent-messenger@2.20.4와 Bun 조합을 기준으로 합니다. 이후 버전에서는 명령이나 내부 파일 경로가 달라질 수 있습니다.

Agent Messenger는 어떻게 카카오톡과 연결될까?

Agent Messenger는 여러 메신저를 CLI와 SDK로 다룰 수 있게 만든 오픈소스입니다. 카카오톡에서는 agent-kakaotalk CLI가 서브 디바이스 로그인과 LOCO 프로토콜을 사용합니다.

Hermes나 OpenClaw에 카카오톡 플러그인을 직접 설치한다기보다, 에이전트가 같은 컴퓨터에 설치된 카카오톡 CLI를 실행하는 구조에 가깝습니다.

Hermes / OpenClaw
       ↓ 로컬 명령 실행
agent-kakaotalk CLI
       ↓
카카오톡 계정과 채팅방

따라서 Agent Messenger는 Hermes 또는 OpenClaw가 실제로 명령을 실행하는 컴퓨터와 같은 사용자 계정에 설치해야 합니다.

1. 계정별 작업 폴더 만들기

먼저 카카오톡 전용 작업 폴더를 만듭니다. 여러 계정을 연결한다면 계정별로 폴더를 분리하는 편이 좋습니다. 세션과 설정이 섞이는 문제를 줄일 수 있습니다.

mkdir -p ~/.local/share/agent-messenger-kakao
cd ~/.local/share/agent-messenger-kakao

npm init -y
npm install agent-messenger@2.20.4

새 계정을 추가한다면 별도 폴더를 사용합니다.

mkdir -p ~/.local/share/agent-messenger-kakao-new
cd ~/.local/share/agent-messenger-kakao-new

npm init -y
npm install agent-messenger@2.20.4

이번 작업에서는 전역 명령보다 설치된 CLI 파일을 Bun으로 직접 실행했습니다. 매번 긴 경로를 입력하지 않도록 환경 변수로 지정합니다.

export KAKAO_CLI="$PWD/node_modules/agent-messenger/dist/src/platforms/kakaotalk/cli.js"

이후 명령은 같은 터미널에서 계속 실행합니다. 터미널을 새로 열었다면 작업 폴더로 이동한 뒤 KAKAO_CLI를 다시 지정해야 합니다.

2. 설치 결과와 기존 인증 확인하기

카카오톡 CLI가 실행되는지 확인하면서 기존 로그인 정보도 조회합니다.

bun "$KAKAO_CLI" auth status

이 명령이 실행되면 적어도 패키지와 CLI 경로는 정상적으로 연결된 것입니다. 로그인된 상태라면 대략 다음 정보가 나옵니다.

{
  "account_id": "...",
  "user_id": "...",
  "device_type": "tablet",
  "has_refresh_token": true,
  "has_device_uuid": true
}

기존 계정이 표시된다면 이번에 연결할 계정이 맞는지 먼저 확인합니다. 다른 계정이라면 그대로 로그인 작업을 덮어쓰지 말고 작업 폴더를 새로 만드는 편이 안전합니다.

여기서 CLI가 실행되지 않는다면

아래 세 가지를 먼저 확인합니다.

pwd
npm list agent-messenger
ls node_modules/agent-messenger/dist/src/platforms/kakaotalk/cli.js

현재 위치가 Agent Messenger를 설치한 폴더인지
agent-messenger@2.20.4가 로컬에 설치되어 있는지
카카오톡 CLI 파일이 실제 경로에 존재하는지

Node 실행 방식도 비교해볼 수 있습니다.

npx -y --package agent-messenger@2.20.4 agent-kakaotalk auth status

직접 실행과 npx 중 한쪽만 동작한다면 로그인 문제보다 런타임이나 실행 경로 문제일 가능성이 큽니다.

3. 카카오톡 계정 로그인하기

CLI 실행을 확인했다면 로그인을 시작합니다.

bun "$KAKAO_CLI" auth login

로그인 과정에서는 계정 정보 입력과 카카오톡 앱의 기기 인증이 필요할 수 있습니다. 비밀번호는 Hermes나 OpenClaw의 채팅창에 전달하지 말고 로컬 터미널의 보안 입력창에 직접 입력합니다.

휴대폰에 입력할 인증 코드가 일반 출력에 보이지 않는다면 디버그 모드로 다시 실행합니다.

bun "$KAKAO_CLI" auth login --debug

출력에서 다음과 같은 내용을 찾습니다.

Enter this code on your phone: 1234
Waiting for confirmation...

휴대폰에는 숫자 코드만 입력합니다. 디버그 로그 전체에는 토큰이나 계정 관련 정보가 포함될 수 있으므로 LLM 대화나 공개 채팅에 그대로 붙여 넣지 않습니다.

비대화식 로그인이 꼭 필요하다면 --password-file을 사용할 수 있습니다. 파일은 사용자가 로컬에서 직접 만들고, 권한을 제한한 뒤 로그인 직후 삭제합니다.

chmod 600 /path/to/password-file
bun "$KAKAO_CLI" auth login --password-file /path/to/password-file
rm -f /path/to/password-file

가능하면 비밀번호 파일보다 터미널의 보안 입력을 사용하는 편을 권장합니다.

4. 로그인 결과 검증하기

처음 작업을 맡길 때는 에이전트가 “로그인했습니다”라고 답하면 연동이 끝난 것으로 생각하기 쉽습니다. 하지만 실제 계정과 세션이 저장되었는지는 별도로 확인해야 합니다.

bun "$KAKAO_CLI" auth status
bun "$KAKAO_CLI" whoami --pretty

다음 항목을 확인합니다.

has_refresh_token이 true인지
has_device_uuid가 true인지
user_id가 출력되는지
표시된 계정 ID 또는 이메일이 연결하려는 계정과 일치하는지

이 네 가지가 맞아야 설치와 로그인 단계가 끝난 것입니다.

5. 카카오톡 채팅방 목록 조회하기

로그인 검증이 끝난 뒤 채팅방 목록과 방 제목을 조회합니다.

bun "$KAKAO_CLI" chat list --resolve-titles --pretty

원하는 방이 보이지 않으면 전체 페이지를 조회합니다.

bun "$KAKAO_CLI" chat list --all --resolve-titles --pretty

특정 이름으로 검색할 수도 있습니다.

bun "$KAKAO_CLI" chat list --search "테스트 대상 이름" --resolve-titles --pretty

출력에서 메시지를 보낼 방의 chat_id를 기록합니다. 이름이 비슷한 방이 있을 수 있으므로 제목만 보고 바로 발송하지 말고 대상이 맞는지 사용자에게 다시 확인받는 것이 좋습니다.

6. 테스트 메시지를 보내고 다시 조회하기

테스트 메시지는 본인과의 채팅방이나 사전에 동의를 받은 방에만 보냅니다.

bun "$KAKAO_CLI" message send <chat-id> "카카오톡 연동 테스트 메시지입니다."

성공하면 대략 다음과 같은 결과가 나옵니다.

{
  "success": true,
  "status_code": 0,
  "chat_id": "...",
  "log_id": "...",
  "sent_at": 1782050091
}

저는 여기서 한 번 더 확인하는 과정을 완료 기준으로 잡았습니다. 명령이 성공했다고 해도 실제 채팅방에 메시지가 기록되었는지 다시 조회합니다.

bun "$KAKAO_CLI" message list <chat-id> -n 3

다음 세 가지를 비교합니다.

방금 보낸 문구가 최근 메시지에 있는지
발송 결과와 조회 결과의 log_id가 일치하는지
메시지의 author_id가 로그인 계정의 user_id인지

message send의 success: true와 message list의 실제 메시지를 모두 확인해야 연동 테스트가 끝납니다.

전체 작업 순서

다른 에이전트가 작업할 때는 다음 순서대로 한 단계씩 확인하면 됩니다.

계정별 로컬 작업 폴더 생성
agent-messenger@2.20.4 설치
agent-kakaotalk CLI 파일과 Bun 실행 확인
auth status와 auth login으로 인증 진행
whoami --pretty로 실제 로그인 계정 검증
chat list --resolve-titles --pretty로 대상 방의 chat_id 확보
사용자 승인 후 테스트 메시지 한 번 발송
message list로 메시지와 log_id 재확인

설치가 안 된 상태에서 로그인 명령만 반복하거나, 버전 문제와 인증 문제를 동시에 해결하려고 하면 원인을 구분하기 어렵습니다. CLI 실행 확인 → 로그인 → 계정 확인 → 방 조회 → 발송 → 재조회 순서로 한 단계씩 통과시키는 것이 중요합니다.

다른 에이전트에게 그대로 전달할 프롬프트

새로운 Hermes/OpenClaw 에이전트가 같은 작업을 이어받아야 한다면 아래 내용을 그대로 전달할 수 있습니다.

Agent Messenger를 이용해 카카오톡 연동 작업을 진행한다.

이전 작업에서는 카카오톡 설치 단계에서 진행이 멈췄고, 패키지/바이너리 이름의 혼선과 라이브러리 버전 및 Bun/bson 호환 문제가 있었다. 따라서 처음부터 최신 버전으로 바꾸지 말고 아래의 기존 성공 환경을 기준으로 검증한다.

- 작업 폴더: ~/.local/share/agent-messenger-kakao
- 패키지: agent-messenger@2.20.4
- 실행 바이너리: agent-kakaotalk
- CLI 파일: node_modules/agent-messenger/dist/src/platforms/kakaotalk/cli.js
- 실행 방식: 작업 폴더에서 Bun으로 CLI 파일 직접 실행

반드시 아래 순서로 진행한다.

1. 현재 작업 폴더와 agent-messenger 설치 버전을 확인한다.
2. CLI 파일이 실제 경로에 있는지 확인한다.
3. auth status로 인증 상태를 확인한다.
4. 로그인이 필요하면 auth login을 실행한다.
5. whoami --pretty로 로그인 계정과 user_id를 확인한다.
6. chat list --resolve-titles --pretty로 채팅방 목록을 조회한다.
7. 메시지를 보내기 전 대상 chat_id와 발송 문구를 사용자에게 확인받는다.
8. message send로 메시지를 한 번만 전송한다.
9. message list <chat-id> -n 3으로 실제 발송 메시지를 다시 확인한다.
10. success, chat_id, log_id와 message list 검증 여부를 보고한다.

보안 및 발송 규칙:
- 카카오 비밀번호나 토큰을 채팅으로 요청하거나 출력하지 않는다.
- debug 로그 전체를 대화에 붙여 넣지 않는다.
- 사용자가 승인하지 않은 방에는 메시지를 보내지 않는다.
- 실패 원인을 확인하지 않고 발송 명령을 반복하지 않는다.
- 중복 메시지를 막기 위해 자동 재시도하지 않는다.

이 프롬프트에는 실행 명령뿐 아니라 이전에 막혔던 지점과 완료 기준도 포함되어 있어, 새 에이전트가 같은 시행착오를 반복하는 것을 줄일 수 있습니다.

자주 발생한 문제

`startupSnapshot.isBuildingSnapshot()` 오류

agent-messenger@2.20.4와 Bun 1.3.x 조합에서 bson/lib/bson.node.mjs 관련 오류가 발생한 적이 있습니다.

이 경우 다음 순서로 범위를 좁힙니다.

현재 설치 버전과 작업 폴더 확인
CLI 파일의 실제 존재 여부 확인
npx 방식으로 Node 런타임에서도 같은 오류가 나는지 비교
최신 Agent Messenger에서 문제가 재현되는지 별도 폴더에서 확인
재현될 때만 node_modules 로컬 패치를 임시 적용

npx -y --package agent-messenger@2.20.4 agent-kakaotalk auth status

node_modules를 직접 수정하면 재설치할 때 패치가 사라집니다. 계속 필요한 패치라면 별도 패치 파일이나 설치 후 스크립트로 관리해야 합니다.

`Session kicked — another device logged in`

다른 카카오 세션과 충돌하면 다음 메시지가 나타날 수 있습니다.

Session kicked — another device logged in

이 상태에서는 실시간 리스너가 끊길 수 있습니다. 사용하는 계정과 작업 폴더가 맞는지 확인하고 다른 기기의 로그인 상태를 점검한 뒤 다시 연결합니다. 상시 실행하는 서비스라면 세션 종료 감지와 재연결 로직도 필요합니다.

원하는 채팅방이 목록에 없음

기본 chat list는 일부 결과만 보여줄 수 있습니다. --all과 --resolve-titles를 함께 사용합니다.

bun "$KAKAO_CLI" chat list --all --resolve-titles --pretty

자동응답까지 확장한다면

한 번의 테스트 발송과 자동응답 서비스 운영은 위험도가 다릅니다. 자동응답까지 확장할 때는 최소한 다음 안전장치가 필요합니다.

허용한 chat_id만 처리하는 allowlist
에이전트 자신이 보낸 메시지 무시
log_id 기준 중복 처리 방지
채팅방별 rate limit과 FIFO queue
민감정보를 제외한 실행 로그
세션 종료와 네트워크 오류 감지 및 재연결
일정, 약속, 금전, 개인정보 관련 답변의 사용자 승인

특히 약속이나 일정은 에이전트가 임의로 확정하지 않도록 해야 합니다. 먼저 사용자에게 알리고 확인을 받은 뒤 답장하는 흐름이 안전합니다.

최종 완료 보고 형식

다른 에이전트에게 작업을 맡겼다면 아래 항목을 모두 보고받아야 합니다.

- 작업 폴더:
- agent-messenger 버전:
- 로그인 계정 user_id:
- 테스트 대상 chat_id:
- 테스트 발송 문구:
- 발송 success:
- log_id:
- message list 확인 여부:

이번 작업에서 가장 중요하게 느낀 점은 “설치했다” 또는 “연동했다”는 답변만으로 완료 처리하지 않는 것이었습니다. 설치 단계에서 멈춘 이유를 먼저 분리하고, 검증된 라이브러리 버전으로 CLI 실행을 확인한 뒤, 실제 메시지를 보내고 다시 조회하는 것까지 마쳐야 연동이 끝납니다.

참고 자료

Agent Messenger는 카카오의 공식 봇 API가 아니라 사용자 세션과 서브 디바이스 로그인을 활용합니다. 중요한 계정에 적용하기 전에 최신 프로젝트 문서와 카카오톡 이용 정책, 계정 보안 위험을 확인하고 테스트 계정이나 제한된 채팅방에서 먼저 검증하는 것을 권장합니다.

목차