agent-kakaotalk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

一款TypeScript CLI工具，支持AI Agent和人类通过简单的命令行界面与KakaoTalk交互。支持子设备登录，不会影响你的桌面端应用运行。

Key Concepts

核心概念

Before diving in, a few things about KakaoTalk's architecture:

LOCO protocol = KakaoTalk's binary messaging protocol. The CLI handles this internally — you never interact with it directly.
Chat rooms = conversations (1:1, group, or open chat). Referenced by numeric chat ID.
Device slots = KakaoTalk allows one phone + one PC + one tablet session. The CLI registers as a tablet by default to avoid kicking your desktop app.
Sub-device = a secondary device (PC or tablet). The CLI logs in as a sub-device, so your phone session is never affected.
Passcode verification = when registering a new device, KakaoTalk displays a code on screen that you confirm on your phone.
Log ID = a unique numeric identifier for each message, used for pagination.

在使用前，先了解KakaoTalk的架构相关要点：

LOCO protocol = KakaoTalk的二进制消息协议。CLI会在内部处理该协议——你无需直接与它交互。
聊天室 = 对话（一对一、群组或开放聊天室）。通过数字聊天ID引用。
设备插槽 = KakaoTalk允许同时存在一个手机+一个电脑+一个平板会话。CLI默认注册为平板设备，避免强制退出你的桌面端应用。
子设备 = 次要设备（电脑或平板）。CLI以子设备身份登录，因此你的手机会话不会受到影响。
验证码验证 = 注册新设备时，KakaoTalk会在屏幕上显示一个验证码，你需要在手机上确认。
日志ID = 每条消息的唯一数字标识符，用于分页。

Quick Start

快速开始

bash

undefined

bash

undefined

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

undefined

agent-kakaotalk whoami

undefined

Authentication

身份验证

Registers the CLI as a sub-device (tablet slot by default). Your desktop app keeps running.

bash

agent-kakaotalk auth login

In interactive mode, this prompts for email and password. The CLI first tries to extract cached credentials from the desktop app so you may not need to type anything.

For AI agents (non-interactive), provide credentials via flags:

bash

agent-kakaotalk auth login --email user@example.com --password mypass

Device registration flow: On first login, KakaoTalk requires device verification:

The CLI requests a passcode from KakaoTalk's server
A numeric code is displayed — enter it on your phone when prompted
The CLI polls until you confirm on your phone
Login completes automatically after confirmation

IMPORTANT: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens. Always use

agent-kakaotalk auth login

将CLI注册为子设备（默认使用平板插槽）。你的桌面端应用会保持运行。

bash

agent-kakaotalk auth login

在交互模式下，会提示输入邮箱和密码。CLI会先尝试从桌面端应用提取缓存的凭据，因此你可能无需手动输入任何信息。

对于AI Agent（非交互模式），可通过参数提供凭据：

bash

agent-kakaotalk auth login --email user@example.com --password mypass

设备注册流程：首次登录时，KakaoTalk需要设备验证：

CLI向KakaoTalk服务器请求验证码
屏幕上会显示一个数字验证码——在手机上收到提示时输入该验证码
CLI会轮询等待，直到你在手机上确认
确认后登录会自动完成

重要提示：绝对不要引导用户打开浏览器、使用开发者工具或手动复制令牌。请始终使用

agent-kakaotalk auth login

命令。

Agent Behavior (MANDATORY)

Agent行为规范（强制要求）

When a command fails because no account is configured, the agent MUST drive the auth flow itself:

Step 1: Check auth status

bash

agent-kakaotalk auth status

If authenticated → retry the original command.

Step 2: Login (registers as sub-device — desktop app stays running)

bash

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

--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

bash

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.

当命令因未配置账户而失败时，Agent必须自行引导完成身份验证流程：

步骤1：检查身份验证状态

bash

agent-kakaotalk auth status

如果已验证身份 → 重试原始命令。

步骤2：登录（注册为子设备——桌面端应用保持运行）

bash

agent-kakaotalk auth login

CLI会自动从桌面端应用提取邮箱（如果可用还会提取密码）。在全新安装的情况下，CLI可能会提示输入一次KakaoTalk密码（仅用于一次性设备注册）。注册完成后，将不再需要密码。

