redbook — 小红书命令行工具

小红书 CLI 工具：搜索笔记、阅读内容、分析博主、发布图文。使用浏览器 Cookie 认证，无需 API Key。

English | 中文

最快上手方式

把这段话发给你的 AI 助手（Claude Code、Cursor、Codex、Windsurf、OpenClaw 等）：

"帮我用 npm 安装 @lucasygu/redbook 这个小红书 CLI 工具，然后运行 redbook whoami 验证是否能正常连接。GitHub 地址：https://github.com/lucasygu/redbook"

OpenClaw 用户也可以直接：clawhub install redbook

AI 会自动完成安装、验证连接、处理可能的 Cookie 问题。你只需要确保已在 Chrome 中登录 xiaohongshu.com。

安装完成后，试试："帮我分析'AI编程'这个话题在小红书上的竞争格局" —— AI 会自动搜索关键词、分析互动数据、发现头部博主、给出内容建议。

安装

npm install -g @lucasygu/redbook
# 或通过 ClawHub（OpenClaw 生态）
clawhub install redbook

需要 Node.js >= 22。支持 macOS、Windows、Linux。使用 Chrome 浏览器的 Cookie —— 请先在 Chrome 中登录 xiaohongshu.com。

安装后运行 redbook whoami 验证连接。CLI 会自动检测所有 Chrome 配置文件，找到你的小红书登录状态。

• macOS —— 如果遇到钥匙串弹窗，请点击"始终允许"
• Windows —— Chrome 127+ 使用了 App-Bound Encryption，CLI 会自动启动 Chrome headless 模式读取 Cookie（需要先关闭 Chrome）。如果自动提取失败，可以用 --cookie-string 手动传入

能做什么

• 话题研究 —— 搜索关键词，分析哪些话题有流量、哪些是蓝海
• 竞品分析 —— 找到头部博主，对比粉丝量、互动数据、内容风格
• 爆款拆解 —— 分析爆款笔记的标题钩子、互动比例、评论主题
• 爆款模板 —— 从多篇爆款笔记提取内容模板（标题结构、正文结构、钩子模式）
• 限流检测 —— 检测笔记是否被隐形限流（通过创作者后台 API 的隐藏 level 字段）
• 收藏专辑 —— 查看收藏专辑内容，分析专辑内的笔记
• 收藏管理 —— 查看收藏列表、收藏/取消收藏笔记（支持自己和其他用户的公开收藏）
• 评论管理 —— 发评论、回复评论、按策略批量回复（问题优先 / 高赞优先 / 未回复优先）
• 图文卡片 —— Markdown 渲染为小红书风格的 PNG 图文卡片（7 种配色主题）
• 内容策划 —— 基于数据发现内容机会，生成有数据支撑的选题建议
• 受众洞察 —— 从互动信号推断目标用户画像

通过 AI 助手使用时，这些工作流可以自动串联完成。直接使用 CLI 时，每个命令也可以独立运行。

快速开始

# 检查连接
redbook whoami

# 搜索笔记
redbook search "AI编程" --sort popular

# 阅读笔记
redbook read https://www.xiaohongshu.com/explore/abc123

# 获取评论
redbook comments https://www.xiaohongshu.com/explore/abc123 --all

# 浏览推荐页
redbook feed

# 查看博主信息
redbook user <userId>
redbook user-posts <userId>

# 搜索话题标签
redbook topics "Claude Code"

# 查看收藏（默认当前用户）
redbook favorites --json
redbook favorites <userId> --json --all

# 收藏/取消收藏
redbook collect "<noteUrl>"
redbook uncollect "<noteUrl>"

# 分析爆款笔记
redbook analyze-viral https://www.xiaohongshu.com/explore/abc123

# 从多篇爆款提取内容模板
redbook viral-template "<url1>" "<url2>" "<url3>" --json

# 发评论
redbook comment "<noteUrl>" --content "写得好！"

# 回复评论
redbook reply "<noteUrl>" --comment-id "<id>" --content "感谢提问！"

# 按策略批量回复（先预览再执行）
redbook batch-reply "<noteUrl>" --strategy questions --dry-run
redbook batch-reply "<noteUrl>" --strategy questions --template "感谢！{content}" --max 10

# 查看收藏专辑
redbook boards                          # 列出自己的专辑
redbook boards <userId>                 # 列出他人的专辑
redbook board "https://www.xiaohongshu.com/board/abc123"
redbook board abc123 --json

# 检测笔记限流状态
redbook health
redbook health --all --json

# 将 Markdown 渲染为图文卡片（需要可选依赖）
redbook render content.md --style xiaohongshu
redbook render content.md --style dark --output-dir ./cards

# 发布图文笔记
redbook post --title "标题" --body "正文内容" --images cover.png
redbook post --title "测试" --body "..." --images img.png --private

命令一览

