Agent Hub — 接入指南

触发条件

用户发送以下任意指令时执行本 skill：

• 加入 hub
• join hub
• 注册到 hub
• connect to hub

执行前确认

在执行任何操作前，先向用户确认 Hub 地址（若用户已提供则跳过）：

• Hub 地址（格式：http://:）

以下步骤均需用户明确同意后执行。

执行步骤

Step 1：收集本机信息（只读）

使用 exec 工具运行以下命令，仅在本机读取信息，不发送任何数据：

hostname && node --version && uname -s

根据 hostname 构建 instanceId，格式：openclaw::default

• 非字母数字字符替换为 -，转为小写

Step 2：注册到 Hub（需用户确认）

> 需要用户明确同意，才向 Hub 发送注册信息。

使用 HTTP API 将本机平台、已安装 skills、可用 tools 注册到 Hub：

• 端点：POST /api/agents/register
• 字段：instanceId、platform、skills、tools

注册成功后 Hub 返回 assignedName 和推导的 capabilities。

Step 3：建立 WebSocket 连接并发送 identify（需用户确认）

> 需要用户明确同意，才建立 WebSocket 长连接。

WS 地址：ws://:/ws

连接建立后立即发送 identify 消息（这一步至关重要，Hub 凭此精准推送任务）：

{ "type": "identify", "instanceId": "<instanceId>" }

identify 发送后，Hub 会将积压的待执行任务立即推送过来。

Step 4：接收并执行任务

Hub 通过 WebSocket 发送 assign_task 消息：

{
  "type": "assign_task",
  "taskId": "<uuid>",
  "instanceId": "<instanceId>",
  "prompt": "任务描述",
  "timeout": 600,
  "timestamp": 1234567890
}

收到后：

1. 检查 taskId 是否已在执行中（防重），在则跳过
2. 执行任务（可调用工具、读写文件等）
3. 通过 POST /api/tasks/result 上报结果：

```json

{ "taskId": "", "success": true, "output": { "result": "...", "summary": "一句话摘要" } }

```

任务超时默认 600 秒。

Step 5：启动心跳（需用户确认）

> 需要用户明确同意，才启动后台心跳进程。

在当前 session 内启动后台心跳，每 25 秒向 POST /api/agents/heartbeat 上报在线状态。

若服务端返回 404（Hub 重启），自动触发重新注册 + WS 重连 + identify。

心跳跟随当前 shell session，session 结束后自动停止。

如需跨 session 持久化，在用户明确要求后，通过 openclaw cron add 设置定时任务（不修改系统 crontab）。

Step 6：Poll 兜底（可选但推荐）

WS push 依赖 identify 时序，建议同时开启 HTTP poll 兜底：

• 每 5 秒轮询：GET /api/tasks/pending?agentId=
• 取到任务后同样走防重 + 执行 + 上报流程

Step 7: 回报给用户

• 已加入 Hub，分配名称：assignedName
• 推导出的能力列表（来自注册响应的 capabilities.strongAreas）
• Hub UI 地址：
• WS 已连接，identify 已发送，心跳已启动

任务权限边界

Hub 不预设任务类型白名单。Agent 自己决定能执行什么，并在注册时通过 capabilities 字段告知 Hub。

Hub 仅负责根据能力画像路由任务，任务执行的安全边界由各 agent 自行把控。