wms-cli 使用指南

微秘书 (WMS) 命令行工具，让你用一行命令查好友、查群、发消息，也能让 AI 助手（Claude Code / Codex / OpenClaw / Hermes）自动帮你操作微信。

这是什么？

wms-cli（npm 包名 @aibotk/wms-cli）是微秘书平台的官方命令行工具。

两类典型用户：

• 👤 运营 / 社群管理者 —— 用命令快速给群发通知、查找客户、批量推送，比在面板里点鼠标快很多
• 🤖 AI Agent 玩家 —— 让 Claude Code 等 AI 助手用自然语言操作你的微信（"帮我给运营群发条公告"），背后自动调用 wms 命令

支持的能力：

• 查找好友（按昵称模糊搜索）
• 查找群（按群名模糊搜索）
• 给好友发消息（文字 / 图片 / URL 卡片）
• 给群发消息（文字 / 图片 / URL 卡片）
• 群公告 @所有人（机器人需是群主或管理员）
• 批量给多个好友 / 多个群发多条消息
• 多账号 / 多环境切换

准备工作

1. 你需要

提前安装好 codex / claude-code / openclaw / hermes

2. 获取你的 apiKey

apiKey 是工具调用接口时的"身份令牌"，从微秘书面板拿：

1. 登录 https://wechat.aibotk.com
2. 进入 个人中心 → API 接口（或"开发者中心"）
3. 复制你的 apiKey（形如 253c396e60a955ad7b3b9944b9046184e63c7c63 这样的 40 位字符串）

⚠️ apiKey 等同于密码，不要发到群里、不要写进代码 commit，建议放本地配置文件或环境变量。

3. 确认机器人在线

去面板看你的机器人是否显示"在线"。如果掉线，先到面板重新扫码登录，再来用 CLI。

安装

npm install -g @aibotk/wms-cli

安装成功后会看到：

✓ @aibotk/wms-cli 已安装

快速开始：
  wms auth token <你的 apiKey>
  wms auth whoami --json
  ...

验证安装：

wms --version
# 输出 0.1.0（或更高）

wms --help
# 列出所有子命令

让 AI 助手用 wms 帮你操作

wms-cli 自带一份 SKILL 文档，让 AI Agent 能"听懂"WeChat 任务并自动调用 CLI。

一行命令装到所有支持的 AI 平台：

wms install-skill --platform all

支持的平台与生效方式：

装好后，直接用自然语言告诉 AI：

"这是微秘书的 apiKey: xxxxxxxxxx, 帮我使用微秘书, 找一下我的好友『张三』，给她发『下周一开会哈』"

AI 会自动完成：

1. wms contact list --keyword 张三 --json 拿到 wxid
2. wms send contact --to <wxid> --text "下周一开会哈" --json 发消息
3. 把结果反馈给你

群公告同理：

"给运营群发个公告：明早 9 点全员到场"

AI 会自动转成 wms send multi --target roomnotice --groups <运营群 wxid> --text "明早 9 点全员到场"。

命令速查

直接使用CLI

1. 配置 apiKey

wms auth token 253c396e60a955ad7b3b9944b9046184e63c7c63
# 输出：Profile "default" saved (https://api-bot.aibotk.com)

apiKey 会被保存在 ~/.wms/config.json，文件权限自动设为 0600（只有你自己能读）。

2. 验证有效

wms auth whoami --json

正常返回你机器人的信息：

{
  "wxid": "1688853763013591",
  "name": "xxx",
  "avatar": "https://img.aibotk.com/wechat/avatar/...",
  "online": true,
  "heartBeat": "live",
  "panelVersion": "1.6.123"
}

如果看到 "online": false，机器人掉线了——回面板重新扫码。 如果返回错误 [auth]，apiKey 错了——核对一遍重新 wms auth token。

使用案例

下面所有命令都加了 --json，方便复制结果、写脚本。日常人工使用可以去掉 --json 拿到表格输出。

案例 1：找好友

按昵称模糊搜索：

wms contact list --keyword "张三" --json

返回：

{
  "robotInfo": { "wxid": "...", "name": "...", ... },
  "total": 1,
  "list": [
    {
      "name": "张三",
      "alias": "三哥",
      "wxid": "7881301415957290",
      "weixin": "zhangsan_wx"
    }
  ]
}

重点字段：wxid 才是发消息要用的标识（不是 uniqueId，那是数据库主键）。

案例 2：找群

wms room list --keyword "运营" --json

返回：

{
  "robotInfo": { ... },
  "total": 1,
  "list": [
    {
      "topic": "运营群",
      "wxid": "R:10804599808581977",
      "memberCount": 38,
      "ownerId": "1688853763013591"
    }
  ]
}

群名字段叫 topic（不是 name）；群 wxid 形如 R:数字。

案例 3：给好友发文字

wms send contact --to 7881301415957290 --text "你好，这是测试消息" --json

返回 {"code":0,"msg":"ok","data":{}} 表示已下发。

发图片：

wms send contact --to 7881301415957290 --image "https://example.com/image.jpg" --json

