百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
X

xiaohongshu-cli

> 编程语言
开源

Xiaohongshu (小红书) 的 CLI — 通过反向工程的 API 进行搜索、阅读和互动

2.4K stars0 点赞1 次浏览
访问官网GitHub

工具介绍

Xiaohongshu (小红书) 的 CLI — 通过反向工程的 API 进行搜索、阅读和互动

xiaohongshu-cli

A CLI for Xiaohongshu (小红书) — search, read, interact, and post via reverse-engineered API

English | 中文

More Tools

  • bilibili-cli — Bilibili CLI for videos, users, search, and feeds
  • twitter-cli — Twitter/X CLI for timelines, bookmarks, and posting
  • discord-cli — Discord CLI for local-first sync, search, and export
  • tg-cli — Telegram CLI for local-first sync, search, and export

Features

  • Auth — auto-extract browser cookies, QR code login, status check, whoami
  • Search — notes by keyword, user search, topic search
  • Reading — note detail, comments, sub-comments, user profiles
  • Short-index navigation — open recent list results with xhs read 1 or xhs comments 1
  • Feed — recommendation feed, hot/trending by category
  • Social — follow/unfollow, favorites
  • Interactions — like, favorite, comment, reply, delete
  • ✍️ Creator — post image notes, my-notes list, delete
  • Notifications — unread count, mentions, likes, new followers
  • ️ Anti-detection — consistent macOS Chrome fingerprint, sec-ch-ua alignment, session-stable browser identity, Gaussian jitter, captcha cooldown, exponential backoff
  • Structured output — commands support --yaml and --json; non-TTY stdout defaults to YAML
  • Stable envelope — see SCHEMA.md for ok/schema_version/data/error

AI Agent Tip: Prefer --yaml for structured output unless strict JSON is required. Non-TTY stdout defaults to YAML automatically.

Installation

bash
# Recommended: uv tool (fast, isolated)
uv tool install xiaohongshu-cli

# Or: pipx
pipx install xiaohongshu-cli

Upgrade to the latest version:

bash
uv tool upgrade xiaohongshu-cli
# Or: pipx upgrade xiaohongshu-cli

Tip: Upgrade regularly to avoid unexpected errors from outdated API handling.

From source:

bash
git clone [email protected]:jackwener/xiaohongshu-cli.git
cd xiaohongshu-cli
uv sync

Usage

…

Authentication

xiaohongshu-cli supports multiple authentication methods:

  1. Saved cookies — loads from ~/.xiaohongshu-cli/cookies.json
  2. Browser cookies — auto-detects installed browsers and extracts cookies (supports Chrome, Arc, Edge, Firefox, Safari, Brave, Chromium, Opera, Vivaldi, and more)
  3. QR code login — browser-assisted login with terminal QR output (xhs login --qrcode)

xhs login automatically tries all installed browsers and uses the first one with valid cookies. Use --cookie-source <browser> to specify a browser explicitly, or --qrcode for browser-assisted QR login. Other authenticated commands automatically retry once with fresh browser cookies when the saved session has expired.

Cookie TTL

Saved cookies are valid for 7 days by default. After that, the client automatically attempts to refresh from the browser. If browser extraction fails, the existing cookies are used with a warning.

Short-Index Navigation

After any listing command such as search, feed, hot, user-posts, favorites, or my-notes, the CLI stores the latest ordered note list in ~/.xiaohongshu-cli/index_cache.json.

  • xhs read <N> opens the Nth note from the latest listing
  • xhs comments <N> opens comments for the Nth note from the latest listing
  • xhs like <N>, xhs favorite <N>, xhs unfavorite <N>, xhs comment <N>, and xhs reply <N> reuse the same short index
  • Empty listings clear the index cache, so old results are not reused by accident

Environment Variables

Variable Default Description
OUTPUT auto Output format: json, yaml, rich, or auto (→ YAML when non-TTY)

Rate Limiting & Anti-Detection

xiaohongshu-cli includes comprehensive anti-risk-control measures designed to minimize detection:

Request Timing

  • Gaussian jitter: Delays between requests use a truncated Gaussian distribution (not fixed intervals) to mimic natural browsing patterns
  • Random long pauses: ~5% of requests include an additional 2-5 second delay simulating reading behavior
  • Auto-retry: Exponential backoff on HTTP 429/5xx and network errors (up to 3 retries)

