@2en/clawly-plugins 1.29.0 → 1.30.0-beta.0

package/clawly-config-defaults.json5

@@ -0,0 +1,118 @@
+{
+  // Static defaults for clawly-plugins.
+  // Deep-merged into openclaw.json via $include — sibling keys in the main
+  // config override these values. Arrays are concatenated, so the main config
+  // must NOT duplicate arrays defined here.
+
+  // models.providers — how to connect (endpoint, auth, capability declarations)
+  models: {
+    providers: {
+      "clawly-model-gateway": {
+        baseUrl: "${CLAWLY_MODEL_GATEWAY_BASE}/v1",
+        apiKey: "${CLAWLY_MODEL_GATEWAY_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "moonshotai/kimi-k2.5",
+            name: "moonshotai/kimi-k2.5",
+            input: ["text", "image"],
+            contextWindow: 262144,
+            maxTokens: 65535,
+          },
+          {
+            id: "google/gemini-2.5-pro",
+            name: "google/gemini-2.5-pro",
+            input: ["text", "image"],
+            contextWindow: 1048576,
+            maxTokens: 65536,
+          },
+          {
+            id: "google/gemini-3-pro-preview",
+            name: "google/gemini-3-pro-preview",
+            input: ["text", "image"],
+            contextWindow: 1048576,
+            maxTokens: 65536,
+          },
+          {
+            id: "anthropic/claude-sonnet-4.6",
+            name: "anthropic/claude-sonnet-4.6",
+            input: ["text", "image"],
+            contextWindow: 1000000,
+            maxTokens: 128000,
+            // api: 'anthropic-messages', // TODO: uncomment once model gateway Anthropic Messages API support is out of testing
+          },
+          {
+            id: "anthropic/claude-opus-4.6",
+            name: "anthropic/claude-opus-4.6",
+            input: ["text", "image"],
+            contextWindow: 1000000,
+            maxTokens: 128000,
+            // api: 'anthropic-messages', // TODO: uncomment once model gateway Anthropic Messages API support is out of testing
+          },
+          {
+            id: "openai/gpt-5.4",
+            name: "openai/gpt-5.4",
+            input: ["text", "image"],
+            contextWindow: 1050000,
+            maxTokens: 128000,
+          },
+          {
+            id: "minimax/minimax-m2.5",
+            name: "minimax/minimax-m2.5",
+            input: ["text"],
+            contextWindow: 196608,
+            maxTokens: 196608,
+          },
+          {
+            id: "minimax/minimax-m2.1",
+            name: "minimax/minimax-m2.1",
+            input: ["text"],
+            contextWindow: 196608,
+            maxTokens: 196608,
+          },
+          {
+            id: "qwen/qwen3.5-plus-02-15",
+            name: "qwen/qwen3.5-plus-02-15",
+            input: ["text", "image"],
+            contextWindow: 1000000,
+            maxTokens: 65536,
+          },
+          {
+            id: "z-ai/glm-5",
+            name: "z-ai/glm-5",
+            input: ["text"],
+            contextWindow: 202752,
+            maxTokens: 131072,
+          },
+        ],
+      },
+    },
+  },
+
+  // agents.defaults.models — which models the agent can use, display names,
+  // and per-model overrides. The whitelist only constrains the UI model picker
+  // and fallback lists.
+  agents: {
+    defaults: {
+      model: {
+        primary: "clawly-model-gateway/anthropic/claude-sonnet-4.6",
+      },
+      imageModel: {
+        primary: "clawly-model-gateway/qwen/qwen3.5-flash-02-23",
+        fallbacks: [],
+      },
+      models: {
+        "clawly-model-gateway/moonshotai/kimi-k2.5": { alias: "Kimi K2.5" },
+        "clawly-model-gateway/google/gemini-2.5-pro": { alias: "Gemini 2.5 Pro" },
+        "clawly-model-gateway/google/gemini-3-pro-preview": { alias: "Gemini 3 Pro Preview" },
+        "clawly-model-gateway/anthropic/claude-sonnet-4.6": { alias: "Claude Sonnet 4.6" },
+        "clawly-model-gateway/anthropic/claude-opus-4.6": { alias: "Claude Opus 4.6" },
+        "clawly-model-gateway/openai/gpt-5.4": { alias: "GPT-5.4" },
+        "clawly-model-gateway/minimax/minimax-m2.5": { alias: "MiniMax M2.5" },
+        "clawly-model-gateway/minimax/minimax-m2.1": { alias: "MiniMax M2.1" },
+        "clawly-model-gateway/qwen/qwen3.5-plus-02-15": { alias: "Qwen 3.5 Plus" },
+        "clawly-model-gateway/z-ai/glm-5": { alias: "GLM-5" },
+      },
+    },
+  },
+}

