CLI 常用命令
所有命令默认输出易读的文本格式。在脚本中解析输出时请加上 --json 参数。多账号环境下,请在命令中添加 --account ID(或账号别名)。
查看与读取
wx chats list --limit 20 # 查看最近会话列表及未读消息数wx chats get CHAT_ID # 查看会话详情,包含消息免打扰与置顶设置wx chats find "读书俱乐部" # 按名称搜索会话wx messages list CHAT_ID --limit 50 # 分页获取消息(最新在前),可通过 --cursor 翻页wx contacts find Alice # 查找联系人wx groups members list 'family@chatroom' # 列出群成员会话列表与搜索会呈现表格视图,包含会话名称、Chat ID、类型、未读数以及最新消息。若存在下一页,复制游标执行 wx chats list --cursor CURSOR 即可翻页。
Name Chat ID Kind Unread Last messageBook club books@chatroom group 2 See you Fridaywx messages list 会在表格中展示发送者、消息预览、时间戳及缩略消息 ID。如果历史记录处于部分拉取状态,表格下方会显示提示。如需获取完整消息文本、完整 ID 及数据库覆盖详情,请添加 --json。
已保存的联系人列表与搜索结果会省略 Profile 标记为已删除的条目。这些联系人的名称在已有会话和群成员列表中仍可查看。
会话的消息免打扰设置直接读取自本地已保存的 Profile。Daemon 通过联系人同步流实时接收手机端联系人变更。若返回 null,表示该字段缺失或尚未确定,通知消费端在此期间应对该会话保持静默。可执行 wx contacts refresh CONTACT_ID 手动拉取最新信息。wx chats mute/unmute 可开启或关闭单聊和群聊的消息免打扰;修改单聊时会先读取当前联系人信息,以保证无关字段不被覆盖。
filehelper 为文件传输助手,非常适合用来测试。群聊编辑与成员查询请参考管理群聊。
置顶聊天
wx chats pin CHAT_ID --idempotency-key pin-001wx chats unpin CHAT_ID --idempotency-key unpin-001需要 admin 权限范围,且目标需为已在本地会话列表中存在的普通单聊或活跃群聊。命令执行后将打印对应的操作记录和本地收据路径。请检查 remoteOutcome 和 profileProjection;若因网络异常未收到响应,请复用相同的参数与幂等键重试。重新调用 chats list 时置顶会话将排在最前。系统内置会话(如文件传输助手)不支持置顶修改。
发送消息
wx messages send CHAT_ID --text "在路上了"wx messages send CHAT_ID --image ./photo.jpgwx messages send CHAT_ID --file ./report.pdfwx messages send CHAT_ID --video ./clip.mp4wx messages send CHAT_ID --voice ./note.wav # 自动编码为微信语音消息wx messages send CHAT_ID --share https://example.com/post --title "值得一读"消息发送最长等待微信服务端确认 30 秒。添加 --detach 参数可立即返回并在后台继续执行。
在群聊普通文本或引用回复中配合 --mention 成员ID 或 --mention-all 可实现群成员 @ 提醒。
发送较大文件时,可指定 --wait 3600 延长等待时间至一小时。更多信息请查看附件大小限制与进度。
引用回复
-
在
wx messages list CHAT_ID --json的返回结果中复制被引用消息的完整id与serverId。 -
发送带有两项引用参数的文本回复:
Terminal window wx messages send CHAT_ID --text "收到,赞同" \--quote-message-id MESSAGE_ID --quote-server-id SERVER_ID --detach已进入队列的回复会展示其任务 ID、状态以及本地收据路径。可通过
wx messages sends get SEND_ID查询状态。
对于群聊中的引用回复,可以在同一命令中添加 --mention 成员ID 或 --mention-all。
需要 read 和 send 权限,且原消息必须存在于当前会话的本地记录中。参见 API 与 SDK 示例。
| 原消息类型 | 是否支持被引用 |
|---|---|
| 文本、图片、语音、视频或文件 | 支持已保存的标准格式 |
| 表情、分享表情、分享文本、音乐/视频/链接/视频号卡片或纯文本群公告 | 支持已保存的标准格式 |
| 名片分享或静态位置 | 支持经验证的已保存格式 |
| 已是引用回复的消息 | 引用其自身的回复内容 |
| 合并转发聊天记录 | 引用其摘要内容;嵌套消息被省略 |
| 系统/控制消息、上传通知、专用或未知卡片 | 不支持引用 |
下载媒体附件
wx messages media CHAT_ID MESSAGE_ID --output ./photo.jpgwx messages media CHAT_ID MESSAGE_ID --quality original --output ./photo.jpg默认 --quality best 会自动返回本地可用的最高质量副本。--cached-only 参数仅读取本地缓存,绝不发起网络下载。
实时监听新消息
wx events watch --cursor-file ~/.cache/wx-events.cursor在新消息到达时实时输出事件详情。添加 --json 可逐行输出 JSON 事件。配合游标文件可在意外中断后精准断点续传。
标记已读与撤回消息
wx chats get CHAT_ID # 获取会话当前的 Read State Versionwx chats read CHAT_ID --expected-version VERSIONwx messages recall MESSAGE_ID --server-id SERVER_ID标记已读会更新整个会话的已读状态,并同步至你的其他微信登录端。撤回消息需要传入 wx messages list CHAT_ID --json 中对应的完整 id 与 serverId。
连接远程机器上的 Daemon
wx config servers add box --url https://wx.example.com --token-file ~/.config/agent-wechat/box-tokenwx config servers select box