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 tokens | API 令牌:list、create NAME --accounts ID --scopes S、revoke ID |
wx config | CLI 配置: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 ID | AGENT_WECHAT_ACCOUNT | 指定操作的目标账号 ID 或别名 |
--server-name NAME | AGENT_WECHAT_SERVER | 指定通过 wx config servers add 保存的服务器配置名称 |
--server URL | AGENT_WECHAT_URL | 指定 Daemon 服务的直接访问 URL |
--token-file PATH | AGENT_WECHAT_TOKEN_FILE | 存放 API 访问令牌的文件路径 |
AGENT_WECHAT_TOKEN | 访问令牌直接字符串(建议优先使用文件路径形式) | |
--config PATH | AGENT_WECHAT_CONFIG | CLI 配置文件路径 |
--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 服务仍在继续运行) |