🐟 闲鱼 × OpenClaw 频道插件

将闲鱼二手交易平台的消息接入 OpenClaw AI Agent，实现智能客服、自动回复、自动发货、商品发布等功能。

✨ 特性

• 🔌 一键安装 — 克隆仓库，运行安装脚本，搞定
• 🤖 OpenClaw 集成 — 闲鱼消息直接接入 AI Agent，支持上下文对话
• 🚀 自动启动 — OpenClaw Gateway 启动时自动拉起闲鱼服务，停止时自动关闭
• 📱 多账号 — 支持同时管理多个闲鱼账号
• 🚚 自动发货 — 检测付款消息自动确认发货
• 🛒 商品发布 — 支持单个/批量商品发布（API + 工具）
• 🔍 商品搜索 — 爬取闲鱼商品信息，市场调研
• 🔒 Bridge 模式 — TypeScript 插件通过 HTTP/SSE 桥接 Python 闲鱼服务，安全隔离

🏗️ 架构

OpenClaw Agent ←→ Channel Plugin (TS) ←HTTP/SSE→ Bridge API (Python) ←WebSocket→ 闲鱼
                   openclaw-plugin/                 reply_server.py

• Channel Plugin（openclaw-plugin/）：TypeScript OpenClaw 频道适配器
• Bridge API（bridge_api.py）：Python 端 RESTful + SSE 接口
• 闲鱼核心（XianyuAutoAsync.py）：WebSocket 连接、消息处理、自动回复
• 商品发布器（product_publisher.py）：Playwright 自动化发布商品
• Gateway 启动时，插件通过 registerService 自动 spawn Python 进程

📋 环境要求

依赖	版本
Python	3.11+
Node.js	16+
OpenClaw	最新版

🚀 快速开始

1. 克隆仓库

git clone https://github.com/laozuzhen/xianyu-openclaw-channel.git
cd xianyu-openclaw-channel

2. 一键安装

# Linux/macOS
bash install-openclaw.sh

# Windows
install-openclaw.bat

脚本自动完成：

• ✅ Python 虚拟环境 + 依赖安装
• ✅ Node.js 插件依赖安装
• ✅ Bridge Token 自动生成
• ✅ 插件注册到 OpenClaw extensions

3. 配置 OpenClaw

在 ~/.openclaw/openclaw.json 中添加配置：

插件加载配置（必须）

{
  "plugins": {
    "allow": ["xianyu"],
    "load": {
      "paths": ["<扩展目录>/xianyu/openclaw-plugin"]
    },
    "entries": {
      "xianyu": {
        "enabled": true
      }
    }
  }
}

频道配置

{
  "channels": {
    "xianyu": {
      "accounts": {
        "2207836320265_1": {  // 账号ID，对应闲鱼管理界面中的Cookie ID
          "apiUrl": "http://localhost:8080"
        }
      },
      "enabled": true
    }
  }
}

Agent 绑定配置

{
  "agentMatch": [
    {
      "agentId": "xianyu-kefu",  // 绑定到闲鱼客服 agent
      "match": {
        "accountId": "2207836320265_1",
        "channel": "xianyu"
      }
    }
  ]
}

4. 配置闲鱼账号

1. 访问 http://localhost:8080（闲鱼管理界面）
2. 默认账号：admin / admin123（首次登录请改密码）
3. 添加闲鱼账号的 Cookie

重要:

• 添加账号时，账号 ID 必须与 OpenClaw 配置中的 accountId 一致
• Cookie 必须包含 unb 和 _m_h5_tk 字段

5. 启动

# 启动 Python 后端
python Start.py

# 重启 OpenClaw Gateway 使配置生效
openclaw gateway restart

🛠️ 可用工具

闲鱼插件注册了以下工具供 AI Agent 调用：

工具名称	说明
xianyu_publish_product	发布单个商品到闲鱼
xianyu_batch_publish_products	批量发布多个商品
xianyu_get_orders	获取订单列表
xianyu_confirm_delivery	确认订单发货
xianyu_create_card	创建发货内容卡片
xianyu_create_delivery_rule	创建自动发货规则
xianyu_search_products	搜索闲鱼商品
xianyu_get_spider_products	获取已爬取的商品列表

商品发布示例

用户：帮我发布一个商品
Agent：好的，请提供商品信息...
[调用 xianyu_publish_product 工具]

工具参数说明：