可能的响应：

```
{"authenticated": true, ...}
```
→ 成功。重试原始命令。
```
{"next_action": "confirm_on_phone", "passcode": "1234", ...}
```
→ 告知用户在手机上输入显示的验证码。CLI正在轮询等待——等待流程完成，登录会自动结束。
```
{"next_action": "choose_device", ...}
```
→ 平板插槽已被占用。询问用户要使用哪个插槽，然后通过
```
--device-type pc --force
```
或
```
--device-type tablet --force
```
重新运行命令。
```
{"error": "bad_credentials", ...}
```
→ 邮箱或密码错误。请用户通过
```
--email
```
和
```
--password
```
参数手动提供凭据。
```
{"next_action": "run_interactive", ...}
```
→ 需要一次性设备注册。在macOS/Windows系统中，CLI通常会自动显示原生密码对话框。该响应仅会在无GUI或TTY的无头环境中出现。请用户在任意终端中运行
```
agent-kakaotalk auth login
```
。绝对不要在聊天中询问密码。

或者，使用

--password-file

参数：

bash

agent-kakaotalk auth login --password-file /tmp/.kakao-pw

--password-file

参数会从指定文件中读取密码，并在读取后立即删除该文件。密码绝不会出现在聊天记录、shell历史或进程列表中。

步骤3：重试原始命令 身份验证成功后，立即执行用户最初请求的操作。

Device Slots

设备插槽

KakaoTalk allows these simultaneous sessions:

Phone (always active, never affected by the CLI)
PC — will kick KakaoTalk desktop if the CLI uses this slot
Tablet (default) — safe if you don't use a tablet for KakaoTalk

bash

undefined

KakaoTalk允许以下同时在线的会话：

手机（始终处于活跃状态，绝不会受到CLI影响）
电脑——如果CLI使用该插槽，会强制退出KakaoTalk桌面端应用
平板（默认选项）——如果你不使用平板登录KakaoTalk，则此选项安全

bash

undefined

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

undefined

agent-kakaotalk auth login --device-type tablet --force

undefined

Multi-Account

多账户支持

KakaoTalk supports multiple accounts. Each login stores credentials separately, keyed by user ID.

KakaoTalk支持多个账户。每次登录的凭据会单独存储，以用户ID作为标识。

Listing Accounts

列出账户

bash

agent-kakaotalk auth list
agent-kakaotalk auth list --pretty

bash

agent-kakaotalk auth list
agent-kakaotalk auth list --pretty

Switching Accounts

切换账户

bash

agent-kakaotalk auth use <account-id>

bash

agent-kakaotalk auth use <account-id>

Using a Specific Account

使用指定账户

All data commands accept

--account <id>

to use a specific account without switching the default:

bash

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.

所有数据类命令都支持

--account <id>

参数，可在不切换默认账户的情况下使用指定账户：

bash

agent-kakaotalk chat list --account 1234567890
agent-kakaotalk message list <chat-id> --account 1234567890
agent-kakaotalk message send <chat-id> "Hello" --account 1234567890

如果不添加

--account

参数，命令会使用当前（默认）账户。

Memory

记忆功能

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.

Agent会维护一个

~/.config/agent-messenger/MEMORY.md

文件，作为跨会话的持久化存储。该文件由Agent管理——CLI不会读取或写入此文件。请使用

Read

和

Write

工具管理你的记忆文件。

Reading Memory

读取记忆

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.

If the file doesn't exist yet, that's fine — proceed without it and create it when you first have useful information to store.
If the file can't be read (permissions, missing directory), proceed without memory — don't error out.

在每个任务开始时，使用

Read

工具读取

~/.config/agent-messenger/MEMORY.md

，加载之前保存的聊天ID、好友名称和偏好设置。

如果文件尚未存在，无需担心——继续执行任务，当有有用信息时再创建该文件。
如果无法读取文件（权限问题、目录缺失），无需报错——不使用记忆功能继续执行任务即可。

Writing Memory

写入记忆

After discovering useful information, update

~/.config/agent-messenger/MEMORY.md

