@2en/clawly-plugins 1.22.2 → 1.23.0

package/config-setup.ts

@@ -0,0 +1,383 @@
+/**
+ * On plugin init, patches openclaw.json to set all business config that was
+ * previously written by provision's buildConfig().
+ *
+ * Domain helpers read the pluginConfig, apply enforce or set-if-missing
+ * semantics, and write once if anything changed.  This runs before
+ * setupModelGateway so agents.defaults.model is available for the model
+ * provider setup.
+ *
+ * Backward compatibility: old sprites have pluginConfig with only 4 fields
+ * (skill/model gateway credentials). Helpers check for the new fields and
+ * skip gracefully when absent.
+ */
+
+import path from 'node:path'
+
+import type {PluginApi} from './index'
+import {
+  PROVIDER_NAME,
+  patchModelGateway,
+  readOpenclawConfig,
+  resolveStateDir,
+  writeOpenclawConfig,
+} from './model-gateway-setup'
+
+export interface ConfigPluginConfig {
+  agentId?: string
+  agentName?: string
+  workspaceDir?: string
+  defaultModel?: string
+  defaultImageModel?: string
+  sessionMainKey?: string
+  elevenlabsApiKey?: string
+  elevenlabsVoiceId?: string
+  braveSearchApiKey?: string
+}
+
+function toPC(api: PluginApi): ConfigPluginConfig {
+  return (api.pluginConfig ?? {}) as ConfigPluginConfig
+}
+
+// ---------------------------------------------------------------------------
+// Domain helpers — each returns true when config was mutated
+// ---------------------------------------------------------------------------
+
+export function patchAgent(config: Record<string, unknown>, pc: ConfigPluginConfig): boolean {
+  if (!pc.agentId) return false
+
+  let dirty = false
+  const agents = (config.agents ?? {}) as Record<string, unknown>
+  const defaults = (agents.defaults ?? {}) as Record<string, unknown>
+
+  // agents.list: find-or-create entry by id, then enforce our fields only
+  const list = (Array.isArray(agents.list) ? agents.list : []) as Record<string, unknown>[]
+  let entry = list.find((e) => e.id === pc.agentId)
+  if (!entry) {
+    entry = {id: pc.agentId}
+    list.push(entry)
+    dirty = true
+  }
+  const agentName = pc.agentName ?? 'Clawly'
+  if (entry.name !== agentName) {
+    entry.name = agentName
+    dirty = true
+  }
+  if (entry.default !== true) {
+    entry.default = true
+    dirty = true
+  }
+  const workspace = pc.workspaceDir ?? ''
+  if (entry.workspace !== workspace) {
+    entry.workspace = workspace
+    dirty = true
+  }
+  if (agents.list !== list) {
+    agents.list = list
+    dirty = true
+  }
+
+  // model: set-if-missing
+  if (pc.defaultModel && !defaults.model) {
+    defaults.model = {primary: `${PROVIDER_NAME}/${pc.defaultModel}`}
+    dirty = true
+  }
+
+  // imageModel: set-if-missing
+  if (pc.defaultImageModel && !defaults.imageModel) {
+    defaults.imageModel = {
+      primary: `${PROVIDER_NAME}/${pc.defaultImageModel}`,
+      fallbacks: [],
+    }
+    dirty = true
+  }
+
+  // sandbox.mode: enforce (only set the field we care about)
+  const sandbox = (defaults.sandbox ?? {}) as Record<string, unknown>
+  if (sandbox.mode !== 'off') {
+    sandbox.mode = 'off'
+    defaults.sandbox = sandbox
+    dirty = true
+  }
+
+  // verboseDefault: set-if-missing
+  if (defaults.verboseDefault === undefined) {
+    defaults.verboseDefault = 'on'
+    dirty = true
+  }
+
+  if (dirty) {
+    agents.defaults = defaults
+    config.agents = agents
+  }
+
+  return dirty
+}
+
+export function patchGateway(config: Record<string, unknown>): boolean {
+  let dirty = false
+  const gateway = (config.gateway ?? {}) as Record<string, unknown>
+
+  if (gateway.mode !== 'local') {
+    gateway.mode = 'local'
+    dirty = true
+  }
+
+  // http.endpoints.chatCompletions.enabled: enforce (only set the field we care about)
+  const http = (gateway.http ?? {}) as Record<string, unknown>
+  const endpoints = (http.endpoints ?? {}) as Record<string, unknown>
+  const chatCompletions = (endpoints.chatCompletions ?? {}) as Record<string, unknown>
+  if (chatCompletions.enabled !== true) {
+    chatCompletions.enabled = true
+    endpoints.chatCompletions = chatCompletions
+    http.endpoints = endpoints
+    gateway.http = http
+    dirty = true
+  }
+
+  const desiredProxies = ['0.0.0.0/0']
+  if (JSON.stringify(gateway.trustedProxies) !== JSON.stringify(desiredProxies)) {
+    gateway.trustedProxies = desiredProxies
+    dirty = true
+  }
+
+  if (dirty) config.gateway = gateway
+  return dirty
+}
+
+export function patchBrowser(config: Record<string, unknown>): boolean {
+  let dirty = false
+
+  // browser: enforce individual fields only
+  const browser = (config.browser ?? {}) as Record<string, unknown>
+  if (browser.headless !== true) {
+    browser.headless = true
+    dirty = true
+  }
+  if (browser.noSandbox !== true) {
+    browser.noSandbox = true
+    dirty = true
+  }
+  if (browser.attachOnly !== false) {
+    browser.attachOnly = false
+    dirty = true
+  }
+  if (dirty) config.browser = browser
+
+  // commands: enforce individual fields only
+  const commands = (config.commands ?? {}) as Record<string, unknown>
+  if (commands.restart !== true) {
+    commands.restart = true
+    config.commands = commands
+    dirty = true
+  }
+
+  return dirty
+}
+
+export function patchSessionMainKey(
+  config: Record<string, unknown>,
+  pc: ConfigPluginConfig,
+): boolean {
+  if (!pc.sessionMainKey) return false
+
+  const session = (config.session ?? {}) as Record<string, unknown>
+  if (session.mainKey === pc.sessionMainKey) return false
+
+  session.mainKey = pc.sessionMainKey
+  config.session = session
+  return true
+}
+
+export function patchTts(config: Record<string, unknown>, pc: ConfigPluginConfig): boolean {
+  if (!pc.elevenlabsApiKey) return false
+
+  let dirty = false
+  const messages = (config.messages ?? {}) as Record<string, unknown>
+  const tts = (messages.tts ?? {}) as Record<string, unknown>
+  const elevenlabs = (tts.elevenlabs ?? {}) as Record<string, unknown>
+
+  // Credentials: enforce
+  if (elevenlabs.apiKey !== pc.elevenlabsApiKey) {
+    elevenlabs.apiKey = pc.elevenlabsApiKey
+    dirty = true
+  }
+  if (elevenlabs.baseUrl !== 'https://api.elevenlabs.io') {
+    elevenlabs.baseUrl = 'https://api.elevenlabs.io'
+    dirty = true
+  }
+  const voiceId = pc.elevenlabsVoiceId ?? ''
+  if (elevenlabs.voiceId !== voiceId) {
+    elevenlabs.voiceId = voiceId
+    dirty = true
+  }
+
+  // Tuning: set-if-missing
+  if (tts.auto === undefined) {
+    tts.auto = 'tagged'
+    dirty = true
+  }
+  if (tts.mode === undefined) {
+    tts.mode = 'final'
+    dirty = true
+  }
+  if (tts.provider === undefined) {
+    tts.provider = 'elevenlabs'
+    dirty = true
+  }
+  if (tts.summaryModel === undefined && pc.defaultModel) {
+    tts.summaryModel = `${PROVIDER_NAME}/${pc.defaultModel}`
+    dirty = true
+  }
+  if (tts.modelOverrides === undefined) {
+    tts.modelOverrides = {enabled: true}
+    dirty = true
+  }
+  if (tts.maxTextLength === undefined) {
+    tts.maxTextLength = 4000
+    dirty = true
+  }
+  if (tts.timeoutMs === undefined) {
+    tts.timeoutMs = 30000
+    dirty = true
+  }
+  if (tts.prefsPath === undefined) {
+    tts.prefsPath = '~/.openclaw/settings/tts.json'
+    dirty = true
+  }
+
+  // elevenlabs tuning: set-if-missing
+  if (elevenlabs.modelId === undefined) {
+    elevenlabs.modelId = 'eleven_multilingual_v2'
+    dirty = true
+  }
+  if (elevenlabs.seed === undefined) {
+    elevenlabs.seed = 42
+    dirty = true
+  }
+  if (elevenlabs.applyTextNormalization === undefined) {
+    elevenlabs.applyTextNormalization = 'auto'
+    dirty = true
+  }
+  if (elevenlabs.languageCode === undefined) {
+    elevenlabs.languageCode = 'en'
+    dirty = true
+  }
+  if (elevenlabs.voiceSettings === undefined) {
+    elevenlabs.voiceSettings = {
+      stability: 0.5,
+      similarityBoost: 0.75,
+      style: 0.0,
+      useSpeakerBoost: true,
+      speed: 1.0,
+    }
+    dirty = true
+  }
+
+  if (dirty) {
+    tts.elevenlabs = elevenlabs
+    messages.tts = tts
+    config.messages = messages
+  }
+
+  return dirty
+}
+
+export function patchWebSearch(config: Record<string, unknown>, pc: ConfigPluginConfig): boolean {
+  if (!pc.braveSearchApiKey) return false
+
+  let dirty = false
+  const tools = (config.tools ?? {}) as Record<string, unknown>
+  const web = (tools.web ?? {}) as Record<string, unknown>
+  const search = (web.search ?? {}) as Record<string, unknown>
+
+  // Credentials: enforce
+  if (search.provider !== 'brave') {
+    search.provider = 'brave'
+    dirty = true
+  }
+  if (search.apiKey !== pc.braveSearchApiKey) {
+    search.apiKey = pc.braveSearchApiKey
+    dirty = true
+  }
+
+  // Tuning: set-if-missing
+  if (search.maxResults === undefined) {
+    search.maxResults = 5
+    dirty = true
+  }
+  if (search.timeoutSeconds === undefined) {
+    search.timeoutSeconds = 30
+    dirty = true
+  }
+
+  if (dirty) {
+    web.search = search
+    tools.web = web
+    config.tools = tools
+  }
+
+  return dirty
+}
+
+export function patchSession(config: Record<string, unknown>): boolean {
+  let dirty = false
+
+  // session.dmScope: enforce
+  const session = (config.session ?? {}) as Record<string, unknown>
+  if (session.dmScope !== 'per-channel-peer') {
+    session.dmScope = 'per-channel-peer'
+    config.session = session
+    dirty = true
+  }
+
+  // tools.sessions.visibility: enforce
+  const tools = (config.tools ?? {}) as Record<string, unknown>
+  const sessions = (tools.sessions ?? {}) as Record<string, unknown>
+  if (sessions.visibility !== 'agent') {
+    sessions.visibility = 'agent'
+    tools.sessions = sessions
+    config.tools = tools
+    dirty = true
+  }
+
+  return dirty
+}
+
+// ---------------------------------------------------------------------------
+// Entry point — single read, patch all, single write
+// ---------------------------------------------------------------------------
+
+export function setupConfig(api: PluginApi): void {
+  const stateDir = resolveStateDir(api)
+  if (!stateDir) {
+    api.logger.warn('Cannot resolve state dir — config setup skipped.')
+    return
+  }
+
+  const configPath = path.join(stateDir, 'openclaw.json')
+  const config = readOpenclawConfig(configPath)
+  const pc = toPC(api)
+
+  let dirty = false
+  dirty = patchAgent(config, pc) || dirty
+  dirty = patchGateway(config) || dirty
+  dirty = patchBrowser(config) || dirty
+  dirty = patchSessionMainKey(config, pc) || dirty
+  dirty = patchSession(config) || dirty
+  dirty = patchTts(config, pc) || dirty
+  dirty = patchWebSearch(config, pc) || dirty
+  dirty = patchModelGateway(config, api) || dirty
+
+  if (!dirty) {
+    api.logger.info('Config setup: no changes needed.')
+    return
+  }
+
+  try {
+    writeOpenclawConfig(configPath, config)
+    api.logger.info('Config setup: patched openclaw.json.')
+  } catch (err) {
+    api.logger.error(`Config setup failed: ${(err as Error).message}`)
+  }
+}

