Claw XHS

面向小红书的、以发布为优先的自动化运行时，基于“每个账号一套持久化 Chrome 状态”。

claw-xhs 是一个本地 daemon，加上一层 MCP-compatible tool surface，用来做可监督的小红书运营自动化。 它的设计前提不是 cookie-only 恢复，也不是 Docker-first 的浏览器运行方式，而是真实、持久化、隔离的浏览器态。

当前口径：

• 主通用示例已经改成 ~/.claw-xhs + Chrome auto-detect
• repo 里也提供了 macOS / Linux / Windows 的显式配置示例
• 当前文档和运维流程仍主要按 macOS 编排
• 但 v0.1 还不能把 Windows 当成正式支持平台来宣传

语言：

• English README

当前状态

目前已经明确并验证的能力：

• v0.1 首发边界已经定义
• 单账号运行时可用
• 私密发布已经 end-to-end 打通
• 公开发布默认进入 pending confirmation
• 最小读取能力可用：
  • login status
  • user profile
  • feed list
  • feed detail

默认 MCP 地址：

http://localhost:18060/mcp

如果你的目标是尽快让 OpenClaw 或 Claude Code 接进来，不用先读完整个 repo，直接看：

• Agent 安装与接入（中文）
• Agent Setup（English）

快速入口

• Agent 安装与接入（中文）
• Agent Setup（English）
• 平台与路径说明
• 快速开始
• 操作手册
• Agent 资产说明
• Agent Playbook（中文）
• Agent Short Prompt（中文）
• 首发边界
• 发版检查清单
• Release Notes 草稿
• License
• Docker 定位说明
• 下一步计划

选择你的接入方式

方案 A. 我已经在用 OpenClaw

最短路径：

1. 按 Agent 安装与接入（中文） 走一遍本地初始化
2. 启动 claw-xhsd
3. 安装 skill：

./scripts/install_skills.sh --preset openclaw

4. 在 OpenClaw 里把 MCP server 名设为 claw-xhs
5. MCP 地址指向：

http://localhost:18060/mcp

6. 第一条验证建议： 先检查登录，再发一条 仅自己可见 的测试内容

方案 B. 我在用 Claude Code / Codex-style MCP client

最短路径：

1. 按 Agent Setup（English） 或中文版完成本地初始化
2. 启动 claw-xhsd
3. 安装 skill：

./scripts/install_skills.sh --preset codex

4. 在客户端里注册名为 claw-xhs 的 MCP server
5. MCP 地址指向：

http://localhost:18060/mcp

6. 第一条验证建议： 先执行 login check，再跑一次 private test publish

方案 C. 我暂时不接 Agent，只想先验证运行时

最短路径：

1. 运行：

./bin/claw-xhs-login -config ~/.claw-xhs/config.json -account christina-main

2. 在独立 Chrome runtime 里手动登录一次
3. 启动：

./bin/claw-xhsd -config ~/.claw-xhs/config.json -account christina-main

4. 验证：

curl http://127.0.0.1:18060/health
curl http://127.0.0.1:18060/api/v1/login/status

5. 最稳的第一条真实动作是： 发一条 仅自己可见 的测试内容

它是什么

• 一个本地持久化的小红书运行时
• 一账号一套独立 Chrome runtime
• 一个可接 OpenClaw / 其他 MCP client 的发布优先工具面
• 一个默认支持人工监督公开发布的工作流

它不是什么

• 不是通用爬虫平台
• 不是 search-first 产品
• 不是全自动无人值守社交媒体机器人
• 不是以 Docker 为中心的浏览器运行环境

简单架构图

Agent
  -> MCP tool call
  -> claw-xhsd
  -> 独立 Chrome runtime
  -> 小红书 web / creator 页面

多账号隔离方式：

账号 A -> runtime A -> 端口 A
账号 B -> runtime B -> 端口 B

为什么要这么做

之前的调试已经说明了几件事：

