kmsg使用指南
介绍安装、主要命令、安全读取、JSON、MCP和故障排除。
本页介绍安装、消息读取与发送、MCP服务器以及常见故障处理。全部参数与最新契约请参阅英文完整参考。
安装
环境要求
- macOS 13或更高版本
- macOS版KakaoTalk
- 为实际运行的
kmsg二进制授予辅助功能权限
Homebrew
brew install channprj/tap/kmsg
更新:
kmsg update
kmsg update会在需要时安装Homebrew，安装或升级formula，并将直接安装的二进制文件链接到由Homebrew管理的命令。
从源码构建
git clone https://github.com/channprj/kmsg.git
cd kmsg
swift build -c release
install -m 755 .build/release/kmsg ~/.local/bin/kmsg
快速开始
首先检查权限和KakaoTalk状态。
kmsg status --verbose
列出聊天并读取最近消息。
kmsg chats --limit 20
kmsg read "聊天名称" --limit 20
发送前先检查目标与内容。
kmsg send "聊天名称" "你好" --dry-run
--dry-run会在访问KakaoTalk UI之前结束，因此不会发送消息。
登录与权限
kmsg auth login
kmsg auth login --auto
密码使用AES-GCM加密，凭据和密钥分别存放在仅所有者可访问的文件中。请勿公开或上传这些文件。
~/.config/kmsg/credentials.json
~/.config/kmsg/credentials/primary.key
锁定模式
如果KakaoTalk显示锁定界面，命令会先解锁再继续，并接着完成原本的请求。
密码取自已保存的值：优先使用上次解锁时记住的锁定密码，否则使用kmsg auth login保存的账号密码。只有两者都不可用时才会提示输入，并记住成功的值。
每条命令只尝试解锁一次，因为多次输错密码会导致KakaoTalk将账号登出。若已保存的账号密码被拒绝，则不会再次尝试，请运行kmsg auth login保存当前密码。
没有终端的调用方（kmsg mcp-server、kmsg watch、cron）无法接收输入，因此依赖这些已保存的凭据。
命令概览
| 命令 | 用途 |
|---|---|
kmsg status |
检查权限、KakaoTalk、登录和就绪状态 |
kmsg auth login |
输入或复用凭据 |
kmsg chats |
获取聊天列表与本地chat_id |
kmsg read |
读取最近消息 |
kmsg watch |
持续监控新消息 |
kmsg send |
发送文本消息 |
kmsg send-image |
发送图片 |
kmsg inspect |
检查AX层级 |
kmsg cache |
管理AX路径缓存 |
kmsg mcp-server |
启动原生stdio MCP服务器 |
kmsg update |
将kmsg更新到Homebrew发布版本 |
安全读取
不希望打断前台工作时，可使用--background-safe。
kmsg read "聊天名称" --json --background-safe
此模式不会启动或激活KakaoTalk，也不会登录、搜索、打开、调整或关闭窗口。如果匹配的聊天窗口尚未显示，读取会失败。
找不到--background-safe时
此CLI标志从kmsg v1.260618.0开始提供，并且仅适用于kmsg read命令。请先确认当前Shell实际执行的二进制文件：
kmsg --version
kmsg read --help
如果帮助中没有此标志，请更新Homebrew安装后再次检查：
brew update
brew upgrade kmsg
kmsg read --help
MCP客户端不使用CLI写法--background-safe，而是使用JSON参数background_safe: true。
发送
kmsg send <recipient> <message> [options]
kmsg send --chat-id <chat-id> <message> [options]
| 选项 | 行为 |
|---|---|
--dry-run |
不操作UI，只显示目标与内容 |
--chat-id ID |
使用kmsg chats生成的本地ID |
--keep-window |
保留命令打开的聊天窗口 |
--no-cache |
清除相关AX缓存并重新查找 |
--layout MODE |
指定窗口布局 |
发送图片:
kmsg send-image "聊天名称" /absolute/path/image.png --dry-run
JSON与MCP
kmsg chats --json
kmsg read "聊天名称" --json
kmsg watch "聊天名称" --json
结构化结果写入stdout，AX诊断写入stderr。
MCP服务器提供以下工具。
| 工具 | 用途 |
|---|---|
kmsg_read |
读取最近消息 |
kmsg_send |
发送文本 |
kmsg_send_image |
发送本地图片 |
对于发送工具，confirm=true不会发送，而是返回CONFIRMATION_REQUIRED。confirm=false或省略时会立即发送。
主要环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
KMSG_MCP_KMSG_PATH |
当前可执行文件 | MCP服务器调用的kmsg路径 |
KMSG_MCP_TIMEOUT_SECONDS |
30 |
子进程超时时间 |
KMSG_DEFAULT_LAYOUT |
preserve |
默认窗口布局 |
KMSG_DEFAULT_BACKGROUND_SAFE |
false |
安全读取默认值 |
KMSG_DEFAULT_DEEP_RECOVERY |
false |
深度恢复默认值 |
故障排除
没有辅助功能权限
kmsg status
请在系统设置中允许实际运行的二进制。Homebrew版本和本地构建可能会被视为不同的程序。
找不到聊天
kmsg chats --verbose --limit 50
kmsg cache clear
kmsg read "准确的聊天名称" --deep-recovery
重复自动化时，建议先用kmsg chats刷新注册表，再使用chat_id。
UI结构发生变化
kmsg read "聊天名称" --debug --trace-ax
kmsg inspect --depth 5
kmsg cache stats
KakaoTalk更新后，可清除缓存并重新发现路径。