using the

Write

tool. Write triggers include:

After discovering chat IDs and participant names (from
```
chat list
```
)
After discovering your own user ID (from
```
auth status
```
)
After the user gives you an alias or preference ("call this the work chat", "my group chat with Alice is X")
After discovering chat structure (group chats, 1:1 chats)

When writing, include the complete file content — the

Write

tool overwrites the entire file.

发现有用信息后，使用

Write

工具更新

~/.config/agent-messenger/MEMORY.md

。触发写入的场景包括：

发现聊天ID和参与者名称后（来自
```
chat list
```
命令）
发现自己的用户ID后（来自
```
auth status
```
命令）
用户提供别名或偏好设置后（例如“把这个叫做工作群聊”“我和Alice的群聊ID是X”）
发现聊天结构后（群聊、一对一聊天）

写入时，请包含完整的文件内容——

Write

工具会覆盖整个文件。

What to Store

存储内容

Chat IDs with participant names or display names
Your own user ID
User-given aliases ("work chat", "family group")
Commonly referenced chat IDs
Any user preference expressed during interaction

带有参与者名称或显示名称的聊天ID
你自己的用户ID
用户指定的别名（例如“工作群聊”“家庭群组”）
经常引用的聊天ID
交互过程中用户表达的任何偏好设置

What NOT to Store

禁止存储内容

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.

绝对不要存储令牌、密码、凭据或任何敏感数据。绝对不要存储完整的消息内容（仅存储ID和聊天上下文）。绝对不要存储OAuth令牌或设备UUID。

Handling Stale Data

处理过期数据

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.

如果记忆中的聊天ID返回错误，请将其从

MEMORY.md

中移除。不要盲目信任记忆中的数据——当出现异常时请进行验证。相比使用可能过期的记忆ID，重新列出聊天列表是更可靠的方式。

Format / Example

格式 / 示例

markdown

undefined

markdown

undefined

Agent Messenger Memory

Agent Messenger 记忆文件

KakaoTalk Account

KakaoTalk 账户

User ID:
```
1234567890
```
Device type: tablet

用户ID:
```
1234567890
```
设备类型: tablet

Chat Rooms

聊天室

```
9876543210
```
— Work group chat (Alice, Bob, Charlie)
```
1111111111
```
— 1:1 with Alice
```
2222222222
```
— Family group

```
9876543210
```
— 工作群聊（Alice, Bob, Charlie）
```
1111111111
```
— 与Alice的一对一聊天
```
2222222222
```
— 家庭群组

Aliases

别名

"work" →
```
9876543210
```
(Work group chat)
"alice" →
```
1111111111
```
(1:1 with Alice)

"work" →
```
9876543210
```
（工作群聊）
"alice" →
```
1111111111
```
（与Alice的一对一聊天）

Notes

备注

User prefers --pretty output
Work chat is the most frequently used


> Memory lets you skip repeated `chat list` calls. When you already know a chat ID from a previous session, use it directly.

用户偏好使用--pretty输出
工作群聊是最常用的聊天


> 记忆功能可让你跳过重复的`chat list`调用。如果在之前的会话中已经知道某个聊天ID，可直接使用该ID。

Commands

命令列表

Auth Commands

身份验证命令

bash

undefined

bash

undefined

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>

undefined

agent-kakaotalk auth logout --account <account-id>

undefined

Whoami Command

Whoami命令

bash

undefined

bash

undefined

Show current authenticated user

显示当前已验证身份的用户

agent-kakaotalk whoami agent-kakaotalk whoami --pretty agent-kakaotalk whoami --account <account-id>


Output includes:
- `user_id` — your KakaoTalk user ID
- `nickname` — your display name
- `profile_image_url` — profile image thumbnail URL
- `original_profile_image_url` — original profile image URL
- `status_message` — your status message
- `account_display_id` — your KakaoTalk ID (may be null if not set)
- `background_image_url` — background image URL
- `original_background_image_url` — original background image URL
- `fullname` — 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)

agent-kakaotalk whoami agent-kakaotalk whoami --pretty agent-kakaotalk whoami --account <account-id>


