Agent Reach 小红书渠道配置指南：OpenCLI / xiaohongshu-mcp / xhs-cli 三后端路由与 Cookie-Editor 手工导出实战

2026-09-04 22:00:51作者：霍妲思

Agent Reach 的小红书（XiaoHongShu）渠道让 AI Agent 能读取和搜索小红书笔记。本篇基于仓库内置配置指南 agent_reach/guides/setup-xiaohongshu.md 展开：先讲清「桌面用 OpenCLI、服务器用 xiaohongshu-mcp、xhs-cli 仅存量备选」的三后端路由模型，再完整拆解 Cookie-Editor 手工导出的认证流程与 agent-reach configure xhs-cookies 命令的底层实现，最后给出 Doctor 体检方法和三个后端各自的可复制命令组。读完你可以独立完成小红书渠道的选型、认证、验证与日常排障。

三后端路由模型：为什么是 OpenCLI / xiaohongshu-mcp / xhs-cli

小红书渠道的能力定位是读取和搜索小红书笔记。Agent Reach 的设计是「首选 + 备选」的有序后端列表，而不是绑定某一个工具，选型逻辑在 agent_reach/channels/xiaohongshu.py 的模块注释里写得很明确：

后端	适用场景	认证方式	定位
OpenCLI	桌面（有 Chrome）	复用用户已有且明确控制的 Chrome 小红书会话	首选
xiaohongshu-mcp	服务器	Cookie-Editor 手工导出 Cookie 导入容器	服务器方案
xhs-cli（xiaohongshu-cli）	已安装用户	本地 cookies.json	存量备选（上游自 2026-03 起停更）

从源码看，后端顺序本身就是推荐顺序（agent_reach/channels/xiaohongshu.py）：

class XiaoHongShuChannel(Channel):
    name = "xiaohongshu"
    description = "小红书笔记"
    backends = ["OpenCLI", "xiaohongshu-mcp", "xhs-cli (xiaohongshu-cli)"]
    tier = 1

这个顺序同时实现了环境自动分流：OpenCLI 依赖桌面 Chrome，在服务器上天然探测不到、自动落选；xiaohongshu-mcp 是自带无头浏览器的容器化方案，在显式导入 Cookie 后接管；xhs-cli 作为最后一个候选，仅为存量安装保留。

该渠道还能识别 xiaohongshu.com 与 xhslink.com 域名的链接（can_handle 方法，agent_reach/channels/xiaohongshu.py），Agent 拿到笔记 URL 后可路由到正确渠道。

前置条件

OpenCLI 路径：用户浏览器中已经存在、且由用户明确控制的 Chrome 小红书会话（即你本人已在 Chrome 里登录过小红书）。
xiaohongshu-mcp / 存量工具路径：Cookie-Editor 浏览器扩展（Chrome 商店中的 Cookie 导出扩展），用于手工导出会话。

注意第一条的措辞："已经存在且明确控制"。Agent Reach 不会替你打开小红书执行登录，也不会去读取浏览器里的 Cookie，这一点在「认证边界」一节展开。

认证边界：不代登录、不读浏览器 Cookie

原指南的认证边界规则是小红书渠道的核心设计约束：

Agent Reach 不替用户执行小红书登录，也不读取浏览器 Cookie。 OpenCLI 只使用用户已经存在且明确控制的 Chrome 会话。 agent-reach configure xhs-cookies 不会把 Cookie 注入 OpenCLI 或 Chrome。

这条边界在源码中是硬性编码的，不只是文档承诺。agent_reach/cookie_extract.py 定义了各平台的浏览器 Cookie 自动提取规格，小红书被显式标记为只走手工导出：

{
    "name": "XiaoHongShu",
    "domains": (".xiaohongshu.com",),
    "cookies": None,  # manual Cookie-Editor export only
    "config_key": "xhs",
},

同时该文件维护了一个「仅允许 Cookie-Editor 手工导出」的平台清单（agent_reach/cookie_extract.py）：

