WebSocket 接收器

WebSocket 数据接收练手 skill。支持自动重连、批量处理和 AI 分析集成。

Security Scan

The skill mostly does what it claims (WebSocket receiving, batching, AI analysis) but contains surprising/undeclared behaviors — notably an install script that writes a default config pointing to an external IP and runtime code that invokes the local 'openclaw' CLI to analyze batches — that are not fully documented in the registry metadata.

Purpose & Capability

The code (scripts/receiver.py) implements a WebSocket receiver with reconnect, batching, JSONL persistence, and optional AI analysis — consistent with the skill description. However, the install script creates a sample config that points to a hard-coded external IP (ws://59.110.46.1:6680/ws). That default server is not mentioned in the SKILL.md prose and contradicts the README's claim that the skill "does not contain a real data source." Creating a pre-filled config pointing to a remote host is unnecessary for a learning template and is disproportionate to the stated purpose.

Instruction Scope

SKILL.md documents env vars and a config file (~/.openclaw/websocket-config.json) but does not mention that the runtime will call the local 'openclaw' CLI. The receiver uses asyncio.create_subprocess_exec to run 'openclaw agent ... --message <prompt>' for batch AI analysis and 'openclaw notify <message>' for notifications. Those calls cause collected message content (the batch prompt) to be handed to the local OpenClaw agent, which may forward it to external LLM providers; this data flow is not clearly documented in metadata/registry. The install.sh also auto-writes the config with a remote ws_url, which could cause the skill to immediately start connecting to an unfamiliar external endpoint if the user runs it.

Install Mechanism

There is no formal install spec in the registry, but the package includes install.sh which: installs Python dependency, creates data directories, appends the skill script path to the user's shell rc (modifies PATH), and writes ~/.openclaw/websocket-config.json containing a hard-coded external IP. Modifying shell startup files and creating a config with a remote server are actions with side effects that should be explicitly documented in registry metadata; the presence of a hard-coded IP in the created config is a red flag.

Credentials

Registry metadata lists no required environment variables, but SKILL.md expects WEBSOCKET_URL and a config file path. The code invokes external CLI 'openclaw' without declaring it as a required binary or dependency. While the skill does not request secrets like API keys, it does rely on an external CLI (openclaw) and on a config file that the installer populates with a remote ws_url — these runtime dependencies are not reflected in the declared requirements and can lead to unexpected network activity or data exposure.

Persistence & Privilege

The skill does not request 'always: true' and does not alter other skills' configs. However, install.sh persists state: it writes files under the user's home (~/.openclaw, ~/clawd/data/websocket), writes a PID file at runtime, and appends to shell rc to add the scripts directory to PATH. These are normal for a local CLI tool but are nontrivial side effects that should be highlighted before installation.

What to consider before installing

This skill implements the advertised WebSocket receiver, but exercise caution before installing/running it. Specific things to consider before proceeding: - Inspect and edit install.sh: it writes ~/.openclaw/websocket-config.json with ws://59.110.46.1:6680/ws by default. Remove or change that hard-coded ws_url before starting the receiver to avoid connecting to an unknown host. - Be aware that receiver.py sends batch content to the local 'openclaw' CLI (openclaw agent --message ...) for AI analysis. That hands your collected messages to whatever the local OpenClaw agent is configured to do (likely forwarding to an external LLM provider). If you will process sensitive data, disable auto_analyze or remove/replace that code. - The installer appends the skill scripts path to your shell rc (~/.bashrc or ~/.zshrc). If you prefer no PATH modifications, edit the script or run the tool directly (python3 scripts/receiver.py). - Confirm provenance: the package source is 'unknown' and metadata author is minimal. If you don't trust the author, run this in an isolated environment (container or VM), or avoid installing. - If you want to use this as a template: set ws_url to a known local/test server, turn off auto_analyze, and review the notify/agent subprocess calls. Consider replacing the openclaw subprocess calls with explicit calls to a vetted LLM API or local analyzer you control. If you want, I can: (1) point out the exact lines in install.sh and receiver.py to change, (2) produce a safe modified install script that does not write a default remote ws_url or modify shell rc, or (3) show how to run the receiver in a containerized/isolated way.

WebSocket 接收器 v1.1.2

🎓 这是一个 WebSocket 对接的练手 skill，适合学习如何：

• 建立和维护 WebSocket 长连接
• 处理实时数据流
• 实现自动重连和错误恢复
• 批量处理和 AI 分析集成

可作为模板，修改后对接你自己的 WebSocket 数据源。

功能特点

• 🔌 自动重连（指数退避算法）
• 📦 批量数据处理
• 🤖 可选 AI 分析集成
• 📊 日志轮转
• 🛑 优雅关闭（处理完缓冲区再退出）
• 💾 JSONL 数据持久化

安装

# 安装依赖
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

快速开始

# 前台测试（替换为你的真实地址）
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：

{
  "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

命令

websocket-receiver start    # 后台启动
websocket-receiver stop     # 停止
websocket-receiver restart  # 重启
websocket-receiver status   # 查看状态
websocket-receiver logs     # 实时日志
websocket-receiver config   # 查看或创建配置
websocket-receiver test     # 前台测试

数据格式

接收的 JSON 消息格式：

{
  "id": "unique-id",
  "title": "标题",
  "content": "内容",
  "url": "链接",
  "timestamp": "2026-03-12T12:00:00Z"
}

数据保存为 JSONL 格式：

{"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 分析报告

自定义处理

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