shellbot-cli

v0.1.4

Published

21 days ago

CLI SDK for ShellBot WeAssist platform — designed for AI agents

0High
0Medium
0Low

leo_chen

shellbot weassist wechat cli ai-agent

shellbot-cli 使用文档

ShellBot AI 平台命令行工具，支持微信、WhatsApp 机器人的全功能管理。专为 AI Agent（Claude Code、OpenHands、Codex）和人工操作双场景设计。

安装

# 全局安装（推荐）
npm install -g shellbot-cli

安装后，后置脚本自动检测本机 AI Agent 平台并打印安装提示：

┌──────────────────────────────────────────────────────────────┐
│                   shellbot-cli installed ✓                   │
│  Install AI agent skill (copies from this npm package):      │
│    shellbot install-skill                  (interactive)     │
│    shellbot install-skill -y --platform all                  │
│  Detected: Claude Code, OpenClaw                             │
└──────────────────────────────────────────────────────────────┘

安装 AI Agent Skill

执行以下命令，将 shellbot skill 注册到 AI Agent 平台，让 Claude Code / OpenClaw / Codex 等 AI 具备原生 shellbot 操作能力：

# 交互式安装（推荐新手使用）
shellbot install-skill

# 非交互式（脚本 / CI 环境）
shellbot install-skill --platform claude                  # 仅 Claude Code
shellbot install-skill --platform openclaw                # 仅 OpenClaw
shellbot install-skill --platform codex                   # 仅 Codex (OpenAI)
shellbot install-skill --platform hermes                  # 仅 Hermes
shellbot install-skill --platform claude,openclaw,hermes  # 多平台
shellbot install-skill --platform all                     # 全部已检测平台
shellbot install-skill --platform all --scope project     # 仅当前项目
shellbot install-skill --platform all --yes               # 跳过确认

安装完成后重启 AI Agent 会话即可生效，无需额外配置。

Skill 文件随 npm 包一起分发（在 node_modules/shellbot-cli/skill/ 下），install-skill 只是把它复制到 AI Agent 的 skills 目录，无需 git clone，无需额外下载。

支持的平台

| 平台 | Skill 目录 | |------|-----------| | Claude Code | ~/.claude/skills/shellbot/ | | OpenClaw | ~/.openclaw/skills/shellbot/ | | Codex (OpenAI) | ~/.codex/skills/shellbot/ | | Hermes | ~/.hermes/skills/shellbot/ |

快速开始

# 第一步：配置 API Key（默认服务地址 https://rpa.openai-next.com）
shellbot auth token <your-api-key>

# 或使用自定义服务器
shellbot auth token <your-api-key> --host https://your-server.com

# 第二步：验证连接
shellbot auth whoami

# 第三步：查看机器人列表
shellbot bot list

# 第四步：发送消息
shellbot message send --bot 1 --to wxid_abc123 --text "你好！"

全局选项

所有命令均支持以下全局选项：

| 选项 | 说明 | |------|------| | --json | 输出原始 JSON；错误也以 JSON envelope 写入 stderr | | --dry-run | 打印请求详情，不执行；AI Agent 专用安全验证模式 | | --profile <name> | 使用指定配置 profile（默认 default）| | --host <url> | 临时覆盖 API 服务器地址 | | --debug | 打印请求/响应详情 | | --yes, -y | 跳过危险操作确认提示 | | --no-color | 禁用颜色输出 |

JSON 错误格式

使用 --json 时，所有错误以结构化 envelope 写入 stderr，stdout 不含错误内容：

{
  "ok": false,
  "error": {
    "type": "auth",
    "code": 2,
    "message": "Profile \"default\" not found",
    "hint": "shellbot auth token <key> --host <url>"
  }
}

| type | 含义 | 建议操作 | |--------|------|---------| | auth | 未配置凭证或 Key 无效 | 执行 shellbot auth token | | api | API 业务错误 | 检查 message 字段 | | validation | 参数缺失或格式错误 | 检查命令参数 | | network | 网络/设备错误（可重试）| 重试；检查 --host | | timeout | 异步等待超时 | 延长 --wait 或手动轮询 |

--dry-run

打印将要发送的 HTTP 请求并退出（exit 0），不实际调用 API。未配置凭证也可使用。

