什么是 WebSocket 实现与可靠性？

WebSocket 技能为开发人员提供了有效处理全双工通信协议的基本模式和配置。它解决了实时网络中的关键复杂性，如静默连接断开、背压管理和跨源安全。通过遵循 Openclaw Skills 中的标准，开发人员可以确保其 AI 代理和应用程序即使在穿过复杂的代理设置或不稳定的移动网络时，也能保持稳定、长期的连接。

该资源综合了客户端处理和服务器端配置的最佳实践。它专注于解决常见陷阱，如服务器恢复期间的惊群效应，以及浏览器环境中缺乏协议级心跳的问题。利用这些 Openclaw Skills 可确保您的实时基础设施已做好生产准备，并针对高性能数据交换进行了优化。

下载入口:https://github.com/openclaw/skills/tree/main/skills/ivangdavila/websocket

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

WebSocket 实现与可靠性 应用场景

• 构建必须优雅处理网络中断的实时聊天或通知系统。
• 使用 Redis 发布/订阅或粘性会话跨多个实例扩展有状态的 WebSocket 服务器。
• 配置 Nginx 或负载均衡器以支持长连接，避免过早超时。
• 为 AI 驱动的界面中的敏感实时数据流实现安全身份验证和来源验证。

1. 初始化连接，同时监控 readyState 以确保在尝试数据传输之前套接字已打开。
2. 每 30 秒执行一次应用级心跳（ping/pong），以检测 TCP 保活机制经常遗漏的静默故障。
3. 使用指数退避（1s、2s、4s...）结合随机抖动实现自动重连逻辑，以防止服务器过载。
4. 当连接处于正在连接状态时对消息进行排队和缓冲，在链路恢复后重新播放。
5. 在初始握手期间验证 Origin 标头，以防止跨站 WebSocket 劫持 (CSWSH)。

WebSocket 实现与可靠性 配置指南

为了在 Openclaw Skills 框架内正确设置 WebSocket 环境，请确保您的代理（如 Nginx）已配置为处理协议升级：

# Nginx 配置示例片段
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;

在客户端，使用稳健的重试策略初始化您的连接：

const socket = new WebSocket('wss://your-api.com/ws');
// 在此处实现指数退避和心跳逻辑

WebSocket 实现与可靠性 数据架构与分类体系

该技能使用以下技术元数据和架构管理连接状态和消息帧：

name: WebSocket
description: Implement reliable WebSocket connections with proper reconnection, heartbeats, and scaling.
metadata: {"clawdbot":{"emoji":"??","os":["linux","darwin","win32"]}}

Reconnection (Always Forget)

• Connections drop silently—TCP FIN may never arrive; don't assume onclose fires
• Exponential backoff: 1s, 2s, 4s, 8s... cap at 30s—prevents thundering herd on server recovery
• Add jitter: delay * (0.5 + Math.random())—prevents synchronized reconnection storms
• Track reconnection state—queue messages during reconnect, replay after
• Max retry limit then surface error to user—don't retry forever silently

Heartbeats (Critical)

• Ping/pong frames at protocol level—browser doesn't expose; use application-level ping
• Send ping every 30s, expect pong within 10s—no pong = connection dead, reconnect
• Server should ping too—detects dead clients, cleans up resources
• Idle timeout in proxies (60-120s typical)—heartbeat must be more frequent
• Don't rely on TCP keepalive—too infrequent, not reliable through proxies

Connection State

• readyState: 0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED—check before sending
• Buffer messages while CONNECTING—send after OPEN
• bufferedAmount shows queued bytes—pause sending if backpressure building
• Multiple tabs = multiple connections—coordinate via BroadcastChannel or SharedWorker

Authentication

• Token in URL query: wss://host/ws?token=xxx—simple but logged in access logs
• First message auth: connect, send token, wait for ack—cleaner but more round trips
• Cookie auth: works if same origin—but no custom headers in WebSocket
• Reauthenticate after reconnect—don't assume previous session valid

Scaling Challenges

• WebSocket connections are stateful—can't round-robin between servers
• Sticky sessions: route by client ID to same server—or use Redis pub/sub for broadcast
• Each connection holds memory—thousands of connections = significant RAM
• Graceful shutdown: send close frame, wait for clients to reconnect elsewhere

Nginx/Proxy Config

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;

• Without these headers, upgrade fails—connection closes immediately
• proxy_read_timeout must exceed your ping interval—default 60s too short
• Load balancer health checks: separate HTTP endpoint, not WebSocket

Close Codes

• 1000: normal closure; 1001: going away (page close)
• 1006: abnormal (no close frame received)—usually network issue
• 1008: policy violation; 1011: server error
• 4000-4999: application-defined—use for auth failure, rate limit, etc.
• Always send close code and reason—helps debugging

Message Handling

• Text frames for JSON; binary frames for blobs/protobuf—don't mix without framing
• No guaranteed message boundaries in TCP—but WebSocket handles framing for you
• Order preserved per connection—messages arrive in send order
• Large messages may fragment—library handles reassembly; set max message size server-side

Security

• Validate Origin header on handshake—prevent cross-site WebSocket hijacking
• Same-origin policy doesn't apply—any page can connect to your WebSocket server
• Rate limit per connection—one client can flood with messages
• Validate every message—malicious clients can send anything after connecting

Common Mistakes

• No heartbeat—connection appears alive but is dead; messages go nowhere
• Reconnect without backoff—hammers server during outage, prolongs recovery
• Storing state only in connection—lost on reconnect; persist critical state externally
• Huge messages—blocks event loop; stream large data via chunking
• Not handling bufferedAmount—memory grows unbounded if client slower than server