跳转到内容

CLI 命令参考

执行 wx --help 可查看顶级命令分组,wx accounts --help 查看某个命令组的子命令,或者 wx accounts select --help 查看具体操作参数。帮助信息按字母顺序排列并详细解释功能。所有命令默认输出易读的文本结果,添加 --json 可获得便于脚本解析的机器可读 JSON 输出。

命令列表

顶级命令子命令与操作
wx serve在前台启动守护服务进程
wx daemon后台托管命令:start、status、logs [--follow]、stop
wx auth认证授权:login [--official[=PATH]] [--qr] [--saved-only]、status、qr ID、attempts get/cancel ID、logout [--local]、forget --yes
wx accounts账号管理:alias ID NAME、capabilities、connect、create [ID] [--alias NAME]、disconnect、get [ID]、list、remove ID --confirm ID、select ID、settings [--auto-download-max-mb MB]、status
wx chats会话管理:list、get ID、find TEXT、read ID --expected-version V、mute ID、unmute ID、pin ID、unpin ID
wx messages消息收发:list CHAT、get CHAT ID、send CHAT --text/--image/--file/--video/--voice/--share、media CHAT ID、指定 --video 时搭配 --video-quality normal/original、recall ID --server-id S、sends lookup/get/cancel
wx contacts联系人:list、find TEXT、get ID、lookup ID...、refresh ID、sync、avatar ID
wx groups群组操作:list、get ID、lookup ID [--version N]、members list/get/refresh/add/remove、create MEMBERS...、rename ID NAME、leave ID、my-name ID NAME、clear-announcement ID、refresh ID、sync
wx events事件流:watch [--cursor-file F]、list、ack --consumer NAME --through CURSOR
wx calls实时通话:status、monitor [--json]、dial 联系人、answer [CALL_ID]
wx jobs后台任务:get ID、cancel ID、retry ID [--reuse-completed-upload]、repair-writeback
wx operations操作记录:get ID
wx sync立即触发增量消息拉取同步
wx tokensAPI 令牌:list、create NAME --accounts ID --scopes S、revoke ID
wx configCLI 配置:client、servers add/list/remove/select、show
wx profiles在无需 Daemon 启动的情况下离线只读审查 Profile(add、avatars、chats、contacts、groups、images、inspect、keys export、list、messages、select)
wx store实验性:复制、导入与导出 Profile
wx version查看版本与编译目标平台

contacts find、groups find 与 groups members list --search 用于在已保存的本地目录中搜索。搜索不区分大小写,并会组合匹配以空格分隔的多个词语:wx contacts find "Mira work" 可以在同一联系人的昵称和备注中同时匹配。contacts lookup 向微信服务端实时请求一个或两个确切联系人 ID 的详情。如果好友备注和昵称均为空,则显示名称默认取用其联系人 ID。groups lookup 向微信服务端实时请求指定群聊 ID 的完整成员名册。两种查询都不会保存结果;如需更新本地数据,请使用 contacts refresh 或 groups members refresh。

select 命令用于在 CLI 本地配置中持久化默认偏好:

命令保存的默认配置
wx config servers select NAME后续所有命令默认使用的目标服务端
wx accounts select ID指定服务端上默认使用的账号 ID 或别名
wx profiles select NAME指定服务端对应的本地 Profile,未指定服务端时为独立的本地 Profile

设置默认值并不会自动登录或建立连接。可在单个命令中使用 --server-name、--account 或 --local-profile 参数临时覆盖默认设置。旧版命令写法仍保持兼容,但帮助信息中仅展示上述标准命令。

全局标志 (Global Flags)

命令行标志对应环境变量作用说明
--account IDAGENT_WECHAT_ACCOUNT指定操作的目标账号 ID 或别名
--server-name NAMEAGENT_WECHAT_SERVER指定通过 wx config servers add 保存的服务器配置名称
--server URLAGENT_WECHAT_URL指定 Daemon 服务的直接访问 URL
--token-file PATHAGENT_WECHAT_TOKEN_FILE存放 API 访问令牌的文件路径
AGENT_WECHAT_TOKEN访问令牌直接字符串(建议优先使用文件路径形式)
--config PATHAGENT_WECHAT_CONFIGCLI 配置文件路径
--json输出机器友好的机器可读结果与错误。事件监听模式下每行输出一个 JSON 事件。

命令行标志优先级高于环境变量,环境变量优先级高于本地配置文件。所有耗时后台命令(发送、下载、登录、撤回等)均支持传入 --detach,使命令在任务成功入队后立即返回。

在自动化脚本中可使用 wx daemon status --json 解析守护进程状态。wx serve --json 会在 stderr 上输出服务就绪记录。wx daemon logs 会流式输出原始格式的日志记录。

messages send --wait SECONDS 参数对附件发送最长允许等待 3,600 秒,对文本或分享链接最长允许等待 900 秒(默认 30 秒)。发送大文件建议指定 --wait 3600。等待超时将返回退出状态码 7,此时后台任务仍在持续运行;可通过 wx jobs get JOB_ID 进行跟踪。参考发送附件与媒体。

退出状态码 (Exit Codes)

状态码含义
0成功完成,或已使用 --detach 成功入队
2输入参数或配置无效
3无法连接到 Daemon 服务
4令牌被拒绝或缺少必要权限范围
5需要登录
6需要用户交互:在手机端确认或扫码
7等待时间已结束但任务仍在后台运行;可稍后查询
8结果未决 (needs_review):切勿直接盲目重发
9执行失败
130已中断(Daemon 服务仍在继续运行)