输出内容包括：
- `user_id` — 你的KakaoTalk用户ID
- `nickname` — 你的显示名称
- `profile_image_url` — 头像缩略图URL
- `original_profile_image_url` — 原始头像URL
- `status_message` — 你的状态消息
- `account_display_id` — 你的KakaoTalk ID（如果未设置则为null）
- `background_image_url` — 背景图片URL
- `original_background_image_url` — 原始背景图片URL
- `fullname` — 真实姓名（如果未设置则为null）
- `account_email` — 账户邮箱（如果未设置则为null）
- `pstn_number` — 电话号码（如果未设置则为null）
- `email_verified` — 邮箱是否已验证（如果未设置则为null）

Chat Commands

聊天室命令

bash

undefined

bash

undefined

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


Output includes:
- `chat_id` — numeric chat room ID
- `type` — chat type (1:1, group, open chat)
- `display_name` — comma-separated member names
- `active_members` — number of active members
- `unread_count` — unread message count
- `last_message` — most recent message preview

agent-kakaotalk chat list agent-kakaotalk chat list --pretty agent-kakaotalk chat list --account <account-id> agent-kakaotalk chat list --account <account-id> --pretty


输出内容包括：
- `chat_id` — 数字聊天室ID
- `type` — 聊天类型（一对一、群组、开放聊天室）
- `display_name` — 成员名称（逗号分隔）
- `active_members` — 活跃成员数量
- `unread_count` — 未读消息数量
- `last_message` — 最新消息预览

Message Commands

消息命令

bash

undefined

bash

undefined

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

Use a specific account

使用指定账户

agent-kakaotalk message list <chat-id> --account <account-id> agent-kakaotalk message send <chat-id> "Hello" --account <account-id>

undefined

agent-kakaotalk message list <chat-id> --account <account-id> agent-kakaotalk message send <chat-id> "Hello" --account <account-id>

undefined

Message List Output

消息列表输出

Each message includes:

```
log_id
```
— unique message identifier
```
type
```
— message type (1 = text, 2 = photo, etc.)
```
author_id
```
— sender's user ID
```
message
```
— message text content
```
sent_at
```
— Unix timestamp (milliseconds)

每条消息包含：

```
log_id
```
— 唯一消息标识符
```
type
```
— 消息类型（1 = 文本，2 = 图片等）
```
author_id
```
— 发送者的用户ID
```
message
```
— 消息文本内容
```
sent_at
```
— Unix时间戳（毫秒）

Fetching More Messages

获取更多消息

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.

bash

undefined

CLI会自动处理内部分页。只需增加

-n

参数的值即可获取更多消息。分页上限约为4000条原始消息（50页 × 每页80条）。如果达到上限，会向stderr输出警告，结果可能不完整。

bash

undefined

Get latest 20 messages (default)

获取最新20条消息（默认）

agent-kakaotalk message list 9876543210

Get 50 messages

获取50条消息

agent-kakaotalk message list 9876543210 -n 50

Get 200 messages

获取200条消息

agent-kakaotalk message list 9876543210 -n 200

Get messages newer than a known log ID (forward only)

获取比指定日志ID更新的消息（仅向前获取）

agent-kakaotalk message list 9876543210 --from 123456789

undefined

agent-kakaotalk message list 9876543210 --from 123456789

undefined

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:

json

{
  "chat_id": "9876543210",
  "type": 2,
  "display_name": "Alice, Bob",
  "active_members": 3,
  "unread_count": 5,
  "last_message": {
    "author_id": "1111111111",
    "message": "Hello everyone!",
    "sent_at": 1705312200000
  }
}

所有命令默认输出JSON格式，供AI使用：

json

{
  "chat_id": "9876543210",
  "type": 2,
  "display_name": "Alice, Bob",
  "active_members": 3,
  "unread_count": 5,
  "last_message": {
    "author_id": "1111111111",
    "message": "Hello everyone!",
    "sent_at": 1705312200000
  }
}

Pretty (Human-Readable)

美化格式（人类可读）

Use

--pretty

flag for formatted output:

bash

agent-kakaotalk chat list --pretty

使用

--pretty

参数获取格式化输出：

bash