_COOKIE_EDITOR_ONLY = {
    "twitter": "twitter-cookies",
    "xhs": "xhs-cookies",
}

如果你尝试用 agent-reach configure --from-browser chrome --platform xhs 这类自动提取路径，_require_browser_extractable 会直接抛出错误，提示改用 agent-reach configure xhs-cookies（agent_reach/cookie_extract.py）。也就是说，平台层面主动放弃了"偷偷读浏览器 Cookie"的能力，认证必须经用户显式动作完成。

同理，Doctor 体检小红书后端时也刻意规避了会触发浏览器读取的动作：xhs-cli 分支只检查显式保存的 Cookie 文件，不会执行上游的 xhs status（该命令会自动提取浏览器 Cookie），见 agent_reach/channels/xiaohongshu.py。

没有现成 Chrome 会话时：Cookie-Editor 手工导出流程

如果没有可复用的 Chrome 会话，不要自动登录；改用 Cookie-Editor 手工导出后配置 xiaohongshu-mcp 或存量工具。完整流程：

在 Chrome 中安装 Cookie-Editor 扩展；
用户自行在 xiaohongshu.com 准备要导出的会话；
点击 Cookie-Editor 图标 → Export → Header String；
把导出的字符串发给 Agent，运行：

agent-reach configure xhs-cookies
agent-reach doctor

该显式命令会保存/导入用户提供的 xiaohongshu.com 同域 Cookie 集；执行前请确认 Cookie 名称和范围。非 xiaohongshu.com 域的 Cookie 会被忽略。

如果 xiaohongshu-mcp 容器正在运行，配置命令会把 Cookie 导入容器；否则会写入 owner-only（仅所有者可读写）的本地文件，并打印后续手工导入路径。

`configure xhs-cookies` 底层行为：两种输入格式与三条落盘路径

结合 agent_reach/cli.py 中 _configure_xhs_cookies 的实现，可以看到原指南中"保存/导入"的完整语义：

接受两种输入格式（函数 docstring 明确列出）：

Cookie-Editor JSON 导出（cookie 对象数组）：逐条校验，仅保留 domain 匹配 xiaohongshu.com 的 Cookie，并打印被忽略的数量（非同域 Cookie 数、格式无效数）；没有任何有效 Cookie 时直接失败返回。
Header String（name1=value1; name2=value2; ...）：按分号拆分为 cookie 对象，自动补全 domain: ".xiaohongshu.com"、path: "/"、session: true、sameSite: "Lax" 等字段。

三条落盘路径：

Docker 可用且容器在跑：通过 docker exec ... printenv COOKIES_PATH 读取容器内 Cookie 路径（缺省回退 /app/cookies.json），用临时文件 docker cp 写入容器，然后 重启容器使其从磁盘重新加载，最后若检测到 mcporter 会执行 mcporter call xiaohongshu.check_login_status() 验证登录态——输出包含"已登录"或"logged"即验证通过。
Docker 可用但容器未运行：提示先启动容器并给出启动命令。
未安装 Docker：Cookie 以 owner-only 权限写入 ~/.agent-reach/xhs-cookies.json（通过 atomic_write_private_text 原子落盘），并打印手工导入命令：

docker cp ~/.agent-reach/xhs-cookies.json xiaohongshu-mcp:/app/data/cookies.json

这也解释了指南中"owner-only 的本地文件"的出处：凭据只留在本机 ~/.agent-reach/ 下，文件权限仅所有者可读写，不上传不外传。

使用示例：先看 `active_backend`，再选命令组

原指南的关键操作纪律是：先按 agent-reach doctor --json 的 active_backend 选择命令。原因是小红书有三条后端路线，命令组各不相同，跑错后端会白忙。

Doctor 是如何判定当前后端的

agent-reach doctor 会对候选后端按序真实探测（不只是看命令是否存在），XiaoHongShuChannel.check() 收集每个候选的 (backend, status, message)，优先报告第一个 ok，其次第一个可修复的 warn，避免一次抛给用户三条半相关的处方（agent_reach/channels/xiaohongshu.py）。各候选的探测逻辑：

