rol-websocket-channel 1.5.9 → 1.6.2

package/MQTT-API/347/211/210/346/234/254/346/237/245/347/234/213.md

@@ -0,0 +1,2191 @@
+# OpenClaw MQTT API 文档 （版本查看）
+
+## 消息格式
+
+所有 MQTT 消息使用以下格式：
+
+**请求消息**
+```json
+{
+  "type": "消息类型",
+  "trace_id": "唯一追踪ID",
+  "data": { /* 请求参数 */ }
+}
+```
+
+**响应消息**
+```json
+{
+  "type": "receiver",
+  "trace_id": "对应的请求 trace_id",
+  "source": "system",
+  "timestamp": 1776331005170,
+  "success": true,
+  "data": { /* 响应数据 */ }
+}
+```
+
+---
+
+## 系统管理 (System)
+
+### systemRestart - 重启网关
+
+**请求**
+```json
+{
+  "type": "systemRestart",
+  "trace_id": "system-restart-001",
+  "data": {}
+}
+```
+
+---
+
+### systemStop - 停止网关 *
+
+**请求**
+
+```json
+{
+  "type": "systemStop",
+  "trace_id": "system-stop-001",
+  "data": {}
+}
+```
+
+---
+
+### systemDoctorFix - 诊断修复
+
+**请求**
+```json
+{
+  "type": "systemDoctorFix",
+  "trace_id": "system-doctor-001",
+  "data": {}
+}
+```
+
+---
+
+### systemLogs - 查看日志 接！！
+
+**请求**
+```json
+{
+  "type": "systemLogs",
+  "trace_id": "system-logs-001",
+  "data": {}
+}
+```
+```
+说明：获取最近 100 条日志。
+```
+
+---
+
+### openclawUpdate - 升级 OpenClaw
+
+**说明**
+- 固定执行 `npm install -g @openclaw/core@2026.5.6`。
+- 安装后依次执行 `openclaw --version` 和 `openclaw doctor --deep` 做校验。
+- 用于 App 上的“升级 OpenClaw”按钮。
+- 返回 `stdout` / `stderr`，失败时外层 `ok` 为 `false`。
+
+**请求**
+```json
+{
+  "type": "openclawUpdate",
+  "trace_id": "openclaw-update-001",
+  "data": {}
+}
+```
+
+**成功返回 data.result 示例**
+```json
+{
+  "ok": true,
+  "action": "openclawUpdate",
+  "targetPackage": "@openclaw/core",
+  "targetVersion": "2026.5.6",
+  "restartRecommended": true,
+  "steps": [
+    {
+      "name": "installCore",
+      "command": "npm",
+      "args": ["install", "-g", "@openclaw/core@2026.5.6"],
+      "cwd": "/home/user/.openclaw",
+      "stdout": "",
+      "stderr": ""
+    },
+    {
+      "name": "version",
+      "command": "openclaw",
+      "args": ["--version"],
+      "cwd": "/home/user/.openclaw",
+      "stdout": "OpenClaw 2026.5.6 ...",
+      "stderr": ""
+    },
+    {
+      "name": "doctorDeep",
+      "command": "openclaw",
+      "args": ["doctor", "--deep"],
+      "cwd": "/home/user/.openclaw",
+      "stdout": "",
+      "stderr": ""
+    }
+  ]
+}
+```
+
+---
+
+### pluginSelfUpdate - 升级 rol-websocket-channel 插件
+
+**说明**
+- 固定执行 `openclaw plugins install clawhub:rol-websocket-channel`。
+- 用于 App 上的“升级插件”按钮。
+- 命令执行成功后，新的插件代码通常需要 OpenClaw/插件进程重新加载后才会生效。
+
+**请求**
+```json
+{
+  "type": "pluginSelfUpdate",
+  "trace_id": "plugin-self-update-001",
+  "data": {}
+}
+```
+
+---
+
+### systemCurrentVersion - 查询当前版本
+
+**说明**
+- 查询本机 OpenClaw 版本和 channel 插件版本，与期望版本比对。
+- openclaw 期望版本：插件内硬编码常量（当前 `2026.5.6`）。
+- channel 期望版本：`npm view rol-websocket-channel --json` 从 npm registry 获取最新发布版本。
+- `npm view` 失败时回退到硬编码 `1.5.9`，不阻塞接口。
+- `currentVersion !== latestVersion`  `status: "outdated"`，相等  `status: "current"`。
+- 前端只需看 `targets` 里的 `status`，哪个 `"outdated"` 就调对应的升级接口。
+
+**前端升级流程**
+1. 调 `systemCurrentVersion`
+2. `channel` 是 `outdated`  调 `pluginSelfUpdate`
+3. `openclaw` 是 `outdated`  调 `openclawUpdate`
+4. 升完重启
+
+**请求**
+```json
+{
+  "type": "systemCurrentVersion",
+  "trace_id": "system-current-version-001",
+  "data": {}
+}
+```
+
+---
+
+## 代理管理 (Agents)
+
+## 代理管理 (Agents)
+
+### agentsGet - 获取代理配置
+
+**说明**
+
+- `agentsGet` 偏向配置视角，返回默认代理配置、命名代理配置和当前工具配置。
+- 如果前端是做代理列表页，优先使用 `agentsList`。
+
+**请求**
+```json
+{
+  "type": "agentsGet",
+  "trace_id": "agents-get-001",
+  "data": {}
+}
+```
+
+---
+
+### agentsList - 列出所有代理
+
+**说明**
+- `agentsList` 偏向管理列表视角，返回可直接用于列表渲染的 `items`。
+- 返回中通常包含 `defaults` 和所有命名代理。
+
+**请求**
+```json
+{
+  "type": "agentsList",
+  "trace_id": "agents-list-001",
+  "data": {}
+}
+```
+
+---
+
+### agentsCreate - 创建代理
+
+**说明**
+- `agentId` 是代理唯一标识，建议前端统一使用这个字段。
+- `workspace` 表示代理实际工作的目录。
+- `agentDir` 表示代理自己的运行/状态目录。
+- 不传 `workspace` / `agentDir` 时，后端会自动生成默认路径。
+
+**请求**
+```json
+{
+  "type": "agentsCreate",
+  "trace_id": "agents-create-001",
+  "data": {
+    "agentId": "my-agent",
+    "name": "My Agent",
+    "workspace": "/home/woowonjae/.openclaw/workspace/my-agent",
+    "agentDir": "/home/woowonjae/.openclaw/agents/my-agent/agent",
+    "modelPrimary": "custom-dashscope-aliyuncs-com/qwen-plus",
+    "modelProvider": "custom-dashscope-aliyuncs-com",
+    "toolsProfile": "coding"
+  }
+}
+```
+
+**模型字段说明**
+- `modelPrimary` 使用完整的 `providerId/modelName`。
+- `modelProvider` 只做兼容校验；如果传入，必须与 `modelPrimary` 的 provider 部分一致。
+- 创建后只保存 `model.primary`，不会把 `modelProvider` 写成 `model.provider`。
+
+---
+
+### agentsUpdate - 更新代理
+
+**说明**
+- 使用 `agentId` 指定要修改的代理。
+- 不传 `agentId` 时，默认更新 `defaults`。
+- `updates` 目前只支持这些字段：
+  - `name`
+  - `workspace`
+  - `agentDir`
+  - `model.primary`
+  - `skills`
+  - `tools.profile`
+  - `behavior`
+- `model.provider` 不能通过 `agentsUpdate` 写入；provider 从 `model.primary` 派生。
+- 切换 agent 模型时只写 `model.primary`，值必须是完整的 `providerId/modelName`。
+
+**请求**
+
+```json
+{
+  "type": "agentsUpdate",
+  "trace_id": "agents-update-001",
+  "data": {
+    "agentId": "my-agent",
+    "updates": {
+      "model.primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+      "tools.profile": "coding"
+    }
+  }
+}
+```
+
+**更新默认代理示例**
+
+```json
+{
+  "type": "agentsUpdate",
+  "trace_id": "agents-update-defaults-001",
+  "data": {
+    "updates": {
+      "model.primary": "custom-dashscope-aliyuncs-com/qwen-plus"
+    }
+  }
+}
+```
+
+---
+
+### agentsDelete - 删除代理
+
+**请求**
+
+```json
+{
+  "type": "agentsDelete",
+  "trace_id": "agent-delete-001",
+  "data": {
+    "agentId": "coder2",
+    "purgeFiles": false
+  }
+}
+```
+
+---
+
+## 配置管理 (Config)
+
+### configGet - 获取配置
+
+**请求**
+
+```json
+{
+  "type": "configGet",
+  "trace_id": "config-get-001",
+  "data": {}
+}
+```
+
+---
+
+## 会话管理 (Sessions)
+
+### sessionsList - 列出所有会话
+
+**请求**
+
+```json
+{
+  "type": "sessionsList",
+  "trace_id": "sessions-list-001",
+  "data": {}
+}
+```
+
+---
+
+### sessionsGet - 获取会话详情
+
+**说明**
+
+- 支持分页参数 `limit` 和 `offset`。
+- 后端单次最多返回 `100` 条消息。
+
+**请求**
+
+```json
+{
+  "type": "sessionsGet",
+  "trace_id": "sessions-get-001",
+  "data": {
+    "sessionId": "session-123",
+    "limit": 50,
+    "offset": 0
+  }
+}
+```
+
+---
+
+### sessionsPrepareMessage - 准备消息 *
+
+**请求**
+
+```json
+{
+  "type": "sessionsPrepareMessage",
+  "trace_id": "sessions-prepare-001",
+  "data": {
+    "sessionId": "session-123",
+    "message": "Hello, how are you?"
+  }
+}
+```
+
+---
+
+### sessionsAttachSkill - 附加技能 *
+
+**请求**
+
+```json
+{
+  "type": "sessionsAttachSkill",
+  "trace_id": "sessions-attach-001",
+  "data": {
+    "sessionId": "session-123",
+    "skillSlug": "letsping",
+    "message": "按这个 skill 处理"
+  }
+}
+```
+
+---
+
+## 模型管理 (Models)
+
+### 核心规则
+
+调整：模型配置统一收口到 `primary` 和 `models.providers`。
+
+- 当前默认模型只看 `agents.defaults.model.primary`。
+- `primary` 必须传完整 ref：`providerId/modelId`，例如 `custom-dashscope-aliyuncs-com/qwen3.6-flash`。
+- 不再写 `agents.defaults.model.provider`；provider 从 `primary` 的 `/` 前半段派生。
+- custom provider 必须维护在 `models.providers.<providerId>`，否则 `primary` 前缀无法解析到真实接口。
+- `agents.defaults.models` 是可选模型池 / allowlist / alias 表，前端可以用它生成模型下拉。
+- 前端提交完整 ref；展示可以用 alias、`modelOptions[].label`、`modelOptions[].model`，或者只展示 `/` 后半段。
+
+### modelsGet - 获取模型列表
+
+调整：只负责读取当前模型和下拉数据，不写配置。
+
+**什么时候用**
+
+- 页面初始化时获取当前默认模型、模型下拉选项和 provider 配置视图。
+- 前端下拉框优先使用 `data.modelOptions`。
+
+**请求**
+```json
+{
+  "type": "modelsGet",
+  "trace_id": "models-get-001",
+  "data": {}
+}
+```
+
+**前端取值**
+- 当前默认模型：`data.defaults.model.primary`
+- 下拉提交值：`data.modelOptions[].value`
+- 下拉展示名：优先 `data.modelOptions[].label`
+- 只展示模型名：`data.modelOptions[].model`，例如 `qwen3.6-flash`
+- provider 展示：`data.modelOptions[].providerLabel` 或 `data.modelOptions[].provider`
+- `data.defaults.model.provider` 即使返回，也只当派生展示值，不写回配置。
+
+### modelsSet - 只切换默认模型
+
+调整：只写 `agents.defaults.model.primary即可`，`provider` 只做校验 可以不传。
+
+**什么时候用**
+- 用户只是在已有模型列表里切换默认模型。
+- 这是前端模型选择器最常用的切换接口。
+
+**请求**
+```json
+{
+  "type": "modelsSet",
+  "trace_id": "models-set-001",
+  "data": {
+    "primary": "custom-dashscope-aliyuncs-com/qwen3.6-flash"
+  }
+}
+```
+
+**可选 provider 校验**  可以忽略不管
+```json
+{
+  "type": "modelsSet",
+  "trace_id": "models-set-with-provider-001",
+  "data": {
+    "primary": "custom-dashscope-aliyuncs-com/qwen3.6-flash",
+    "provider": "custom-dashscope-aliyuncs-com"
+  }
+}
+```
+
+**行为**
+- 写入：`agents.defaults.model.primary`
+- 不写入：`agents.defaults.model.provider`
+- 如果传了 `provider`，只校验它必须等于 `primary` 的前缀。
+- 如果 `primary` 不在 `agents.defaults.models` allowlist 中，会返回 `MODEL_NOT_ALLOWED`。
+
+### modelsUpdate - 更新 custom provider，可选同时切默认模型
+
+新增 custom provider
+修改 custom provider 的 baseUrl / apiKey / api
+更新 custom provider 的 models[]
+更新 provider 后顺手用 primaryModel 切到这个模型
+
+暂时不要custom provider 就不需要管这个接口
+
+
+调整：主要维护 `models.providers`，需要切模型时传 `primaryModel`。
+
+**什么时候用**
+- 新增或更新 custom provider。
+- 更新 provider 的 base URL、API key、协议类型或模型列表。
+- 需要在更新 provider 后同时切到某个模型。
+
+**只更新 provider**
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-update-provider-001",
+  "data": {
+    "provider": "custom-dashscope-aliyuncs-com",
+    "providerConfig": {
+      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "api": "openai-completions",
+      "apiKey": "YOUR_API_KEY",
+      "models": [
+        {
+          "id": "qwen3.6-flash",
+          "name": "qwen3.6-flash (Custom Provider)"
+        }
+      ]
+    }
+  }
+}
+```
+
+**更新 provider 并切默认模型**
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-update-and-switch-001",
+  "data": {
+    "primaryModel": "custom-dashscope-aliyuncs-com/qwen3.6-flash",
+    "provider": "custom-dashscope-aliyuncs-com",
+    "providerConfig": {
+      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "api": "openai-completions",
+      "apiKey": "YOUR_API_KEY",
+      "models": [
+        {
+          "id": "qwen3.6-flash",
+          "name": "qwen3.6-flash (Custom Provider)"
+        }
+      ]
+    }
+  }
+}
+```
+
+**带 modelProvider 的兼容校验**
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-update-with-model-provider-001",
+  "data": {
+    "primaryModel": "custom-dashscope-aliyuncs-com/qwen3.6-flash",
+    "modelProvider": "custom-dashscope-aliyuncs-com"
+  }
+}
+```
+
+**行为**
+- `provider + providerConfig` 写入并合并到 `models.providers[provider]`。
+- `primaryModel` 写入 `agents.defaults.model.primary`。
+- `modelProvider` 不能单独传；它只在同时传 `primaryModel` 时做兼容校验。
+- 不写入 `agents.defaults.model.provider`。
+
+**providerConfig 允许字段**
+- `apiKey`
+- `api`
+- `baseUrl`
+- `models`
+- `name`
+- `label`
+- `model`
+- `temperature`
+- `maxTokens`
+- `topP`
+- `frequencyPenalty`
+- `presencePenalty`
+
+### agentsUpdate - 切换指定 agent 模型
+
+调整：只允许写 agent 的 `model.primary`，不再写 `model.provider`。
+
+**什么时候用**
+- 只切某个命名 agent 的模型，而不是默认模型。
+
+**请求**
+```json
+{
+  "type": "agentsUpdate",
+  "trace_id": "agent-switch-model-001",
+  "data": {
+    "agentId": "my-agent",
+    "updates": {
+      "model.primary": "custom-dashscope-aliyuncs-com/qwen3.6-flash"
+    }
+  }
+}
+```
+
+**行为**
+- 只能写 `model.primary`。
+- 不能写 `model.provider`。
+
+---
+
+## Mem9 管理 (Mem9)
+
+### mem9Install - 安装并配置 Mem9
+
+**说明**
+- 调用 `openclaw plugins install @mem9/mem9` 安装 Mem9 插件。
+- 调用 `POST https://api.mem9.ai/v1alpha1/mem9s` 创建新的云端 key。
+- 将 `plugins.entries.mem9` 和 `plugins.slots.memory` 写入 `openclaw.json`。
+- 尝试重启 `openclaw-gateway.service`。
+- 已经存在有效的 mem9 key 时，不会重复创建新 key，而是复用现有配置。
+
+**请求**
+```json
+{
+  "type": "mem9Install",
+  "trace_id": "mem9-install-001",
+  "data": {}
+}
+```
+
+**成功响应 data**
+```json
+{
+  "ok": true,
+  "installed": true,
+  "alreadyInstalled": true,
+  "alreadyConfigured": true,
+  "createdNewKey": false,
+  "reusedExistingKey": true,
+  "plugin": "mem9",
+  "apiUrl": "https://api.mem9.ai",
+  "apiKey": "generated-or-existing-id",
+  "updated": [
+    "plugins.entries.mem9",
+    "plugins.slots.memory"
+  ],
+  "restart": {
+    "attempted": true,
+    "success": true
+  }
+}
+```
+
+**幂等行为**
+- 如果 Mem9 已安装且 `plugins.entries.mem9.config.apiKey` 已存在，则直接复用当前 key。
+- 如果 Mem9 已安装但没有 key，则创建新 key 并补齐配置。
+- 如果 Mem9 未安装，则执行完整安装流程。
+
+**错误码**
+- `MEM9_OPENCLAW_NOT_FOUND`
+- `MEM9_NODE_NOT_FOUND`
+- `MEM9_CONFIG_NOT_FOUND`
+- `MEM9_PLUGIN_INSTALL_FAILED`
+- `MEM9_KEY_CREATE_FAILED`
+
+---
+
+### mem9GetConfig - 获取 Mem9 配置
+
+**说明**
+- 返回当前 Mem9 的安装状态、启用状态、`apiUrl`、`apiKey` 和 memory slot。
+- 当前返回 `apiKey` 明文，适合前端直接使用。
+
+**请求**
+```json
+{
+  "type": "mem9GetConfig",
+  "trace_id": "mem9-get-config-001",
+  "data": {}
+}
+```
+
+**成功响应 data**
+```json
+{
+  "ok": true,
+  "installed": true,
+  "configured": true,
+  "plugin": "mem9",
+  "enabled": true,
+  "apiUrl": "https://api.mem9.ai",
+  "apiKey": "4dc48913-d74e-4677-8fed-c2ee41de8d1d",
+  "slot": "mem9"
+}
+```
+
+---
+
+### mem9Reconnect - 替换 Mem9 Key
+
+**说明**
+- 只替换 `plugins.entries.mem9.config.apiKey`。
+- 同时确保 `plugins.entries.mem9.enabled = true` 和 `plugins.slots.memory = "mem9"`。
+- 尝试重启 `openclaw-gateway.service`。
+- 不重新安装 mem9 插件。
+
+**请求**
+```json
+{
+  "type": "mem9Reconnect",
+  "trace_id": "mem9-reconnect-001",
+  "data": {
+    "key": "new-mem9-key"
+  }
+}
+```
+
+**成功响应 data**
+```json
+{
+  "ok": true,
+  "reconnected": true,
+  "replacedExistingKey": true,
+  "plugin": "mem9",
+  "apiUrl": "https://api.mem9.ai",
+  "apiKey": "new-mem9-key",
+  "updated": [
+    "plugins.entries.mem9.config.apiKey"
+  ],
+  "restart": {
+    "attempted": true,
+    "success": true
+  }
+}
+```
+
+**错误码**
+- `MEM9_KEY_REQUIRED`
+- `MEM9_CONFIG_NOT_FOUND`
+- `MEM9_RESTART_FAILED`
+
+---
+
+## 使用统计 (Usage)
+
+### usageSummary - 获取使用统计摘要
+
+**请求**
+```json
+{
+  "type": "usageSummary",
+  "trace_id": "usage-summary-001",
+  "data": {}
+}
+```
+
+---
+
+### usagePageSummary - 获取页面使用统计
+
+**说明**
+- 用途：获取一个完整的使用统计概览页面，包含多个维度的汇总数据。
+- 返回内容：
+  - `totals` - 总体统计指标（token、成本、消息数等）
+  - `topModels` - 使用最多的前 10 个模型排行
+  - `topProviders` - 使用最多的前 10 个提供商排行
+  - `topTools` - 使用最多的前 10 个工具排行
+  - `topAgents` - 使用最多的前 10 个代理排行
+  - `topChannels` - 使用最多的前 10 个渠道排行
+  - `sessions` - 会话列表
+  - `meta` - 元数据（扫描的会话数、数据源等）
+
+**请求**
+```json
+{
+  "type": "usagePageSummary",
+  "trace_id": "usage-page-001",
+  "data": {}
+}
+```
+
+---
+
+### usageTimeseries - 获取时间序列数据
+
+**说明**
+- 用途：获取按时间分组的使用数据，用于绘制趋势图表。
+- 参数：
+  - `granularity` - 时间粒度（`day` / `hour` / `week` 等）
+- 返回内容：
+  - `series` - 时间序列数组，每个元素表示一个时间桶
+    - `ts` - 当前时间桶的起始时间
+    - `messages` - 当前时间桶内的消息数
+    - `sessions` - 当前时间桶内涉及的会话数
+    - `inputTokens` - 当前时间桶内输入 token 总数
+    - `outputTokens` - 当前时间桶内输出 token 总数
+    - `cacheReadTokens` - 当前时间桶内缓存读取 token 总数
+    - `cacheWriteTokens` - 当前时间桶内缓存写入 token 总数
+    - `totalTokens` - 当前时间桶内总 token 数
+    - `totalCostUsd` - 当前时间桶内总成本
+    - `toolCalls` - 当前时间桶内工具调用次数
+    - `errors` - 当前时间桶内错误次数
+    - `avgTokensPerMessage` - 当前时间桶内平均每条消息的 token 数
+    - `throughputTokPerMin` - 当前时间桶内折算的 token 吞吐量（token/分钟）
+
+**请求**
+```json
+{
+  "type": "usageTimeseries",
+  "trace_id": "usage-timeseries-001",
+  "data": {
+    "granularity": "day"
+  }
+}
+```
+
+---
+
+### usageBreakdown - 获取使用明细 
+
+**说明**
+- 参数：
+  - `dimension` - 分组维度（`model` / `provider` / `agent` / `channel` / `tool`）
+  - `limit` - 返回前 N 条记录（默认 20）
+  - `sortBy` - 排序字段（`totalTokens` / `totalCostUsd` 等）
+  - `order` - 排序方向（`asc` / `desc`）
+- 返回内容：
+  - `rows` - 按维度分组的统计行，每行包含：
+    - 维度值（例如具体的模型名）
+    - 该维度的使用统计（token、成本、消息数等）
+    - 占总量的百分比
+
+**请求**
+```json
+{
+  "type": "usageBreakdown",
+  "trace_id": "usage-breakdown-001",
+  "data": {
+    "dimension": "model"
+  }
+}
+```
+
+---
+
+## 技能管理 (Skills)
+
+**说明**
+- 所有技能相关操作统一使用 `slug`，不要使用 `skillId`。
+
+### skillsListInstalled - 列出已安装技能
+
+**请求**
+```json
+{
+  "type": "skillsListInstalled",
+  "trace_id": "skills-list-001",
+  "data": {}
+}
+```
+
+---
+
+### skillsInstallFromNpm - 从 NPM 安装技能
+
+**请求**
+
+```json
+{
+  "type": "skillsInstallFromNpm",
+  "trace_id": "skills-install-001",
+  "data": {
+    "package": "@openclaw/skill-example",
+    "scope": "global"
+  }
+}
+```
+
+---
+
+### skillsSearchClawHub - 搜索 ClawHub 技能
+
+**说明**
+- 调用 OpenClaw CLI 执行 `openclaw skills search`。
+- `query` 可选；不传时返回默认搜索结果，具体结果取决于 OpenClaw CLI。
+
+**请求**
+
+```json
+{
+  "type": "skillsSearchClawHub",
+  "trace_id": "skills-search-clawhub-001",
+  "data": {
+    "query": "browser"
+  }
+}
+```
+
+---
+
+### skillsInstallFromClawHub - 从 ClawHub 安装技能
+
+**说明**
+- 调用 OpenClaw CLI 执行 `openclaw skills install <slug>`。
+- 安装后如需启用，继续调用 `skillsToggle`。
+
+**请求**
+```json
+{
+  "type": "skillsInstallFromClawHub",
+  "trace_id": "skills-install-clawhub-001",
+  "data": {
+    "slug": "browser"
+  }
+}
+```
+
+---
+
+### skillsUpdateFromClawHub - 更新 ClawHub 技能
+
+**说明**
+- 调用 OpenClaw CLI 执行 `openclaw skills update <slug>`。
+
+**请求**
+```json
+{
+  "type": "skillsUpdateFromClawHub",
+  "trace_id": "skills-update-clawhub-001",
+  "data": {
+    "slug": "browser"
+  }
+}
+```
+
+---
+
+### skillsGetInstalled - 获取已安装技能详情
+
+**请求**
+```json
+{
+  "type": "skillsGetInstalled",
+  "trace_id": "skills-get-001",
+  "data": {
+    "slug": "letsping"
+  }
+}
+```
+
+---
+
+### skillsUninstall - 卸载技能 * 
+
+**请求**
+```json
+{
+  "type": "skillsUninstall",
+  "trace_id": "skills-uninstall-001",
+  "data": {
+    "slug": "letsping",
+    "scope": "global"
+  }
+}
+```
+
+---
+
+### skillsToggle - 启用/停用技能
+
+**请求**
+
+```json
+{
+  "type": "skillsToggle",
+  "trace_id": "skills-toggle-001",
+  "data": {
+    "slug": "letsping",
+    "enabled": true
+  }
+}
+```
+
+---
+
+## 记忆管理 (Memory) 
+
+**说明**
+- 当前备份/恢复白名单固定为：
+  - `openclaw.json`
+  - `workspace/AGENTS.md`
+  - `workspace/HEARTBEAT.md`
+  - `workspace/IDENTITY.md`
+  - `workspace/MEMORY.md`
+  - `workspace/SoUL.md`
+  - `workspace/TooLS.md`
+  - `workspace/USER.md`
+  - `credentials/*`
+- 不在上述范围内的文件不会进入备份，也不会参与恢复。
+
+### memoryListFiles - 列出记忆文件
+
+**请求**
+```json
+{
+  "type": "memoryListFiles",
+  "trace_id": "memory-list-001",
+  "data": {}
+}
+```
+
+---
+
+### memoryGetFile - 获取记忆文件
+
+**请求**
+```json
+{
+  "type": "memoryGetFile",
+  "trace_id": "memory-get-001",
+  "data": {
+    "path": "workspace/MEMORY.md"
+  }
+}
+```
+
+---
+
+### memoryBackup - 创建备份快照 *
+
+**请求**
+```json
+{
+  "type": "memoryBackup",
+  "trace_id": "memory-backup-001",
+  "data": {}
+}
+```
+
+---
+
+### memoryExportZip - 导出 ZIP
+
+**请求**
+
+```json
+{
+  "type": "memoryExportZip",
+  "trace_id": "memory-export-001",
+  "data": {}
+}
+```
+
+---
+
+### memoryGetPresignedPost - 获取预签名上传参数
+
+**请求**
+```json
+{
+  "type": "memoryGetPresignedPost",
+  "trace_id": "memory-presigned-001",
+  "data": {
+    "body": {
+      "file_name": "memory-backup-2026-04-17.zip",
+      "dir": "memory/2026/04/17/"
+    }
+  }
+}
+```
+
+---
+
+### memoryCreateBackupRecord - 创建备份记录
+
+**请求**
+
+```json
+{
+  "type": "memoryCreateBackupRecord",
+  "trace_id": "memory-backup-record-001",
+  "data": {
+    "body": {
+      "user_id": 1,
+      "source_file_key": "memory/2026/04/17/memory-backup-2026-04-17.zip",
+      "source_file_name": "memory-backup-2026-04-17.zip",
+      "source_file_url": "https://example-bucket.s3.amazonaws.com/memory/2026/04/17/memory-backup-2026-04-17.zip",
+      "backup_location": "s3",
+      "remark": "OpenClaw memory backup",
+      "extend_json": {
+        "upload_dir": "memory/2026/04/17/"
+      }
+    }
+  }
+}
+```
+
+---
+
+### memoryImportZip - 导入 ZIP
+
+**说明**
+- 同一个 `type` 同时支持：
+  - 全量恢复：不传 `includePaths`
+  - 指定文件恢复：传 `includePaths`
+
+**请求**
+
+```json
+{
+  "type": "memoryImportZip",
+  "trace_id": "memory-import-001",
+  "data": {
+    "zipPath": "path/to/backup.zip",
+    "createBackup": true,
+    "includePaths": [
+      "openclaw.json",
+      "workspace/MEMORY.md",
+      "credentials/"
+    ]
+  }
+}
+```
+
+---
+
+## 其他消息类型
+
+**说明**
+- `ping`、`status`、`echo` 是基础调试类消息。
+- `systemRestart`、`systemStop`、`systemDoctorFix`、`systemLogs` 这类系统运维命令联调前建议先实际调用确认一次。
+
+### ping - 健康检查
+
+**请求**
+
+```json
+{
+  "type": "ping",
+  "trace_id": "ping-001",
+  "data": {}
+}
+```
+
+---
+
+### status - 获取状态
+
+**请求**
+```json
+{
+  "type": "status",
+  "trace_id": "status-001",
+  "data": {}
+}
+```
+
+---
+
+### echo - 回显测试
+
+**请求**
+```json
+{
+  "type": "echo",
+  "trace_id": "echo-001",
+  "data": {
+    "message": "test"
+  }
+}
+```
+
+---
+
+## 消息类型快速索引
+
+### 系统管理
+- `systemRestart`
+- `systemStop`
+- `systemDoctorFix`
+- `systemLogs`
+- `openclawUpdate`
+- `pluginSelfUpdate`
+- `systemCurrentVersion`
+- `ping`
+- `status`
+- `echo`
+
+### 代理管理
+- `agentsGet`
+- `agentsList`
+- `agentsCreate`
+- `agentsUpdate`
+- `agentsDelete`
+
+### 配置管理
+- `configGet`
+
+### 会话管理
+- `sessionsList`
+- `sessionsGet`
+- `sessionsPrepareMessage`
+- `sessionsAttachSkill`
+
+### 模型管理
+- `modelsGet`
+- `modelsSet`
+- `modelsUpdate`
+
+### Mem9 管理
+- `mem9Install`
+- `mem9GetConfig`
+- `mem9Reconnect`
+
+### 使用统计
+- `usageSummary`
+- `usagePageSummary`
+- `usageTimeseries`
+- `usageBreakdown`
+
+### 技能管理
+- `skillsListInstalled`
+- `skillsInstallFromNpm`
+- `skillsSearchClawHub`
+- `skillsInstallFromClawHub`
+- `skillsUpdateFromClawHub`
+- `skillsGetInstalled`
+- `skillsUninstall`
+- `skillsToggle`
+
+### 记忆管理
+- `memoryListFiles`
+- `memoryGetFile`
+- `memoryBackup`
+- `memoryExportZip`
+- `memoryGetPresignedPost`
+- `memoryCreateBackupRecord`
+- `memoryImportZip`
+
+---
+
+## Cron
+
+### cronList
+
+列出 cron 任务列表。
+
+**请求**
+```json
+{
+  "type": "cronList",
+  "trace_id": "cron-list-001",
+  "data": {}
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "list"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronStatus
+
+获取 cron 服务状态。
+
+**请求**
+```json
+{
+  "type": "cronStatus",
+  "trace_id": "cron-status-001",
+  "data": {}
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "status"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronRuns
+
+获取指定 cron 任务的运行记录。
+
+**请求**
+```json
+{
+  "type": "cronRuns",
+  "trace_id": "cron-runs-001",
+  "data": {
+    "id": "cron-id",
+    "limit": 10
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "runs", "--id", "cron-id", "--limit", "10"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronAdd
+
+新增 cron 任务。
+
+**请求 isolated**
+```json
+{
+  "type": "cronAdd",
+  "trace_id": "cron-add-001",
+  "data": {
+    "name": "test isolated message",
+    "every": "5m",
+    "session": "isolated",
+    "message": "帮我检查一下当前状态"
+  }
+}
+```
+
+**请求 main**
+```json
+{
+  "type": "cronAdd",
+  "trace_id": "cron-add-002",
+  "data": {
+    "name": "test main event",
+    "cron": "*/10 * * * *",
+    "session": "main",
+    "systemEvent": "cron_tick"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "add", "--name", "test isolated message", "--every", "5m", "--session", "isolated", "--message", "帮我检查一下当前状态"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronRename
+
+修改 cron 任务名称或描述。
+
+**请求**
+```json
+{
+  "type": "cronRename",
+  "trace_id": "cron-rename-001",
+  "data": {
+    "id": "cron-id",
+    "name": "new cron name",
+    "description": "new description"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "edit", "cron-id", "--name", "new cron name", "--description", "new description"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronReschedule
+
+修改 cron 任务调度时间。
+
+**请求**
+```json
+{
+  "type": "cronReschedule",
+  "trace_id": "cron-reschedule-001",
+  "data": {
+    "id": "cron-id",
+    "every": "10m"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "edit", "cron-id", "--every", "10m"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronUpdateMessage （isolate）
+
+修改独立（isolate）任务内容。
+
+**请求**
+```json
+{
+  "type": "cronUpdateMessage",
+  "trace_id": "cron-message-001",
+  "data": {
+    "id": "cron-id",
+    "message": "新的任务内容"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "edit", "cron-id", "--session", "isolated", "--message", "新的任务内容"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronUpdateSystemEvent (main)
+
+修改主会话系统事件。（main）在main里执行定时任务
+
+**请求**
+```json
+{
+  "type": "cronUpdateSystemEvent",
+  "trace_id": "cron-event-001",
+  "data": {
+    "id": "cron-id",
+    "systemEvent": "cron_tick_updated"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "edit", "cron-id", "--session", "main", "--system-event", "cron_tick_updated"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronSetContent
+
+按 session 修改任务内容。isolated 定时任务的结果会单开一个聊天框（没有上下文 ）
+
+**请求**
+```json
+{
+  "type": "cronSetContent",
+  "trace_id": "cron-content-001",
+  "data": {
+    "id": "cron-id",
+    "session": "isolated",
+    "message": "新的任务内容"
+  }
+}
+```
+
+**响应 data**
+
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "edit", "cron-id", "--session", "isolated", "--message", "新的任务内容"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronEnable
+
+启用 cron 任务。
+
+**请求**
+```json
+{
+  "type": "cronEnable",
+  "trace_id": "cron-enable-001",
+  "data": {
+    "id": "cron-id"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "enable", "cron-id"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronDisable
+
+停用 cron 任务。
+
+**请求**
+```json
+{
+  "type": "cronDisable",
+  "trace_id": "cron-disable-001",
+  "data": {
+    "id": "cron-id"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "disable", "cron-id"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronRun
+
+立即运行 cron 任务。
+
+**请求**
+```json
+{
+  "type": "cronRun",
+  "trace_id": "cron-run-001",
+  "data": {
+    "id": "cron-id"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "run", "cron-id"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+### cronRemove
+
+删除 cron 任务。
+
+**请求**
+```json
+{
+  "type": "cronRemove",
+  "trace_id": "cron-remove-001",
+  "data": {
+    "id": "cron-id"
+  }
+}
+```
+
+**响应 data**
+```json
+{
+  "ok": true,
+  "command": "openclaw",
+  "args": ["cron", "rm", "cron-id"],
+  "stdout": "",
+  "stderr": "",
+  "parsed": null
+}
+```
+
+---
+
+**错误响应**  表示当前运行环境里找不到 `openclaw` 这个可执行文件
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "cron-add-001",
+  "source": "system",
+  "timestamp": 1776331005170,
+  "success": false,
+  "error": "OpenClaw cron command failed: spawn openclaw ENOENT"
+}
+```
+
+## Pairing Endpoint 线上/线下切换
+
+### 实际操作区别
+
+**线上用户安装/配对**
+
+插件不再读取 `DEOTALAND_API_BASE_URL` 环境变量。用户正常安装后，只要发起配对，不传任何 endpoint，就固定走生产接口：
+
+```txt
+https://api.deotaland.ai/api-core-bot/front/agent/agent/key/query
+```
+
+线上用户不需要设置环境变量，也不会因为 `process.env` 读取被新版 OpenClaw 安全扫描拦截。
+
+**本地/测试环境配对**
+
+不要再用环境变量切换：
+
+```bash
+DEOTALAND_API_BASE_URL=https://api.deotaland.ai
+```
+
+改成显式传参：
+
+```bash
+openclaw admin-bridge pair <key> --endpoint https://api.deotaland.ai
+```
+
+实际请求会变成：
+
+```txt
+https://api.deotaland.ai/api-core-bot/front/agent/agent/key/query
+```
+
+如果传完整接口 URL，插件会直接使用该 URL：
+
+```bash
+openclaw admin-bridge pair <key> --endpoint https://api.deotaland.ai/api-core-bot/front/agent/agent/key/query
+```
+
+**长期固定测试环境** （尽量 用--endpoint的方式）
+
+如果不想每次都传 `--endpoint`，可以在 `openclaw.json` 里配置：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "rol-websocket-channel": {
+        "config": {
+          "pairingEndpoint": "https://api.deotaland.ai"
+        }
+      }
+    }
+  }
+}
+```
+
+之后配对时不传 `--endpoint`，就会走 `pairingEndpoint`。
+
+**临时覆盖**
+
+如果 `openclaw.json` 里配置了 staging，但某次想临时走线上，可以传：
+
+```bash
+openclaw admin-bridge pair <key> --endpoint https://api.deotaland.ai
+```
+
+当前优先级是：
+
+```txt
+--endpoint 参数 > openclaw.json pairingEndpoint > 默认生产地址
+```
+
+命令参数永远是调用最高优先级。
+```
+
+如果要走测试环境，可以在 `data` 里带 endpoint：
+
+
+实际效果是：线上默认更安全，线下切环境更显式，安装器不再因为环境变量读取拦截 pairing 文件。
+
+---
+
+```
+```
+
+## Artifacts 文件下载（按需上传对象存储）
+
+如果文件之前已经上传过，则不会重复上传，而是直接复用已有 `fileUrl`。
+
+### Markdown 文件规则
+
+- 第一次扫描时，已有 `.md` 文件会作为基线记录，不会展示在 artifacts 列表里。
+- 后续新生成的 `.md` 文件会进入 artifacts 列表。
+- `MEMORY.md`、`SoUL.md`、`AGENTS.md`、`HEARTBEAT.md`、`IDENTITY.md`、`TooLS.md`、`USER.md` 等记忆/身份文件永远不会展示。
+
+
+
+
+### 下载前先获取列表
+
+建议前端不要直接拿路径去调下载，而是先调用一次 `artifactsList`，确认当前可下载文件的 `artifactId`、`relativePath`、`storageStatus`。
+
+MQTT 请求示例：
+
+​```json
+{
+  "type": "artifactsList",
+  "trace_id": "artifact-list-before-download-001",
+  "data": {}
+}
+```
+
+典型顺序：
+
+1. `artifactsList`    
+
+   {
+     "type": "artifactsList",
+     "trace_id": "artifact-list-before-download-001",
+     "data": {}
+   }
+
+2. 用户选择某个文件
+
+3. `artifactsEnsureUploaded`
+
+4. 使用返回的 `downloadUrl`
+
+
+
+### MQTT 请求示例
+
+```json
+{
+  "type": "artifactsEnsureUploaded",
+  "trace_id": "artifact-download-006",
+  "data": {
+    "baseUrl": "http://api.deotaland.local",
+    "authToken": "123",
+    "relativePath": "me.pdf",
+    "presignedPostBody": {
+      "dir": "artifacts/"
+    }
+  }
+}
+```
+
+### 成功返回示例
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "artifact-download-006",
+  "source": "system",
+  "timestamp": 1777364603366,
+  "success": true,
+  "data": {
+    "ok": true,
+    "scope": "workspace",
+    "uploaded": true,
+    "artifactId": "art_fe4672f1badd",
+    "objectKey": "uploads/666ff786-9d01-4159-b4ae-338f385d6ae2.pdf",
+    "downloadUrl": "https://draft-user.s3.us-east-2.amazonaws.com/uploads/666ff786-9d01-4159-b4ae-338f385d6ae2.pdf"
+  }
+}
+```
+
+### 前端使用方式
+
+1. 调 `artifactsList` 获取文件列表
+2. 用户点击下载时，调 `artifactsEnsureUploaded`
+3. 直接使用返回的 `data.downloadUrl`
+4. 如果返回 `uploaded: false`，表示这次没有重新上传，而是复用了历史上传结果
+
+展示建议：
+
+- `category === "image"` 时，可以作为图片预览/展示。
+- `category === "document"` 时，可以作为文档展示或下载。
+- `storageStatus === "local_only"` 时，先调 `artifactsEnsureUploaded` 获取可访问的 `downloadUrl`。
+- `storageStatus === "uploaded"` 且 `fileUrl` 存在时，可以直接使用 `fileUrl` 展示或下载。
+
+---
+
+## System 更新接口
+
+这两个接口用于 App 按钮触发本机 OpenClaw 或当前插件更新。请求通过 MQTT 发送到当前已配对设备，插件会在本机执行对应的 `openclaw` 命令。
+
+### openclawUpdate
+
+作用：升级本机 OpenClaw。
+
+实际执行命令：
+
+```bash
+npm install -g @openclaw/core@2026.5.6
+openclaw --version
+openclaw doctor --deep
+```
+
+MQTT 请求示例：
+
+```json
+{
+  "type": "openclawUpdate",
+  "trace_id": "openclaw-update-001",
+  "data": {}
+}
+```
+
+成功返回示例：
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "openclaw-update-001",
+  "source": "system",
+  "success": true,
+  "data": {
+    "ok": true,
+    "action": "openclawUpdate",
+    "targetPackage": "@openclaw/core",
+    "targetVersion": "2026.5.6",
+    "restartRecommended": true,
+    "steps": [
+      {
+        "name": "installCore",
+        "command": "npm",
+        "args": ["install", "-g", "@openclaw/core@2026.5.6"],
+        "cwd": "/home/woowonjae/.openclaw",
+        "stdout": "...",
+        "stderr": ""
+      },
+      {
+        "name": "version",
+        "command": "openclaw",
+        "args": ["--version"],
+        "cwd": "/home/woowonjae/.openclaw",
+        "stdout": "OpenClaw 2026.5.6 ...",
+        "stderr": ""
+      },
+      {
+        "name": "doctorDeep",
+        "command": "openclaw",
+        "args": ["doctor", "--deep"],
+        "cwd": "/home/woowonjae/.openclaw",
+        "stdout": "...",
+        "stderr": ""
+      }
+    ]
+  }
+}
+```
+
+### pluginSelfUpdate
+
+作用：升级当前 `rol-websocket-channel` 插件。
+
+实际执行命令：
+
+```bash
+openclaw plugins update rol-websocket-channel
+```
+
+MQTT 请求示例：
+
+```json
+{
+  "type": "pluginSelfUpdate",
+  "trace_id": "plugin-self-update-001",
+  "data": {}
+}
+```
+
+成功返回示例：
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "plugin-self-update-001",
+  "source": "system",
+  "success": true,
+  "data": {
+    "ok": true,
+    "action": "pluginSelfUpdate",
+    "plugin": "rol-websocket-channel",
+    "restartRecommended": true,
+    "command": "openclaw",
+    "args": ["plugins", "update", "rol-websocket-channel"],
+    "cwd": "/home/woowonjae/.openclaw",
+    "stdout": "...",
+    "stderr": ""
+  }
+}
+```
+
+### 失败返回
+
+如果本机命令执行失败，`success` 会是 `false`，错误信息里会带上实际执行的命令、参数、工作目录、`stdout` 和 `stderr`，前端可以直接展示 `error.message` 或 `error.stderr`。
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "plugin-self-update-001",
+  "source": "system",
+  "success": false,
+  "error": {
+    "message": "OpenClaw system command failed: Command failed: openclaw plugins update rol-websocket-channel",
+    "action": "pluginSelfUpdate",
+    "command": "openclaw",
+    "args": ["plugins", "update", "rol-websocket-channel"],
+    "cwd": "/home/woowonjae/.openclaw",
+    "stdout": "...",
+    "stderr": "..."
+  }
+}
+```
+
+---
+
+## apiCoreBot 配置与 Artifact 发布（新增 configSetApiCoreBot；上传链接可返回会话）
+
+### configSetApiCoreBot
+
+作用：前端在需要开启文件上传/下载链接能力时主动调用，写入当前插件的 `apiCoreBot` 配置。这个配置不是配对时写入，只有收到该 MQTT 消息后才会更新 `openclaw.json`。
+
+写入位置：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "rol-websocket-channel": {
+        "config": {
+          "apiCoreBot": {
+            "baseUrl": "http://192.168.1.23:9092",
+            "authToken": "123"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+默认值：
+
+- `baseUrl`: `http://192.168.1.23:9092`
+- `authToken`: `123`
+
+MQTT 请求示例：
+
+```json
+{
+  "type": "configSetApiCoreBot",
+  "trace_id": "config-api-core-bot-001",
+  "data": {}
+}
+```
+
+如果前端需要覆盖默认值，也可以显式传入：
+
+```json
+{
+  "type": "configSetApiCoreBot",
+  "trace_id": "config-api-core-bot-002",
+  "data": {
+    "baseUrl": "http://192.168.1.23:9092",
+    "authToken": "123"
+  }
+}
+```
+
+成功返回示例：
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "config-api-core-bot-001",
+  "source": "system",
+  "success": true,
+  "data": {
+    "ok": true,
+    "configFile": "/home/woowonjae/.openclaw/openclaw.json",
+    "updated": [
+      "plugins.entries.rol-websocket-channel.config.apiCoreBot.baseUrl",
+      "plugins.entries.rol-websocket-channel.config.apiCoreBot.authToken"
+    ],
+    "apiCoreBot": {
+      "baseUrl": "http://192.168.1.23:9092",
+      "authToken": "********"
+    }
+  }
+}
+```
+
+### Artifact 发布链路
+
+`configSetApiCoreBot` 写入成功后，Artifact 发布方法会从 `openclaw.json` 读取 `apiCoreBot.baseUrl` 和 `apiCoreBot.authToken`，再调用上传接口。小龙虾会话如果调用插件工具 `rol_artifacts_publish`，成功后会拿到可返回给用户的下载链接。
+
+成功返回中的核心字段：
+
+```json
+{
+  "ok": true,
+  "uploaded": true,
+  "artifactId": "art_91f6d03e144c",
+  "objectKey": "uploads/91a78677-5e79-4259-a28d-fa01f24d4848.svg",
+  "downloadUrl": "https://draft-user.s3.us-east-2.amazonaws.com/uploads/91a78677-5e79-4259-a28d-fa01f24d4848.svg"
+}
+```
+
+注意：
+
+- 如果没有先调用 `configSetApiCoreBot`，发布时可能返回 `apiCoreBot.baseUrl is not configured`。
+- `authToken` 在返回值中会脱敏显示，实际写入 `openclaw.json` 的值是 `123` 或前端传入的值。
+- 生成文件本身仍然在 `.openclaw/workspace` 下，上传只在发布/下载链路触发时执行。
+---
+
+## Version Management
+
+查询本机版本并与期望版本比对，告知前端哪些组件需要升级。
+
+### systemCurrentVersion
+
+**说明**
+- 查询本机 OpenClaw 版本和 channel 插件版本，与期望版本比对。
+- openclaw 期望版本：插件内硬编码常量（当前 `2026.5.6`）。
+- channel 期望版本：`npm view rol-websocket-channel --json` 从 npm registry 获取最新发布版本。
+- `npm view` 失败时回退到硬编码 `1.5.9`，不阻塞接口。
+- `currentVersion !== latestVersion` → `status: "outdated"`，相等 → `status: "current"`。
+- 前端只需看 `targets` 里的 `status`，哪个 `"outdated"` 就调对应的升级接口。
+
+**前端升级流程**
+1. 调 `systemCurrentVersion`
+2. `channel` 是 `outdated` → 调 `pluginSelfUpdate`
+3. `openclaw` 是 `outdated` → 调 `openclawUpdate`
+4. 升完重启
+
+**请求**
+```json
+{
+  "type": "systemCurrentVersion",
+  "trace_id": "system-current-version-001",
+  "data": {}
+}
+```
+
+**成功返回示例（需要升级）**
+```json
+{
+  "type": "receiver",
+  "trace_id": "system-current-version-001",
+  "source": "system",
+  "success": true,
+  "data": {
+    "ok": true,
+    "action": "currentVersion",
+    "checkOnly": true,
+    "targets": [
+      {
+        "name": "openclaw",
+        "packageName": "openclaw",
+        "currentVersion": "2026.5.5",
+        "latestVersion": "2026.5.6",
+        "status": "outdated"
+      },
+      {
+        "name": "channel",
+        "packageName": "rol-websocket-channel",
+        "currentVersion": "1.4.8",
+        "latestVersion": "1.5.9",
+        "status": "outdated"
+      }
+    ],
+    "upgradeOrder": ["openclaw", "channel"],
+    "restartRecommended": true
+  }
+}
+```
+
+**成功返回示例（全部最新）**
+```json
+{
+  "type": "receiver",
+  "trace_id": "system-current-version-001",
+  "source": "system",
+  "success": true,
+  "data": {
+    "ok": true,
+    "action": "currentVersion",
+    "checkOnly": true,
+    "targets": [
+      {
+        "name": "openclaw",
+        "packageName": "openclaw",
+        "currentVersion": "2026.5.6",
+        "latestVersion": "2026.5.6",
+        "status": "current"
+      },
+      {
+        "name": "channel",
+        "packageName": "rol-websocket-channel",
+        "currentVersion": "1.5.9",
+        "latestVersion": "1.5.9",
+        "status": "current"
+      }
+    ],
+    "upgradeOrder": [],
+    "restartRecommended": false
+  }
+}
+```
+
+**失败返回**
+```json
+{
+  "type": "receiver",
+  "trace_id": "system-current-version-001",
+  "source": "system",
+  "success": false,
+  "error": {
+    "message": "OpenClaw system command failed: spawn openclaw ENOENT",
+    "action": "currentVersion.openclaw",
+    "command": "openclaw",
+    "args": ["--version"],
+    "cwd": "/home/woowonjae/.openclaw",
+    "stdout": "",
+    "stderr": ""
+  }
+}
+```
+
+JSON-RPC method name: `system.currentVersion`