小红书智能浏览器自动化工具，AI驱动的社区冲浪和互动。
- 智能冲浪 - AI驱动自主决策，自动搜索、浏览、点赞、评论
- 实时控制 - Web控制面板 + REST API + WebSocket
- 安全防护 - 防封号机制、频率限制、行为模拟
- 多LLM支持 - 通义千问、智谱、DeepSeek、OpenAI等
- OpenClaw Skill - 支持自然语言调用，可集成到AI Agent
# 安装 ClawHub CLI
npm i -g clawhub
# 安装 Skill
clawhub install xhs-surfer
# 安装 Python 依赖
pip install xhs-surfer
playwright install chromium# 克隆项目
git clone https://github.com/MTXAI/xhs_suffer.git
cd xhs_suffer
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -e ".[dev,llm,api]"
# 安装浏览器
playwright install chromium# 终端1：启动后端
xhs-surfer api --port 8000
# 终端2：启动前端
cd frontend && npm install && npm run dev访问 http://localhost:5173 打开控制面板。
# 登录
xhs-surfer login
# 冲浪
xhs-surfer surf --topic "Python编程" --duration 30
# 无头模式
xhs-surfer surf --topic "AI" --duration 60 --headlessimport asyncio
from xhs_surfer import CommunitySurfer, SurfConfig
async def main():
config = SurfConfig(topic="Python编程", duration_minutes=10)
surfer = CommunitySurfer(config)
await surfer.start()
if not await surfer.check_login():
await surfer.login(method="qr")
await surfer.surf()
summary = await surfer.stop()
print(f"浏览: {summary.total_posts_viewed}, 点赞: {summary.likes_given}")
asyncio.run(main())from xhs_surfer import CommunitySurferSkill
skill = CommunitySurferSkill.create()
result = await skill.run("浏览小红书上关于Python的帖子30分钟")注意：Skill 功能目前处于测试阶段，推荐优先使用 Web 控制面板或命令行方式体验完整功能。
详细文档：SKILL.md
创建 .env 文件：
LLM_PROVIDER=qwen
QWEN_API_KEY=sk-xxx支持的提供商：
| 提供商 | Provider ID | 环境变量 |
|---|---|---|
| 阿里通义千问 | qwen |
QWEN_API_KEY |
| 智谱AI | zhipu |
ZHIPU_API_KEY |
| DeepSeek | deepseek |
DEEPSEEK_API_KEY |
| OpenAI | openai |
OPENAI_API_KEY |
| Anthropic | anthropic |
ANTHROPIC_API_KEY |
| 端点 | 方法 | 说明 |
|---|---|---|
/api/session/start |
POST | 开始会话 |
/api/session/stop |
POST | 停止会话 |
/api/session/pause |
POST | 暂停会话 |
/api/session/resume |
POST | 恢复会话 |
/api/session/status |
GET | 获取状态 |
/api/command |
POST | 发送命令 |
WebSocket: ws://localhost:8000/ws
┌─────────────────────────────────────────────────────┐
│ XHS Surfer │
├─────────────────────────────────────────────────────┤
│ Frontend (React) ←→ API (FastAPI) ←→ Surfer │
│ WebSocket 实时通信 │
├─────────────────────────────────────────────────────┤
│ Brain(决策) Eyes(感知) Hands(操作) Memory(存储) │
│ Shield(防护) Safety(安全) Events(事件) │
└─────────────────────────────────────────────────────┘
pip install -e ".[dev,llm,api]"
pytest tests/ -v
black src/ && ruff check src/本项目仅供学习和研究目的。使用本工具时请遵守相关平台的服务条款和法律法规。