OpenCLI（_check_opencli，agent_reach/channels/xiaohongshu.py）：检查 OpenCLI 是否安装、桥接是否连接。注意即使桥接已连接，由于 Doctor 不执行平台命令、无法实时验证小红书登录态，也只会标记为 warn 而非 ok——这是一种刻意的保守。
xiaohongshu-mcp（_check_mcp，agent_reach/channels/xiaohongshu.py）：先探测 http://localhost:18060/mcp 是否可达（agent_reach/channels/xiaohongshu.py，探测时显式绕过 HTTP 代理，因为 localhost 绝不能被路由到 HTTP_PROXY；任何 HTTP 响应都算"服务活着"）；再检查 mcporter 是否安装；最后检查 mcporter 配置中是否已接入名为 xiaohongshu 的服务，未接入时给出处方 mcporter config add xiaohongshu http://localhost:18060/mcp --scope home。
xhs-cli（_check_xhs_cli，agent_reach/channels/xiaohongshu.py）：检查 xhs 命令是否存在，然后安全读取 ~/.xiaohongshu-cli/cookies.json（限制 1MB 以内、不跟随符号链接，见模块常量 _MAX_XHS_COOKIE_BYTES）。文件需包含 a1 字段；若 saved_at 距今超过 7 天（_XHS_COOKIE_TTL_SECONDS = 7 * 86400）则提示 Cookie 已过期，需用 Cookie-Editor 明确更新。

如果没有任何后端可用，Doctor 会给出完整推荐路径（agent_reach/channels/xiaohongshu.py）：桌面装 OpenCLI 复用 Chrome 登录态，服务器走 xiaohongshu-mcp + Cookie-Editor 导出。

后端 A：OpenCLI（桌面，首选）

要求 Chrome 打开且装了 OpenCLI 扩展。命令组（来自 agent_reach/skill/references/social.md）：

# 搜索笔记
opencli xiaohongshu search "query" -f yaml

# 读笔记正文+互动数据（用搜索结果里的完整 URL，含 xsec_token）
opencli xiaohongshu note "NOTE_URL" -f yaml

# 评论（支持楼中楼）
opencli xiaohongshu comments NOTE_ID -f yaml

# 首页推荐 feed
opencli xiaohongshu feed -f yaml

# 用户主页公开笔记
opencli xiaohongshu user USER_ID -f yaml

后端 B：xiaohongshu-mcp（服务器场景）

认证前先用 Cookie-Editor 手工导出并显式导入，然后全部经 mcporter 调用（agent_reach/skill/references/social.md）：

# 认证前先让用户用 Cookie-Editor 手工导出，再显式导入
agent-reach configure xhs-cookies

# 只读检查当前状态
mcporter call xiaohongshu.check_login_status --timeout 120000

# 搜索
mcporter call xiaohongshu.search_feeds keyword="query" --timeout 120000

# 笔记详情+评论（feed_id 和 xsec_token 从搜索结果取）
mcporter call xiaohongshu.get_feed_detail feed_id="..." xsec_token="..." --timeout 120000

首次调用会自动下载约 150MB 无头浏览器，务必带 --timeout 120000。

后端 C：xhs-cli（存量备选）

原指南给出的存量示例命令：

# 搜索笔记
xhs search "关键词"

# 阅读笔记详情
xhs read NOTE_ID

# 查看评论
xhs comments NOTE_ID

扩展命令组还包括 xhs hot（热门）与 xhs feed（推荐）（agent_reach/skill/references/social.md）。已知限制：xhs user / xhs user-posts / xhs favorites 可能返回 API error（上游停更无人修），新装用户建议直接走后端 A/B。

服务器方案：Docker MCP

如果你已经在使用 xiaohongshu-mcp 项目的 Docker 方案，它也能正常工作（该方案为独立开源项目，容器镜像为 xpzouying/xiaohongshu-mcp）：

