@2en/clawly-plugins 1.32.0-beta.2 → 1.33.1

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

@@ -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

@@ -236,6 +236,66 @@ export function patchBrowser(config: OpenClawConfig): boolean {
 // patchMemorySearch — migrated to clawly-config-defaults.json5
 // patchHeartbeat — migrated to clawly-config-defaults.json5
 
+/** Fields enforced by patchModelDefinitions on every gateway restart. */
+const MODEL_ENFORCED_KEYS = ['contextWindow', 'maxTokens', 'input'] as const
+
+/** Shallow equality — only supports primitives and arrays of primitives. */
+function valuesEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => v === b[i])
+  }
+  return false
+}
+
+/**
+ * Enforce model definitions from defaults onto existing provider model arrays.
+ *
+ * deepMergeDefaults skips arrays ("config wins"), so stale model entries
+ * (e.g. wrong contextWindow from a previous auto target) persist forever.
+ * This patches each existing entry's enforced fields to match the canonical
+ * defaults from clawly-config-defaults.json5.
+ */
+export function patchModelDefinitions(
+  config: OpenClawConfig,
+  defaults: Record<string, unknown>,
+): boolean {
+  const defaultProviders = defaults.models as Record<string, unknown> | undefined
+  const defaultGw = (defaultProviders?.providers as Record<string, unknown> | undefined)?.[
+    PROVIDER_NAME
+  ] as Record<string, unknown> | undefined
+  const defaultModels = defaultGw?.models as Array<Record<string, unknown>> | undefined
+  if (!Array.isArray(defaultModels) || defaultModels.length === 0) return false
+
+  const configGw = config.models?.providers?.[PROVIDER_NAME] as Record<string, unknown> | undefined
+  const configModels = configGw?.models as Array<Record<string, unknown>> | undefined
+  if (!Array.isArray(configModels) || configModels.length === 0) return false
+
+  const defaultsById = new Map<string, Record<string, unknown>>()
+  for (const m of defaultModels) {
+    if (typeof m.id === 'string') defaultsById.set(m.id, m)
+  }
+
+  let dirty = false
+  for (const model of configModels) {
+    const id = model.id
+    if (typeof id !== 'string') continue
+    const canonical = defaultsById.get(id)
+    if (!canonical) continue
+
+    for (const key of MODEL_ENFORCED_KEYS) {
+      const canonicalVal = canonical[key]
+      if (canonicalVal === undefined) continue
+      if (!valuesEqual(model[key], canonicalVal)) {
+        model[key] = Array.isArray(canonicalVal) ? [...canonicalVal] : canonicalVal
+        dirty = true
+      }
+    }
+  }
+
+  return dirty
+}
+
 // TODO: Re-enable patchToolPolicy once rollback-safe (deny is sticky — rolling back
 // the plugin leaves web_search permanently denied). Tracked in ENG-1493.
 // export function patchToolPolicy(config: Record<string, unknown>, pc: ConfigPluginConfig): boolean {
@@ -497,6 +557,42 @@ function loadDefaults(stateDir: string): Record<string, unknown> | null {
   }
 }
 
