@agent_claw/openclaw-agentclaw-plugin

OpenClaw agentclaw channel plugin，用于把 AgentClaw / 自有后端的 WebSocket 任务分发桥接到 OpenClaw agent。

支持两类入站消息：

1. JSON 文本帧：task.dispatch / task.cancel
2. 二进制单帧图片消息：4-byte header length + JSON header + image bytes

插件会把后端任务路由到 OpenClaw agent，并要求 agent 最终返回：

{"summary": "...", "content": "...", "artifacts": []}

通过 npm 发布后的用户安装方式

1. 一键安装（推荐）

npx -y @agent_claw/openclaw-agentclaw-installer install --token <YOUR_TOKEN>

可选：

npx -y @agent_claw/openclaw-agentclaw-installer install --token <YOUR_TOKEN> --version 1.0.4
npx -y @agent_claw/openclaw-agentclaw-installer install --token <YOUR_TOKEN> --no-restart
npx -y @agent_claw/openclaw-agentclaw-installer install --token <YOUR_TOKEN> --openclaw-bin "%APPDATA%\\npm\\openclaw.cmd"

该命令会自动完成：

• 安装插件包 @agent_claw/openclaw-agentclaw-plugin
• 确保 plugins.allow 包含 agentclaw
• 写入 channels.agentclaw.token
• 默认重启 OpenClaw gateway

2. 手动安装插件

openclaw plugins install @agent_claw/openclaw-agentclaw-plugin

如需固定版本：

openclaw plugins install @agent_claw/[email protected]

3. 配置 OpenClaw

{
  "plugins": {
    "allow": ["agentclaw"]
  },
  "channels": {
    "agentclaw": {
      "token": "your-token-here"
    }
  }
}

最小必填项：

• token

说明：

• WebSocket 地址在插件内 agentclaw-ws-url.mjs（AGENTCLAW_WS_URL）中固定，更换网关请改该文件而非 OpenClaw 配置
• token 填原始值即可，不要手动加 Bearer 前缀
• agentId 不填时，插件会使用默认 account id 作为回退值
• 其他参数都可以先用默认值

4. 重启 OpenClaw

openclaw gateway restart

本地开发 / 本地安装

安装依赖：

npm install

本地语法校验：

npm run check

本地目录安装到 OpenClaw：

openclaw plugins install .

发布到 npm

1. 登录 npm

npm login

2. 检查即将发布的文件

npm pack --dry-run

确认输出中至少包含：

• package.json
• README.md
• INSTALL.md
• openclaw.plugin.json
• plugin-index.mjs
• agentclaw-ws-url.mjs
• plugin-channel.mjs
• plugin-worker-client.mjs
• plugin-wss-client.mjs
• binary-frame.mjs
• attachment-adapter.mjs

并且不应包含安装器脚本 agentclaw-install.mjs。

3. 正式发布

npm publish --access public

安装器包在 installer/ 目录下，单独发布：

cd installer
npm publish --access public

4. 发布后验证

npm view @agent_claw/openclaw-agentclaw-plugin version
npm view @agent_claw/openclaw-agentclaw-installer version

可选配置示例

{
  "plugins": {
    "allow": ["agentclaw"]
  },
  "channels": {
    "agentclaw": {
      "token": "your-token-here",
      "agentId": "agentclaw-agent-001",
      "protocolVersion": "v1",
      "heartbeatSeconds": 30,
      "defaultPeerId": "backend",
      "mediaDir": "D:/tmp/openclaw-agentclaw-media",
      "maxInboundImageBytes": 20971520,
      "mediaTtlSeconds": 86400,
      "allowedImageMimeTypes": [
        "image/png",
        "image/jpeg",
        "image/webp",
        "image/gif",
        "image/heic",
        "image/heif"
      ]
    }
  }
}

说明：

• mediaDir 不填时默认落到 %TEMP%/openclaw/agentclaw-media/<accountId>，该目录位于 OpenClaw 默认允许读取的本地媒体根目录下
• maxInboundImageBytes 当前默认 20MB
• mediaTtlSeconds 默认 86400 秒，插件会在处理新的二进制图片前清理过期文件

文本任务协议

task.dispatch

{
  "type": "task.dispatch",
  "request_id": "req_001",
  "task_id": "task_001",
  "timestamp": "2026-04-29T02:00:00Z",
  "payload": {
    "task_type": "text_query",
    "instruction": "总结这段内容",
    "context": {
      "conversation_id": "conv_001",
      "user_id": "user_001"
    }
  },
  "meta": {
    "trace_id": "trace_001",
    "protocol_version": "v1"
  }
}

task.cancel

{
  "type": "task.cancel",
  "request_id": "req_cancel_001",
  "task_id": "task_001",
  "timestamp": "2026-04-29T02:00:10Z",
  "payload": {
    "reason": "user interrupted"
  },
  "meta": {
    "trace_id": "trace_001",
    "protocol_version": "v1"
  }
}

二进制图片单帧协议

帧布局

| 4 bytes header length (uint32, big-endian) |
| header JSON (utf-8)                         |
| raw image bytes                             |

header JSON 示例

{
  "type": "task.dispatch",
  "request_id": "req_img_001",
  "task_id": "task_img_001",
  "timestamp": "2026-04-29T02:05:00Z",
  "payload": {
    "instruction": "帮我看这张图里有什么异常",
    "has_image": true,
    "image_format": "png",
    "image_size": 245678,
    "context": {
      "conversation_id": "conv_001",
      "user_id": "user_001"
    }
  },
  "meta": {
    "trace_id": "trace_img_001",
    "protocol_version": "v1"
  }
}

插件行为：

1. 解析二进制帧
2. 校验 payload.instruction / payload.has_image / payload.image_format / payload.image_size
3. 校验图片格式 / 大小 / image_size 与实际字节数是否一致
4. 将图片写入本地 mediaDir
5. 生成：
   • 本地文件路径 MediaPath
   • 本地 file:// URL MediaUrl
6. 调用 OpenClaw finalizeInboundContext()，把图片作为真正的多模态媒体输入交给 agent
7. 同时把附件摘要拼进 prompt，作为兼容兜底

agent 接收方式

插件不会只把图片路径拼到纯文本里，而是会通过下面这些上下文字段传给 OpenClaw：

• MediaPath / MediaPaths
• MediaUrl / MediaUrls
• MediaType / MediaTypes

这意味着 OpenClaw runtime 可以把它当成真实图片输入处理，而不是仅靠 prompt 猜。

返回消息

插件会回传：

• task.ack
• task.status
• task.result
• error

失败时典型错误码包括：

• INVALID_MESSAGE
• INVALID_BINARY_FRAME
• TASK_CONFLICT
• TASK_NOT_FOUND
• UNSUPPORTED_MESSAGE_TYPE
• EXECUTION_FAILED
• INVALID_AGENT_OUTPUT

注意

1. 二进制帧当前只支持 图片。
2. 推荐后端严格按协议发送 has_image、image_format、image_size，二进制帧类型固定为 task.dispatch。
3. 如果后端已经有对象存储 URL，也可以直接走普通 task.dispatch + context.attachments[]。
4. 本实现优先保证 AgentClaw 场景可落地，不包含更复杂的 task.stream、任务真正中断底层 run 等增强功能。