| 命令 | 说明 | |------|------| | whoami | 查看当前登录账号 | | search <关键词> | 搜索笔记 | | read <url> | 阅读单篇笔记 | | comments <url> | 获取笔记评论 | | user <userId> | 查看用户资料 | | user-posts <userId> | 列出用户所有笔记 | | feed | 获取推荐页内容 | | post | 发布图文笔记（易触发验证码，详见下方说明） | | topics <关键词> | 搜索话题/标签 | | favorites [userId] | 查看收藏笔记列表（默认当前用户） | | collect <url> | 收藏（书签）笔记 | | uncollect <url> | 取消收藏笔记 | | health | 检测笔记隐形限流（通过创作者后台隐藏 level 字段） | | boards [userId] | 列出用户的收藏专辑（默认当前用户） | | board <url> | 查看收藏专辑内容（接受专辑 URL 或 ID） | | analyze-viral <url> | 分析爆款笔记（钩子、互动、结构） | | viral-template <url...> | 从 1-3 篇爆款笔记提取内容模板 | | comment <url> | 发表评论 | | reply <url> | 回复指定评论 | | batch-reply <url> | 按策略批量回复评论（支持预览模式） | | render <文件> | Markdown 渲染为小红书图文卡片 PNG（需可选依赖） |

通用选项

| 选项 | 说明 | 默认值 | |------|------|--------| | --cookie-source <浏览器> | Cookie 来源浏览器（chrome, safari, firefox） | chrome | | --chrome-profile <名称> | Chrome 配置文件目录名（如 "Profile 1"），默认自动检测 | 自动 | | --cookie-string <cookies> | 手动传入 Cookie 字符串："a1=值; web_session=值"（从 Chrome DevTools 复制） | 无 | | --json | JSON 格式输出 | false |

搜索选项

| 选项 | 说明 | 默认值 | |------|------|--------| | --sort <类型> | general（综合）、popular（热门）、latest（最新） | general | | --type <类型> | all（全部）、video（视频）、image（图文） | all | | --page <页码> | 页码 | 1 |

分析选项（analyze-viral / viral-template）

| 选项 | 说明 | 默认值 | |------|------|--------| | --comment-pages <n> | 获取评论页数 | 3 |

批量回复选项（batch-reply）

| 选项 | 说明 | 默认值 | |------|------|--------| | --strategy <策略> | questions（提问）、top-engaged（高赞）、all-unanswered（未回复） | questions | | --template <模板> | 回复模板，支持 {author}, {content} 占位符 | 无（预览模式） | | --max <数量> | 最大回复数（上限 30） | 10 | | --delay <毫秒> | 回复间隔（最小 180000ms/3分钟），自动添加 ±30% 随机抖动 | 300000（5分钟） | | --dry-run | 只预览不发送 | 无模板时自动开启 |

⚠️ 风控安全： 小红书检测均匀时间间隔的自动化行为。回复间隔已自动添加 ±30% 随机抖动，避免触发机器人检测。建议每天每篇笔记最多批量回复 1-2 次。

渲染选项（render）

将 Markdown 文件渲染为小红书风格的 PNG 图文卡片。使用本机 Chrome 渲染，无需额外下载浏览器。

| 选项 | 说明 | 默认值 | |------|------|--------| | --style <名称> | 配色：purple, xiaohongshu, mint, sunset, ocean, elegant, dark | xiaohongshu | | --pagination <模式> | 分页：auto（自动拆分）、separator（按 --- 拆分） | auto | | --output-dir <目录> | 输出目录 | 与输入文件同目录 | | --width <像素> | 卡片宽度 | 1080 | | --height <像素> | 卡片高度 | 1440 | | --dpr <倍率> | 设备像素比 | 2 |

可选依赖： 需要安装 puppeteer-core 和 marked：

npm install -g puppeteer-core marked

发布选项（post）

发布功能目前容易触发验证码（type=124）。图片上传正常，但发布步骤经常被拦截。如需发布笔记，建议使用浏览器自动化。

| 选项 | 说明 | |------|------| | --title <标题> | 笔记标题（必填） | | --body <正文> | 笔记正文（必填） | | --images <路径...> | 图片文件路径（必填） | | --topic <关键词> | 附加话题标签 | | --private | 发布为私密笔记 |

常见问题

| 问题 | 解决方案 | |------|----------| | No 'a1' cookie found | 在 Chrome 中登录 xiaohongshu.com，然后重试 | | Windows 上 -101 错误 | Chrome 127+ 的 App-Bound Encryption 导致。先关闭 Chrome，再运行命令（CLI 会自动启动 Chrome headless 读取 Cookie）。如仍失败，用 --cookie-string 手动传入 | | Windows --cookie-string 用法 | Chrome 按 F12 → Application → Cookies → xiaohongshu.com，复制 a1 和 web_session 的值：redbook whoami --cookie-string "a1=值; web_session=值" | | macOS 钥匙串弹窗 | 输入密码后点击"始终允许"，CLI 需要读取 Chrome 的加密 Cookie | | 多个 Chrome 配置文件 | CLI 自动扫描所有配置文件（macOS / Windows / Linux）。如需指定：--chrome-profile "Profile 1" | | 使用 Brave/Arc 等浏览器 | 尝试 --cookie-source safari，或在 Chrome 中登录 |

