@2en/clawly-plugins 1.24.2-beta.0 → 1.24.3

package/types/openclaw.ts

@@ -0,0 +1,963 @@
+/**
+ * Standalone OpenClaw configuration types.
+ *
+ * Derived from openclaw/src/config/types.openclaw.ts and its transitive
+ * dependencies.  Kept self-contained so the plugin package does not need a
+ * build-time dependency on the openclaw source tree.
+ *
+ * When the upstream types change, diff against the openclaw fork at
+ *   src/config/types.*.ts
+ * and update this file accordingly.
+ */
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+export type AuthProfileConfig = {
+  provider: string
+  mode: 'api_key' | 'oauth' | 'token'
+  email?: string
+}
+
+export type AuthConfig = {
+  profiles?: Record<string, AuthProfileConfig>
+  order?: Record<string, string[]>
+  cooldowns?: {
+    billingBackoffHours?: number
+    billingBackoffHoursByProvider?: Record<string, number>
+    billingMaxHours?: number
+    failureWindowHours?: number
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Base (shared primitives)
+// ---------------------------------------------------------------------------
+
+export type TypingMode = 'never' | 'instant' | 'thinking' | 'message'
+
+export type HumanDelayConfig = {
+  mode?: 'off' | 'natural' | 'custom'
+  minMs?: number
+  maxMs?: number
+}
+
+export type BlockStreamingCoalesceConfig = {
+  minChars?: number
+  maxChars?: number
+  idleMs?: number
+}
+
+export type BlockStreamingChunkConfig = {
+  minChars?: number
+  maxChars?: number
+  breakPreference?: 'paragraph' | 'newline' | 'sentence'
+}
+
+export type IdentityConfig = {
+  name?: string
+  theme?: string
+  emoji?: string
+  avatar?: string
+}
+
+export type SessionResetConfig = {
+  mode?: 'daily' | 'idle'
+  atHour?: number
+  idleMinutes?: number
+}
+
+export type SessionSendPolicyAction = 'allow' | 'deny'
+
+export type SessionSendPolicyConfig = {
+  default?: SessionSendPolicyAction
+  rules?: Array<{
+    action: SessionSendPolicyAction
+    match?: {channel?: string; chatType?: string; keyPrefix?: string; rawKeyPrefix?: string}
+  }>
+}
+
+export type SessionConfig = {
+  scope?: 'per-sender' | 'global'
+  dmScope?: 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer'
+  identityLinks?: Record<string, string[]>
+  resetTriggers?: string[]
+  idleMinutes?: number
+  reset?: SessionResetConfig
+  resetByType?: {
+    direct?: SessionResetConfig
+    dm?: SessionResetConfig
+    group?: SessionResetConfig
+    thread?: SessionResetConfig
+  }
+  resetByChannel?: Record<string, SessionResetConfig>
+  store?: string
+  typingIntervalSeconds?: number
+  typingMode?: TypingMode
+  mainKey?: string
+  sendPolicy?: SessionSendPolicyConfig
+  agentToAgent?: {maxPingPongTurns?: number}
+  maintenance?: {
+    mode?: 'enforce' | 'warn'
+    pruneAfter?: string | number
+    pruneDays?: number
+    maxEntries?: number
+    rotateBytes?: number | string
+  }
+}
+
+export type DiagnosticsConfig = {
+  enabled?: boolean
+  flags?: string[]
+  otel?: {
+    enabled?: boolean
+    endpoint?: string
+    protocol?: 'http/protobuf' | 'grpc'
+    headers?: Record<string, string>
+    serviceName?: string
+    traces?: boolean
+    metrics?: boolean
+    logs?: boolean
+    sampleRate?: number
+    flushIntervalMs?: number
+  }
+  cacheTrace?: {
+    enabled?: boolean
+    filePath?: string
+    includeMessages?: boolean
+    includePrompt?: boolean
+    includeSystem?: boolean
+  }
+}
+
+export type LoggingConfig = {
+  level?: 'silent' | 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
+  file?: string
+  consoleLevel?: 'silent' | 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
+  consoleStyle?: 'pretty' | 'compact' | 'json'
+  redactSensitive?: 'off' | 'tools'
+  redactPatterns?: string[]
+}
+
+export type WebConfig = {
+  enabled?: boolean
+  heartbeatSeconds?: number
+  reconnect?: {
+    initialMs?: number
+    maxMs?: number
+    factor?: number
+    jitter?: number
+    maxAttempts?: number
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Browser
+// ---------------------------------------------------------------------------
+
+export type BrowserConfig = {
+  enabled?: boolean
+  evaluateEnabled?: boolean
+  cdpUrl?: string
+  remoteCdpTimeoutMs?: number
+  remoteCdpHandshakeTimeoutMs?: number
+  color?: string
+  executablePath?: string
+  headless?: boolean
+  noSandbox?: boolean
+  attachOnly?: boolean
+  defaultProfile?: string
+  profiles?: Record<
+    string,
+    {cdpPort?: number; cdpUrl?: string; driver?: 'openclaw' | 'extension'; color: string}
+  >
+  snapshotDefaults?: {mode?: 'efficient'}
+}
+
+// ---------------------------------------------------------------------------
+// Agents
+// ---------------------------------------------------------------------------
+
+export type AgentModelConfig = string | {primary?: string; fallbacks?: string[]}
+
+export type AgentModelListConfig = {primary?: string; fallbacks?: string[]}
+
+export type AgentModelEntryConfig = {
+  alias?: string
+  params?: Record<string, unknown>
+  streaming?: boolean
+}
+
+export type AgentDefaultsConfig = {
+  model?: AgentModelListConfig
+  imageModel?: AgentModelListConfig
+  models?: Record<string, AgentModelEntryConfig>
+  workspace?: string
+  repoRoot?: string
+  skipBootstrap?: boolean
+  bootstrapMaxChars?: number
+  bootstrapTotalMaxChars?: number
+  userTimezone?: string
+  timeFormat?: 'auto' | '12' | '24'
+  envelopeTimezone?: string
+  envelopeTimestamp?: 'on' | 'off'
+  envelopeElapsed?: 'on' | 'off'
+  contextTokens?: number
+  cliBackends?: Record<
+    string,
+    {
+      command: string
+      args?: string[]
+      output?: 'json' | 'text' | 'jsonl'
+      resumeOutput?: 'json' | 'text' | 'jsonl'
+      input?: 'arg' | 'stdin'
+      maxPromptArgChars?: number
+      env?: Record<string, string>
+      clearEnv?: string[]
+      modelArg?: string
+      modelAliases?: Record<string, string>
+      sessionArg?: string
+      sessionArgs?: string[]
+      resumeArgs?: string[]
+      sessionMode?: 'always' | 'existing' | 'none'
+      sessionIdFields?: string[]
+      systemPromptArg?: string
+      systemPromptMode?: 'append' | 'replace'
+      systemPromptWhen?: 'first' | 'always' | 'never'
+      imageArg?: string
+      imageMode?: 'repeat' | 'list'
+      serialize?: boolean
+    }
+  >
+  contextPruning?: {
+    mode?: 'off' | 'cache-ttl'
+    ttl?: string
+    keepLastAssistants?: number
+    softTrimRatio?: number
+    hardClearRatio?: number
+    minPrunableToolChars?: number
+    tools?: {allow?: string[]; deny?: string[]}
+    softTrim?: {maxChars?: number; headChars?: number; tailChars?: number}
+    hardClear?: {enabled?: boolean; placeholder?: string}
+  }
+  compaction?: {
+    mode?: 'default' | 'safeguard'
+    reserveTokensFloor?: number
+    maxHistoryShare?: number
+    memoryFlush?: {
+      enabled?: boolean
+      softThresholdTokens?: number
+      prompt?: string
+      systemPrompt?: string
+    }
+  }
+  memorySearch?: MemorySearchConfig
+  thinkingDefault?: 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
+  verboseDefault?: 'off' | 'on' | 'full'
+  elevatedDefault?: 'off' | 'on' | 'ask' | 'full'
+  blockStreamingDefault?: 'off' | 'on'
+  blockStreamingBreak?: 'text_end' | 'message_end'
+  blockStreamingChunk?: BlockStreamingChunkConfig
+  blockStreamingCoalesce?: BlockStreamingCoalesceConfig
+  humanDelay?: HumanDelayConfig
+  timeoutSeconds?: number
+  mediaMaxMb?: number
+  typingIntervalSeconds?: number
+  typingMode?: TypingMode
+  heartbeat?: {
+    every?: string
+    activeHours?: {start?: string; end?: string; timezone?: string}
+    model?: string
+    session?: string
+    target?: 'last' | 'none' | string
+    to?: string
+    accountId?: string
+    prompt?: string
+    ackMaxChars?: number
+    includeReasoning?: boolean
+  }
+  maxConcurrent?: number
+  subagents?: {
+    maxConcurrent?: number
+    maxSpawnDepth?: number
+    maxChildrenPerAgent?: number
+    archiveAfterMinutes?: number
+    model?: string | {primary?: string; fallbacks?: string[]}
+    thinking?: string
+  }
+  sandbox?: {
+    mode?: 'off' | 'non-main' | 'all'
+    workspaceAccess?: 'none' | 'ro' | 'rw'
+    sessionToolsVisibility?: 'spawned' | 'all'
+    scope?: 'session' | 'agent' | 'shared'
+    perSession?: boolean
+    workspaceRoot?: string
+    docker?: Record<string, unknown>
+    browser?: Record<string, unknown>
+    prune?: Record<string, unknown>
+  }
+}
+
+export type AgentConfig = {
+  id: string
+  default?: boolean
+  name?: string
+  workspace?: string
+  agentDir?: string
+  model?: AgentModelConfig
+  skills?: string[]
+  memorySearch?: MemorySearchConfig
+  humanDelay?: HumanDelayConfig
+  heartbeat?: AgentDefaultsConfig['heartbeat']
+  identity?: IdentityConfig
+  groupChat?: {mentionPatterns?: string[]; historyLimit?: number}
+  subagents?: {allowAgents?: string[]; model?: string | {primary?: string; fallbacks?: string[]}}
+  sandbox?: {
+    mode?: 'off' | 'non-main' | 'all'
+    workspaceAccess?: 'none' | 'ro' | 'rw'
+    sessionToolsVisibility?: 'spawned' | 'all'
+    scope?: 'session' | 'agent' | 'shared'
+    perSession?: boolean
+    workspaceRoot?: string
+    docker?: Record<string, unknown>
+    browser?: Record<string, unknown>
+    prune?: Record<string, unknown>
+  }
+  tools?: AgentToolsConfig
+}
+
+export type AgentsConfig = {
+  defaults?: AgentDefaultsConfig
+  list?: AgentConfig[]
+}
+
+export type AgentBinding = {
+  agentId: string
+  match: {
+    channel: string
+    accountId?: string
+    peer?: {kind: string; id: string}
+    guildId?: string
+    teamId?: string
+    roles?: string[]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Models
+// ---------------------------------------------------------------------------
+
+export type ModelApi =
+  | 'openai-completions'
+  | 'openai-responses'
+  | 'anthropic-messages'
+  | 'google-generative-ai'
+  | 'github-copilot'
+  | 'bedrock-converse-stream'
+  | 'ollama'
+
+export type ModelDefinitionConfig = {
+  id: string
+  name: string
+  api?: ModelApi
+  reasoning: boolean
+  input: Array<'text' | 'image'>
+  cost: {input: number; output: number; cacheRead: number; cacheWrite: number}
+  contextWindow: number
+  maxTokens: number
+  headers?: Record<string, string>
+  compat?: {
+    supportsStore?: boolean
+    supportsDeveloperRole?: boolean
+    supportsReasoningEffort?: boolean
+    supportsUsageInStreaming?: boolean
+    supportsStrictMode?: boolean
+    maxTokensField?: 'max_completion_tokens' | 'max_tokens'
+    thinkingFormat?: 'openai' | 'zai' | 'qwen'
+    requiresToolResultName?: boolean
+    requiresAssistantAfterToolResult?: boolean
+    requiresThinkingAsText?: boolean
+    requiresMistralToolIds?: boolean
+  }
+}
+
+export type ModelProviderConfig = {
+  baseUrl: string
+  apiKey?: string
+  auth?: 'api-key' | 'aws-sdk' | 'oauth' | 'token'
+  api?: ModelApi
+  headers?: Record<string, string>
+  authHeader?: boolean
+  models: ModelDefinitionConfig[]
+}
+
+export type ModelsConfig = {
+  mode?: 'merge' | 'replace'
+  providers?: Record<string, ModelProviderConfig>
+  bedrockDiscovery?: {
+    enabled?: boolean
+    region?: string
+    providerFilter?: string[]
+    refreshInterval?: number
+    defaultContextWindow?: number
+    defaultMaxTokens?: number
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+export type ExecToolConfig = {
+  host?: 'sandbox' | 'gateway' | 'node'
+  security?: 'deny' | 'allowlist' | 'full'
+  ask?: 'off' | 'on-miss' | 'always'
+  node?: string
+  pathPrepend?: string[]
+  safeBins?: string[]
+  backgroundMs?: number
+  timeoutSec?: number
+  approvalRunningNoticeMs?: number
+  cleanupMs?: number
+  notifyOnExit?: boolean
+  notifyOnExitEmptySuccess?: boolean
+  applyPatch?: {enabled?: boolean; workspaceOnly?: boolean; allowModels?: string[]}
+}
+
+export type MemorySearchConfig = {
+  enabled?: boolean
+  sources?: Array<'memory' | 'sessions'>
+  extraPaths?: string[]
+  experimental?: {sessionMemory?: boolean}
+  provider?: 'openai' | 'gemini' | 'local' | 'voyage'
+  remote?: {
+    baseUrl?: string
+    apiKey?: string
+    headers?: Record<string, string>
+    batch?: {
+      enabled?: boolean
+      wait?: boolean
+      concurrency?: number
+      pollIntervalMs?: number
+      timeoutMinutes?: number
+    }
+  }
+  fallback?: 'openai' | 'gemini' | 'local' | 'voyage' | 'none'
+  model?: string
+  local?: {modelPath?: string; modelCacheDir?: string}
+  store?: {
+    driver?: 'sqlite'
+    path?: string
+    vector?: {enabled?: boolean; extensionPath?: string}
+    cache?: {enabled?: boolean; maxEntries?: number}
+  }
+  chunking?: {tokens?: number; overlap?: number}
+  sync?: {
+    onSessionStart?: boolean
+    onSearch?: boolean
+    watch?: boolean
+    watchDebounceMs?: number
+    intervalMinutes?: number
+    sessions?: {deltaBytes?: number; deltaMessages?: number}
+  }
+  query?: {
+    maxResults?: number
+    minScore?: number
+    hybrid?: {
+      enabled?: boolean
+      vectorWeight?: number
+      textWeight?: number
+      candidateMultiplier?: number
+    }
+  }
+  cache?: {enabled?: boolean; maxEntries?: number}
+}
+
+export type AgentToolsConfig = {
+  profile?: 'minimal' | 'coding' | 'messaging' | 'full'
+  allow?: string[]
+  alsoAllow?: string[]
+  deny?: string[]
+  byProvider?: Record<
+    string,
+    {allow?: string[]; alsoAllow?: string[]; deny?: string[]; profile?: string}
+  >
+  elevated?: {enabled?: boolean; allowFrom?: Record<string, Array<string | number>>}
+  exec?: ExecToolConfig
+  fs?: {workspaceOnly?: boolean}
+  sandbox?: {tools?: {allow?: string[]; deny?: string[]}}
+}
+
+export type ToolsConfig = {
+  profile?: 'minimal' | 'coding' | 'messaging' | 'full'
+  allow?: string[]
+  alsoAllow?: string[]
+  deny?: string[]
+  byProvider?: Record<
+    string,
+    {allow?: string[]; alsoAllow?: string[]; deny?: string[]; profile?: string}
+  >
+  web?: {
+    search?: {
+      enabled?: boolean
+      provider?: 'brave' | 'perplexity' | 'grok'
+      apiKey?: string
+      maxResults?: number
+      timeoutSeconds?: number
+      cacheTtlMinutes?: number
+      perplexity?: {apiKey?: string; baseUrl?: string; model?: string}
+      grok?: {apiKey?: string; model?: string; inlineCitations?: boolean}
+    }
+    fetch?: {
+      enabled?: boolean
+      maxChars?: number
+      maxCharsCap?: number
+      timeoutSeconds?: number
+      cacheTtlMinutes?: number
+      maxRedirects?: number
+      userAgent?: string
+      readability?: boolean
+      firecrawl?: {
+        enabled?: boolean
+        apiKey?: string
+        baseUrl?: string
+        onlyMainContent?: boolean
+        maxAgeMs?: number
+        timeoutSeconds?: number
+      }
+    }
+  }
+  media?: {
+    models?: Array<Record<string, unknown>>
+    concurrency?: number
+    image?: Record<string, unknown>
+    audio?: Record<string, unknown>
+    video?: Record<string, unknown>
+  }
+  links?: {
+    enabled?: boolean
+    scope?: Record<string, unknown>
+    maxLinks?: number
+    timeoutSeconds?: number
+    models?: Array<Record<string, unknown>>
+  }
+  message?: {
+    allowCrossContextSend?: boolean
+    crossContext?: {
+      allowWithinProvider?: boolean
+      allowAcrossProviders?: boolean
+      marker?: {enabled?: boolean; prefix?: string; suffix?: string}
+    }
+    broadcast?: {enabled?: boolean}
+  }
+  agentToAgent?: {enabled?: boolean; allow?: string[]}
+  elevated?: {enabled?: boolean; allowFrom?: Record<string, Array<string | number>>}
+  exec?: ExecToolConfig
+  fs?: {workspaceOnly?: boolean}
+  subagents?: {
+    model?: string | {primary?: string; fallbacks?: string[]}
+    tools?: {allow?: string[]; deny?: string[]}
+  }
+  sandbox?: {tools?: {allow?: string[]; deny?: string[]}}
+}
+
+// ---------------------------------------------------------------------------
+// Messages / Commands
+// ---------------------------------------------------------------------------
+
+export type MessagesConfig = {
+  messagePrefix?: string
+  responsePrefix?: string
+  groupChat?: {mentionPatterns?: string[]; historyLimit?: number}
+  queue?: {
+    mode?: string
+    byChannel?: Record<string, string>
+    debounceMs?: number
+    debounceMsByChannel?: Record<string, number>
+    cap?: number
+    drop?: string
+  }
+  inbound?: {debounceMs?: number; byChannel?: Record<string, number>}
+  ackReaction?: string
+  ackReactionScope?: 'group-mentions' | 'group-all' | 'direct' | 'all'
+  removeAckAfterReply?: boolean
+  suppressToolErrors?: boolean
+  tts?: Record<string, unknown>
+}
+
+export type CommandsConfig = {
+  native?: boolean | 'auto'
+  nativeSkills?: boolean | 'auto'
+  text?: boolean
+  bash?: boolean
+  bashForegroundMs?: number
+  config?: boolean
+  debug?: boolean
+  restart?: boolean
+  useAccessGroups?: boolean
+  ownerAllowFrom?: Array<string | number>
+  allowFrom?: Record<string, Array<string | number>>
+}
+
+export type BroadcastConfig = {
+  strategy?: 'parallel' | 'sequential'
+  [peerId: string]: string[] | 'parallel' | 'sequential' | undefined
+}
+
+export type AudioConfig = {
+  transcription?: {command: string[]; timeoutSeconds?: number}
+}
+
+// ---------------------------------------------------------------------------
+// Plugins / Skills
+// ---------------------------------------------------------------------------
+
+export type PluginsConfig = {
+  enabled?: boolean
+  allow?: string[]
+  deny?: string[]
+  load?: {paths?: string[]}
+  slots?: {memory?: string}
+  entries?: Record<string, {enabled?: boolean; config?: Record<string, unknown>}>
+  installs?: Record<
+    string,
+    {
+      source: 'npm' | 'archive' | 'path'
+      spec?: string
+      sourcePath?: string
+      installPath?: string
+      version?: string
+      installedAt?: string
+    }
+  >
+}
+
+export type SkillsConfig = {
+  allowBundled?: string[]
+  load?: {extraDirs?: string[]; watch?: boolean; watchDebounceMs?: number}
+  install?: {preferBrew?: boolean; nodeManager?: 'npm' | 'pnpm' | 'yarn' | 'bun'}
+  entries?: Record<
+    string,
+    {
+      enabled?: boolean
+      apiKey?: string
+      env?: Record<string, string>
+      config?: Record<string, unknown>
+    }
+  >
+}
+
+// ---------------------------------------------------------------------------
+// Approvals
+// ---------------------------------------------------------------------------
+
+export type ApprovalsConfig = {
+  exec?: {
+    enabled?: boolean
+    mode?: 'session' | 'targets' | 'both'
+    agentFilter?: string[]
+    sessionFilter?: string[]
+    targets?: Array<{channel: string; to: string; accountId?: string; threadId?: string | number}>
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Node Host
+// ---------------------------------------------------------------------------
+
+export type NodeHostConfig = {
+  browserProxy?: {enabled?: boolean; allowProfiles?: string[]}
+}
+
+// ---------------------------------------------------------------------------
+// Channels (loosely typed — plugin does not interact with channel specifics)
+// ---------------------------------------------------------------------------
+
+export type ChannelsConfig = {
+  defaults?: {
+    groupPolicy?: string
+    heartbeat?: {showOk?: boolean; showAlerts?: boolean; useIndicator?: boolean}
+  }
+  [key: string]: unknown
+}
+
+// ---------------------------------------------------------------------------
+// Cron
+// ---------------------------------------------------------------------------
+
+export type CronConfig = {
+  enabled?: boolean
+  store?: string
+  maxConcurrentRuns?: number
+  sessionRetention?: string | false
+}
+
+// ---------------------------------------------------------------------------
+// Gateway
+// ---------------------------------------------------------------------------
+
+export type GatewayConfig = {
+  port?: number
+  mode?: 'local' | 'remote'
+  bind?: 'auto' | 'lan' | 'loopback' | 'custom' | 'tailnet'
+  customBindHost?: string
+  controlUi?: {
+    enabled?: boolean
+    basePath?: string
+    root?: string
+    allowedOrigins?: string[]
+    allowInsecureAuth?: boolean
+    dangerouslyDisableDeviceAuth?: boolean
+  }
+  auth?: {
+    mode?: 'token' | 'password' | 'trusted-proxy'
+    token?: string
+    password?: string
+    allowTailscale?: boolean
+    rateLimit?: {
+      maxAttempts?: number
+      windowMs?: number
+      lockoutMs?: number
+      exemptLoopback?: boolean
+    }
+    trustedProxy?: {userHeader: string; requiredHeaders?: string[]; allowUsers?: string[]}
+  }
+  tailscale?: {mode?: 'off' | 'serve' | 'funnel'; resetOnExit?: boolean}
+  remote?: {
+    url?: string
+    transport?: 'ssh' | 'direct'
+    token?: string
+    password?: string
+    tlsFingerprint?: string
+    sshTarget?: string
+    sshIdentity?: string
+  }
+  reload?: {mode?: 'off' | 'restart' | 'hot' | 'hybrid'; debounceMs?: number}
+  tls?: {
+    enabled?: boolean
+    autoGenerate?: boolean
+    certPath?: string
+    keyPath?: string
+    caPath?: string
+  }
+  http?: {
+    endpoints?: {
+      chatCompletions?: {enabled?: boolean}
+      responses?: {
+        enabled?: boolean
+        maxBodyBytes?: number
+        maxUrlParts?: number
+        files?: Record<string, unknown>
+        images?: Record<string, unknown>
+      }
+    }
+  }
+  nodes?: {
+    browser?: {mode?: 'auto' | 'manual' | 'off'; node?: string}
+    allowCommands?: string[]
+    denyCommands?: string[]
+  }
+  trustedProxies?: string[]
+  tools?: {deny?: string[]; allow?: string[]}
+}
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+export type HooksConfig = {
+  enabled?: boolean
+  path?: string
+  token?: string
+  defaultSessionKey?: string
+  allowRequestSessionKey?: boolean
+  allowedSessionKeyPrefixes?: string[]
+  allowedAgentIds?: string[]
+  maxBodyBytes?: number
+  presets?: string[]
+  transformsDir?: string
+  mappings?: Array<{
+    id?: string
+    match?: {path?: string; source?: string}
+    action?: 'wake' | 'agent'
+    wakeMode?: 'now' | 'next-heartbeat'
+    name?: string
+    agentId?: string
+    sessionKey?: string
+    messageTemplate?: string
+    textTemplate?: string
+    deliver?: boolean
+    allowUnsafeExternalContent?: boolean
+    channel?: string
+    to?: string
+    model?: string
+    thinking?: string
+    timeoutSeconds?: number
+    transform?: {module: string; export?: string}
+  }>
+  gmail?: Record<string, unknown>
+  internal?: {
+    enabled?: boolean
+    handlers?: Array<{event: string; module: string; export?: string}>
+    entries?: Record<
+      string,
+      {enabled?: boolean; env?: Record<string, string>; [key: string]: unknown}
+    >
+    load?: {extraDirs?: string[]}
+    installs?: Record<
+      string,
+      {
+        source: 'npm' | 'archive' | 'path'
+        spec?: string
+        sourcePath?: string
+        installPath?: string
+        version?: string
+        installedAt?: string
+        hooks?: string[]
+      }
+    >
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Memory
+// ---------------------------------------------------------------------------
+
+export type MemoryConfig = {
+  backend?: 'builtin' | 'qmd'
+  citations?: 'auto' | 'on' | 'off'
+  qmd?: {
+    command?: string
+    searchMode?: 'query' | 'search' | 'vsearch'
+    includeDefaultMemory?: boolean
+    paths?: Array<{path: string; name?: string; pattern?: string}>
+    sessions?: {enabled?: boolean; exportDir?: string; retentionDays?: number}
+    update?: {
+      interval?: string
+      debounceMs?: number
+      onBoot?: boolean
+      waitForBootSync?: boolean
+      embedInterval?: string
+      commandTimeoutMs?: number
+      updateTimeoutMs?: number
+      embedTimeoutMs?: number
+    }
+    limits?: {
+      maxResults?: number
+      maxSnippetChars?: number
+      maxInjectedChars?: number
+      timeoutMs?: number
+    }
+    scope?: SessionSendPolicyConfig
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Discovery / Canvas / Talk
+// ---------------------------------------------------------------------------
+
+export type DiscoveryConfig = {
+  wideArea?: {enabled?: boolean; domain?: string}
+  mdns?: {mode?: 'off' | 'minimal' | 'full'}
+}
+
+export type CanvasHostConfig = {
+  enabled?: boolean
+  root?: string
+  port?: number
+  liveReload?: boolean
+}
+
+export type TalkConfig = {
+  voiceId?: string
+  voiceAliases?: Record<string, string>
+  modelId?: string
+  outputFormat?: string
+  apiKey?: string
+  interruptOnSpeech?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Top-level config
+// ---------------------------------------------------------------------------
+
+export type OpenClawConfig = {
+  meta?: {
+    lastTouchedVersion?: string
+    lastTouchedAt?: string
+  }
+  auth?: AuthConfig
+  env?: {
+    shellEnv?: {enabled?: boolean; timeoutMs?: number}
+    vars?: Record<string, string>
+    [key: string]:
+      | string
+      | Record<string, string>
+      | {enabled?: boolean; timeoutMs?: number}
+      | undefined
+  }
+  wizard?: {
+    lastRunAt?: string
+    lastRunVersion?: string
+    lastRunCommit?: string
+    lastRunCommand?: string
+    lastRunMode?: 'local' | 'remote'
+  }
+  diagnostics?: DiagnosticsConfig
+  logging?: LoggingConfig
+  update?: {
+    channel?: 'stable' | 'beta' | 'dev'
+    checkOnStart?: boolean
+  }
+  browser?: BrowserConfig
+  ui?: {
+    seamColor?: string
+    assistant?: {name?: string; avatar?: string}
+  }
+  skills?: SkillsConfig
+  plugins?: PluginsConfig
+  models?: ModelsConfig
+  nodeHost?: NodeHostConfig
+  agents?: AgentsConfig
+  tools?: ToolsConfig
+  bindings?: AgentBinding[]
+  broadcast?: BroadcastConfig
+  audio?: AudioConfig
+  messages?: MessagesConfig
+  commands?: CommandsConfig
+  approvals?: ApprovalsConfig
+  session?: SessionConfig
+  web?: WebConfig
+  channels?: ChannelsConfig
+  cron?: CronConfig
+  hooks?: HooksConfig
+  discovery?: DiscoveryConfig
+  canvasHost?: CanvasHostConfig
+  talk?: TalkConfig
+  gateway?: GatewayConfig
+  memory?: MemoryConfig
+}
+
+// ---------------------------------------------------------------------------
+// Config file snapshot (returned by runtime config loaders)
+// ---------------------------------------------------------------------------
+
+export type ConfigValidationIssue = {
+  path: string
+  message: string
+}
+
+export type ConfigFileSnapshot = {
+  path: string
+  exists: boolean
+  raw: string | null
+  parsed: unknown
+  resolved: OpenClawConfig
+  valid: boolean
+  config: OpenClawConfig
+  hash?: string
+  issues: ConfigValidationIssue[]
+  warnings: ConfigValidationIssue[]
+  legacyIssues: ConfigValidationIssue[]
+}