rol-websocket-channel 1.2.5 → 1.3.5

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)

package/dist/src/admin/methods/agents-extended.js

@@ -7,7 +7,6 @@ const ALLOWED_AGENT_UPDATES = {
     'workspace': true,
     'agentDir': true,
     'model.primary': true,
-    'model.provider': true,
     'skills': true,
     'tools.profile': true,
     'behavior': true,
@@ -50,11 +49,21 @@ export const createAgent = async (params, context) => {
         workspace,
         agentDir
     };
-    if (typeof objectParams.modelPrimary === 'string' && objectParams.modelPrimary.trim().length > 0) {
-        created.model = { ...(created.model ?? {}), primary: objectParams.modelPrimary.trim() };
+    const modelPrimary = typeof objectParams.modelPrimary === 'string' && objectParams.modelPrimary.trim().length > 0
+        ? objectParams.modelPrimary.trim()
+        : null;
+    const modelProvider = typeof objectParams.modelProvider === 'string' && objectParams.modelProvider.trim().length > 0
+        ? objectParams.modelProvider.trim()
+        : null;
+    if (modelPrimary) {
+        const inferredProvider = inferProviderFromPrimaryModel(modelPrimary);
+        if (modelProvider && modelProvider !== inferredProvider) {
+            throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'modelProvider does not match modelPrimary');
+        }
+        created.model = { ...(created.model ?? {}), primary: modelPrimary };
     }
-    if (typeof objectParams.modelProvider === 'string' && objectParams.modelProvider.trim().length > 0) {
-        created.model = { ...(created.model ?? {}), provider: objectParams.modelProvider.trim() };
+    else if (modelProvider) {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'modelProvider cannot be set without modelPrimary; provider is derived from model.primary');
     }
     if (Array.isArray(objectParams.skills)) {
         created.skills = objectParams.skills.filter((item) => typeof item === 'string');
@@ -143,6 +152,9 @@ export const updateAgent = async (params, context) => {
     const target = resolveAgentTarget(config, agentId);
     const changes = [];
     for (const [fieldPath, value] of Object.entries(updates)) {
+        if (fieldPath === 'model.provider') {
+            throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'model.provider is derived from model.primary and cannot be updated directly');
+        }
         if (!ALLOWED_AGENT_UPDATES[fieldPath]) {
             throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, `Field not allowed for update: ${fieldPath}. Allowed fields: ${Object.keys(ALLOWED_AGENT_UPDATES).join(', ')}`);
         }
@@ -170,6 +182,10 @@ function setNestedValue(obj, pathExpression, value) {
     }
     current[keys[keys.length - 1]] = value;
 }
+function inferProviderFromPrimaryModel(primary) {
+    const separatorIndex = primary.indexOf('/');
+    return separatorIndex > 0 ? primary.slice(0, separatorIndex) : null;
+}
 function isObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }

package/dist/src/admin/methods/models-extended.js

