rol-websocket-channel 1.1.5 → 1.2.6

package/MQTT-API /346/226/260/345/242/236/346/226/207/344/273/266/345/212/237/350/203/275.md"

@@ -147,6 +147,11 @@
 }
 ```
 
+**模型字段说明**
+- `modelPrimary` 使用完整的 `providerId/modelName`。
+- `modelProvider` 只做兼容校验；如果传入，必须与 `modelPrimary` 的 provider 部分一致。
+- 创建后只保存 `model.primary`，不会把 `modelProvider` 写成 `model.provider`。
+
 ---
 
 ### agentsUpdate - 更新代理
@@ -159,10 +164,11 @@
   - `workspace`
   - `agentDir`
   - `model.primary`
-  - `model.provider`
   - `skills`
   - `tools.profile`
   - `behavior`
+- `model.provider` 不能通过 `agentsUpdate` 写入；provider 从 `model.primary` 派生。
+- 切换 agent 模型时只写 `model.primary`，值必须是完整的 `providerId/modelName`。
 
 **请求**
 
@@ -305,13 +311,25 @@
 
 ## 模型管理 (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 - 获取模型列表
 
-**说明**
-- 返回默认模型、所有 agent 的模型配置视图、模型下拉选项、模型配置模式，以及脱敏后的 provider 配置。
-- 前端模型选择器使用 `modelOptions[]`。展示 `label`，提交 `value` 和 `provider`。
-- `modelOptions[]` 优先从 `agents.defaults.models` 生成；如果没有配置，会从 `agents.defaults.model` 和 `agents.list[].model` 中收集当前已使用的模型作为兜底选项。
-- `configuredProviders` 是脱敏后的 provider 原始配置，普通模型选择器不需要使用它。
+调整：只负责读取当前模型和下拉数据，不写配置。
+
+**什么时候用**
+
+- 页面初始化时获取当前默认模型、模型下拉选项和 provider 配置视图。
+- 前端下拉框优先使用 `data.modelOptions`。
 
 **请求**
 ```json
@@ -322,111 +340,21 @@
 }
 ```
 
-**响应**
-```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`
+- 下拉提交值：`data.modelOptions[].value`
+- 下拉展示名：优先 `data.modelOptions[].label`
+- 只展示模型名：`data.modelOptions[].model`，例如 `qwen3.6-flash`
+- provider 展示：`data.modelOptions[].providerLabel` 或 `data.modelOptions[].provider`
+- `data.defaults.model.provider` 即使返回，也只当派生展示值，不写回配置。
 
-**前端使用方式**
-- 默认模型：读取 `data.defaults.model.primary`。
-- 默认 provider：读取 `data.defaults.model.provider`；如果为空，可以从选中的 `modelOptions[].provider` 获取。
-- 模型下拉框：使用 `data.modelOptions`。
-- agent 模型列表：使用 `data.agents[]`。
+### modelsSet - 只切换默认模型
 
----
+调整：只写 `agents.defaults.model.primary即可`，`provider` 只做校验 可以不传。
 
-### 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
@@ -434,56 +362,47 @@
   "type": "modelsSet",
   "trace_id": "models-set-001",
   "data": {
-    "primary": "custom-dashscope-aliyuncs-com/qwen-plus"
+    "primary": "custom-dashscope-aliyuncs-com/qwen3.6-flash"
   }
 }
 ```
 
-**带 provider 校验的请求** 测试
+**可选 provider 校验**  可以忽略不管
 ```json
 {
   "type": "modelsSet",
   "trace_id": "models-set-with-provider-001",
   "data": {
-    "primary": "custom-dashscope-aliyuncs-com/qwen-plus",
+    "primary": "custom-dashscope-aliyuncs-com/qwen3.6-flash",
     "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"
-    }
-  }
-}
-```
+**行为**
+- 写入：`agents.defaults.model.primary`
+- 不写入：`agents.defaults.model.provider`
+- 如果传了 `provider`，只校验它必须等于 `primary` 的前缀。
+- 如果 `primary` 不在 `agents.defaults.models` allowlist 中，会返回 `MODEL_NOT_ALLOWED`。
 
-**错误规则**
-- `MODEL_PRIMARY_REQUIRED`：缺少 `primary`。
-- `MODEL_PRIMARY_INVALID`：`primary` 不是 `provider/model` 格式。
-- `MODEL_NOT_ALLOWED`：`primary` 不在允许的模型选项中。
-- `MODEL_PROVIDER_MISMATCH`：传入的 `provider` 与 `primary` 不一致。
+### modelsUpdate - 更新 custom provider，可选同时切默认模型
 
----
+新增 custom provider
+修改 custom provider 的 baseUrl / apiKey / api
+更新 custom provider 的 models[]
+更新 provider 后顺手用 primaryModel 切到这个模型
 
-### modelsUpdate - 更新 provider 配置
+暂时不要custom provider 就不需要管这个接口
 
-**说明**
-- 用于更新 `models.providers[provider]`。
-- 不建议用它做前端模型下拉切换；默认模型切换请使用 `modelsSet`。
-- `providerConfig` 会合并到已有 provider 配置中。
 
-**请求**
+调整：主要维护 `models.providers`，需要切模型时传 `primaryModel`。
+
+**什么时候用**
+- 新增或更新 custom provider。
+- 更新 provider 的 base URL、API key、协议类型或模型列表。
+- 需要在更新 provider 后同时切到某个模型。
+
+**只更新 provider**
 ```json
 {
   "type": "modelsUpdate",
@@ -491,35 +410,68 @@
   "data": {
     "provider": "custom-dashscope-aliyuncs-com",
     "providerConfig": {
+      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "api": "openai-completions",
       "apiKey": "YOUR_API_KEY",
-      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+      "models": [
+        {
+          "id": "qwen3.6-flash",
+          "name": "qwen3.6-flash (Custom Provider)"
+        }
+      ]
     }
   }
 }
 ```
 
-**切换指定 agent 模型**
+**更新 provider 并切默认模型**
 ```json
 {
-  "type": "agentsUpdate",
-  "trace_id": "agent-switch-model-001",
+  "type": "modelsUpdate",
+  "trace_id": "models-update-and-switch-001",
   "data": {
-    "agentId": "my-agent",
-    "updates": {
-      "model.primary": "custom-dashscope-aliyuncs-com/qwen-plus",
-      "model.provider": "custom-dashscope-aliyuncs-com"
+    "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)"
+        }
+      ]
     }
   }
 }
 ```
 
-**参数说明**
-- `provider`：要更新配置的 provider ID，写入 `models.providers[provider]`。
-- `providerConfig`：provider 配置增量，会合并到已有 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 字段**
+**providerConfig 允许字段**
 - `apiKey`
+- `api`
 - `baseUrl`
+- `models`
+- `name`
+- `label`
 - `model`
 - `temperature`
 - `maxTokens`
@@ -527,6 +479,31 @@
 - `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)