安装方式
手动下载安装
下载 ZIP 后解压到技能目录即可安装。若在桌面客户端 WebView中直接下载出现异常，本站会改为提示页 + 原始链接，请按页内说明操作。
下载 ZIP (shub-websocket-receiver-v1.0.0.zip)触发指令
/websocket-receiver
跨平台安装指引
该技能声明兼容以下 1 个平台，将 ZIP 解压到对应目录即可被识别。
unzip shub-websocket-receiver-v1.0.0.zip -d ~/.claude/skills/
目录不存在时请先
mkdir -p 创建；启用 Skill 后请重启对应 Agent 让配置生效。
使用指南
WebSocket 服务端接收
围绕 WebSocket 服务端接收：连接接入、鉴权、限流与消息分发模式；与「websocket-reconnect」客户端向互补。 无需在每次任务前把零散英文说明手工拼进上下文，也 减少 与客户端默认行为脱节的试错；具体命令、钩子与 JSON 参数仍以 ZIP 包内 SKILL.md 为权威。下文结构与站内 MCP CLI 类专题稿相同：何时用、前置、流程、速查与故障。
何时使用
- 连接接入、鉴权、限流与消息分发模式
- 与「websocket-reconnect」客户端向互补
- 已获取本技能 ZIP，并准备在 Claude Code / OpenClaw 中按 SKILL.md 挂载。
- 希望用中文专题稿快速判断「该不该启用」，再深入英文 SKILL 查参数与边界。
- 需要与团队对齐同一套触发方式、目录约定或回调格式时。
前置条件
- 通用：可运行 Claude Code 或文档要求的客户端；有可读写的项目工作区（或 SKILL.md 指定的沙箱目录）。
- 权威细节：API Key / OAuth、钩子路径、环境变量以 ZIP 内 SKILL.md 为准。
典型流程
- 从 ClawHub / 站内分发获取技能 ZIP，校验版本与校验和（若提供）。
- 阅读 SKILL.md 的安装段落：目录落点、客户端类型（Claude Code / OpenClaw / 脚本）。
- 用文档中的最小示例完成第一次调用（单文件修改、单次查询或单次委派）。
- 确认工作目录、权限边界与输出路径后，再处理多文件或长耗时任务。
- 需要回调 / Webhook / 通知时，按 SKILL.md 配置端点并在测试环境先验通。
与 ZIP / SKILL.md 的关系
站内专题稿与 MCP CLI 类 oss 稿同样：概括何时用、怎么接、怎么排错；命令模板、钩子名、JSON 字段、版本矩阵一律以 ZIP 内 SKILL.md 与 ClawHub 上游为准。
命令示例（摘自包内 SKILL.md）
以下为从上游 SKILL.md（或入库正文）自动抽取的终端/脚本片段；路径、环境变量与参数以当前 ZIP 与官方说明为准。
ClawHub slug：websocket-receiver（安装命令以 SKILL.md / claw CLI 为准）。
# 安装依赖
pip install websockets
# 或使用虚拟环境
~/clawd/venv/bin/pip install websockets
# 前台测试（替换为你的真实地址）
WEBSOCKET_URL=ws://your-server:port/ws websocket-receiver test
# 后台运行
WEBSOCKET_URL=ws://your-server:port/ws websocket-receiver start
# 查看状态
websocket-receiver status
# 查看日志
websocket-receiver logs
# 停止
websocket-receiver stop
websocket-receiver start # 后台启动
websocket-receiver stop # 停止
websocket-receiver restart # 重启
websocket-receiver status # 查看状态
websocket-receiver logs # 实时日志
websocket-receiver config # 查看或创建配置
websocket-receiver test # 前台测试
站内入库时的触发命令（完整语义见 ZIP）：
# 使用本技能时可在对话中引用或执行上述指令；完整参数与示例见下载包内 SKILL.md。
/websocket-receiver
最佳实践
- 先 SKILL.md 再猜参数；站内专题稿不替代 schema 与必填字段说明。
- 委派任务时写清验收标准（命令、文件路径、测试命令），减少来回追问。
- 长任务用文档推荐的回调 / 日志落盘代替高频轮询，省 Token 也省机器负载。
- 多技能同时启用时，注意钩子加载顺序与重复工具调用（以 SKILL.md 冲突说明为准）。
调试与排错
- 打开 stderr 与客户端日志；PTY/tmux 场景同时看面板最后几十行输出。
- 参数错误时对照 SKILL.md 中的 JSON/CLI 示例（引号、转义、工作目录）。
- 网络类失败：查代理、防火墙、MCP 传输方式（stdio / HTTP / SSE）。
速查
| 动作 | 说明 |
|------|------|
| 获取技能包 | ClawHub / 站内 ZIP，核对版本 |
| 权威步骤 | 优先阅读 ZIP 内 SKILL.md |
| 首次试跑 | 使用 SKILL.md 最小示例 |
| 验收 | 对照路径、测试命令或回调负载 |
常见故障
- 无输出或立即退出 → 工作目录错误、依赖未装、或 Claude Code 未登录；按 SKILL.md 自检清单执行。
- 权限被拒绝 → 检查沙箱路径、
--permission-mode与工具白名单。 - 与简介不符 → 以英文 SKILL 与上游仓库为准，站内稿仅作结构化导读。
# WebSocket 接收器 v1.1.2
🎓 这是一个 WebSocket 对接的练手 skill，适合学习如何：
- 建立和维护 WebSocket 长连接
- 处理实时数据流
- 实现自动重连和错误恢复
- 批量处理和 AI 分析集成
可作为模板，修改后对接你自己的 WebSocket 数据源。
## 功能特点
- 🔌 自动重连（指数退避算法）
- 📦 批量数据处理
- 🤖 可选 AI 分析集成
- 📊 日志轮转
- 🛑 优雅关闭（处理完缓冲区再退出）
- 💾 JSONL 数据持久化
## 安装
```bash
# 安装依赖
pip install websockets
# 或使用虚拟环境
~/clawd/venv/bin/pip install websockets
```
## 获取 WebSocket 地址
⚠️ 本 skill 仅供学习练手，不包含真实数据源。
配套的测试服务端每隔 10 秒推送一条模拟数据，方便你观察接收和批量处理流程。
如需测试，你可以：
1. 联系作者获取测试服务器地址
2. 自己搭建一个 WebSocket 服务器
3. 使用公开的测试 WebSocket
配置方式：
- 环境变量：`WEBSOCKET_URL=ws://your-server:port/ws`
- 配置文件：`~/.openclaw/websocket-config.json`
## 快速开始
```bash
# 前台测试（替换为你的真实地址）
WEBSOCKET_URL=ws://your-server:port/ws websocket-receiver test
# 后台运行
WEBSOCKET_URL=ws://your-server:port/ws websocket-receiver start
# 查看状态
websocket-receiver status
# 查看日志
websocket-receiver logs
# 停止
websocket-receiver stop
```
## 配置
### 环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `WEBSOCKET_URL` | WebSocket 服务器地址 | （需配置） |
| `WEBSOCKET_BATCH` | 批次大小 | `10` |
| `WEBSOCKET_DATA_DIR` | 数据目录 | `~/clawd/data/websocket` |
| `WEBSOCKET_CONFIG` | 配置文件路径 | `~/.openclaw/websocket-config.json` |
### 配置文件
创建 `~/.openclaw/websocket-config.json`：
```json
{
"ws_url": "ws://your-server:port/ws",
"batch_size": 10,
"auto_analyze": true,
"data_dir": "~/clawd/data/websocket",
"reconnect_delay": 2,
"reconnect_max_delay": 60,
"reconnect_max_attempts": 0
}
```
### 配置项说明
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `ws_url` | WebSocket 地址 | （需配置） |
| `batch_size` | 触发批量处理的消息数 | `10` |
| `auto_analyze` | 是否自动 AI 分析 | `true` |
| `data_dir` | 数据存储目录 | `~/clawd/data/websocket` |
| `reconnect_delay` | 初始重连延迟（秒） | `2` |
| `reconnect_max_delay` | 最大重连延迟（秒） | `60` |
| `reconnect_max_attempts` | 最大重连次数（0=无限） | `0` |
| `connect_timeout` | 连接超时（秒） | `30` |
| `ping_interval` | 心跳间隔（秒） | `30` |
| `ping_timeout` | 心跳超时（秒） | `10` |
## 命令
```bash
websocket-receiver start # 后台启动
websocket-receiver stop # 停止
websocket-receiver restart # 重启
websocket-receiver status # 查看状态
websocket-receiver logs # 实时日志
websocket-receiver config # 查看或创建配置
websocket-receiver test # 前台测试
```
## 数据格式
接收的 JSON 消息格式：
```json
{
"id": "unique-id",
"title": "标题",
"content": "内容",
"url": "链接",
"timestamp": "2026-03-12T12:00:00Z"
}
```
数据保存为 JSONL 格式：
```json
{"received_at": "2026-03-12T12:00:00", "data": {...}}
```
## 文件结构
```
~/clawd/data/websocket/
├── receiver.pid # 进程 ID 文件
├── receiver.log # 日志文件（自动轮转）
├── data_20260312_14.jsonl # 按小时分割的数据文件
├── data_20260312_15.jsonl
└── analysis_20260312.md # AI 分析报告
```
## 自定义处理
```python
from receiver import WebSocketReceiver
receiver = WebSocketReceiver(config)
# 自定义消息处理函数
def my_handler(data):
print(f"收到数据: {data}")
return True # 返回 True 表示处理成功
receiver.on_message = my_handler
# 自定义批量处理函数（支持 async）
async def my_batch_handler(batch):
# 在这里编写自定义分析逻辑
return "分析结果"
receiver.on_batch = my_batch_handler
receiver.run()
```
## 依赖
- Python 3.8+
- websockets
## 版本历史
### v1.1.2
- 强制配置 WebSocket 地址，未配置时启动报错
### v1.1.1
- 重写核心逻辑，提升稳定性
- 添加指数退避重连
- 异步 subprocess 调用
- 优雅关闭机制
- 日志轮转
- 正确的 PID 管理
### v1.0.0
- 初始版本
## 许可证
MIT