+/**
+ * Ensure plugins.allow lists every installed non-bundled plugin.
+ *
+ * OpenClaw v2026.3+ enforces an explicit allowlist when non-bundled plugins
+ * are discovered in the extensions directory. Without this, sessions.resolve
+ * fails — which breaks cron delivery (the delivery step resolves the main
+ * session to inject results).
+ *
+ * We derive the set from plugins.installs keys (written by `openclaw plugins
+ * install`) plus 'clawly-plugins' as a baseline. User-installed plugins
+ * (e.g. openclaw-weixin) are picked up automatically because their install
+ * records land in plugins.installs.
+ */
+export function patchPluginsAllow(config: OpenClawConfig): boolean {
+  const plugins = (config.plugins ?? {}) as Record<string, unknown>
+  const installs = asObj(plugins.installs)
+
+  // Collect all installed plugin ids; always include clawly-plugins
+  const required = new Set<string>(['clawly-plugins'])
+  for (const id of Object.keys(installs)) {
+    required.add(id)
+  }
+
+  const existing = Array.isArray(plugins.allow) ? (plugins.allow as string[]) : []
+  const existingSet = new Set(existing)
+
+  // Check if the allowlist already contains all required ids
+  const missing = [...required].filter((id) => !existingSet.has(id))
+  if (missing.length === 0) return false
+
+  // Append missing ids (preserve any manually added entries)
+  plugins.allow = [...existing, ...missing]
+  config.plugins = plugins as OpenClawConfig['plugins']
+  return true
+}
+
 function reconcileRuntimeConfig(
   api: PluginApi,
   config: OpenClawConfig,
@@ -516,6 +612,7 @@ function reconcileRuntimeConfig(
   }
 
   let dirty = false
+  dirty = patchPluginsAllow(config) || dirty
   dirty = patchEnvVars(config, pc, api) || dirty
   dirty = patchAgent(config, pc) || dirty
   dirty = patchGateway(config) || dirty
@@ -525,6 +622,11 @@ function reconcileRuntimeConfig(
   const defaults = loadDefaults(stateDir)
   if (defaults) {
     dirty = deepMergeDefaults(config, defaults) || dirty
+    const modelsDirty = patchModelDefinitions(config, defaults)
+    if (modelsDirty) {
+      api.logger.info('Config setup: patched stale model definitions from defaults.')
+    }
+    dirty = modelsDirty || dirty
   } else {
     api.logger.warn('Config setup: failed to load defaults json5, skipping merge.')
   }

package/gateway/notification.test.ts

@@ -0,0 +1,221 @@
+import {beforeEach, describe, expect, mock, test} from 'bun:test'
+import type {PluginApi} from '../types'
+
+// ── fs mock ──────────────────────────────────────────────────────
+
+const fileSystem = new Map<string, string>()
+
+mock.module('node:fs', () => ({
+  default: {
+    readFileSync: (filePath: string, _encoding: string) => {
+      const content = fileSystem.get(filePath)
+      if (content === undefined) {
+        const err = new Error(`ENOENT: no such file '${filePath}'`) as NodeJS.ErrnoException
+        err.code = 'ENOENT'
+        throw err
+      }
+      if (content === '<<EPERM>>') {
+        const err = new Error(`EPERM: permission denied '${filePath}'`) as NodeJS.ErrnoException
+        err.code = 'EPERM'
+        throw err
+      }
+      return content
+    },
+    existsSync: (filePath: string) => fileSystem.has(filePath),
+    mkdirSync: () => {},
+    writeFileSync: () => {},
+    unlinkSync: () => {},
+  },
+}))
+
+import {getAgentIdentity, parseIdentityFields, resolveAgentTitle} from './notification'
+
+// ── helpers ──────────────────────────────────────────────────────
+
+const logs: {level: string; msg: string}[] = []
+
+function createMockApi(stateDir = '/data'): PluginApi {
+  return {
+    runtime: {state: {resolveStateDir: () => stateDir}},
+    logger: {
+      info: (msg: string) => logs.push({level: 'info', msg}),
+      warn: (msg: string) => logs.push({level: 'warn', msg}),
+      error: (msg: string) => logs.push({level: 'error', msg}),
+    },
+  } as unknown as PluginApi
+}
+
+beforeEach(() => {
+  fileSystem.clear()
+  logs.length = 0
+  delete process.env.OPENCLAW_WORKSPACE
+})
+
+// ── parseIdentityFields ──────────────────────────────────────────
+
+describe('parseIdentityFields', () => {
+  test('parses standard IDENTITY.md format', () => {
+    const content = [
+      '# IDENTITY.md - Who Am I?',
+      '',
+      '- **Name:** Tigermountain',
+      '- **Creature:** AI agent',
+      '- **Emoji:** 🐅',
+      '- **Avatar:** *(none yet)*',
+    ].join('\n')
+    expect(parseIdentityFields(content)).toEqual({name: 'Tigermountain', emoji: '🐅'})
+  })
+
+  test('parses without list markers', () => {
+    const content = 'Name: Alice\nEmoji: 🦊'
+    expect(parseIdentityFields(content)).toEqual({name: 'Alice', emoji: '🦊'})
+  })
+
+  test('strips markdown heading syntax from labels', () => {
+    const content = '## Name: HeadingAgent\n## Emoji: 🎯'
+    expect(parseIdentityFields(content)).toEqual({name: 'HeadingAgent', emoji: '🎯'})
+  })
+
+  test('returns empty when no name or emoji', () => {
+    const content = '- **Creature:** robot\n- **Vibe:** chill'
+    expect(parseIdentityFields(content)).toEqual({})
+  })
+
+  test('returns empty for blank content', () => {
+    expect(parseIdentityFields('')).toEqual({})
+  })
+
+  test('handles Windows line endings', () => {
+    const content = '- **Name:** WinBot\r\n- **Emoji:** 💻\r\n'
+    expect(parseIdentityFields(content)).toEqual({name: 'WinBot', emoji: '💻'})
+  })
+
+  test('handles value without markdown wrapping', () => {
+    const content = '- **Name:** PlainName'
+    expect(parseIdentityFields(content)).toEqual({name: 'PlainName'})
+  })
+
+  test('ignores lines without colon', () => {
+    const content = 'No colon here\nName: Valid'
+    expect(parseIdentityFields(content)).toEqual({name: 'Valid'})
+  })
+})
+
+// ── getAgentIdentity ─────────────────────────────────────────────
+
+describe('getAgentIdentity', () => {
+  test('returns null for undefined agentId', () => {
+    expect(getAgentIdentity(undefined, createMockApi())).toBeNull()
+  })
+
+  test('reads identity from convention workspace path', () => {
+    fileSystem.set('/data/openclaw.json', '{}')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '- **Name:** Tiger\n- **Emoji:** 🐅')
+    expect(getAgentIdentity('clawly', createMockApi())).toEqual({name: 'Tiger', emoji: '🐅'})
+  })
+
+  test('uses explicit workspace from agent config', () => {
+    fileSystem.set(
+      '/data/openclaw.json',
+      JSON.stringify({agents: {list: [{id: 'clawly', workspace: '/custom/ws'}]}}),
+    )
+    fileSystem.set('/custom/ws/IDENTITY.md', '- Name: CustomAgent\n- Emoji: 🎭')
+    expect(getAgentIdentity('clawly', createMockApi())).toEqual({
+      name: 'CustomAgent',
+      emoji: '🎭',
+    })
+  })
+
+  test('does not fall back to default agent workspace', () => {
+    fileSystem.set(
+      '/data/openclaw.json',
+      JSON.stringify({
+        agents: {list: [{id: 'other', default: true, workspace: '/other/ws'}]},
+      }),
+    )
+    fileSystem.set('/other/ws/IDENTITY.md', '- Name: WrongAgent')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '- Name: CorrectAgent')
+    expect(getAgentIdentity('clawly', createMockApi())).toEqual({name: 'CorrectAgent'})
+  })
+
+  test('returns null silently when IDENTITY.md missing (ENOENT)', () => {
+    fileSystem.set('/data/openclaw.json', '{}')
+    expect(getAgentIdentity('clawly', createMockApi())).toBeNull()
+    expect(logs.filter((l) => l.level === 'warn')).toHaveLength(0)
+  })
+
+  test('warns when IDENTITY.md exists but has no name/emoji', () => {
+    fileSystem.set('/data/openclaw.json', '{}')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '- Creature: robot')
+    expect(getAgentIdentity('clawly', createMockApi())).toBeNull()
+    expect(logs).toContainEqual({
+      level: 'warn',
+      msg: expect.stringContaining('no name/emoji found'),
+    })
+  })
+
+  test('warns on IDENTITY.md read error (non-ENOENT)', () => {
+    fileSystem.set('/data/openclaw.json', '{}')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '<<EPERM>>')
+    expect(getAgentIdentity('clawly', createMockApi())).toBeNull()
+    expect(logs).toContainEqual({
+      level: 'warn',
+      msg: expect.stringContaining('failed to read IDENTITY.md'),
+    })
+  })
+
+  test('warns on corrupted openclaw.json (non-ENOENT)', () => {
+    fileSystem.set('/data/openclaw.json', '{invalid json')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '- Name: Tiger')
+    // Still falls back to convention path and reads identity
+    expect(getAgentIdentity('clawly', createMockApi())).toEqual({name: 'Tiger'})
+    expect(logs).toContainEqual({
+      level: 'warn',
+      msg: expect.stringContaining('failed to parse openclaw.json'),
+    })
+  })
+
+  test('ignores OPENCLAW_WORKSPACE when openclaw.json is readable', () => {
+    process.env.OPENCLAW_WORKSPACE = '/env/workspace'
+    fileSystem.set('/data/openclaw.json', '{}')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '- Name: CorrectAgent')
+    fileSystem.set('/env/workspace/IDENTITY.md', '- Name: WrongAgent')
+    expect(getAgentIdentity('clawly', createMockApi())).toEqual({name: 'CorrectAgent'})
+  })
+
+  test('ignores OPENCLAW_WORKSPACE even when openclaw.json is missing', () => {
+    process.env.OPENCLAW_WORKSPACE = '/env/workspace'
+    fileSystem.set('/env/workspace/IDENTITY.md', '- Name: WrongAgent')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '- Name: CorrectAgent')
+    expect(getAgentIdentity('clawly', createMockApi())).toEqual({name: 'CorrectAgent'})
+  })
+
+  test('returns null when stateDir is empty', () => {
+    expect(getAgentIdentity('clawly', createMockApi(''))).toBeNull()
+  })
+})
+
+// ── resolveAgentTitle ────────────────────────────────────────────
+
+describe('resolveAgentTitle', () => {
+  test('returns agent name with emoji', () => {
+    fileSystem.set('/data/openclaw.json', '{}')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '- Name: Tiger\n- Emoji: 🐅')
+    expect(resolveAgentTitle('clawly', createMockApi())).toBe('🐅 Tiger')
+  })
+
+  test('falls back to lobster Clawly when no identity', () => {
+    fileSystem.set('/data/openclaw.json', '{}')
+    expect(resolveAgentTitle('clawly', createMockApi())).toBe('🦞 Clawly')
+  })
+
+  test('uses lobster emoji when name exists but no emoji', () => {
+    fileSystem.set('/data/openclaw.json', '{}')
+    fileSystem.set('/data/workspace-clawly/IDENTITY.md', '- Name: NoEmoji')
+    expect(resolveAgentTitle('clawly', createMockApi())).toBe('🦞 NoEmoji')
+  })
+
+  test('falls back to lobster Clawly when agentId is undefined', () => {
+    expect(resolveAgentTitle(undefined, createMockApi())).toBe('🦞 Clawly')
+  })
+})