工作原理

redbook 从 Chrome 读取小红书的登录 Cookie，然后用 TypeScript 实现的签名算法对 API 请求签名。

三层 Cookie 提取策略：

1. sweet-cookie（快速路径）—— 直接读取 Chrome 的 SQLite 数据库，macOS 上即开即用
2. CDP 回退（Windows 自动触发）—— 启动 Chrome headless，通过 DevTools Protocol 读取 Cookie，绕过 Chrome 127+ 的 App-Bound Encryption
3. --cookie-string（手动兜底）—— 从 Chrome DevTools 复制 Cookie 字符串，任何平台通用

两套签名系统：

• 主 API（edith.xiaohongshu.com）—— 读取：搜索、推荐页、笔记、评论、用户资料。使用 144 字节 x-s 签名（v4.3.1）
• 创作者 API（creator.xiaohongshu.com）—— 写入：上传图片、发布笔记。使用 AES-128-CBC 签名

分析模块（A-M）

内置 13 个可组合的分析模块，覆盖从关键词研究到内容发布的完整工作流：

| 模块 | 功能 | |------|------| | A. 关键词矩阵 | 分析各关键词的互动天花板和竞争密度 | | B. 跨话题热力图 | 发现话题 × 场景的内容空白 | | C. 互动信号分析 | 分类内容类型（工具型 / 认知型 / 娱乐型） | | D. 博主画像 | 对比头部博主的粉丝、互动、风格 | | E. 内容形式分析 | 图文 vs. 视频的表现对比 | | F. 机会评分 | 按性价比排序关键词 | | G. 受众推断 | 从互动信号推断用户画像 | | H. 选题策划 | 数据驱动的内容创意 | | I. 评论运营 | 按策略筛选和批量回复评论 | | J. 爆款复刻 | 从爆款笔记提取内容模板 | | K. 互动自动化 | 组合 I + J 的自动化运营工作流 | | L. 图文卡片 | Markdown → 小红书风格 PNG 图文卡片（7 种配色） | | M. 限流检测 | 通过创作者后台隐藏 level 字段检测笔记限流状态 |

详见 SKILL.md 的模块文档和组合工作流。

AI 助手集成

Claude Code

安装后自动注册为 Claude Code 技能。在 Claude Code 中使用 /redbook 命令：

/redbook search "AI编程"                        # 搜索笔记
/redbook read <url>                             # 阅读笔记
/redbook user <userId>                          # 查看博主
/redbook analyze-viral <url>                    # 分析爆款笔记

你可以直接用自然语言下达复杂任务：

• "分析'AI编程'在小红书的竞争格局，找出蓝海关键词"
• "对比这三个博主的内容策略和互动数据"
• "拆解这篇爆款笔记，告诉我为什么火了"
• "帮我回复这篇笔记下面的提问评论"

Claude 会自动组合多个命令，解析 JSON 数据，输出结构化分析报告。

OpenClaw / ClawHub

官方支持 OpenClaw 和 ClawHub 生态。通过 ClawHub 安装：

clawhub install redbook

安装后在 OpenClaw 中可直接使用所有 redbook 命令。SKILL.md 同时兼容 Claude Code 和 OpenClaw 两个生态。

编程接口

import { XhsClient } from "@lucasygu/redbook";
import { loadCookies } from "@lucasygu/redbook/cookies";

const cookies = await loadCookies("chrome");
const client = new XhsClient(cookies);

const results = await client.searchNotes("AI编程", 1, 20, "popular");
const topics = await client.searchTopics("Claude Code");

致谢

签名算法移植自以下开源项目（MIT 协议）：

• Cloxl/xhshow — 主 API 签名（x-s, x-s-common）
• Spider_XHS — 创作者 API 签名
• ReaJason/xhs — API 端点参考

Cookie 提取使用 @steipete/sweet-cookie。

限流检测灵感来自 jzOcb/xhs-note-health-checker（@xxx111god 发现了创作者后台 API 的隐藏 level 字段）。

免责声明

本工具使用非官方 API。小红书可能随时更改或封锁这些接口。请合理使用，风险自负。本项目与小红书无任何关联。

---

<a id="english"></a>

English

A fast CLI tool for Xiaohongshu (小红书 / RED) — search notes, read content, analyze creators, and publish posts. Uses browser cookie auth (no API key needed).

Easiest way to get started

Paste this to your AI coding agent (Claude Code, Cursor, Codex, Windsurf, OpenClaw, etc.):

"Install the @lucasygu/redbook Xiaohongshu CLI tool via npm and run redbook whoami to verify it works. Repo: https://github.com/lucasygu/redbook"

OpenClaw users can also run: clawhub install redbook

The agent will handle installation, verify the connection, and troubleshoot any cookie issues. Just make sure you're logged into xiaohongshu.com in Chrome first.

Once installed, try: "Analyze the competitive landscape for 'AI编程' on Xiaohongshu" — the agent will search keywords, analyze engagement data, profile top creators, and suggest content opportunities.

Install

npm install -g @lucasygu/redbo