Browser Fingerprint Consistency

  • UA/Platform alignment: User-Agent, sec-ch-ua, sec-ch-ua-platform, and fingerprint fields are all consistent (macOS Chrome 145)
  • Session-stable identity: GPU, screen resolution, CPU cores, and other hardware fingerprint values are generated once per session and reused across all requests (real browsers don't change hardware mid-session)
  • macOS-native values: GPU vendors (Apple M1/M2/M3, Intel Iris), Retina screen resolutions, MacIntel platform — all matching a real macOS browser

Captcha Cooldown

  • Progressive backoff: On captcha trigger (HTTP 461/471), automatically sleeps 5→10→20→30 seconds with increasing delays
  • Adaptive rate limiting: Request delay is permanently doubled after a captcha event to reduce future risk

Signed Requests

  • All API calls use x-s / x-s-common / x-t signatures (reverse-engineered from web client)
  • x-b3-traceid and x-xray-traceid for distributed tracing consistency

Structured Output

All --json / --yaml output uses the shared envelope from SCHEMA.md:

yaml
ok: true
schema_version: "1"
data: { ... }

When stdout is not a TTY (e.g., piped or invoked by an AI agent), output defaults to YAML. Use OUTPUT=yaml|json|rich|auto to override.

Use as AI Agent Skill

xiaohongshu-cli ships with a SKILL.md that teaches AI agents how to use it.

Skills CLI (Recommended)

bash
npx skills add jackwener/xiaohongshu-cli
Flag Description
-g Install globally (user-level, shared across projects)
-a claude-code Target a specific agent
-y Non-interactive mode

Manual Install

bash
mkdir -p .agents/skills
git clone [email protected]:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli

OpenClaw / ClawHub (Deprecated)

⚠️ ClawHub install method is deprecated and no longer supported. Use Skills CLI or Manual Install above.

Project Structure

…

Development

bash
# Install dependencies
uv sync

# Run tests
uv run pytest tests/ -v

# Unit tests only (no network)
uv run pytest tests/ -v --ignore=tests/test_integration.py -m "not smoke"

# Smoke tests (need cookies)
uv run pytest tests/ -v -m smoke

# Integration tests (need cookies)
uv run pytest tests/test_integration.py -v

# Lint
uv run ruff check .

Troubleshooting

Q: NoCookieError: No 'a1' cookie found

  1. Open any browser and visit https://www.xiaohongshu.com/
  2. Log in with your account
  3. Run xhs login (auto-detects browser) or xhs login --cookie-source <browser>

Q: NeedVerifyError: Captcha required

XHS has triggered a captcha check. Open https://www.xiaohongshu.com/ in your browser, complete the captcha, then retry.

Q: IpBlockedError: IP blocked by XHS

Try a different network (e.g., mobile hotspot or VPN). XHS blocks IPs that make too many requests.

Q: SessionExpiredError: Session expired

Your cookies have expired. Run xhs login to refresh.

Q: Requests are slow

The built-in Gaussian jitter delay (~1-1.5s between requests) is intentional to mimic natural browsing and avoid triggering XHS's risk control. Aggressive request patterns may lead to captcha triggers or IP blocks.

推荐项目

  • bilibili-cli — Bilibili 视频、用户、搜索与动态 CLI
  • twitter-cli — Twitter/X 时间线、书签和发推 CLI
  • discord-cli — Discord 本地优先同步、检索与导出 CLI
  • tg-cli — Telegram 本地优先同步、检索与导出 CLI

功能特性

  • 认证 — 自动提取浏览器 Cookie，browser-assisted 二维码扫码登录，状态检查，用户信息
  • 搜索 — 按关键词搜索笔记、用户、话题
  • 阅读 — 笔记详情、评论、子评论、用户主页
  • 发现 — 推荐 Feed、按分类浏览热门
  • 社交 — 关注/取关、收藏夹
  • 互动 — 点赞、收藏、评论、回复、删除
  • ✍️ 创作者 — 发布图文笔记、我的笔记列表、删除
  • 通知 — 未读数、@、点赞、新关注
  • ️ 反风控 — macOS Chrome 指纹一致性、session 级浏览器身份持久化、高斯抖动延迟、验证码自动冷却、指数退避重试
  • 结构化输出 — --yaml / --json，非 TTY 默认输出 YAML
  • 稳定 envelope — 参见 SCHEMA.md

安装

bash
# 推荐：uv tool（快速、隔离环境）
uv tool install xiaohongshu-cli

# 或者：pipx
pipx install xiaohongshu-cli

升级到最新版本：

bash
uv tool upgrade xiaohongshu-cli
# 或：pipx upgrade xiaohongshu-cli

提示： 建议定期升级，避免因版本过旧导致的 API 调用异常。

从源码安装：

bash
git clone [email protected]:jackwener/xiaohongshu-cli.git
cd xiaohongshu-cli
uv sync

使用示例

…

认证策略

xiaohongshu-cli 支持多种认证方式：

  1. 已保存 Cookie — 从 ~/.xiaohongshu-cli/cookies.json 加载
  2. 浏览器 Cookie — 自动检测已安装浏览器并提取（支持 Chrome、Arc、Edge、Firefox、Safari、Brave、Chromium、Opera、Vivaldi 等）
  3. 二维码扫码登录 — browser-assisted 登录，终端显示二维码，用小红书 App 扫码（xhs login --qrcode）

Cookie 保存后有效期 7 天，超时后自动尝试从浏览器刷新。

xhs login 会自动尝试所有已安装浏览器，使用第一个有有效 Cookie 的浏览器。也可用 --cookie-source <browser> 指定浏览器，或 --qrcode 使用 browser-assisted 二维码登录。其他需认证命令在 session 过期时会自动重试一次。

常见问题

  • NoCookieError: No 'a1' cookie found — 请先在任意浏览器打开 https://www.xiaohongshu.com/ 并登录，然后执行 xhs login
  • NeedVerifyError — 触发了验证码，请到浏览器中完成验证后重试
  • IpBlockedError — IP 被限制，尝试切换网络（手机热点或 VPN）
  • SessionExpiredError — Cookie 过期，执行 xhs login 刷新
  • 请求较慢是正常的 — 内置高斯随机延迟（~1-1.5s）是为了模拟人类浏览行为，避免触发风控

作为 AI Agent Skill 使用

xiaohongshu-cli 自带 SKILL.md，让 AI Agent 能自动学习并使用本工具。

Skills CLI（推荐）

bash
npx skills add jackwener/xiaohongshu-cli
参数 说明
-g 全局安装（用户级别，跨项目共享）
-a claude-code 指定目标 Agent
-y 非交互模式

手动安装

bash
mkdir -p .agents/skills
git clone [email protected]:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli

OpenClaw / ClawHub（已过时）

⚠️ ClawHub 安装方式已过时，不再支持。请使用上方的 Skills CLI 或手动安装。

License

Apache-2.0

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues，或尚未同步最近议题。

> 标签

Python

暂无评论，来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集，为前端与全栈提供静态类型
P
Python
通用编程语言，广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言