package/gateway/notification.ts

@@ -14,13 +14,9 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 
-import {$} from 'zx'
 import type {PluginApi} from '../types'
-import {stripCliLogs} from '../lib/stripCliLogs'
 import {stripMarkdown} from '../lib/stripMarkdown'
 
-$.verbose = false
-
 /** Extract the first emoji from a string, or null if none found. */
 const EMOJI_RE =
   /(?:\p{Emoji_Presentation}|\p{Emoji}\uFE0F)(?:\u200d(?:\p{Emoji_Presentation}|\p{Emoji}\uFE0F))*/u
@@ -120,22 +116,80 @@ function resetBadgeCount(): void {
 }
 
 /**
- * Fetch agent display identity (name, emoji) via gateway RPC.
- * Returns null on failure so the caller can fall back to defaults.
+ * Parse name and emoji from an IDENTITY.md file content.
+ * Mirrors the field extraction in openclaw's parseIdentityMarkdown.
  */
-export async function getAgentIdentity(
+export function parseIdentityFields(content: string): {name?: string; emoji?: string} {
+  const result: {name?: string; emoji?: string} = {}
+  for (const line of content.split(/\r?\n/)) {
+    const cleaned = line.trim().replace(/^-\s*/, '')
+    const colonIdx = cleaned.indexOf(':')
+    if (colonIdx === -1) continue
+    const label = cleaned.slice(0, colonIdx).replace(/[*_#]/g, '').trim().toLowerCase()
+    const value = cleaned
+      .slice(colonIdx + 1)
+      .replace(/^[*_]+|[*_]+$/g, '')
+      .trim()
+    if (!value) continue
+    if (label === 'name') result.name = value
+    if (label === 'emoji') result.emoji = value
+  }
+  return result
+}
+
+/**
+ * Resolve the workspace directory for a given agent by reading openclaw.json.
+ * Falls back to `<stateDir>/workspace-<agentId>` when the agent entry has no explicit workspace.
+ */
+function resolveWorkspaceDir(api: PluginApi, agentId: string): string | null {
+  const stateDir = api.runtime.state.resolveStateDir()
+  if (!stateDir) return null
+  try {
+    const raw = fs.readFileSync(path.join(stateDir, 'openclaw.json'), 'utf-8')
+    const config = JSON.parse(raw)
+    const agents: Array<{id?: string; default?: boolean; workspace?: string}> = Array.isArray(
+      config?.agents?.list,
+    )
+      ? config.agents.list
+      : []
+    const agent = agents.find((a) => a.id === agentId)
+    if (agent?.workspace) return agent.workspace
+    // Config parsed successfully — use convention path, not env var (which may belong to a different agent)
+    return path.join(stateDir, `workspace-${agentId}`)
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      api.logger.warn(
+        `notification: failed to parse openclaw.json for agentId=${agentId}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  }
+  // openclaw.json unreadable — use convention path (stateDir is always available)
+  return path.join(stateDir, `workspace-${agentId}`)
+}
+
+/**
+ * Read agent display identity (name, emoji) directly from IDENTITY.md.
+ * Avoids the CLI→WebSocket roundtrip that fails under gateway load.
+ */
+export function getAgentIdentity(
   agentId: string | undefined,
-): Promise<{name?: string; emoji?: string} | null> {
+  api: PluginApi,
+): {name?: string; emoji?: string} | null {
   if (!agentId) return null
+  const wsDir = resolveWorkspaceDir(api, agentId)
+  if (!wsDir) return null
   try {
-    const rpcParams = JSON.stringify({agentId})
-    const result = await $`openclaw gateway call agent.identity.get --json --params ${rpcParams}`
-    const parsed = JSON.parse(stripCliLogs(result.stdout))
-    return {
-      name: typeof parsed.name === 'string' ? parsed.name : undefined,
-      emoji: typeof parsed.emoji === 'string' ? parsed.emoji : undefined,
+    const content = fs.readFileSync(path.join(wsDir, 'IDENTITY.md'), 'utf-8')
+    const fields = parseIdentityFields(content)
+    if (fields.name || fields.emoji) return fields
+    api.logger.warn(`notification: IDENTITY.md parsed but no name/emoji found (agentId=${agentId})`)
+    return null
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      api.logger.warn(
+        `notification: failed to read IDENTITY.md for agentId=${agentId}: ${err instanceof Error ? err.message : String(err)}`,
+      )
     }
-  } catch {
     return null
   }
 }
@@ -144,8 +198,8 @@ export async function getAgentIdentity(
  * Build a push notification title from agent identity.
  * Falls back to "🦞 Clawly" when identity is unavailable.
  */
-export async function resolveAgentTitle(agentId?: string): Promise<string> {
-  const identity = await getAgentIdentity(agentId)
+export function resolveAgentTitle(agentId: string | undefined, api: PluginApi): string {
+  const identity = getAgentIdentity(agentId, api)
   const emoji = extractEmoji(identity?.emoji) ?? '🦞'
   return `${emoji} ${identity?.name ?? 'Clawly'}`
 }
@@ -161,7 +215,7 @@ export async function sendPushNotification(
     return false
   }
 
-  const title = stripMarkdown(opts.title ?? (await resolveAgentTitle(opts.agentId)))
+  const title = stripMarkdown(opts.title ?? resolveAgentTitle(opts.agentId, api))
   const body = stripMarkdown(opts.body)
   if (!body) {
     api.logger.warn('notification: body stripped to empty, skipping push')
@@ -255,7 +309,25 @@ export function registerNotification(api: PluginApi) {
     respond(true, {cleared: true})
   })
 
+  api.registerGatewayMethod('clawly.notification.clearToken', async ({respond}) => {
+    let fileCleared = true
+    try {
+      await fs.promises.unlink(TOKEN_FILE)
+    } catch (err) {
+      // ENOENT is fine — file already gone.
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        fileCleared = false
+        api.logger.warn(
+          `notification: failed to delete token file: ${err instanceof Error ? err.message : String(err)}`,
+        )
+      }
+    }
+    if (fileCleared) resetBadgeCount()
+    api.logger.info(`notification: push token cleared (fileCleared=${fileCleared})`)
+    respond(fileCleared, {cleared: fileCleared})
+  })
+
   api.logger.info(
-    'notification: registered clawly.notification.setToken + clawly.notification.send + clawly.notification.clearBadge',
+    'notification: registered clawly.notification.setToken + clawly.notification.send + clawly.notification.clearBadge + clawly.notification.clearToken',
   )
 }

package/gateway/weixin-login.test.ts

@@ -0,0 +1,110 @@
+import {afterEach, describe, expect, mock, test} from 'bun:test'
+import type {PluginApi} from '../types'
+import {
+  ensureWeixinBinding,
+  resetBindingEnsureInFlight,
+  resolveDefaultAgentId,
+} from './weixin-login'
+
+// ---------------------------------------------------------------------------
+// resolveDefaultAgentId
+// ---------------------------------------------------------------------------
+
+describe('resolveDefaultAgentId', () => {
+  test('returns "clawly" when agents.list is empty', () => {
+    expect(resolveDefaultAgentId({agents: {list: []}} as any)).toBe('clawly')
+  })
+
+  test('returns "clawly" when agents is undefined', () => {
+    expect(resolveDefaultAgentId({} as any)).toBe('clawly')
+  })
+
+  test('returns the default agent id', () => {
+    const config = {
+      agents: {list: [{id: 'other'}, {id: 'mybot', default: true}]},
+    }
+    expect(resolveDefaultAgentId(config as any)).toBe('mybot')
+  })
+
+  test('returns first agent when none marked default', () => {
+    const config = {agents: {list: [{id: 'alpha'}, {id: 'beta'}]}}
+    expect(resolveDefaultAgentId(config as any)).toBe('alpha')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ensureWeixinBinding
+// ---------------------------------------------------------------------------
+
+function createMockApi(config: Record<string, unknown> = {}) {
+  return {
+    runtime: {
+      config: {
+        loadConfig: mock(() => config),
+        writeConfigFile: mock(() => Promise.resolve()),
+      },
+    },
+    logger: {
+      info: mock(() => {}),
+      warn: mock(() => {}),
+    },
+  } as unknown as PluginApi
+}
+
+describe('ensureWeixinBinding', () => {
+  afterEach(() => resetBindingEnsureInFlight())
+
+  test('skips write when binding already exists', async () => {
+    const api = createMockApi({
+      bindings: [{agentId: 'clawly', match: {channel: 'openclaw-weixin'}}],
+    })
+    await ensureWeixinBinding(api)
+    expect(api.runtime.config.writeConfigFile).not.toHaveBeenCalled()
+  })
+
+  test('writes binding when none exists', async () => {
+    const api = createMockApi({agents: {list: [{id: 'clawly', default: true}]}})
+    await ensureWeixinBinding(api)
+    expect(api.runtime.config.writeConfigFile).toHaveBeenCalledTimes(1)
+    const written = (api.runtime.config.writeConfigFile as ReturnType<typeof mock>).mock.calls[0][0]
+    expect(written.bindings).toEqual([{agentId: 'clawly', match: {channel: 'openclaw-weixin'}}])
+  })
+
+  test('returns silently when loadConfig throws', async () => {
+    const api = createMockApi()
+    ;(api.runtime.config.loadConfig as ReturnType<typeof mock>).mockImplementation(() => {
+      throw new Error('corrupted')
+    })
+    await ensureWeixinBinding(api)
+    expect(api.runtime.config.writeConfigFile).not.toHaveBeenCalled()
+  })
+
+  test('resets in-flight flag after loadConfig throws', async () => {
+    const api = createMockApi()
+    ;(api.runtime.config.loadConfig as ReturnType<typeof mock>).mockImplementation(() => {
+      throw new Error('corrupted')
+    })
+    await ensureWeixinBinding(api)
+    // Second call should not be blocked
+    ;(api.runtime.config.loadConfig as ReturnType<typeof mock>).mockImplementation(() => ({}))
+    await ensureWeixinBinding(api)
+    expect(api.runtime.config.writeConfigFile).toHaveBeenCalledTimes(1)
+  })
+
+  test('concurrent call is a no-op while in-flight', async () => {
+    let resolveWrite!: () => void
+    const api = createMockApi({})
+    ;(api.runtime.config.writeConfigFile as ReturnType<typeof mock>).mockImplementation(
+      () =>
+        new Promise<void>((r) => {
+          resolveWrite = r
+        }),
+    )
+    const first = ensureWeixinBinding(api)
+    // Second call while first is awaiting writeConfigFile
+    await ensureWeixinBinding(api)
+    expect(api.runtime.config.writeConfigFile).toHaveBeenCalledTimes(1)
+    resolveWrite()
+    await first
+  })
+})

package/gateway/weixin-login.ts

@@ -10,6 +10,7 @@
  *   clawly.weixin.login.wait  → { connected, message }
  */
 
+import type {OpenClawConfig} from '../types/openclaw'
 import type {PluginApi} from '../types'
 
 const WEIXIN_CHANNEL_ID = 'openclaw-weixin'
@@ -73,6 +74,66 @@ function resolveWeixinPlugin(logger?: {warn: (msg: string) => void}): ChannelPlu
   }
 }
 
+/**
+ * Resolve the default agent ID from config (first default agent, or first agent, or 'clawly').
+ */
+/** @internal exported for testing */
+export function resolveDefaultAgentId(config: OpenClawConfig): string {
+  const list = config.agents?.list
+  if (!Array.isArray(list) || list.length === 0) return 'clawly'
+  const defaultAgent = list.find((a) => a.default) ?? list[0]
+  return defaultAgent?.id ?? 'clawly'
+}
+
+/**
+ * Ensure a binding exists for openclaw-weixin → default agent.
+ * Bindings changes are classified as "none" in OpenClaw's config-reload,
+ * so this does NOT trigger a gateway restart.
+ */
+/** @internal exported for testing */
+export let bindingEnsureInFlight = false
+
+/** @internal reset for testing */
+export function resetBindingEnsureInFlight() {
+  bindingEnsureInFlight = false
+}
+
+/** @internal exported for testing */
+export async function ensureWeixinBinding(api: PluginApi): Promise<void> {
+  if (bindingEnsureInFlight) return
+  bindingEnsureInFlight = true
+  try {
+    let config: OpenClawConfig
+    try {
+      config = {...(api.runtime.config.loadConfig() as OpenClawConfig)}
+    } catch {
+      return
+    }
+
+    const bindings = Array.isArray(config.bindings) ? config.bindings : []
+    const agentId = resolveDefaultAgentId(config)
+    const hasValidBinding = bindings.some(
+      (b) => b.match?.channel === WEIXIN_CHANNEL_ID && b.agentId === agentId,
+    )
+    if (hasValidBinding) return
+
+    // Remove any stale weixin bindings (pointing to a different agent), then add the current one.
+    const filtered = bindings.filter((b) => b.match?.channel !== WEIXIN_CHANNEL_ID)
+    config.bindings = [...filtered, {agentId, match: {channel: WEIXIN_CHANNEL_ID}}]
+
+    try {
+      await api.runtime.config.writeConfigFile(config)
+      api.logger.info(`weixin-login: created binding ${WEIXIN_CHANNEL_ID} → ${agentId}`)
+    } catch (err) {
+      api.logger.warn(
+        `weixin-login: failed to write binding: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  } finally {
+    bindingEnsureInFlight = false
+  }
+}
+
 export function registerWeixinLogin(api: PluginApi) {
   api.registerGatewayMethod('clawly.weixin.login.start', async ({params, respond}) => {
     const plugin = resolveWeixinPlugin(api.logger)
@@ -98,6 +159,9 @@ export function registerWeixinLogin(api: PluginApi) {
         GATEWAY_TIMEOUT_MS,
         'loginWithQrStart',
       )
+      // Ensure routing binding exists before responding — if the user scans
+      // the QR code and WeChat connects, messages need to be routed immediately.
+      await ensureWeixinBinding(api)
       respond(true, result)
     } catch (err) {
       respond(false, undefined, {

package/index.ts

@@ -55,6 +55,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'
@@ -83,6 +84,7 @@ export default {
     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,44 @@
+import {PROVIDER_NAME} from './model-gateway-setup'
+import type {PluginApi} from './types'
+
+type MediaSdk = {
+  describeImageWithModel: (...args: unknown[]) => Promise<unknown>
+  describeImagesWithModel: (...args: unknown[]) => Promise<unknown>
+}
+
+let sdkPromise: Promise<MediaSdk | null> | null = null
+
+function loadSdk(logger: PluginApi['logger']): Promise<MediaSdk | null> {
+  if (!sdkPromise) {
+    sdkPromise = import('openclaw/plugin-sdk/media-understanding').catch((err: unknown) => {
+      const code = (err as NodeJS.ErrnoException)?.code
+      if (code === 'ERR_MODULE_NOT_FOUND' || code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+        logger.warn(
+          'media-understanding: openclaw/plugin-sdk/media-understanding not available, skipping',
+        )
+        return null
+      }
+      throw err
+    })
+  }
+  return sdkPromise
+}
+
+export function registerMediaUnderstanding(api: PluginApi): void {
+  if (!api.registerMediaUnderstandingProvider) return
+
+  api.registerMediaUnderstandingProvider({
+    id: PROVIDER_NAME,
+    capabilities: ['image'],
+    describeImage: async (...args: unknown[]) => {
+      const sdk = await loadSdk(api.logger)
+      if (!sdk) return undefined
+      return sdk.describeImageWithModel(...args)
+    },
+    describeImages: async (...args: unknown[]) => {
+      const sdk = await loadSdk(api.logger)
+      if (!sdk) return undefined
+      return sdk.describeImagesWithModel(...args)
+    },
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.32.0-beta.2",
+  "version": "1.33.1",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -34,6 +34,7 @@
     "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>(