weibo-cli：微博开放平台官方命令行工具使用指南

环境Node.js 18 · macOS / Linux / Windowsnpm 包weibo-ai/weibo-cli当前版本 0.8.3背景接入微博开放平台的常规路径是手写 HTTP 客户端——OAuth 鉴权、token 管理、分页、重试这些基础设施代码往往比业务逻辑本身更多。weibo-cli 是微博开放平台官方发布的 CLI 工具将这些基础设施内置以命令行的方式直接暴露平台接口同时也可以作为 MCP Server 接入 AI Agent 工作流。本文基于实际执行的验证结果记录安装流程、命令结构和三个可跑通的脚本示例。文中所有命令均经过执行验证参数和字段以实际输出为准。一、安装npm install -g weibo-ai/weibo-cli也可以用官方脚本建议先下载审查再执行不要直接管道给 bash推荐先下载确认内容后再执行curl -fsSL https://open.weibo.com/cli/install.sh -o install.shcat install.sh # 检查内容bash install.sh确认版本weibo-cli version0.8.3二、前置条件与鉴权2.1 开放平台配置在 open.weibo.com 按顺序完成三步缺少任何一步都会在 weibo-cli doctor 输出 ×步骤 位置 说明1 基本信息 → 开发者认证 实名认证未通过无法创建授权2 套餐订阅 选择方案获取调用额度有免费档3 设备授权 绑定本机后执行登录命令2.2 登录有桌面环境weibo-cli auth login无头环境SSH / Docker / CIweibo-cli auth login --device–device 会输出一个 URL 和验证码在任意浏览器中打开完成授权即可适合服务器场景。2.3 状态检查weibo-cli doctor✓ 登录账号: yourname✓ 完成开发者认证✓ 开通套餐: Ultraweibo-cli me --output table显示账号、余额、套餐有效期、额度使用情况2.4 套餐与额度方案 额度 价格Free 5 次/小时仅本人数据 免费Basic 3,000 Credits/月 ¥29Plus 7,500 Credits/月 ¥69Pro 32,000 Credits/月 ¥299Ultra 100,000 Credits/月 ¥899个人测试从 Free 起步足够weibo-cli doctor 可以随时检查当前状态。三、命令结构所有命令格式为 weibo-cli [flags]。# 查看当前套餐下可用命令 weibo-cli commands list --available # 查看某条命令的完整参数 weibo-cli commands show search statuses/limited weibo-cli commands show comments reply 注意事项不同套餐可用命令不同commands list --all 可以看到锁定项输出格式支持 --output json 和 --output table不支持 csv翻页参数统一为 --page返回条数为 --count不是 --limit当前 Ultra 套餐共 67 个命令覆盖以下模块模块 代表命令微博内容 statuses update / statuses user_timeline/other / statuses show_batch/biz评论 comments to_me/biz / comments reply / comments show/all搜索 search statuses/limited / search hot_word/biz粉丝关系 friendships followers/biz / friendships followers/age_group_count用户信息 users show/biz / users show_batch/other表态 attitudes create / attitudes show/biz影视榜单 wbindex ranking/tvHot / wbindex ranking/showHot四、常用命令示例4.1 关键词搜索微博weibo-cli search statuses/limited–q “关键词”–type 1–sort hot–count 20–output json result.json关键参数参数 必填 说明–q ✅ 关键词不能含 { } 等特殊字符–type ✅ 1 微博 / 2 评论 / 3 私信–sort ❌ time默认/ hot / fwnum / cmtnum–count ❌ 1050默认 10返回结构中关键字段{ total_number: 140316, statuses: [ { id: 5316534266232939, text: 微博正文, attitudes_count: 5592493, comments_count: 977316, reposts_count: 1000000, user: { id: 1234567890, screen_name: 用户昵称, followers_count: 80000000 } } ] }4.2 热搜榜weibo-cli search hot_word/biz --output json返回 data 数组每条包含 id排名、word词条、num热度值。固定返回 20 条不支持 --count 参数。输出热搜排名和热度weibo-cli search hot_word/biz --output json | python3 -c import sys, jsonfor item in json.load(sys.stdin)[‘data’]:print(f{item[‘id’]:2}. {item[‘word’]} {item[‘num’]})4.3 获取用户微博时间线查他人微博需要 UIDweibo-cli statuses user_timeline/other–uid 1234567890–count 50–output json查当前登录用户自己的微博weibo-cli statuses user_timeline/biz–count 20–output json–uid 可通过 users show_batch/other --screen_name 查到weibo-cli users show_batch/other–screen_name “用户昵称”–output json | python3 -c import sys, jsonusers json.load(sys.stdin)[‘users’]if users: print(users[0][‘id’])4.4 读取收到的评论weibo-cli comments to_me/biz–count 100–output json返回结构中每条评论包含 idstr评论ID、text内容、rootidstr所属微博ID。回复评论时这两个字段都是必填项。4.5 回复评论weibo-cli comments reply–id 微博ID–cid 评论ID–comment “回复内容”–id 是被评论的微博ID–cid 是要回复的评论ID两者都是必填来源分别是评论数据中的 rootidstr 和 idstr。五、脚本示例示例一热搜关键词监控检测某关键词是否出现在热搜榜超过热度阈值时触发通知。!/bin/bashmonitor_topic.shKEYWORD“AI工具”THRESHOLD50000FEISHU_WEBHOOK“https://your-webhook-url”HEAT(weibo−clisearchhotword/biz−−outputjson∣python3−cimportsys,jsondatajson.load(sys.stdin)[′data′]kw′(weibo-cli search hot_word/biz --output json | python3 -c import sys, json data json.load(sys.stdin)[data] kw (weibo−clisearchhotw​ord/biz−−outputjson∣python3−cimportsys,jsondatajson.load(sys.stdin)[′data′]kw′KEYWORD’matches [x for x in data if kw in x[‘word’]]print(matches[0][‘num’] if matches else ‘0’))if [ “HEAT−gtHEAT -gt HEAT−gtTHRESHOLD” ]; thencurl -s -X POST “$FEISHU_WEBHOOK”-H “Content-Type: application/json”-d “{“text”: “[监控] $KEYWORD 热度 $HEAT已超过阈值 $THRESHOLD”}”fi加入 crontab 每小时执行0 * * * * /path/to/monitor_topic.sh示例二指定账号时间线采集拉取指定账号的近期微博并保存为 JSON。!/bin/bashfetch_timeline.shSCREEN_NAME“目标账号昵称”通过昵称查 UIDUID(weibo−cliusersshowbatch/other −−screenname(weibo-cli users show_batch/other \ --screen_name (weibo−cliusersshowb​atch/other−−screenn​ameSCREEN_NAME–output json | python3 -c import sys, jsonusers json.load(sys.stdin)[‘users’]print(users[0][‘id’]) if users else exit(1))if [ -z “$UID” ]; thenecho “未找到用户:SCREENNAMEexit1fi拉取最近50条微博weibo−clistatusesusertimeline/other −−uidSCREEN_NAME exit 1 fi 拉取最近 50 条微博 weibo-cli statuses user_timeline/other \ --uid SCREENN​AMEexit1fi拉取最近50条微博weibo−clistatusesusert​imeline/other−−uidUID”–count 50–output json timeline_UID.jsonCOUNT{UID}.json COUNTUID.jsonCOUNT(python3 -c import jsonprint(len(json.load(open(‘timeline_${UID}.json’))[‘statuses’])))echo “已采集KaTeX parse error: Expected group after _ at position 21: … 条保存至 timeline_̲{UID}.json”示例三评论关键词筛选与批量回复筛选含特定关键词的评论批量回复。执行前建议先检查 inquiry.json 的内容写操作不可撤销。Step 1拉取最近 100 条收到的评论weibo-cli comments to_me/biz–count 100–output json comments.jsonStep 2筛选咨询类评论python3Windows/macOS/Linux 均可用python3 -c import json, recomments json.load(open(‘comments.json’))[‘comments’]pattern re.compile(r’多少钱|在哪买|怎么买|链接’)inquiry [c for c in comments if pattern.search(c.get(‘text’, ‘’))]print(f’匹配 {len(inquiry)} 条’)with open(‘inquiry.json’, ‘w’, encoding‘utf-8’) as f:json.dump(inquiry, f, ensure_asciiFalse, indent2)Step 3确认 inquiry.json 内容后执行批量回复python3 -c import json, subprocessfor c in json.load(open(‘inquiry.json’)):subprocess.run([‘weibo-cli’, ‘comments’, ‘reply’,‘–id’, c[‘rootidstr’],‘–cid’, c[‘idstr’],‘–comment’, ‘感谢咨询详情可私信了解’])六、已知限制无私信模块当前版本不支持私信相关操作无批量发布statuses update 只支持单条发布无 batch 接口热搜固定 20 条search hot_word/biz 不接受 --count 参数搜索接口有限速search statuses/limited 在 Pro 及以上套餐可用Basic/Plus 套餐受限输出格式仅支持 json 和 table不支持 csvWindows 环境weibo-cli 命令在 Git Bash 下存在路径解析问题建议用 PowerShell 或直接调用 node 执行参考官方文档https://open.weibo.com/cli/index使用手册https://open.weibo.com/cli/quickstartnpm 包https://www.npmjs.com/package/weibo-ai/weibo-cli