xiaohongshu-cli

xiaohongshu-cli — 小红书 CLI 工具

二进制文件： xhs 凭据： 浏览器 Cookie（自动提取）或通过浏览器辅助的二维码登录（--qrcode）

设置

# Install (requires Python 3.10+)
uv tool install xiaohongshu-cli
# Or: pipx install xiaohongshu-cli

# Upgrade to latest (recommended to avoid API errors)
uv tool upgrade xiaohongshu-cli
# Or: pipx upgrade xiaohongshu-cli

身份验证

Agent 请注意：执行任何 xhs 命令前，请先检查是否存在凭据。切勿假设 Cookie 已配置。

步骤 0：检查是否已通过身份验证

xhs status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"

如果为 AUTH_OK，跳转至命令参考。 如果为 AUTH_NEEDED，请继续步骤 1。如果无法提取浏览器 Cookie，但可以启动浏览器，优先使用 --qrcode。

步骤 1：引导用户完成身份验证

确保用户已在 browser_cookie3 支持的任意浏览器中登录 xiaohongshu.com。支持的浏览器：Chrome、Arc、Edge、Firefox、Safari、Brave、Chromium、Opera、Opera GX、Vivaldi、LibreWolf、Lynx、w3m。然后：

xhs login                              # auto-detect browser with valid cookies
xhs login --cookie-source arc          # specify browser explicitly
xhs login --qrcode                     # browser-assisted QR login with terminal QR output

使用以下命令验证：

xhs status
xhs whoami

步骤 2：处理常见身份验证问题

症状	Agent 操作
NoCookieError: No 'a1' cookie found	引导用户在浏览器中登录 xiaohongshu.com
NeedVerifyError: Captcha required	请用户打开浏览器，完成验证码，然后重试
IpBlockedError: IP blocked	建议切换网络（热点/VPN）
SessionExpiredError	运行 xhs login 刷新 Cookie

Agent 默认设置

所有机器可读输出都采用 SCHEMA.md 中记录的封装格式。 数据载荷位于 .data 下。

• 非 TTY 标准输出 → 自动使用 YAML
• --json / --yaml → 指定格式
• OUTPUT=json 环境变量 → 全局覆盖
• OUTPUT=rich 环境变量 → 强制使用面向用户的输出

命令参考

阅读

命令	描述	示例
xhs search <keyword>	搜索笔记	xhs search "美食" --sort popular --type video
xhs read <id_or_url_or_index>	通过 ID、URL 或短索引读取笔记	xhs read 1 / xhs read "https://...?xsec_token=xxx"
xhs comments <id_or_url_or_index>	通过 ID、URL 或短索引获取评论	xhs comments 1 / xhs comments "https://...?xsec_token=..."
xhs comments <id_or_url> --all	获取所有评论（自动翻页）	xhs comments "<url>" --all --json
xhs sub-comments <note_id> <comment_id>	获取评论的回复	xhs sub-comments abc 123
xhs user <user_id>	查看用户个人资料	xhs user 5f2e123
xhs user-posts <user_id>	列出用户的笔记	xhs user-posts 5f2e123 --cursor ""
xhs feed	浏览推荐信息流	xhs feed --yaml
xhs hot	浏览热门笔记	xhs hot -c food
xhs topics <keyword>	搜索话题/标签	xhs topics "旅行"
xhs search-user <keyword>	搜索用户	xhs search-user "摄影"
xhs my-notes	列出自己发布的笔记	xhs my-notes --page 0
xhs notifications	查看通知	xhs notifications --type likes
xhs unread	显示未读数量	xhs unread --json

互动（写入）

命令	描述	示例
xhs like <id_or_url_or_index>	点赞笔记	xhs like 1 / xhs like abc123
xhs like <id_or_url_or_index> --undo	取消点赞	xhs like 1 --undo
xhs favorite <id_or_url_or_index>	收藏笔记	xhs favorite 1
xhs unfavorite <id_or_url_or_index>	取消收藏	xhs unfavorite 1
xhs comment <id_or_url_or_index> -c "text"	发布评论	xhs comment 1 -c "好看！"
xhs reply <id_or_url_or_index> --comment-id ID -c "text"	回复评论	xhs reply 1 --comment-id 456 -c "谢谢"
xhs delete-comment <note_id> <comment_id>	删除自己的评论	xhs delete-comment abc 123 -y