• 单纯靠 cookies.json 不够稳
• 短生命周期浏览器很脆
• 真正可复用的是持久化浏览器状态
• “人工首次登录 + 公开发布时人工确认”是完全可接受的产品选择

所以这个 repo 的核心设计是：

• 持久化、隔离的 Chrome 状态
• 默认本机运行
• 本地 daemon + MCP surface

60 秒上手

1. 编译

mkdir -p bin
go build -o bin/claw-xhsd ./cmd/claw-xhsd
go build -o bin/claw-xhs-login ./cmd/claw-xhs-login
go build -o bin/claw-xhs-inspect ./cmd/claw-xhs-inspect
go build -o bin/claw-xhs-publish ./cmd/claw-xhs-publish

2. 创建配置文件

创建 ~/.claw-xhs/config.json：

{
  "version": "0.1",
  "state_dir": "~/.claw-xhs",
  "browser": {
    "binary_path": "",
    "headless": false,
    "remote_debugging_base_port": 9333
  },
  "service": {
    "default_bind_host": "127.0.0.1",
    "mcp_path": "/mcp",
    "health_path": "/health"
  },
  "logging": {
    "level": "info",
    "format": "text"
  },
  "accounts": [
    {
      "id": "christina-main",
      "enabled": true,
      "http_port": 18060,
      "remote_debugging_port": 9441
    }
  ]
}

说明：

• state_dir 可以直接写成 ~/.claw-xhs
• browser.binary_path 留空时会自动探测本机 Chrome / Chromium
• 如果自动探测失败，再手动填本机路径

3. 初始化并登录

./bin/claw-xhs-login -config ~/.claw-xhs/config.json -account christina-main

这一步会拉起一套独立 Chrome 窗口。
你在里面手动登录小红书一次即可。

4. 启动服务

./bin/claw-xhsd -config ~/.claw-xhs/config.json -account christina-main

5. 验证

curl http://127.0.0.1:18060/health
curl http://127.0.0.1:18060/api/v1/login/status

6. 让 MCP client 连接

http://localhost:18060/mcp

7. 如需安装 skill

./scripts/install_skills.sh --preset openclaw

或者：

./scripts/install_skills.sh --preset codex

如果两边都要装：

./scripts/install_skills.sh --preset all

发布是怎么工作的

私密测试发布

最安全的验证方式是直接发 仅自己可见 的测试内容。

公开发布

公开内容默认不会立刻真发。
当前流程是：

1. 创建 pending draft
2. 查看 pending draft
3. 显式确认，或者取消

这套流程同时暴露给：

• REST
• MCP

功能预览

1. 登录与登录检查

第一步必须先完成。

你可以：

• 用 claw-xhs-login 拉起独立 Chrome runtime
• 在里面手动登录一次小红书
• 再通过 REST 或 MCP 做 login/status

这是所有高价值动作前的第一道检查。

2. 私密测试发布

当前最稳的路径就是：

• 发一条 仅自己可见
• 验证发布链路是否真的 end-to-end 可用

这也是推荐的第一条 smoke test。

3. 公开内容待确认发布

公开可见 默认不会直接真发。

流程是：

1. publish_image_post
2. 返回 pending draft 和 confirmation_id
3. 由你显式确认
4. 再 confirm_publish

这也是 claw-xhs 和上游通用“直接发帖”思路最不一样的地方之一。

最小 MCP 示例

从 Agent 角度看，最安全的公开发布流程是：

1. 调用 publish_image_post
2. 收到一个 pending draft 和 confirmation_id
3. 如有需要，调用 list_pending_publishes 再看一遍
4. 再调用 confirm_publish 或 cancel_pending_publish

例如：

{
  "tool": "publish_image_post",
  "arguments": {
    "title": "Daily update",
    "content": "Draft for review before publishing.",
    "images": ["/absolute/path/to/image.png"],
    "visibility": "公开可见"
  }
}

预期返回形态：

{
  "status": "pending_confirmation",
  "confirmation_id": "pub_xxx",
  "visibility": "公开可见"
}