agent-kakaotalk chat list --pretty

Global Options

全局选项

Option	Description
`--account`	Use a specific KakaoTalk account (default: current account)
`--pretty`	Human-readable output instead of JSON

选项	描述
`--account`	使用指定的KakaoTalk账户（默认：当前账户）
`--pretty`	输出人类可读格式，而非JSON

Common Patterns

常见模式

See

references/common-patterns.md

for typical AI agent workflows.

请查看

references/common-patterns.md

获取典型AI Agent工作流。

Templates

模板

See

templates/

directory for runnable examples:

```
post-message.sh
```
- Send messages with error handling
```
monitor-chat.sh
```
- Monitor a chat for new messages
```
chat-summary.sh
```
- Generate chat summary

请查看

templates/

目录获取可运行的示例：

```
post-message.sh
```
- 带错误处理的消息发送脚本
```
monitor-chat.sh
```
- 聊天室监控脚本（检测新消息）
```
chat-summary.sh
```
- 聊天摘要生成脚本

Error Handling

错误处理

All commands return consistent error format:

json

{
  "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).

所有命令返回一致的错误格式：

json

{
  "error": "No KakaoTalk credentials found. Run:\n  agent-kakaotalk auth login     (recommended — registers as sub-device, desktop app stays running)"
}

常见错误：

No KakaoTalk credentials found

— 未验证身份。请运行

auth login

命令。

```
bad_credentials
```
— 邮箱或密码错误。桌面端应用的缓存凭据可能已过期。请用户通过
```
--email
```
和
```
--password
```
参数手动提供凭据。
```
login_failed
```
— 设备插槽冲突或未知登录错误。添加
```
--debug
```
参数运行命令，查看完整的服务器响应。
```
passcode_request_failed
```
— 请求设备验证码失败。
```
registration_timeout
```
— 用户在验证码过期前未在手机上确认。
```
login_http_error
```
— 连接KakaoTalk服务器时出现网络问题。
```
LOCO packet timeout
```
— 消息协议超时（服务器可能过载）。

Configuration

配置

Credentials stored in

~/.config/agent-messenger/kakaotalk-credentials.json

(0600 permissions). See references/authentication.md for format and security details.

Config format:

json

{
  "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"
    }
  }
}

凭据存储在

~/.config/agent-messenger/kakaotalk-credentials.json

文件中（权限为0600）。请查看references/authentication.md获取格式和安全细节。

配置格式：

json

{
  "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"
    }
  }
}

SDK: Programmatic Usage

SDK：程序化使用

KakaoTalkClient

is available as a TypeScript SDK for building scripts and automations.

KakaoTalkClient

作为TypeScript SDK提供，可用于构建脚本和自动化流程。

Setup

设置

typescript

import { KakaoTalkClient } from 'agent-messenger/kakaotalk'

const client = await new KakaoTalkClient().login()

Or with manual credential management:

typescript

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 })

typescript

import { KakaoTalkClient } from 'agent-messenger/kakaotalk'

const client = await new KakaoTalkClient().login()

或者手动管理凭据：

typescript

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 })

Example

示例

typescript

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!')

  // Read messages
  const messages = await client.getMessages(chatId, { count: 50 })
} finally {
  // Always close when done (LOCO TCP connection)
  client.close()
}

typescript

try {
  // 获取你的个人资料
  const profile = await client.getProfile()

  // 列出聊天室
  const chats = await client.getChats()

  // 发送消息
  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!')

  // 读取消息
  const messages = await client.getMessages(chatId, { count: 50 })
} finally {
  // 使用完毕后请始终关闭连接（LOCO TCP连接）
  client.close()
}

Full API Reference

完整API参考

See the KakaoTalk SDK documentation for complete method signatures, types, schemas, and examples.

请查看KakaoTalk SDK文档获取完整的方法签名、类型、模式和示例。

Limitations

限制

macOS and Windows only (desktop app needed for auto-extracting email/password during login)
No Linux support (KakaoTalk desktop not available on Linux)
No file upload or download
No channel/chat room creation or management
No friend list management
No reactions or emoji
No message editing or deletion
No open chat (오픈채팅) browsing or joining
No search across chats
Plain text messages only (no photos, videos, or rich content)
Chat IDs are numeric and not human-readable — use
```
chat list
```
to discover them