@@ -4,7 +4,11 @@ import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.ts';
 // 允许修改的 provider 配置字段白名单
 const ALLOWED_PROVIDER_FIELDS = {
     'apiKey': true,
+    'api': true,
     'baseUrl': true,
+    'models': true,
+    'name': true,
+    'label': true,
     'model': true,
     'temperature': true,
     'maxTokens': true,
@@ -35,24 +39,15 @@ export const updateModels = async (params, context) => {
         if (!config.agents.defaults.model)
             config.agents.defaults.model = {};
         config.agents.defaults.model.primary = primaryModel;
-        const inferredProvider = modelProvider ?? inferProviderFromPrimaryModel(primaryModel);
-        if (inferredProvider) {
-            config.agents.defaults.model.provider = inferredProvider;
-            changes.push(`Updated default model provider to: ${inferredProvider}`);
+        const inferredProvider = inferProviderFromPrimaryModel(primaryModel);
+        if (modelProvider && modelProvider !== inferredProvider) {
+            throwModelError('MODEL_PROVIDER_MISMATCH', 'modelProvider does not match primaryModel');
         }
         updated = true;
         changes.push(`Updated primary model to: ${primaryModel}`);
     }
     if (modelProvider && !primaryModel) {
-        if (!config.agents)
-            config.agents = {};
-        if (!config.agents.defaults)
-            config.agents.defaults = {};
-        if (!config.agents.defaults.model)
-            config.agents.defaults.model = {};
-        config.agents.defaults.model.provider = modelProvider;
-        updated = true;
-        changes.push(`Updated default model provider to: ${modelProvider}`);
+        throwModelError('MODEL_PROVIDER_DERIVED', 'modelProvider cannot be updated directly; set primaryModel in provider/model format');
     }
     // 更新 provider 配置
     if (provider && providerConfig) {
@@ -88,7 +83,9 @@ export const updateModels = async (params, context) => {
         changes,
         updatedConfig: {
             primaryModel: config.agents?.defaults?.model?.primary ?? null,
-            modelProvider: config.agents?.defaults?.model?.provider ?? null,
+            modelProvider: config.agents?.defaults?.model?.primary
+                ? inferProviderFromPrimaryModel(config.agents.defaults.model.primary)
+                : null,
             defaultModel: config.agents?.defaults?.model ?? {},
             providers: redactSecrets(config.models?.providers ?? {})
         }
@@ -120,7 +117,6 @@ export const setModel = async (params, context) => {
     if (!config.agents.defaults.model)
         config.agents.defaults.model = {};
     config.agents.defaults.model.primary = primary;
-    config.agents.defaults.model.provider = inferredProvider;
     await writeJsonFile(configPath, config);
     return {
         ok: true,

package/dist/src/admin/methods/skills.js

@@ -65,7 +65,7 @@ export const searchClawHubSkills = async (params, context) => {
 export const installSkillFromClawHub = async (params, context) => {
     const objectParams = expectObject(params);
     const slug = expectString(objectParams.slug, 'slug');
-    const result = await runOpenClawSkillCommand(['skills', 'install', slug], context.openclawRoot, context.openclawRoot);
+    const result = await runClawHubSkillCommandWithFallback('install', slug, context.openclawRoot, context.openclawRoot);
     return {
         ok: true,
         slug,
@@ -75,7 +75,7 @@ export const installSkillFromClawHub = async (params, context) => {
 export const updateSkillFromClawHub = async (params, context) => {
     const objectParams = expectObject(params);
     const slug = expectString(objectParams.slug, 'slug');
-    const result = await runOpenClawSkillCommand(['skills', 'update', slug], context.openclawRoot, context.openclawRoot);
+    const result = await runClawHubSkillCommandWithFallback('update', slug, context.openclawRoot, context.openclawRoot);
     return {
         ok: true,
         slug,
@@ -124,13 +124,52 @@ async function npmPack(packageSpec, cwd) {
     }
     return tarballName;
 }
+export function buildClawHubSkillCommandPlan(action, slug) {
+    const args = action === 'install' && slug === 'proactive-agent'
+        ? [action, slug, '--force']
+        : [action, slug];
+    return [
+        {
+            command: process.env.CLAWHUB_BIN || 'clawhub',
+            args
+        }
+    ];
+}
 async function runOpenClawSkillCommand(args, cwd, openclawRoot) {
     const command = process.env.OPENCLAW_BIN || 'openclaw';
+    return await runSkillCommand(command, args, cwd, openclawRoot);
+}
+async function runClawHubSkillCommandWithFallback(action, slug, cwd, openclawRoot) {
+    const attempts = [];
+    for (const invocation of buildClawHubSkillCommandPlan(action, slug)) {
+        try {
+            return await runSkillCommand(invocation.command, invocation.args, cwd, openclawRoot);
+        }
+        catch (err) {
+            const data = err instanceof JsonRpcException && isRecord(err.data) ? err.data : {};
+            attempts.push({
+                command: invocation.command,
+                args: invocation.args,
+                stdout: typeof data.stdout === 'string' ? data.stdout : '',
+                stderr: typeof data.stderr === 'string' ? data.stderr : '',
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+    }
+    const lastAttempt = attempts.at(-1);
+    throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `ClawHub skill ${action} command failed: ${lastAttempt?.error ?? 'unknown error'}`, {
+        action,
+        slug,
+        attempts
+    });
+}
+async function runSkillCommand(command, args, cwd, openclawRoot) {
     const options = buildOpenClawExecOptions(cwd, openclawRoot);
     const openclawBin = process.env.OPENCLAW_BIN || '';
+    const clawhubBin = process.env.CLAWHUB_BIN || '';
     const openclawHome = options.env?.OPENCLAW_HOME || '';
     const home = options.env?.HOME || '';
-    console.log(`[skills] exec start: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}`);
+    console.log(`[skills] exec start: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, CLAWHUB_BIN=${clawhubBin}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}`);
     try {
         const { stdout, stderr } = await execFileAsync(command, args, options);
         console.log(`[skills] exec success: command=${command}, args=${JSON.stringify(args)}, stdoutLength=${stdout.length}, stderrLength=${stderr.length}`);
@@ -143,7 +182,7 @@ async function runOpenClawSkillCommand(args, cwd, openclawRoot) {
     catch (err) {
         const stdout = typeof err?.stdout === 'string' ? err.stdout : '';
         const stderr = typeof err?.stderr === 'string' ? err.stderr : '';
-        console.error(`[skills] exec failed: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}, stdout=${JSON.stringify(stdout)}, stderr=${JSON.stringify(stderr)}`);
+        console.error(`[skills] exec failed: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, CLAWHUB_BIN=${clawhubBin}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}, stdout=${JSON.stringify(stdout)}, stderr=${JSON.stringify(stderr)}`);
         throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `OpenClaw skill command failed: ${err instanceof Error ? err.message : String(err)}`, {
             command,
             args,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rol-websocket-channel",
-  "version": "1.2.5",
+  "version": "1.3.5",
   "description": "Unified OpenClaw plugin: MQTT Channel + Admin Bridge for remote management",
   "license": "MIT",
   "author": "nixgnehc",

package/src/admin/methods/agents-extended.ts

@@ -30,7 +30,6 @@ const ALLOWED_AGENT_UPDATES: Record<string, boolean> = {
   'workspace': true,
   'agentDir': true,
   'model.primary': true,
-  'model.provider': true,
   'skills': true,
   'tools.profile': true,
   'behavior': true,
@@ -83,11 +82,27 @@ export const createAgent: MethodHandler = async (params, context): Promise<JsonV
     agentDir
   };
 
-  if (typeof objectParams.modelPrimary === 'string' && objectParams.modelPrimary.trim().length > 0) {
-    created.model = { ...(created.model ?? {}), primary: objectParams.modelPrimary.trim() };
-  }
-  if (typeof objectParams.modelProvider === 'string' && objectParams.modelProvider.trim().length > 0) {
-    created.model = { ...(created.model ?? {}), provider: objectParams.modelProvider.trim() };
+  const modelPrimary = typeof objectParams.modelPrimary === 'string' && objectParams.modelPrimary.trim().length > 0
+    ? objectParams.modelPrimary.trim()
+    : null;
+  const modelProvider = typeof objectParams.modelProvider === 'string' && objectParams.modelProvider.trim().length > 0
+    ? objectParams.modelProvider.trim()
+    : null;
+
+  if (modelPrimary) {
+    const inferredProvider = inferProviderFromPrimaryModel(modelPrimary);
+    if (modelProvider && modelProvider !== inferredProvider) {
+      throw new JsonRpcException(
+        JSON_RPC_ERRORS.invalidParams,
+        'modelProvider does not match modelPrimary'
+      );
+    }
+    created.model = { ...(created.model ?? {}), primary: modelPrimary };
+  } else if (modelProvider) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      'modelProvider cannot be set without modelPrimary; provider is derived from model.primary'
+    );
   }
   if (Array.isArray(objectParams.skills)) {
     created.skills = objectParams.skills.filter((item): item is string => typeof item === 'string');
@@ -196,6 +211,13 @@ export const updateAgent: MethodHandler = async (params, context): Promise<JsonV
   const changes: string[] = [];
 
   for (const [fieldPath, value] of Object.entries(updates)) {
+    if (fieldPath === 'model.provider') {
+      throw new JsonRpcException(
+        JSON_RPC_ERRORS.invalidParams,
+        'model.provider is derived from model.primary and cannot be updated directly'
+      );
+    }
+
     if (!ALLOWED_AGENT_UPDATES[fieldPath]) {
       throw new JsonRpcException(
         JSON_RPC_ERRORS.invalidParams,
@@ -233,6 +255,11 @@ function setNestedValue(obj: any, pathExpression: string, value: any): void {
   current[keys[keys.length - 1]] = value;
 }
 
+function inferProviderFromPrimaryModel(primary: string): string | null {
+  const separatorIndex = primary.indexOf('/');
+  return separatorIndex > 0 ? primary.slice(0, separatorIndex) : null;
+}
+
 function isObject(value: JsonValue | undefined): value is Record<string, JsonValue> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }

package/src/admin/methods/models-extended.ts

@@ -27,7 +27,11 @@ interface OpenClawConfig {
 // 允许修改的 provider 配置字段白名单
 const ALLOWED_PROVIDER_FIELDS: Record<string, boolean> = {
   'apiKey': true,
+  'api': true,
   'baseUrl': true,
+  'models': true,
+  'name': true,
+  'label': true,
   'model': true,
   'temperature': true,
   'maxTokens': true,
@@ -63,23 +67,22 @@ export const updateModels: MethodHandler = async (
     if (!config.agents.defaults.model) config.agents.defaults.model = {};
     
     config.agents.defaults.model.primary = primaryModel;
-    const inferredProvider = modelProvider ?? inferProviderFromPrimaryModel(primaryModel);
-    if (inferredProvider) {
-      config.agents.defaults.model.provider = inferredProvider;
-      changes.push(`Updated default model provider to: ${inferredProvider}`);
+    const inferredProvider = inferProviderFromPrimaryModel(primaryModel);
+    if (modelProvider && modelProvider !== inferredProvider) {
+      throwModelError(
+        'MODEL_PROVIDER_MISMATCH',
+        'modelProvider does not match primaryModel'
+      );
     }
     updated = true;
     changes.push(`Updated primary model to: ${primaryModel}`);
   }
 
   if (modelProvider && !primaryModel) {
-    if (!config.agents) config.agents = {};
-    if (!config.agents.defaults) config.agents.defaults = {};
-    if (!config.agents.defaults.model) config.agents.defaults.model = {};
-
-    config.agents.defaults.model.provider = modelProvider;
-    updated = true;
-    changes.push(`Updated default model provider to: ${modelProvider}`);
+    throwModelError(
+      'MODEL_PROVIDER_DERIVED',
+      'modelProvider cannot be updated directly; set primaryModel in provider/model format'
+    );
   }
 
   // 更新 provider 配置
@@ -126,7 +129,9 @@ export const updateModels: MethodHandler = async (
     changes,
     updatedConfig: {
       primaryModel: config.agents?.defaults?.model?.primary ?? null,
-      modelProvider: config.agents?.defaults?.model?.provider ?? null,
+      modelProvider: config.agents?.defaults?.model?.primary
+        ? inferProviderFromPrimaryModel(config.agents.defaults.model.primary)
+        : null,
       defaultModel: config.agents?.defaults?.model ?? {},
       providers: redactSecrets(config.models?.providers ?? {})
     }
@@ -178,7 +183,6 @@ export const setModel: MethodHandler = async (
   if (!config.agents.defaults.model) config.agents.defaults.model = {};
 
   config.agents.defaults.model.primary = primary;
-  config.agents.defaults.model.provider = inferredProvider;
 
   await writeJsonFile(configPath, config);
 

package/src/admin/methods/skills.ts

@@ -33,6 +33,13 @@ interface ClawHubSkillParams {
   slug: string;
 }
 
+type ClawHubSkillAction = 'install' | 'update';
+
+interface SkillCommandInvocation {
+  command: string;
+  args: string[];
+}
+
 interface ResolvedSkillIdentity {
   slug: string;
   displayName: string;
@@ -155,7 +162,7 @@ export const searchClawHubSkills: MethodHandler = async (params, context): Promi
 export const installSkillFromClawHub: MethodHandler = async (params, context): Promise<JsonValue> => {
   const objectParams = expectObject(params) as unknown as ClawHubSkillParams;
   const slug = expectString(objectParams.slug, 'slug');
-  const result = await runOpenClawSkillCommand(['skills', 'install', slug], context.openclawRoot, context.openclawRoot);
+  const result = await runClawHubSkillCommandWithFallback('install', slug, context.openclawRoot, context.openclawRoot);
 
   return {
     ok: true,
@@ -167,7 +174,7 @@ export const installSkillFromClawHub: MethodHandler = async (params, context): P
 export const updateSkillFromClawHub: MethodHandler = async (params, context): Promise<JsonValue> => {
   const objectParams = expectObject(params) as unknown as ClawHubSkillParams;
   const slug = expectString(objectParams.slug, 'slug');
-  const result = await runOpenClawSkillCommand(['skills', 'update', slug], context.openclawRoot, context.openclawRoot);
+  const result = await runClawHubSkillCommandWithFallback('update', slug, context.openclawRoot, context.openclawRoot);
 
   return {
     ok: true,
@@ -231,19 +238,77 @@ async function npmPack(packageSpec: string, cwd: string): Promise<string> {
   return tarballName;
 }
 
+export function buildClawHubSkillCommandPlan(action: ClawHubSkillAction, slug: string): SkillCommandInvocation[] {
+  const args = action === 'install' && slug === 'proactive-agent'
+    ? [action, slug, '--force']
+    : [action, slug];
+
+  return [
+    {
+      command: process.env.CLAWHUB_BIN || 'clawhub',
+      args
+    }
+  ];
+}
+
 async function runOpenClawSkillCommand(
   args: string[],
   cwd: string,
   openclawRoot?: string
 ): Promise<{ stdout: string; stderr: string; parsed: JsonValue | null }> {
   const command = process.env.OPENCLAW_BIN || 'openclaw';
+  return await runSkillCommand(command, args, cwd, openclawRoot);
+}
+
+async function runClawHubSkillCommandWithFallback(
+  action: ClawHubSkillAction,
+  slug: string,
+  cwd: string,
+  openclawRoot?: string
+): Promise<{ stdout: string; stderr: string; parsed: JsonValue | null }> {
+  const attempts: Array<SkillCommandInvocation & { stdout: string; stderr: string; error: string }> = [];
+
+  for (const invocation of buildClawHubSkillCommandPlan(action, slug)) {
+    try {
+      return await runSkillCommand(invocation.command, invocation.args, cwd, openclawRoot);
+    } catch (err) {
+      const data = err instanceof JsonRpcException && isRecord(err.data) ? err.data : {};
+      attempts.push({
+        command: invocation.command,
+        args: invocation.args,
+        stdout: typeof data.stdout === 'string' ? data.stdout : '',
+        stderr: typeof data.stderr === 'string' ? data.stderr : '',
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+
+  const lastAttempt = attempts.at(-1);
+  throw new JsonRpcException(
+    JSON_RPC_ERRORS.internalError,
+    `ClawHub skill ${action} command failed: ${lastAttempt?.error ?? 'unknown error'}`,
+    {
+      action,
+      slug,
+      attempts
+    }
+  );
+}
+
+async function runSkillCommand(
+  command: string,
+  args: string[],
+  cwd: string,
+  openclawRoot?: string
+): Promise<{ stdout: string; stderr: string; parsed: JsonValue | null }> {
   const options = buildOpenClawExecOptions(cwd, openclawRoot);
   const openclawBin = process.env.OPENCLAW_BIN || '';
+  const clawhubBin = process.env.CLAWHUB_BIN || '';
   const openclawHome = options.env?.OPENCLAW_HOME || '';
   const home = options.env?.HOME || '';
 
   console.log(
-    `[skills] exec start: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}`
+    `[skills] exec start: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, CLAWHUB_BIN=${clawhubBin}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}`
   );
 
   try {
@@ -260,7 +325,7 @@ async function runOpenClawSkillCommand(
     const stdout = typeof err?.stdout === 'string' ? err.stdout : '';
     const stderr = typeof err?.stderr === 'string' ? err.stderr : '';
     console.error(
-      `[skills] exec failed: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}, stdout=${JSON.stringify(stdout)}, stderr=${JSON.stringify(stderr)}`
+      `[skills] exec failed: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, CLAWHUB_BIN=${clawhubBin}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}, stdout=${JSON.stringify(stdout)}, stderr=${JSON.stringify(stderr)}`
     );
     throw new JsonRpcException(
       JSON_RPC_ERRORS.internalError,