shellbot message send --bot 1 --to wxid_abc --text "你好" --dry-run
# 输出：
# {
#   "dryRun": true,
#   "method": "POST",
#   "url": "https://your-server.com/aiapi/v1/bots/1/messages/send",
#   "body": { "targetType": "contact", "targetId": "wxid_abc", ... }
# }

命令参考

`auth` — 认证管理

# 保存 API Key（默认服务地址 https://rpa.openai-next.com，可省略 --host）
shellbot auth token <apiKey>

# 使用自定义服务器
shellbot auth token <apiKey> --host https://your-server.com

# 保存到指定 profile
shellbot auth token <apiKey> --host https://prod.example.com --profile-name prod

# 验证 Key 是否有效，返回当前用户信息
shellbot auth whoami

# 删除本地凭证
shellbot auth logout

# 删除指定 profile 的凭证
shellbot auth logout --profile-name dev

`bot` — 机器人管理

# 查看机器人列表
shellbot bot list
shellbot bot list --status online        # 只看在线
shellbot bot list --page 2 --page-size 50

# 查看单个机器人详情
shellbot bot get <id>

# 实时状态（botState + PM2 状态 + 登录状态）
shellbot bot status <id>

# 启动 / 停止 / 重启
shellbot bot start <id>
shellbot bot start <id> --wait           # 等待进入终态再返回
shellbot bot stop <id>
shellbot bot stop <id> --wait
shellbot bot restart <id>
shellbot bot restart-all --yes           # 重启全部机器人

# 检查所有机器人是否在线
shellbot bot check-online

# 扫码登录（终端渲染二维码，自动轮询直到登录成功）
shellbot bot qr <id>

# 查看日志
shellbot bot logs <id>
shellbot bot logs <id> --lines 200

# 重置 AI 对话上下文
shellbot bot reset-context <id>

# 触发联系人同步
shellbot bot sync-contacts <id>

# 发送控制事件
shellbot bot event <id> logout

# 更新机器人配置
shellbot bot config <id> --chat-enabled true --chat-ai-account 2
shellbot bot config <id> --friend-welcome-enabled true --friend-welcome-message "欢迎添加！"
shellbot bot config <id> --room-welcome-enabled true --room-welcome-message "欢迎入群！"
shellbot bot config <id> --auto-summer-enabled true

botState 枚举值

| 值 | 含义 | |----|------| | running | 运行中（已登录） | | login_required | 需要扫码登录 | | scan_pending | 等待扫码 | | confirm_pending | 等待手机确认 | | starting | 启动中 | | stopped | 已停止 | | error | 异常 | | offline | 掉线 |

`message` — 消息发送

# 发送文字消息给好友
shellbot message send --bot 1 --to wxid_abc123 --text "你好！"

# 发送到群（需指定 --type room）
shellbot message send --bot 1 --to room@chatroom --type room --text "群公告"

# 发送并 @ 指定成员
shellbot message send --bot 1 --to room@chatroom --type room \
  --text "请注意" --at wxid1,wxid2

# 发送图片 / 文件
shellbot message send --bot 1 --to wxid_abc123 --image https://example.com/img.jpg
shellbot message send --bot 1 --to wxid_abc123 --file https://example.com/doc.pdf

# 群发给多个目标
shellbot message broadcast --bot 1 --targets wxid1,wxid2,wxid3 --text "通知内容"

# 群发给用户分组
shellbot message broadcast --bot 1 --group 5 --text "分组通知"

# 使用素材库群发
shellbot message broadcast --bot 1 --group 5 --material 3

`contact` — 联系人管理

shellbot contact list --bot 1
shellbot contact list --bot 1 --keyword "张三"
shellbot contact list --bot 1 --all              # 自动翻页获取全部
shellbot contact get --bot 1 --wxid wxid_abc123

`room` — 群组管理

# 查看群列表
shellbot room list --bot 1
shellbot room list --bot 1 --keyword "运营"
shellbot room list --bot 1 --all                 # 获取全部

# 查看群详情
shellbot room get --bot 1 --wxid room@chatroom

# 建群
shellbot room create --bot 1 --name "新群名" --members wxid1,wxid2,wxid3

# 建群并发送欢迎消息
shellbot room create --bot 1 --name "VIP群" --members wxid1,wxid2 \
  --message "欢迎加入！"

# 邀请联系人进群
shellbot room invite --bot 1 --room room@chatroom --contacts wxid4,wxid5

# 发布群公告
shellbot room announce --bot 1 --room room@chatroom --content "重要公告内容"