发 URL 卡片（4 个字段全要）：

wms send contact --to 7881301415957290 \
  --card-url "https://www.aibotk.com" \
  --card-title "微秘书官网" \
  --card-desc "智能微信机器人平台" \
  --card-thumb "https://img.aibotk.com/logo.png" --json

案例 4：给群发消息

wms send room --to "R:10804599808581977" --text "今晚 8 点开会" --json

支持的内容类型与发好友相同（文字/图片/卡片）。

案例 5：发群公告（@所有人）

群公告是特殊场景，调 chat/multi 接口、target=roomnotice、只支持文字：

wms send multi --target roomnotice \
  --groups "R:10804599808581977" \
  --text "【公告】本周日 9:00 全员加班，请按时打卡" --json

一次给多个群发同一份公告：

wms send multi --target roomnotice \
  --groups "R:111,R:222,R:333" \
  --text "公司全员通知..." --json

多行公告（用 \n 换行）：

wms send multi --target roomnotice \
  --groups "R:10804599808581977" \
  --messages-json '[{"type":1,"content":"第一段公告\n\n第二段内容\n第三段总结"}]' --json

⚠️ 机器人必须是该群的群主或管理员，否则即便接口返回成功，实际公告也不会生效。建议先 --dry-run 看请求结构。

案例 6：批量给多个目标发多条混合消息

一次给 2 个群各发 2 条消息（先文字、后图片）：

wms send multi --target room \
  --groups "R:111,R:222" \
  --messages-json '[
    {"type":1,"content":"早安各位"},
    {"type":2,"url":"https://example.com/morning.jpg"}
  ]' \
  --delay 1000 --json

--delay 控制每条消息的发送间隔（默认 600ms，避免太快被风控）。

批量给好友也可以（注意 target=contact、--groups 里填好友 wxid 列表）：

wms send multi --target contact \
  --groups "wxid_a,wxid_b,wxid_c" \
  --text "节日祝福" --json

案例 7：先找人再发消息（一键脚本）

最常用的工作流——根据昵称找到 wxid 再发消息：

WXID=$(wms contact list --keyword "张三" --json | jq -r '.list[0].wxid // empty')
[ -z "$WXID" ] && { echo "没找到张三"; exit 1; }

wms send contact --to "$WXID" --text "你好" --json

需要 jq 工具（macOS：brew install jq；Ubuntu：apt install jq）。

案例 8：演练但不实发（dry-run）

发任何命令前都可以加 --dry-run，看请求结构但不真发出去：

wms send multi --target roomnotice --groups "R:xxx" --text "测试" --dry-run --json

输出：

{
  "dryRun": true,
  "method": "POST",
  "url": "https://api-bot.aibotk.com/openapi/v1/chat/multi",
  "body": {
    "target": "roomnotice",
    "groups": [{"wxid": "R:xxx", "name": ""}],
    "messages": [{"type": 1, "content": "测试"}],
    "delay": 600,
    "apiKey": "253c39..."
  }
}

多账号 / 多环境

如果你管理多个微秘书账号（比如 dev 测试 + prod 生产，或 A 公司 + B 公司机器人），可以建多个 profile：

# 配置两个账号
wms auth token <key-A> --profile-name companyA
wms auth token <key-B> --profile-name companyB

# 查看所有
wms auth list

# 切换默认账号
wms auth use companyB

# 临时用 A 账号执行一条命令（不改默认）
wms --profile companyA contact list --keyword "..." --json

apiKey 在列表中会自动遮罩成 253c...7c63，截图分享不怕泄露。

环境变量也能临时覆盖（适合 CI 场景）：

WMS_API_KEY=<key> wms contact list --json

常见问题

Q：wms 命令找不到？ A：确认 npm i -g @aibotk/wms-cli 装到了全局；运行 which wms 看路径；如果 PATH 没有 npm 全局 bin，加一下：export PATH="$(npm config get prefix)/bin:$PATH"。

Q：返回 [auth] 请检查apiKey是否填写错误？ A：apiKey 错了或被吊销。回面板复制一份新的，重新 wms auth token <apiKey>。

Q：返回 [vip_required] 或 没有权限，请在微秘书平台开通会员后使用？ A：发消息相关接口要求 VIP。请到微秘书面板开通会员。

Q：发群公告返回 code=0 但群里没看到？ A：检查机器人是不是该群的群主或管理员——只有群主/管理员才能发公告。普通成员的机器人没这个权限，接口虽然返回成功但实际不会触达群。

Q：消息发出去了但好友/群没收到？ A：检查 wms auth whoami 看机器人 online 是不是 true。如果 false，机器人掉线了，需要回面板重新扫码登录。

Q：批量发消息会不会被风控？ A：单账号建议把 --delay 调大（默认 600ms，谨慎可以设到 2000-3000ms），单次群发的目标数量也别太多。具体限额请参考微秘书面板说明。

退出码

写脚本时用得上：

一行话总结

npm i -g @aibotk/wms-cli && wms auth token <你的apiKey> && wms auth whoami --json

跑通这一行，你就准备好了。