1. 项目概述一个为小红书平台设计的命令行自动化工具如果你是一个经常需要在小红书上进行内容发布、数据分析或互动运营的创作者、营销人员或开发者那么手动重复操作、在不同界面间切换、以及处理大量数据可能会让你感到效率低下。今天要聊的这个工具redbook-cli正是为了解决这些痛点而生。它是一个纯粹的命令行界面工具让你能像操作本地文件系统一样通过输入简单的命令来完成对小红书的搜索、发布、互动和分析等一系列操作。简单来说redbook-cli是一个用 Python 编写的CLI工具它通过两种底层技术引擎与小红书的后台进行交互一种是基于 Go 语言编译的MCP服务器负责处理发布、搜索等核心高频操作另一种是基于CDP的浏览器自动化脚本用于实现数据分析、消息通知等需要完整浏览器环境的功能。这种双引擎架构的设计既保证了常用操作的执行速度又确保了功能覆盖的全面性。这个工具特别适合以下几类人一是技术背景的社交媒体运营者希望通过脚本自动化日常工作流二是数据驱动的内容创作者需要定期导出自己的账号数据进行分析三是开发者或研究者希望以程序化方式研究小红书平台的内容生态。它把复杂的网页交互封装成了简洁的命令让你可以轻松地将小红书操作集成到自己的自动化脚本、定时任务甚至是更复杂的AI Agent应用中。1.1 核心需求与设计哲学为什么需要这样一个命令行工具在社交媒体运营中效率和信息处理能力是关键。图形化界面虽然直观但在批量操作、数据导出和流程自动化方面存在天然短板。redbook-cli的设计哲学是“自动化一切可自动化的”将用户从重复的点击和等待中解放出来。它的核心需求主要体现在三个方面效率提升、数据获取和流程集成。在效率层面一条命令就能完成搜索、筛选、导出或者定时发布内容这比手动操作快了几个数量级。在数据获取层面运营者最关心的创作者后台数据、互动数据可以通过命令直接导出为结构化的 CSV 或 JSON 文件方便进行进一步的数据分析。在流程集成层面CLI 工具可以无缝嵌入到 CI/CD 流水线、爬虫系统或自主运行的AI Agent中例如可以设计一个 Agent 自动监控热点话题然后用redbook-cli搜索相关内容并生成分析报告。这个工具与市面上一些基于图形化自动化的方案最大的不同在于其“非侵入性”和“可编程性”。它不依赖于模拟鼠标键盘操作而是尝试通过更底层的协议与平台通信理论上更稳定且不易被风控机制识别为异常行为。同时命令行的输出是结构化的文本极易被其他程序解析和处理这为构建复杂的社交媒体管理生态系统打下了基础。2. 环境准备与安装部署详解在开始使用redbook-cli之前我们需要准备好运行环境并完成安装。整个过程并不复杂但有一些细节和选择需要明确这关系到后续功能的完整性和使用的便利性。2.1 基础环境与依赖检查redbook-cli是一个 Python 包因此首要条件是安装 Python。项目要求 Python 版本不低于 3.10。我建议使用 Python 3.10 或 3.11 的稳定版本因为某些依赖库在新版本中可能还存在兼容性问题。你可以通过以下命令检查你的 Python 版本python3 --version # 或 python --version如果你的版本低于 3.10需要先升级 Python。在 macOS 上我推荐使用brew install python3.11在 Linux 上可以使用系统的包管理器如apt install python3.11在 Windows 上可以从官网下载安装包。另一个重要的基础依赖是pip它是 Python 的包管理工具通常随 Python 一起安装同样可以通过pip3 --version来确认。注意在 Linux 或 macOS 系统上如果遇到权限问题尽量不要使用sudo pip install。更好的做法是使用 Python 虚拟环境这可以避免污染系统级的 Python 包也便于管理不同项目的依赖。可以使用python3 -m venv venv创建虚拟环境然后用source venv/bin/activate激活。2.2 核心安装的两种方式安装redbook-cli主要有两种方式通过 PyPI 直接安装或者从源码克隆并安装。对于绝大多数用户我推荐第一种方式最为简单直接。方式一通过 PyPI 安装推荐打开你的终端输入以下命令即可完成核心 CLI 的安装pip install redbook-cli这条命令会从 Python 包索引下载redbook-cli及其所有必要的 Python 依赖如requests,click,rich等并自动安装。安装完成后系统里就会有一个名为xhs的可执行命令。你可以通过xhs --version来验证安装是否成功。方式二从源码安装如果你希望体验最新的开发版功能或者有意参与项目贡献可以从 GitHub 克隆源码进行安装。git clone https://github.com/Youhai020616/xiaohongshu.git cd xiaohongshu bash setup.sh从源码安装会执行项目自带的安装脚本setup.sh。这个脚本通常会做几件事1) 检查环境2) 以“可编辑”模式安装 Python 包 (pip install -e .)3) 根据你的系统平台尝试下载或编译 MCP 服务器二进制文件。源码安装的好处是你可以随时git pull更新到最新代码。2.3 可选组件API 服务器的安装redbook-cli的功能依赖于一个常驻后台的 MCP 服务器。对于 macOS ARM64 的用户安装程序会自动下载对应的预编译二进制文件。但对于其他平台用户或者当你需要启动独立的 REST API 服务器时就需要安装额外的组件。启动独立的 API 服务器可以让你通过 HTTP 接口来调用xhs的功能这对于将功能集成到 Web 应用或其他非 Python 环境中非常有用。安装 API 服务器依赖的命令如下pip install redbook-cli[api]这个[api]是一个“额外依赖”标识它会额外安装fastapi,uvicorn等用于构建 Web 服务器的库。安装后你就可以使用xhs server start来启动一个本地 API 服务默认端口可能是 8000之后便可以通过发送 HTTP 请求来执行搜索、发布等操作。平台兼容性说明这是初期使用最容易踩坑的地方。项目文档中的平台支持表明确指出预编译的 MCP 服务器仅支持macOS ARM64架构。这意味着如果你使用的是 Intel 芯片的 Mac、Windows 或 Linux 系统在安装后运行某些命令时可能会因为找不到 MCP 服务器而回退到纯 CDP 模式。纯 CDP 模式完全依赖浏览器自动化功能虽然齐全但执行速度可能不如 MCP 模式快并且对浏览器环境有要求。工具在设计时考虑到了这一点xhs init初始化命令会自动检测你的系统如果找不到 MCP会提示你并切换到 CDP-only 模式不影响基本使用只是需要你有一个可用的 Chrome 或 Chromium 浏览器。3. 初始化配置与账号登录实战安装完成只是第一步要让redbook-cli真正能操作你的小红书账号必须完成初始化和登录。这个过程涉及到身份认证和运行模式选择是工具能否成功使用的关键。3.1 首次运行与引导式初始化第一次使用xhs命令时你应该首先运行初始化命令xhs init这个命令会启动一个交互式的引导流程。它会询问你一系列问题来创建配置文件通常位于~/.config/redbook-cli/config.toml。问题可能包括首选引擎它会检测你的系统如果支持 MCP会询问是否将其作为主要引擎。对于 macOS ARM64 用户强烈建议选择“是”以获得最佳性能。对于其他平台用户这里会直接提示使用 CDP 模式。Chrome 路径在 CDP 模式下需要指定 Chrome 或 Chromium 浏览器的可执行文件路径。工具会尝试自动查找如果找不到需要你手动输入。默认输出格式设置search等命令的默认输出格式是table终端表格、json还是csv。缓存设置是否启用缓存以及缓存过期时间。启用缓存可以极大提升重复搜索的速度。初始化完成后你的基本运行环境就配置好了。你可以随时使用xhs config show命令来查看完整的配置内容。3.2 核心登录机制解析与实操登录是获取操作权限的核心步骤。redbook-cli提供了两种登录方式对应其双引擎架构理解它们的区别很重要。方式一MCP QR 扫码登录首选速度快运行命令xhs login如果你的系统支持 MCP这条命令会启动 MCP 服务器如果还没运行并在终端打印出一个二维码同时可能自动打开一个二维码图片。此时你需要打开手机上的小红书 App使用“扫一扫”功能扫描这个二维码。扫码成功后终端会显示登录成功的提示。这种方式的原理是 MCP 服务器模拟了小红书 Web 端的二维码登录流程获取到登录态后保存在本地。这种登录方式获取的令牌通常有效期较长且操作效率高。方式二CDP 浏览器登录通用备选运行命令xhs login --cdp这条命令会启动一个受控的 Chrome 浏览器窗口并打开小红书的登录页面。你需要在这个浏览器窗口内手动输入账号密码或通过手机验证码完成登录。登录成功后浏览器会保持登录状态redbook-cli的 CDP 脚本通过开发者协议控制这个浏览器实例来执行后续操作。注意请务必在自动弹出的浏览器窗口中完成登录不要在你日常使用的浏览器中登录因为工具需要管理独立的浏览器会话。实操心得我强烈建议 macOS ARM64 用户优先使用xhs login。它的体验更接近“无头”操作不需要弹窗更适合在服务器或无图形界面的环境中使用。而--cdp方式虽然通用但依赖于图形界面并且每次启动可能都需要重新登录除非配置了浏览器用户数据持久化。登录成功后可以使用xhs status命令来检查当前的登录状态和活跃的引擎。3.3 多账号管理策略对于需要管理多个小红书账号的用户redbook-cli提供了多账号隔离支持。其原理是为每个账号创建独立的 Chrome 用户配置文件目录确保彼此的 Cookies 和本地存储完全隔离避免串号。添加新账号在已登录一个账号的情况下想登录第二个账号需要先切换到新的“上下文”。虽然 CLI 没有直接的add-account命令但你可以通过指定不同的配置目录或环境变量来实现。一种实践方法是在运行登录命令前设置一个不同的配置文件路径环境变量例如REDBOOK_CLI_CONFIG~/.config/redbook-cli/account2.toml xhs login。工具会读取这个新配置文件从而使用全新的浏览器环境登录第二个账号。查看与管理账号使用xhs account list命令可以列出当前已配置或已缓存登录态的账号。不过这个功能可能依赖于 MCP 服务器对多会话的支持。切换账号在执行具体操作命令时可以通过-t参数指定不同账号的token或者通过--profile参数指定不同的浏览器配置文件路径来切换操作对象。注意事项多账号操作是平台风控的重点关注对象。即使工具提供了隔离能力在实操中也要注意模拟真人行为避免在短时间内用多个账号执行大量相同操作如批量点赞、评论否则极易触发账号安全限制。建议为每个账号设置不同的操作时间间隔和使用模式。4. 核心功能深度解析与实战命令现在我们进入最核心的部分详细拆解redbook-cli的各项功能及其对应的命令。我会结合常见的使用场景解释每条命令的参数、输出以及背后的逻辑。4.1 内容搜索与信息获取搜索是内容分析和竞品调研的起点。xhs search命令功能强大远不止简单的关键词匹配。基础搜索与结果处理xhs search 露营装备这条命令会返回关于“露营装备”的笔记列表。默认情况下它以终端表格的形式输出包含笔记的序号、标题、作者、点赞数、收藏数等关键信息。这里有一个非常重要的概念短索引。输出表格最左边的序号就是短索引它是对本次搜索结果的临时本地编号。后续的read、like、comment等命令都可以直接使用这个短索引来操作对应的笔记无需记忆复杂的笔记 ID。高级筛选与排序小红书的搜索本身支持多种排序和内容类型筛选redbook-cli通过参数暴露了这些功能。xhs search 夏日穿搭 --sort 最多点赞 --type 图文--sort指定排序方式。可选值通常包括综合、最新、最多点赞、最多收藏等对应小红书网页版的排序下拉框。--type筛选内容类型。可选值如图文、视频可以帮你快速聚焦在特定形式的内容上。--time按时间筛选例如--time 今年内。数据导出为结构化文件这是数据分析的关键一步。搜索结果可以直接导出方便用 Excel、Python pandas 或数据库进行进一步处理。xhs search AI绘画 -o ai_notes.csv --format csv xhs search AI绘画 -o ai_notes.json --format json-o参数指定输出文件路径。--format指定格式默认为table终端打印可改为csv或json。CSV 文件可以用 Excel 直接打开分析JSON 文件则包含了更完整的分层信息适合程序解析。导出的字段通常比终端表格显示得更全可能包括笔记ID、详情链接、发布时间戳等。查看笔记详情获取列表后查看具体内容有两种方式xhs read 1使用短索引1来打开搜索列表中第一条笔记的详细信息。工具会获取并展示笔记的完整正文、所有图片/视频链接、以及更详细的互动数据。xhs detail 5e4c6b8f000000000101abcd -t your_auth_token直接通过笔记的唯一 ID 和授权令牌来获取详情。这种方式通常用于从其他渠道获取到笔记ID后的定点查询。4.2 内容发布与管理发布功能是自动化内容运营的核心。xhs publish命令支持图文和视频并提供了丰富的发布选项。发布图文笔记xhs publish -t 我的咖啡拉花入门心得 -c 经历了无数次失败终于能拉出像样的心形了...正文内容 -i latte_art1.jpg -i latte_art2.jpg --tags 咖啡 --tags 生活记录 --tags 新手入门-t或--title笔记标题。-c或--content笔记正文。正文中可以使用换行符\n来分段支持小红书的表情符号和话题标签如#咖啡日记。-i或--image指定图片路径可多次使用以上传多张图片。支持常见格式如 JPG、PNG。--tags添加话题标签可多次使用。发布视频笔记xhs publish -t 周末Vlog公园散步 -c 天气真好随手记录~ -v walk_in_park.mp4 --visibility 仅自己可见用-v参数替换-i来指定视频文件。视频发布处理时间可能较长因为涉及上传和转码。高级发布选项--visibility设置可见性。默认为公开可设置为仅自己可见或粉丝可见。这对于测试内容或发布专属福利非常有用。--schedule定时发布。例如--schedule 2023-10-01 09:30:00工具会在指定时间自动发布笔记。这需要 MCP 服务器在后台持续运行。--dry-run试运行。使用此参数时工具会执行所有发布前的准备工作如读取文件、生成请求但最终不会真正提交到平台用于检查内容和参数是否正确。实操心得与避坑指南图片/视频规格务必确保上传的媒体文件符合小红书的要求。图片建议分辨率清晰视频时长、大小、格式需在平台允许范围内。虽然CLI在上传前可能不做本地校验但平台服务器会拒绝不合规的文件导致发布失败。内容风控自动化发布需格外注意内容合规性。含有营销导流、二维码、联系方式或敏感信息的笔记即使通过CLI发布成功也可能被平台事后审核限流或删除。建议先少量测试。发布频率避免在极短时间内连续发布多条笔记这会被判定为 spam 行为。可以在脚本中为发布命令之间添加随机延时。--dry-run的重要性在编写自动化脚本时务必先使用--dry-run参数测试整个流程确认文件路径、参数解析无误后再移除该参数进行真实发布。4.3 互动操作点赞、收藏与评论互动是提升账号活跃度和权重的关键。redbook-cli让这些操作变得可编程。点赞与取消点赞xhs like 1为搜索列表中第一条笔记点赞。再次执行即为取消点赞如果已赞过。xhs like 5e4c6b8f000000000101abcd -t your_token --unlike通过指定笔记ID和令牌直接取消点赞。收藏xhs fav 2收藏搜索列表中第二条笔记。收藏操作通常没有直接的“取消收藏”短命令可能需要通过其他方式操作。评论与回复xhs comment 1 -c 教程很详细感谢分享对第一条笔记进行评论。xhs reply 1 --comment-id 1234567890 --user-id 987654321 -c 谢谢你的喜欢回复某条笔记下的特定评论。这里需要--comment-id被回复的评论ID和--user-id被回复的用户ID这两个ID需要从笔记的评论列表中获取。互动操作的注意事项频率限制平台对互动行为有严格的频率限制。自动化脚本必须加入足够的、随机的延迟例如每次操作间隔 30 秒到数分钟并模拟真人浏览如先read再like否则账号的互动功能可能被临时禁用。内容质量评论内容应避免千篇一律的“沙发”、“好文”尽量多样化、个性化否则会被系统识别为垃圾评论。短索引的时效性短索引是基于最近一次search命令的结果。如果你执行了新的搜索旧的短索引就会失效。对于需要长期跟踪的笔记建议使用笔记ID进行操作。4.4 数据分析与个人主页管理对于创作者和运营者数据驱动决策至关重要。redbook-cli提供了访问后台数据的能力。创作者数据分析xhs analytics这条命令会获取并展示你的创作者中心数据概览可能包括近期的笔记阅读量、互动数、粉丝增长等。这是通过 CDP 引擎模拟浏览器访问创作者后台页面并解析数据实现的。xhs analytics --csv dashboard_data.csv将数据导出为 CSV 文件方便进行趋势分析、图表制作。消息通知xhs notifications查看你的小红书消息通知包括收到的点赞、收藏、评论和提及。个人主页与粉丝列表xhs me查看当前登录账号的公开信息如昵称、简介、粉丝数、获赞与收藏数等。xhs profile 1234567890 -t your_token查看指定用户ID的个人主页信息。这可以用于竞品分析或粉丝研究。推荐流获取xhs feeds模拟打开小红书首页获取推荐流的内容列表。这对于研究平台推荐算法和内容热点有一定帮助。经验分享analytics和notifications功能高度依赖 CDP 引擎因为它们需要渲染完整的、动态加载的网页。执行这些命令时你会看到 Chrome 浏览器窗口的启动和操作过程。请确保网络环境稳定并且不要手动干扰自动弹出的浏览器窗口。如果命令执行时间过长或失败可能是页面结构发生了变化需要等待工具更新。5. 高级用法、架构解析与生态集成掌握了基本命令后我们可以深入看看redbook-cli的底层原理以及如何将它集成到更强大的自动化工作流中。5.1 双引擎架构深度剖析redbook-cli的性能和功能广度源于其独特的双引擎设计MCP 服务器和CDP 脚本。理解它们的分工和协作方式有助于你更好地使用和排错。MCP 服务器角色高性能核心引擎。它是一个用 Go 语言编写的独立守护进程通过 JSON-RPC 协议与xhsCLI 主程序通信。负责功能笔记发布、基础搜索、点赞、评论、用户信息查询等高频、对实时性要求高的操作。优势速度快、资源占用低、无需启动浏览器。它直接调用平台的非公开接口效率远高于模拟点击。限制目前仅提供 macOS ARM64 的预编译版本。其实现的功能受限于作者逆向工程的小红书接口范围。CDP 脚本角色功能补充引擎。它是一系列 Python 脚本通过 Chrome DevTools Protocol 控制一个真实的 Chrome/Chromium 浏览器。负责功能创作者后台数据分析、消息通知、复杂的搜索过滤需要渲染完整页面、以及所有 MCP 不支持的功能。优势功能全面。凡是能在浏览器里手动完成的操作理论上都能通过 CDP 实现。平台兼容性好。劣势速度慢、资源占用高需要运行浏览器、稳定性受网页前端变化影响大。协作流程当你执行xhs search命令时CLI 会优先尝试通过 MCP 服务器执行。如果 MCP 不可用如非 ARM64 Mac或者该功能 MCP 未实现则会自动回退到 CDP 脚本模式。这种设计在保证核心体验的同时最大限度地扩展了功能覆盖面。5.2 配置管理与自定义redbook-cli的行为可以通过配置文件和环境变量进行精细控制。查看与修改配置xhs config show显示当前所有配置项包括引擎选择、浏览器路径、缓存设置、API 端点等。xhs config set mcp.proxy http://127.0.0.1:7890设置 MCP 服务器连接的代理。这在某些网络环境下是必需的。xhs config set cdp.chrome_path /usr/bin/google-chrome-stable手动指定 Chrome 浏览器的路径。配置优先级命令行参数 环境变量 配置文件 默认值。例如你可以通过设置环境变量REDBOOK_CLI_ENGINEcdp来强制本次会话使用 CDP 引擎。缓存机制搜索等操作的结果会被缓存在本地默认过期时间可能是 5 分钟。这能避免重复请求提升速度。你可以通过xhs config set cache.ttl 600来调整缓存时长单位秒或者用xhs config set cache.enabled false完全关闭缓存。5.3 集成到自动化工作流与 AI Agentredbook-cli的真正威力在于其可编程性。你可以将它嵌入到 Shell 脚本、Python 程序或其他任何能执行命令行工具的环境中。场景一定时内容发布脚本创建一个 Bash 脚本publish_daily.sh#!/bin/bash # 切换到虚拟环境 source ~/venv/redbook/bin/activate # 发布预准备好的内容 xhs publish -t “每日灵感 $(date %F)” -c “今天也要加油\n#每日打卡” -i ~/pics/daily/$(date %Y%m%d).jpg --schedule “$(date %Y-%m-%d) 08:00:00” echo “[$date] 定时发布任务已提交。”然后使用crontab -e设置定时任务每天凌晨准备内容并提交发布计划。场景二竞品监控与数据分析使用 Python 脚本定期搜索关键词导出数据并分析import subprocess import json import pandas as pd from datetime import datetime # 1. 执行搜索并导出JSON keyword “露营” output_file f“search_{keyword}_{datetime.now().strftime‘%Y%m%d’}.json” subprocess.run[“xhs”, “search”, keyword, “-o”, output_file, “--format”, “json”] # 2. 加载并分析数据 with openoutput_file, ‘r’, encoding‘utf-8’ as f: data json.loadf df pd.DataFramedata[‘notes’] # 假设JSON结构中有‘notes’列表 top_liked df.nlargest5, ‘likes’ printf“今日‘{keyword}’话题点赞前五” printtop_liked[[‘title’, ‘author’, ‘likes’]]场景三作为 AI Agent 的工具结合像Claude Code、OpenClaw这类能理解并执行自然语言指令的 AI 代理框架你可以构建一个“社交媒体经理”Agent。你可以告诉 Agent“帮我搜索最近三天关于‘AI绘画’最火的五篇笔记总结它们的共同特点并用我的账号在最有价值的一篇下面发表一条有深度的评论。” Agent 可以自动规划并执行xhs search、xhs read、xhs comment等一系列命令完成复杂任务。5.4 故障排查与常见问题在使用过程中你可能会遇到一些问题。这里是一些常见问题的排查思路。问题一登录失败或登录后操作无权限可能原因登录态过期扫码登录未成功CDP 登录的浏览器会话丢失。解决方案运行xhs status检查登录状态。尝试重新登录xhs login或xhs login --cdp。对于 CDP 模式检查是否有多个 Chrome 实例冲突尝试关闭所有 Chrome 后重试。清理缓存和旧配置有时旧的配置文件会冲突可以尝试重命名~/.config/redbook-cli目录然后重新xhs init。问题二command not found: xhs可能原因Python 环境未激活pip install安装的路径不在系统的 PATH 环境变量中。解决方案确认你是在安装redbook-cli的 Python 环境中运行命令。尝试使用python3 -m redbook_cli代替xhs。检查pip show -f redbook-cli找到可执行文件路径并将其添加到 PATH。问题三MCP 服务器连接错误可能原因非 macOS ARM64 系统尝试使用 MCPMCP 服务器进程意外退出端口冲突。解决方案运行xhs init查看系统检测结果确认是否支持 MCP。尝试手动启动/停止服务器xhs server startxhs server stop 然后重试命令。检查是否有其他程序占用了 MCP 服务器默认的端口。问题四发布或上传失败可能原因网络问题文件格式或大小不符内容触发平台风控。解决方案首先使用--dry-run参数测试排除命令语法和文件路径问题。检查网络连接特别是上传所需的网络环境。确认图片/视频格式如 .jpg, .mp4和分辨率符合要求。简化发布内容如纯文字测试是否是内容问题。问题五CDP 模式浏览器无法启动可能原因未安装 Chrome/Chromium指定的浏览器路径错误浏览器版本与 CDP 驱动不兼容。解决方案确保系统已安装 Chrome 或 Chromium。运行xhs config show查看cdp.chrome_path配置确保路径正确。尝试更新 Chrome 到最新稳定版。当遇到问题时开启详细日志输出通常能提供更多线索。你可以尝试在命令前加上环境变量REDBOOK_CLI_LOG_LEVELdebug来运行例如REDBOOK_CLI_LOG_LEVELdebug xhs search “测试”这将在终端打印出详细的 HTTP 请求、响应和内部处理信息对于开发者定位问题非常有帮助。