`reply` — 自动回复规则

# 查看规则列表（必须指定 --bot）
shellbot reply list --bot 1

# 查看单条规则
shellbot reply get <id> --bot 1

# 创建规则（使用素材回复）
shellbot reply create \
  --bot 1 \
  --name "订单咨询" \
  --keywords "订单,购买,怎么买" \
  --match fuzzy \
  --scope group \
  --reply-type material \
  --material-ids 1,2,3

# 创建规则（AI 回复）
shellbot reply create \
  --bot 1 \
  --name "智能客服" \
  --keywords "帮助,支持,问题" \
  --reply-type ai \
  --ai-account 1

# 更新规则
shellbot reply update <id> --bot 1 --name "新名称" --keywords "新,关键词"

# 删除规则（ids 可用逗号分隔传多个）
shellbot reply delete <ids> --bot 1 --yes

--match 取值：fuzzy（模糊匹配）、exact（精确匹配）

--scope 取值：all（全部）、group（仅群）、contact（仅好友）

--reply-type 取值：none、material（固定素材）、random_material（随机素材）、ai（AI 回复）

`schedule` — 定时任务

# 查看定时任务（必须指定 --bot）
shellbot schedule list --bot 1
shellbot schedule get <id> --bot 1

# 创建素材群发定时任务（每天 9 点）
shellbot schedule create \
  --name "每日早报" \
  --bot 1 \
  --cron "0 9 * * *" \
  --type material \
  --group 1 \
  --materials 1,2,3

# 创建消息总结定时任务（每天 20 点）
shellbot schedule create \
  --name "每日总结" \
  --bot 1 \
  --cron "0 20 * * *" \
  --type summerChat \
  --ai-account 1 \
  --summer-type time \
  --summer-time 24 \
  --source-rooms room1@chatroom,room2@chatroom \
  --send-to-contacts wxid_admin

# 更新 cron 表达式
shellbot schedule update <id> --bot 1 --cron "0 10 * * *"

# 启用 / 禁用
shellbot schedule enable <id> --bot 1
shellbot schedule disable <id> --bot 1

# 立即触发（不等待 cron）
shellbot schedule trigger <id> --bot 1

# 删除
shellbot schedule delete <ids> --bot 1 --yes

--type 取值：material（素材群发）、summerChat（消息总结）、sendMoment（发朋友圈）

`callback` — Webhook 回调

# 查看回调列表（必须指定 --bot）
shellbot callback list --bot 1
shellbot callback get <id> --bot 1

# 创建 Webhook 回调
shellbot callback create \
  --bot 1 \
  --name "订单通知" \
  --url https://your-app.com/webhook \
  --keyword "订单" \
  --method POST \
  --header "Authorization=Bearer token123" \
  --header "X-Source=wechat"

# 更新
shellbot callback update <id> --bot 1 --url https://new-url.com

# 删除
shellbot callback delete <ids> --bot 1 --yes

`material` — 消息素材库

# 查看素材列表
shellbot material list
shellbot material list --type text
shellbot material list --keyword "促销"
shellbot material get <id>

# 创建文字素材
shellbot material create --name "欢迎语" --type text --content "欢迎关注！"

# 创建图片素材
shellbot material create --name "品牌 Logo" --type image_url \
  --url https://example.com/logo.png

# 更新 / 删除
shellbot material update <id> --name "新名称" --content "新内容"
shellbot material delete <ids> --yes

`moment` — 发朋友圈

仅支持 puppetType 2（padlocal）或 7（matrix）协议的机器人。

# 发纯文字朋友圈
shellbot moment send --bot 1 --type text --content "早安！"

# 发图片朋友圈
shellbot moment send --bot 1 --type image \
  --images https://example.com/img1.jpg,https://example.com/img2.jpg \
  --content "图片说明"

# 发视频朋友圈
shellbot moment send --bot 1 --type video --video https://example.com/video.mp4

# 批量向多个机器人发朋友圈
shellbot moment broadcast --bots 1,2,3 --type text --content "多账号同步发布"

# 使用朋友圈素材批量发布
shellbot moment broadcast --bots 1,2,3 --material 5

`moment-material` — 朋友圈素材库

shellbot moment-material list
shellbot moment-material list --type image
shellbot moment-material get <id>