package/gateway/offline-push.test.ts

@@ -279,9 +279,20 @@ describe('shouldSkipPushForMessage', () => {
     expect(shouldSkipPushForMessage('All good. HEARTBEAT_OK')).toBe('heartbeat ack')
   })
 
-  test('does not skip long message containing HEARTBEAT_OK', () => {
-    const longMsg = 'HEARTBEAT_OK ' + 'x'.repeat(400)
-    expect(shouldSkipPushForMessage(longMsg)).toBeNull()
+  test('skips verbose heartbeat ack ending with HEARTBEAT_OK', () => {
+    const verbose =
+      'The user said hello recently. Looking at HEARTBEAT.md checklist: nothing needs attention. HEARTBEAT_OK'
+    expect(shouldSkipPushForMessage(verbose)).toBe('heartbeat ack')
+  })
+
+  test('does not skip message mentioning HEARTBEAT_OK mid-text', () => {
+    expect(
+      shouldSkipPushForMessage('HEARTBEAT_OK is a status code I output after each check.'),
+    ).toBeNull()
+  })
+
+  test('skips heartbeat ack with non-ASCII trailing punctuation', () => {
+    expect(shouldSkipPushForMessage('Nothing to report. HEARTBEAT_OK。')).toBe('heartbeat ack')
   })
 
   test('skips system prompt leak', () => {

package/gateway/offline-push.ts

@@ -79,8 +79,8 @@ export function shouldSkipPushForMessage(text: string): string | null {
   // Agent sentinel "nothing to say" — mobile hides as "silentReply"
   if (trimmed === 'NO_REPLY') return 'silent reply'
 
-  // Short heartbeat acknowledgment — mobile hides as "heartbeatAck"
-  if (text.includes('HEARTBEAT_OK') && text.length < 400) return 'heartbeat ack'
+  // Heartbeat acknowledgment (HEARTBEAT_OK as ending sentinel) — mobile hides as "heartbeatAck"
+  if (/HEARTBEAT_OK[\p{P}\s]*$/u.test(text)) return 'heartbeat ack'
 
   // Agent echoed system prompt metadata — mobile hides as "systemPromptLeak"
   if (text.includes('Conversation info (untrusted metadata)')) return 'system prompt leak'

package/index.ts

@@ -32,13 +32,12 @@
 import {registerAutoPair} from './auto-pair'
 import {registerCalendar} from './calendar'
 import {registerCommands} from './command'
+import {setupConfig} from './config-setup'
 import {registerCronHook} from './cron-hook'
 import {registerEmail} from './email'
 import {registerGateway} from './gateway'
 import {getGatewayConfig} from './gateway-fetch'
-import {setupModelGateway} from './model-gateway-setup'
 import {registerOutboundHook, registerOutboundHttpRoute, registerOutboundMethods} from './outbound'
-import {setupSession} from './session-setup'
 import {registerSkillCommandRestore} from './skill-command-restore'
 import {registerTools} from './tools'
 
@@ -184,10 +183,9 @@ export default {
     registerCommands(api)
     registerTools(api)
     registerCronHook(api)
+    setupConfig(api)
     registerGateway(api)
     registerAutoPair(api)
-    setupModelGateway(api)
-    setupSession(api)
 
     // Email & calendar (optional — requires skillGatewayBaseUrl + skillGatewayToken in config)
     const gw = getGatewayConfig(api)

package/model-gateway-setup.ts

@@ -83,16 +83,7 @@ export function writeOpenclawConfig(configPath: string, config: Record<string, u
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
 }
 
-export function setupModelGateway(api: PluginApi): void {
-  const stateDir = resolveStateDir(api)
-  if (!stateDir) {
-    api.logger.warn('Cannot resolve state dir — model gateway setup skipped.')
-    return
-  }
-
-  const configPath = path.join(stateDir, 'openclaw.json')
-  const config = readOpenclawConfig(configPath)
-
+export function patchModelGateway(config: Record<string, unknown>, api: PluginApi): boolean {
   // If provider already exists, check if extra models or aliases need updating.
   // This runs before the credentials check because provisioned sprites have
   // credentials in openclaw.json directly, not in pluginConfig.
@@ -150,16 +141,11 @@ export function setupModelGateway(api: PluginApi): void {
       defaults.models = existingAliases
       agents.defaults = defaults
       config.agents = agents
-      try {
-        writeOpenclawConfig(configPath, config)
-        api.logger.info(`Model gateway updated: appended missing extra models/aliases.`)
-      } catch (err) {
-        api.logger.error(`Failed to update model gateway: ${(err as Error).message}`)
-      }
+      api.logger.info(`Model gateway updated: appended missing extra models/aliases.`)
     } else {
       api.logger.info('Model gateway provider already configured.')
     }
-    return
+    return dirty
   }
 
   // No existing provider — need pluginConfig credentials to create one
@@ -170,7 +156,7 @@ export function setupModelGateway(api: PluginApi): void {
 
   if (!baseUrl || !token) {
     api.logger.info('Model gateway not configured (missing baseUrl or token), skipping.')
-    return
+    return false
   }
 
   // Derive model IDs from agents.defaults
@@ -187,7 +173,7 @@ export function setupModelGateway(api: PluginApi): void {
 
   if (!defaultModel) {
     api.logger.warn('No default model found in agents.defaults — model gateway setup skipped.')
-    return
+    return false
   }
 
   const defaultModels =
@@ -233,9 +219,25 @@ export function setupModelGateway(api: PluginApi): void {
   agents.defaults = defaults
   config.agents = agents
 
+  api.logger.info(`Model gateway provider configured: ${baseUrl} with ${models.length} model(s).`)
+  return true
+}
+
+/** Standalone wrapper — reads config, patches, writes. Used by tests. */
+export function setupModelGateway(api: PluginApi): void {
+  const stateDir = resolveStateDir(api)
+  if (!stateDir) {
+    api.logger.warn('Cannot resolve state dir — model gateway setup skipped.')
+    return
+  }
+
+  const configPath = path.join(stateDir, 'openclaw.json')
+  const config = readOpenclawConfig(configPath)
+
+  if (!patchModelGateway(config, api)) return
+
   try {
     writeOpenclawConfig(configPath, config)
-    api.logger.info(`Model gateway provider configured: ${baseUrl} with ${models.length} model(s).`)
   } catch (err) {
     api.logger.error(`Failed to setup model gateway: ${(err as Error).message}`)
   }

package/openclaw.plugin.json

@@ -38,7 +38,7 @@
   },
   "configSchema": {
     "type": "object",
-    "additionalProperties": false,
+    "additionalProperties": true,
     "properties": {
       "memoryDir": { "type": "string", "minLength": 1 },
       "bin": { "type": "string", "minLength": 1 },
@@ -49,7 +49,16 @@
       "skillGatewayBaseUrl": { "type": "string" },
       "skillGatewayToken": { "type": "string" },
       "modelGatewayBaseUrl": { "type": "string" },
-      "modelGatewayToken": { "type": "string" }
+      "modelGatewayToken": { "type": "string" },
+      "agentId": { "type": "string" },
+      "agentName": { "type": "string" },
+      "workspaceDir": { "type": "string" },
+      "defaultModel": { "type": "string" },
+      "defaultImageModel": { "type": "string" },
+      "sessionMainKey": { "type": "string" },
+      "elevenlabsApiKey": { "type": "string" },
+      "elevenlabsVoiceId": { "type": "string" },
+      "braveSearchApiKey": { "type": "string" }
     },
     "required": []
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.22.2",
+  "version": "1.23.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -19,12 +19,12 @@
     "index.ts",
     "auto-pair.ts",
     "calendar.ts",
+    "config-setup.ts",
     "cron-hook.ts",
     "email.ts",
     "gateway-fetch.ts",
     "outbound.ts",
     "model-gateway-setup.ts",
-    "session-setup.ts",
     "skill-command-restore.ts",
     "openclaw.plugin.json"
   ],

package/session-setup.ts

@@ -1,61 +0,0 @@
-/**
- * On plugin init, patches openclaw.json to:
- * 1. Set `session.dmScope` to "per-channel-peer" — isolates Telegram (and
- *    other channel) DMs from the Clawly mobile session.
- * 2. Set `tools.sessions.visibility` to "agent" — lets the agent read
- *    conversation history from other sessions under the same agent (e.g.
- *    reference recent Telegram chats from the mobile session).
- *
- * Runs synchronously during plugin registration, same pattern as
- * model-gateway-setup.ts.
- */
-
-import path from 'node:path'
-
-import type {PluginApi} from './index'
-import {readOpenclawConfig, resolveStateDir, writeOpenclawConfig} from './model-gateway-setup'
-
-const DESIRED_DM_SCOPE = 'per-channel-peer'
-const DESIRED_SESSION_VISIBILITY = 'agent'
-
-export function setupSession(api: PluginApi): void {
-  const stateDir = resolveStateDir(api)
-  if (!stateDir) {
-    api.logger.warn('Cannot resolve state dir — session setup skipped.')
-    return
-  }
-
-  const configPath = path.join(stateDir, 'openclaw.json')
-  const config = readOpenclawConfig(configPath)
-
-  let dirty = false
-
-  // 1. dmScope
-  const session = ((config.session as Record<string, unknown>) ?? {}) as Record<string, unknown>
-  if (session.dmScope !== DESIRED_DM_SCOPE) {
-    session.dmScope = DESIRED_DM_SCOPE
-    config.session = session
-    dirty = true
-  }
-
-  // 2. tools.sessions.visibility
-  const tools = ((config.tools as Record<string, unknown>) ?? {}) as Record<string, unknown>
-  const sessions = ((tools.sessions as Record<string, unknown>) ?? {}) as Record<string, unknown>
-  if (sessions.visibility !== DESIRED_SESSION_VISIBILITY) {
-    sessions.visibility = DESIRED_SESSION_VISIBILITY
-    tools.sessions = sessions
-    config.tools = tools
-    dirty = true
-  }
-
-  if (!dirty) return
-
-  try {
-    writeOpenclawConfig(configPath, config)
-    api.logger.info(
-      `Session: dmScope="${DESIRED_DM_SCOPE}", tools.sessions.visibility="${DESIRED_SESSION_VISIBILITY}".`,
-    )
-  } catch (err) {
-    api.logger.error(`Failed to update session config: ${(err as Error).message}`)
-  }
-}