环境：Node.js 18+ · macOS / Linux / Windows
npm 包：@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.sh
cat install.sh # 检查内容
bash install.sh
确认版本：
0.8.3
二、前置条件与鉴权
2.1 开放平台配置
在 open.weibo.com 按顺序完成三步，缺少任何一步都会在 weibo-cli doctor 输出 ×：
步骤 位置 说明
1 基本信息 → 开发者认证 实名认证，未通过无法创建授权
2 套餐订阅 选择方案获取调用额度，有免费档
3 设备授权 绑定本机后执行登录命令
2.2 登录
有桌面环境
weibo-cli auth login
无头环境（SSH / Docker / CI）
weibo-cli auth login --device
–device 会输出一个 URL 和验证码，在任意浏览器中打开完成授权即可，适合服务器场景。
2.3 状态检查
weibo-cli doctor
✓ 登录账号: yourname
✓ 完成开发者认证
✓ 开通套餐: Ultra
weibo-cli me --output table
显示账号、余额、套餐有效期、额度使用情况
2.4 套餐与额度
方案 额度 价格
Free 5 次/小时，仅本人数据 免费
Basic 3,000 Credits/月 ¥29
Plus 7,500 Credits/月 ¥69
Pro 32,000 Credits/月 ¥299
Ultra 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 ❌ 10～50，默认 10
返回结构中关键字段：
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, json
for item in json.load(sys.stdin)[‘data’]:
print(f"{item[‘id’]:>2}. {item[‘word’]} {item[‘num’]}")
"
4.3 获取用户微博时间线
查他人微博，需要 UID
weibo-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, json
users = 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/bash
monitor_topic.sh
KEYWORD=“AI工具”
THRESHOLD=50000
FEISHU_WEBHOOK=“https://your-webhook-url”
HEAT=(weibo−clisearchhotword/biz−−outputjson∣python3−c"importsys,jsondata=json.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−clisearchhotword/biz−−outputjson∣python3−c"importsys,jsondata=json.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"−gt"HEAT" -gt "HEAT"−gt"THRESHOLD” ]; then
curl -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/bash
fetch_timeline.sh
SCREEN_NAME=“目标账号昵称”
通过昵称查 UID
UID=(weibo−cliusersshowbatch/other −−screenname"(weibo-cli users show_batch/other \ --screen_name "(weibo−cliusersshowbatch/other−−screenname"SCREEN_NAME"
–output json | python3 -c "
import sys, json
users = json.load(sys.stdin)[‘users’]
print(users[0][‘id’]) if users else exit(1)
")
if [ -z “$UID” ]; then
echo “未找到用户:SCREENNAME"exit1fi拉取最近50条微博weibo−clistatusesusertimeline/other −−uid"SCREEN_NAME" exit 1 fi 拉取最近 50 条微博 weibo-cli statuses user_timeline/other \ --uid "SCREENNAME"exit1fi拉取最近50条微博weibo−clistatusesusertimeline/other−−uid"UID”
–count 50
–output json > "timeline_UID.json"COUNT={UID}.json" COUNT=UID.json"COUNT=(python3 -c "
import json
print(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.json
Step 2：筛选咨询类评论（python3，Windows/macOS/Linux 均可用）
python3 -c "
import json, re
comments = 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_ascii=False, indent=2)
"
Step 3：确认 inquiry.json 内容后执行批量回复
python3 -c "
import json, subprocess
for 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，不支持 csv
Windows 环境：weibo-cli 命令在 Git Bash 下存在路径解析问题，建议用 PowerShell 或直接调用 node 执行
参考
官方文档：https://open.weibo.com/cli/index
使用手册：https://open.weibo.com/cli/quickstart
npm 包：https://www.npmjs.com/package/@weibo-ai/weibo-cli
