/agent-kakaotalk

name: agent-kakaotalk
description: Interact with KakaoTalk - send messages, read chats, manage conversations
version: 2.38.0
allowed-tools: Bash(agent-kakaotalk:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-kakaotalk
    install:
      - kind: node
        package: agent-messenger
        bins: [agent-kakaotalk]

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.

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.

Quick Start

# 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

Authentication

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: 1. The CLI requests a passcode from KakaoTalk's server 2. A numeric code is displayed — enter it on your phone when prompted 3. The CLI polls until you confirm on your phone 4. 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`.

Agent Behavior (MANDATORY)

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.

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

# 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

Multi-Account

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

Listing Accounts

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

Switching Accounts

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:

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.

Memory

The agent maintains