rol-websocket-channel 1.0.0

package/MQTT-API.md

@@ -0,0 +1,967 @@
+# 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 - 获取模型列表
+
+**本次变更**
+| 项目 | 之前 | 现在 | 前端需要调整 |
+| --- | --- | --- | --- |
+| 默认模型字段 | 顶层返回 `defaultAgentPrimaryModel` | 移除顶层默认模型字段，统一返回 `defaults.model` | 改为读取 `defaults.model.primary` / `defaults.model.provider` |
+| agent 模型视图 | 不返回 | 新增 `agents[]` | agent 列表可直接展示每个 agent 的模型 |
+| providers | 返回脱敏 `configuredProviders` | 保持不变 | 无需调整 |
+
+**破坏性调整**
+- `defaultAgentPrimaryModel` 已移除。
+- 不再新增 `defaultAgentModelProvider`。
+- 默认模型统一从 `defaults.model` 读取；默认 agent 也会出现在 `agents[]` 的第一项。
+
+**说明**
+- 返回默认代理模型、所有 agent 的模型配置视图、模型配置模式，以及脱敏后的 providers。
+
+**请求**
+```json
+{
+  "type": "modelsGet",
+  "trace_id": "models-get-001",
+  "data": {}
+}
+```
+
+**响应 data 主要字段**
+```json
+{
+  "defaults": {
+    "model": {
+      "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+      "provider": "custom-dashscope-aliyuncs-com"
+    }
+  },
+  "agents": [
+    {
+      "id": "defaults",
+      "name": "defaults",
+      "model": {
+        "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+        "provider": "custom-dashscope-aliyuncs-com"
+      }
+    }
+  ],
+  "configuredProviders": {}
+}
+```
+
+---
+
+### modelsUpdate - 更新模型配置
+
+**本次变更**
+| 项目 | 之前 | 现在 | 前端需要调整 |
+| --- | --- | --- | --- |
+| 切换默认模型 | 只传 `primaryModel`，只写 `agents.defaults.model.primary` | 支持 `primaryModel` + `modelProvider`，会同时写 `primary` 和 `provider` | 默认模型切换表单建议同时提交 `primaryModel` 和 `modelProvider` |
+| provider 推断 | 不处理 | `primaryModel` 为 `providerId/modelName` 时自动推断 `model.provider` | 如果模型值已带 provider 前缀，可以不传 `modelProvider`，但推荐显式传 |
+| 仅切 provider | 不支持 | 支持只传 `modelProvider` | provider 下拉单独保存时可用 |
+| 厂商配置 | `provider` + `providerConfig` | 保持不变 | 继续用于更新 `models.providers[provider]` |
+
+**兼容性**
+- 旧请求仍可用：
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-update-old-001",
+  "data": {
+    "primaryModel": "custom-dashscope-aliyuncs-com/qwen-plus"
+  }
+}
+```
+- 旧请求现在会额外自动写入：
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "provider": "custom-dashscope-aliyuncs-com"
+      }
+    }
+  }
+}
+```
+- 如果 `primaryModel` 没有 `/`，后端不会自动推断 provider，需要前端显式传 `modelProvider`。
+
+**请求对比**
+旧请求：
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-switch-default-old-001",
+  "data": {
+    "primaryModel": "custom-dashscope-aliyuncs-com/qwen-plus"
+  }
+}
+```
+
+新推荐请求：
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-switch-default-new-001",
+  "data": {
+    "primaryModel": "custom-dashscope-aliyuncs-com/qwen-plus",
+    "modelProvider": "custom-dashscope-aliyuncs-com"
+  }
+}
+```
+
+**说明**
+- `openclaw.json` 可以同时保存多个 AI 厂商/provider 的配置，通常放在 `models.providers` 下。
+- 每个 agent 通过 `model.primary` 指向具体模型，格式通常是 `providerId/modelName`，例如 `custom-dashscope-aliyuncs-com/qwen-plus`。
+- `modelsUpdate` 负责远程修改默认代理的 `agents.defaults.model.primary` / `agents.defaults.model.provider`，以及合并写入 `models.providers[provider]` 的配置；真正能否调用成功取决于 OpenClaw 本体是否支持该 provider 配置格式和密钥。
+- `primaryModel` 形如 `providerId/modelName` 时，会自动把 `/` 前面的部分写入默认代理的 `model.provider`。也可以显式传 `modelProvider` 覆盖自动推断。
+- `provider` + `providerConfig` 只用于更新 `models.providers[provider]`，不要把它和默认代理的 `modelProvider` 混用。
+- 如果要修改某个指定代理的模型，使用 `agentsUpdate` 并传入 `agentId`。
+- 可先调用 `configGet` 或 `modelsGet` 查看当前配置。
+
+**openclaw.json 多厂商配置示例**
+```json
+{
+  "models": {
+    "mode": "custom",
+    "providers": {
+      "custom-dashscope-aliyuncs-com": {
+        "apiKey": "YOUR_DASHSCOPE_API_KEY",
+        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+      },
+      "custom-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"
+      }
+    },
+    "list": [
+      {
+        "id": "openai-agent",
+        "name": "OpenAI Agent",
+        "model": {
+          "primary": "custom-openai/gpt-4.1",
+          "provider": "custom-openai"
+        }
+      }
+    ]
+  }
+}
+```
+
+**请求**
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-update-001",
+  "data": {
+    "primaryModel": "custom-dashscope-aliyuncs-com/qwen-plus",
+    "modelProvider": "custom-dashscope-aliyuncs-com"
+  }
+}
+```
+
+**切换默认模型示例**
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-switch-default-001",
+  "data": {
+    "primaryModel": "custom-dashscope-aliyuncs-com/qwen-plus",
+    "modelProvider": "custom-dashscope-aliyuncs-com"
+  }
+}
+```
+
+**仅切换默认 provider 示例**
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-switch-provider-001",
+  "data": {
+    "modelProvider": "custom-dashscope-aliyuncs-com"
+  }
+}
+```
+
+**同时更新 provider 配置示例**
+```json
+{
+  "type": "modelsUpdate",
+  "trace_id": "models-update-provider-001",
+  "data": {
+    "primaryModel": "custom-dashscope-aliyuncs-com/qwen-plus",
+    "modelProvider": "custom-dashscope-aliyuncs-com",
+    "provider": "custom-dashscope-aliyuncs-com",
+    "providerConfig": {
+      "apiKey": "YOUR_API_KEY",
+      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+    }
+  }
+}
+```
+
+**切换指定代理模型示例**
+```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"
+    }
+  }
+}
+```
+
+**允许更新的 providerConfig 字段**
+- `apiKey`
+- `baseUrl`
+- `model`
+- `temperature`
+- `maxTokens`
+- `topP`
+- `frequencyPenalty`
+- `presencePenalty`
+
+---
+
+## 使用统计 (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"
+  }
+}
+```
+
+---
+
+### 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`
+- `modelsUpdate`
+
+### 使用统计
+- `usageSummary`
+- `usagePageSummary`
+- `usageTimeseries`
+- `usageBreakdown`
+
+### 技能管理
+- `skillsListInstalled`
+- `skillsInstallFromNpm`
+- `skillsGetInstalled`
+- `skillsUninstall`
+- `skillsToggle`
+
+### 记忆管理
+- `memoryListFiles`
+- `memoryGetFile`
+- `memoryBackup`
+- `memoryExportZip`
+- `memoryGetPresignedPost`
+- `memoryCreateBackupRecord`
+- `memoryImportZip`