Back to Details

openkakao-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenKakao CLI

OpenKakao CLI

openkakao-rs
— KakaoTalk CLI client with REST API and LOCO protocol support.
openkakao-rs
— 支持REST API和LOCO协议的KakaoTalk CLI客户端。

Quick checks

快速检查

bash
openkakao-rs --version
openkakao-rs auth
If Homebrew install is needed:
bash
brew tap JungHoonGhae/openkakao
brew install JungHoonGhae/openkakao/openkakao-rs
bash
openkakao-rs --version
openkakao-rs auth
如果需要通过Homebrew安装：
bash
brew tap JungHoonGhae/openkakao
brew install JungHoonGhae/openkakao/openkakao-rs

REST API Commands (read-only, cached token)

REST API命令（只读，令牌缓存）

bash
openkakao-rs login --save          # Extract credentials from KakaoTalk's Cache.db
openkakao-rs auth                  # Verify token validity
openkakao-rs me                    # Show your profile
openkakao-rs friends [-f] [-s q]   # List friends (favorites/search)
openkakao-rs settings              # Show account settings
openkakao-rs chats                 # List chat rooms (Pilsner REST API)
openkakao-rs messages <id> [-n N]  # Read messages (Pilsner, limited cache)
openkakao-rs members <id>          # List chat room members
bash
openkakao-rs login --save          # 从KakaoTalk的Cache.db中提取凭证
openkakao-rs auth                  # 验证令牌有效性
openkakao-rs me                    # 查看个人资料
openkakao-rs friends [-f] [-s q]   # 列出好友（星标好友/搜索）
openkakao-rs settings              # 查看账户设置
openkakao-rs chats                 # 列出聊天室（基于Pilsner REST API）
openkakao-rs messages <id> [-n N]  # 读取消息（基于Pilsner，缓存有限）
openkakao-rs members <id>          # 列出聊天室成员

LOCO Protocol Commands (full access, real-time)

LOCO协议命令（全权限，实时）

bash
openkakao-rs loco-test                          # Test full LOCO connection
openkakao-rs send <chat_id> <message>           # Send message via LOCO WRITE
openkakao-rs watch [--chat-id ID] [--raw]       # Watch real-time incoming messages
openkakao-rs loco-chats [--all]                 # List all chat rooms
openkakao-rs loco-read <chat_id> [-n N] [--all] # Read message history (SYNCMSG)
openkakao-rs loco-read <chat_id> --all --json   # JSON output
openkakao-rs loco-members <chat_id>             # List members
openkakao-rs loco-chatinfo <chat_id>            # Raw chat room info
bash
openkakao-rs loco-test                          # 测试完整LOCO连接
openkakao-rs send <chat_id> <message>           # 通过LOCO WRITE发送消息
openkakao-rs watch [--chat-id ID] [--raw]       # 监控实时接收消息
openkakao-rs loco-chats [--all]                 # 列出所有聊天室
openkakao-rs loco-read <chat_id> [-n N] [--all] # 读取消息历史（SYNCMSG）
openkakao-rs loco-read <chat_id> --all --json   # 输出JSON格式
openkakao-rs loco-members <chat_id>             # 列出成员
openkakao-rs loco-chatinfo <chat_id>            # 原始聊天室信息

LOCO vs REST for messages

LOCO与REST协议的消息功能对比

  • REST (
    messages
    ): Uses Pilsner cache — only returns messages for recently opened chats in the KakaoTalk app. Most chats return empty.
  • LOCO (
    loco-read
    ): Uses SYNCMSG protocol — returns all server-retained messages. Preferred for full history access.
  • REST（
    messages
    命令）：使用Pilsner缓存——仅返回KakaoTalk应用中最近打开的聊天的消息。大多数聊天室会返回空结果。
  • LOCO（
    loco-read
    命令）：使用SYNCMSG协议——返回服务器保留的所有消息。如需获取完整历史记录，优先使用该方式。

Token Management

令牌管理

bash
openkakao-rs relogin [--fresh-xvc]    # Refresh token via login.json + X-VC
openkakao-rs renew                     # Attempt token renewal via refresh_token
openkakao-rs watch-token [--interval N] # Poll Cache.db for fresh tokens
LOCO commands automatically refresh tokens via login.json + X-VC when needed.
bash
openkakao-rs relogin [--fresh-xvc]    # 通过login.json + X-VC刷新令牌
openkakao-rs renew                     # 尝试通过refresh_token续订令牌
openkakao-rs watch-token [--interval N] # 轮询Cache.db获取新令牌
LOCO命令会在需要时自动通过login.json + X-VC刷新令牌。

Workflow

使用流程

  1. Verify binary and token: 
    openkakao-rs --version && openkakao-rs auth
  2. If token invalid: open KakaoTalk app, then 
    openkakao-rs login --save
  3. Get chat IDs: 
    openkakao-rs loco-chats
    (or 
    chats
    for REST)
  4. Read messages: 
    openkakao-rs loco-read <chat_id> --all
    (full history)
  5. Send message: 
    openkakao-rs send <chat_id> "message text"
  6. Watch real-time: 
    openkakao-rs watch
  1. 验证二进制文件和令牌：
    openkakao-rs --version && openkakao-rs auth
  2. 如果令牌无效：打开KakaoTalk应用，然后执行
    openkakao-rs login --save
  3. 获取聊天ID：
    openkakao-rs loco-chats
    （或使用REST方式的
    chats
    命令）
  4. 读取消息：
    openkakao-rs loco-read <chat_id> --all
    （获取完整历史）
  5. 发送消息：
    openkakao-rs send <chat_id> "message text"
  6. 监控实时消息：
    openkakao-rs watch

Troubleshooting

故障排除

Token invalid or 
-950
error

令牌无效或出现
-950
错误

bash
undefined
bash
undefined

Open KakaoTalk app first, then:

先打开KakaoTalk应用，然后执行：

openkakao-rs login --save openkakao-rs auth

LOCO commands auto-refresh tokens, so `-950` is usually handled automatically.
openkakao-rs login --save openkakao-rs auth

LOCO命令会自动刷新令牌，因此`-950`错误通常会被自动处理。

GETMSGS returns 
-300

GETMSGS返回
-300
错误

This is expected on Mac (dtype=2). Use 
loco-read
(SYNCMSG) instead of 
messages
(GETMSGS).
这在Mac平台上属于预期情况（dtype=2）。请使用
loco-read
（SYNCMSG）替代
messages
（GETMSGS）命令。

Homebrew formula not found

Homebrew公式未找到

bash
brew tap JungHoonGhae/openkakao
brew update
brew install JungHoonGhae/openkakao/openkakao-rs
bash
brew tap JungHoonGhae/openkakao
brew update
brew install JungHoonGhae/openkakao/openkakao-rs

Guardrails

注意事项

  • Do not expose personal chat content unless the user explicitly asks.
  • Prefer summary/aggregation output for logs and reports.
  • Message sending (
    send
    ) is functional — confirm chat_id before sending.
  • 除非用户明确要求，否则不要泄露个人聊天内容。
  • 对于日志和报告，优先提供摘要/聚合输出。
  • 消息发送（
    send
    命令）功能可用——发送前请确认chat_id是否正确。