docker run -d \
  --name xiaohongshu-mcp \
  -p 18060:18060 \
  xpzouying/xiaohongshu-mcp

mcporter config add xiaohongshu http://localhost:18060/mcp --scope home

该服务器后端使用前面的 Cookie-Editor 手工导出流程：启动容器后运行 agent-reach configure xhs-cookies，配置命令会把 Cookie 直接 docker cp 进容器、重启容器并验证登录态（实现细节见前文「configure xhs-cookies 底层行为」一节）。两条命令与源码探测逻辑一一对应：docker run 让 Doctor 的 _mcp_service_reachable 能探测到 18060 端口，mcporter config add 让 inspect_mcporter_config 能在本地配置中发现名为 xiaohongshu 的服务——缺任何一条，Doctor 都会给出对应的 warn 处方。

常见问题

Q: Cookie 过期了？ A: 重新通过 Cookie-Editor 手工导出，再运行 agent-reach configure xhs-cookies，并粘贴到隐藏输入提示。对应地，Doctor 对 xhs-cli 侧的判定阈值是显式保存的 Cookie 超过 7 天即提示过期（agent_reach/channels/xiaohongshu.py），与这个处理节奏一致。

Q: 小红书提示 IP 风险？ A: 推荐使用住宅代理：

export HTTP_PROXY="http://user:pass@ip:port"

注意一个源码细节：Doctor 探测 xiaohongshu-mcp 的 localhost:18060 时会显式绕过代理（agent_reach/channels/xiaohongshu.py），所以即使设置了 HTTP_PROXY，本机体检也不会被代理干扰；代理只影响 Agent 实际调用小红书接口的链路。本地电脑不需要代理，代理只在部署于服务器（数据中心 IP）时需要考虑。

Q: xhs-cli 不支持我的系统？ A: 确保 Python 3.10+ 和 pipx 已安装。运行 pipx install xiaohongshu-cli 即可。

实战注意事项与延伸阅读

xsec_token 限制：小红书强制 xsec_token 机制，不能直接用裸 note_id 去读。正确流程：先搜索/feed 拿结果，再用结果中的完整 URL/ID 去读，三个后端都一样（agent_reach/skill/references/social.md）。
频率控制：高频请求（批量搜索、深翻评论）会触发验证码，平台限制无法绕过，建议每次操作间隔 2-3 秒。
写操作：建议只读。xhs-cli v0.6.x 的写操作（发帖/评论/点赞）可能因签名问题返回 406。
账号安全：使用 Cookie 登录的平台存在被平台检测并封号的风险，README 明确建议使用专用小号，不要用主账号（见 README.md 安全性一节）。
结果清洗：Agent Reach 内置了 format_xhs_result 结果格式化函数，从原始 API 响应中只保留标题、正文、作者、点赞/收藏/评论/分享数、图片 URL、标签等有用字段（agent_reach/channels/xiaohongshu.py），可大幅降低喂给模型的 token 消耗；其行为有专门测试覆盖，见 tests/test_xhs_format.py。
Agent 侧入口：Agent 读取 agent_reach/skill/SKILL.md 后按"动手前先体检"的纪律运行 agent-reach doctor，再根据 active_backend 选择上述命令组；多后端/登录态平台的这一流程在 SKILL.md 中被列为通用工作纪律。

小结

小红书渠道的配置主线可以压缩成四步：

选型：桌面有 Chrome 会话 → OpenCLI；服务器 → xiaohongshu-mcp（Docker）；已装 xhs-cli → 存量沿用；
认证：只走 Cookie-Editor 手工导出 + agent-reach configure xhs-cookies，Agent Reach 不代登录、不读浏览器 Cookie；
验证：agent-reach doctor / doctor --json 看 xiaohongshu 的状态与 active_backend；
使用：按当前 active_backend 选择对应的 opencli xiaohongshu ...、mcporter call xiaohongshu.* 或 xhs ... 命令组。