社交

命令	描述	示例
xhs follow <user_id>	关注用户	xhs follow 5f2e123
xhs unfollow <user_id>	取消关注用户	xhs unfollow 5f2e123
xhs favorites [user_id]	列出已收藏的笔记（默认显示自己的）	xhs favorites --json

创作者

命令	描述	示例
xhs post --title "..." --body "..." --images img.png	发布笔记	xhs post --title "Test" --body "Hello"
xhs delete <id_or_url>	删除自己的笔记	xhs delete abc123 -y

账户

命令	描述
xhs login	从浏览器提取 Cookie（自动检测）
xhs login --qrcode	浏览器辅助二维码登录——在终端输出二维码，由浏览器完成登录
xhs status	检查身份验证状态
xhs logout	清除缓存的 Cookie
xhs whoami	显示当前用户资料

Agent 工作流示例

搜索 → 阅读 → 点赞流程

NOTE_ID=$(xhs search "美食推荐" --json | jq -r '.data.items[0].id')
xhs read "$NOTE_ID" --json | jq '.data'
xhs like "$NOTE_ID"

浏览热门美食笔记

xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'

获取用户信息后关注

xhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'
xhs follow 5f2e123

查看通知

xhs unread --json | jq '.data'
xhs notifications --type mentions --json | jq '.data.message_list[:5]'

分析笔记的所有评论

# Fetch ALL comments and analyze themes
xhs comments "$NOTE_URL" --all --json | jq '.data.comments | length'
# Count questions
xhs comments "$NOTE_URL" --all --json | jq '[.data.comments[] | select(.content | test("[\uff1f?]"))] | length'

每日阅读工作流

# Browse recommendation feed
xhs feed --yaml

# Interactive short-index workflow
xhs search "旅行"
xhs read 1
xhs comments 1
xhs like 1
xhs favorite 1
xhs comment 1 -c "收藏了"

# Browse trending by category
xhs hot -c food --yaml
xhs hot -c travel --yaml

二维码登录

# When browser cookie extraction is not available
xhs login --qrcode
# → Launches a browser-assisted login flow
# → Renders QR in terminal using Unicode half-blocks
# → Scan with Xiaohongshu app → confirm → export cookies

从 URL 到洞察的流程

# User pastes a URL → read + all comments
xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --json
xhs comments "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --all --json

热门分类

可用于 xhs hot -c <category>： fashion、food、cosmetics、movie、career、love、home、gaming、travel、fitness

错误代码

在 error.code 字段中返回的结构化错误代码：

• not_authenticated — Cookie 已过期或缺失
• verification_required — 需要验证码／身份验证
• ip_blocked — IP 请求频率受限
• signature_error — 请求签名失败
• api_error — 上游 API 错误
• unsupported_operation — 不支持此操作

限制

• 不支持下载视频 — 无法下载笔记图片／视频
• 不支持私信 — 无法访问私信
• 不支持直播 — 不支持直播功能
• 不提供关注／粉丝列表 — XHS Web API 未公开这些端点
• 仅支持单个账户 — 一次只能使用一组 Cookie
• 请求频率受限 — 请求之间内置高斯抖动延迟（约 1–1.5 秒）；频繁操作可能触发验证码或 IP 封禁

Agent 防检测注意事项

• 请勿并行发送请求 — 内置的请求频率限制延迟是为了保障账户安全
• 验证码恢复：如果出现 NeedVerifyError，客户端会自动进入冷却期并逐步延长等待时间（5 秒→10 秒→20 秒→30 秒）。请先让用户在浏览器中完成验证码，再重试
• 批量操作：执行批量任务（例如阅读大量笔记）时，请在 CLI 调用之间添加 time.sleep()
• 会话稳定性：同一会话中的所有请求共用一致的浏览器指纹。重启 CLI 会创建新的指纹会话

安全注意事项

• 请勿要求用户在聊天记录中分享原始 Cookie 值。
• 优先使用本地浏览器 Cookie 提取，而不是手动复制／粘贴机密信息。
• 如果身份验证失败，请让用户通过 xhs login 重新登录。
• Agent 应将 Cookie 值视为机密信息（避免不必要地回显到标准输出）。
• 内置的请求频率限制延迟有助于保护账户；请勿绕过。