@2en/clawly-plugins 1.32.0 → 1.34.0-beta.0

package/auto-pair.ts

@@ -37,7 +37,15 @@ export function registerAutoPair(api: PluginApi) {
 
   api.on('gateway_start', async () => {
     try {
-      sdk = await import('openclaw/plugin-sdk')
+      // v2026.3.23+ moved pairing functions to device-bootstrap subpath;
+      // older versions export them from the main plugin-sdk index.
+      try {
+        sdk = await import('openclaw/plugin-sdk/device-bootstrap')
+      } catch (err: unknown) {
+        const code = (err as NodeJS.ErrnoException)?.code
+        if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') throw err
+        sdk = await import('openclaw/plugin-sdk')
+      }
     } catch {
       api.logger.warn('auto-pair: openclaw/plugin-sdk not available, skipping')
       return

package/clawly-config-defaults.json5

@@ -39,7 +39,7 @@
             input: ["text", "image"],
             contextWindow: 1000000,
             maxTokens: 128000,
-            // api: 'anthropic-messages', // TODO: uncomment once model gateway Anthropic Messages API support is out of testing
+            api: "anthropic-messages",
           },
           {
             id: "anthropic/claude-opus-4.6",
@@ -47,7 +47,7 @@
             input: ["text", "image"],
             contextWindow: 1000000,
             maxTokens: 128000,
-            // api: 'anthropic-messages', // TODO: uncomment once model gateway Anthropic Messages API support is out of testing
+            api: "anthropic-messages",
           },
           {
             id: "openai/gpt-5.4",
@@ -77,6 +77,13 @@
             contextWindow: 196608,
             maxTokens: 196608,
           },
+          {
+            id: "qwen/qwen3.5-flash-02-23",
+            name: "qwen/qwen3.5-flash-02-23",
+            input: ["text", "image"],
+            contextWindow: 1000000,
+            maxTokens: 65536,
+          },
           {
             id: "qwen/qwen3.5-plus-02-15",
             name: "qwen/qwen3.5-plus-02-15",

package/config-setup.ts

@@ -237,7 +237,7 @@ export function patchBrowser(config: OpenClawConfig): boolean {
 // patchHeartbeat — migrated to clawly-config-defaults.json5
 
 /** Fields enforced by patchModelDefinitions on every gateway restart. */
-const MODEL_ENFORCED_KEYS = ['contextWindow', 'maxTokens', 'input'] as const
+const MODEL_ENFORCED_KEYS = ['contextWindow', 'maxTokens', 'input', 'api'] as const
 
 /** Shallow equality — only supports primitives and arrays of primitives. */
 function valuesEqual(a: unknown, b: unknown): boolean {
@@ -593,6 +593,43 @@ export function patchPluginsAllow(config: OpenClawConfig): boolean {
   return true
 }
 
+/**
+ * Ensure the bootstrap-extra-files internal hook is configured so the agent
+ * loads system-managed workspace files from .clawly/ alongside user files.
+ */
+export function patchBootstrapExtraFiles(config: OpenClawConfig): boolean {
+  const hooks = (config.hooks ?? {}) as Record<string, unknown>
+  const internal = asObj(hooks.internal)
+  const entries = asObj(internal.entries)
+
+  // Must match systemWorkspacePaths from @clawly/workspace-files.
+  // Hardcoded because this plugin runs on sprites without access to that package.
+  const EXPECTED_PATHS = ['.clawly/AGENTS.md', '.clawly/TOOLS.md']
+
+  const existing = entries['bootstrap-extra-files'] as
+    | {enabled?: boolean; paths?: string[]}
+    | undefined
+  if (
+    internal.enabled === true &&
+    existing?.enabled === true &&
+    Array.isArray(existing.paths) &&
+    existing.paths.length === EXPECTED_PATHS.length &&
+    EXPECTED_PATHS.every((p) => existing.paths!.includes(p))
+  ) {
+    return false
+  }
+
+  entries['bootstrap-extra-files'] = {
+    enabled: true,
+    paths: EXPECTED_PATHS,
+  }
+  internal.enabled = true
+  internal.entries = entries
+  hooks.internal = internal
+  config.hooks = hooks as OpenClawConfig['hooks']
+  return true
+}
+
 function reconcileRuntimeConfig(
   api: PluginApi,
   config: OpenClawConfig,
@@ -618,6 +655,7 @@ function reconcileRuntimeConfig(
   dirty = patchGateway(config) || dirty
   dirty = patchBrowser(config) || dirty
   dirty = patchSession(config) || dirty
+  dirty = patchBootstrapExtraFiles(config) || dirty
 
   const defaults = loadDefaults(stateDir)
   if (defaults) {

package/cron-history.ts

@@ -0,0 +1,151 @@
+/**
+ * Cron history injection — before_agent_start hook that prepends past run
+ * summaries to cron job prompts, preventing the LLM from repeating the same
+ * output across isolated sessions.
+ *
+ * Feature-flagged via agents.defaults.cronHistoryInjection in openclaw.json
+ * (default: off). Toggled from the mobile app's system settings.
+ *
+ * Data source: the existing cron run log JSONL at
+ * {cronStoreDir}/runs/{jobId}.jsonl — populated by OpenClaw after each run
+ * with a `summary` field (last agent output, truncated to 2000 chars).
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import {autoUpdateJobId} from './internal/hooks/auto-update'
+import type {PluginApi} from './types'
+import type {OpenClawConfig} from './types/openclaw'
+
+const HISTORY_DEPTH = 10
+const SUMMARY_MAX_CHARS = 200
+
+/** Extract the first sentence or first line, truncated to maxChars. */
+function truncateSummary(summary: string, maxChars: number): string {
+  // Take first line
+  const firstLine = summary.split('\n')[0]?.trim() ?? summary.trim()
+  if (firstLine.length <= maxChars) return firstLine
+  return `${firstLine.slice(0, maxChars)}…`
+}
+
+/** Parse job ID from the cron prompt prefix: [cron:{jobId} {jobName}] */
+function parseJobIdFromPrompt(prompt: string): string | null {
+  const match = prompt.match(/\[cron:([0-9a-f-]+)\s/)
+  return match?.[1] ?? null
+}
+
+/** Resolve the cron run log path for a job. */
+function resolveRunLogPath(cronStore: string | undefined, jobId: string): string {
+  const storePath =
+    cronStore || path.join(process.env.HOME || '/home/claw', '.openclaw', 'cron', 'cron.json')
+  return path.join(path.dirname(storePath), 'runs', `${jobId}.jsonl`)
+}
+
+interface RunLogEntry {
+  ts: number
+  status?: string
+  summary?: string
+}
+
+/** Read last N successful run summaries from the JSONL run log. */
+async function readRecentSummaries(
+  logPath: string,
+  limit: number,
+): Promise<Array<{ts: number; summary: string}>> {
+  let raw: string
+  try {
+    raw = await fs.readFile(logPath, 'utf-8')
+  } catch {
+    return []
+  }
+  if (!raw.trim()) return []
+
+  const lines = raw.split('\n')
+  const results: Array<{ts: number; summary: string}> = []
+
+  // Read from the end (most recent first)
+  for (let i = lines.length - 1; i >= 0 && results.length < limit; i--) {
+    const line = lines[i]?.trim()
+    if (!line) continue
+    try {
+      const entry = JSON.parse(line) as Partial<RunLogEntry>
+      if (entry.status !== 'ok') continue
+      const summary = entry.summary?.trim()
+      if (!summary) continue
+      if (typeof entry.ts !== 'number') continue
+      results.push({ts: entry.ts, summary})
+    } catch {
+      // skip malformed lines
+    }
+  }
+
+  return results.reverse()
+}
+
+function formatDate(ts: number): string {
+  const d = new Date(ts)
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}
+
+export function registerCronHistory(api: PluginApi) {
+  api.on(
+    'before_agent_start',
+    async (
+      event: {prompt: string; messages?: unknown[]},
+      ctx?: {agentId?: string; sessionKey?: string; sessionId?: string},
+    ) => {
+      // Feature flag check — read fresh config each time (loadConfig has ~200ms cache)
+      try {
+        const config = api.runtime.config.loadConfig() as OpenClawConfig
+        const defaults = (config.agents as Record<string, unknown> | undefined)?.defaults as
+          | Record<string, unknown>
+          | undefined
+        if (defaults?.cronHistoryInjection !== true) return
+      } catch {
+        return
+      }
+
+      // Only fire for cron sessions
+      const sessionKey = ctx?.sessionKey
+      if (!sessionKey?.includes(':cron:')) return
+
+      // Extract job ID from the prompt prefix
+      const jobId = parseJobIdFromPrompt(event.prompt)
+      if (!jobId) return
+
+      // Skip auto-update job
+      if (autoUpdateJobId && jobId === autoUpdateJobId) return
+
+      try {
+        const logPath = resolveRunLogPath(
+          (api.config.cron as Record<string, unknown> | undefined)?.store as string | undefined,
+          jobId,
+        )
+        const summaries = await readRecentSummaries(logPath, HISTORY_DEPTH)
+        if (summaries.length === 0) return
+
+        const lines = summaries.map(
+          (s, i) =>
+            `${i + 1}. (${formatDate(s.ts)}) ${truncateSummary(s.summary, SUMMARY_MAX_CHARS)}`,
+        )
+        const prependContext = [
+          `[For context: summaries of your previous ${summaries.length} ${summaries.length === 1 ? 'output' : 'outputs'} for this task. Use this to avoid repetition where appropriate.]`,
+          ...lines,
+        ].join('\n')
+
+        api.logger.info(`cron-history: injected ${summaries.length} summaries for job ${jobId}`)
+
+        return {prependContext}
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        api.logger.warn(`cron-history: failed to read history for job ${jobId} — ${msg}`)
+      }
+    },
+  )
+
+  api.logger.info('cron-history: registered before_agent_start hook')
+}

package/gateway/config-cron-history.ts

@@ -0,0 +1,57 @@
+/**
+ * Cron history injection toggle RPC: writes agents.defaults.cronHistoryInjection
+ * to openclaw.json without triggering a gateway restart.
+ *
+ * When enabled, the before_agent_start hook in cron-history.ts injects past run
+ * summaries into every cron job's prompt to prevent repeated outputs.
+ *
+ * Methods:
+ * - clawly.config.setCronHistory({ enabled }) → { changed, enabled }
+ */
+
+import type {PluginApi} from '../types'
+import type {OpenClawConfig} from '../types/openclaw'
+
+export function registerConfigCronHistory(api: PluginApi) {
+  api.registerGatewayMethod('clawly.config.setCronHistory', async ({params, respond}) => {
+    const enabled = params.enabled === true
+
+    let config: OpenClawConfig
+    try {
+      config = {...(api.runtime.config.loadConfig() as OpenClawConfig)}
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      respond(true, {changed: false, enabled, error: `Load failed: ${msg}`})
+      return
+    }
+
+    const currentDefaults = (config.agents as Record<string, unknown> | undefined)?.defaults as
+      | Record<string, unknown>
+      | undefined
+
+    if (currentDefaults?.cronHistoryInjection === enabled) {
+      respond(true, {changed: false, enabled})
+      return
+    }
+
+    // Shallow-copy nested objects to avoid polluting the loadConfig() cache
+    // if writeConfigFile fails below.
+    const agents = {...((config.agents ?? {}) as Record<string, unknown>)}
+    const defaults = {...((agents.defaults ?? {}) as Record<string, unknown>)}
+    defaults.cronHistoryInjection = enabled
+    agents.defaults = defaults
+    config.agents = agents
+
+    try {
+      await api.runtime.config.writeConfigFile(config)
+      api.logger.info(`config-cron-history: set cronHistoryInjection to ${enabled}`)
+      respond(true, {changed: true, enabled})
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      api.logger.error(`config-cron-history: write failed — ${msg}`)
+      respond(true, {changed: false, enabled, error: `Write failed: ${msg}`})
+    }
+  })
+
+  api.logger.info('config-cron-history: registered clawly.config.setCronHistory')
+}

package/gateway/index.ts

@@ -4,6 +4,7 @@ import {registerCalendarNative} from './calendar-native'
 import {registerAnalytics} from './analytics'
 import {registerAudit} from './audit'
 import {registerClawhub2gateway} from './clawhub2gateway'
+import {registerConfigCronHistory} from './config-cron-history'
 import {registerConfigModel} from './config-model'
 import {registerConfigRepair} from './config-repair'
 import {registerConfigTimezone} from './config-timezone'
@@ -63,6 +64,7 @@ export function registerGateway(api: PluginApi) {
   registerCronTelemetry(api)
   registerMessageLog(api)
   registerAnalytics(api)
+  registerConfigCronHistory(api)
   registerConfigModel(api)
   registerConfigRepair(api)
   registerConfigTimezone(api)

package/index.ts

@@ -46,6 +46,7 @@ import {registerAutoUpdate} from './internal/hooks/auto-update'
 import {registerCalendar} from './calendar'
 import {registerCommands} from './command'
 import {setupConfig} from './config-setup'
+import {registerCronHistory} from './cron-history'
 import {registerCronHook} from './cron-hook'
 import {registerEmail} from './email'
 import {registerGateway} from './gateway'
@@ -55,6 +56,7 @@ import {
   registerOutboundHttpRoute,
   registerOutboundMethods,
 } from './http/file/outbound'
+import {registerMediaUnderstanding} from './media-understanding'
 import {registerSkillCommandRestore} from './skill-command-restore'
 import {registerTools} from './tools'
 import type {PluginApi} from './types'
@@ -79,10 +81,12 @@ export default {
     registerCommands(api)
     registerTools(api)
     registerCronHook(api)
+    registerCronHistory(api)
     setupConfig(api)
     registerGateway(api)
     registerAutoPair(api)
     registerAutoUpdate(api)
+    registerMediaUnderstanding(api)
 
     // Email & calendar (optional — requires API base URL + token)
     const gw = getGatewayConfig(api)

package/media-understanding.ts

@@ -0,0 +1,97 @@
+import {PROVIDER_NAME} from './model-gateway-setup'
+import {resolveGatewayCredentials, type GatewayCredentials} from './resolve-gateway-credentials'
+import type {PluginApi} from './types'
+
+async function chatCompletion(
+  creds: GatewayCredentials,
+  content: Array<Record<string, unknown>>,
+  opts: {model: string; timeoutMs: number; maxTokens: number},
+): Promise<{text: string; model?: string}> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), opts.timeoutMs)
+
+  try {
+    const res = await fetch(`${creds.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${creds.token}`,
+      },
+      body: JSON.stringify({
+        model: opts.model,
+        messages: [{role: 'user', content}],
+        max_tokens: opts.maxTokens,
+      }),
+      signal: controller.signal,
+    })
+
+    if (!res.ok) {
+      const errText = await res.text().catch(() => '')
+      throw new Error(`Model gateway returned ${res.status}: ${errText}`)
+    }
+
+    const data = (await res.json()) as {
+      choices?: {message?: {content?: string}}[]
+      model?: string
+    }
+    const text = data.choices?.[0]?.message?.content ?? ''
+    return {text, model: data.model ?? opts.model}
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+function imageToContentPart(buffer: Buffer, mime?: string): Record<string, unknown> {
+  const base64 = buffer.toString('base64')
+  return {type: 'image_url', image_url: {url: `data:${mime || 'image/jpeg'};base64,${base64}`}}
+}
+
+async function describeImageViaGateway(
+  creds: GatewayCredentials,
+  params: Record<string, unknown>,
+): Promise<{text: string; model?: string}> {
+  const content = [
+    {type: 'text', text: (params.prompt as string) || 'Describe the image.'},
+    imageToContentPart(params.buffer as Buffer, params.mime as string | undefined),
+  ]
+  return chatCompletion(creds, content, {
+    model: params.model as string,
+    timeoutMs: (params.timeoutMs as number) || 30_000,
+    maxTokens: (params.maxTokens as number) || 512,
+  })
+}
+
+async function describeImagesViaGateway(
+  creds: GatewayCredentials,
+  params: Record<string, unknown>,
+): Promise<{text: string; model?: string}> {
+  const images = params.images as Array<{buffer: Buffer; fileName?: string; mime?: string}>
+  const content: Array<Record<string, unknown>> = [
+    {type: 'text', text: (params.prompt as string) || 'Describe the images.'},
+    ...images.map((img) => imageToContentPart(img.buffer, img.mime)),
+  ]
+  return chatCompletion(creds, content, {
+    model: params.model as string,
+    timeoutMs: (params.timeoutMs as number) || 30_000,
+    maxTokens: (params.maxTokens as number) || 512,
+  })
+}
+
+export function registerMediaUnderstanding(api: PluginApi): void {
+  if (!api.registerMediaUnderstandingProvider) return
+
+  const creds = resolveGatewayCredentials(api)
+  if (!creds) {
+    api.logger.warn('media-understanding: model gateway credentials not available, skipping')
+    return
+  }
+
+  api.registerMediaUnderstandingProvider({
+    id: PROVIDER_NAME,
+    capabilities: ['image'],
+    describeImage: (...args: unknown[]) =>
+      describeImageViaGateway(creds, args[0] as Record<string, unknown>),
+    describeImages: (...args: unknown[]) =>
+      describeImagesViaGateway(creds, args[0] as Record<string, unknown>),
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.32.0",
+  "version": "1.34.0-beta.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -30,10 +30,12 @@
     "auto-pair.ts",
     "calendar.ts",
     "config-setup.ts",
+    "cron-history.ts",
     "cron-hook.ts",
     "email.ts",
     "gateway-fetch.ts",
     "http",
+    "media-understanding.ts",
     "model-gateway-setup.ts",
     "resolve-gateway-credentials.ts",
     "skill-command-restore.ts",

package/types.ts

@@ -256,6 +256,14 @@ export type PluginApi = {
     stop?: (...args: unknown[]) => void | Promise<void>
   }) => void
   registerProvider: (provider: Record<string, unknown>) => void
+  registerMediaUnderstandingProvider?: (provider: {
+    id: string
+    capabilities?: Array<'image' | 'audio' | 'video'>
+    describeImage?: (...args: unknown[]) => Promise<unknown>
+    describeImages?: (...args: unknown[]) => Promise<unknown>
+    transcribeAudio?: (...args: unknown[]) => Promise<unknown>
+    describeVideo?: (...args: unknown[]) => Promise<unknown>
+  }) => void
   registerContextEngine: (id: string, factory: (...args: unknown[]) => unknown) => void
   resolvePath: (input: string) => string
   on: <K extends PluginHookName>(

package/gateway/memory-browser.md

@@ -1,55 +0,0 @@
-# memory-browser
-
-OpenClaw plugin that exposes the **memory directory** (all `.md` files) as **Gateway WebSocket RPC methods**.
-
-## What you get
-
-Gateway methods (call via WS RPC):
-
-- **`memory-browser.list`** — List all `.md` files in the memory directory (recursive). Returns `{ files: string[] }` (relative paths).
-- **`memory-browser.get`** — Return the content of a single `.md` file. Params: `{ path: string }` (relative path, e.g. `"notes/foo.md"`). Returns `{ path: string, content: string }`.
-
-## Memory directory
-
-The memory directory is resolved in this order:
-
-1. Plugin config `memoryDir` (absolute path)
-2. `<OPENCLAW_STATE_DIR>/memory` (or `<CLAWDBOT_STATE_DIR>/memory`)
-3. `<process.cwd()>/memory`
-
-## Install on a gateway host
-
-1. Put this plugin on the gateway host and make it discoverable, e.g.:
-   - Workspace: `<workspace>/.openclaw/extensions/memory-browser/` with `index.ts` + `openclaw.plugin.json`
-   - Or set `plugins.load.paths` to the plugin folder
-
-2. Enable the plugin in `openclaw.json`:
-
-```json5
-{
-  "plugins": {
-    "enabled": true,
-    "entries": {
-      "memory-browser": { "enabled": true, "config": {} }
-    }
-  }
-}
-```
-
-Optional config: `config.memoryDir` to override the memory directory path.
-
-## Call examples (RPC params)
-
-List all `.md` files:
-
-```json
-{ "method": "memory-browser.list", "params": {} }
-```
-
-Get one file:
-
-```json
-{ "method": "memory-browser.get", "params": { "path": "notes/meeting-2024.md" } }
-```
-
-`path` must be a relative path to a `.md` file inside the memory directory; directory traversal (`..`) is rejected.

package/gateway/plugin-version-management.md

@@ -1,190 +0,0 @@
-# 插件版本管理
-
-## 产品需求
-
-### 背景
-
-OpenClaw 插件以 npm 包形式安装在 gateway 的 `extensions/` 目录下。用户需要一种方式来查询已安装插件的版本、检测是否有更新、并执行更新操作——无需手动 SSH 到服务器执行 CLI 命令。
-
-### 目标
-
-- 通过 Gateway RPC 远程查询任意插件的已安装版本和 npm 最新版本
-- 支持多种更新策略（常规更新、全新安装、强制重装）
-- 更新后可选自动重启 gateway，使新版本立即生效
-
-### 功能需求
-
-1. **版本查询** — 给定 `pluginId` 和 `npmPkgName`，返回已安装版本、npm 最新版本、所有可用版本列表，以及是否有更新。
-2. **插件更新** — 给定 `pluginId`、`npmPkgName` 和更新策略，执行安装或更新操作。支持指定目标版本和更新后自动重启。
-3. **强制重装** — `force` 策略会备份插件配置、删除扩展目录、全新安装、再恢复配置，解决损坏安装或缓存问题。
-
-### 约束
-
-- 仅通过 Gateway WebSocket RPC 调用，不暴露 HTTP 端点。
-- 版本比较仅支持标准 semver，预发布版本（如 `1.0.0-beta.1`）不会被标记为可用更新。
-- npm registry 查询结果缓存 5 分钟（LRU，最多 5 个包），避免频繁请求。
-
----
-
-## 技术设计
-
-### 概览
-
-插件版本管理通过 `gateway/plugins.ts` 注册两个 Gateway RPC 方法，分别负责版本查询和更新执行。
-
-### 数据流
-
-```
-Mobile / Agent
-  │
-  ├─ clawly.plugins.version({ pluginId, npmPkgName })
-  │    ├─ 读取 extensions/<pluginId>/package.json → 已安装版本
-  │    ├─ npm view <npmPkgName> --json → 最新版本 + 所有版本
-  │    └─ isUpdateAvailable(current, latest) → 是否有更新
-  │
-  └─ clawly.plugins.update({ pluginId, npmPkgName, strategy, targetVersion?, restart? })
-       ├─ strategy=install  → openclaw plugins install <pkg>
-       ├─ strategy=update   → openclaw plugins update <pluginId>
-       └─ strategy=force    → 备份配置 → 删除目录 → 安装 → 恢复配置
-            └─ restart=true  → openclaw gateway restart
-```
-
-### Gateway RPC 方法
-
-| 方法 | 参数 | 返回 |
-|---|---|---|
-| `clawly.plugins.version` | `{ pluginId, npmPkgName }` | `VersionResult` |
-| `clawly.plugins.update` | `{ pluginId, npmPkgName, strategy, targetVersion?, restart? }` | `UpdateResult` |
-
-### 关键类型
-
-```typescript
-// clawly.plugins.version 返回
-interface VersionResult {
-  pluginVersion: string | null     // 已安装版本（来自 package.json）
-  npmPackageVersion: string | null // 同上（兼容字段）
-  latestNpmVersion: string | null  // npm registry 最新稳定版
-  allNpmVersions: string[]         // npm registry 所有已发布版本
-  updateAvailable: boolean         // 是否有可用更新
-  error?: string                   // 查询错误（如 npm 不可达）
-}
-
-// clawly.plugins.update 返回
-interface UpdateResult {
-  ok: boolean        // 操作是否成功
-  strategy: string   // 实际使用的策略
-  output?: string    // CLI 输出
-  restarted?: boolean // 是否已重启 gateway
-  error?: string     // 失败时的错误信息
-}
-```
-
-### 更新策略
-
-| 策略 | 行为 | 适用场景 |
-|---|---|---|
-| `install` | `openclaw plugins install <pkg>[@version]` | 首次安装或指定版本安装 |
-| `update` | `openclaw plugins update <pluginId>` | 常规更新到最新版 |
-| `force` | 备份配置 → 删除扩展目录 → 全新安装 → 恢复配置 | 安装损坏、缓存问题、降级 |
-
-### `force` 策略详细流程
-
-1. 读取 `openclaw.json` 中 `plugins.entries.<pluginId>` 的用户配置并保存
-2. 从 `openclaw.json` 删除该插件条目（确保干净安装）
-3. 删除 `extensions/<pluginId>/` 目录
-4. 执行 `openclaw plugins install <pkg>[@version]`
-5. 将保存的用户配置合并回 `openclaw.json`
-
-### 版本检测逻辑
-
-已安装版本从 `<stateDir>/extensions/<pluginId>/package.json` 读取。npm 最新版本通过 `npm view <pkg> --json` 获取。版本比较使用内置 `isUpdateAvailable(current, latest)`：
-
-- 仅比较标准 semver（`major.minor.patch`）
-- `latest` 为预发布版本时返回 `false`（不推荐更新到预发布版）
-- `latest > current` 时返回 `true`
-
-### 缓存
-
-npm registry 查询结果通过 `LruCache` 缓存：
-
-- **容量**: 5 个包
-- **TTL**: 5 分钟
-- 更新操作成功后自动失效对应包的缓存
-
-### 状态目录解析
-
-`stateDir` 按以下优先级解析：
-
-1. `api.runtime.state.resolveStateDir(process.env)`（插件 API 提供）
-2. `OPENCLAW_STATE_DIR` 环境变量
-3. 空字符串（回退，版本查询将返回 `null`）
-
-### 调用示例
-
-查询版本：
-
-```json
-{
-  "method": "clawly.plugins.version",
-  "params": {
-    "pluginId": "clawly-plugins",
-    "npmPkgName": "@AISomething/clawly-plugins"
-  }
-}
-```
-
-常规更新：
-
-```json
-{
-  "method": "clawly.plugins.update",
-  "params": {
-    "pluginId": "clawly-plugins",
-    "npmPkgName": "@AISomething/clawly-plugins",
-    "strategy": "update"
-  }
-}
-```
-
-强制重装并重启 gateway：
-
-```json
-{
-  "method": "clawly.plugins.update",
-  "params": {
-    "pluginId": "clawly-plugins",
-    "npmPkgName": "@AISomething/clawly-plugins",
-    "strategy": "force",
-    "restart": true
-  }
-}
-```
-
-安装指定版本：
-
-```json
-{
-  "method": "clawly.plugins.update",
-  "params": {
-    "pluginId": "clawly-plugins",
-    "npmPkgName": "@AISomething/clawly-plugins",
-    "strategy": "install",
-    "targetVersion": "1.2.3"
-  }
-}
-```
-
-### 错误处理
-
-- 参数缺失返回 `{ code: "invalid_params" }` 错误。
-- 无效 strategy 返回 `{ code: "invalid_params" }` 错误。
-- npm 查询失败时，版本查询仍返回成功，`error` 字段包含错误信息。
-- 更新操作失败时返回 `{ ok: false, error: "..." }`。
-- `force` 策略在恢复配置失败时仅打印警告日志，不影响整体操作结果。
-
-### 不在范围内
-
-- 批量更新多个插件。
-- 插件安装/卸载（使用 `clawhub2gateway` 或 CLI）。
-- 自动定时检查更新。
-- 版本回滚历史记录。