القائمة
Interact with KakaoTalk - send messages, read chats, manage conversations
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | agent-kakaotalk |
| description | Interact with KakaoTalk - send messages, read chats, manage conversations |
| version | 2.32.0 |
| allowed-tools | Bash(agent-kakaotalk:*) |
| metadata | {"openclaw":{"requires":{"bins":["agent-kakaotalk"]},"install":[{"kind":"node","package":"agent-messenger","bins":["agent-kakaotalk"]}]}} |
A TypeScript CLI tool that enables AI agents and humans to interact with KakaoTalk through a simple command interface. Features sub-device login that keeps your desktop app running.
Before diving in, a few things about KakaoTalk's architecture:
# Login (registers as sub-device, desktop app stays running)
agent-kakaotalk auth login
# List chat rooms
agent-kakaotalk chat list
# Send a message
agent-kakaotalk message send <chat-id> "Hello from AI agent!"
# List messages in a chat
agent-kakaotalk message list <chat-id>
# Show your identity
agent-kakaotalk whoami
Registers the CLI as a sub-device (tablet slot by default). Your desktop app keeps running.
agent-kakaotalk auth login
In interactive mode, this prompts for email and password. On macOS and Windows, the CLI first tries to extract cached credentials from the desktop app so you may not need to type anything. On Linux there is no desktop app, so always pass credentials explicitly via --email and --password (or --password-file).
For AI agents (non-interactive), provide credentials via flags:
agent-kakaotalk auth login --email user@example.com --password mypass
Device registration flow: On first login, KakaoTalk requires device verification:
IMPORTANT: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens. Always use agent-kakaotalk auth login.
When a command fails because no account is configured, the agent MUST drive the auth flow itself:
Step 1: Check auth status
agent-kakaotalk auth status
If authenticated → retry the original command.
Step 2: Login (registers as sub-device — desktop app stays running)
agent-kakaotalk auth login
The CLI auto-extracts the email (and password if available) from the desktop app. On fresh installs, the CLI may prompt for the KakaoTalk password once (one-time device registration). After registration, the password is never needed again.
Possible responses:
{"authenticated": true, ...} → Success. Retry original command.{"next_action": "confirm_on_phone", "passcode": "1234", ...} → Tell the user to enter the displayed code on their phone. The CLI is polling — wait for it to complete, then the login will finish automatically.{"next_action": "choose_device", ...} → Tablet slot is occupied. Ask user which slot to use, then re-run with --device-type pc --force or --device-type tablet --force.{"error": "bad_credentials", ...} → Wrong email or password. Ask the user to provide their credentials manually via --email and --password flags.{"next_action": "run_interactive", ...} → One-time device registration. On macOS/Windows, the CLI normally shows a native password dialog automatically. This response only appears in headless environments where no GUI or TTY is available. Ask the user to run agent-kakaotalk auth login in any terminal. Do NOT ask for the password in chat.Alternatively, use --password-file:
agent-kakaotalk auth login --password-file /tmp/.kakao-pw
The --password-file flag reads the password from the file and deletes the file immediately after reading. The password never appears in chat, shell history, or process list.
Step 3: Retry the original command After successful auth, immediately execute whatever the user originally asked for.
KakaoTalk allows these simultaneous sessions:
# Default: tablet slot (safe for most users)
agent-kakaotalk auth login
# Use PC slot instead (kicks desktop app)
agent-kakaotalk auth login --device-type pc
# Force login even if slot is occupied
agent-kakaotalk auth login --device-type tablet --force
KakaoTalk supports multiple accounts. Each login stores credentials separately, keyed by user ID.
agent-kakaotalk auth list
agent-kakaotalk auth list --pretty
agent-kakaotalk auth use <account-id>
All data commands accept --account <id> to use a specific account without switching the default:
agent-kakaotalk chat list --account 1234567890
agent-kakaotalk message list <chat-id> --account 1234567890
agent-kakaotalk message send <chat-id> "Hello" --account 1234567890
Without --account, commands use the current (default) account.
The agent maintains a ~/.config/agent-messenger/MEMORY.md file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the Read and Write tools to manage your memory file.
At the start of every task, read ~/.config/agent-messenger/MEMORY.md using the Read tool to load any previously discovered chat IDs, friend names, and preferences.
After discovering useful information, update ~/.config/agent-messenger/MEMORY.md using the Write tool. Write triggers include:
chat list)auth status)When writing, include the complete file content — the Write tool overwrites the entire file.
Never store tokens, passwords, credentials, or any sensitive data. Never store full message content (just IDs and chat context). Never store OAuth tokens or device UUIDs.
If a memorized chat ID returns an error, remove it from MEMORY.md. Don't blindly trust memorized data — verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.
# Agent Messenger Memory
## KakaoTalk Account
- User ID: `1234567890`
- Device type: tablet
## Chat Rooms
- `9876543210` — Work group chat (Alice, Bob, Charlie)
- `1111111111` — 1:1 with Alice
- `2222222222` — Family group
## Aliases
- "work" → `9876543210` (Work group chat)
- "alice" → `1111111111` (1:1 with Alice)
## Notes
- User prefers --pretty output
- Work chat is the most frequently used
Memory lets you skip repeated
chat listcalls. When you already know a chat ID from a previous session, use it directly.
# Login as sub-device (recommended)
agent-kakaotalk auth login
agent-kakaotalk auth login --email <email> --password <password>
agent-kakaotalk auth login --device-type pc --force
agent-kakaotalk auth login --debug
# Check auth status
agent-kakaotalk auth status
# Remove stored credentials
agent-kakaotalk auth logout
agent-kakaotalk auth logout --account <account-id>
# List all stored accounts
agent-kakaotalk auth list
agent-kakaotalk auth list --pretty
# Switch the current account
agent-kakaotalk auth use <account-id>
# Check status of specific account
agent-kakaotalk auth status --account <account-id>
# Remove specific account
agent-kakaotalk auth logout --account <account-id>
# Show current authenticated user
agent-kakaotalk whoami
agent-kakaotalk whoami --pretty
agent-kakaotalk whoami --account <account-id>
Output includes:
user_id — your KakaoTalk user IDnickname — your display nameprofile_image_url — profile image thumbnail URLoriginal_profile_image_url — original profile image URLstatus_message — your status messageaccount_display_id — your KakaoTalk ID (may be null if not set)background_image_url — background image URLoriginal_background_image_url — original background image URLfullname — real name (may be null)account_email — account email (may be null)pstn_number — phone number (may be null)email_verified — whether email is verified (may be null)# List all chat rooms (sorted by most recent activity)
agent-kakaotalk chat list
agent-kakaotalk chat list --pretty
agent-kakaotalk chat list --account <account-id>
agent-kakaotalk chat list --account <account-id> --pretty
# Resolve user-set room titles via CHATINFO (one extra LOCO call per chat;
# slower, but matches the room name shown in the official KakaoTalk app)
agent-kakaotalk chat list --resolve-titles
Output includes:
chat_id — numeric chat room IDtype — chat type (1:1, group, open chat)display_name — comma-separated member namestitle — user-set room title (only populated with --resolve-titles; otherwise null). For open chats (OM / OD) without a user-set title, falls back to the OpenLink room name (one extra INFOLINK LOCO call per such chat).active_members — number of active membersunread_count — unread message countlast_message — most recent message preview, including author_name when the sender's nickname is known from the chat list (otherwise null)# Leave a chat room (works on 1:1, group, open, and PlusChat rooms)
agent-kakaotalk chat leave <chat-id>
agent-kakaotalk chat leave <chat-id> --pretty
agent-kakaotalk chat leave <chat-id> --account <account-id>
Output (JSON by default; --pretty pretty-prints the same JSON):
{ "success": true, "status_code": 0, "chat_id": "9876543210" }
The process exits non-zero when success is false.
# List all members of a chat room (uses LOCO GETMEM — one call per invocation)
agent-kakaotalk member list <chat-id>
agent-kakaotalk member list <chat-id> --pretty
agent-kakaotalk member list <chat-id> --account <account-id>
Each member includes:
user_id — numeric user ID (string for safety)nickname — display name in this chat (open chats may differ from the user's main Kakao nickname)profile_image_url, full_profile_image_url, original_profile_image_urlstatus_message, country_isouser_type — KakaoTalk's user type (100 = friend, 1000 = open profile, etc.); null when the server omits the fieldopen_token, open_profile_link_id, open_permission — open-chat-only fields (null for normal chats; open_permission is 1=OWNER, 2=NONE, 4=MANAGER, 8=BOT)SDK-only:
KakaoTalkClient.getMembersByIds(chatId, userIds)is available for the >100-member case where you already have specific user IDs to resolve (typically from a CHATONROOMmiarray). It is intentionally not exposed via the CLI because acquiring those IDs requires a CHATONROOM call that is also SDK-only. Useagent-kakaotalk member listfor the common case.
# List messages in a chat room
agent-kakaotalk message list <chat-id>
agent-kakaotalk message list <chat-id> -n 50
agent-kakaotalk message list <chat-id> --from <log-id>
agent-kakaotalk message list <chat-id> --pretty
# Send a text message
agent-kakaotalk message send <chat-id> "Hello world"
agent-kakaotalk message send <chat-id> "Hello world" --pretty
# Send a quoted reply to a specific message (use a log_id from `message list`)
agent-kakaotalk message send <chat-id> "Replying to this" --reply-to <log-id>
# Send a file (auto-routes by MIME: photo / video / audio / generic file)
agent-kakaotalk message upload <chat-id> ./photo.jpg
agent-kakaotalk message upload <chat-id> ./clip.mp4
agent-kakaotalk message upload <chat-id> ./voice.m4a
agent-kakaotalk message upload <chat-id> ./report.pdf
# Send a multi-photo gallery (2+ images in one message)
agent-kakaotalk message upload <chat-id> ./img1.jpg ./img2.jpg ./img3.jpg
# Force a specific kind (override auto-routing)
agent-kakaotalk message upload <chat-id> ./clip.mp4 --as file # send as generic file, not video
agent-kakaotalk message upload <chat-id> ./image --as photo # extension-less file
agent-kakaotalk message upload <chat-id> ./data.bin --mime application/octet-stream
# Mark messages as read up to a given log ID
agent-kakaotalk message mark-read <chat-id> <log-id>
agent-kakaotalk message mark-read <chat-id> <log-id> --pretty
agent-kakaotalk message mark-read <chat-id> <log-id> --link-id <li> # open chats only
# Use a specific account
agent-kakaotalk message list <chat-id> --account <account-id>
agent-kakaotalk message send <chat-id> "Hello" --account <account-id>
agent-kakaotalk message upload <chat-id> ./photo.jpg --account <account-id>
agent-kakaotalk message mark-read <chat-id> <log-id> --account <account-id>
--reply-to <log-id> sends the text as a quoted reply that references an existing message. Get the log_id from message list output. The CLI looks up the target in the chat's recent history (latest 100 messages) to build the quote, so the target must be reasonably recent.
# Find the message you want to reply to
agent-kakaotalk message list <chat-id> -n 50
# Reply to it by its log_id
agent-kakaotalk message send <chat-id> "Good point!" --reply-to 1234567890
If the log_id is not found in the latest 100 messages, the command errors out without sending.
message upload sends photos, videos, audio, and arbitrary files to a chat. The CLI sniffs the MIME type from the filename and dispatches to the matching KakaoTalk message type, so the common case is a single command and a file path:
agent-kakaotalk message upload <chat-id> ./report.pdf
Routing rules:
| Filename / MIME | Sent as | KakaoTalk renders it as |
|---|---|---|
image/* (.jpg, .png, .gif, .webp) | photo | Inline image with tap-to-zoom |
video/* (.mp4, .mov, .webm) | video | Inline player with play button |
audio/* (.m4a, .mp3, .wav, .ogg) | audio | Voice-message bubble with waveform |
| anything else | file | Generic file attachment with download icon |
Multi-photo galleries (one message that contains several images): pass 2+ files and the CLI uses the gallery flow automatically.
agent-kakaotalk message upload <chat-id> ./img1.jpg ./img2.jpg ./img3.jpg
Override the auto-routing with --as <photo|video|audio|file|multi> when you need explicit control — for example, to send an .mp4 as a generic downloadable file instead of an inline video. Use --mime <type> to override MIME detection (handy for extension-less files or when the caller knows better than the filename).
Output (JSON by default; --pretty pretty-prints the same JSON):
{ "success": true, "status_code": 0, "chat_id": "9876543210", "log_id": "3846830417126748160", "sent_at": 1779509936 }
The process exits non-zero when success is false.
Notes:
file kind, used as a display label for audio, and ignored for photo / video (the client renders the bytes directly).message mark-read sends a LOCO NOTIREAD packet to advance the server-side read watermark for a chat. The watermark is a log_id — typically the latest message's log_id from message list — not a timestamp.
Output (JSON by default; --pretty pretty-prints the same JSON):
{ "success": true, "status_code": 0, "chat_id": "9876543210", "watermark": "123456789" }
The process exits non-zero when success is false so shell scripts can branch on it.
Notes:
agent-messenger slot). KakaoTalk does not support third-party clients; server behavior may vary by chat type, account region, or client version. Use sparingly; avoid tight loops.--link-id <li> (the li field on the open chat). Without it the server returns a non-zero body.status, which the CLI reports as "success": false with the server's status code, and exits non-zero.Each message includes:
log_id — unique message identifiertype — message type (1 = text, 2 = photo, 3 = video, 5 = audio, 12 = sticker, 18 = file, 20 = animated sticker, 27 = multi-photo, etc.)author_id — sender's user IDauthor_name — sender's nickname when known from the chat list (otherwise null; only the room's "display members" are cached)message — message text content (empty string for non-text messages like stickers)attachment — parsed JSON metadata for non-text messages (e.g. photo URL/dimensions, sticker path), or null for plain text. Shape varies by type; treat as an opaque object and narrow per message type.sent_at — Unix timestamp (milliseconds)The CLI handles internal pagination automatically. Just increase -n to get more messages. Pagination is capped at ~4,000 raw messages (50 pages × 80 per page). If the cap is hit, a warning is printed to stderr and results may be incomplete.
# Get latest 20 messages (default)
agent-kakaotalk message list 9876543210
# Get 50 messages
agent-kakaotalk message list 9876543210 -n 50
# Get 200 messages
agent-kakaotalk message list 9876543210 -n 200
# Get messages newer than a known log ID (forward only)
agent-kakaotalk message list 9876543210 --from 123456789
All commands output JSON by default for AI consumption:
{
"chat_id": "9876543210",
"type": 2,
"display_name": "Alice, Bob",
"title": null,
"active_members": 3,
"unread_count": 5,
"last_message": {
"author_id": 1111111111,
"author_name": "Alice",
"message": "Hello everyone!",
"sent_at": 1705312200000
}
}
Use --pretty flag for formatted output:
agent-kakaotalk chat list --pretty
| Option | Description |
|---|---|
--account | Use a specific KakaoTalk account (default: current account) |
--pretty | Human-readable output instead of JSON |
See references/common-patterns.md for typical AI agent workflows.
See templates/ directory for runnable examples:
post-message.sh - Send messages with error handlingmonitor-chat.sh - Monitor a chat for new messageschat-summary.sh - Generate chat summaryAll commands return consistent error format:
{
"error": "No KakaoTalk credentials found. Run:\n agent-kakaotalk auth login (recommended — registers as sub-device, desktop app stays running)"
}
Common errors:
No KakaoTalk credentials found — not authenticated. Run auth login.bad_credentials — wrong email or password. Cached credentials from the desktop app may be stale. Ask the user to provide credentials manually with --email and --password.login_failed — device slot conflict or unknown login error. Run with --debug for the full server response.passcode_request_failed — failed to request device verification code.registration_timeout — passcode expired before user confirmed on phone.login_http_error — network issue reaching KakaoTalk servers.LOCO packet timeout — messaging protocol timed out (server may be overloaded).Credentials stored in ~/.config/agent-messenger/kakaotalk-credentials.json (0600 permissions). See references/authentication.md for format and security details.
Config format:
{
"current_account": "1234567890",
"accounts": {
"1234567890": {
"account_id": "1234567890",
"oauth_token": "...",
"user_id": "1234567890",
"refresh_token": "...",
"device_uuid": "...",
"device_type": "tablet",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z"
}
}
}
KakaoTalkClient is available as a TypeScript SDK for building scripts and automations.
import { KakaoTalkClient } from 'agent-messenger/kakaotalk'
const client = await new KakaoTalkClient().login()
Or with manual credential management:
import { KakaoTalkClient, KakaoCredentialManager } from 'agent-messenger/kakaotalk'
const manager = new KakaoCredentialManager()
const account = await manager.getAccount()
if (!account) throw new Error('Not authenticated')
const client = await new KakaoTalkClient().login({ oauthToken: account.oauth_token, userId: account.user_id, deviceUuid: account.device_uuid })
try {
// Get your profile
const profile = await client.getProfile()
// List chats
const chats = await client.getChats()
// Send a message
if (chats.length === 0) throw new Error('No chats found')
const chatId = chats[0].chat_id
const result = await client.sendMessage(chatId, 'Hello from SDK!')
// Send a file (photo / video / audio / file auto-routed by MIME). Pass
// an array to send several at once — all-image arrays become a gallery.
const photo = await Bun.file('./photo.jpg').bytes()
await client.sendAttachment(chatId, photo, 'photo.jpg')
// Read messages
const messages = await client.getMessages(chatId, { count: 50 })
// Reply to a message by quoting it
const target = messages[messages.length - 1]
await client.sendMessage(chatId, 'Replying to your last message', {
replyTo: { log_id: target.log_id, author_id: target.author_id, message: target.message, type: target.type },
})
} finally {
// Always close when done (LOCO TCP connection)
client.close()
}
See the KakaoTalk SDK documentation for complete method signatures, types, schemas, and examples.
--email and --password (or --password-file) explicitly — the LOCO protocol, login flow, and all messaging features work on Linux.message upload and KakaoTalkClient.sendAttachment.chat list to discover themagent-kakaotalk: command not foundagent-kakaotalk is NOT the npm package name. The npm package is agent-messenger.
If the package is installed globally, use agent-kakaotalk directly:
agent-kakaotalk chat list --pretty
If the package is NOT installed, use --package to install and run:
npx -y --package agent-messenger agent-kakaotalk chat list --pretty
bunx --package agent-messenger agent-kakaotalk chat list --pretty
pnpm dlx --package agent-messenger agent-kakaotalk chat list --pretty
Note: If the user prefers a different package runner, use the matching command above.
NEVER run npx agent-kakaotalk, bunx agent-kakaotalk, or pnpm dlx agent-kakaotalk without --package agent-messenger. It will fail or install a wrong package since agent-kakaotalk is not the npm package name.
On fresh installs, the desktop app (macOS or Windows) may hash or omit the password from its cache, so the CLI cannot extract it automatically. The CLI will prompt for the password once to register the device — via a native dialog on macOS (AppKit), Windows (PowerShell WinForms), or Linux (zenity / kdialog), or via a TTY prompt if a terminal is available. After registration, the password is never needed again.
On Linux there is no desktop app to extract from, so always provide credentials explicitly:
agent-kakaotalk auth login --email user@example.com --password-file /tmp/.kakao-pw
--password-file reads the file then immediately deletes it, so the password never appears in shell history or process listings.
When the CLI returns {"next_action": "run_interactive", ...}, use a tmux session to let the user type their password securely. See "Handling run_interactive" above for the exact steps.
NEVER ask for the password in chat or pass it via --password — this exposes the plaintext password in conversation logs, shell history, and process lists.
If login returns bad_credentials, the provided password is incorrect. Do NOT retry with --force or switch device slots — the issue is the credentials themselves, not the device slot.
If the issue persists, run with --debug to see the full server response.
If login fails because the tablet slot is occupied (error: login_failed, not bad_credentials):
# Option 1: Use the PC slot instead
agent-kakaotalk auth login --device-type pc --force
# Option 2: Force the tablet slot (kicks existing tablet session)
agent-kakaotalk auth login --device-type tablet --force
If the passcode expires before you confirm on your phone:
agent-kakaotalk auth login again — a new passcode will be generatedInteract with Channel Talk using extracted desktop app or browser credentials - read chats, send messages, search messages, manage groups
Interact with Channel Talk workspaces using API credentials - send messages, read chats, manage groups and bots
Interact with Discord servers - send messages, read channels, manage reactions
Interact with Discord servers using bot tokens - send messages, read channels, manage reactions
Interact with iMessage on a Mac via the imsg tool - send messages, read chats, watch for new messages
Interact with Instagram DMs - send messages, read conversations, manage accounts