# 创建图片素材
shellbot moment-material create \
  --name "促销海报" \
  --type image \
  --content "限时优惠！" \
  --images https://example.com/img1.jpg,https://example.com/img2.jpg

shellbot moment-material update <id> --content "更新文案"
shellbot moment-material delete <ids> --yes

--type 取值：text（纯文字）、image（图片）、video（视频）、link（卡片链接）、channel（视频号）

`summarize` — AI 内容总结

# 总结指定群的最近 N 条消息，结果发给管理员
shellbot summarize chat \
  --bot 1 \
  --from-rooms room1@chatroom \
  --count 100 \
  --send-to-contacts wxid_admin \
  --ai-account 1

# 按时间段总结聊天记录
shellbot summarize chat \
  --bot 1 \
  --from-rooms room1@chatroom,room2@chatroom \
  --since "2026-04-17T08:00:00" \
  --until "2026-04-17T20:00:00" \
  --send-to-contacts wxid_admin

# 总结指定 URL 内容并发送给好友
shellbot summarize url \
  --bot 1 \
  --url https://example.com/article \
  --send-to wxid_admin

`ai` — AI 账号与模型管理

# 查看 AI 账号
shellbot ai account list
shellbot ai account get <id>

# 创建 AI 账号（OpenAI）
shellbot ai account create \
  --name "GPT-4o" \
  --provider openai \
  --api-key sk-xxx \
  --url https://api.openai.com/v1 \
  --model-id 1 \
  --system-message "你是一个专业的客服助手"

# 创建 AI 账号（Dify）
shellbot ai account create \
  --name "Dify 工作流" \
  --provider dify \
  --api-key app-xxx \
  --url https://api.dify.ai/v1

# 更新 / 删除
shellbot ai account update <id> --name "新名称" --system-message "更新后的提示词"
shellbot ai account delete <ids> --yes

# 查看可用 AI 模型
shellbot ai model list
shellbot ai model all

--provider 取值：openai、dify、fastgpt、coze

`group` — 用户分组（广播目标）

# 查看分组（必须指定 --bot）
shellbot group list --bot 1
shellbot group get <id> --bot 1

# 创建"所有联系人"分组
shellbot group create --name "全部好友" --bot 1 --scope all-contacts

# 创建"所有群"分组
shellbot group create --name "全部群" --bot 1 --scope all-rooms

# 创建自定义分组（指定群 + 好友）
shellbot group create --name "VIP 群组" --bot 1 --scope custom \
  --include-rooms room1@chatroom,room2@chatroom \
  --include-contacts wxid1,wxid2

# 更新 / 删除
shellbot group update <id> --bot 1 --name "新分组名"
shellbot group delete <ids> --bot 1 --yes

--scope 取值：all、all-rooms、all-contacts、custom

`history` — 聊天记录查询

# 查看聊天记录（必须指定 --bot）
shellbot history list --bot 1
shellbot history list --bot 1 --since 2026-01-01T00:00:00Z
shellbot history list --bot 1 --until 2026-04-17T23:59:59Z
shellbot history list --bot 1 --conversation conv_123

# 查看所有会话列表
shellbot history conversations --bot 1

`install-skill` — 安装 AI Agent Skill

将内置 skill 文件复制到 AI Agent 平台的 skills 目录，使 Claude Code、OpenClaw 等 AI 具备原生 shellbot 操作能力。

# 交互式：引导选择 scope（全局/项目）和目标平台
shellbot install-skill

# 非交互式
shellbot install-skill --platform claude              # ~/.claude/skills/shellbot/
shellbot install-skill --platform openclaw            # ~/.openclaw/skills/shellbot/
shellbot install-skill --platform codex               # ~/.codex/skills/shellbot/
shellbot install-skill --platform all                 # 全部三个平台
shellbot install-skill --platform claude --scope project  # 仅当前项目
shellbot install-skill --platform all --yes --json    # CI 环境

安装后重启 AI Agent 会话生效。

`spec` — 输出 OpenAPI 规范

# 输出完整 OpenAPI 3.0 YAML 规范
shellbot spec

# 保存到文件
shellbot spec > openapi.yaml

AI Agent 使用指南

所有命令支持 --json，AI Agent 只需读取机器可读格式。

快速配置（给 AI Agent 使用）

# 1. 全局安装
npm install -g shellbot-cli

# 2. 安装 skill 到 AI Agent 平台
shellbot install-skill --platform claude --yes   # Claude Code
shellbot install-skill --platform all --yes      # 全平台