{
  "cookie_id": "2207836320265_1",  // 必填：账号 Cookie ID
  "title": "商品标题",              // 可选
  "description": "商品描述",        // 必填
  "price": 99.9,                   // 必填：价格（元）
  "images": ["/path/to/image.jpg"], // 必填：图片路径列表
  "category": "数码产品/手机",       // 可选
  "location": "北京市/朝阳区"        // 可选
}

⚠️ 商品发布注意事项

1. 规格选择问题

问题描述：发布页面有时会自动选中商品规格，导致发布按钮禁用。

解决方案：

• 当前代码已处理：自动跳过规格选择
• 如遇到问题，检查 product_publisher_config.yml 中的 category_selector 配置
• 不要使用 button:has-text("添加规格类型") 作为选择器，会误点添加规格按钮

2. 滑块验证

现状：闲鱼发布商品的滑块验证已升级为双物体拼接类型，需要拖动滑块使两个物体完整拼接。

解决方案：

• 方案 A：使用可见模式（headless=False），人工辅助完成验证
• 方案 B：接入第三方打码服务
• 方案 C：发布前手动完成验证

3. 发布验证

发布成功的判断依据：

1. 页面 URL 从 /publish 跳转到 /item?id=xxx
2. 能解析到 product_id 和 product_url

🔌 Bridge API 端点

端点	方法	说明
/api/bridge/messages	GET (SSE)	实时消息推送流
/api/bridge/send	POST	发送文本消息
/api/bridge/send-media	POST	发送图片消息
/api/bridge/accounts	GET	获取账号列表
/api/bridge/status	GET	获取桥接状态
/api/bridge/confirm-delivery	POST	确认发货
/api/bridge/publish/single	POST	发布单个商品
/api/bridge/publish/batch	POST	批量发布商品
/api/bridge/spider/search	POST	搜索商品
/api/bridge/logs	GET	获取后端日志

📁 项目结构

xianyu-openclaw-channel/
├── openclaw-plugin/           # OpenClaw 频道插件 (TypeScript)
│   ├── index.ts               # 插件入口，注册 channel + service + tools
│   └── src/
│       ├── channel.ts             # 频道定义
│       ├── bridge-client.ts       # Bridge API 客户端
│       └── ...
├── bridge_api.py              # Bridge API（Python 端 HTTP/SSE）
├── product_publisher.py       # 商品发布器（Playwright）
├── product_publisher_config.yml # 发布器配置
├── Start.py                   # Python 启动入口
├── XianyuAutoAsync.py         # 闲鱼 WebSocket 核心
└── reply_server.py            # FastAPI Web 服务

❓ 常见问题

Q: 工具没有注册到 OpenClaw？

A: 检查以下几点：

1. 插件是否在 plugins.allow 列表中：

"plugins": {
  "allow": ["xianyu", ...]
}

2. 插件路径是否配置：

"plugins": {
  "load": {
    "paths": ["<扩展目录>/xianyu/openclaw-plugin"]
  }
}

3. 重启 Gateway：

openclaw gateway restart

Q: 收不到闲鱼消息？

A:

1. 检查 Python 后端是否运行：python Start.py
2. 检查 accountId 是否与 Cookie ID 一致
3. 查看 SSE 连接日志

Q: 商品发布失败？

A:

1. 检查 Cookie 是否有效
2. 确认图片路径存在且格式正确
3. 查看后端日志：GET /api/bridge/logs
4. 使用可见模式测试：修改 product_publisher.py 中的 headless=False

Q: Gateway 启动后 Python 进程没起来？

A:

• 检查 venv/ 是否存在
• 查看插件日志中的 [bridge-process] 前缀信息
• 确认系统 PATH 中有 python

Q: 如何只用闲鱼自动回复，不用 OpenClaw？

A: 直接 python Start.py，访问 http://localhost:8080 使用原生管理界面。

📝 更新日志

2026-03-08

• 🐛 修复商品发布时误点"添加规格类型"按钮的问题
• ✨ 改进发布验证逻辑
• 📝 更新文档，添加工具注册说明

2026-03-07

• ✨ 添加商品发布 API 和工具
• ✨ 添加商品搜索功能
• ✨ 添加后端日志 API

📜 致谢

• xianyu-auto-reply — 闲鱼自动回复核心
• OpenClaw — AI Agent 框架
• openclaw-channel-dingtalk — 插件架构参考

⚖️ 声明

本项目仅供学习研究使用，严禁商业用途。使用者需遵守当地法律法规，使用风险自负。