仅支持macOS和Windows系统（登录时需要桌面端应用自动提取邮箱/密码）
不支持Linux系统（KakaoTalk桌面端应用未在Linux平台发布）
不支持文件上传或下载
不支持频道/聊天室创建或管理
不支持好友列表管理
不支持消息反应或表情
不支持消息编辑或删除
不支持开放聊天室（오픈채팅）浏览或加入
不支持跨聊天搜索
仅支持纯文本消息（不支持图片、视频或富媒体内容）
聊天ID为数字，不具备可读性——请使用
```
chat list
```
命令查找聊天ID

Troubleshooting

故障排除

agent-kakaotalk: command not found

agent-kakaotalk: command not found

agent-kakaotalk
is NOT the npm package name. The npm package is

agent-messenger

If the package is installed globally, use

agent-kakaotalk

directly:

bash

agent-kakaotalk chat list --pretty

If the package is NOT installed, use

--package

to install and run:

bash

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.

agent-kakaotalk
不是npm包名称。对应的npm包名称是

agent-messenger

。

如果已全局安装该包，可直接使用

agent-kakaotalk

命令：

bash

agent-kakaotalk chat list --pretty

如果未安装该包，可使用

--package

参数安装并运行：

bash

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

注意：如果用户偏好使用其他包管理器，请使用上述对应的命令。

**绝对不要运行

npx agent-kakaotalk

、

bunx agent-kakaotalk

或

pnpm dlx agent-kakaotalk

**而不添加

--package agent-messenger

参数。由于

agent-kakaotalk

不是npm包名称，该操作会失败或安装错误的包。

Password prompt on fresh install

全新安装时的密码提示

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) and Windows (PowerShell WinForms), or via a TTY prompt if a terminal is available. After registration, the password is never needed again.

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.

在全新安装的情况下，桌面端应用（macOS或Windows）可能会对密码进行哈希处理或从缓存中省略密码，因此CLI无法自动提取密码。CLI会提示输入一次密码以完成设备注册——在macOS系统中会显示AppKit原生对话框，在Windows系统中会显示PowerShell WinForms对话框，如果终端可用则会显示TTY提示。注册完成后，将不再需要密码。

当CLI返回

{"next_action": "run_interactive", ...}

时，请使用tmux会话让用户安全地输入密码。请查看上方的“处理

run_interactive

”部分获取具体步骤。

绝对不要在聊天中询问密码或通过

--password

参数传递密码——这会导致明文密码暴露在对话日志、shell历史和进程列表中。

Bad credentials

凭据错误

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.

如果登录返回

bad_credentials

，说明提供的密码不正确。不要使用
--force
参数重试或切换设备插槽——问题出在凭据本身，而非设备插槽。

如果问题持续存在，请添加

--debug

参数运行命令，查看完整的服务器响应。

Device slot occupied

设备插槽已被占用

If login fails because the tablet slot is occupied (error:

login_failed

, not

bad_credentials

bash

undefined

如果因平板插槽已被占用而登录失败（错误：

login_failed

，而非

bad_credentials

）：

bash

undefined

Option 1: Use the PC slot instead

选项1：改用电脑插槽

agent-kakaotalk auth login --device-type pc --force

Option 2: Force the tablet slot (kicks existing tablet session)

选项2：强制使用平板插槽（会强制退出现有平板会话）

agent-kakaotalk auth login --device-type tablet --force

undefined

agent-kakaotalk auth login --device-type tablet --force

undefined

Passcode verification timeout

验证码验证超时

If the passcode expires before you confirm on your phone:

Run
```
agent-kakaotalk auth login
```
again — a new passcode will be generated
Confirm the code on your phone within the time limit
The CLI automatically completes login after confirmation

如果在你在手机上确认前验证码已过期：

重新运行
```
agent-kakaotalk auth login
```
命令——会生成新的验证码
在时限内在手机上确认该验证码
确认后CLI会自动完成登录

References

参考资料

Authentication Guide
Common Patterns

身份验证指南
常见模式