rol-websocket-channel 1.0.7 → 1.0.9

package/MQTT-API /345/256/232/346/227/266/344/273/273/345/212/241/346/233/264/346/226/260.md"

@@ -0,0 +1,1656 @@
+# 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 条日志。
+```
+
+---
+
+## 代理管理 (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"
+  }
+}
+```
+
+---
+
+### agentsUpdate - 更新代理
+
+**说明**
+- 使用 `agentId` 指定要修改的代理。
+- 不传 `agentId` 时，默认更新 `defaults`。
+- `updates` 目前只支持这些字段：
+  - `name`
+  - `workspace`
+  - `agentDir`
+  - `model.primary`
+  - `model.provider`
+  - `skills`
+  - `tools.profile`
+  - `behavior`
+
+**请求**
+
+```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)
+
+### modelsGet - 获取模型列表
+
+**说明**
+- 返回默认模型、所有 agent 的模型配置视图、模型下拉选项、模型配置模式，以及脱敏后的 provider 配置。
+- 前端模型选择器使用 `modelOptions[]`。展示 `label`，提交 `value` 和 `provider`。
+- `modelOptions[]` 优先从 `agents.defaults.models` 生成；如果没有配置，会从 `agents.defaults.model` 和 `agents.list[].model` 中收集当前已使用的模型作为兜底选项。
+- `configuredProviders` 是脱敏后的 provider 原始配置，普通模型选择器不需要使用它。
+
+**请求**
+```json
+{
+  "type": "modelsGet",
+  "trace_id": "models-get-001",
+  "data": {}
+}
+```
+
+**响应**
+```json
+{
+  "sourceConfigFile": "/home/woowonjae/.openclaw/openclaw.json",
+  "defaults": {
+    "model": {
+      "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+      "provider": "custom-dashscope-aliyuncs-com"
+    },
+    "models": {
+      "custom-dashscope-aliyuncs-com/qwen-plus": {
+        "alias": "Qwen Plus"
+      }
+    }
+  },
+  "agents": [
+    {
+      "id": "defaults",
+      "name": "defaults",
+      "model": {
+        "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+        "provider": "custom-dashscope-aliyuncs-com"
+      }
+    }
+  ],
+  "modelOptions": [
+    {
+      "label": "Qwen Plus",
+      "value": "custom-dashscope-aliyuncs-com/qwen-plus",
+      "provider": "custom-dashscope-aliyuncs-com",
+      "providerLabel": "Dashscope Aliyuncs Com",
+      "model": "qwen-plus"
+    }
+  ],
+  "modelConfigMode": "merge",
+  "configuredProviders": {}
+}
+```
+
+**前端使用方式**
+- 默认模型：读取 `data.defaults.model.primary`。
+- 默认 provider：读取 `data.defaults.model.provider`；如果为空，可以从选中的 `modelOptions[].provider` 获取。
+- 模型下拉框：使用 `data.modelOptions`。
+- agent 模型列表：使用 `data.agents[]`。
+
+---
+
+### modelsSet - 切换默认模型
+
+**说明**
+- 前端模型选择器切换默认模型时使用这个接口。
+- `primary` 是唯一主字段，必须是完整的 `providerId/modelName`。
+- `provider` 是可选字段，只用于校验；如果传入，必须与 `primary` 的 provider 部分一致。
+- 后端写入 `agents.defaults.model.primary`，并从 `primary` 派生写入 `agents.defaults.model.provider`。
+- `primary` 必须存在于 `agents.defaults.models` 白名单中；如果没有配置白名单，则只允许设置当前已使用过的模型。
+
+**推荐配置**
+```json
+{
+  "models": {
+    "mode": "merge",
+    "providers": {
+      "custom-dashscope-aliyuncs-com": {
+        "label": "通义千问 DashScope",
+        "apiKey": "YOUR_DASHSCOPE_API_KEY",
+        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+      },
+      "custom-openai": {
+        "label": "OpenAI",
+        "apiKey": "YOUR_OPENAI_API_KEY",
+        "baseUrl": "https://api.openai.com/v1"
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+        "provider": "custom-dashscope-aliyuncs-com"
+      },
+      "models": {
+        "custom-dashscope-aliyuncs-com/qwen-plus": {
+          "alias": "Qwen Plus"
+        },
+        "custom-dashscope-aliyuncs-com/qwen-max": {
+          "alias": "Qwen Max"
+        },
+        "custom-openai/gpt-4.1": {
+          "alias": "GPT-4.1"
+        }
+      }
+    },
+    "list": [
+      {
+        "id": "openai-agent",
+        "name": "OpenAI Agent",
+        "model": {
+          "primary": "custom-openai/gpt-4.1",
+          "provider": "custom-openai"
+        }
+      }
+    ]
+  }
+}
+```
+
+**请求**
+```json
+{
+  "type": "modelsSet",
+  "trace_id": "models-set-001",
+  "data": {
+    "primary": "custom-dashscope-aliyuncs-com/qwen-plus"
+  }
+}
+```
+
+**带 provider 校验的请求** 测试
+```json
+{
+  "type": "modelsSet",
+  "trace_id": "models-set-with-provider-001",
+  "data": {
+    "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+    "provider": "custom-dashscope-aliyuncs-com"
+  }
+}
+```
+
+**成功响应 data**
+```json
+{
+  "ok": true,
+  "model": {
+    "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+    "provider": "custom-dashscope-aliyuncs-com"
+  },
+  "defaults": {
+    "model": {
+      "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+      "provider": "custom-dashscope-aliyuncs-com"
+    }
+  }
+}
+```
+
+**错误规则**
+- `MODEL_PRIMARY_REQUIRED`：缺少 `primary`。
+- `MODEL_PRIMARY_INVALID`：`primary` 不是 `provider/model` 格式。
+- `MODEL_NOT_ALLOWED`：`primary` 不在允许的模型选项中。
+- `MODEL_PROVIDER_MISMATCH`：传入的 `provider` 与 `primary` 不一致。
+
+---
+
+### modelsUpdate - 更新 provider 配置
+
+**说明**
+- 用于更新 `models.providers[provider]`。
+- 不建议用它做前端模型下拉切换；默认模型切换请使用 `modelsSet`。
+- `providerConfig` 会合并到已有 provider 配置中。
+
+**请求**
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-update-provider-001",
+  "data": {
+    "provider": "custom-dashscope-aliyuncs-com",
+    "providerConfig": {
+      "apiKey": "YOUR_API_KEY",
+      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+    }
+  }
+}
+```
+
+**切换指定 agent 模型**
+```json
+{
+  "type": "agentsUpdate",
+  "trace_id": "agent-switch-model-001",
+  "data": {
+    "agentId": "my-agent",
+    "updates": {
+      "model.primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+      "model.provider": "custom-dashscope-aliyuncs-com"
+    }
+  }
+}
+```
+
+**参数说明**
+- `provider`：要更新配置的 provider ID，写入 `models.providers[provider]`。
+- `providerConfig`：provider 配置增量，会合并到已有 provider 配置中。
+
+**允许更新的 providerConfig 字段**
+- `apiKey`
+- `baseUrl`
+- `model`
+- `temperature`
+- `maxTokens`
+- `topP`
+- `frequencyPenalty`
+- `presencePenalty`
+
+---
+
+## 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`
+- `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 文件。
+
+---