OpenKakao

macOS용 카카오톡 데스크탑 앱을 위한 비공식 CLI입니다.

터미널에서 직접 쓰기 좋고, JSON 출력, watch, hook, webhook 흐름으로 AI나 agent가 호출하기에도 적합합니다.

실행 바이너리는 openkakao-cli입니다.

Quick Start · 핵심 · 문서 · Claude Code Skill

한국어 | English

[!TIP] 로그인 없이 바로 동작합니다. local-send/ax-read는 macOS Accessibility API로 카카오톡 UI를 직접 읽고 조작해서, 서버 세션 없이도 실제 메시지 전송과 최근 대화 읽기를 지원합니다. KakaoTalk 앱이 실행 중이고 로그인만 되어 있으면 됩니다 — 아래 Quick Start 참고.

[!NOTE] 서버 로그인(login --save/login --manual)은 최근 KakaoTalk macOS 빌드에서 대부분 동작하지 않습니다 (#15, #20, #22). 미등록 기기로 로그인을 반복 시도하지 마세요 — 카카오가 계정의 "서브 디바이스 로그인"을 차단하거나 계정을 제재할 수 있습니다(실제 피해 사례가 보고되었습니다). 로컬 SQLCipher DB(local-chats/local-read/local-search)도 최신 빌드에서 키 유도 공식이 어긋나 신뢰할 수 없습니다 — 대신 ax-read를 쓰세요.

[!WARNING] 이 프로젝트는 카카오(Kakao Corp.)와 무관한 비공식 CLI입니다. 연구, 자동화, 로컬 워크플로 용도로 만들었고, 카카오의 승인이나 보증을 받지 않았습니다. 사용 방식에 따라 카카오 이용약관 또는 운영정책 위반으로 해석될 수 있으며, 그 경우 사용자 계정이 정지되거나 영구 삭제될 수 있습니다. 사용 전에 관련 정책을 직접 확인하고, 모든 책임은 사용자 본인에게 있음을 전제로 신중히 사용하세요.

Works with

OpenClaw

Claude Code

Codex

Cursor

Bash

HTTP

  <img alt="Star History Chart" src="https://api.star-history.com/image?repos=JungHoonGhae/openkakao-cli&type=date&legend=top-left" width="600" />

Quick Start

로그인 없이 쓰기 (권장)

서버 로그인이 필요 없는 경로입니다. KakaoTalk 앱이 실행 중이고 로그인되어 있기만 하면 됩니다.

# Homebrew
brew tap JungHoonGhae/openkakao
brew install openkakao-cli

# 1. 실제 전송 전 화이트리스트에 채팅방을 등록 (필수 — 아무 채팅에나 보내지 않도록)
#    ~/.config/openkakao/config.toml
#    [safety]
#    allow_ax_send = true
#    allowed_send_chats = ["나와의 채팅에 표시되는 이름"]

# 2. 메시지 보내기 — 서버 접촉 없음, 실제 카톡 UI를 직접 조작
openkakao-cli local-send "채팅방 표시 이름" "Hello from CLI!" --dry-run   # 미리보기
openkakao-cli local-send "채팅방 표시 이름" "Hello from CLI!" -y         # 실제 전송

# 3. 최근 메시지 읽기 — 같은 방식(AX)으로 화면에 보이는 메시지를 스크랩
openkakao-cli ax-read "채팅방 표시 이름" -n 20

# 4. 수신 감지 — 채팅 목록을 폴링해 안읽음이 늘면 hook/webhook 발화 (서버 접촉 없음)
openkakao-cli ax-watch --hook-cmd 'my-script.sh'

서버 로그인 기반 (현재 대부분 깨짐)

# 1. 인증 정보 저장 — 최신 빌드에서는 대부분 실패합니다 (#15, #20, #22)
openkakao-cli login --manual --save
#    (예전 빌드에서 캐시 추출이 되는 경우: openkakao-cli login --save)

# 2. 채팅방 목록
openkakao-cli chats

# 3. 메시지 읽기
openkakao-cli read <chat_id> -n 20

# 4. 메시지 보내기 (LOCO write — opt-in 필요: safety.allow_loco_write = true)
openkakao-cli send <chat_id> "Hello from CLI!"

# 로컬 DB 읽기 (현재 최신 빌드에서 키 유도 실패로 신뢰 불가 — ax-read 권장)
openkakao-cli local-chats
openkakao-cli local-read <chat_id>

필요할 때만 예전 cache-backed 경로를 강제합니다.

openkakao-cli chats --rest
openkakao-cli read <chat_id> --rest
openkakao-cli members <chat_id> --rest

For Agent

# 로그인 없이 읽고 쓰기 (서버 통신 없음, AX 기반)
openkakao-cli ax-read "채팅방 표시 이름" -n 20 --json
openkakao-cli local-send "채팅방 표시 이름" "message" -y --json

# 실행 전 미리보기
openkakao-cli send <chat_id> "message" --dry-run --json

# 구조화된 출력
openkakao-cli --json chats
openkakao-cli --json read <chat_id> -n 20

# 실시간 이벤트 감시
openkakao-cli watch --json

# 로컬 hook 또는 webhook 흐름으로 연결
openkakao-cli --unattended --allow-watch-side-effects watch \
  --hook-cmd 'jq . > /tmp/openkakao-event.json'

Claude Code에서 바로 쓰려면:

npx skills add JungHoonGhae/skills@openkakao-cli

핵심

• local-send/ax-read로 로그인 없이 실제 메시지 전송·읽기 (macOS Accessibility API로 카톡 UI를 직접 조작, 서버 통신 없음)
• macOS 카카오톡 앱에서 인증 정보 추출
• 채팅, 메시지, 멤버, 친구, 프로필 조회
• LOCO 기반 메시지 전송, 실시간 watch, 미디어 처리
• --json 출력으로 jq, cron, SQLite, LLM 흐름과 연결 가능
• watch, hook, webhook로 로컬 자동화와 에이전트 워크플로에 연결 가능
• friends --local, profile --local, profile --chat-id로 일부 조회 복구 가능
• local-chats, local-read, local-search로 로컬 DB 읽기 시도 (최신 빌드에서는 키 유도 실패로 신뢰 불가 — ax-read 권장)
• --dry-run으로 실행 전 미리보기
• send --me로 나와의 채팅에 바로 전송 (테스트용)
• LOCO write 기본 비활성 — safety.allow_loco_write = true로 opt-in
• local-send도 기본 비활성 — safety.allow_ax_send = true + safety.allowed_send_chats 화이트리스트로 opt-in

이런 경우에 잘 맞습니다

• 채팅 기록을 JSON으로 읽어서 다른 도구로 넘기고 싶을 때
• 카카오톡을 로컬 스크립트나 운영 도구의 입력 채널로 쓰고 싶을 때
• watch 이벤트를 hook이나 webhook으로 받아 후속 작업을 실행하고 싶을 때
• 사람이 직접 쓰는 CLI와 AI가 호출하는 로컬 인터페이스를 같이 두고 싶을 때

안전 모드

v1.1.0부터 LOCO write 작업(send, delete, edit, react)은 기본 비활성입니다. 계정 보호를 위해 서버에 쓰기 요청을 보내는 명령은 명시적 opt-in이 필요합니다.

# ~/.config/openkakao/config.toml
[safety]
allow_loco_write = true

local-send(AX 기반 실전송)도 v1.4.0부터 기본 비활성이며, 별도로 opt-in과 채팅방 화이트리스트가 필요합니다. local-send는 채팅 목록에서 표시 이름이 정확히 일치하는 방을 찾아 전송하는데, 로컬 DB의 chat-id로 대상을 다시 검증할 방법이 없어졌기 때문에 화이트리스트가 유일한 안전장치입니다:

# ~/.config/openkakao/config.toml
[safety]
allow_ax_send = true
allowed_send_chats = ["나와의 채팅에 표시되는 이름", "다른 허용 채팅방 이름"]

읽기 전용 작업은 항상 사용 가능합니다:

[!NOTE] local-send/ax-read/ax-watch는 macOS Accessibility API로 카카오톡의 메인 채팅 목록 창을 찾아야 동작합니다. 이 창이 최소화돼 있거나 현재 보고 있는 것과 다른 macOS Space(가상 데스크탑)에 있으면 찾지 못합니다(포커스를 뺏지 않고는 자동 복구가 불가능해서, 명확한 에러만 내고 직접 복원을 요청합니다). 계속 겪는다면 Dock의 카카오톡 아이콘 우클릭 → Options → Assign To → All Desktops로 한 번만 설정해두세요.

요구 사항

설치

Homebrew

brew tap JungHoonGhae/openkakao
brew install openkakao-cli

From source

git clone https://github.com/JungHoonGhae/openkakao-cli.git
cd openkakao/openkakao-cli
cargo install --path .

문서

• 문서 사이트: https://openkakao.vercel.app/
• 빠른 시작: https://openkakao.vercel.app/docs/getting-started/quickstart/
• CLI 레퍼런스: https://openkakao.vercel.app/docs/cli/overview/
• 자동화 개요: https://openkakao.vercel.app/docs/automation/overview/
• LLM / agent 워크플로: https://openkakao.vercel.app/docs/automation/llm-agent-workflows/
• watch 패턴: https://openkakao.vercel.app/docs/automation/watch-patterns/
• 프로토콜 문서: https://openkakao.vercel.app/docs/protocol/overview/

Reverse engineering / local app-state diff:

openkakao-cli profile-hints --local-graph --json
openkakao-cli profile-hints --app-state --json > /tmp/profile-before.json
openkakao-cli profile-hints --app-state --app-state-diff /tmp/profile-before.json --json

Claude Code Skill

npx skills add JungHoonGhae/skills@openkakao-cli

개발

cd openkakao-cli
cargo build --release

자세한 사용법, 운영 메모, 프로토콜 설명은 문서 사이트에 정리되어 있습니다.

Support

이 프로젝트가 도움이 되셨다면 응원해 주세요:

Contributing

버그 제보와 PR 환영합니다.

Acknowledgments

• kakaocli (MIT) — local-send의 macOS Accessibility API 기반 카톡 UI 자동 조작(채팅방 행 선택, 입력창 탐색·전송) 로직을 Rust로 이식했습니다 (src/ax_send.rs).
• Peekaboo (MIT) — local-send에서 CGEventPostToPid로 이벤트를 대상 프로세스에 직접 전달하는 방식을 참고해, kakaocli가 겪던 포그라운드 활성화 타이밍 레이스(silver-flight-group/kakaocli#9)를 우회했습니다.

License

MIT