确认发布：

{
  "tool": "confirm_publish",
  "arguments": {
    "confirmation_id": "pub_xxx"
  }
}

v0.1 已支持的能力

命令行

• claw-xhs-login
• claw-xhs-inspect
• claw-xhs-publish
• claw-xhsd

REST

• /health
• /api/v1/login/status
• /api/v1/user/me
• /api/v1/feeds/list
• /api/v1/feeds/detail
• /api/v1/publish
• /api/v1/publish/pending
• /api/v1/publish/confirm
• /api/v1/publish/cancel

MCP tools

• get_login_status
• get_my_profile
• list_home_feeds
• get_feed_detail
• publish_image_post
• list_pending_publishes
• confirm_publish
• cancel_pending_publish

v0.1 明确不做的事

• 原生 search
• 删除笔记
• 评论 / 点赞 / 收藏
• 广义 scraping 承诺
• 无人值守公开发布
• Docker-first parity

准确边界见：

• docs/public-release-boundary-v0.1.md

当前已知限制

• feeds/list 比发布慢，也更不稳定
• user/me.desc 可能为空，因为当前来源不稳定
• search 是故意不暴露的，不是忘了做
• 目前还没有更丰富的 review UI，只有 API/MCP 的 pending-draft 流程
• MCP output schema 在递归 payload 上仍然偏保守

推荐运行模型

1. 本机安装普通 Google Chrome
2. 每个小红书账号对应一套独立 Chrome runtime
3. 首次由用户手动登录一次
4. 后续长期复用这套 runtime
5. 公开发布默认走人工监督

打包定位：

• 推荐运行方式：host-native persistent Chrome
• Docker：以后可选补充，不是当前主路径

文档导航

• META.md - 项目定位、约束和架构立场
• README.en.md - 英文版首页
• LICENSE - MIT license
• INDEX.md - 项目导航图
• CONTRIBUTING.md - 贡献与改动时的边界要求
• tracker.md - milestone 状态和下一步跟踪
• task_plan.md - 已完成内容和接下来的阶段
• progress.md - 时间顺序的建设日志
• docs/setup-local.md - 本机启动和接入方式
• docs/operator-guide.md - 日常运行、发布确认、常见故障
• docs/agent-assets.md - playbook、skill、short prompt 的关系和使用方式
• playbooks/agent-playbook.zh-CN.md - 面向 Agent 的中文长版工作说明
• playbooks/agent-prompt-short.zh-CN.md - 面向 Agent 的中文短版 prompt
• playbooks/agent-playbook.en.md - 面向 Agent 的英文长版工作说明
• playbooks/agent-prompt-short.en.md - 面向 Agent 的英文短版 prompt
• skills/claw-xhs-agent-zh-cn/SKILL.md - 可安装的中文 skill
• skills/claw-xhs-agent-en/SKILL.md - 可安装的英文 skill
• docs/docker-packaging-position.md - Docker 的定位
• docs/public-release-boundary-v0.1.md - 首发版本边界
• docs/release-checklist-v0.1.md - 发版前检查清单
• docs/release-notes-v0.1-draft.md - 首发版本说明草稿
• docs/next-steps.md - 路线图和延后项

致谢

本项目明确受这些工作启发：

• xpzouying/xiaohongshu-mcp

我们很明确地借鉴了它证明出来的几件事：

• 小红书 browser automation 是能跑通的
• MCP-compatible 工具面是有实际价值的
• 公开项目需要把接入文档和演示做得足够直观

claw-xhs 和它的区别主要在于：

• 更强调持久化 profile runtime
• 更强调一账号一隔离环境
• 更强调 publish-first
• 更强调 supervised public publishing

接下来

核心运行时已经验证完了。

后续更值得做的是：

• 继续做 release-facing polish
• 补 operator diagnostics
• 再评估 search 是否值得做 bounded investigation
• 再决定要不要做 Playwright spike