package/config-setup.ts

@@ -22,9 +22,12 @@ import type {PluginApi} from './index'
 import {autoSanitizeSession} from './gateway/session-sanitize'
 import {resolveGatewayCredentials} from './resolve-gateway-credentials'
 import {
+  ENV_KEY_API_KEY,
+  ENV_KEY_BASE,
   PROVIDER_NAME,
   patchModelGateway,
   readOpenclawConfig,
+  stripPathname,
   writeOpenclawConfig,
 } from './model-gateway-setup'
 
@@ -542,6 +545,44 @@ export function patchHeartbeat(config: Record<string, unknown>, pc: ConfigPlugin
 //   return false
 // }
 
+export function patchEnvVars(
+  config: import('./types/openclaw').OpenClawConfig,
+  pc: ConfigPluginConfig,
+  api: PluginApi,
+): boolean {
+  // TEMP fallback: recover from legacy provider entry until all sprites are migrated.
+  const provider = config.models?.providers?.[PROVIDER_NAME]
+
+  let dirty = false
+  if (!config.env) {
+    config.env = {}
+  }
+  if (!config.env.vars) {
+    config.env.vars = {}
+  }
+  const vars = config.env.vars
+
+  // CLAWLY_MODEL_GATEWAY_BASE
+  if (!vars[ENV_KEY_BASE]) {
+    const urlValue = pc.modelGatewayBaseUrl || provider?.baseUrl || ''
+    if (urlValue) {
+      vars[ENV_KEY_BASE] = stripPathname(urlValue)
+      dirty = true
+    }
+  }
+
+  // CLAWLY_MODEL_GATEWAY_API_KEY
+  if (!vars[ENV_KEY_API_KEY]) {
+    const tokenValue = pc.modelGatewayToken || (provider?.apiKey as string) || ''
+    if (tokenValue) {
+      vars[ENV_KEY_API_KEY] = tokenValue
+      dirty = true
+    }
+  }
+
+  return dirty
+}
+
 export function patchSession(config: Record<string, unknown>): boolean {
   let dirty = false
 
@@ -585,6 +626,50 @@ export function patchSession(config: Record<string, unknown>): boolean {
   return dirty
 }
 
+const INCLUDE_PATH = './extensions/clawly-plugins/clawly-config-defaults.json5'
+
+/**
+ * Ensures our defaults file is listed in the config's `$include` array.
+ * Returns true if `$include` was modified.
+ */
+export function ensureInclude(config: Record<string, unknown>): boolean {
+  const existing = config.$include
+  let includes: string[]
+
+  if (Array.isArray(existing)) {
+    includes = existing as string[]
+  } else if (typeof existing === 'string') {
+    includes = [existing]
+  } else {
+    includes = []
+  }
+
+  if (includes.includes(INCLUDE_PATH)) return false
+
+  includes.push(INCLUDE_PATH)
+  config.$include = includes.length === 1 ? includes[0] : includes
+  return true
+}
+
+/**
+ * Restrict the $include defaults file to owner-only (0o600), matching
+ * openclaw.json. npm/plugin-install creates files with 0o644 by default,
+ * which would leave config readable by other local users.
+ */
+function hardenIncludePermissions(stateDir: string, api: PluginApi): void {
+  const includePath = path.join(stateDir, INCLUDE_PATH)
+  try {
+    const stat = fs.statSync(includePath)
+    const mode = stat.mode & 0o777
+    if (mode !== 0o600) {
+      fs.chmodSync(includePath, 0o600)
+      api.logger.info(`Hardened ${INCLUDE_PATH} permissions to 0600.`)
+    }
+  } catch {
+    // File may not exist yet (first install before plugin copies files)
+  }
+}
+
 const PLUGIN_ID = 'clawly-plugins'
 const NPM_PKG_NAME = '@2en/clawly-plugins'
 
@@ -663,7 +748,7 @@ function reconcileRuntimeConfig(
   // Ensure gateway credentials are available to all patchers.
   // After a force-update, runtime pluginConfig may be empty and on-disk
   // file plugin config may not have credentials — but they may exist in
-  // models.providers.clawly-model-gateway (backfilled by prior runs).
+  // env.vars (backfilled by prior runs).
   // resolveGatewayCredentials checks all three sources.
   if (!pc.modelGatewayBaseUrl || !pc.modelGatewayToken) {
     const creds = resolveGatewayCredentials(api, config)
@@ -673,6 +758,7 @@ function reconcileRuntimeConfig(
   }
 
   let dirty = false
+  dirty = patchEnvVars(config as import('./types/openclaw').OpenClawConfig, pc, api) || dirty
   dirty = patchAgent(config, pc) || dirty
   dirty = patchContextPruning(config) || dirty
   dirty = patchHeartbeat(config, pc) || dirty
@@ -682,7 +768,7 @@ function reconcileRuntimeConfig(
   dirty = patchTts(config, pc) || dirty
   dirty = patchWebSearch(config, pc) || dirty
   dirty = patchMemorySearch(config, pc) || dirty
-  dirty = patchModelGateway(config, api, pc) || dirty
+  dirty = patchModelGateway(config as import('./types/openclaw').OpenClawConfig, api) || dirty
   return dirty
 }
 
@@ -702,6 +788,8 @@ export function setupConfig(api: PluginApi): void {
   const pc = toPCMerged(api, config)
 
   let dirty = false
+  dirty = ensureInclude(config) || dirty
+  hardenIncludePermissions(stateDir, api)
   dirty = repairLegacyProvisionState(api, config, stateDir) || dirty
   dirty = reconcileRuntimeConfig(api, config, pc) || dirty
 

package/gateway/config-repair.ts

@@ -10,8 +10,8 @@ import path from 'node:path'
 
 import type {PluginApi} from '../types'
 import {
-  EXTRA_GATEWAY_MODELS,
-  PROVIDER_NAME,
+  ENV_KEY_API_KEY,
+  ENV_KEY_BASE,
   readOpenclawConfig,
   writeOpenclawConfig,
 } from '../model-gateway-setup'
@@ -33,7 +33,7 @@ export function registerConfigRepair(api: PluginApi) {
     const configPath = path.join(stateDir, 'openclaw.json')
     const config = readOpenclawConfig(configPath)
 
-    const gw = resolveGatewayCredentials(api, config)
+    const gw = resolveGatewayCredentials(api, config as Record<string, unknown>)
     if (!gw) {
       respond(true, {
         ...(dryRun ? {ok: false} : {repaired: false}),
@@ -42,102 +42,35 @@ export function registerConfigRepair(api: PluginApi) {
       return
     }
     const {baseUrl, token} = gw
-    const providers = (config.models as any)?.providers as Record<string, any> | undefined
-    const provider = providers?.[PROVIDER_NAME] as Record<string, unknown> | undefined
+    const vars = config.env?.vars
 
-    // Check current provider state
-    const currentBaseUrl = typeof provider?.baseUrl === 'string' ? provider.baseUrl : ''
-    const currentApiKey = typeof provider?.apiKey === 'string' ? provider.apiKey : ''
-
-    const needsRepair = !provider || !currentBaseUrl || !currentApiKey
-
-    if (!needsRepair) {
+    if (vars?.[ENV_KEY_BASE] && vars?.[ENV_KEY_API_KEY]) {
       respond(true, {
         ...(dryRun ? {ok: true} : {repaired: false}),
-        detail: 'Provider credentials intact',
+        detail: 'env.vars credentials intact',
       })
       return
     }
 
-    // Dry-run: report status without mutating
     if (dryRun) {
-      const missing: string[] = []
-      if (!provider) missing.push('provider entry')
-      else {
-        if (!currentBaseUrl) missing.push('baseUrl')
-        if (!currentApiKey) missing.push('apiKey')
-      }
-      respond(true, {ok: false, detail: `Missing: ${missing.join(', ')}`})
+      respond(true, {ok: false, detail: 'Missing: env.vars credentials'})
       return
     }
 
-    // Repair: derive models from agents.defaults (same logic as model-gateway-setup).
-    // Image fallback is handled server-side by the model-gateway proxy, so only
-    // the default chat model is registered (with image support).
-    const defaultModelFull: string = (config.agents as any)?.defaults?.model?.primary ?? ''
-
-    const prefix = `${PROVIDER_NAME}/`
-    const defaultModel = defaultModelFull.startsWith(prefix)
-      ? defaultModelFull.slice(prefix.length)
-      : defaultModelFull
-
-    const defaultIds = new Set([defaultModel])
-    const extraModels = EXTRA_GATEWAY_MODELS.filter((m) => !defaultIds.has(m.id)).map(
-      ({id, name, input, contextWindow, maxTokens, api}) => ({
-        id,
-        name,
-        input,
-        contextWindow,
-        maxTokens,
-        ...(api ? {api} : {}),
-      }),
-    )
-    const extraMatch = EXTRA_GATEWAY_MODELS.find((m) => m.id === defaultModel)
-    const models = !defaultModel
-      ? (provider?.models ?? [])
-      : [
-          {
-            id: defaultModel,
-            name: defaultModel,
-            input: extraMatch ? [...extraMatch.input] : (['text', 'image'] as string[]),
-            ...(extraMatch && {
-              contextWindow: extraMatch.contextWindow,
-              maxTokens: extraMatch.maxTokens,
-            }),
-            ...(extraMatch?.api ? {api: extraMatch.api} : {}),
-          },
-          ...extraModels,
-        ]
-
-    if (!config.models) config.models = {}
-    if (!(config.models as any).providers) (config.models as any).providers = {}
-    ;(config.models as any).providers[PROVIDER_NAME] = {
-      ...(provider ?? {}),
-      baseUrl,
-      apiKey: token,
-      api: 'openai-completions',
-      models,
-    }
-
-    // Write agents.defaults.models alias map (mirrors model-gateway-setup)
-    if (defaultModel) {
-      const agents = (config.agents ?? {}) as any
-      const defaults = agents.defaults ?? {}
-      const modelsMap: Record<string, {alias: string}> = {
-        [`${PROVIDER_NAME}/${defaultModel}`]: {alias: defaultModel},
-      }
-      for (const m of EXTRA_GATEWAY_MODELS) {
-        modelsMap[`${PROVIDER_NAME}/${m.id}`] = {alias: m.alias}
-      }
-      defaults.models = modelsMap
-      agents.defaults = defaults
-      config.agents = agents
+    // Write credentials into env.vars for $include resolution.
+    if (!config.env) config.env = {}
+    if (!config.env.vars) config.env.vars = {}
+    try {
+      config.env.vars[ENV_KEY_BASE] = new URL(baseUrl).origin
+    } catch {
+      config.env.vars[ENV_KEY_BASE] = baseUrl
     }
+    config.env.vars[ENV_KEY_API_KEY] = token
 
     try {
       writeOpenclawConfig(configPath, config)
-      api.logger.info(`config.repair: restored provider credentials (baseUrl + apiKey)`)
-      respond(true, {repaired: true, detail: 'Provider credentials restored'})
+      api.logger.info(`config.repair: restored env.vars credentials`)
+      respond(true, {repaired: true, detail: 'env.vars credentials restored'})
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       api.logger.error(`config.repair: write failed — ${msg}`)

package/model-gateway-setup.ts

@@ -1,122 +1,23 @@
 /**
- * Reconciles the `clawly-model-gateway` provider in openclaw.json from
- * pluginConfig inputs and the current runtime-facing agent defaults.
+ * Reconciles the `clawly-model-gateway` provider in openclaw.json.
  *
- * This is a runtime reconcile path, not a provision/bootstrap contract.
- * The first-boot correctness of gateway startup should not rely on this file
- * write winning a race against OpenClaw's internal startup snapshot timing.
+ * Static provider config (baseUrl, apiKey, api, models, aliases) is declarative
+ * via $include (clawly-config-defaults.json5) with env var references. This
+ * file only handles:
+ * - Migration: delete inline models, aliases from provider (now from $include)
  *
- * Important boundary: this file intentionally keeps only the instance-visible
- * public model view. Provider routing and upstream model mapping remain
- * repository-internal concerns owned by the backend.
+ * env.vars backfill is handled by patchEnvVars in config-setup.ts.
  */
 
 import fs from 'node:fs'
-import path from 'node:path'
 
 import type {PluginApi} from './index'
+import type {OpenClawConfig} from './types/openclaw'
 
 export const PROVIDER_NAME = 'clawly-model-gateway'
-type ModelGatewayConfigInputs = {
-  modelGatewayBaseUrl?: string
-  modelGatewayToken?: string
-}
-
-export const PUBLIC_GATEWAY_MODELS = [
-  {
-    canonicalId: 'moonshotai/kimi-k2.5',
-    alias: 'Kimi K2.5',
-    input: ['text', 'image'],
-    contextWindow: 262_144,
-    maxTokens: 65_535,
-  },
-  {
-    canonicalId: 'google/gemini-2.5-pro',
-    alias: 'Gemini 2.5 Pro',
-    input: ['text', 'image'],
-    contextWindow: 1_048_576,
-    maxTokens: 65_536,
-  },
-  {
-    canonicalId: 'google/gemini-3-pro-preview',
-    alias: 'Gemini 3 Pro Preview',
-    input: ['text', 'image'],
-    contextWindow: 1_048_576,
-    maxTokens: 65_536,
-  },
-  {
-    canonicalId: 'anthropic/claude-sonnet-4.6',
-    alias: 'Claude Sonnet 4.6',
-    input: ['text', 'image'],
-    contextWindow: 1_000_000,
-    maxTokens: 128_000,
-    // api: 'anthropic-messages', // TODO: uncomment once model gateway Anthropic Messages API support is out of testing
-  },
-  {
-    canonicalId: 'anthropic/claude-opus-4.6',
-    alias: 'Claude Opus 4.6',
-    input: ['text', 'image'],
-    contextWindow: 1_000_000,
-    maxTokens: 128_000,
-    // api: 'anthropic-messages',
-  },
-  {
-    canonicalId: 'openai/gpt-5.4',
-    alias: 'GPT-5.4',
-    input: ['text', 'image'],
-    contextWindow: 1_050_000,
-    maxTokens: 128_000,
-  },
-  {
-    canonicalId: 'minimax/minimax-m2.5',
-    alias: 'MiniMax M2.5',
-    input: ['text'],
-    contextWindow: 196_608,
-    maxTokens: 196_608,
-  },
-  {
-    canonicalId: 'minimax/minimax-m2.1',
-    alias: 'MiniMax M2.1',
-    input: ['text'],
-    contextWindow: 196_608,
-    maxTokens: 196_608,
-  },
-  {
-    canonicalId: 'qwen/qwen3.5-plus-02-15',
-    alias: 'Qwen 3.5 Plus',
-    input: ['text', 'image'],
-    contextWindow: 1_000_000,
-    maxTokens: 65_536,
-  },
-  {
-    canonicalId: 'z-ai/glm-5',
-    alias: 'GLM-5',
-    input: ['text'],
-    contextWindow: 202_752,
-    maxTokens: 131_072,
-  },
-] as const
-
-/** Additional models available through the model gateway (beyond env-configured defaults). */
-export const EXTRA_GATEWAY_MODELS: Array<{
-  id: string
-  name: string
-  alias: string
-  input: string[]
-  contextWindow: number
-  maxTokens: number
-  api?: string
-}> = PUBLIC_GATEWAY_MODELS.map((model) => ({
-  id: model.canonicalId,
-  name: model.canonicalId,
-  alias: model.alias,
-  input: [...model.input],
-  contextWindow: model.contextWindow,
-  maxTokens: model.maxTokens,
-  ...('api' in model && model.api ? {api: model.api} : {}),
-}))
-
-export function readOpenclawConfig(configPath: string): Record<string, unknown> {
+export const ENV_KEY_BASE = 'CLAWLY_MODEL_GATEWAY_BASE'
+export const ENV_KEY_API_KEY = 'CLAWLY_MODEL_GATEWAY_API_KEY'
+export function readOpenclawConfig(configPath: string): OpenClawConfig {
   try {
     return JSON.parse(fs.readFileSync(configPath, 'utf-8'))
   } catch {
@@ -124,211 +25,45 @@ export function readOpenclawConfig(configPath: string): Record<string, unknown>
   }
 }
 
-export function writeOpenclawConfig(configPath: string, config: Record<string, unknown>) {
+export function writeOpenclawConfig(configPath: string, config: OpenClawConfig) {
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n')
 }
 
-function buildProviderModel(id: string): {
-  id: string
-  name: string
-  input: string[]
-  contextWindow?: number
-  maxTokens?: number
-  api?: string
-} {
-  const extra = EXTRA_GATEWAY_MODELS.find((model) => model.id === id)
-  return {
-    id,
-    name: id,
-    input: extra ? [...extra.input] : ['text', 'image'],
-    ...(extra ? {contextWindow: extra.contextWindow, maxTokens: extra.maxTokens} : {}),
-    ...(extra?.api ? {api: extra.api} : {}),
+/** Strip pathname from a URL, returning just the origin (scheme + host + port). */
+export function stripPathname(url: string): string {
+  try {
+    const parsed = new URL(url)
+    return parsed.origin
+  } catch {
+    return url
   }
 }
 
-export function patchModelGateway(
-  config: Record<string, unknown>,
-  api: PluginApi,
-  inputs?: ModelGatewayConfigInputs,
-): boolean {
-  const cfg =
-    inputs ??
-    (api.pluginConfig as Record<string, unknown> | undefined as
-      | ModelGatewayConfigInputs
-      | undefined)
-
-  // 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.
-  const existingProvider = (config.models as any)?.providers?.[PROVIDER_NAME]
-  if (existingProvider) {
-    let dirty = false
-    const existingModels: Array<{id: string}> = existingProvider.models ?? []
-    const existingIds = new Set(existingModels.map((m: {id: string}) => m.id))
-
-    // Append any missing extra models
-    for (const m of EXTRA_GATEWAY_MODELS) {
-      if (!existingIds.has(m.id)) {
-        existingModels.push({
-          id: m.id,
-          name: m.name,
-          input: m.input,
-          contextWindow: m.contextWindow,
-          maxTokens: m.maxTokens,
-          ...(m.api ? {api: m.api} : {}),
-        } as any)
-        dirty = true
-      }
-    }
-
-    // Backfill contextWindow/maxTokens and api on existing models that lack them
-    const extraLookup = new Map(EXTRA_GATEWAY_MODELS.map((m) => [m.id, m]))
-    for (const m of existingModels) {
-      const extra = extraLookup.get(m.id)
-      if (!extra) continue
-      if (
-        (m as any).contextWindow !== extra.contextWindow ||
-        (m as any).maxTokens !== extra.maxTokens
-      ) {
-        ;(m as any).contextWindow = extra.contextWindow
-        ;(m as any).maxTokens = extra.maxTokens
-        dirty = true
-      }
-      if (extra.api && (m as any).api !== extra.api) {
-        ;(m as any).api = extra.api
-        dirty = true
-      }
-    }
-
-    // Ensure aliases exist for ALL models (existing + extras)
-    const agents = (config.agents ?? {}) as any
-    const defaults = agents.defaults ?? {}
-    const existingAliases: Record<string, {alias: string}> = defaults.models ?? {}
-    for (const m of existingModels) {
-      const key = `${PROVIDER_NAME}/${m.id}`
-      if (!existingAliases[key]) {
-        const extra = EXTRA_GATEWAY_MODELS.find((e) => e.id === m.id)
-        existingAliases[key] = {alias: extra?.alias ?? m.id}
-        dirty = true
-      }
-    }
+/**
+ * @deprecated Migration-only — remove once all sprites have been reprovisioned
+ * and no inline models/aliases remain in openclaw.json.
+ */
+export function patchModelGateway(config: OpenClawConfig, _api: PluginApi): boolean {
+  let dirty = false
+  const provider = config.models?.providers?.[PROVIDER_NAME]
+
+  // Migration: delete inline models array (now from $include).
+  if (provider?.models) {
+    delete (provider as Record<string, unknown>).models
+    dirty = true
+  }
 
-    // Backfill pluginConfig from existing provider credentials (legacy sprites
-    // provisioned before plugin config was written during configure phase).
-    if (
-      existingProvider.baseUrl &&
-      existingProvider.apiKey &&
-      (!cfg?.modelGatewayBaseUrl || !cfg?.modelGatewayToken)
-    ) {
-      const entries = (config.plugins as any)?.entries?.['clawly-plugins']
-      if (entries) {
-        entries.config = {
-          ...entries.config,
-          modelGatewayBaseUrl: existingProvider.baseUrl,
-          modelGatewayToken: existingProvider.apiKey,
-        }
+  // Migration: delete aliases starting with our provider prefix (now from $include).
+  const aliasMap = config.agents?.defaults?.models
+  if (aliasMap) {
+    const prefix = `${PROVIDER_NAME}/`
+    for (const key of Object.keys(aliasMap)) {
+      if (key.startsWith(prefix)) {
+        delete aliasMap[key]
         dirty = true
-        api.logger.info(
-          'Model gateway: backfilled pluginConfig from existing provider credentials.',
-        )
       }
     }
-
-    if (dirty) {
-      existingProvider.models = existingModels
-      defaults.models = existingAliases
-      agents.defaults = defaults
-      config.agents = agents
-      api.logger.info('Model gateway updated.')
-    } else {
-      api.logger.info('Model gateway provider already configured.')
-    }
-    return dirty
   }
 
-  // No existing provider — need pluginConfig credentials to create one
-  const baseUrl =
-    typeof cfg?.modelGatewayBaseUrl === 'string' ? cfg.modelGatewayBaseUrl.replace(/\/$/, '') : ''
-  const token = typeof cfg?.modelGatewayToken === 'string' ? cfg.modelGatewayToken : ''
-
-  if (!baseUrl || !token) {
-    api.logger.info('Model gateway not configured (missing baseUrl or token), skipping.')
-    return false
-  }
-
-  // Derive default model ID from agents.defaults.
-  // Image fallback is handled server-side by the model-gateway proxy, so only
-  // the default chat model needs to be registered in the provider's model list.
-  const defaultModelFull: string = (config.agents as any)?.defaults?.model?.primary ?? ''
-
-  const prefix = `${PROVIDER_NAME}/`
-  const defaultModel = defaultModelFull.startsWith(prefix)
-    ? defaultModelFull.slice(prefix.length)
-    : defaultModelFull
-
-  if (!defaultModel) {
-    api.logger.warn('No default model found in agents.defaults — model gateway setup skipped.')
-    return false
-  }
-
-  const defaultModels = [buildProviderModel(defaultModel)]
-
-  const defaultIds = new Set(defaultModels.map((m) => m.id))
-  const models = [
-    ...defaultModels,
-    ...EXTRA_GATEWAY_MODELS.filter((m) => !defaultIds.has(m.id)).map(({id}) =>
-      buildProviderModel(id),
-    ),
-  ]
-
-  if (!config.models) config.models = {}
-  if (!(config.models as any).providers) (config.models as any).providers = {}
-  ;(config.models as any).providers[PROVIDER_NAME] = {
-    baseUrl,
-    apiKey: token,
-    api: 'openai-completions',
-    models,
-  }
-
-  // Write agents.defaults.models map for UI dropdown aliases
-  const agents = (config.agents ?? {}) as any
-  const defaults = agents.defaults ?? {}
-  const modelsMap: Record<string, {alias: string}> = {
-    [`${PROVIDER_NAME}/${defaultModel}`]: {alias: defaultModel},
-  }
-  for (const m of EXTRA_GATEWAY_MODELS) {
-    modelsMap[`${PROVIDER_NAME}/${m.id}`] = {alias: m.alias}
-  }
-  defaults.models = modelsMap
-  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.
- *
- * This helper intentionally does not apply the file-backed pluginConfig fallback
- * from setupConfig(); production startup should go through the full runtime
- * reconcile path there.
- */
-export function setupModelGateway(api: PluginApi): void {
-  const stateDir = api.runtime.state.resolveStateDir()
-  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)
-  } catch (err) {
-    api.logger.error(`Failed to setup model gateway: ${(err as Error).message}`)
-  }
+  return dirty
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.29.0",
+  "version": "1.30.0-beta.0",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -36,6 +36,7 @@
     "resolve-gateway-credentials.ts",
     "skill-command-restore.ts",
     "openclaw.plugin.json",
+    "clawly-config-defaults.json5",
     "internal",
     "skills"
   ],
@@ -46,5 +47,8 @@
     "extensions": [
       "./index.ts"
     ]
+  },
+  "devDependencies": {
+    "json5": "^2.2.3"
   }
 }

package/resolve-gateway-credentials.ts

@@ -3,18 +3,18 @@
  *
  * Fallback order:
  * 1. Runtime pluginConfig (api.pluginConfig) — always present on fresh provision
- * 2. On-disk provider entry (models.providers.clawly-model-gateway) — backfilled by setupConfig
+ * 2. On-disk env.vars (CLAWLY_MODEL_GATEWAY_BASE/API_KEY) — written by setupConfig
  * 3. On-disk file plugin config (plugins.entries.clawly-plugins.config) — written during provision
  *
  * After a force-update, runtime pluginConfig may be empty (it's immutable at
- * runtime), but setupConfig backfills credentials into the on-disk provider
- * and file plugin config entries. This function reads from all three sources
- * so callers always get credentials when available.
+ * runtime), but setupConfig backfills credentials into env.vars and file
+ * plugin config entries. This function reads from all three sources so
+ * callers always get credentials when available.
  */
 
 import path from 'node:path'
 
-import {PROVIDER_NAME, readOpenclawConfig} from './model-gateway-setup'
+import {ENV_KEY_API_KEY, ENV_KEY_BASE, readOpenclawConfig} from './model-gateway-setup'
 import type {PluginApi} from './types'
 
 export interface GatewayCredentials {
@@ -43,14 +43,13 @@ export function resolveGatewayCredentials(
     config = readOpenclawConfig(path.join(stateDir, 'openclaw.json'))
   }
 
-  // 2. On-disk provider entry
-  const provider = (config.models as any)?.providers?.[PROVIDER_NAME] as
-    | Record<string, unknown>
-    | undefined
-  const provBaseUrl = typeof provider?.baseUrl === 'string' ? provider.baseUrl : ''
-  const provApiKey = typeof provider?.apiKey === 'string' ? provider.apiKey : ''
-  if (provBaseUrl && provApiKey) {
-    return {baseUrl: provBaseUrl.replace(/\/$/, ''), token: provApiKey}
+  // 2. On-disk env.vars (credentials stored as env vars for $include resolution)
+  const envVars = (config.env as any)?.vars as Record<string, string> | undefined
+  const envBase = typeof envVars?.[ENV_KEY_BASE] === 'string' ? envVars[ENV_KEY_BASE] : ''
+  const envBaseUrl = envBase ? `${envBase}/v1` : ''
+  const envApiKey = typeof envVars?.[ENV_KEY_API_KEY] === 'string' ? envVars[ENV_KEY_API_KEY] : ''
+  if (envBaseUrl && envApiKey) {
+    return {baseUrl: envBaseUrl.replace(/\/$/, ''), token: envApiKey}
   }
 
   // 3. On-disk file plugin config