跳转到内容

CLI 常用命令

所有命令默认输出易读的文本格式。在脚本中解析输出时请加上 --json 参数。多账号环境下,请在命令中添加 --account ID(或账号别名)。

查看与读取

Terminal window
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 message
Book club books@chatroom group 2 See you Friday

wx messages list 会在表格中展示发送者、消息预览、时间戳及缩略消息 ID。如果历史记录处于部分拉取状态,表格下方会显示提示。如需获取完整消息文本、完整 ID 及数据库覆盖详情,请添加 --json。

已保存的联系人列表与搜索结果会省略 Profile 标记为已删除的条目。这些联系人的名称在已有会话和群成员列表中仍可查看。

会话的消息免打扰设置直接读取自本地已保存的 Profile。Daemon 通过联系人同步流实时接收手机端联系人变更。若返回 null,表示该字段缺失或尚未确定,通知消费端在此期间应对该会话保持静默。可执行 wx contacts refresh CONTACT_ID 手动拉取最新信息。wx chats mute/unmute 可开启或关闭单聊和群聊的消息免打扰;修改单聊时会先读取当前联系人信息,以保证无关字段不被覆盖。

filehelper 为文件传输助手,非常适合用来测试。群聊编辑与成员查询请参考管理群聊。

置顶聊天

Terminal window
wx chats pin CHAT_ID --idempotency-key pin-001
wx chats unpin CHAT_ID --idempotency-key unpin-001

需要 admin 权限范围,且目标需为已在本地会话列表中存在的普通单聊或活跃群聊。命令执行后将打印对应的操作记录和本地收据路径。请检查 remoteOutcome 和 profileProjection;若因网络异常未收到响应,请复用相同的参数与幂等键重试。重新调用 chats list 时置顶会话将排在最前。系统内置会话(如文件传输助手)不支持置顶修改。

发送消息

Terminal window
wx messages send CHAT_ID --text "在路上了"
wx messages send CHAT_ID --image ./photo.jpg
wx messages send CHAT_ID --file ./report.pdf
wx messages send CHAT_ID --video ./clip.mp4
wx 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 延长等待时间至一小时。更多信息请查看附件大小限制与进度。

引用回复

  1. 在 wx messages list CHAT_ID --json 的返回结果中复制被引用消息的完整 id 与 serverId。

  2. 发送带有两项引用参数的文本回复:

    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 示例。

原消息类型是否支持被引用
文本、图片、语音、视频或文件支持已保存的标准格式
表情、分享表情、分享文本、音乐/视频/链接/视频号卡片或纯文本群公告支持已保存的标准格式
名片分享或静态位置支持经验证的已保存格式
已是引用回复的消息引用其自身的回复内容
合并转发聊天记录引用其摘要内容;嵌套消息被省略
系统/控制消息、上传通知、专用或未知卡片不支持引用

下载媒体附件

Terminal window
wx messages media CHAT_ID MESSAGE_ID --output ./photo.jpg
wx messages media CHAT_ID MESSAGE_ID --quality original --output ./photo.jpg

默认 --quality best 会自动返回本地可用的最高质量副本。--cached-only 参数仅读取本地缓存,绝不发起网络下载。

实时监听新消息

Terminal window
wx events watch --cursor-file ~/.cache/wx-events.cursor

在新消息到达时实时输出事件详情。添加 --json 可逐行输出 JSON 事件。配合游标文件可在意外中断后精准断点续传。

标记已读与撤回消息

Terminal window
wx chats get CHAT_ID # 获取会话当前的 Read State Version
wx chats read CHAT_ID --expected-version VERSION
wx messages recall MESSAGE_ID --server-id SERVER_ID

标记已读会更新整个会话的已读状态,并同步至你的其他微信登录端。撤回消息需要传入 wx messages list CHAT_ID --json 中对应的完整 id 与 serverId。

连接远程机器上的 Daemon

Terminal window
wx config servers add box --url https://wx.example.com --token-file ~/.config/agent-wechat/box-token
wx config servers select box