# 3. 配置 API Key
shellbot auth token <api-key> --host https://your-server.com

# 4. 重启 AI Agent 会话

Skill 安装完成后，AI Agent 自动具备所有 shellbot 命令的使用能力，无需额外提示。

Claude Code

在 Claude Code 中，使用 --json 获取结构化数据：

shellbot bot list --json
shellbot bot status 1 --json
shellbot message send --bot 1 --to wxid_abc --text "你好" --json

示例 Prompt：

使用 shellbot bot list --json 找到所有在线机器人，然后用 shellbot message send 向第一个机器人的第一个联系人发送欢迎消息。

OpenHands / Codex

结合 jq 解析 JSON 输出，实现自动化流程：

# 检查机器人状态，未在线则启动
STATUS=$(shellbot bot status 1 --json)
BOT_STATE=$(echo $STATUS | jq -r '.data.botState')

if [ "$BOT_STATE" != "running" ]; then
  shellbot bot start 1 --wait --json
fi

# 获取全部联系人并逐一发消息
shellbot contact list --bot 1 --all --json | \
  jq -r '.data[].wxid' | \
  xargs -I{} shellbot message send --bot 1 --to {} --text "通知内容" --json

与 AI 工具集成 OpenAPI 规范

# 导出规范供 AI 工具使用
shellbot spec > /tmp/shellbot-openapi.yaml

# 用 openapi-generator 生成任意语言 SDK
openapi-generator-cli generate \
  -i /tmp/shellbot-openapi.yaml \
  -g python \
  -o ./python-sdk

多环境配置

# 配置开发环境和生产环境
shellbot auth token <dev-key> --host https://dev.example.com --profile-name dev
shellbot auth token <prod-key> --host https://prod.example.com --profile-name prod

# 切换 profile 使用
shellbot --profile prod bot list
shellbot --profile dev bot list

退出码

| 退出码 | 含义 | |--------|------| | 0 | 成功 | | 1 | 业务错误（资源不存在、参数校验失败、资源冲突等）| | 2 | 认证/权限错误 | | 3 | 网络/设备错误（可重试）| | 4 | 等待异步操作超时 |

配置文件

凭证存储在 ~/.shellbot/config.json（文件权限 600）：

{
  "version": "1",
  "default": "prod",
  "profiles": {
    "prod": {
      "host": "https://your-server.com",
      "apiKey": "your-api-key",
      "addedAt": "2026-04-17T10:00:00.000Z"
    },
    "dev": {
      "host": "http://localhost:7008",
      "apiKey": "your-dev-key",
      "addedAt": "2026-04-17T10:00:00.000Z"
    }
  }
}

异步操作说明

bot start、bot stop、bot restart 为异步操作：

不带 --wait：立即返回，响应中含 statusUrl 可供轮询
带 --wait：CLI 自动轮询直到机器人进入终态（running / stopped / error）或超时（默认 60 秒，二维码登录最长 5 分钟）

License

MIT

开发与测试

npm test              # 单元测试（不联网）
npm run test:e2e      # 生产环境 E2E 实测（需以下环境变量）

E2E 测试会真实调用 ShellBot API，并向指定联系人/群发送测试消息。运行前设置：

export SHELLBOT_E2E_TOKEN=<你的 api-key>
export SHELLBOT_E2E_BOT_ID=<bot id>
export SHELLBOT_E2E_CONTACT_WXID=<测试联系人 wxid>
export SHELLBOT_E2E_ROOM_WXID=<测试群 wxid>                 # 可选
export SHELLBOT_E2E_HOST=https://rpa.openai-next.com       # 可选，这是默认值
npm run test:e2e

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

shellbot-cli 使用文档

安装

安装 AI Agent Skill

快速开始

全局选项

JSON 错误格式

--dry-run

命令参考

auth — 认证管理

bot — 机器人管理

message — 消息发送

contact — 联系人管理

room — 群组管理

reply — 自动回复规则

schedule — 定时任务

callback — Webhook 回调

material — 消息素材库

moment — 发朋友圈

moment-material — 朋友圈素材库

summarize — AI 内容总结

ai — AI 账号与模型管理

group — 用户分组（广播目标）

history — 聊天记录查询

install-skill — 安装 AI Agent Skill

spec — 输出 OpenAPI 规范