From f8171ffcdc63bfb2801a553fae8aef80009dfbbc Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Sun, 22 Feb 2026 15:17:07 -0600 Subject: [PATCH] Config UI: tag filters and complete schema help/labels coverage (#23796) * Config UI: add tag filters and complete schema help/labels * Config UI: finalize tags/help polish and unblock test suite * Protocol: regenerate Swift gateway models --- CHANGELOG.md | 1 + .../OpenClawProtocol/GatewayModels.swift | 12 + .../OpenClawProtocol/GatewayModels.swift | 12 + src/channels/plugins/types.plugin.ts | 1 + src/config/schema.help.quality.test.ts | 763 +++++++++++++ src/config/schema.help.ts | 1005 +++++++++++++++-- src/config/schema.hints.ts | 4 +- src/config/schema.labels.ts | 360 +++++- src/config/schema.tags.test.ts | 46 + src/config/schema.tags.ts | 180 +++ src/config/schema.ts | 9 +- src/gateway/protocol/schema/config.ts | 1 + .../server/ws-connection/auth-context.test.ts | 14 +- src/plugins/types.ts | 1 + src/slack/monitor/replies.ts | 7 + src/tui/tui-command-handlers.test.ts | 19 +- test/media-understanding.auto.test.ts | 19 + ui/src/styles/config.css | 250 +++- ui/src/ui/config-form.browser.test.ts | 107 ++ ui/src/ui/types.ts | 1 + ui/src/ui/views/config-form.node.ts | 401 ++++++- ui/src/ui/views/config-form.render.ts | 92 +- .../ui/views/config-form.search.node.test.ts | 69 ++ ui/src/ui/views/config-form.shared.ts | 2 + ui/src/ui/views/config-search.node.test.ts | 50 + ui/src/ui/views/config-search.ts | 92 ++ ui/src/ui/views/config.browser.test.ts | 31 + ui/src/ui/views/config.ts | 134 ++- 28 files changed, 3409 insertions(+), 274 deletions(-) create mode 100644 src/config/schema.help.quality.test.ts create mode 100644 src/config/schema.tags.test.ts create mode 100644 src/config/schema.tags.ts create mode 100644 ui/src/ui/views/config-form.search.node.test.ts create mode 100644 ui/src/ui/views/config-search.node.test.ts create mode 100644 ui/src/ui/views/config-search.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index deda3adfd56..3864683ca02 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ Docs: https://docs.openclaw.ai ### Changes +- Config/UI: add tag-aware settings filtering and broaden config labels/help copy so fields are easier to discover and understand in the dashboard config screen. - Update/Core: add an optional built-in auto-updater for package installs (`update.auto.*`), default-off, with stable rollout delay+jitter and beta hourly cadence. - CLI/Update: add `openclaw update --dry-run` to preview channel/tag/target/restart actions without mutating config, installing, syncing plugins, or restarting. - Skills: remove bundled `food-order` skill from this repo; manage/install it from ClawHub instead. diff --git a/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift b/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift index 2f2dd7f6090..2909418d0c3 100644 --- a/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift +++ b/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift @@ -2381,6 +2381,9 @@ public struct CronRunLogEntry: Codable, Sendable { public let status: AnyCodable? public let error: String? public let summary: String? + public let delivered: Bool? + public let deliverystatus: AnyCodable? + public let deliveryerror: String? public let sessionid: String? public let sessionkey: String? public let runatms: Int? @@ -2394,6 +2397,9 @@ public struct CronRunLogEntry: Codable, Sendable { status: AnyCodable?, error: String?, summary: String?, + delivered: Bool?, + deliverystatus: AnyCodable?, + deliveryerror: String?, sessionid: String?, sessionkey: String?, runatms: Int?, @@ -2406,6 +2412,9 @@ public struct CronRunLogEntry: Codable, Sendable { self.status = status self.error = error self.summary = summary + self.delivered = delivered + self.deliverystatus = deliverystatus + self.deliveryerror = deliveryerror self.sessionid = sessionid self.sessionkey = sessionkey self.runatms = runatms @@ -2420,6 +2429,9 @@ public struct CronRunLogEntry: Codable, Sendable { case status case error case summary + case delivered + case deliverystatus = "deliveryStatus" + case deliveryerror = "deliveryError" case sessionid = "sessionId" case sessionkey = "sessionKey" case runatms = "runAtMs" diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift index 2f2dd7f6090..2909418d0c3 100644 --- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift +++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift @@ -2381,6 +2381,9 @@ public struct CronRunLogEntry: Codable, Sendable { public let status: AnyCodable? public let error: String? public let summary: String? + public let delivered: Bool? + public let deliverystatus: AnyCodable? + public let deliveryerror: String? public let sessionid: String? public let sessionkey: String? public let runatms: Int? @@ -2394,6 +2397,9 @@ public struct CronRunLogEntry: Codable, Sendable { status: AnyCodable?, error: String?, summary: String?, + delivered: Bool?, + deliverystatus: AnyCodable?, + deliveryerror: String?, sessionid: String?, sessionkey: String?, runatms: Int?, @@ -2406,6 +2412,9 @@ public struct CronRunLogEntry: Codable, Sendable { self.status = status self.error = error self.summary = summary + self.delivered = delivered + self.deliverystatus = deliverystatus + self.deliveryerror = deliveryerror self.sessionid = sessionid self.sessionkey = sessionkey self.runatms = runatms @@ -2420,6 +2429,9 @@ public struct CronRunLogEntry: Codable, Sendable { case status case error case summary + case delivered + case deliverystatus = "deliveryStatus" + case deliveryerror = "deliveryError" case sessionid = "sessionId" case sessionkey = "sessionKey" case runatms = "runAtMs" diff --git a/src/channels/plugins/types.plugin.ts b/src/channels/plugins/types.plugin.ts index 044cbd5864d..a0d5aabadc7 100644 --- a/src/channels/plugins/types.plugin.ts +++ b/src/channels/plugins/types.plugin.ts @@ -33,6 +33,7 @@ import type { export type ChannelConfigUiHint = { label?: string; help?: string; + tags?: string[]; advanced?: boolean; sensitive?: boolean; placeholder?: string; diff --git a/src/config/schema.help.quality.test.ts b/src/config/schema.help.quality.test.ts new file mode 100644 index 00000000000..e1b9addaed6 --- /dev/null +++ b/src/config/schema.help.quality.test.ts @@ -0,0 +1,763 @@ +import { describe, expect, it } from "vitest"; +import { FIELD_HELP } from "./schema.help.js"; +import { FIELD_LABELS } from "./schema.labels.js"; + +const ROOT_SECTIONS = [ + "meta", + "env", + "wizard", + "diagnostics", + "logging", + "update", + "browser", + "ui", + "auth", + "models", + "nodeHost", + "agents", + "tools", + "bindings", + "broadcast", + "audio", + "media", + "messages", + "commands", + "approvals", + "session", + "cron", + "hooks", + "web", + "channels", + "discovery", + "canvasHost", + "talk", + "gateway", + "memory", + "plugins", +] as const; + +const TARGET_KEYS = [ + "memory.citations", + "memory.backend", + "memory.qmd.searchMode", + "memory.qmd.scope", + "memory.qmd.includeDefaultMemory", + "memory.qmd.mcporter.enabled", + "memory.qmd.mcporter.serverName", + "memory.qmd.command", + "memory.qmd.mcporter", + "memory.qmd.mcporter.startDaemon", + "memory.qmd.paths", + "memory.qmd.paths.path", + "memory.qmd.paths.pattern", + "memory.qmd.paths.name", + "memory.qmd.sessions.enabled", + "memory.qmd.sessions.exportDir", + "memory.qmd.sessions.retentionDays", + "memory.qmd.update.interval", + "memory.qmd.update.debounceMs", + "memory.qmd.update.onBoot", + "memory.qmd.update.waitForBootSync", + "memory.qmd.update.embedInterval", + "memory.qmd.update.commandTimeoutMs", + "memory.qmd.update.updateTimeoutMs", + "memory.qmd.update.embedTimeoutMs", + "memory.qmd.limits.maxResults", + "memory.qmd.limits.maxSnippetChars", + "memory.qmd.limits.maxInjectedChars", + "memory.qmd.limits.timeoutMs", + "agents.defaults.memorySearch.provider", + "agents.defaults.memorySearch.fallback", + "agents.defaults.memorySearch.sources", + "agents.defaults.memorySearch.extraPaths", + "agents.defaults.memorySearch.experimental.sessionMemory", + "agents.defaults.memorySearch.remote.baseUrl", + "agents.defaults.memorySearch.remote.apiKey", + "agents.defaults.memorySearch.remote.headers", + "agents.defaults.memorySearch.remote.batch.enabled", + "agents.defaults.memorySearch.remote.batch.wait", + "agents.defaults.memorySearch.remote.batch.concurrency", + "agents.defaults.memorySearch.remote.batch.pollIntervalMs", + "agents.defaults.memorySearch.remote.batch.timeoutMinutes", + "agents.defaults.memorySearch.local.modelPath", + "agents.defaults.memorySearch.store.path", + "agents.defaults.memorySearch.store.vector.enabled", + "agents.defaults.memorySearch.store.vector.extensionPath", + "agents.defaults.memorySearch.query.hybrid.enabled", + "agents.defaults.memorySearch.query.hybrid.vectorWeight", + "agents.defaults.memorySearch.query.hybrid.textWeight", + "agents.defaults.memorySearch.query.hybrid.candidateMultiplier", + "agents.defaults.memorySearch.query.hybrid.mmr.enabled", + "agents.defaults.memorySearch.query.hybrid.mmr.lambda", + "agents.defaults.memorySearch.query.hybrid.temporalDecay.enabled", + "agents.defaults.memorySearch.query.hybrid.temporalDecay.halfLifeDays", + "agents.defaults.memorySearch.cache.enabled", + "agents.defaults.memorySearch.cache.maxEntries", + "agents.defaults.memorySearch.sync.onSearch", + "agents.defaults.memorySearch.sync.watch", + "agents.defaults.memorySearch.sync.sessions.deltaBytes", + "agents.defaults.memorySearch.sync.sessions.deltaMessages", + "models.mode", + "models.providers.*.auth", + "models.providers.*.authHeader", + "gateway.reload.mode", + "gateway.controlUi.allowInsecureAuth", + "gateway.controlUi.dangerouslyDisableDeviceAuth", + "cron", + "cron.enabled", + "cron.store", + "cron.maxConcurrentRuns", + "cron.webhook", + "cron.webhookToken", + "cron.sessionRetention", + "session", + "session.scope", + "session.dmScope", + "session.identityLinks", + "session.resetTriggers", + "session.idleMinutes", + "session.reset", + "session.reset.mode", + "session.reset.atHour", + "session.reset.idleMinutes", + "session.resetByType", + "session.resetByType.direct", + "session.resetByType.dm", + "session.resetByType.group", + "session.resetByType.thread", + "session.resetByChannel", + "session.store", + "session.typingIntervalSeconds", + "session.typingMode", + "session.mainKey", + "session.sendPolicy", + "session.sendPolicy.default", + "session.sendPolicy.rules", + "session.sendPolicy.rules[].action", + "session.sendPolicy.rules[].match", + "session.sendPolicy.rules[].match.channel", + "session.sendPolicy.rules[].match.chatType", + "session.sendPolicy.rules[].match.keyPrefix", + "session.sendPolicy.rules[].match.rawKeyPrefix", + "session.agentToAgent", + "session.agentToAgent.maxPingPongTurns", + "session.threadBindings", + "session.threadBindings.enabled", + "session.threadBindings.ttlHours", + "session.maintenance", + "session.maintenance.mode", + "session.maintenance.pruneAfter", + "session.maintenance.pruneDays", + "session.maintenance.maxEntries", + "session.maintenance.rotateBytes", + "approvals", + "approvals.exec", + "approvals.exec.enabled", + "approvals.exec.mode", + "approvals.exec.agentFilter", + "approvals.exec.sessionFilter", + "approvals.exec.targets", + "approvals.exec.targets[].channel", + "approvals.exec.targets[].to", + "approvals.exec.targets[].accountId", + "approvals.exec.targets[].threadId", + "nodeHost", + "nodeHost.browserProxy", + "nodeHost.browserProxy.enabled", + "nodeHost.browserProxy.allowProfiles", + "media", + "media.preserveFilenames", + "audio", + "audio.transcription", + "audio.transcription.command", + "audio.transcription.timeoutSeconds", + "bindings", + "bindings[].agentId", + "bindings[].match", + "bindings[].match.channel", + "bindings[].match.accountId", + "bindings[].match.peer", + "bindings[].match.peer.kind", + "bindings[].match.peer.id", + "bindings[].match.guildId", + "bindings[].match.teamId", + "bindings[].match.roles", + "broadcast", + "broadcast.strategy", + "broadcast.*", + "commands", + "commands.allowFrom", + "hooks", + "hooks.enabled", + "hooks.path", + "hooks.token", + "hooks.defaultSessionKey", + "hooks.allowRequestSessionKey", + "hooks.allowedSessionKeyPrefixes", + "hooks.allowedAgentIds", + "hooks.maxBodyBytes", + "hooks.transformsDir", + "hooks.mappings", + "hooks.mappings[].action", + "hooks.mappings[].wakeMode", + "hooks.mappings[].channel", + "hooks.mappings[].transform.module", + "hooks.gmail", + "hooks.gmail.pushToken", + "hooks.gmail.tailscale.mode", + "hooks.gmail.thinking", + "hooks.internal", + "hooks.internal.handlers", + "hooks.internal.handlers[].event", + "hooks.internal.handlers[].module", + "hooks.internal.load.extraDirs", + "messages", + "messages.messagePrefix", + "messages.responsePrefix", + "messages.groupChat", + "messages.groupChat.mentionPatterns", + "messages.groupChat.historyLimit", + "messages.queue", + "messages.queue.mode", + "messages.queue.byChannel", + "messages.queue.debounceMs", + "messages.queue.debounceMsByChannel", + "messages.queue.cap", + "messages.queue.drop", + "messages.inbound", + "messages.inbound.byChannel", + "messages.removeAckAfterReply", + "messages.tts", + "channels", + "channels.defaults", + "channels.defaults.groupPolicy", + "channels.defaults.heartbeat", + "channels.defaults.heartbeat.showOk", + "channels.defaults.heartbeat.showAlerts", + "channels.defaults.heartbeat.useIndicator", + "gateway", + "gateway.mode", + "gateway.bind", + "gateway.auth.mode", + "gateway.tailscale.mode", + "gateway.tools.allow", + "gateway.tools.deny", + "gateway.tls.enabled", + "gateway.tls.autoGenerate", + "gateway.http", + "gateway.http.endpoints", + "browser", + "browser.enabled", + "browser.cdpUrl", + "browser.headless", + "browser.noSandbox", + "browser.profiles", + "browser.profiles.*.driver", + "tools", + "tools.allow", + "tools.deny", + "tools.exec", + "tools.exec.host", + "tools.exec.security", + "tools.exec.ask", + "tools.exec.node", + "tools.agentToAgent.enabled", + "tools.elevated.enabled", + "tools.elevated.allowFrom", + "tools.subagents.tools", + "tools.sandbox.tools", + "web", + "web.enabled", + "web.heartbeatSeconds", + "web.reconnect", + "web.reconnect.initialMs", + "web.reconnect.maxMs", + "web.reconnect.factor", + "web.reconnect.jitter", + "web.reconnect.maxAttempts", + "discovery", + "discovery.wideArea.enabled", + "discovery.mdns", + "discovery.mdns.mode", + "canvasHost", + "canvasHost.enabled", + "canvasHost.root", + "canvasHost.port", + "canvasHost.liveReload", + "talk", + "talk.voiceId", + "talk.voiceAliases", + "talk.modelId", + "talk.outputFormat", + "talk.interruptOnSpeech", + "meta", + "env", + "env.shellEnv", + "env.shellEnv.enabled", + "env.shellEnv.timeoutMs", + "env.vars", + "wizard", + "wizard.lastRunAt", + "wizard.lastRunVersion", + "wizard.lastRunCommit", + "wizard.lastRunCommand", + "wizard.lastRunMode", + "diagnostics", + "diagnostics.otel", + "diagnostics.cacheTrace", + "logging", + "logging.level", + "logging.file", + "logging.consoleLevel", + "logging.consoleStyle", + "logging.redactSensitive", + "logging.redactPatterns", + "update", + "ui", + "ui.assistant", + "plugins", + "plugins.enabled", + "plugins.allow", + "plugins.deny", + "plugins.load", + "plugins.load.paths", + "plugins.slots", + "plugins.entries", + "plugins.entries.*.enabled", + "plugins.entries.*.apiKey", + "plugins.entries.*.env", + "plugins.entries.*.config", + "plugins.installs", + "auth", + "auth.cooldowns", + "models", + "models.providers", + "models.providers.*.baseUrl", + "models.providers.*.apiKey", + "models.providers.*.api", + "models.providers.*.headers", + "models.providers.*.models", + "models.bedrockDiscovery", + "models.bedrockDiscovery.enabled", + "models.bedrockDiscovery.region", + "models.bedrockDiscovery.providerFilter", + "models.bedrockDiscovery.refreshInterval", + "models.bedrockDiscovery.defaultContextWindow", + "models.bedrockDiscovery.defaultMaxTokens", + "agents", + "agents.defaults", + "agents.list", + "agents.defaults.compaction", + "agents.defaults.compaction.mode", + "agents.defaults.compaction.reserveTokens", + "agents.defaults.compaction.keepRecentTokens", + "agents.defaults.compaction.reserveTokensFloor", + "agents.defaults.compaction.maxHistoryShare", + "agents.defaults.compaction.memoryFlush", + "agents.defaults.compaction.memoryFlush.enabled", + "agents.defaults.compaction.memoryFlush.softThresholdTokens", + "agents.defaults.compaction.memoryFlush.prompt", + "agents.defaults.compaction.memoryFlush.systemPrompt", +] as const; + +const ENUM_EXPECTATIONS: Record = { + "memory.citations": ['"auto"', '"on"', '"off"'], + "memory.backend": ['"builtin"', '"qmd"'], + "memory.qmd.searchMode": ['"query"', '"search"', '"vsearch"'], + "models.mode": ['"merge"', '"replace"'], + "models.providers.*.auth": ['"api-key"', '"token"', '"oauth"', '"aws-sdk"'], + "gateway.reload.mode": ['"off"', '"restart"', '"hot"', '"hybrid"'], + "approvals.exec.mode": ['"session"', '"targets"', '"both"'], + "bindings[].match.peer.kind": ['"direct"', '"group"', '"channel"', '"dm"'], + "broadcast.strategy": ['"parallel"', '"sequential"'], + "hooks.mappings[].action": ['"wake"', '"agent"'], + "hooks.mappings[].wakeMode": ['"now"', '"next-heartbeat"'], + "hooks.gmail.tailscale.mode": ['"off"', '"serve"', '"funnel"'], + "hooks.gmail.thinking": ['"off"', '"minimal"', '"low"', '"medium"', '"high"'], + "messages.queue.mode": [ + '"steer"', + '"followup"', + '"collect"', + '"steer-backlog"', + '"steer+backlog"', + '"queue"', + '"interrupt"', + ], + "messages.queue.drop": ['"old"', '"new"', '"summarize"'], + "channels.defaults.groupPolicy": ['"open"', '"disabled"', '"allowlist"'], + "gateway.mode": ['"local"', '"remote"'], + "gateway.bind": ['"auto"', '"lan"', '"loopback"', '"custom"', '"tailnet"'], + "gateway.auth.mode": ['"none"', '"token"', '"password"', '"trusted-proxy"'], + "gateway.tailscale.mode": ['"off"', '"serve"', '"funnel"'], + "browser.profiles.*.driver": ['"clawd"', '"extension"'], + "discovery.mdns.mode": ['"off"', '"minimal"', '"full"'], + "wizard.lastRunMode": ['"local"', '"remote"'], + "diagnostics.otel.protocol": ['"http/protobuf"', '"grpc"'], + "logging.level": ['"silent"', '"fatal"', '"error"', '"warn"', '"info"', '"debug"', '"trace"'], + "logging.consoleLevel": [ + '"silent"', + '"fatal"', + '"error"', + '"warn"', + '"info"', + '"debug"', + '"trace"', + ], + "logging.consoleStyle": ['"pretty"', '"compact"', '"json"'], + "logging.redactSensitive": ['"off"', '"tools"'], + "update.channel": ['"stable"', '"beta"', '"dev"'], + "agents.defaults.compaction.mode": ['"default"', '"safeguard"'], +}; + +const TOOLS_HOOKS_TARGET_KEYS = [ + "hooks.gmail.account", + "hooks.gmail.allowUnsafeExternalContent", + "hooks.gmail.hookUrl", + "hooks.gmail.includeBody", + "hooks.gmail.label", + "hooks.gmail.model", + "hooks.gmail.serve", + "hooks.gmail.subscription", + "hooks.gmail.tailscale", + "hooks.gmail.topic", + "hooks.internal.entries", + "hooks.internal.installs", + "hooks.internal.load", + "hooks.mappings[].allowUnsafeExternalContent", + "hooks.mappings[].deliver", + "hooks.mappings[].id", + "hooks.mappings[].match", + "hooks.mappings[].messageTemplate", + "hooks.mappings[].model", + "hooks.mappings[].name", + "hooks.mappings[].textTemplate", + "hooks.mappings[].thinking", + "hooks.mappings[].transform", + "tools.alsoAllow", + "tools.byProvider", + "tools.exec.approvalRunningNoticeMs", + "tools.links.enabled", + "tools.links.maxLinks", + "tools.links.models", + "tools.links.scope", + "tools.links.timeoutSeconds", + "tools.media.audio.attachments", + "tools.media.audio.enabled", + "tools.media.audio.language", + "tools.media.audio.maxBytes", + "tools.media.audio.maxChars", + "tools.media.audio.models", + "tools.media.audio.prompt", + "tools.media.audio.scope", + "tools.media.audio.timeoutSeconds", + "tools.media.concurrency", + "tools.media.image.attachments", + "tools.media.image.enabled", + "tools.media.image.maxBytes", + "tools.media.image.maxChars", + "tools.media.image.models", + "tools.media.image.prompt", + "tools.media.image.scope", + "tools.media.image.timeoutSeconds", + "tools.media.models", + "tools.media.video.attachments", + "tools.media.video.enabled", + "tools.media.video.maxBytes", + "tools.media.video.maxChars", + "tools.media.video.models", + "tools.media.video.prompt", + "tools.media.video.scope", + "tools.media.video.timeoutSeconds", + "tools.profile", +] as const; + +const CHANNELS_AGENTS_TARGET_KEYS = [ + "agents.defaults.memorySearch.chunking.overlap", + "agents.defaults.memorySearch.chunking.tokens", + "agents.defaults.memorySearch.enabled", + "agents.defaults.memorySearch.model", + "agents.defaults.memorySearch.query.maxResults", + "agents.defaults.memorySearch.query.minScore", + "agents.defaults.memorySearch.sync.onSessionStart", + "agents.defaults.memorySearch.sync.watchDebounceMs", + "agents.defaults.workspace", + "agents.list[].tools.alsoAllow", + "agents.list[].tools.byProvider", + "agents.list[].tools.profile", + "channels.bluebubbles", + "channels.discord", + "channels.discord.token", + "channels.imessage", + "channels.imessage.cliPath", + "channels.irc", + "channels.mattermost", + "channels.msteams", + "channels.signal", + "channels.signal.account", + "channels.slack", + "channels.slack.appToken", + "channels.slack.botToken", + "channels.slack.userToken", + "channels.slack.userTokenReadOnly", + "channels.telegram", + "channels.telegram.botToken", + "channels.telegram.capabilities.inlineButtons", + "channels.whatsapp", +] as const; + +const FINAL_BACKLOG_TARGET_KEYS = [ + "browser.evaluateEnabled", + "browser.remoteCdpHandshakeTimeoutMs", + "browser.remoteCdpTimeoutMs", + "browser.snapshotDefaults", + "browser.snapshotDefaults.mode", + "browser.ssrfPolicy", + "browser.ssrfPolicy.allowPrivateNetwork", + "browser.ssrfPolicy.allowedHostnames", + "browser.ssrfPolicy.hostnameAllowlist", + "diagnostics.enabled", + "diagnostics.otel.enabled", + "diagnostics.otel.endpoint", + "diagnostics.otel.flushIntervalMs", + "diagnostics.otel.headers", + "diagnostics.otel.logs", + "diagnostics.otel.metrics", + "diagnostics.otel.sampleRate", + "diagnostics.otel.serviceName", + "diagnostics.otel.traces", + "gateway.remote.password", + "gateway.remote.token", + "skills.load.watch", + "skills.load.watchDebounceMs", + "talk.apiKey", + "ui.assistant.avatar", + "ui.assistant.name", + "ui.seamColor", +] as const; + +describe("config help copy quality", () => { + it("keeps root section labels and help complete", () => { + for (const key of ROOT_SECTIONS) { + expect(FIELD_LABELS[key], `missing root label for ${key}`).toBeDefined(); + expect(FIELD_HELP[key], `missing root help for ${key}`).toBeDefined(); + } + }); + + it("keeps labels in parity for all help keys", () => { + for (const key of Object.keys(FIELD_HELP)) { + expect(FIELD_LABELS[key], `missing label for help key ${key}`).toBeDefined(); + } + }); + + it("covers the target confusing fields with non-trivial explanations", () => { + for (const key of TARGET_KEYS) { + const help = FIELD_HELP[key]; + expect(help, `missing help for ${key}`).toBeDefined(); + expect(help.length, `help too short for ${key}`).toBeGreaterThanOrEqual(80); + expect( + /(default|keep|use|enable|disable|controls|selects|sets|defines)/i.test(help), + `help should include operational guidance for ${key}`, + ).toBe(true); + } + }); + + it("covers tools/hooks help keys with non-trivial operational guidance", () => { + for (const key of TOOLS_HOOKS_TARGET_KEYS) { + const help = FIELD_HELP[key]; + expect(help, `missing help for ${key}`).toBeDefined(); + expect(help.length, `help too short for ${key}`).toBeGreaterThanOrEqual(80); + expect( + /(default|keep|use|enable|disable|controls|set|sets|increase|lower|prefer|tune|avoid|choose|when)/i.test( + help, + ), + `help should include operational guidance for ${key}`, + ).toBe(true); + } + }); + + it("covers channels/agents help keys with non-trivial operational guidance", () => { + for (const key of CHANNELS_AGENTS_TARGET_KEYS) { + const help = FIELD_HELP[key]; + expect(help, `missing help for ${key}`).toBeDefined(); + expect(help.length, `help too short for ${key}`).toBeGreaterThanOrEqual(80); + expect( + /(default|keep|use|enable|disable|controls|set|sets|increase|lower|prefer|tune|avoid|choose|when)/i.test( + help, + ), + `help should include operational guidance for ${key}`, + ).toBe(true); + } + }); + + it("covers final backlog help keys with non-trivial operational guidance", () => { + for (const key of FINAL_BACKLOG_TARGET_KEYS) { + const help = FIELD_HELP[key]; + expect(help, `missing help for ${key}`).toBeDefined(); + expect(help.length, `help too short for ${key}`).toBeGreaterThanOrEqual(80); + expect( + /(default|keep|use|enable|disable|controls|set|sets|increase|lower|prefer|tune|avoid|choose|when)/i.test( + help, + ), + `help should include operational guidance for ${key}`, + ).toBe(true); + } + }); + + it("documents option behavior for enum-style fields", () => { + for (const [key, options] of Object.entries(ENUM_EXPECTATIONS)) { + const help = FIELD_HELP[key]; + expect(help, `missing help for enum key ${key}`).toBeDefined(); + for (const token of options) { + expect(help.includes(token), `missing option ${token} in ${key}`).toBe(true); + } + } + }); + + it("explains memory citations mode semantics", () => { + const help = FIELD_HELP["memory.citations"]; + expect(help.includes('"auto"')).toBe(true); + expect(help.includes('"on"')).toBe(true); + expect(help.includes('"off"')).toBe(true); + expect(/always|always shows/i.test(help)).toBe(true); + expect(/hides|hide/i.test(help)).toBe(true); + }); + + it("includes concrete examples on path and interval fields", () => { + expect(FIELD_HELP["memory.qmd.paths.pattern"].includes("**/*.md")).toBe(true); + expect(FIELD_HELP["memory.qmd.update.interval"].includes("5m")).toBe(true); + expect(FIELD_HELP["memory.qmd.update.embedInterval"].includes("60m")).toBe(true); + expect(FIELD_HELP["agents.defaults.memorySearch.store.path"]).toContain( + "~/.openclaw/memory/{agentId}.sqlite", + ); + }); + + it("documents cron deprecation, migration, and retention formats", () => { + const legacy = FIELD_HELP["cron.webhook"]; + expect(/deprecated|legacy/i.test(legacy)).toBe(true); + expect(legacy.includes('delivery.mode="webhook"')).toBe(true); + expect(legacy.includes("delivery.to")).toBe(true); + + const retention = FIELD_HELP["cron.sessionRetention"]; + expect(retention.includes("24h")).toBe(true); + expect(retention.includes("7d")).toBe(true); + expect(retention.includes("1h30m")).toBe(true); + expect(/false/i.test(retention)).toBe(true); + + const token = FIELD_HELP["cron.webhookToken"]; + expect(/token|bearer/i.test(token)).toBe(true); + expect(/secret|env|rotate/i.test(token)).toBe(true); + }); + + it("documents session send-policy examples and prefix semantics", () => { + const rules = FIELD_HELP["session.sendPolicy.rules"]; + expect(rules.includes("{ action:")).toBe(true); + expect(rules.includes('"deny"')).toBe(true); + expect(rules.includes('"discord"')).toBe(true); + + const keyPrefix = FIELD_HELP["session.sendPolicy.rules[].match.keyPrefix"]; + expect(/normalized/i.test(keyPrefix)).toBe(true); + + const rawKeyPrefix = FIELD_HELP["session.sendPolicy.rules[].match.rawKeyPrefix"]; + expect(/raw|unnormalized/i.test(rawKeyPrefix)).toBe(true); + }); + + it("documents session maintenance duration/size examples and deprecations", () => { + const pruneAfter = FIELD_HELP["session.maintenance.pruneAfter"]; + expect(pruneAfter.includes("30d")).toBe(true); + expect(pruneAfter.includes("12h")).toBe(true); + + const rotate = FIELD_HELP["session.maintenance.rotateBytes"]; + expect(rotate.includes("10mb")).toBe(true); + expect(rotate.includes("1gb")).toBe(true); + + const deprecated = FIELD_HELP["session.maintenance.pruneDays"]; + expect(/deprecated/i.test(deprecated)).toBe(true); + expect(deprecated.includes("session.maintenance.pruneAfter")).toBe(true); + }); + + it("documents approvals filters and target semantics", () => { + const sessionFilter = FIELD_HELP["approvals.exec.sessionFilter"]; + expect(/substring|regex/i.test(sessionFilter)).toBe(true); + expect(sessionFilter.includes("discord:")).toBe(true); + expect(sessionFilter.includes("^agent:ops:")).toBe(true); + + const agentFilter = FIELD_HELP["approvals.exec.agentFilter"]; + expect(agentFilter.includes("primary")).toBe(true); + expect(agentFilter.includes("ops-agent")).toBe(true); + + const targetTo = FIELD_HELP["approvals.exec.targets[].to"]; + expect(/channel ID|user ID|thread root/i.test(targetTo)).toBe(true); + expect(/differs|per provider/i.test(targetTo)).toBe(true); + }); + + it("documents broadcast and audio command examples", () => { + const audioCmd = FIELD_HELP["audio.transcription.command"]; + expect(audioCmd.includes("whisper-cli")).toBe(true); + expect(audioCmd.includes("{input}")).toBe(true); + + const broadcastMap = FIELD_HELP["broadcast.*"]; + expect(/source peer ID/i.test(broadcastMap)).toBe(true); + expect(/destination peer IDs/i.test(broadcastMap)).toBe(true); + }); + + it("documents hook transform safety and queue behavior options", () => { + const transformModule = FIELD_HELP["hooks.mappings[].transform.module"]; + expect(/relative/i.test(transformModule)).toBe(true); + expect(/path traversal|reviewed|controlled/i.test(transformModule)).toBe(true); + + const queueMode = FIELD_HELP["messages.queue.mode"]; + expect(queueMode.includes('"interrupt"')).toBe(true); + expect(queueMode.includes('"steer+backlog"')).toBe(true); + }); + + it("documents gateway bind modes and web reconnect semantics", () => { + const bind = FIELD_HELP["gateway.bind"]; + expect(bind.includes('"loopback"')).toBe(true); + expect(bind.includes('"tailnet"')).toBe(true); + + const reconnect = FIELD_HELP["web.reconnect.maxAttempts"]; + expect(/0 means no retries|no retries/i.test(reconnect)).toBe(true); + expect(/failure sequence|retry/i.test(reconnect)).toBe(true); + }); + + it("documents metadata/admin semantics for logging, wizard, and plugins", () => { + const wizardMode = FIELD_HELP["wizard.lastRunMode"]; + expect(wizardMode.includes('"local"')).toBe(true); + expect(wizardMode.includes('"remote"')).toBe(true); + + const consoleStyle = FIELD_HELP["logging.consoleStyle"]; + expect(consoleStyle.includes('"pretty"')).toBe(true); + expect(consoleStyle.includes('"compact"')).toBe(true); + expect(consoleStyle.includes('"json"')).toBe(true); + + const pluginApiKey = FIELD_HELP["plugins.entries.*.apiKey"]; + expect(/secret|env|credential/i.test(pluginApiKey)).toBe(true); + + const pluginEnv = FIELD_HELP["plugins.entries.*.env"]; + expect(/scope|plugin|environment/i.test(pluginEnv)).toBe(true); + }); + + it("documents auth/model root semantics and provider secret handling", () => { + const providerKey = FIELD_HELP["models.providers.*.apiKey"]; + expect(/secret|env|credential/i.test(providerKey)).toBe(true); + + const bedrockRefresh = FIELD_HELP["models.bedrockDiscovery.refreshInterval"]; + expect(/refresh|seconds|interval/i.test(bedrockRefresh)).toBe(true); + expect(/cost|noise|api/i.test(bedrockRefresh)).toBe(true); + + const authCooldowns = FIELD_HELP["auth.cooldowns"]; + expect(/cooldown|backoff|retry/i.test(authCooldowns)).toBe(true); + }); + + it("documents agent compaction safeguards and memory flush behavior", () => { + const mode = FIELD_HELP["agents.defaults.compaction.mode"]; + expect(mode.includes('"default"')).toBe(true); + expect(mode.includes('"safeguard"')).toBe(true); + + const historyShare = FIELD_HELP["agents.defaults.compaction.maxHistoryShare"]; + expect(/0\\.1-0\\.9|fraction|share/i.test(historyShare)).toBe(true); + + const flush = FIELD_HELP["agents.defaults.compaction.memoryFlush.enabled"]; + expect(/pre-compaction|memory flush|token/i.test(flush)).toBe(true); + }); +}); diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts index 1dc98be1d93..825d34710a8 100644 --- a/src/config/schema.help.ts +++ b/src/config/schema.help.ts @@ -1,8 +1,52 @@ import { IRC_FIELD_HELP } from "./schema.irc.js"; export const FIELD_HELP: Record = { + meta: "Metadata fields automatically maintained by OpenClaw to record write/version history for this config file. Keep these values system-managed and avoid manual edits unless debugging migration history.", "meta.lastTouchedVersion": "Auto-set when OpenClaw writes the config.", "meta.lastTouchedAt": "ISO timestamp of the last config write (auto-set).", + env: "Environment import and override settings used to supply runtime variables to the gateway process. Use this section to control shell-env loading and explicit variable injection behavior.", + "env.shellEnv": + "Shell environment import controls for loading variables from your login shell during startup. Keep this enabled when you depend on profile-defined secrets or PATH customizations.", + "env.shellEnv.enabled": + "Enables loading environment variables from the user shell profile during startup initialization. Keep enabled for developer machines, or disable in locked-down service environments with explicit env management.", + "env.shellEnv.timeoutMs": + "Maximum time in milliseconds allowed for shell environment resolution before fallback behavior applies. Use tighter timeouts for faster startup, or increase when shell initialization is heavy.", + "env.vars": + "Explicit key/value environment variable overrides merged into runtime process environment for OpenClaw. Use this for deterministic env configuration instead of relying only on shell profile side effects.", + wizard: + "Setup wizard state tracking fields that record the most recent guided onboarding run details. Keep these fields for observability and troubleshooting of setup flows across upgrades.", + "wizard.lastRunAt": + "ISO timestamp for when the setup wizard most recently completed on this host. Use this to confirm onboarding recency during support and operational audits.", + "wizard.lastRunVersion": + "OpenClaw version recorded at the time of the most recent wizard run on this config. Use this when diagnosing behavior differences across version-to-version onboarding changes.", + "wizard.lastRunCommit": + "Source commit identifier recorded for the last wizard execution in development builds. Use this to correlate onboarding behavior with exact source state during debugging.", + "wizard.lastRunCommand": + "Command invocation recorded for the latest wizard run to preserve execution context. Use this to reproduce onboarding steps when verifying setup regressions.", + "wizard.lastRunMode": + 'Wizard execution mode recorded as "local" or "remote" for the most recent onboarding flow. Use this to understand whether setup targeted direct local runtime or remote gateway topology.', + diagnostics: + "Diagnostics controls for targeted tracing, telemetry export, and cache inspection during debugging. Keep baseline diagnostics minimal in production and enable deeper signals only when investigating issues.", + "diagnostics.otel": + "OpenTelemetry export settings for traces, metrics, and logs emitted by gateway components. Use this when integrating with centralized observability backends and distributed tracing pipelines.", + "diagnostics.cacheTrace": + "Cache-trace logging settings for observing cache decisions and payload context in embedded runs. Enable this temporarily for debugging and disable afterward to reduce sensitive log footprint.", + logging: + "Logging behavior controls for severity, output destinations, formatting, and sensitive-data redaction. Keep levels and redaction strict enough for production while preserving useful diagnostics.", + "logging.level": + 'Primary log level threshold for runtime logger output: "silent", "fatal", "error", "warn", "info", "debug", or "trace". Keep "info" or "warn" for production, and use debug/trace only during investigation.', + "logging.file": + "Optional file path for persisted log output in addition to or instead of console logging. Use a managed writable path and align retention/rotation with your operational policy.", + "logging.consoleLevel": + 'Console-specific log threshold: "silent", "fatal", "error", "warn", "info", "debug", or "trace" for terminal output control. Use this to keep local console quieter while retaining richer file logging if needed.', + "logging.consoleStyle": + 'Console output format style: "pretty", "compact", or "json" based on operator and ingestion needs. Use json for machine parsing pipelines and pretty/compact for human-first terminal workflows.', + "logging.redactSensitive": + 'Sensitive redaction mode: "off" disables built-in masking, while "tools" redacts sensitive tool/config payload fields. Keep "tools" in shared logs unless you have isolated secure log sinks.', + "logging.redactPatterns": + "Additional custom redact regex patterns applied to log output before emission/storage. Use this to mask org-specific tokens and identifiers not covered by built-in redaction rules.", + update: + "Update-channel and startup-check behavior for keeping OpenClaw runtime versions current. Use conservative channels in production and more experimental channels only in controlled environments.", "update.channel": 'Update channel for git + npm installs ("stable", "beta", or "dev").', "update.checkOnStart": "Check for npm updates when the gateway starts (default: true).", "update.auto.enabled": "Enable background auto-update for package installs (default: false).", @@ -11,7 +55,75 @@ export const FIELD_HELP: Record = { "update.auto.stableJitterHours": "Extra stable-channel rollout spread window in hours (default: 12).", "update.auto.betaCheckIntervalHours": "How often beta-channel checks run in hours (default: 1).", + gateway: + "Gateway runtime surface for bind mode, auth, control UI, remote transport, and operational safety controls. Keep conservative defaults unless you intentionally expose the gateway beyond trusted local interfaces.", + "gateway.port": + "TCP port used by the gateway listener for API, control UI, and channel-facing ingress paths. Use a dedicated port and avoid collisions with reverse proxies or local developer services.", + "gateway.mode": + 'Gateway operation mode: "local" runs channels and agent runtime on this host, while "remote" connects through remote transport. Keep "local" unless you intentionally run a split remote gateway topology.', + "gateway.bind": + 'Network bind profile: "auto", "lan", "loopback", "custom", or "tailnet" to control interface exposure. Keep "loopback" or "auto" for safest local operation unless external clients must connect.', + "gateway.customBindHost": + "Explicit bind host/IP used when gateway.bind is set to custom for manual interface targeting. Use a precise address and avoid wildcard binds unless external exposure is required.", + "gateway.controlUi": + "Control UI hosting settings including enablement, pathing, and browser-origin/auth hardening behavior. Keep UI exposure minimal and pair with strong auth controls before internet-facing deployments.", + "gateway.controlUi.enabled": + "Enables serving the gateway Control UI from the gateway HTTP process when true. Keep enabled for local administration, and disable when an external control surface replaces it.", + "gateway.auth": + "Authentication policy for gateway HTTP/WebSocket access including mode, credentials, trusted-proxy behavior, and rate limiting. Keep auth enabled for every non-loopback deployment.", + "gateway.auth.mode": + 'Gateway auth mode: "none", "token", "password", or "trusted-proxy" depending on your edge architecture. Use token/password for direct exposure, and trusted-proxy only behind hardened identity-aware proxies.', + "gateway.auth.allowTailscale": + "Allows trusted Tailscale identity paths to satisfy gateway auth checks when configured. Use this only when your tailnet identity posture is strong and operator workflows depend on it.", + "gateway.auth.rateLimit": + "Login/auth attempt throttling controls to reduce credential brute-force risk at the gateway boundary. Keep enabled in exposed environments and tune thresholds to your traffic baseline.", + "gateway.auth.trustedProxy": + "Trusted-proxy auth header mapping for upstream identity providers that inject user claims. Use only with known proxy CIDRs and strict header allowlists to prevent spoofed identity headers.", + "gateway.trustedProxies": + "CIDR/IP allowlist of upstream proxies permitted to provide forwarded client identity headers. Keep this list narrow so untrusted hops cannot impersonate users.", + "gateway.allowRealIpFallback": + "Enables x-real-ip fallback when x-forwarded-for is missing in proxy scenarios. Keep disabled unless your ingress stack requires this compatibility behavior.", + "gateway.tools": + "Gateway-level tool exposure allow/deny policy that can restrict runtime tool availability independent of agent/tool profiles. Use this for coarse emergency controls and production hardening.", + "gateway.tools.allow": + "Explicit gateway-level tool allowlist when you want a narrow set of tools available at runtime. Use this for locked-down environments where tool scope must be tightly controlled.", + "gateway.tools.deny": + "Explicit gateway-level tool denylist to block risky tools even if lower-level policies allow them. Use deny rules for emergency response and defense-in-depth hardening.", + "gateway.channelHealthCheckMinutes": + "Interval in minutes for automatic channel health probing and status updates. Use lower intervals for faster detection, or higher intervals to reduce periodic probe noise.", + "gateway.tailscale": + "Tailscale integration settings for Serve/Funnel exposure and lifecycle handling on gateway start/exit. Keep off unless your deployment intentionally relies on Tailscale ingress.", + "gateway.tailscale.mode": + 'Tailscale publish mode: "off", "serve", or "funnel" for private or public exposure paths. Use "serve" for tailnet-only access and "funnel" only when public internet reachability is required.', + "gateway.tailscale.resetOnExit": + "Resets Tailscale Serve/Funnel state on gateway exit to avoid stale published routes after shutdown. Keep enabled unless another controller manages publish lifecycle outside the gateway.", + "gateway.remote": + "Remote gateway connection settings for direct or SSH transport when this instance proxies to another runtime host. Use remote mode only when split-host operation is intentionally configured.", + "gateway.remote.transport": + 'Remote connection transport: "direct" uses configured URL connectivity, while "ssh" tunnels through SSH. Use SSH when you need encrypted tunnel semantics without exposing remote ports.', + "gateway.reload": + "Live config-reload policy for how edits are applied and when full restarts are triggered. Keep hybrid behavior for safest operational updates unless debugging reload internals.", + "gateway.tls": + "TLS certificate and key settings for terminating HTTPS directly in the gateway process. Use explicit certificates in production and avoid plaintext exposure on untrusted networks.", + "gateway.tls.enabled": + "Enables TLS termination at the gateway listener so clients connect over HTTPS/WSS directly. Keep enabled for direct internet exposure or any untrusted network boundary.", + "gateway.tls.autoGenerate": + "Auto-generates a local TLS certificate/key pair when explicit files are not configured. Use only for local/dev setups and replace with real certificates for production traffic.", + "gateway.tls.certPath": + "Filesystem path to the TLS certificate file used by the gateway when TLS is enabled. Use managed certificate paths and keep renewal automation aligned with this location.", + "gateway.tls.keyPath": + "Filesystem path to the TLS private key file used by the gateway when TLS is enabled. Keep this key file permission-restricted and rotate per your security policy.", + "gateway.tls.caPath": + "Optional CA bundle path for client verification or custom trust-chain requirements at the gateway edge. Use this when private PKI or custom certificate chains are part of deployment.", + "gateway.http": + "Gateway HTTP API configuration grouping endpoint toggles and transport-facing API exposure controls. Keep only required endpoints enabled to reduce attack surface.", + "gateway.http.endpoints": + "HTTP endpoint feature toggles under the gateway API surface for compatibility routes and optional integrations. Enable endpoints intentionally and monitor access patterns after rollout.", "gateway.remote.url": "Remote Gateway WebSocket URL (ws:// or wss://).", + "gateway.remote.token": + "Bearer token used to authenticate this client to a remote gateway in token-auth deployments. Store via secret/env substitution and rotate alongside remote gateway auth changes.", + "gateway.remote.password": + "Password credential used for remote gateway authentication when password mode is enabled. Keep this secret managed externally and avoid plaintext values in committed config.", "gateway.remote.tlsFingerprint": "Expected sha256 TLS fingerprint for the remote gateway (pin to avoid MITM).", "gateway.remote.sshTarget": @@ -21,14 +133,152 @@ export const FIELD_HELP: Record = { "Optional allowlist of skills for this agent (omit = all skills; empty = no skills).", "agents.list[].skills": "Optional allowlist of skills for this agent (omit = all skills; empty = no skills).", + agents: + "Agent runtime configuration root covering defaults and explicit agent entries used for routing and execution context. Keep this section explicit so model/tool behavior stays predictable across multi-agent workflows.", + "agents.defaults": + "Shared default settings inherited by agents unless overridden per entry in agents.list. Use defaults to enforce consistent baseline behavior and reduce duplicated per-agent configuration.", + "agents.list": + "Explicit list of configured agents with IDs and optional overrides for model, tools, identity, and workspace. Keep IDs stable over time so bindings, approvals, and session routing remain deterministic.", "agents.list[].identity.avatar": "Avatar image path (relative to the agent workspace only) or a remote URL/data URL.", "agents.defaults.heartbeat.suppressToolErrorWarnings": "Suppress tool error warning payloads during heartbeat runs.", "agents.list[].heartbeat.suppressToolErrorWarnings": "Suppress tool error warning payloads during heartbeat runs.", + browser: + "Browser runtime controls for local or remote CDP attachment, profile routing, and screenshot/snapshot behavior. Keep defaults unless your automation workflow requires custom browser transport settings.", + "browser.enabled": + "Enables browser capability wiring in the gateway so browser tools and CDP-driven workflows can run. Disable when browser automation is not needed to reduce surface area and startup work.", + "browser.cdpUrl": + "Remote CDP websocket URL used to attach to an externally managed browser instance. Use this for centralized browser hosts and keep URL access restricted to trusted network paths.", + "browser.color": + "Default accent color used for browser profile/UI cues where colored identity hints are displayed. Use consistent colors to help operators identify active browser profile context quickly.", + "browser.executablePath": + "Explicit browser executable path when auto-discovery is insufficient for your host environment. Use absolute stable paths so launch behavior stays deterministic across restarts.", + "browser.headless": + "Forces browser launch in headless mode when the local launcher starts browser instances. Keep headless enabled for server environments and disable only when visible UI debugging is required.", + "browser.noSandbox": + "Disables Chromium sandbox isolation flags for environments where sandboxing fails at runtime. Keep this off whenever possible because process isolation protections are reduced.", + "browser.attachOnly": + "Restricts browser mode to attach-only behavior without starting local browser processes. Use this when all browser sessions are externally managed by a remote CDP provider.", + "browser.defaultProfile": + "Default browser profile name selected when callers do not explicitly choose a profile. Use a stable low-privilege profile as the default to reduce accidental cross-context state use.", + "browser.profiles": + "Named browser profile connection map used for explicit routing to CDP ports or URLs with optional metadata. Keep profile names consistent and avoid overlapping endpoint definitions.", + "browser.profiles.*.cdpPort": + "Per-profile local CDP port used when connecting to browser instances by port instead of URL. Use unique ports per profile to avoid connection collisions.", + "browser.profiles.*.cdpUrl": + "Per-profile CDP websocket URL used for explicit remote browser routing by profile name. Use this when profile connections terminate on remote hosts or tunnels.", + "browser.profiles.*.driver": + 'Per-profile browser driver mode: "clawd" or "extension" depending on connection/runtime strategy. Use the driver that matches your browser control stack to avoid protocol mismatches.', + "browser.profiles.*.color": + "Per-profile accent color for visual differentiation in dashboards and browser-related UI hints. Use distinct colors for high-signal operator recognition of active profiles.", + "browser.evaluateEnabled": + "Enables browser-side evaluate helpers for runtime script evaluation capabilities where supported. Keep disabled unless your workflows require evaluate semantics beyond snapshots/navigation.", + "browser.snapshotDefaults": + "Default snapshot capture configuration used when callers do not provide explicit snapshot options. Tune this for consistent capture behavior across channels and automation paths.", + "browser.snapshotDefaults.mode": + "Default snapshot extraction mode controlling how page content is transformed for agent consumption. Choose the mode that balances readability, fidelity, and token footprint for your workflows.", + "browser.ssrfPolicy": + "Server-side request forgery guardrail settings for browser/network fetch paths that could reach internal hosts. Keep restrictive defaults in production and open only explicitly approved targets.", + "browser.ssrfPolicy.allowPrivateNetwork": + "Allows access to private-network address ranges from browser/network tooling when SSRF protections are active. Keep disabled unless internal-network access is required and separately controlled.", + "browser.ssrfPolicy.allowedHostnames": + "Explicit hostname allowlist exceptions for SSRF policy checks on browser/network requests. Keep this list minimal and review entries regularly to avoid stale broad access.", + "browser.ssrfPolicy.hostnameAllowlist": + "Legacy/alternate hostname allowlist field used by SSRF policy consumers for explicit host exceptions. Use stable exact hostnames and avoid wildcard-like broad patterns.", + "browser.remoteCdpTimeoutMs": + "Timeout in milliseconds for connecting to a remote CDP endpoint before failing the browser attach attempt. Increase for high-latency tunnels, or lower for faster failure detection.", + "browser.remoteCdpHandshakeTimeoutMs": + "Timeout in milliseconds for post-connect CDP handshake readiness checks against remote browser targets. Raise this for slow-start remote browsers and lower to fail fast in automation loops.", "discovery.mdns.mode": 'mDNS broadcast mode ("minimal" default, "full" includes cliPath/sshPort, "off" disables mDNS).', + discovery: + "Service discovery settings for local mDNS advertisement and optional wide-area presence signaling. Keep discovery scoped to expected networks to avoid leaking service metadata.", + "discovery.wideArea": + "Wide-area discovery configuration group for exposing discovery signals beyond local-link scopes. Enable only in deployments that intentionally aggregate gateway presence across sites.", + "discovery.wideArea.enabled": + "Enables wide-area discovery signaling when your environment needs non-local gateway discovery. Keep disabled unless cross-network discovery is operationally required.", + "discovery.mdns": + "mDNS discovery configuration group for local network advertisement and discovery behavior tuning. Keep minimal mode for routine LAN discovery unless extra metadata is required.", + tools: + "Global tool access policy and capability configuration across web, exec, media, messaging, and elevated surfaces. Use this section to constrain risky capabilities before broad rollout.", + "tools.allow": + "Absolute tool allowlist that replaces profile-derived defaults for strict environments. Use this only when you intentionally run a tightly curated subset of tool capabilities.", + "tools.deny": + "Global tool denylist that blocks listed tools even when profile or provider rules would allow them. Use deny rules for emergency lockouts and long-term defense-in-depth.", + "tools.web": + "Web-tool policy grouping for search/fetch providers, limits, and fallback behavior tuning. Keep enabled settings aligned with API key availability and outbound networking policy.", + "tools.exec": + "Exec-tool policy grouping for shell execution host, security mode, approval behavior, and runtime bindings. Keep conservative defaults in production and tighten elevated execution paths.", + "tools.exec.host": + "Selects execution host strategy for shell commands, typically controlling local vs delegated execution environment. Use the safest host mode that still satisfies your automation requirements.", + "tools.exec.security": + "Execution security posture selector controlling sandbox/approval expectations for command execution. Keep strict security mode for untrusted prompts and relax only for trusted operator workflows.", + "tools.exec.ask": + "Approval strategy for when exec commands require human confirmation before running. Use stricter ask behavior in shared channels and lower-friction settings in private operator contexts.", + "tools.exec.node": + "Node binding configuration for exec tooling when command execution is delegated through connected nodes. Use explicit node binding only when multi-node routing is required.", + "tools.agentToAgent": + "Policy for allowing agent-to-agent tool calls and constraining which target agents can be reached. Keep disabled or tightly scoped unless cross-agent orchestration is intentionally enabled.", + "tools.agentToAgent.enabled": + "Enables the agent_to_agent tool surface so one agent can invoke another agent at runtime. Keep off in simple deployments and enable only when orchestration value outweighs complexity.", + "tools.agentToAgent.allow": + "Allowlist of target agent IDs permitted for agent_to_agent calls when orchestration is enabled. Use explicit allowlists to avoid uncontrolled cross-agent call graphs.", + "tools.elevated": + "Elevated tool access controls for privileged command surfaces that should only be reachable from trusted senders. Keep disabled unless operator workflows explicitly require elevated actions.", + "tools.elevated.enabled": + "Enables elevated tool execution path when sender and policy checks pass. Keep disabled in public/shared channels and enable only for trusted owner-operated contexts.", + "tools.elevated.allowFrom": + "Sender allow rules for elevated tools, usually keyed by channel/provider identity formats. Use narrow, explicit identities so elevated commands cannot be triggered by unintended users.", + "tools.subagents": + "Tool policy wrapper for spawned subagents to restrict or expand tool availability compared to parent defaults. Use this to keep delegated agent capabilities scoped to task intent.", + "tools.subagents.tools": + "Allow/deny tool policy applied to spawned subagent runtimes for per-subagent hardening. Keep this narrower than parent scope when subagents run semi-autonomous workflows.", + "tools.sandbox": + "Tool policy wrapper for sandboxed agent executions so sandbox runs can have distinct capability boundaries. Use this to enforce stronger safety in sandbox contexts.", + "tools.sandbox.tools": + "Allow/deny tool policy applied when agents run in sandboxed execution environments. Keep policies minimal so sandbox tasks cannot escalate into unnecessary external actions.", + web: "Web channel runtime settings for heartbeat and reconnect behavior when operating web-based chat surfaces. Use reconnect values tuned to your network reliability profile and expected uptime needs.", + "web.enabled": + "Enables the web channel runtime and related websocket lifecycle behavior. Keep disabled when web chat is unused to reduce active connection management overhead.", + "web.heartbeatSeconds": + "Heartbeat interval in seconds for web channel connectivity and liveness maintenance. Use shorter intervals for faster detection, or longer intervals to reduce keepalive chatter.", + "web.reconnect": + "Reconnect backoff policy for web channel reconnect attempts after transport failure. Keep bounded retries and jitter tuned to avoid thundering-herd reconnect behavior.", + "web.reconnect.initialMs": + "Initial reconnect delay in milliseconds before the first retry after disconnection. Use modest delays to recover quickly without immediate retry storms.", + "web.reconnect.maxMs": + "Maximum reconnect backoff cap in milliseconds to bound retry delay growth over repeated failures. Use a reasonable cap so recovery remains timely after prolonged outages.", + "web.reconnect.factor": + "Exponential backoff multiplier used between reconnect attempts in web channel retry loops. Keep factor above 1 and tune with jitter for stable large-fleet reconnect behavior.", + "web.reconnect.jitter": + "Randomization factor (0-1) applied to reconnect delays to desynchronize clients after outage events. Keep non-zero jitter in multi-client deployments to reduce synchronized spikes.", + "web.reconnect.maxAttempts": + "Maximum reconnect attempts before giving up for the current failure sequence (0 means no retries). Use finite caps for controlled failure handling in automation-sensitive environments.", + canvasHost: + "Canvas host settings for serving canvas assets and local live-reload behavior used by canvas-enabled workflows. Keep disabled unless canvas-hosted assets are actively used.", + "canvasHost.enabled": + "Enables the canvas host server process and routes for serving canvas files. Keep disabled when canvas workflows are inactive to reduce exposed local services.", + "canvasHost.root": + "Filesystem root directory served by canvas host for canvas content and static assets. Use a dedicated directory and avoid broad repo roots for least-privilege file exposure.", + "canvasHost.port": + "TCP port used by the canvas host HTTP server when canvas hosting is enabled. Choose a non-conflicting port and align firewall/proxy policy accordingly.", + "canvasHost.liveReload": + "Enables automatic live-reload behavior for canvas assets during development workflows. Keep disabled in production-like environments where deterministic output is preferred.", + talk: "Talk-mode voice synthesis settings for voice identity, model selection, output format, and interruption behavior. Use this section to tune human-facing voice UX while controlling latency and cost.", + "talk.voiceId": + "Primary voice identifier used by talk mode when synthesizing spoken responses. Use a stable voice for consistent persona and switch only when experience goals change.", + "talk.voiceAliases": + "Alias map for human-friendly voice shortcuts to concrete voice IDs in talk workflows. Use aliases to simplify operator switching without exposing long provider-native IDs.", + "talk.modelId": + "Model override used for talk pipeline generation when voice workflows require different model behavior. Use this when speech output needs a specialized low-latency or style-tuned model.", + "talk.outputFormat": + "Audio output format for synthesized talk responses, depending on provider support and client playback expectations. Use formats compatible with your playback channel to avoid decode failures.", + "talk.interruptOnSpeech": + "When true, interrupts current speech playback on new speech/input events for more conversational turn-taking. Keep enabled for interactive voice UX and disable for uninterrupted long-form playback.", + "talk.apiKey": + "Optional talk-provider API key override used specifically for speech synthesis requests. Use env-backed secrets and set this only when talk traffic must use separate credentials.", "gateway.auth.token": "Required by default for gateway access (unless using Tailscale Serve identity); required for non-loopback binds.", "gateway.auth.password": "Required for Tailscale funnel.", @@ -46,12 +296,13 @@ export const FIELD_HELP: Record = { "gateway.controlUi.allowedOrigins": "Allowed browser origins for Control UI/WebChat websocket connections (full origins only, e.g. https://control.example.com).", "gateway.controlUi.allowInsecureAuth": - "Insecure-auth toggle; Control UI still enforces secure context + device identity unless dangerouslyDisableDeviceAuth is enabled.", + "Loosens strict browser auth checks for Control UI when you must run a non-standard setup. Keep this off unless you trust your network and proxy path, because impersonation risk is higher.", "gateway.controlUi.dangerouslyDisableDeviceAuth": - "DANGEROUS. Disable Control UI device identity checks (token/password only).", + "Disables Control UI device identity checks and relies on token/password only. Use only for short-lived debugging on trusted networks, then turn it off immediately.", "gateway.http.endpoints.chatCompletions.enabled": "Enable the OpenAI-compatible `POST /v1/chat/completions` endpoint (default: false).", - "gateway.reload.mode": 'Hot reload strategy for config changes ("hybrid" recommended).', + "gateway.reload.mode": + 'Controls how config edits are applied: "off" ignores live edits, "restart" always restarts, "hot" applies in-process, and "hybrid" tries hot then restarts if required. Keep "hybrid" for safest routine updates.', "gateway.reload.debounceMs": "Debounce window (ms) before applying config changes.", "gateway.nodes.browser.mode": 'Node browser routing ("auto" = pick single connected browser node, "manual" = require node param, "off" = disable).', @@ -60,11 +311,78 @@ export const FIELD_HELP: Record = { "Extra node.invoke commands to allow beyond the gateway defaults (array of command strings). Enabling dangerous commands here is a security-sensitive override and is flagged by `openclaw security audit`.", "gateway.nodes.denyCommands": "Commands to block even if present in node claims or default allowlist.", - "nodeHost.browserProxy.enabled": "Expose the local browser control server via node proxy.", + nodeHost: + "Node host controls for features exposed from this gateway node to other nodes or clients. Keep defaults unless you intentionally proxy local capabilities across your node network.", + "nodeHost.browserProxy": + "Groups browser-proxy settings for exposing local browser control through node routing. Enable only when remote node workflows need your local browser profiles.", + "nodeHost.browserProxy.enabled": + "Expose the local browser control server through node proxy routing so remote clients can use this host's browser capabilities. Keep disabled unless remote automation explicitly depends on it.", "nodeHost.browserProxy.allowProfiles": - "Optional allowlist of browser profile names exposed via the node proxy.", + "Optional allowlist of browser profile names exposed through node proxy routing. Leave empty to expose all configured profiles, or use a tight list to enforce least-privilege profile access.", + media: + "Top-level media behavior shared across providers and tools that handle inbound files. Keep defaults unless you need stable filenames for external processing pipelines.", + "media.preserveFilenames": + "When enabled, uploaded media keeps its original filename instead of a generated temp-safe name. Turn this on when downstream automations depend on stable names, and leave off to reduce accidental filename leakage.", + audio: + "Global audio ingestion settings used before higher-level tools process speech or media content. Configure this when you need deterministic transcription behavior for voice notes and clips.", + "audio.transcription": + "Command-based transcription settings for converting audio files into text before agent handling. Keep a simple, deterministic command path here so failures are easy to diagnose in logs.", + "audio.transcription.command": + 'Executable + args used to transcribe audio (first token must be a safe binary/path), for example `["whisper-cli", "--model", "small", "{input}"]`. Prefer a pinned command so runtime environments behave consistently.', + "audio.transcription.timeoutSeconds": + "Maximum time allowed for the transcription command to finish before it is aborted. Increase this for longer recordings, and keep it tight in latency-sensitive deployments.", + bindings: + "Static routing bindings that pin inbound conversations to specific agent IDs by match rules. Use bindings for deterministic ownership when dynamic routing should not decide.", + "bindings[].agentId": + "Target agent ID that receives traffic when the corresponding binding match rule is satisfied. Use valid configured agent IDs only so routing does not fail at runtime.", + "bindings[].match": + "Match rule object for deciding when a binding applies, including channel and optional account/peer constraints. Keep rules narrow to avoid accidental agent takeover across contexts.", + "bindings[].match.channel": + "Channel/provider identifier this binding applies to, such as `telegram`, `discord`, or a plugin channel ID. Use the configured channel key exactly so binding evaluation works reliably.", + "bindings[].match.accountId": + "Optional account selector for multi-account channel setups so the binding applies only to one identity. Use this when account scoping is required for the route and leave unset otherwise.", + "bindings[].match.peer": + "Optional peer matcher for specific conversations including peer kind and peer id. Use this when only one direct/group/channel target should be pinned to an agent.", + "bindings[].match.peer.kind": + 'Peer conversation type: "direct", "group", "channel", or legacy "dm" (deprecated alias for direct). Prefer "direct" for new configs and keep kind aligned with channel semantics.', + "bindings[].match.peer.id": + "Conversation identifier used with peer matching, such as a chat ID, channel ID, or group ID from the provider. Keep this exact to avoid silent non-matches.", + "bindings[].match.guildId": + "Optional Discord-style guild/server ID constraint for binding evaluation in multi-server deployments. Use this when the same peer identifiers can appear across different guilds.", + "bindings[].match.teamId": + "Optional team/workspace ID constraint used by providers that scope chats under teams. Add this when you need bindings isolated to one workspace context.", + "bindings[].match.roles": + "Optional role-based filter list used by providers that attach roles to chat context. Use this to route privileged or operational role traffic to specialized agents.", + broadcast: + "Broadcast routing map for sending the same outbound message to multiple peer IDs per source conversation. Keep this minimal and audited because one source can fan out to many destinations.", + "broadcast.strategy": + 'Delivery order for broadcast fan-out: "parallel" sends to all targets concurrently, while "sequential" sends one-by-one. Use "parallel" for speed and "sequential" for stricter ordering/backpressure control.', + "broadcast.*": + "Per-source broadcast destination list where each key is a source peer ID and the value is an array of destination peer IDs. Keep lists intentional to avoid accidental message amplification.", "diagnostics.flags": 'Enable targeted diagnostics logs by flag (e.g. ["telegram.http"]). Supports wildcards like "telegram.*" or "*".', + "diagnostics.enabled": + "Master toggle for diagnostics instrumentation output in logs and telemetry wiring paths. Keep enabled for normal observability, and disable only in tightly constrained environments.", + "diagnostics.otel.enabled": + "Enables OpenTelemetry export pipeline for traces, metrics, and logs based on configured endpoint/protocol settings. Keep disabled unless your collector endpoint and auth are fully configured.", + "diagnostics.otel.endpoint": + "Collector endpoint URL used for OpenTelemetry export transport, including scheme and port. Use a reachable, trusted collector endpoint and monitor ingestion errors after rollout.", + "diagnostics.otel.protocol": + 'OTel transport protocol for telemetry export: "http/protobuf" or "grpc" depending on collector support. Use the protocol your observability backend expects to avoid dropped telemetry payloads.', + "diagnostics.otel.headers": + "Additional HTTP/gRPC metadata headers sent with OpenTelemetry export requests, often used for tenant auth or routing. Keep secrets in env-backed values and avoid unnecessary header sprawl.", + "diagnostics.otel.serviceName": + "Service name reported in telemetry resource attributes to identify this gateway instance in observability backends. Use stable names so dashboards and alerts remain consistent over deployments.", + "diagnostics.otel.traces": + "Enable trace signal export to the configured OpenTelemetry collector endpoint. Keep enabled when latency/debug tracing is needed, and disable if you only want metrics/logs.", + "diagnostics.otel.metrics": + "Enable metrics signal export to the configured OpenTelemetry collector endpoint. Keep enabled for runtime health dashboards, and disable only if metric volume must be minimized.", + "diagnostics.otel.logs": + "Enable log signal export through OpenTelemetry in addition to local logging sinks. Use this when centralized log correlation is required across services and agents.", + "diagnostics.otel.sampleRate": + "Trace sampling rate (0-1) controlling how much trace traffic is exported to observability backends. Lower rates reduce overhead/cost, while higher rates improve debugging fidelity.", + "diagnostics.otel.flushIntervalMs": + "Interval in milliseconds for periodic telemetry flush from buffers to the collector. Increase to reduce export chatter, or lower for faster visibility during active incident response.", "diagnostics.cacheTrace.enabled": "Log cache trace snapshots for embedded agent runs (default: false).", "diagnostics.cacheTrace.filePath": @@ -102,6 +420,110 @@ export const FIELD_HELP: Record = { "Allow stdin-only safe binaries to run without explicit allowlist entries.", "tools.exec.safeBinProfiles": "Optional per-binary safe-bin profiles (positional limits + allowed/denied flags).", + "tools.profile": + "Global tool profile name used to select a predefined tool policy baseline before applying allow/deny overrides. Use this for consistent environment posture across agents and keep profile names stable.", + "tools.alsoAllow": + "Extra tool allowlist entries merged on top of the selected tool profile and default policy. Keep this list small and explicit so audits can quickly identify intentional policy exceptions.", + "tools.byProvider": + "Per-provider tool allow/deny overrides keyed by channel/provider ID to tailor capabilities by surface. Use this when one provider needs stricter controls than global tool policy.", + "agents.list[].tools.profile": + "Per-agent override for tool profile selection when one agent needs a different capability baseline. Use this sparingly so policy differences across agents stay intentional and reviewable.", + "agents.list[].tools.alsoAllow": + "Per-agent additive allowlist for tools on top of global and profile policy. Keep narrow to avoid accidental privilege expansion on specialized agents.", + "agents.list[].tools.byProvider": + "Per-agent provider-specific tool policy overrides for channel-scoped capability control. Use this when a single agent needs tighter restrictions on one provider than others.", + "tools.exec.approvalRunningNoticeMs": + "Delay in milliseconds before showing an in-progress notice after an exec approval is granted. Increase to reduce flicker for fast commands, or lower for quicker operator feedback.", + "tools.links.enabled": + "Enable automatic link understanding pre-processing so URLs can be summarized before agent reasoning. Keep enabled for richer context, and disable when strict minimal processing is required.", + "tools.links.maxLinks": + "Maximum number of links expanded per turn during link understanding. Use lower values to control latency/cost in chatty threads and higher values when multi-link context is critical.", + "tools.links.timeoutSeconds": + "Per-link understanding timeout budget in seconds before unresolved links are skipped. Keep this bounded to avoid long stalls when external sites are slow or unreachable.", + "tools.links.models": + "Preferred model list for link understanding tasks, evaluated in order as fallbacks when supported. Use lightweight models first for routine summarization and heavier models only when needed.", + "tools.links.scope": + "Controls when link understanding runs relative to conversation context and message type. Keep scope conservative to avoid unnecessary fetches on messages where links are not actionable.", + "tools.media.models": + "Shared fallback model list used by media understanding tools when modality-specific model lists are not set. Keep this aligned with available multimodal providers to avoid runtime fallback churn.", + "tools.media.concurrency": + "Maximum number of concurrent media understanding operations per turn across image, audio, and video tasks. Lower this in resource-constrained deployments to prevent CPU/network saturation.", + "tools.media.image.enabled": + "Enable image understanding so attached or referenced images can be interpreted into textual context. Disable if you need text-only operation or want to avoid image-processing cost.", + "tools.media.image.maxBytes": + "Maximum accepted image payload size in bytes before the item is skipped or truncated by policy. Keep limits realistic for your provider caps and infrastructure bandwidth.", + "tools.media.image.maxChars": + "Maximum characters returned from image understanding output after model response normalization. Use tighter limits to reduce prompt bloat and larger limits for detail-heavy OCR tasks.", + "tools.media.image.prompt": + "Instruction template used for image understanding requests to shape extraction style and detail level. Keep prompts deterministic so outputs stay consistent across turns and channels.", + "tools.media.image.timeoutSeconds": + "Timeout in seconds for each image understanding request before it is aborted. Increase for high-resolution analysis and lower it for latency-sensitive operator workflows.", + "tools.media.image.attachments": + "Attachment handling policy for image inputs, including which message attachments qualify for image analysis. Use restrictive settings in untrusted channels to reduce unexpected processing.", + "tools.media.image.models": + "Ordered model preferences specifically for image understanding when you want to override shared media models. Put the most reliable multimodal model first to reduce fallback attempts.", + "tools.media.image.scope": + "Scope selector for when image understanding is attempted (for example only explicit requests versus broader auto-detection). Keep narrow scope in busy channels to control token and API spend.", + "tools.media.audio.enabled": + "Enable audio understanding so voice notes or audio clips can be transcribed/summarized for agent context. Disable when audio ingestion is outside policy or unnecessary for your workflows.", + "tools.media.audio.maxBytes": + "Maximum accepted audio payload size in bytes before processing is rejected or clipped by policy. Set this based on expected recording length and upstream provider limits.", + "tools.media.audio.maxChars": + "Maximum characters retained from audio understanding output to prevent oversized transcript injection. Increase for long-form dictation, or lower to keep conversational turns compact.", + "tools.media.audio.prompt": + "Instruction template guiding audio understanding output style, such as concise summary versus near-verbatim transcript. Keep wording consistent so downstream automations can rely on output format.", + "tools.media.audio.timeoutSeconds": + "Timeout in seconds for audio understanding execution before the operation is cancelled. Use longer timeouts for long recordings and tighter ones for interactive chat responsiveness.", + "tools.media.audio.language": + "Preferred language hint for audio understanding/transcription when provider support is available. Set this to improve recognition accuracy for known primary languages.", + "tools.media.audio.attachments": + "Attachment policy for audio inputs indicating which uploaded files are eligible for audio processing. Keep restrictive defaults in mixed-content channels to avoid unintended audio workloads.", + "tools.media.audio.models": + "Ordered model preferences specifically for audio understanding, used before shared media model fallback. Choose models optimized for transcription quality in your primary language/domain.", + "tools.media.audio.scope": + "Scope selector for when audio understanding runs across inbound messages and attachments. Keep focused scopes in high-volume channels to reduce cost and avoid accidental transcription.", + "tools.media.video.enabled": + "Enable video understanding so clips can be summarized into text for downstream reasoning and responses. Disable when processing video is out of policy or too expensive for your deployment.", + "tools.media.video.maxBytes": + "Maximum accepted video payload size in bytes before policy rejection or trimming occurs. Tune this to provider and infrastructure limits to avoid repeated timeout/failure loops.", + "tools.media.video.maxChars": + "Maximum characters retained from video understanding output to control prompt growth. Raise for dense scene descriptions and lower when concise summaries are preferred.", + "tools.media.video.prompt": + "Instruction template for video understanding describing desired summary granularity and focus areas. Keep this stable so output quality remains predictable across model/provider fallbacks.", + "tools.media.video.timeoutSeconds": + "Timeout in seconds for each video understanding request before cancellation. Use conservative values in interactive channels and longer values for offline or batch-heavy processing.", + "tools.media.video.attachments": + "Attachment eligibility policy for video analysis, defining which message files can trigger video processing. Keep this explicit in shared channels to prevent accidental large media workloads.", + "tools.media.video.models": + "Ordered model preferences specifically for video understanding before shared media fallback applies. Prioritize models with strong multimodal video support to minimize degraded summaries.", + "tools.media.video.scope": + "Scope selector controlling when video understanding is attempted across incoming events. Narrow scope in noisy channels, and broaden only where video interpretation is core to workflow.", + "skills.load.watch": + "Enable filesystem watching for skill-definition changes so updates can be applied without full process restart. Keep enabled in development workflows and disable in immutable production images.", + "skills.load.watchDebounceMs": + "Debounce window in milliseconds for coalescing rapid skill file changes before reload logic runs. Increase to reduce reload churn on frequent writes, or lower for faster edit feedback.", + approvals: + "Approval routing controls for forwarding exec approval requests to chat destinations outside the originating session. Keep this disabled unless operators need explicit out-of-band approval visibility.", + "approvals.exec": + "Groups exec-approval forwarding behavior including enablement, routing mode, filters, and explicit targets. Configure here when approval prompts must reach operational channels instead of only the origin thread.", + "approvals.exec.enabled": + "Enables forwarding of exec approval requests to configured delivery destinations (default: false). Keep disabled in low-risk setups and enable only when human approval responders need channel-visible prompts.", + "approvals.exec.mode": + 'Controls where approval prompts are sent: "session" uses origin chat, "targets" uses configured targets, and "both" sends to both paths. Use "session" as baseline and expand only when operational workflow requires redundancy.', + "approvals.exec.agentFilter": + 'Optional allowlist of agent IDs eligible for forwarded approvals, for example `["primary", "ops-agent"]`. Use this to limit forwarding blast radius and avoid notifying channels for unrelated agents.', + "approvals.exec.sessionFilter": + 'Optional session-key filters matched as substring or regex-style patterns, for example `["discord:", "^agent:ops:"]`. Use narrow patterns so only intended approval contexts are forwarded to shared destinations.', + "approvals.exec.targets": + "Explicit delivery targets used when forwarding mode includes targets, each with channel and destination details. Keep target lists least-privilege and validate each destination before enabling broad forwarding.", + "approvals.exec.targets[].channel": + "Channel/provider ID used for forwarded approval delivery, such as discord, slack, or a plugin channel id. Use valid channel IDs only so approvals do not silently fail due to unknown routes.", + "approvals.exec.targets[].to": + "Destination identifier inside the target channel (channel ID, user ID, or thread root depending on provider). Verify semantics per provider because destination format differs across channel integrations.", + "approvals.exec.targets[].accountId": + "Optional account selector for multi-account channel setups when approvals must route through a specific account context. Use this only when the target channel has multiple configured identities.", + "approvals.exec.targets[].threadId": + "Optional thread/topic target for channels that support threaded delivery of forwarded approvals. Use this to keep approval traffic contained in operational threads instead of main channels.", "tools.fs.workspaceOnly": "Restrict filesystem tools (read/write/edit/apply_patch) to the workspace directory (default: false).", "tools.sessions.visibility": @@ -150,6 +572,41 @@ export const FIELD_HELP: Record = { "tools.web.fetch.firecrawl.maxAgeMs": "Firecrawl maxAge (ms) for cached results when supported by the API.", "tools.web.fetch.firecrawl.timeoutSeconds": "Timeout in seconds for Firecrawl requests.", + models: + "Model catalog root for provider definitions, merge/replace behavior, and optional Bedrock discovery integration. Keep provider definitions explicit and validated before relying on production failover paths.", + "models.mode": + 'Controls provider catalog behavior: "merge" keeps built-ins and overlays your custom providers, while "replace" uses only your configured providers. Keep "merge" unless you intentionally want a strict custom list.', + "models.providers": + "Provider map keyed by provider ID containing connection/auth settings and concrete model definitions. Use stable provider keys so references from agents and tooling remain portable across environments.", + "models.providers.*.baseUrl": + "Base URL for the provider endpoint used to serve model requests for that provider entry. Use HTTPS endpoints and keep URLs environment-specific through config templating where needed.", + "models.providers.*.apiKey": + "Provider credential used for API-key based authentication when the provider requires direct key auth. Use secret/env substitution and avoid storing real keys in committed config files.", + "models.providers.*.auth": + 'Selects provider auth style: "api-key" for API key auth, "token" for bearer token auth, "oauth" for OAuth credentials, and "aws-sdk" for AWS credential resolution. Match this to your provider requirements.', + "models.providers.*.api": + "Provider API adapter selection controlling request/response compatibility handling for model calls. Use the adapter that matches your upstream provider protocol to avoid feature mismatch.", + "models.providers.*.headers": + "Static HTTP headers merged into provider requests for tenant routing, proxy auth, or custom gateway requirements. Use this sparingly and keep sensitive header values in secrets.", + "models.providers.*.authHeader": + "When true, credentials are sent via the HTTP Authorization header even if alternate auth is possible. Use this only when your provider or proxy explicitly requires Authorization forwarding.", + "models.providers.*.models": + "Declared model list for a provider including identifiers, metadata, and optional compatibility/cost hints. Keep IDs exact to provider catalog values so selection and fallback resolve correctly.", + "models.bedrockDiscovery": + "Automatic AWS Bedrock model discovery settings used to synthesize provider model entries from account visibility. Keep discovery scoped and refresh intervals conservative to reduce API churn.", + "models.bedrockDiscovery.enabled": + "Enables periodic Bedrock model discovery and catalog refresh for Bedrock-backed providers. Keep disabled unless Bedrock is actively used and IAM permissions are correctly configured.", + "models.bedrockDiscovery.region": + "AWS region used for Bedrock discovery calls when discovery is enabled for your deployment. Use the region where your Bedrock models are provisioned to avoid empty discovery results.", + "models.bedrockDiscovery.providerFilter": + "Optional provider allowlist filter for Bedrock discovery so only selected providers are refreshed. Use this to limit discovery scope in multi-provider environments.", + "models.bedrockDiscovery.refreshInterval": + "Refresh cadence for Bedrock discovery polling in seconds to detect newly available models over time. Use longer intervals in production to reduce API cost and control-plane noise.", + "models.bedrockDiscovery.defaultContextWindow": + "Fallback context-window value applied to discovered models when provider metadata lacks explicit limits. Use realistic defaults to avoid oversized prompts that exceed true provider constraints.", + "models.bedrockDiscovery.defaultMaxTokens": + "Fallback max-token value applied to discovered models without explicit output token limits. Use conservative defaults to reduce truncation surprises and unexpected token spend.", + auth: "Authentication profile root used for multi-profile provider credentials and cooldown-based failover ordering. Keep profiles minimal and explicit so automatic failover behavior stays auditable.", "channels.slack.allowBots": "Allow bot-authored messages to trigger Slack replies (default: false).", "channels.slack.thread.historyScope": @@ -169,12 +626,16 @@ export const FIELD_HELP: Record = { "Require @mention in channels before responding (default: true).", "auth.profiles": "Named auth profiles (provider + mode + optional email).", "auth.order": "Ordered auth profile IDs per provider (used for automatic failover).", + "auth.cooldowns": + "Cooldown/backoff controls for temporary profile suppression after billing-related failures and retry windows. Use these to prevent rapid re-selection of profiles that are still blocked.", "auth.cooldowns.billingBackoffHours": "Base backoff (hours) when a profile fails due to billing/insufficient credits (default: 5).", "auth.cooldowns.billingBackoffHoursByProvider": "Optional per-provider overrides for billing backoff (hours).", "auth.cooldowns.billingMaxHours": "Cap (hours) for billing backoff (default: 24).", "auth.cooldowns.failureWindowHours": "Failure window (hours) for backoff counters (default: 24).", + "agents.defaults.workspace": + "Default workspace path exposed to agent runtime tools for filesystem context and repo-aware behavior. Set this explicitly when running from wrappers so path resolution stays deterministic.", "agents.defaults.bootstrapMaxChars": "Max characters of each workspace bootstrap file injected into the system prompt before truncation (default: 20000).", "agents.defaults.bootstrapTotalMaxChars": @@ -189,120 +650,178 @@ export const FIELD_HELP: Record = { "agents.defaults.models": "Configured model catalog (keys are full provider/model IDs).", "agents.defaults.memorySearch": "Vector search over MEMORY.md and memory/*.md (per-agent overrides supported).", + "agents.defaults.memorySearch.enabled": + "Master toggle for memory search indexing and retrieval behavior on this agent profile. Keep enabled for semantic recall, and disable when you want fully stateless responses.", "agents.defaults.memorySearch.sources": - 'Sources to index for memory search (default: ["memory"]; add "sessions" to include session transcripts).', + 'Chooses which sources are indexed: "memory" reads MEMORY.md + memory files, and "sessions" includes transcript history. Keep ["memory"] unless you need recall from prior chat transcripts.', "agents.defaults.memorySearch.extraPaths": - "Extra paths to include in memory search (directories or .md files; relative paths resolved from workspace).", + "Adds extra directories or .md files to the memory index beyond default memory files. Use this when key reference docs live elsewhere in your repo; keep paths small and intentional to avoid noisy recall.", "agents.defaults.memorySearch.experimental.sessionMemory": - "Enable experimental session transcript indexing for memory search (default: false).", + "Indexes session transcripts into memory search so responses can reference prior chat turns. Keep this off unless transcript recall is needed, because indexing cost and storage usage both increase.", "agents.defaults.memorySearch.provider": - 'Embedding provider ("openai", "gemini", "voyage", or "local").', + 'Selects the embedding backend used to build/query memory vectors: "openai", "gemini", "voyage", or "local". Keep your most reliable provider here and configure fallback for resilience.', + "agents.defaults.memorySearch.model": + "Embedding model override used by the selected memory provider when a non-default model is required. Set this only when you need explicit recall quality/cost tuning beyond provider defaults.", "agents.defaults.memorySearch.remote.baseUrl": - "Custom base URL for remote embeddings (OpenAI-compatible proxies or Gemini overrides).", - "agents.defaults.memorySearch.remote.apiKey": "Custom API key for the remote embedding provider.", + "Overrides the embedding API endpoint, such as an OpenAI-compatible proxy or custom Gemini base URL. Use this only when routing through your own gateway or vendor endpoint; keep provider defaults otherwise.", + "agents.defaults.memorySearch.remote.apiKey": + "Supplies a dedicated API key for remote embedding calls used by memory indexing and query-time embeddings. Use this when memory embeddings should use different credentials than global defaults or environment variables.", "agents.defaults.memorySearch.remote.headers": - "Extra headers for remote embeddings (merged; remote overrides OpenAI headers).", + "Adds custom HTTP headers to remote embedding requests, merged with provider defaults. Use this for proxy auth and tenant routing headers, and keep values minimal to avoid leaking sensitive metadata.", "agents.defaults.memorySearch.remote.batch.enabled": - "Enable batch API for memory embeddings (OpenAI/Gemini; default: true).", + "Enables provider batch APIs for embedding jobs when supported (OpenAI/Gemini), improving throughput on larger index runs. Keep this enabled unless debugging provider batch failures or running very small workloads.", "agents.defaults.memorySearch.remote.batch.wait": - "Wait for batch completion when indexing (default: true).", + "Waits for batch embedding jobs to fully finish before the indexing operation completes. Keep this enabled for deterministic indexing state; disable only if you accept delayed consistency.", "agents.defaults.memorySearch.remote.batch.concurrency": - "Max concurrent embedding batch jobs for memory indexing (default: 2).", + "Limits how many embedding batch jobs run at the same time during indexing (default: 2). Increase carefully for faster bulk indexing, but watch provider rate limits and queue errors.", "agents.defaults.memorySearch.remote.batch.pollIntervalMs": - "Polling interval in ms for batch status (default: 2000).", + "Controls how often the system polls provider APIs for batch job status in milliseconds (default: 2000). Use longer intervals to reduce API chatter, or shorter intervals for faster completion detection.", "agents.defaults.memorySearch.remote.batch.timeoutMinutes": - "Timeout in minutes for batch indexing (default: 60).", + "Sets the maximum wait time for a full embedding batch operation in minutes (default: 60). Increase for very large corpora or slower providers, and lower it to fail fast in automation-heavy flows.", "agents.defaults.memorySearch.local.modelPath": - "Local GGUF model path or hf: URI (node-llama-cpp).", + "Specifies the local embedding model source for local memory search, such as a GGUF file path or `hf:` URI. Use this only when provider is `local`, and verify model compatibility before large index rebuilds.", "agents.defaults.memorySearch.fallback": - 'Fallback provider when embeddings fail ("openai", "gemini", "local", or "none").', + 'Backup provider used when primary embeddings fail: "openai", "gemini", "local", or "none". Set a real fallback for production reliability; use "none" only if you prefer explicit failures.', "agents.defaults.memorySearch.store.path": - "SQLite index path (default: ~/.openclaw/memory/{agentId}.sqlite).", + "Sets where the SQLite memory index is stored on disk for each agent. Keep the default `~/.openclaw/memory/{agentId}.sqlite` unless you need custom storage placement or backup policy alignment.", "agents.defaults.memorySearch.store.vector.enabled": - "Enable sqlite-vec extension for vector search (default: true).", + "Enables the sqlite-vec extension used for vector similarity queries in memory search (default: true). Keep this enabled for normal semantic recall; disable only for debugging or fallback-only operation.", "agents.defaults.memorySearch.store.vector.extensionPath": - "Optional override path to sqlite-vec extension library (.dylib/.so/.dll).", + "Overrides the auto-discovered sqlite-vec extension library path (`.dylib`, `.so`, or `.dll`). Use this when your runtime cannot find sqlite-vec automatically or you pin a known-good build.", + "agents.defaults.memorySearch.chunking.tokens": + "Chunk size in tokens used when splitting memory sources before embedding/indexing. Increase for broader context per chunk, or lower to improve precision on pinpoint lookups.", + "agents.defaults.memorySearch.chunking.overlap": + "Token overlap between adjacent memory chunks to preserve context continuity near split boundaries. Use modest overlap to reduce boundary misses without inflating index size too aggressively.", + "agents.defaults.memorySearch.query.maxResults": + "Maximum number of memory hits returned from search before downstream reranking and prompt injection. Raise for broader recall, or lower for tighter prompts and faster responses.", + "agents.defaults.memorySearch.query.minScore": + "Minimum relevance score threshold for including memory results in final recall output. Increase to reduce weak/noisy matches, or lower when you need more permissive retrieval.", "agents.defaults.memorySearch.query.hybrid.enabled": - "Enable hybrid BM25 + vector search for memory (default: true).", + "Combines BM25 keyword matching with vector similarity for better recall on mixed exact + semantic queries. Keep enabled unless you are isolating ranking behavior for troubleshooting.", "agents.defaults.memorySearch.query.hybrid.vectorWeight": - "Weight for vector similarity when merging results (0-1).", + "Controls how strongly semantic similarity influences hybrid ranking (0-1). Increase when paraphrase matching matters more than exact terms; decrease for stricter keyword emphasis.", "agents.defaults.memorySearch.query.hybrid.textWeight": - "Weight for BM25 text relevance when merging results (0-1).", + "Controls how strongly BM25 keyword relevance influences hybrid ranking (0-1). Increase for exact-term matching; decrease when semantic matches should rank higher.", "agents.defaults.memorySearch.query.hybrid.candidateMultiplier": - "Multiplier for candidate pool size (default: 4).", + "Expands the candidate pool before reranking (default: 4). Raise this for better recall on noisy corpora, but expect more compute and slightly slower searches.", "agents.defaults.memorySearch.query.hybrid.mmr.enabled": - "Enable MMR re-ranking to reduce near-duplicate memory hits (default: false).", + "Adds MMR reranking to diversify results and reduce near-duplicate snippets in a single answer window. Enable when recall looks repetitive; keep off for strict score ordering.", "agents.defaults.memorySearch.query.hybrid.mmr.lambda": - "MMR relevance/diversity balance (0 = max diversity, 1 = max relevance, default: 0.7).", + "Sets MMR relevance-vs-diversity balance (0 = most diverse, 1 = most relevant, default: 0.7). Lower values reduce repetition; higher values keep tightly relevant but may duplicate.", "agents.defaults.memorySearch.query.hybrid.temporalDecay.enabled": - "Enable exponential recency decay for hybrid scoring (default: false).", + "Applies recency decay so newer memory can outrank older memory when scores are close. Enable when timeliness matters; keep off for timeless reference knowledge.", "agents.defaults.memorySearch.query.hybrid.temporalDecay.halfLifeDays": - "Half-life in days for temporal decay (default: 30).", + "Controls how fast older memory loses rank when temporal decay is enabled (half-life in days, default: 30). Lower values prioritize recent context more aggressively.", "agents.defaults.memorySearch.cache.enabled": - "Cache chunk embeddings in SQLite to speed up reindexing and frequent updates (default: true).", + "Caches computed chunk embeddings in SQLite so reindexing and incremental updates run faster (default: true). Keep this enabled unless investigating cache correctness or minimizing disk usage.", memory: "Memory backend configuration (global).", - "memory.backend": 'Memory backend ("builtin" for OpenClaw embeddings, "qmd" for QMD sidecar).', - "memory.citations": 'Default citation behavior ("auto", "on", or "off").', - "memory.qmd.command": "Path to the qmd binary (default: resolves from PATH).", + "memory.backend": + 'Selects the global memory engine: "builtin" uses OpenClaw memory internals, while "qmd" uses the QMD sidecar pipeline. Keep "builtin" unless you intentionally operate QMD.', + "memory.citations": + 'Controls citation visibility in replies: "auto" shows citations when useful, "on" always shows them, and "off" hides them. Keep "auto" for a balanced signal-to-noise default.', + "memory.qmd.command": + "Sets the executable path for the `qmd` binary used by the QMD backend (default: resolved from PATH). Use an explicit absolute path when multiple qmd installs exist or PATH differs across environments.", "memory.qmd.mcporter": - "Optional: route QMD searches through mcporter (MCP runtime) instead of spawning `qmd` per query. Intended to avoid per-search cold starts when QMD models are large.", - "memory.qmd.mcporter.enabled": "Enable mcporter-backed QMD searches (default: false).", + "Routes QMD work through mcporter (MCP runtime) instead of spawning `qmd` for each call. Use this when cold starts are expensive on large models; keep direct process mode for simpler local setups.", + "memory.qmd.mcporter.enabled": + "Routes QMD through an mcporter daemon instead of spawning qmd per request, reducing cold-start overhead for larger models. Keep disabled unless mcporter is installed and configured.", "memory.qmd.mcporter.serverName": - "mcporter server name to call (default: qmd). Server should run `qmd mcp` with lifecycle keep-alive.", + "Names the mcporter server target used for QMD calls (default: qmd). Change only when your mcporter setup uses a custom server name for qmd mcp keep-alive.", "memory.qmd.mcporter.startDaemon": - "Start `mcporter daemon start` automatically when enabled (default: true).", + "Automatically starts the mcporter daemon when mcporter-backed QMD mode is enabled (default: true). Keep enabled unless process lifecycle is managed externally by your service supervisor.", + "memory.qmd.searchMode": + 'Selects the QMD retrieval path: "query" uses standard query flow, "search" uses search-oriented retrieval, and "vsearch" emphasizes vector retrieval. Keep default unless tuning relevance quality.', "memory.qmd.includeDefaultMemory": - "Whether to automatically index MEMORY.md + memory/**/*.md (default: true).", + "Automatically indexes default memory files (MEMORY.md and memory/**/*.md) into QMD collections. Keep enabled unless you want indexing controlled only through explicit custom paths.", "memory.qmd.paths": - "Additional directories/files to index with QMD (path + optional glob pattern).", - "memory.qmd.paths.path": "Absolute or ~-relative path to index via QMD.", - "memory.qmd.paths.pattern": "Glob pattern relative to the path root (default: **/*.md).", + "Adds custom directories or files to include in QMD indexing, each with an optional name and glob pattern. Use this for project-specific knowledge locations that are outside default memory paths.", + "memory.qmd.paths.path": + "Defines the root location QMD should scan, using an absolute path or `~`-relative path. Use stable directories so collection identity does not drift across environments.", + "memory.qmd.paths.pattern": + "Filters files under each indexed root using a glob pattern, with default `**/*.md`. Use narrower patterns to reduce noise and indexing cost when directories contain mixed file types.", "memory.qmd.paths.name": - "Optional stable name for the QMD collection (default derived from path).", + "Sets a stable collection name for an indexed path instead of deriving it from filesystem location. Use this when paths vary across machines but you want consistent collection identity.", "memory.qmd.sessions.enabled": - "Enable QMD session transcript indexing (experimental, default: false).", + "Indexes session transcripts into QMD so recall can include prior conversation content (experimental, default: false). Enable only when transcript memory is required and you accept larger index churn.", "memory.qmd.sessions.exportDir": - "Override directory for sanitized session exports before indexing.", + "Overrides where sanitized session exports are written before QMD indexing. Use this when default state storage is constrained or when exports must land on a managed volume.", "memory.qmd.sessions.retentionDays": - "Retention window for exported sessions before pruning (default: unlimited).", + "Defines how long exported session files are kept before automatic pruning, in days (default: unlimited). Set a finite value for storage hygiene or compliance retention policies.", "memory.qmd.update.interval": - "How often the QMD sidecar refreshes indexes (duration string, default: 5m).", + "Sets how often QMD refreshes indexes from source content (duration string, default: 5m). Shorter intervals improve freshness but increase background CPU and I/O.", "memory.qmd.update.debounceMs": - "Minimum delay between successive QMD refresh runs (default: 15000).", - "memory.qmd.update.onBoot": "Run QMD update once on gateway startup (default: true).", + "Sets the minimum delay between consecutive QMD refresh attempts in milliseconds (default: 15000). Increase this if frequent file changes cause update thrash or unnecessary background load.", + "memory.qmd.update.onBoot": + "Runs an initial QMD update once during gateway startup (default: true). Keep enabled so recall starts from a fresh baseline; disable only when startup speed is more important than immediate freshness.", "memory.qmd.update.waitForBootSync": - "Block startup until the boot QMD refresh finishes (default: false).", + "Blocks startup completion until the initial boot-time QMD sync finishes (default: false). Enable when you need fully up-to-date recall before serving traffic, and keep off for faster boot.", "memory.qmd.update.embedInterval": - "How often QMD embeddings are refreshed (duration string, default: 60m). Set to 0 to disable periodic embed.", + "Sets how often QMD recomputes embeddings (duration string, default: 60m; set 0 to disable periodic embeds). Lower intervals improve freshness but increase embedding workload and cost.", "memory.qmd.update.commandTimeoutMs": - "Timeout for QMD maintenance commands like collection list/add (default: 30000).", - "memory.qmd.update.updateTimeoutMs": "Timeout for `qmd update` runs (default: 120000).", - "memory.qmd.update.embedTimeoutMs": "Timeout for `qmd embed` runs (default: 120000).", - "memory.qmd.limits.maxResults": "Max QMD results returned to the agent loop (default: 6).", - "memory.qmd.limits.maxSnippetChars": "Max characters per snippet pulled from QMD (default: 700).", - "memory.qmd.limits.maxInjectedChars": "Max total characters injected from QMD hits per turn.", - "memory.qmd.limits.timeoutMs": "Per-query timeout for QMD searches (default: 4000).", + "Sets timeout for QMD maintenance commands such as collection list/add in milliseconds (default: 30000). Increase when running on slower disks or remote filesystems that delay command completion.", + "memory.qmd.update.updateTimeoutMs": + "Sets maximum runtime for each `qmd update` cycle in milliseconds (default: 120000). Raise this for larger collections; lower it when you want quicker failure detection in automation.", + "memory.qmd.update.embedTimeoutMs": + "Sets maximum runtime for each `qmd embed` cycle in milliseconds (default: 120000). Increase for heavier embedding workloads or slower hardware, and lower to fail fast under tight SLAs.", + "memory.qmd.limits.maxResults": + "Limits how many QMD hits are returned into the agent loop for each recall request (default: 6). Increase for broader recall context, or lower to keep prompts tighter and faster.", + "memory.qmd.limits.maxSnippetChars": + "Caps per-result snippet length extracted from QMD hits in characters (default: 700). Lower this when prompts bloat quickly, and raise only if answers consistently miss key details.", + "memory.qmd.limits.maxInjectedChars": + "Caps how much QMD text can be injected into one turn across all hits. Use lower values to control prompt bloat and latency; raise only when context is consistently truncated.", + "memory.qmd.limits.timeoutMs": + "Sets per-query QMD search timeout in milliseconds (default: 4000). Increase for larger indexes or slower environments, and lower to keep request latency bounded.", "memory.qmd.scope": - "Session/channel scope for QMD recall (same syntax as session.sendPolicy; default: direct-only). Use match.rawKeyPrefix to match full agent-prefixed session keys.", + "Defines which sessions/channels are eligible for QMD recall using session.sendPolicy-style rules. Keep default direct-only scope unless you intentionally want cross-chat memory sharing.", "agents.defaults.memorySearch.cache.maxEntries": - "Optional cap on cached embeddings (best-effort).", + "Sets a best-effort upper bound on cached embeddings kept in SQLite for memory search. Use this when controlling disk growth matters more than peak reindex speed.", + "agents.defaults.memorySearch.sync.onSessionStart": + "Triggers a memory index sync when a session starts so early turns see fresh memory content. Keep enabled when startup freshness matters more than initial turn latency.", "agents.defaults.memorySearch.sync.onSearch": - "Lazy sync: schedule a reindex on search after changes.", - "agents.defaults.memorySearch.sync.watch": "Watch memory files for changes (chokidar).", + "Uses lazy sync by scheduling reindex on search after content changes are detected. Keep enabled for lower idle overhead, or disable if you require pre-synced indexes before any query.", + "agents.defaults.memorySearch.sync.watch": + "Watches memory files and schedules index updates from file-change events (chokidar). Enable for near-real-time freshness; disable on very large workspaces if watch churn is too noisy.", + "agents.defaults.memorySearch.sync.watchDebounceMs": + "Debounce window in milliseconds for coalescing rapid file-watch events before reindex runs. Increase to reduce churn on frequently-written files, or lower for faster freshness.", "agents.defaults.memorySearch.sync.sessions.deltaBytes": - "Minimum appended bytes before session transcripts trigger reindex (default: 100000).", + "Requires at least this many newly appended bytes before session transcript changes trigger reindex (default: 100000). Increase to reduce frequent small reindexes, or lower for faster transcript freshness.", "agents.defaults.memorySearch.sync.sessions.deltaMessages": - "Minimum appended JSONL lines before session transcripts trigger reindex (default: 50).", - "plugins.enabled": "Enable plugin/extension loading (default: true).", - "plugins.allow": "Optional allowlist of plugin ids; when set, only listed plugins load.", - "plugins.deny": "Optional denylist of plugin ids; deny wins over allowlist.", - "plugins.load.paths": "Additional plugin files or directories to load.", - "plugins.slots": "Select which plugins own exclusive slots (memory, etc.).", + "Requires at least this many appended transcript messages before reindex is triggered (default: 50). Lower this for near-real-time transcript recall, or raise it to reduce indexing churn.", + ui: "UI presentation settings for accenting and assistant identity shown in control surfaces. Use this for branding and readability customization without changing runtime behavior.", + "ui.seamColor": + "Primary accent/seam color used by UI surfaces for emphasis, badges, and visual identity cues. Use high-contrast values that remain readable across light/dark themes.", + "ui.assistant": + "Assistant display identity settings for name and avatar shown in UI surfaces. Keep these values aligned with your operator-facing persona and support expectations.", + "ui.assistant.name": + "Display name shown for the assistant in UI views, chat chrome, and status contexts. Keep this stable so operators can reliably identify which assistant persona is active.", + "ui.assistant.avatar": + "Assistant avatar image source used in UI surfaces (URL, path, or data URI depending on runtime support). Use trusted assets and consistent branding dimensions for clean rendering.", + plugins: + "Plugin system controls for enabling extensions, constraining load scope, configuring entries, and tracking installs. Keep plugin policy explicit and least-privilege in production environments.", + "plugins.enabled": + "Enable or disable plugin/extension loading globally during startup and config reload (default: true). Keep enabled only when extension capabilities are required by your deployment.", + "plugins.allow": + "Optional allowlist of plugin IDs; when set, only listed plugins are eligible to load. Use this to enforce approved extension inventories in controlled environments.", + "plugins.deny": + "Optional denylist of plugin IDs that are blocked even if allowlists or paths include them. Use deny rules for emergency rollback and hard blocks on risky plugins.", + "plugins.load": + "Plugin loader configuration group for specifying filesystem paths where plugins are discovered. Keep load paths explicit and reviewed to avoid accidental untrusted extension loading.", + "plugins.load.paths": + "Additional plugin files or directories scanned by the loader beyond built-in defaults. Use dedicated extension directories and avoid broad paths with unrelated executable content.", + "plugins.slots": + "Selects which plugins own exclusive runtime slots such as memory so only one plugin provides that capability. Use explicit slot ownership to avoid overlapping providers with conflicting behavior.", "plugins.slots.memory": 'Select the active memory plugin by id, or "none" to disable memory plugins.', - "plugins.entries": "Per-plugin settings keyed by plugin id (enable/disable + config payloads).", - "plugins.entries.*.enabled": "Overrides plugin enable/disable for this entry (restart required).", - "plugins.entries.*.config": "Plugin-defined config payload (schema is provided by the plugin).", + "plugins.entries": + "Per-plugin settings keyed by plugin ID including enablement and plugin-specific runtime configuration payloads. Use this for scoped plugin tuning without changing global loader policy.", + "plugins.entries.*.enabled": + "Per-plugin enablement override for a specific entry, applied on top of global plugin policy (restart required). Use this to stage plugin rollout gradually across environments.", + "plugins.entries.*.apiKey": + "Optional API key field consumed by plugins that accept direct key configuration in entry settings. Use secret/env substitution and avoid committing real credentials into config files.", + "plugins.entries.*.env": + "Per-plugin environment variable map injected for that plugin runtime context only. Use this to scope provider credentials to one plugin instead of sharing global process environment.", + "plugins.entries.*.config": + "Plugin-defined configuration payload interpreted by that plugin's own schema and validation rules. Use only documented fields from the plugin to prevent ignored or invalid settings.", "plugins.installs": "CLI-managed install metadata (used by `openclaw plugins update` to locate install sources).", "plugins.installs.*.source": 'Install source ("npm", "archive", or "path").', @@ -334,14 +853,39 @@ export const FIELD_HELP: Record = { "agents.defaults.imageMaxDimensionPx": "Max image side length in pixels when sanitizing transcript/tool-result image payloads (default: 1200).", "agents.defaults.cliBackends": "Optional CLI backends for text-only fallback (claude-cli, etc.).", + "agents.defaults.compaction": + "Compaction tuning for when context nears token limits, including history share, reserve headroom, and pre-compaction memory flush behavior. Use this when long-running sessions need stable continuity under tight context windows.", + "agents.defaults.compaction.mode": + 'Compaction strategy mode: "default" uses baseline behavior, while "safeguard" applies stricter guardrails to preserve recent context. Keep "default" unless you observe aggressive history loss near limit boundaries.', + "agents.defaults.compaction.reserveTokens": + "Token headroom reserved for reply generation and tool output after compaction runs. Use higher reserves for verbose/tool-heavy sessions, and lower reserves when maximizing retained history matters more.", + "agents.defaults.compaction.keepRecentTokens": + "Minimum token budget preserved from the most recent conversation window during compaction. Use higher values to protect immediate context continuity and lower values to keep more long-tail history.", + "agents.defaults.compaction.reserveTokensFloor": + "Minimum floor enforced for reserveTokens in Pi compaction paths (0 disables the floor guard). Use a non-zero floor to avoid over-aggressive compression under fluctuating token estimates.", + "agents.defaults.compaction.maxHistoryShare": + "Maximum fraction of total context budget allowed for retained history after compaction (range 0.1-0.9). Use lower shares for more generation headroom or higher shares for deeper historical continuity.", + "agents.defaults.compaction.memoryFlush": + "Pre-compaction memory flush settings that run an agentic memory write before heavy compaction. Keep enabled for long sessions so salient context is persisted before aggressive trimming.", + "agents.defaults.compaction.memoryFlush.enabled": + "Enables pre-compaction memory flush before the runtime performs stronger history reduction near token limits. Keep enabled unless you intentionally disable memory side effects in constrained environments.", + "agents.defaults.compaction.memoryFlush.softThresholdTokens": + "Threshold distance to compaction (in tokens) that triggers pre-compaction memory flush execution. Use earlier thresholds for safer persistence, or tighter thresholds for lower flush frequency.", + "agents.defaults.compaction.memoryFlush.prompt": + "User-prompt template used for the pre-compaction memory flush turn when generating memory candidates. Use this only when you need custom extraction instructions beyond the default memory flush behavior.", + "agents.defaults.compaction.memoryFlush.systemPrompt": + "System-prompt override for the pre-compaction memory flush turn to control extraction style and safety constraints. Use carefully so custom instructions do not reduce memory quality or leak sensitive context.", "agents.defaults.humanDelay.mode": 'Delay style for block replies ("off", "natural", "custom").', "agents.defaults.humanDelay.minMs": "Minimum delay in ms for custom humanDelay (default: 800).", "agents.defaults.humanDelay.maxMs": "Maximum delay in ms for custom humanDelay (default: 2500).", + commands: + "Controls chat command surfaces, owner gating, and elevated command access behavior across providers. Keep defaults unless you need stricter operator controls or broader command availability.", "commands.native": - "Register native commands with channels that support it (Discord/Slack/Telegram).", + "Registers native slash/menu commands with channels that support command registration (Discord, Slack, Telegram). Keep enabled for discoverability unless you intentionally run text-only command workflows.", "commands.nativeSkills": - "Register native skill commands (user-invocable skills) with channels that support it.", - "commands.text": "Allow text command parsing (slash commands only).", + "Registers native skill commands so users can invoke skills directly from provider command menus where supported. Keep aligned with your skill policy so exposed commands match what operators expect.", + "commands.text": + "Enables text-command parsing in chat input in addition to native command surfaces where available. Keep this enabled for compatibility across channels that do not support native command registration.", "commands.bash": "Allow bash chat command (`!`; `/bash` alias) to run host shell commands (default: false; requires tools.elevated).", "commands.bashForegroundMs": @@ -356,30 +900,331 @@ export const FIELD_HELP: Record = { "Controls how owner IDs are rendered in the system prompt. Allowed values: raw, hash. Default: raw.", "commands.ownerDisplaySecret": "Optional secret used to HMAC hash owner IDs when ownerDisplay=hash. Prefer env substitution.", + "commands.allowFrom": + "Defines elevated command allow rules by channel and sender for owner-level command surfaces. Use narrow provider-specific identities so privileged commands are not exposed to broad chat audiences.", + session: + "Global session routing, reset, delivery policy, and maintenance controls for conversation history behavior. Keep defaults unless you need stricter isolation, retention, or delivery constraints.", + "session.scope": + 'Sets base session grouping strategy: "per-sender" isolates by sender and "global" shares one session per channel context. Keep "per-sender" for safer multi-user behavior unless deliberate shared context is required.', "session.dmScope": - 'DM session scoping: "main" keeps continuity; "per-peer", "per-channel-peer", or "per-account-channel-peer" isolates DM history (recommended for shared inboxes/multi-account).', + 'DM session scoping: "main" keeps continuity, while "per-peer", "per-channel-peer", and "per-account-channel-peer" increase isolation. Use isolated modes for shared inboxes or multi-account deployments.', "session.identityLinks": - "Map canonical identities to provider-prefixed peer IDs for DM session linking (example: telegram:123456).", + "Maps canonical identities to provider-prefixed peer IDs so equivalent users resolve to one DM thread (example: telegram:123456). Use this when the same human appears across multiple channels or accounts.", + "session.resetTriggers": + "Lists message triggers that force a session reset when matched in inbound content. Use sparingly for explicit reset phrases so context is not dropped unexpectedly during normal conversation.", + "session.idleMinutes": + "Applies a legacy idle reset window in minutes for session reuse behavior across inactivity gaps. Use this only for compatibility and prefer structured reset policies under session.reset/session.resetByType.", + "session.reset": + "Defines the default reset policy object used when no type-specific or channel-specific override applies. Set this first, then layer resetByType or resetByChannel only where behavior must differ.", + "session.reset.mode": + 'Selects reset strategy: "daily" resets at a configured hour and "idle" resets after inactivity windows. Keep one clear mode per policy to avoid surprising context turnover patterns.', + "session.reset.atHour": + "Sets local-hour boundary (0-23) for daily reset mode so sessions roll over at predictable times. Use with mode=daily and align to operator timezone expectations for human-readable behavior.", + "session.reset.idleMinutes": + "Sets inactivity window before reset for idle mode and can also act as secondary guard with daily mode. Use larger values to preserve continuity or smaller values for fresher short-lived threads.", + "session.resetByType": + "Overrides reset behavior by chat type (direct, group, thread) when defaults are not sufficient. Use this when group/thread traffic needs different reset cadence than direct messages.", + "session.resetByType.direct": + "Defines reset policy for direct chats and supersedes the base session.reset configuration for that type. Use this as the canonical direct-message override instead of the legacy dm alias.", + "session.resetByType.dm": + "Deprecated alias for direct reset behavior kept for backward compatibility with older configs. Use session.resetByType.direct instead so future tooling and validation remain consistent.", + "session.resetByType.group": + "Defines reset policy for group chat sessions where continuity and noise patterns differ from DMs. Use shorter idle windows for busy groups if context drift becomes a problem.", + "session.resetByType.thread": + "Defines reset policy for thread-scoped sessions, including focused channel thread workflows. Use this when thread sessions should expire faster or slower than other chat types.", + "session.resetByChannel": + "Provides channel-specific reset overrides keyed by provider/channel id for fine-grained behavior control. Use this only when one channel needs exceptional reset behavior beyond type-level policies.", + "session.store": + "Sets the session storage file path used to persist session records across restarts. Use an explicit path only when you need custom disk layout, backup routing, or mounted-volume storage.", + "session.typingIntervalSeconds": + "Controls interval for repeated typing indicators while replies are being prepared in typing-capable channels. Increase to reduce chatty updates or decrease for more active typing feedback.", + "session.typingMode": + 'Controls typing behavior timing: "never", "instant", "thinking", or "message" based emission points. Keep conservative modes in high-volume channels to avoid unnecessary typing noise.', + "session.mainKey": + 'Overrides the canonical main session key used for continuity when dmScope or routing logic points to "main". Use a stable value only if you intentionally need custom session anchoring.', + "session.sendPolicy": + "Controls cross-session send permissions using allow/deny rules evaluated against channel, chatType, and key prefixes. Use this to fence where session tools can deliver messages in complex environments.", + "session.sendPolicy.default": + 'Sets fallback action when no sendPolicy rule matches: "allow" or "deny". Keep "allow" for simpler setups, or choose "deny" when you require explicit allow rules for every destination.', + "session.sendPolicy.rules": + 'Ordered allow/deny rules evaluated before the default action, for example `{ action: "deny", match: { channel: "discord" } }`. Put most specific rules first so broad rules do not shadow exceptions.', + "session.sendPolicy.rules[].action": + 'Defines rule decision as "allow" or "deny" when the corresponding match criteria are satisfied. Use deny-first ordering when enforcing strict boundaries with explicit allow exceptions.', + "session.sendPolicy.rules[].match": + "Defines optional rule match conditions that can combine channel, chatType, and key-prefix constraints. Keep matches narrow so policy intent stays readable and debugging remains straightforward.", + "session.sendPolicy.rules[].match.channel": + "Matches rule application to a specific channel/provider id (for example discord, telegram, slack). Use this when one channel should permit or deny delivery independently of others.", + "session.sendPolicy.rules[].match.chatType": + "Matches rule application to chat type (direct, group, thread) so behavior varies by conversation form. Use this when DM and group destinations require different safety boundaries.", + "session.sendPolicy.rules[].match.keyPrefix": + "Matches a normalized session-key prefix after internal key normalization steps in policy consumers. Use this for general prefix controls, and prefer rawKeyPrefix when exact full-key matching is required.", + "session.sendPolicy.rules[].match.rawKeyPrefix": + "Matches the raw, unnormalized session-key prefix for exact full-key policy targeting. Use this when normalized keyPrefix is too broad and you need agent-prefixed or transport-specific precision.", + "session.agentToAgent": + "Groups controls for inter-agent session exchanges, including loop prevention limits on reply chaining. Keep defaults unless you run advanced agent-to-agent automation with strict turn caps.", + "session.agentToAgent.maxPingPongTurns": + "Max reply-back turns between requester and target agents during agent-to-agent exchanges (0-5). Use lower values to hard-limit chatter loops and preserve predictable run completion.", + "session.threadBindings": + "Shared defaults for thread-bound session routing behavior across providers that support thread focus workflows. Configure global defaults here and override per channel only when behavior differs.", "session.threadBindings.enabled": - "Global master switch for thread-bound session routing features. Channel/provider keys (for example channels.discord.threadBindings.enabled) override this default. Default: true.", + "Global master switch for thread-bound session routing features and focused thread delivery behavior. Keep enabled for modern thread workflows unless you need to disable thread binding globally.", "session.threadBindings.ttlHours": - "Default auto-unfocus TTL in hours for thread-bound sessions across providers/channels. Set 0 to disable (default: 24). Provider keys (for example channels.discord.threadBindings.ttlHours) override this.", + "Default auto-unfocus TTL in hours for thread-bound sessions across providers/channels (0 disables). Keep 24h-like values for practical focus windows unless your team needs longer-lived thread binding.", + "session.maintenance": + "Automatic session-store maintenance controls for pruning age, entry caps, and file rotation behavior. Start in warn mode to observe impact, then enforce once thresholds are tuned.", + "session.maintenance.mode": + 'Determines whether maintenance policies are only reported ("warn") or actively applied ("enforce"). Keep "warn" during rollout and switch to "enforce" after validating safe thresholds.', + "session.maintenance.pruneAfter": + "Removes entries older than this duration (for example `30d` or `12h`) during maintenance passes. Use this as the primary age-retention control and align it with data retention policy.", + "session.maintenance.pruneDays": + "Deprecated age-retention field kept for compatibility with legacy configs using day counts. Use session.maintenance.pruneAfter instead so duration syntax and behavior are consistent.", + "session.maintenance.maxEntries": + "Caps total session entry count retained in the store to prevent unbounded growth over time. Use lower limits for constrained environments, or higher limits when longer history is required.", + "session.maintenance.rotateBytes": + "Rotates the session store when file size exceeds a threshold such as `10mb` or `1gb`. Use this to bound single-file growth and keep backup/restore operations manageable.", + cron: "Global scheduler settings for stored cron jobs, run concurrency, delivery fallback, and run-session retention. Keep defaults unless you are scaling job volume or integrating external webhook receivers.", + "cron.enabled": + "Enables cron job execution for stored schedules managed by the gateway. Keep enabled for normal reminder/automation flows, and disable only to pause all cron execution without deleting jobs.", + "cron.store": + "Path to the cron job store file used to persist scheduled jobs across restarts. Set an explicit path only when you need custom storage layout, backups, or mounted volumes.", + "cron.maxConcurrentRuns": + "Limits how many cron jobs can execute at the same time when multiple schedules fire together. Use lower values to protect CPU/memory under heavy automation load, or raise carefully for higher throughput.", + "cron.webhook": + 'Deprecated legacy fallback webhook URL used only for old jobs with `notify=true`. Migrate to per-job delivery using `delivery.mode="webhook"` plus `delivery.to`, and avoid relying on this global field.', + "cron.webhookToken": + "Bearer token attached to cron webhook POST deliveries when webhook mode is used. Prefer secret/env substitution and rotate this token regularly if shared webhook endpoints are internet-reachable.", + "cron.sessionRetention": + "Controls how long completed cron run sessions are kept before pruning (`24h`, `7d`, `1h30m`, or `false` to disable pruning; default: `24h`). Use shorter retention to reduce storage growth on high-frequency schedules.", + hooks: + "Inbound webhook automation surface for mapping external events into wake or agent actions in OpenClaw. Keep this locked down with explicit token/session/agent controls before exposing it beyond trusted networks.", + "hooks.enabled": + "Enables the hooks endpoint and mapping execution pipeline for inbound webhook requests. Keep disabled unless you are actively routing external events into the gateway.", + "hooks.path": + "HTTP path used by the hooks endpoint (for example `/hooks`) on the gateway control server. Use a non-guessable path and combine it with token validation for defense in depth.", + "hooks.token": + "Shared bearer token checked by hooks ingress for request authentication before mappings run. Use environment substitution and rotate regularly when webhook endpoints are internet-accessible.", + "hooks.defaultSessionKey": + "Fallback session key used for hook deliveries when a request does not provide one through allowed channels. Use a stable but scoped key to avoid mixing unrelated automation conversations.", + "hooks.allowRequestSessionKey": + "Allows callers to supply a session key in hook requests when true, enabling caller-controlled routing. Keep false unless trusted integrators explicitly need custom session threading.", + "hooks.allowedSessionKeyPrefixes": + "Allowlist of accepted session-key prefixes for inbound hook requests when caller-provided keys are enabled. Use narrow prefixes to prevent arbitrary session-key injection.", + "hooks.allowedAgentIds": + "Allowlist of agent IDs that hook mappings are allowed to target when selecting execution agents. Use this to constrain automation events to dedicated service agents.", + "hooks.maxBodyBytes": + "Maximum accepted webhook payload size in bytes before the request is rejected. Keep this bounded to reduce abuse risk and protect memory usage under bursty integrations.", + "hooks.presets": + "Named hook preset bundles applied at load time to seed standard mappings and behavior defaults. Keep preset usage explicit so operators can audit which automations are active.", + "hooks.transformsDir": + "Base directory for hook transform modules referenced by mapping transform.module paths. Use a controlled repo directory so dynamic imports remain reviewable and predictable.", + "hooks.mappings": + "Ordered mapping rules that match inbound hook requests and choose wake or agent actions with optional delivery routing. Use specific mappings first to avoid broad pattern rules capturing everything.", + "hooks.mappings[].id": + "Optional stable identifier for a hook mapping entry used for auditing, troubleshooting, and targeted updates. Use unique IDs so logs and config diffs can reference mappings unambiguously.", + "hooks.mappings[].match": + "Grouping object for mapping match predicates such as path and source before action routing is applied. Keep match criteria specific so unrelated webhook traffic does not trigger automations.", + "hooks.mappings[].match.path": + "Path match condition for a hook mapping, usually compared against the inbound request path. Use this to split automation behavior by webhook endpoint path families.", + "hooks.mappings[].match.source": + "Source match condition for a hook mapping, typically set by trusted upstream metadata or adapter logic. Use stable source identifiers so routing remains deterministic across retries.", + "hooks.mappings[].action": + 'Mapping action type: "wake" triggers agent wake flow, while "agent" sends directly to agent handling. Use "agent" for immediate execution and "wake" when heartbeat-driven processing is preferred.', + "hooks.mappings[].wakeMode": + 'Wake scheduling mode: "now" wakes immediately, while "next-heartbeat" defers until the next heartbeat cycle. Use deferred mode for lower-priority automations that can tolerate slight delay.', + "hooks.mappings[].name": + "Human-readable mapping display name used in diagnostics and operator-facing config UIs. Keep names concise and descriptive so routing intent is obvious during incident review.", + "hooks.mappings[].agentId": + "Target agent ID for mapping execution when action routing should not use defaults. Use dedicated automation agents to isolate webhook behavior from interactive operator sessions.", + "hooks.mappings[].sessionKey": + "Explicit session key override for mapping-delivered messages to control thread continuity. Use stable scoped keys so repeated events correlate without leaking into unrelated conversations.", + "hooks.mappings[].messageTemplate": + "Template for synthesizing structured mapping input into the final message content sent to the target action path. Keep templates deterministic so downstream parsing and behavior remain stable.", + "hooks.mappings[].textTemplate": + "Text-only fallback template used when rich payload rendering is not desired or not supported. Use this to provide a concise, consistent summary string for chat delivery surfaces.", + "hooks.mappings[].deliver": + "Controls whether mapping execution results are delivered back to a channel destination versus being processed silently. Disable delivery for background automations that should not post user-facing output.", + "hooks.mappings[].allowUnsafeExternalContent": + "When true, mapping content may include less-sanitized external payload data in generated messages. Keep false by default and enable only for trusted sources with reviewed transform logic.", + "hooks.mappings[].channel": + 'Delivery channel override for mapping outputs (for example "last", "telegram", "discord", "slack", "signal", "imessage", or "msteams"). Keep channel overrides explicit to avoid accidental cross-channel sends.', + "hooks.mappings[].to": + "Destination identifier inside the selected channel when mapping replies should route to a fixed target. Verify provider-specific destination formats before enabling production mappings.", + "hooks.mappings[].model": + "Optional model override for mapping-triggered runs when automation should use a different model than agent defaults. Use this sparingly so behavior remains predictable across mapping executions.", + "hooks.mappings[].thinking": + "Optional thinking-effort override for mapping-triggered runs to tune latency versus reasoning depth. Keep low or minimal for high-volume hooks unless deeper reasoning is clearly required.", + "hooks.mappings[].timeoutSeconds": + "Maximum runtime allowed for mapping action execution before timeout handling applies. Use tighter limits for high-volume webhook sources to prevent queue pileups.", + "hooks.mappings[].transform": + "Transform configuration block defining module/export preprocessing before mapping action handling. Use transforms only from reviewed code paths and keep behavior deterministic for repeatable automation.", + "hooks.mappings[].transform.module": + "Relative transform module path loaded from hooks.transformsDir to rewrite incoming payloads before delivery. Keep modules local, reviewed, and free of path traversal patterns.", + "hooks.mappings[].transform.export": + "Named export to invoke from the transform module; defaults to module default export when omitted. Set this when one file hosts multiple transform handlers.", + "hooks.gmail": + "Gmail push integration settings used for Pub/Sub notifications and optional local callback serving. Keep this scoped to dedicated Gmail automation accounts where possible.", + "hooks.gmail.account": + "Google account identifier used for Gmail watch/subscription operations in this hook integration. Use a dedicated automation mailbox account to isolate operational permissions.", + "hooks.gmail.label": + "Optional Gmail label filter limiting which labeled messages trigger hook events. Keep filters narrow to avoid flooding automations with unrelated inbox traffic.", + "hooks.gmail.topic": + "Google Pub/Sub topic name used by Gmail watch to publish change notifications for this account. Ensure the topic IAM grants Gmail publish access before enabling watches.", + "hooks.gmail.subscription": + "Pub/Sub subscription consumed by the gateway to receive Gmail change notifications from the configured topic. Keep subscription ownership clear so multiple consumers do not race unexpectedly.", + "hooks.gmail.hookUrl": + "Public callback URL Gmail or intermediaries invoke to deliver notifications into this hook pipeline. Keep this URL protected with token validation and restricted network exposure.", + "hooks.gmail.includeBody": + "When true, fetch and include email body content for downstream mapping/agent processing. Keep false unless body text is required, because this increases payload size and sensitivity.", + "hooks.gmail.allowUnsafeExternalContent": + "Allows less-sanitized external Gmail content to pass into processing when enabled. Keep disabled for safer defaults, and enable only for trusted mail streams with controlled transforms.", + "hooks.gmail.serve": + "Local callback server settings block for directly receiving Gmail notifications without a separate ingress layer. Enable only when this process should terminate webhook traffic itself.", + "hooks.gmail.pushToken": + "Shared secret token required on Gmail push hook callbacks before processing notifications. Use env substitution and rotate if callback endpoints are exposed externally.", + "hooks.gmail.maxBytes": + "Maximum Gmail payload bytes processed per event when includeBody is enabled. Keep conservative limits to reduce oversized message processing cost and risk.", + "hooks.gmail.renewEveryMinutes": + "Renewal cadence in minutes for Gmail watch subscriptions to prevent expiration. Set below provider expiration windows and monitor renew failures in logs.", + "hooks.gmail.serve.bind": + "Bind address for the local Gmail callback HTTP server used when serving hooks directly. Keep loopback-only unless external ingress is intentionally required.", + "hooks.gmail.serve.port": + "Port for the local Gmail callback HTTP server when serve mode is enabled. Use a dedicated port to avoid collisions with gateway/control interfaces.", + "hooks.gmail.serve.path": + "HTTP path on the local Gmail callback server where push notifications are accepted. Keep this consistent with subscription configuration to avoid dropped events.", + "hooks.gmail.tailscale.mode": + 'Tailscale exposure mode for Gmail callbacks: "off", "serve", or "funnel". Use "serve" for private tailnet delivery and "funnel" only when public internet ingress is required.', + "hooks.gmail.tailscale": + "Tailscale exposure configuration block for publishing Gmail callbacks through Serve/Funnel routes. Use private tailnet modes before enabling any public ingress path.", + "hooks.gmail.tailscale.path": + "Path published by Tailscale Serve/Funnel for Gmail callback forwarding when enabled. Keep it aligned with Gmail webhook config so requests reach the expected handler.", + "hooks.gmail.tailscale.target": + "Local service target forwarded by Tailscale Serve/Funnel (for example http://127.0.0.1:8787). Use explicit loopback targets to avoid ambiguous routing.", + "hooks.gmail.model": + "Optional model override for Gmail-triggered runs when mailbox automations should use dedicated model behavior. Keep unset to inherit agent defaults unless mailbox tasks need specialization.", + "hooks.gmail.thinking": + 'Thinking effort override for Gmail-driven agent runs: "off", "minimal", "low", "medium", or "high". Keep modest defaults for routine inbox automations to control cost and latency.', + "hooks.internal": + "Internal hook runtime settings for bundled/custom event handlers loaded from module paths. Use this for trusted in-process automations and keep handler loading tightly scoped.", + "hooks.internal.enabled": + "Enables processing for internal hook handlers and configured entries in the internal hook runtime. Keep disabled unless internal hook handlers are intentionally configured.", + "hooks.internal.handlers": + "List of internal event handlers mapping event names to modules and optional exports. Keep handler definitions explicit so event-to-code routing is auditable.", + "hooks.internal.handlers[].event": + "Internal event name that triggers this handler module when emitted by the runtime. Use stable event naming conventions to avoid accidental overlap across handlers.", + "hooks.internal.handlers[].module": + "Safe relative module path for the internal hook handler implementation loaded at runtime. Keep module files in reviewed directories and avoid dynamic path composition.", + "hooks.internal.handlers[].export": + "Optional named export for the internal hook handler function when module default export is not used. Set this when one module ships multiple handler entrypoints.", + "hooks.internal.entries": + "Configured internal hook entry records used to register concrete runtime handlers and metadata. Keep entries explicit and versioned so production behavior is auditable.", + "hooks.internal.load": + "Internal hook loader settings controlling where handler modules are discovered at startup. Use constrained load roots to reduce accidental module conflicts or shadowing.", + "hooks.internal.load.extraDirs": + "Additional directories searched for internal hook modules beyond default load paths. Keep this minimal and controlled to reduce accidental module shadowing.", + "hooks.internal.installs": + "Install metadata for internal hook modules, including source and resolved artifacts for repeatable deployments. Use this as operational provenance and avoid manual drift edits.", + messages: + "Message formatting, acknowledgment, queueing, debounce, and status reaction behavior for inbound/outbound chat flows. Use this section when channel responsiveness or message UX needs adjustment.", + "messages.messagePrefix": + "Prefix text prepended to inbound user messages before they are handed to the agent runtime. Use this sparingly for channel context markers and keep it stable across sessions.", + "messages.responsePrefix": + "Prefix text prepended to outbound assistant replies before sending to channels. Use for lightweight branding/context tags and avoid long prefixes that reduce content density.", + "messages.groupChat": + "Group-message handling controls including mention triggers and history window sizing. Keep mention patterns narrow so group channels do not trigger on every message.", + "messages.groupChat.mentionPatterns": + "Regex-like patterns used to detect explicit mentions/trigger phrases in group chats. Use precise patterns to reduce false positives in high-volume channels.", + "messages.groupChat.historyLimit": + "Maximum number of prior group messages loaded as context per turn for group sessions. Use higher values for richer continuity, or lower values for faster and cheaper responses.", + "messages.queue": + "Inbound message queue strategy used to buffer bursts before processing turns. Tune this for busy channels where sequential processing or batching behavior matters.", + "messages.queue.mode": + 'Queue behavior mode: "steer", "followup", "collect", "steer-backlog", "steer+backlog", "queue", or "interrupt". Keep conservative modes unless you intentionally need aggressive interruption/backlog semantics.', + "messages.queue.byChannel": + "Per-channel queue mode overrides keyed by provider id (for example telegram, discord, slack). Use this when one channel’s traffic pattern needs different queue behavior than global defaults.", + "messages.queue.debounceMs": + "Global queue debounce window in milliseconds before processing buffered inbound messages. Use higher values to coalesce rapid bursts, or lower values for reduced response latency.", + "messages.queue.debounceMsByChannel": + "Per-channel debounce overrides for queue behavior keyed by provider id. Use this to tune burst handling independently for chat surfaces with different pacing.", + "messages.queue.cap": + "Maximum number of queued inbound items retained before drop policy applies. Keep caps bounded in noisy channels so memory usage remains predictable.", + "messages.queue.drop": + 'Drop strategy when queue cap is exceeded: "old", "new", or "summarize". Use summarize when preserving intent matters, or old/new when deterministic dropping is preferred.', + "messages.inbound": + "Direct inbound debounce settings used before queue/turn processing starts. Configure this for provider-specific rapid message bursts from the same sender.", + "messages.inbound.byChannel": + "Per-channel inbound debounce overrides keyed by provider id in milliseconds. Use this where some providers send message fragments more aggressively than others.", + "messages.removeAckAfterReply": + "Removes the acknowledgment reaction after final reply delivery when enabled. Keep enabled for cleaner UX in channels where persistent ack reactions create clutter.", + "messages.tts": + "Text-to-speech policy for reading agent replies aloud on supported voice or audio surfaces. Keep disabled unless voice playback is part of your operator/user workflow.", + channels: + "Channel provider configurations plus shared defaults that control access policies, heartbeat visibility, and per-surface behavior. Keep defaults centralized and override per provider only where required.", + "channels.telegram": + "Telegram channel provider configuration including auth tokens, retry behavior, and message rendering controls. Use this section to tune bot behavior for Telegram-specific API semantics.", + "channels.slack": + "Slack channel provider configuration for bot/app tokens, streaming behavior, and DM policy controls. Keep token handling and thread behavior explicit to avoid noisy workspace interactions.", + "channels.discord": + "Discord channel provider configuration for bot auth, retry policy, streaming, thread bindings, and optional voice capabilities. Keep privileged intents and advanced features disabled unless needed.", + "channels.whatsapp": + "WhatsApp channel provider configuration for access policy and message batching behavior. Use this section to tune responsiveness and direct-message routing safety for WhatsApp chats.", + "channels.signal": + "Signal channel provider configuration including account identity and DM policy behavior. Keep account mapping explicit so routing remains stable across multi-device setups.", + "channels.imessage": + "iMessage channel provider configuration for CLI integration and DM access policy handling. Use explicit CLI paths when runtime environments have non-standard binary locations.", + "channels.bluebubbles": + "BlueBubbles channel provider configuration used for Apple messaging bridge integrations. Keep DM policy aligned with your trusted sender model in shared deployments.", + "channels.msteams": + "Microsoft Teams channel provider configuration and provider-specific policy toggles. Use this section to isolate Teams behavior from other enterprise chat providers.", + "channels.mattermost": + "Mattermost channel provider configuration for bot credentials, base URL, and message trigger modes. Keep mention/trigger rules strict in high-volume team channels.", + "channels.irc": + "IRC channel provider configuration and compatibility settings for classic IRC transport workflows. Use this section when bridging legacy chat infrastructure into OpenClaw.", + "channels.defaults": + "Default channel behavior applied across providers when provider-specific settings are not set. Use this to enforce consistent baseline policy before per-provider tuning.", + "channels.defaults.groupPolicy": + 'Default group policy across channels: "open", "disabled", or "allowlist". Keep "allowlist" for safer production setups unless broad group participation is intentional.', + "channels.defaults.heartbeat": + "Default heartbeat visibility settings for status messages emitted by providers/channels. Tune this globally to reduce noisy healthy-state updates while keeping alerts visible.", + "channels.defaults.heartbeat.showOk": + "Shows healthy/OK heartbeat status entries when true in channel status outputs. Keep false in noisy environments and enable only when operators need explicit healthy confirmations.", + "channels.defaults.heartbeat.showAlerts": + "Shows degraded/error heartbeat alerts when true so operator channels surface problems promptly. Keep enabled in production so broken channel states are visible.", + "channels.defaults.heartbeat.useIndicator": + "Enables concise indicator-style heartbeat rendering instead of verbose status text where supported. Use indicator mode for dense dashboards with many active channels.", "channels.telegram.configWrites": "Allow Telegram to write config in response to channel events/commands (default: true).", + "channels.telegram.botToken": + "Telegram bot token used to authenticate Bot API requests for this account/provider config. Use secret/env substitution and rotate tokens if exposure is suspected.", + "channels.telegram.capabilities.inlineButtons": + "Enable Telegram inline button components for supported command and interaction surfaces. Disable if your deployment needs plain-text-only compatibility behavior.", "channels.slack.configWrites": "Allow Slack to write config in response to channel events/commands (default: true).", + "channels.slack.botToken": + "Slack bot token used for standard chat actions in the configured workspace. Keep this credential scoped and rotate if workspace app permissions change.", + "channels.slack.appToken": + "Slack app-level token used for Socket Mode connections and event transport when enabled. Use least-privilege app scopes and store this token as a secret.", + "channels.slack.userToken": + "Optional Slack user token for workflows requiring user-context API access beyond bot permissions. Use sparingly and audit scopes because this token can carry broader authority.", + "channels.slack.userTokenReadOnly": + "When true, treat configured Slack user token usage as read-only helper behavior where possible. Keep enabled if you only need supplemental reads without user-context writes.", "channels.mattermost.configWrites": "Allow Mattermost to write config in response to channel events/commands (default: true).", "channels.discord.configWrites": "Allow Discord to write config in response to channel events/commands (default: true).", + "channels.discord.token": + "Discord bot token used for gateway and REST API authentication for this provider account. Keep this secret out of committed config and rotate immediately after any leak.", "channels.discord.proxy": "Proxy URL for Discord gateway + API requests (app-id lookup and allowlist resolution). Set per account via channels.discord.accounts..proxy.", "channels.whatsapp.configWrites": "Allow WhatsApp to write config in response to channel events/commands (default: true).", "channels.signal.configWrites": "Allow Signal to write config in response to channel events/commands (default: true).", + "channels.signal.account": + "Signal account identifier (phone/number handle) used to bind this channel config to a specific Signal identity. Keep this aligned with your linked device/session state.", "channels.imessage.configWrites": "Allow iMessage to write config in response to channel events/commands (default: true).", + "channels.imessage.cliPath": + "Filesystem path to the iMessage bridge CLI binary used for send/receive operations. Set explicitly when the binary is not on PATH in service runtime environments.", "channels.msteams.configWrites": "Allow Microsoft Teams to write config in response to channel events/commands (default: true).", "channels.modelByChannel": @@ -400,8 +1245,6 @@ export const FIELD_HELP: Record = { "Enable native Slack text streaming (chat.startStream/chat.appendStream/chat.stopStream) when channels.slack.streaming is partial (default: true).", "channels.slack.streamMode": "Legacy Slack preview mode alias (replace | status_final | append); auto-migrated to channels.slack.streaming.", - "session.agentToAgent.maxPingPongTurns": - "Max reply-back turns between requester and target (0–5).", "channels.telegram.customCommands": "Additional Telegram bot menu commands (merged with native; conflicts ignored).", "messages.suppressToolErrors": diff --git a/src/config/schema.hints.ts b/src/config/schema.hints.ts index 14c917bd986..d788a87d701 100644 --- a/src/config/schema.hints.ts +++ b/src/config/schema.hints.ts @@ -2,6 +2,7 @@ import { z } from "zod"; import { createSubsystemLogger } from "../logging/subsystem.js"; import { FIELD_HELP } from "./schema.help.js"; import { FIELD_LABELS } from "./schema.labels.js"; +import { applyDerivedTags } from "./schema.tags.js"; import { sensitive } from "./zod-schema.sensitive.js"; const log = createSubsystemLogger("config/schema"); @@ -9,6 +10,7 @@ const log = createSubsystemLogger("config/schema"); export type ConfigUiHint = { label?: string; help?: string; + tags?: string[]; group?: string; order?: number; advanced?: boolean; @@ -143,7 +145,7 @@ export function buildBaseHints(): ConfigUiHints { const current = hints[path]; hints[path] = current ? { ...current, placeholder } : { placeholder }; } - return hints; + return applyDerivedTags(hints); } export function applySensitiveHints( diff --git a/src/config/schema.labels.ts b/src/config/schema.labels.ts index ba2b2691a9e..479448ad584 100644 --- a/src/config/schema.labels.ts +++ b/src/config/schema.labels.ts @@ -1,8 +1,31 @@ import { IRC_FIELD_LABELS } from "./schema.irc.js"; export const FIELD_LABELS: Record = { + meta: "Metadata", "meta.lastTouchedVersion": "Config Last Touched Version", "meta.lastTouchedAt": "Config Last Touched At", + env: "Environment", + "env.shellEnv": "Shell Environment Import", + "env.shellEnv.enabled": "Shell Environment Import Enabled", + "env.shellEnv.timeoutMs": "Shell Environment Import Timeout (ms)", + "env.vars": "Environment Variable Overrides", + wizard: "Setup Wizard State", + "wizard.lastRunAt": "Wizard Last Run Timestamp", + "wizard.lastRunVersion": "Wizard Last Run Version", + "wizard.lastRunCommit": "Wizard Last Run Commit", + "wizard.lastRunCommand": "Wizard Last Run Command", + "wizard.lastRunMode": "Wizard Last Run Mode", + diagnostics: "Diagnostics", + "diagnostics.otel": "OpenTelemetry", + "diagnostics.cacheTrace": "Cache Trace", + logging: "Logging", + "logging.level": "Log Level", + "logging.file": "Log File Path", + "logging.consoleLevel": "Console Log Level", + "logging.consoleStyle": "Console Log Style", + "logging.redactSensitive": "Sensitive Data Redaction Mode", + "logging.redactPatterns": "Custom Redaction Patterns", + update: "Updates", "update.channel": "Update Channel", "update.checkOnStart": "Update Check on Start", "update.auto.enabled": "Auto Update Enabled", @@ -28,6 +51,41 @@ export const FIELD_LABELS: Record = { "diagnostics.cacheTrace.includeSystem": "Cache Trace Include System", "agents.list.*.identity.avatar": "Identity Avatar", "agents.list.*.skills": "Agent Skill Filter", + agents: "Agents", + "agents.defaults": "Agent Defaults", + "agents.list": "Agent List", + gateway: "Gateway", + "gateway.port": "Gateway Port", + "gateway.mode": "Gateway Mode", + "gateway.bind": "Gateway Bind Mode", + "gateway.customBindHost": "Gateway Custom Bind Host", + "gateway.controlUi": "Control UI", + "gateway.controlUi.enabled": "Control UI Enabled", + "gateway.auth": "Gateway Auth", + "gateway.auth.mode": "Gateway Auth Mode", + "gateway.auth.allowTailscale": "Gateway Auth Allow Tailscale Identity", + "gateway.auth.rateLimit": "Gateway Auth Rate Limit", + "gateway.auth.trustedProxy": "Gateway Trusted Proxy Auth", + "gateway.trustedProxies": "Gateway Trusted Proxy CIDRs", + "gateway.allowRealIpFallback": "Gateway Allow x-real-ip Fallback", + "gateway.tools": "Gateway Tool Exposure Policy", + "gateway.tools.allow": "Gateway Tool Allowlist", + "gateway.tools.deny": "Gateway Tool Denylist", + "gateway.channelHealthCheckMinutes": "Gateway Channel Health Check Interval (min)", + "gateway.tailscale": "Gateway Tailscale", + "gateway.tailscale.mode": "Gateway Tailscale Mode", + "gateway.tailscale.resetOnExit": "Gateway Tailscale Reset on Exit", + "gateway.remote": "Remote Gateway", + "gateway.remote.transport": "Remote Gateway Transport", + "gateway.reload": "Config Reload", + "gateway.tls": "Gateway TLS", + "gateway.tls.enabled": "Gateway TLS Enabled", + "gateway.tls.autoGenerate": "Gateway TLS Auto-Generate Cert", + "gateway.tls.certPath": "Gateway TLS Certificate Path", + "gateway.tls.keyPath": "Gateway TLS Key Path", + "gateway.tls.caPath": "Gateway TLS CA Path", + "gateway.http": "Gateway HTTP API", + "gateway.http.endpoints": "Gateway HTTP Endpoints", "gateway.remote.url": "Remote Gateway URL", "gateway.remote.sshTarget": "Remote Gateway SSH Target", "gateway.remote.sshIdentity": "Remote Gateway SSH Identity", @@ -36,6 +94,25 @@ export const FIELD_LABELS: Record = { "gateway.remote.tlsFingerprint": "Remote Gateway TLS Fingerprint", "gateway.auth.token": "Gateway Token", "gateway.auth.password": "Gateway Password", + browser: "Browser", + "browser.enabled": "Browser Enabled", + "browser.cdpUrl": "Browser CDP URL", + "browser.color": "Browser Accent Color", + "browser.executablePath": "Browser Executable Path", + "browser.headless": "Browser Headless Mode", + "browser.noSandbox": "Browser No-Sandbox Mode", + "browser.attachOnly": "Browser Attach-only Mode", + "browser.defaultProfile": "Browser Default Profile", + "browser.profiles": "Browser Profiles", + "browser.profiles.*.cdpPort": "Browser Profile CDP Port", + "browser.profiles.*.cdpUrl": "Browser Profile CDP URL", + "browser.profiles.*.driver": "Browser Profile Driver", + "browser.profiles.*.color": "Browser Profile Accent Color", + tools: "Tools", + "tools.allow": "Tool Allowlist", + "tools.deny": "Tool Denylist", + "tools.web": "Web Tools", + "tools.exec": "Exec Tool", "tools.media.image.enabled": "Enable Image Understanding", "tools.media.image.maxBytes": "Image Understanding Max Bytes", "tools.media.image.maxChars": "Image Understanding Max Chars", @@ -94,9 +171,30 @@ export const FIELD_LABELS: Record = { "tools.exec.security": "Exec Security", "tools.exec.ask": "Exec Ask", "tools.exec.node": "Exec Node Binding", + "tools.agentToAgent": "Agent-to-Agent Tool Access", + "tools.agentToAgent.enabled": "Enable Agent-to-Agent Tool", + "tools.agentToAgent.allow": "Agent-to-Agent Target Allowlist", + "tools.elevated": "Elevated Tool Access", + "tools.elevated.enabled": "Enable Elevated Tool Access", + "tools.elevated.allowFrom": "Elevated Tool Allow Rules", + "tools.subagents": "Subagent Tool Policy", + "tools.subagents.tools": "Subagent Tool Allow/Deny Policy", + "tools.sandbox": "Sandbox Tool Policy", + "tools.sandbox.tools": "Sandbox Tool Allow/Deny Policy", "tools.exec.pathPrepend": "Exec PATH Prepend", "tools.exec.safeBins": "Exec Safe Bins", "tools.exec.safeBinProfiles": "Exec Safe Bin Profiles", + approvals: "Approvals", + "approvals.exec": "Exec Approval Forwarding", + "approvals.exec.enabled": "Forward Exec Approvals", + "approvals.exec.mode": "Approval Forwarding Mode", + "approvals.exec.agentFilter": "Approval Agent Filter", + "approvals.exec.sessionFilter": "Approval Session Filter", + "approvals.exec.targets": "Approval Forwarding Targets", + "approvals.exec.targets[].channel": "Approval Target Channel", + "approvals.exec.targets[].to": "Approval Target Destination", + "approvals.exec.targets[].accountId": "Approval Target Account ID", + "approvals.exec.targets[].threadId": "Approval Target Thread ID", "tools.message.allowCrossContextSend": "Allow Cross-Context Messaging", "tools.message.crossContext.allowWithinProvider": "Allow Cross-Context (Same Provider)", "tools.message.crossContext.allowAcrossProviders": "Allow Cross-Context (Across Providers)", @@ -110,12 +208,23 @@ export const FIELD_LABELS: Record = { "tools.web.search.maxResults": "Web Search Max Results", "tools.web.search.timeoutSeconds": "Web Search Timeout (sec)", "tools.web.search.cacheTtlMinutes": "Web Search Cache TTL (min)", + "tools.web.search.perplexity.apiKey": "Perplexity API Key", + "tools.web.search.perplexity.baseUrl": "Perplexity Base URL", + "tools.web.search.perplexity.model": "Perplexity Model", "tools.web.fetch.enabled": "Enable Web Fetch Tool", "tools.web.fetch.maxChars": "Web Fetch Max Chars", + "tools.web.fetch.maxCharsCap": "Web Fetch Hard Max Chars", "tools.web.fetch.timeoutSeconds": "Web Fetch Timeout (sec)", "tools.web.fetch.cacheTtlMinutes": "Web Fetch Cache TTL (min)", "tools.web.fetch.maxRedirects": "Web Fetch Max Redirects", "tools.web.fetch.userAgent": "Web Fetch User-Agent", + "tools.web.fetch.readability": "Web Fetch Readability Extraction", + "tools.web.fetch.firecrawl.enabled": "Enable Firecrawl Fallback", + "tools.web.fetch.firecrawl.apiKey": "Firecrawl API Key", + "tools.web.fetch.firecrawl.baseUrl": "Firecrawl Base URL", + "tools.web.fetch.firecrawl.onlyMainContent": "Firecrawl Main Content Only", + "tools.web.fetch.firecrawl.maxAgeMs": "Firecrawl Cache Max Age (ms)", + "tools.web.fetch.firecrawl.timeoutSeconds": "Firecrawl Timeout (sec)", "gateway.controlUi.basePath": "Control UI Base Path", "gateway.controlUi.root": "Control UI Assets Root", "gateway.controlUi.allowedOrigins": "Control UI Allowed Origins", @@ -128,8 +237,30 @@ export const FIELD_LABELS: Record = { "gateway.nodes.browser.node": "Gateway Node Browser Pin", "gateway.nodes.allowCommands": "Gateway Node Allowlist (Extra Commands)", "gateway.nodes.denyCommands": "Gateway Node Denylist", + nodeHost: "Node Host", + "nodeHost.browserProxy": "Node Browser Proxy", "nodeHost.browserProxy.enabled": "Node Browser Proxy Enabled", "nodeHost.browserProxy.allowProfiles": "Node Browser Proxy Allowed Profiles", + media: "Media", + "media.preserveFilenames": "Preserve Media Filenames", + audio: "Audio", + "audio.transcription": "Audio Transcription", + "audio.transcription.command": "Audio Transcription Command", + "audio.transcription.timeoutSeconds": "Audio Transcription Timeout (sec)", + bindings: "Bindings", + "bindings[].agentId": "Binding Agent ID", + "bindings[].match": "Binding Match Rule", + "bindings[].match.channel": "Binding Channel", + "bindings[].match.accountId": "Binding Account ID", + "bindings[].match.peer": "Binding Peer Match", + "bindings[].match.peer.kind": "Binding Peer Kind", + "bindings[].match.peer.id": "Binding Peer ID", + "bindings[].match.guildId": "Binding Guild ID", + "bindings[].match.teamId": "Binding Team ID", + "bindings[].match.roles": "Binding Roles", + broadcast: "Broadcast", + "broadcast.strategy": "Broadcast Strategy", + "broadcast.*": "Broadcast Destination List", "skills.load.watch": "Watch Skills", "skills.load.watchDebounceMs": "Skills Watch Debounce (ms)", "agents.defaults.workspace": "Workspace", @@ -149,7 +280,11 @@ export const FIELD_LABELS: Record = { "agents.defaults.memorySearch.remote.baseUrl": "Remote Embedding Base URL", "agents.defaults.memorySearch.remote.apiKey": "Remote Embedding API Key", "agents.defaults.memorySearch.remote.headers": "Remote Embedding Headers", + "agents.defaults.memorySearch.remote.batch.enabled": "Remote Batch Embedding Enabled", + "agents.defaults.memorySearch.remote.batch.wait": "Remote Batch Wait for Completion", "agents.defaults.memorySearch.remote.batch.concurrency": "Remote Batch Concurrency", + "agents.defaults.memorySearch.remote.batch.pollIntervalMs": "Remote Batch Poll Interval (ms)", + "agents.defaults.memorySearch.remote.batch.timeoutMinutes": "Remote Batch Timeout (min)", "agents.defaults.memorySearch.model": "Memory Search Model", "agents.defaults.memorySearch.fallback": "Memory Search Fallback", "agents.defaults.memorySearch.local.modelPath": "Local Embedding Model Path", @@ -182,6 +317,11 @@ export const FIELD_LABELS: Record = { "memory.backend": "Memory Backend", "memory.citations": "Memory Citations Mode", "memory.qmd.command": "QMD Binary", + "memory.qmd.mcporter": "QMD MCPorter", + "memory.qmd.mcporter.enabled": "QMD MCPorter Enabled", + "memory.qmd.mcporter.serverName": "QMD MCPorter Server Name", + "memory.qmd.mcporter.startDaemon": "QMD MCPorter Start Daemon", + "memory.qmd.searchMode": "QMD Search Mode", "memory.qmd.includeDefaultMemory": "QMD Include Default Memory", "memory.qmd.paths": "QMD Extra Paths", "memory.qmd.paths.path": "QMD Path", @@ -203,8 +343,27 @@ export const FIELD_LABELS: Record = { "memory.qmd.limits.maxInjectedChars": "QMD Max Injected Chars", "memory.qmd.limits.timeoutMs": "QMD Search Timeout (ms)", "memory.qmd.scope": "QMD Surface Scope", + auth: "Auth", "auth.profiles": "Auth Profiles", "auth.order": "Auth Profile Order", + "auth.cooldowns": "Auth Cooldowns", + models: "Models", + "models.mode": "Model Catalog Mode", + "models.providers": "Model Providers", + "models.providers.*.baseUrl": "Model Provider Base URL", + "models.providers.*.apiKey": "Model Provider API Key", + "models.providers.*.auth": "Model Provider Auth Mode", + "models.providers.*.api": "Model Provider API Adapter", + "models.providers.*.headers": "Model Provider Headers", + "models.providers.*.authHeader": "Model Provider Authorization Header", + "models.providers.*.models": "Model Provider Model List", + "models.bedrockDiscovery": "Bedrock Model Discovery", + "models.bedrockDiscovery.enabled": "Bedrock Discovery Enabled", + "models.bedrockDiscovery.region": "Bedrock Discovery Region", + "models.bedrockDiscovery.providerFilter": "Bedrock Discovery Provider Filter", + "models.bedrockDiscovery.refreshInterval": "Bedrock Discovery Refresh Interval (s)", + "models.bedrockDiscovery.defaultContextWindow": "Bedrock Default Context Window", + "models.bedrockDiscovery.defaultMaxTokens": "Bedrock Default Max Tokens", "auth.cooldowns.billingBackoffHours": "Billing Backoff (hours)", "auth.cooldowns.billingBackoffHoursByProvider": "Billing Backoff Overrides", "auth.cooldowns.billingMaxHours": "Billing Backoff Cap (hours)", @@ -219,6 +378,22 @@ export const FIELD_LABELS: Record = { "agents.defaults.humanDelay.minMs": "Human Delay Min (ms)", "agents.defaults.humanDelay.maxMs": "Human Delay Max (ms)", "agents.defaults.cliBackends": "CLI Backends", + "agents.defaults.compaction": "Compaction", + "agents.defaults.compaction.mode": "Compaction Mode", + "agents.defaults.compaction.reserveTokens": "Compaction Reserve Tokens", + "agents.defaults.compaction.keepRecentTokens": "Compaction Keep Recent Tokens", + "agents.defaults.compaction.reserveTokensFloor": "Compaction Reserve Token Floor", + "agents.defaults.compaction.maxHistoryShare": "Compaction Max History Share", + "agents.defaults.compaction.memoryFlush": "Compaction Memory Flush", + "agents.defaults.compaction.memoryFlush.enabled": "Compaction Memory Flush Enabled", + "agents.defaults.compaction.memoryFlush.softThresholdTokens": + "Compaction Memory Flush Soft Threshold", + "agents.defaults.compaction.memoryFlush.prompt": "Compaction Memory Flush Prompt", + "agents.defaults.compaction.memoryFlush.systemPrompt": "Compaction Memory Flush System Prompt", + "agents.defaults.heartbeat.suppressToolErrorWarnings": "Heartbeat Suppress Tool Error Warnings", + "agents.defaults.sandbox.browser.network": "Sandbox Browser Network", + "agents.defaults.sandbox.browser.cdpSourceRange": "Sandbox Browser CDP Source Port Range", + commands: "Commands", "commands.native": "Native Commands", "commands.nativeSkills": "Native Skill Commands", "commands.text": "Text Commands", @@ -231,7 +406,10 @@ export const FIELD_LABELS: Record = { "commands.ownerAllowFrom": "Command Owners", "commands.ownerDisplay": "Owner ID Display", "commands.ownerDisplaySecret": "Owner ID Hash Secret", + "commands.allowFrom": "Command Elevated Access Rules", + ui: "UI", "ui.seamColor": "Accent Color", + "ui.assistant": "Assistant Appearance", "ui.assistant.name": "Assistant Name", "ui.assistant.avatar": "Assistant Avatar", "browser.evaluateEnabled": "Browser Evaluate Enabled", @@ -243,19 +421,174 @@ export const FIELD_LABELS: Record = { "browser.ssrfPolicy.hostnameAllowlist": "Browser Hostname Allowlist", "browser.remoteCdpTimeoutMs": "Remote CDP Timeout (ms)", "browser.remoteCdpHandshakeTimeoutMs": "Remote CDP Handshake Timeout (ms)", + session: "Session", + "session.scope": "Session Scope", "session.dmScope": "DM Session Scope", + "session.identityLinks": "Session Identity Links", + "session.resetTriggers": "Session Reset Triggers", + "session.idleMinutes": "Session Idle Minutes", + "session.reset": "Session Reset Policy", + "session.reset.mode": "Session Reset Mode", + "session.reset.atHour": "Session Daily Reset Hour", + "session.reset.idleMinutes": "Session Reset Idle Minutes", + "session.resetByType": "Session Reset by Chat Type", + "session.resetByType.direct": "Session Reset (Direct)", + "session.resetByType.dm": "Session Reset (DM Deprecated Alias)", + "session.resetByType.group": "Session Reset (Group)", + "session.resetByType.thread": "Session Reset (Thread)", + "session.resetByChannel": "Session Reset by Channel", + "session.store": "Session Store Path", + "session.typingIntervalSeconds": "Session Typing Interval (seconds)", + "session.typingMode": "Session Typing Mode", + "session.mainKey": "Session Main Key", + "session.sendPolicy": "Session Send Policy", + "session.sendPolicy.default": "Session Send Policy Default Action", + "session.sendPolicy.rules": "Session Send Policy Rules", + "session.sendPolicy.rules[].action": "Session Send Rule Action", + "session.sendPolicy.rules[].match": "Session Send Rule Match", + "session.sendPolicy.rules[].match.channel": "Session Send Rule Channel", + "session.sendPolicy.rules[].match.chatType": "Session Send Rule Chat Type", + "session.sendPolicy.rules[].match.keyPrefix": "Session Send Rule Key Prefix", + "session.sendPolicy.rules[].match.rawKeyPrefix": "Session Send Rule Raw Key Prefix", + "session.agentToAgent": "Session Agent-to-Agent", + "session.agentToAgent.maxPingPongTurns": "Agent-to-Agent Ping-Pong Turns", + "session.threadBindings": "Session Thread Bindings", "session.threadBindings.enabled": "Thread Binding Enabled", "session.threadBindings.ttlHours": "Thread Binding TTL (hours)", - "session.agentToAgent.maxPingPongTurns": "Agent-to-Agent Ping-Pong Turns", + "session.maintenance": "Session Maintenance", + "session.maintenance.mode": "Session Maintenance Mode", + "session.maintenance.pruneAfter": "Session Prune After", + "session.maintenance.pruneDays": "Session Prune Days (Deprecated)", + "session.maintenance.maxEntries": "Session Max Entries", + "session.maintenance.rotateBytes": "Session Rotate Size", + cron: "Cron", + "cron.enabled": "Cron Enabled", + "cron.store": "Cron Store Path", + "cron.maxConcurrentRuns": "Cron Max Concurrent Runs", + "cron.webhook": "Cron Legacy Webhook (Deprecated)", + "cron.webhookToken": "Cron Webhook Bearer Token", + "cron.sessionRetention": "Cron Session Retention", + hooks: "Hooks", + "hooks.enabled": "Hooks Enabled", + "hooks.path": "Hooks Endpoint Path", + "hooks.token": "Hooks Auth Token", + "hooks.defaultSessionKey": "Hooks Default Session Key", + "hooks.allowRequestSessionKey": "Hooks Allow Request Session Key", + "hooks.allowedSessionKeyPrefixes": "Hooks Allowed Session Key Prefixes", + "hooks.allowedAgentIds": "Hooks Allowed Agent IDs", + "hooks.maxBodyBytes": "Hooks Max Body Bytes", + "hooks.presets": "Hooks Presets", + "hooks.transformsDir": "Hooks Transforms Directory", + "hooks.mappings": "Hook Mappings", + "hooks.mappings[].id": "Hook Mapping ID", + "hooks.mappings[].match": "Hook Mapping Match", + "hooks.mappings[].match.path": "Hook Mapping Match Path", + "hooks.mappings[].match.source": "Hook Mapping Match Source", + "hooks.mappings[].action": "Hook Mapping Action", + "hooks.mappings[].wakeMode": "Hook Mapping Wake Mode", + "hooks.mappings[].name": "Hook Mapping Name", + "hooks.mappings[].agentId": "Hook Mapping Agent ID", + "hooks.mappings[].sessionKey": "Hook Mapping Session Key", + "hooks.mappings[].messageTemplate": "Hook Mapping Message Template", + "hooks.mappings[].textTemplate": "Hook Mapping Text Template", + "hooks.mappings[].deliver": "Hook Mapping Deliver Reply", + "hooks.mappings[].allowUnsafeExternalContent": "Hook Mapping Allow Unsafe External Content", + "hooks.mappings[].channel": "Hook Mapping Delivery Channel", + "hooks.mappings[].to": "Hook Mapping Delivery Destination", + "hooks.mappings[].model": "Hook Mapping Model Override", + "hooks.mappings[].thinking": "Hook Mapping Thinking Override", + "hooks.mappings[].timeoutSeconds": "Hook Mapping Timeout (sec)", + "hooks.mappings[].transform": "Hook Mapping Transform", + "hooks.mappings[].transform.module": "Hook Transform Module", + "hooks.mappings[].transform.export": "Hook Transform Export", + "hooks.gmail": "Gmail Hook", + "hooks.gmail.account": "Gmail Hook Account", + "hooks.gmail.label": "Gmail Hook Label", + "hooks.gmail.topic": "Gmail Hook Pub/Sub Topic", + "hooks.gmail.subscription": "Gmail Hook Subscription", + "hooks.gmail.pushToken": "Gmail Hook Push Token", + "hooks.gmail.hookUrl": "Gmail Hook Callback URL", + "hooks.gmail.includeBody": "Gmail Hook Include Body", + "hooks.gmail.maxBytes": "Gmail Hook Max Body Bytes", + "hooks.gmail.renewEveryMinutes": "Gmail Hook Renew Interval (min)", + "hooks.gmail.allowUnsafeExternalContent": "Gmail Hook Allow Unsafe External Content", + "hooks.gmail.serve": "Gmail Hook Local Server", + "hooks.gmail.serve.bind": "Gmail Hook Server Bind Address", + "hooks.gmail.serve.port": "Gmail Hook Server Port", + "hooks.gmail.serve.path": "Gmail Hook Server Path", + "hooks.gmail.tailscale": "Gmail Hook Tailscale", + "hooks.gmail.tailscale.mode": "Gmail Hook Tailscale Mode", + "hooks.gmail.tailscale.path": "Gmail Hook Tailscale Path", + "hooks.gmail.tailscale.target": "Gmail Hook Tailscale Target", + "hooks.gmail.model": "Gmail Hook Model Override", + "hooks.gmail.thinking": "Gmail Hook Thinking Override", + "hooks.internal": "Internal Hooks", + "hooks.internal.enabled": "Internal Hooks Enabled", + "hooks.internal.handlers": "Internal Hook Handlers", + "hooks.internal.handlers[].event": "Internal Hook Event", + "hooks.internal.handlers[].module": "Internal Hook Module", + "hooks.internal.handlers[].export": "Internal Hook Export", + "hooks.internal.entries": "Internal Hook Entries", + "hooks.internal.load": "Internal Hook Loader", + "hooks.internal.load.extraDirs": "Internal Hook Extra Directories", + "hooks.internal.installs": "Internal Hook Install Records", + web: "Web Channel", + "web.enabled": "Web Channel Enabled", + "web.heartbeatSeconds": "Web Channel Heartbeat Interval (sec)", + "web.reconnect": "Web Channel Reconnect Policy", + "web.reconnect.initialMs": "Web Reconnect Initial Delay (ms)", + "web.reconnect.maxMs": "Web Reconnect Max Delay (ms)", + "web.reconnect.factor": "Web Reconnect Backoff Factor", + "web.reconnect.jitter": "Web Reconnect Jitter", + "web.reconnect.maxAttempts": "Web Reconnect Max Attempts", + discovery: "Discovery", + "discovery.wideArea": "Wide-area Discovery", + "discovery.wideArea.enabled": "Wide-area Discovery Enabled", + "discovery.mdns": "mDNS Discovery", + canvasHost: "Canvas Host", + "canvasHost.enabled": "Canvas Host Enabled", + "canvasHost.root": "Canvas Host Root Directory", + "canvasHost.port": "Canvas Host Port", + "canvasHost.liveReload": "Canvas Host Live Reload", + talk: "Talk", + "talk.voiceId": "Talk Voice ID", + "talk.voiceAliases": "Talk Voice Aliases", + "talk.modelId": "Talk Model ID", + "talk.outputFormat": "Talk Output Format", + "talk.interruptOnSpeech": "Talk Interrupt on Speech", + messages: "Messages", + "messages.messagePrefix": "Inbound Message Prefix", + "messages.responsePrefix": "Outbound Response Prefix", + "messages.groupChat": "Group Chat Rules", + "messages.groupChat.mentionPatterns": "Group Mention Patterns", + "messages.groupChat.historyLimit": "Group History Limit", + "messages.queue": "Inbound Queue", + "messages.queue.mode": "Queue Mode", + "messages.queue.byChannel": "Queue Mode by Channel", + "messages.queue.debounceMs": "Queue Debounce (ms)", + "messages.queue.debounceMsByChannel": "Queue Debounce by Channel (ms)", + "messages.queue.cap": "Queue Capacity", + "messages.queue.drop": "Queue Drop Strategy", + "messages.inbound": "Inbound Debounce", "messages.suppressToolErrors": "Suppress Tool Error Warnings", "messages.ackReaction": "Ack Reaction Emoji", "messages.ackReactionScope": "Ack Reaction Scope", + "messages.removeAckAfterReply": "Remove Ack Reaction After Reply", "messages.statusReactions": "Status Reactions", "messages.statusReactions.enabled": "Enable Status Reactions", "messages.statusReactions.emojis": "Status Reaction Emojis", "messages.statusReactions.timing": "Status Reaction Timing", "messages.inbound.debounceMs": "Inbound Message Debounce (ms)", + "messages.inbound.byChannel": "Inbound Debounce by Channel (ms)", + "messages.tts": "Message Text-to-Speech", "talk.apiKey": "Talk API Key", + channels: "Channels", + "channels.defaults": "Channel Defaults", + "channels.defaults.groupPolicy": "Default Group Policy", + "channels.defaults.heartbeat": "Default Heartbeat Visibility", + "channels.defaults.heartbeat.showOk": "Heartbeat Show OK", + "channels.defaults.heartbeat.showAlerts": "Heartbeat Show Alerts", + "channels.defaults.heartbeat.useIndicator": "Heartbeat Use Indicator", "channels.whatsapp": "WhatsApp", "channels.telegram": "Telegram", "channels.telegram.customCommands": "Telegram Custom Commands", @@ -270,6 +603,9 @@ export const FIELD_LABELS: Record = { ...IRC_FIELD_LABELS, "channels.telegram.botToken": "Telegram Bot Token", "channels.telegram.dmPolicy": "Telegram DM Policy", + "channels.telegram.configWrites": "Telegram Config Writes", + "channels.telegram.commands.native": "Telegram Native Commands", + "channels.telegram.commands.nativeSkills": "Telegram Native Skill Commands", "channels.telegram.streaming": "Telegram Streaming Mode", "channels.telegram.retry.attempts": "Telegram Retry Attempts", "channels.telegram.retry.minDelayMs": "Telegram Retry Min Delay (ms)", @@ -281,11 +617,20 @@ export const FIELD_LABELS: Record = { "channels.whatsapp.dmPolicy": "WhatsApp DM Policy", "channels.whatsapp.selfChatMode": "WhatsApp Self-Phone Mode", "channels.whatsapp.debounceMs": "WhatsApp Message Debounce (ms)", + "channels.whatsapp.configWrites": "WhatsApp Config Writes", "channels.signal.dmPolicy": "Signal DM Policy", + "channels.signal.configWrites": "Signal Config Writes", "channels.imessage.dmPolicy": "iMessage DM Policy", + "channels.imessage.configWrites": "iMessage Config Writes", "channels.bluebubbles.dmPolicy": "BlueBubbles DM Policy", + "channels.msteams.configWrites": "MS Teams Config Writes", + "channels.irc.configWrites": "IRC Config Writes", "channels.discord.dmPolicy": "Discord DM Policy", "channels.discord.dm.policy": "Discord DM Policy", + "channels.discord.configWrites": "Discord Config Writes", + "channels.discord.proxy": "Discord Proxy URL", + "channels.discord.commands.native": "Discord Native Commands", + "channels.discord.commands.nativeSkills": "Discord Native Skill Commands", "channels.discord.streaming": "Discord Streaming Mode", "channels.discord.streamMode": "Discord Stream Mode (Legacy)", "channels.discord.draftChunk.minChars": "Discord Draft Chunk Min Chars", @@ -304,6 +649,7 @@ export const FIELD_LABELS: Record = { "channels.discord.intents.guildMembers": "Discord Guild Members Intent", "channels.discord.voice.enabled": "Discord Voice Enabled", "channels.discord.voice.autoJoin": "Discord Voice Auto-Join", + "channels.discord.voice.tts": "Discord Voice Text-to-Speech", "channels.discord.pluralkit.enabled": "Discord PluralKit Enabled", "channels.discord.pluralkit.token": "Discord PluralKit Token", "channels.discord.activity": "Discord Presence Activity", @@ -312,6 +658,9 @@ export const FIELD_LABELS: Record = { "channels.discord.activityUrl": "Discord Presence Activity URL", "channels.slack.dm.policy": "Slack DM Policy", "channels.slack.dmPolicy": "Slack DM Policy", + "channels.slack.configWrites": "Slack Config Writes", + "channels.slack.commands.native": "Slack Native Commands", + "channels.slack.commands.nativeSkills": "Slack Native Skill Commands", "channels.slack.allowBots": "Slack Allow Bot Messages", "channels.discord.token": "Discord Bot Token", "channels.slack.botToken": "Slack Bot Token", @@ -326,6 +675,7 @@ export const FIELD_LABELS: Record = { "channels.slack.thread.initialHistoryLimit": "Slack Thread Initial History Limit", "channels.mattermost.botToken": "Mattermost Bot Token", "channels.mattermost.baseUrl": "Mattermost Base URL", + "channels.mattermost.configWrites": "Mattermost Config Writes", "channels.mattermost.chatmode": "Mattermost Chat Mode", "channels.mattermost.oncharPrefixes": "Mattermost Onchar Prefixes", "channels.mattermost.requireMention": "Mattermost Require Mention", @@ -333,15 +683,23 @@ export const FIELD_LABELS: Record = { "channels.imessage.cliPath": "iMessage CLI Path", "agents.list[].skills": "Agent Skill Filter", "agents.list[].identity.avatar": "Agent Avatar", + "agents.list[].heartbeat.suppressToolErrorWarnings": + "Agent Heartbeat Suppress Tool Error Warnings", + "agents.list[].sandbox.browser.network": "Agent Sandbox Browser Network", + "agents.list[].sandbox.browser.cdpSourceRange": "Agent Sandbox Browser CDP Source Port Range", "discovery.mdns.mode": "mDNS Discovery Mode", + plugins: "Plugins", "plugins.enabled": "Enable Plugins", "plugins.allow": "Plugin Allowlist", "plugins.deny": "Plugin Denylist", + "plugins.load": "Plugin Loader", "plugins.load.paths": "Plugin Load Paths", "plugins.slots": "Plugin Slots", "plugins.slots.memory": "Memory Plugin", "plugins.entries": "Plugin Entries", "plugins.entries.*.enabled": "Plugin Enabled", + "plugins.entries.*.apiKey": "Plugin API Key", + "plugins.entries.*.env": "Plugin Environment Variables", "plugins.entries.*.config": "Plugin Config", "plugins.installs": "Plugin Install Records", "plugins.installs.*.source": "Plugin Install Source", diff --git a/src/config/schema.tags.test.ts b/src/config/schema.tags.test.ts new file mode 100644 index 00000000000..5dd0e5d745d --- /dev/null +++ b/src/config/schema.tags.test.ts @@ -0,0 +1,46 @@ +import { describe, expect, it } from "vitest"; +import { buildConfigSchema } from "./schema.js"; +import { applyDerivedTags, CONFIG_TAGS, deriveTagsForPath } from "./schema.tags.js"; + +describe("config schema tags", () => { + it("derives security/auth tags for credential paths", () => { + const tags = deriveTagsForPath("gateway.auth.token"); + expect(tags).toContain("security"); + expect(tags).toContain("auth"); + }); + + it("derives tools/performance tags for web fetch timeout paths", () => { + const tags = deriveTagsForPath("tools.web.fetch.timeoutSeconds"); + expect(tags).toContain("tools"); + expect(tags).toContain("performance"); + }); + + it("keeps tags in the allowed taxonomy", () => { + const withTags = applyDerivedTags({ + "gateway.auth.token": {}, + "tools.web.fetch.timeoutSeconds": {}, + "channels.slack.accounts.*.token": {}, + }); + const allowed = new Set(CONFIG_TAGS); + for (const hint of Object.values(withTags)) { + for (const tag of hint.tags ?? []) { + expect(allowed.has(tag)).toBe(true); + } + } + }); + + it("covers core/built-in config paths with tags", () => { + const schema = buildConfigSchema(); + const allowed = new Set(CONFIG_TAGS); + for (const [key, hint] of Object.entries(schema.uiHints)) { + if (!key.includes(".")) { + continue; + } + const tags = hint.tags ?? []; + expect(tags.length, `expected tags for ${key}`).toBeGreaterThan(0); + for (const tag of tags) { + expect(allowed.has(tag), `unexpected tag ${tag} on ${key}`).toBe(true); + } + } + }); +}); diff --git a/src/config/schema.tags.ts b/src/config/schema.tags.ts new file mode 100644 index 00000000000..6e5241b6e9e --- /dev/null +++ b/src/config/schema.tags.ts @@ -0,0 +1,180 @@ +import type { ConfigUiHint, ConfigUiHints } from "./schema.hints.js"; + +export const CONFIG_TAGS = [ + "security", + "auth", + "network", + "access", + "privacy", + "observability", + "performance", + "reliability", + "storage", + "models", + "media", + "automation", + "channels", + "tools", + "advanced", +] as const; + +export type ConfigTag = (typeof CONFIG_TAGS)[number]; + +const TAG_PRIORITY: Record = { + security: 0, + auth: 1, + access: 2, + network: 3, + privacy: 4, + observability: 5, + reliability: 6, + performance: 7, + storage: 8, + models: 9, + media: 10, + automation: 11, + channels: 12, + tools: 13, + advanced: 14, +}; + +const TAG_OVERRIDES: Record = { + "gateway.auth.token": ["security", "auth", "access", "network"], + "gateway.auth.password": ["security", "auth", "access", "network"], + "gateway.controlUi.dangerouslyDisableDeviceAuth": ["security", "access", "network", "advanced"], + "gateway.controlUi.allowInsecureAuth": ["security", "access", "network", "advanced"], + "tools.exec.applyPatch.workspaceOnly": ["tools", "security", "access", "advanced"], +}; + +const PREFIX_RULES: Array<{ prefix: string; tags: ConfigTag[] }> = [ + { prefix: "channels.", tags: ["channels", "network"] }, + { prefix: "tools.", tags: ["tools"] }, + { prefix: "gateway.", tags: ["network"] }, + { prefix: "nodehost.", tags: ["network"] }, + { prefix: "discovery.", tags: ["network"] }, + { prefix: "auth.", tags: ["auth", "access"] }, + { prefix: "memory.", tags: ["storage"] }, + { prefix: "models.", tags: ["models"] }, + { prefix: "diagnostics.", tags: ["observability"] }, + { prefix: "logging.", tags: ["observability"] }, + { prefix: "cron.", tags: ["automation"] }, + { prefix: "talk.", tags: ["media"] }, + { prefix: "audio.", tags: ["media"] }, +]; + +const KEYWORD_RULES: Array<{ pattern: RegExp; tags: ConfigTag[] }> = [ + { pattern: /(token|password|secret|api[_.-]?key|tlsfingerprint)/i, tags: ["security", "auth"] }, + { pattern: /(allow|deny|owner|permission|policy|access)/i, tags: ["access"] }, + { pattern: /(timeout|debounce|interval|concurrency|max|limit|cachettl)/i, tags: ["performance"] }, + { pattern: /(retry|backoff|fallback|circuit|health|reload|probe)/i, tags: ["reliability"] }, + { pattern: /(path|dir|file|store|db|session|cache)/i, tags: ["storage"] }, + { pattern: /(telemetry|trace|metrics|logs|diagnostic)/i, tags: ["observability"] }, + { pattern: /(experimental|dangerously|insecure)/i, tags: ["advanced", "security"] }, + { pattern: /(privacy|redact|sanitize|anonym|pseudonym)/i, tags: ["privacy"] }, +]; + +const MODEL_PATH_PATTERN = /(^|\.)(model|models|modelid|imagemodel)(\.|$)/i; +const MEDIA_PATH_PATTERN = /(tools\.media\.|^audio\.|^talk\.|image|video|stt|tts)/i; +const AUTOMATION_PATH_PATTERN = /(cron|heartbeat|schedule|onstart|watchdebounce)/i; +const AUTH_KEYWORD_PATTERN = /(token|password|secret|api[_.-]?key|credential|oauth)/i; + +function normalizeTag(tag: string): ConfigTag | null { + const normalized = tag.trim().toLowerCase() as ConfigTag; + return CONFIG_TAGS.includes(normalized) ? normalized : null; +} + +function normalizeTags(tags: ReadonlyArray): ConfigTag[] { + const out = new Set(); + for (const tag of tags) { + const normalized = normalizeTag(tag); + if (normalized) { + out.add(normalized); + } + } + return [...out].toSorted((a, b) => TAG_PRIORITY[a] - TAG_PRIORITY[b]); +} + +function patternToRegExp(pattern: string): RegExp { + const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^.]+"); + return new RegExp(`^${escaped}$`, "i"); +} + +function resolveOverride(path: string): ConfigTag[] | undefined { + const direct = TAG_OVERRIDES[path]; + if (direct) { + return direct; + } + for (const [pattern, tags] of Object.entries(TAG_OVERRIDES)) { + if (!pattern.includes("*")) { + continue; + } + if (patternToRegExp(pattern).test(path)) { + return tags; + } + } + return undefined; +} + +function addTags(set: Set, tags: ReadonlyArray): void { + for (const tag of tags) { + set.add(tag); + } +} + +export function deriveTagsForPath(path: string, hint?: ConfigUiHint): ConfigTag[] { + const lowerPath = path.toLowerCase(); + const override = resolveOverride(path); + if (override) { + return normalizeTags(override); + } + + const tags = new Set(); + for (const rule of PREFIX_RULES) { + if (lowerPath.startsWith(rule.prefix)) { + addTags(tags, rule.tags); + } + } + + for (const rule of KEYWORD_RULES) { + if (rule.pattern.test(path)) { + addTags(tags, rule.tags); + } + } + + if (MODEL_PATH_PATTERN.test(path)) { + tags.add("models"); + } + if (MEDIA_PATH_PATTERN.test(path)) { + tags.add("media"); + } + if (AUTOMATION_PATH_PATTERN.test(path)) { + tags.add("automation"); + } + + if (hint?.sensitive) { + tags.add("security"); + if (AUTH_KEYWORD_PATTERN.test(path)) { + tags.add("auth"); + } + } + if (hint?.advanced) { + tags.add("advanced"); + } + + if (tags.size === 0) { + tags.add("advanced"); + } + + return normalizeTags([...tags]); +} + +export function applyDerivedTags(hints: ConfigUiHints): ConfigUiHints { + const next: ConfigUiHints = {}; + for (const [path, hint] of Object.entries(hints)) { + const existingTags = Array.isArray(hint?.tags) ? hint.tags : []; + const derivedTags = deriveTagsForPath(path, hint); + const tags = normalizeTags([...derivedTags, ...existingTags]); + next[path] = { ...hint, tags }; + } + return next; +} diff --git a/src/config/schema.ts b/src/config/schema.ts index 74dc00f784d..d2add2c96a1 100644 --- a/src/config/schema.ts +++ b/src/config/schema.ts @@ -2,6 +2,7 @@ import { CHANNEL_IDS } from "../channels/registry.js"; import { VERSION } from "../version.js"; import type { ConfigUiHint, ConfigUiHints } from "./schema.hints.js"; import { applySensitiveHints, buildBaseHints, mapSensitivePaths } from "./schema.hints.js"; +import { applyDerivedTags } from "./schema.tags.js"; import { OpenClawSchema } from "./zod-schema.js"; export type { ConfigUiHint, ConfigUiHints } from "./schema.hints.js"; @@ -75,7 +76,7 @@ export type PluginUiMetadata = { description?: string; configUiHints?: Record< string, - Pick + Pick >; configSchema?: JsonSchemaNode; }; @@ -327,7 +328,7 @@ function buildBaseConfigSchema(): ConfigSchemaResponse { unrepresentable: "any", }); schema.title = "OpenClawConfig"; - const hints = mapSensitivePaths(OpenClawSchema, "", buildBaseHints()); + const hints = applyDerivedTags(mapSensitivePaths(OpenClawSchema, "", buildBaseHints())); const next = { schema: stripChannelSchema(schema), uiHints: hints, @@ -357,7 +358,9 @@ export function buildConfigSchema(params?: { plugins, channels, ); - const mergedHints = applySensitiveHints(mergedWithoutSensitiveHints, extensionHintKeys); + const mergedHints = applyDerivedTags( + applySensitiveHints(mergedWithoutSensitiveHints, extensionHintKeys), + ); const mergedSchema = applyChannelSchemas(applyPluginSchemas(base.schema, plugins), channels); return { ...base, diff --git a/src/gateway/protocol/schema/config.ts b/src/gateway/protocol/schema/config.ts index 78587d34abe..150cd6b4ad1 100644 --- a/src/gateway/protocol/schema/config.ts +++ b/src/gateway/protocol/schema/config.ts @@ -41,6 +41,7 @@ export const ConfigUiHintSchema = Type.Object( { label: Type.Optional(Type.String()), help: Type.Optional(Type.String()), + tags: Type.Optional(Type.Array(Type.String())), group: Type.Optional(Type.String()), order: Type.Optional(Type.Integer()), advanced: Type.Optional(Type.Boolean()), diff --git a/src/gateway/server/ws-connection/auth-context.test.ts b/src/gateway/server/ws-connection/auth-context.test.ts index a598a963fd8..130b0566457 100644 --- a/src/gateway/server/ws-connection/auth-context.test.ts +++ b/src/gateway/server/ws-connection/auth-context.test.ts @@ -2,6 +2,8 @@ import { describe, expect, it, vi } from "vitest"; import type { AuthRateLimiter } from "../../auth-rate-limit.js"; import { resolveConnectAuthDecision, type ConnectAuthState } from "./auth-context.js"; +type VerifyDeviceTokenFn = Parameters[0]["verifyDeviceToken"]; + function createRateLimiter(params?: { allowed?: boolean; retryAfterMs?: number }): { limiter: AuthRateLimiter; reset: ReturnType; @@ -35,7 +37,7 @@ function createBaseState(overrides?: Partial): ConnectAuthStat } async function resolveDeviceTokenDecision(params: { - verifyDeviceToken: ReturnType; + verifyDeviceToken: VerifyDeviceTokenFn; stateOverrides?: Partial; rateLimiter?: AuthRateLimiter; clientIp?: string; @@ -54,7 +56,7 @@ async function resolveDeviceTokenDecision(params: { describe("resolveConnectAuthDecision", () => { it("keeps shared-secret mismatch when fallback device-token check fails", async () => { - const verifyDeviceToken = vi.fn(async () => ({ ok: false })); + const verifyDeviceToken = vi.fn(async () => ({ ok: false })); const decision = await resolveConnectAuthDecision({ state: createBaseState(), hasDeviceIdentity: true, @@ -69,7 +71,7 @@ describe("resolveConnectAuthDecision", () => { }); it("reports explicit device-token mismatches as device_token_mismatch", async () => { - const verifyDeviceToken = vi.fn(async () => ({ ok: false })); + const verifyDeviceToken = vi.fn(async () => ({ ok: false })); const decision = await resolveConnectAuthDecision({ state: createBaseState({ deviceTokenCandidateSource: "explicit-device-token", @@ -86,7 +88,7 @@ describe("resolveConnectAuthDecision", () => { it("accepts valid device tokens and marks auth method as device-token", async () => { const rateLimiter = createRateLimiter(); - const verifyDeviceToken = vi.fn(async () => ({ ok: true })); + const verifyDeviceToken = vi.fn(async () => ({ ok: true })); const decision = await resolveDeviceTokenDecision({ verifyDeviceToken, rateLimiter: rateLimiter.limiter, @@ -100,7 +102,7 @@ describe("resolveConnectAuthDecision", () => { it("returns rate-limited auth result without verifying device token", async () => { const rateLimiter = createRateLimiter({ allowed: false, retryAfterMs: 60_000 }); - const verifyDeviceToken = vi.fn(async () => ({ ok: true })); + const verifyDeviceToken = vi.fn(async () => ({ ok: true })); const decision = await resolveDeviceTokenDecision({ verifyDeviceToken, rateLimiter: rateLimiter.limiter, @@ -113,7 +115,7 @@ describe("resolveConnectAuthDecision", () => { }); it("returns the original decision when device fallback does not apply", async () => { - const verifyDeviceToken = vi.fn(async () => ({ ok: true })); + const verifyDeviceToken = vi.fn(async () => ({ ok: true })); const decision = await resolveConnectAuthDecision({ state: createBaseState({ authResult: { ok: true, method: "token" }, diff --git a/src/plugins/types.ts b/src/plugins/types.ts index 5d54a9a500d..2f3ea097ed2 100644 --- a/src/plugins/types.ts +++ b/src/plugins/types.ts @@ -29,6 +29,7 @@ export type PluginLogger = { export type PluginConfigUiHint = { label?: string; help?: string; + tags?: string[]; advanced?: boolean; sensitive?: boolean; placeholder?: string; diff --git a/src/slack/monitor/replies.ts b/src/slack/monitor/replies.ts index 5fa1cb90903..38ccc638dfd 100644 --- a/src/slack/monitor/replies.ts +++ b/src/slack/monitor/replies.ts @@ -72,12 +72,19 @@ export function resolveSlackThreadTs(params: { incomingThreadTs: string | undefined; messageTs: string | undefined; hasReplied: boolean; + isThreadReply?: boolean; }): string | undefined { + const isThreadReply = + params.isThreadReply ?? + (typeof params.incomingThreadTs === "string" && + params.incomingThreadTs.length > 0 && + params.incomingThreadTs !== params.messageTs); const planner = createSlackReplyReferencePlanner({ replyToMode: params.replyToMode, incomingThreadTs: params.incomingThreadTs, messageTs: params.messageTs, hasReplied: params.hasReplied, + isThreadReply, }); return planner.use(); } diff --git a/src/tui/tui-command-handlers.test.ts b/src/tui/tui-command-handlers.test.ts index 8e20a2c0fb2..f9e4ca3e40f 100644 --- a/src/tui/tui-command-handlers.test.ts +++ b/src/tui/tui-command-handlers.test.ts @@ -59,13 +59,13 @@ function createHarness(params?: { describe("tui command handlers", () => { it("renders the sending indicator before chat.send resolves", async () => { - let resolveSend: ((value: { runId: string }) => void) | null = null; - const sendChat = vi.fn( - () => - new Promise<{ runId: string }>((resolve) => { - resolveSend = resolve; - }), - ); + let resolveSend: (value: { runId: string }) => void = () => { + throw new Error("sendChat promise resolver was not initialized"); + }; + const sendPromise = new Promise<{ runId: string }>((resolve) => { + resolveSend = (value) => resolve(value); + }); + const sendChat = vi.fn(() => sendPromise); const setActivityStatus = vi.fn(); const { handleCommand, requestRender } = createHarness({ @@ -81,10 +81,7 @@ describe("tui command handlers", () => { const renderOrders = requestRender.mock.invocationCallOrder; expect(renderOrders.some((order) => order > sendingOrder)).toBe(true); - if (typeof resolveSend !== "function") { - throw new Error("expected sendChat to be pending"); - } - (resolveSend as (value: { runId: string }) => void)({ runId: "r1" }); + resolveSend({ runId: "r1" }); await pending; expect(setActivityStatus).toHaveBeenCalledWith("waiting"); }); diff --git a/test/media-understanding.auto.test.ts b/test/media-understanding.auto.test.ts index a98c05053e1..4aa1e1a6623 100644 --- a/test/media-understanding.auto.test.ts +++ b/test/media-understanding.auto.test.ts @@ -30,12 +30,24 @@ const envSnapshot = () => ({ PATH: process.env.PATH, SHERPA_ONNX_MODEL_DIR: process.env.SHERPA_ONNX_MODEL_DIR, WHISPER_CPP_MODEL: process.env.WHISPER_CPP_MODEL, + OPENAI_API_KEY: process.env.OPENAI_API_KEY, + GROQ_API_KEY: process.env.GROQ_API_KEY, + DEEPGRAM_API_KEY: process.env.DEEPGRAM_API_KEY, + GEMINI_API_KEY: process.env.GEMINI_API_KEY, + OPENCLAW_AGENT_DIR: process.env.OPENCLAW_AGENT_DIR, + PI_CODING_AGENT_DIR: process.env.PI_CODING_AGENT_DIR, }); const restoreEnv = (snapshot: ReturnType) => { process.env.PATH = snapshot.PATH; process.env.SHERPA_ONNX_MODEL_DIR = snapshot.SHERPA_ONNX_MODEL_DIR; process.env.WHISPER_CPP_MODEL = snapshot.WHISPER_CPP_MODEL; + process.env.OPENAI_API_KEY = snapshot.OPENAI_API_KEY; + process.env.GROQ_API_KEY = snapshot.GROQ_API_KEY; + process.env.DEEPGRAM_API_KEY = snapshot.DEEPGRAM_API_KEY; + process.env.GEMINI_API_KEY = snapshot.GEMINI_API_KEY; + process.env.OPENCLAW_AGENT_DIR = snapshot.OPENCLAW_AGENT_DIR; + process.env.PI_CODING_AGENT_DIR = snapshot.PI_CODING_AGENT_DIR; }; const withEnvSnapshot = async (run: () => Promise): Promise => { @@ -176,9 +188,16 @@ describe("media understanding auto-detect (e2e)", () => { it("skips auto-detect when no supported binaries are available", async () => { await withEnvSnapshot(async () => { const emptyBinDir = await createTrackedTempDir(tempPaths, "openclaw-bin-empty-"); + const isolatedAgentDir = await createTrackedTempDir(tempPaths, "openclaw-agent-empty-"); process.env.PATH = emptyBinDir; delete process.env.SHERPA_ONNX_MODEL_DIR; delete process.env.WHISPER_CPP_MODEL; + delete process.env.OPENAI_API_KEY; + delete process.env.GROQ_API_KEY; + delete process.env.DEEPGRAM_API_KEY; + delete process.env.GEMINI_API_KEY; + process.env.OPENCLAW_AGENT_DIR = isolatedAgentDir; + process.env.PI_CODING_AGENT_DIR = isolatedAgentDir; const filePath = await createTrackedTempMedia(tempPaths, ".wav"); const ctx: MsgContext = { diff --git a/ui/src/styles/config.css b/ui/src/styles/config.css index ec4003a1244..c357b025a5e 100644 --- a/ui/src/styles/config.css +++ b/ui/src/styles/config.css @@ -53,14 +53,19 @@ /* Search */ .config-search { - position: relative; - padding: 14px; + display: grid; + gap: 6px; + padding: 12px 14px 10px; border-bottom: 1px solid var(--border); } +.config-search__input-row { + position: relative; +} + .config-search__icon { position: absolute; - left: 28px; + left: 14px; top: 50%; transform: translateY(-50%); width: 16px; @@ -103,7 +108,7 @@ .config-search__clear { position: absolute; - right: 22px; + right: 8px; top: 50%; transform: translateY(-50%); width: 22px; @@ -128,6 +133,131 @@ color: var(--text); } +.config-search__hint { + display: grid; + gap: 6px; +} + +.config-search__hint-label { + font-size: 10px; + font-weight: 600; + color: var(--muted); + text-transform: uppercase; + letter-spacing: 0.03em; + white-space: nowrap; +} + +.config-search__tag-picker { + border: 1px solid var(--border); + border-radius: var(--radius-md); + background: var(--bg-elevated); + transition: + border-color var(--duration-fast) ease, + box-shadow var(--duration-fast) ease, + background var(--duration-fast) ease; +} + +.config-search__tag-picker[open] { + border-color: var(--accent); + box-shadow: var(--focus-ring); + background: var(--bg-hover); +} + +:root[data-theme="light"] .config-search__tag-picker { + background: white; +} + +.config-search__tag-trigger { + list-style: none; + display: flex; + align-items: center; + justify-content: space-between; + gap: 8px; + min-height: 30px; + padding: 6px 8px; + cursor: pointer; +} + +.config-search__tag-trigger::-webkit-details-marker { + display: none; +} + +.config-search__tag-placeholder { + font-size: 11px; + color: var(--muted); +} + +.config-search__tag-chips { + display: flex; + align-items: center; + gap: 6px; + flex-wrap: wrap; + min-width: 0; +} + +.config-search__tag-chip { + display: inline-flex; + align-items: center; + border: 1px solid var(--border); + border-radius: var(--radius-full); + padding: 2px 7px; + font-size: 10px; + font-weight: 500; + color: var(--text); + background: var(--bg); +} + +.config-search__tag-chip--count { + color: var(--muted); +} + +.config-search__tag-caret { + color: var(--muted); + font-size: 12px; + line-height: 1; +} + +.config-search__tag-picker[open] .config-search__tag-caret { + transform: rotate(180deg); +} + +.config-search__tag-menu { + max-height: 104px; + overflow-y: auto; + border-top: 1px solid var(--border); + padding: 6px; + display: grid; + gap: 6px; +} + +.config-search__tag-option { + display: block; + width: 100%; + border: 1px solid transparent; + border-radius: var(--radius-sm); + padding: 6px 8px; + background: transparent; + color: var(--muted); + font-size: 11px; + text-align: left; + cursor: pointer; + transition: + background var(--duration-fast) ease, + color var(--duration-fast) ease, + border-color var(--duration-fast) ease; +} + +.config-search__tag-option:hover { + background: var(--bg-hover); + color: var(--text); +} + +.config-search__tag-option.active { + background: var(--accent-subtle); + color: var(--accent); + border-color: color-mix(in srgb, var(--accent) 34%, transparent); +} + /* Navigation */ .config-nav { flex: 1; @@ -536,7 +666,7 @@ .config-form--modern { display: grid; - gap: 26px; + gap: 20px; } .config-section-card { @@ -603,7 +733,7 @@ } .config-section-card__content { - padding: 22px; + padding: 18px; } /* =========================================== @@ -612,12 +742,16 @@ .cfg-fields { display: grid; - gap: 22px; + gap: 14px; +} + +.cfg-fields--inline { + gap: 10px; } .cfg-field { display: grid; - gap: 8px; + gap: 6px; } .cfg-field--error { @@ -639,6 +773,28 @@ line-height: 1.45; } +.cfg-tags { + display: flex; + flex-wrap: wrap; + gap: 6px; +} + +.cfg-tag { + display: inline-flex; + align-items: center; + border: 1px solid var(--border); + border-radius: var(--radius-full); + padding: 2px 8px; + font-size: 11px; + color: var(--muted); + background: var(--bg-elevated); + white-space: nowrap; +} + +:root[data-theme="light"] .cfg-tag { + background: white; +} + .cfg-field__error { font-size: 12px; color: var(--danger); @@ -989,22 +1145,25 @@ .cfg-object { border: 1px solid var(--border); border-radius: var(--radius-lg); - background: var(--bg-accent); + background: transparent; overflow: hidden; } :root[data-theme="light"] .cfg-object { - background: white; + background: transparent; } .cfg-object__header { display: flex; align-items: center; justify-content: space-between; - padding: 14px 18px; + padding: 10px 12px; cursor: pointer; list-style: none; - transition: background var(--duration-fast) ease; + transition: + background var(--duration-fast) ease, + border-color var(--duration-fast) ease; + border-radius: var(--radius-md); } .cfg-object__header:hover { @@ -1021,6 +1180,12 @@ color: var(--text); } +.cfg-object__title-wrap { + display: grid; + gap: 6px; + min-width: 0; +} + .cfg-object__chevron { width: 18px; height: 18px; @@ -1038,16 +1203,16 @@ } .cfg-object__help { - padding: 0 18px 14px; + padding: 0 12px 10px; font-size: 12px; color: var(--muted); - border-bottom: 1px solid var(--border); } .cfg-object__content { - padding: 18px; + padding: 12px; display: grid; - gap: 18px; + gap: 12px; + border-top: 1px solid var(--border); } /* Array */ @@ -1061,7 +1226,7 @@ display: flex; align-items: center; gap: 14px; - padding: 14px 18px; + padding: 10px 12px; background: var(--bg-accent); border-bottom: 1px solid var(--border); } @@ -1071,12 +1236,18 @@ } .cfg-array__label { - flex: 1; font-size: 14px; font-weight: 600; color: var(--text); } +.cfg-array__title { + flex: 1; + min-width: 0; + display: grid; + gap: 6px; +} + .cfg-array__count { font-size: 12px; color: var(--muted); @@ -1124,7 +1295,7 @@ } .cfg-array__help { - padding: 12px 18px; + padding: 10px 12px; font-size: 12px; color: var(--muted); border-bottom: 1px solid var(--border); @@ -1151,7 +1322,7 @@ display: flex; align-items: center; justify-content: space-between; - padding: 12px 18px; + padding: 10px 12px; background: var(--bg-accent); border-bottom: 1px solid var(--border); } @@ -1200,7 +1371,7 @@ } .cfg-array__item-content { - padding: 18px; + padding: 12px; } /* Map (custom entries) */ @@ -1215,7 +1386,7 @@ align-items: center; justify-content: space-between; gap: 14px; - padding: 14px 18px; + padding: 10px 12px; background: var(--bg-accent); border-bottom: 1px solid var(--border); } @@ -1268,15 +1439,28 @@ .cfg-map__items { display: grid; - gap: 10px; - padding: 14px; + gap: 8px; + padding: 10px 12px 12px; } .cfg-map__item { display: grid; - grid-template-columns: 150px 1fr auto; - gap: 10px; - align-items: start; + gap: 8px; + padding: 10px; + border: 1px solid var(--border); + border-radius: var(--radius-md); + background: var(--bg-accent); +} + +:root[data-theme="light"] .cfg-map__item { + background: white; +} + +.cfg-map__item-header { + display: grid; + grid-template-columns: minmax(0, 300px) auto; + gap: 8px; + align-items: center; } .cfg-map__item-key { @@ -1287,9 +1471,13 @@ min-width: 0; } +.cfg-map__item-value > .cfg-fields { + gap: 10px; +} + .cfg-map__item-remove { - width: 34px; - height: 34px; + width: 32px; + height: 32px; display: flex; align-items: center; justify-content: center; @@ -1410,6 +1598,10 @@ gap: 10px; } + .cfg-map__item-header { + grid-template-columns: 1fr auto; + } + .cfg-map__item-remove { justify-self: end; } diff --git a/ui/src/ui/config-form.browser.test.ts b/ui/src/ui/config-form.browser.test.ts index 292c5780b35..6c131d40672 100644 --- a/ui/src/ui/config-form.browser.test.ts +++ b/ui/src/ui/config-form.browser.test.ts @@ -197,6 +197,113 @@ describe("config form renderer", () => { expect(container.textContent).toContain("Plugin Enabled"); }); + it("renders tags from uiHints metadata", () => { + const onPatch = vi.fn(); + const container = document.createElement("div"); + const analysis = analyzeConfigSchema(rootSchema); + render( + renderConfigForm({ + schema: analysis.schema, + uiHints: { + "gateway.auth.token": { tags: ["security", "secret"] }, + }, + unsupportedPaths: analysis.unsupportedPaths, + value: {}, + onPatch, + }), + container, + ); + + const tags = Array.from(container.querySelectorAll(".cfg-tag")).map((node) => + node.textContent?.trim(), + ); + expect(tags).toContain("security"); + expect(tags).toContain("secret"); + }); + + it("filters by tag query", () => { + const onPatch = vi.fn(); + const container = document.createElement("div"); + const analysis = analyzeConfigSchema(rootSchema); + render( + renderConfigForm({ + schema: analysis.schema, + uiHints: { + "gateway.auth.token": { tags: ["security"] }, + }, + unsupportedPaths: analysis.unsupportedPaths, + value: {}, + searchQuery: "tag:security", + onPatch, + }), + container, + ); + + expect(container.textContent).toContain("Gateway"); + expect(container.textContent).toContain("Token"); + expect(container.textContent).not.toContain("Allow From"); + expect(container.textContent).not.toContain("Mode"); + }); + + it("does not treat plain text as tag filter", () => { + const onPatch = vi.fn(); + const container = document.createElement("div"); + const analysis = analyzeConfigSchema(rootSchema); + render( + renderConfigForm({ + schema: analysis.schema, + uiHints: { + "gateway.auth.token": { tags: ["security"] }, + }, + unsupportedPaths: analysis.unsupportedPaths, + value: {}, + searchQuery: "security", + onPatch, + }), + container, + ); + + expect(container.textContent).toContain('No settings match "security"'); + }); + + it("requires both text and tag when combined", () => { + const onPatch = vi.fn(); + const container = document.createElement("div"); + const analysis = analyzeConfigSchema(rootSchema); + render( + renderConfigForm({ + schema: analysis.schema, + uiHints: { + "gateway.auth.token": { tags: ["security"] }, + }, + unsupportedPaths: analysis.unsupportedPaths, + value: {}, + searchQuery: "token tag:security", + onPatch, + }), + container, + ); + + expect(container.textContent).toContain("Token"); + expect(container.textContent).not.toContain('No settings match "token tag:security"'); + + const noMatchContainer = document.createElement("div"); + render( + renderConfigForm({ + schema: analysis.schema, + uiHints: { + "gateway.auth.token": { tags: ["security"] }, + }, + unsupportedPaths: analysis.unsupportedPaths, + value: {}, + searchQuery: "mode tag:security", + onPatch, + }), + noMatchContainer, + ); + expect(noMatchContainer.textContent).toContain('No settings match "mode tag:security"'); + }); + it("flags unsupported unions", () => { const schema = { type: "object", diff --git a/ui/src/ui/types.ts b/ui/src/ui/types.ts index 307bae9388f..4413c23a58e 100644 --- a/ui/src/ui/types.ts +++ b/ui/src/ui/types.ts @@ -286,6 +286,7 @@ export type ConfigSnapshot = { export type ConfigUiHint = { label?: string; help?: string; + tags?: string[]; group?: string; order?: number; advanced?: boolean; diff --git a/ui/src/ui/views/config-form.node.ts b/ui/src/ui/views/config-form.node.ts index cd567d5e662..bd02be896ea 100644 --- a/ui/src/ui/views/config-form.node.ts +++ b/ui/src/ui/views/config-form.node.ts @@ -9,7 +9,7 @@ import { type JsonSchema, } from "./config-form.shared.ts"; -const META_KEYS = new Set(["title", "description", "default", "nullable"]); +const META_KEYS = new Set(["title", "description", "default", "nullable", "tags", "x-tags"]); function isAnySchema(schema: JsonSchema): boolean { const keys = Object.keys(schema ?? {}).filter((key) => !META_KEYS.has(key)); @@ -94,6 +94,234 @@ const icons = { `, }; +type FieldMeta = { + label: string; + help?: string; + tags: string[]; +}; + +export type ConfigSearchCriteria = { + text: string; + tags: string[]; +}; + +function hasSearchCriteria(criteria: ConfigSearchCriteria | undefined): boolean { + return Boolean(criteria && (criteria.text.length > 0 || criteria.tags.length > 0)); +} + +export function parseConfigSearchQuery(query: string): ConfigSearchCriteria { + const tags: string[] = []; + const seen = new Set(); + const raw = query.trim(); + const stripped = raw.replace(/(^|\s)tag:([^\s]+)/gi, (_, leading: string, token: string) => { + const normalized = token.trim().toLowerCase(); + if (normalized && !seen.has(normalized)) { + seen.add(normalized); + tags.push(normalized); + } + return leading; + }); + return { + text: stripped.trim().toLowerCase(), + tags, + }; +} + +function normalizeTags(raw: unknown): string[] { + if (!Array.isArray(raw)) { + return []; + } + const seen = new Set(); + const tags: string[] = []; + for (const value of raw) { + if (typeof value !== "string") { + continue; + } + const tag = value.trim(); + if (!tag) { + continue; + } + const key = tag.toLowerCase(); + if (seen.has(key)) { + continue; + } + seen.add(key); + tags.push(tag); + } + return tags; +} + +function resolveFieldMeta( + path: Array, + schema: JsonSchema, + hints: ConfigUiHints, +): FieldMeta { + const hint = hintForPath(path, hints); + const label = hint?.label ?? schema.title ?? humanize(String(path.at(-1))); + const help = hint?.help ?? schema.description; + const schemaTags = normalizeTags(schema["x-tags"] ?? schema.tags); + const hintTags = normalizeTags(hint?.tags); + return { + label, + help, + tags: hintTags.length > 0 ? hintTags : schemaTags, + }; +} + +function matchesText(text: string, candidates: Array): boolean { + if (!text) { + return true; + } + for (const candidate of candidates) { + if (candidate && candidate.toLowerCase().includes(text)) { + return true; + } + } + return false; +} + +function matchesTags(filterTags: string[], fieldTags: string[]): boolean { + if (filterTags.length === 0) { + return true; + } + const normalized = new Set(fieldTags.map((tag) => tag.toLowerCase())); + return filterTags.every((tag) => normalized.has(tag)); +} + +function matchesNodeSelf(params: { + schema: JsonSchema; + path: Array; + hints: ConfigUiHints; + criteria: ConfigSearchCriteria; +}): boolean { + const { schema, path, hints, criteria } = params; + if (!hasSearchCriteria(criteria)) { + return true; + } + const { label, help, tags } = resolveFieldMeta(path, schema, hints); + if (!matchesTags(criteria.tags, tags)) { + return false; + } + + if (!criteria.text) { + return true; + } + + const pathLabel = path + .filter((segment): segment is string => typeof segment === "string") + .join("."); + const enumText = + schema.enum && schema.enum.length > 0 + ? schema.enum.map((value) => String(value)).join(" ") + : ""; + + return matchesText(criteria.text, [ + label, + help, + schema.title, + schema.description, + pathLabel, + enumText, + ]); +} + +export function matchesNodeSearch(params: { + schema: JsonSchema; + value: unknown; + path: Array; + hints: ConfigUiHints; + criteria: ConfigSearchCriteria; +}): boolean { + const { schema, value, path, hints, criteria } = params; + if (!hasSearchCriteria(criteria)) { + return true; + } + if (matchesNodeSelf({ schema, path, hints, criteria })) { + return true; + } + + const type = schemaType(schema); + if (type === "object") { + const fallback = value ?? schema.default; + const obj = + fallback && typeof fallback === "object" && !Array.isArray(fallback) + ? (fallback as Record) + : {}; + const props = schema.properties ?? {}; + for (const [propKey, node] of Object.entries(props)) { + if ( + matchesNodeSearch({ + schema: node, + value: obj[propKey], + path: [...path, propKey], + hints, + criteria, + }) + ) { + return true; + } + } + const additional = schema.additionalProperties; + if (additional && typeof additional === "object") { + const reserved = new Set(Object.keys(props)); + for (const [entryKey, entryValue] of Object.entries(obj)) { + if (reserved.has(entryKey)) { + continue; + } + if ( + matchesNodeSearch({ + schema: additional, + value: entryValue, + path: [...path, entryKey], + hints, + criteria, + }) + ) { + return true; + } + } + } + return false; + } + + if (type === "array") { + const itemsSchema = Array.isArray(schema.items) ? schema.items[0] : schema.items; + if (!itemsSchema) { + return false; + } + const arr = Array.isArray(value) ? value : Array.isArray(schema.default) ? schema.default : []; + if (arr.length === 0) { + return false; + } + for (let idx = 0; idx < arr.length; idx += 1) { + if ( + matchesNodeSearch({ + schema: itemsSchema, + value: arr[idx], + path: [...path, idx], + hints, + criteria, + }) + ) { + return true; + } + } + } + + return false; +} + +function renderTags(tags: string[]): TemplateResult | typeof nothing { + if (tags.length === 0) { + return nothing; + } + return html` +
+ ${tags.map((tag) => html`${tag}`)} +
+ `; +} + export function renderNode(params: { schema: JsonSchema; value: unknown; @@ -102,15 +330,15 @@ export function renderNode(params: { unsupported: Set; disabled: boolean; showLabel?: boolean; + searchCriteria?: ConfigSearchCriteria; onPatch: (path: Array, value: unknown) => void; }): TemplateResult | typeof nothing { const { schema, value, path, hints, unsupported, disabled, onPatch } = params; const showLabel = params.showLabel ?? true; const type = schemaType(schema); - const hint = hintForPath(path, hints); - const label = hint?.label ?? schema.title ?? humanize(String(path.at(-1))); - const help = hint?.help ?? schema.description; + const { label, help, tags } = resolveFieldMeta(path, schema, hints); const key = pathKey(path); + const criteria = params.searchCriteria; if (unsupported.has(key)) { return html`
@@ -118,6 +346,13 @@ export function renderNode(params: {
Unsupported schema node. Use Raw mode.
`; } + if ( + criteria && + hasSearchCriteria(criteria) && + !matchesNodeSearch({ schema, value, path, hints, criteria }) + ) { + return nothing; + } // Handle anyOf/oneOf unions if (schema.anyOf || schema.oneOf) { @@ -150,6 +385,7 @@ export function renderNode(params: {
${showLabel ? html`` : nothing} ${help ? html`
${help}
` : nothing} + ${renderTags(tags)}
${literals.map( (lit) => html` @@ -215,6 +451,7 @@ export function renderNode(params: {
${showLabel ? html`` : nothing} ${help ? html`
${help}
` : nothing} + ${renderTags(tags)}
${options.map( (opt) => html` @@ -258,6 +495,7 @@ export function renderNode(params: {
${label} ${help ? html`${help}` : nothing} + ${renderTags(tags)}
, value: unknown) => void; }): TemplateResult { const { schema, value, path, hints, disabled, onPatch, inputType } = params; const showLabel = params.showLabel ?? true; const hint = hintForPath(path, hints); - const label = hint?.label ?? schema.title ?? humanize(String(path.at(-1))); - const help = hint?.help ?? schema.description; + const { label, help, tags } = resolveFieldMeta(path, schema, hints); const isSensitive = (hint?.sensitive ?? false) && !/^\$\{[^}]*\}$/.test(String(value ?? "").trim()); const placeholder = @@ -322,6 +560,7 @@ function renderTextInput(params: {
${showLabel ? html`` : nothing} ${help ? html`
${help}
` : nothing} + ${renderTags(tags)}
, value: unknown) => void; }): TemplateResult { const { schema, value, path, hints, disabled, onPatch } = params; const showLabel = params.showLabel ?? true; - const hint = hintForPath(path, hints); - const label = hint?.label ?? schema.title ?? humanize(String(path.at(-1))); - const help = hint?.help ?? schema.description; + const { label, help, tags } = resolveFieldMeta(path, schema, hints); const displayValue = value ?? schema.default ?? ""; const numValue = typeof displayValue === "number" ? displayValue : 0; @@ -389,6 +627,7 @@ function renderNumberInput(params: {
${showLabel ? html`` : nothing} ${help ? html`
${help}
` : nothing} + ${renderTags(tags)}
${ @@ -753,24 +1056,12 @@ function renderMapField(params: { hints, unsupported, disabled, + searchCriteria, showLabel: false, onPatch, }) }
-
`; })} diff --git a/ui/src/ui/views/config-form.render.ts b/ui/src/ui/views/config-form.render.ts index 9512622d152..124ca50a585 100644 --- a/ui/src/ui/views/config-form.render.ts +++ b/ui/src/ui/views/config-form.render.ts @@ -1,7 +1,7 @@ import { html, nothing } from "lit"; import { icons } from "../icons.ts"; import type { ConfigUiHints } from "../types.ts"; -import { renderNode } from "./config-form.node.ts"; +import { matchesNodeSearch, parseConfigSearchQuery, renderNode } from "./config-form.node.ts"; import { hintForPath, humanize, schemaType, type JsonSchema } from "./config-form.shared.ts"; export type ConfigFormProps = { @@ -278,20 +278,27 @@ function getSectionIcon(key: string) { return sectionIcons[key as keyof typeof sectionIcons] ?? sectionIcons.default; } -function matchesSearch(key: string, schema: JsonSchema, query: string): boolean { - if (!query) { +function matchesSearch(params: { + key: string; + schema: JsonSchema; + sectionValue: unknown; + uiHints: ConfigUiHints; + query: string; +}): boolean { + if (!params.query) { return true; } - const q = query.toLowerCase(); - const meta = SECTION_META[key]; + const criteria = parseConfigSearchQuery(params.query); + const q = criteria.text; + const meta = SECTION_META[params.key]; // Check key name - if (key.toLowerCase().includes(q)) { + if (q && params.key.toLowerCase().includes(q)) { return true; } // Check label and description - if (meta) { + if (q && meta) { if (meta.label.toLowerCase().includes(q)) { return true; } @@ -300,56 +307,13 @@ function matchesSearch(key: string, schema: JsonSchema, query: string): boolean } } - return schemaMatches(schema, q); -} - -function schemaMatches(schema: JsonSchema, query: string): boolean { - if (schema.title?.toLowerCase().includes(query)) { - return true; - } - if (schema.description?.toLowerCase().includes(query)) { - return true; - } - if (schema.enum?.some((value) => String(value).toLowerCase().includes(query))) { - return true; - } - - if (schema.properties) { - for (const [propKey, propSchema] of Object.entries(schema.properties)) { - if (propKey.toLowerCase().includes(query)) { - return true; - } - if (schemaMatches(propSchema, query)) { - return true; - } - } - } - - if (schema.items) { - const items = Array.isArray(schema.items) ? schema.items : [schema.items]; - for (const item of items) { - if (item && schemaMatches(item, query)) { - return true; - } - } - } - - if (schema.additionalProperties && typeof schema.additionalProperties === "object") { - if (schemaMatches(schema.additionalProperties, query)) { - return true; - } - } - - const unions = schema.anyOf ?? schema.oneOf ?? schema.allOf; - if (unions) { - for (const entry of unions) { - if (entry && schemaMatches(entry, query)) { - return true; - } - } - } - - return false; + return matchesNodeSearch({ + schema: params.schema, + value: params.sectionValue, + path: [params.key], + hints: params.uiHints, + criteria, + }); } export function renderConfigForm(props: ConfigFormProps) { @@ -368,6 +332,7 @@ export function renderConfigForm(props: ConfigFormProps) { const unsupported = new Set(props.unsupportedPaths ?? []); const properties = schema.properties; const searchQuery = props.searchQuery ?? ""; + const searchCriteria = parseConfigSearchQuery(searchQuery); const activeSection = props.activeSection; const activeSubsection = props.activeSubsection ?? null; @@ -384,7 +349,16 @@ export function renderConfigForm(props: ConfigFormProps) { if (activeSection && key !== activeSection) { return false; } - if (searchQuery && !matchesSearch(key, node, searchQuery)) { + if ( + searchQuery && + !matchesSearch({ + key, + schema: node, + sectionValue: value[key], + uiHints: props.uiHints, + query: searchQuery, + }) + ) { return false; } return true; @@ -456,6 +430,7 @@ export function renderConfigForm(props: ConfigFormProps) { unsupported, disabled: props.disabled ?? false, showLabel: false, + searchCriteria, onPatch: props.onPatch, })}
@@ -490,6 +465,7 @@ export function renderConfigForm(props: ConfigFormProps) { unsupported, disabled: props.disabled ?? false, showLabel: false, + searchCriteria, onPatch: props.onPatch, })}
diff --git a/ui/src/ui/views/config-form.search.node.test.ts b/ui/src/ui/views/config-form.search.node.test.ts new file mode 100644 index 00000000000..ee2387ee393 --- /dev/null +++ b/ui/src/ui/views/config-form.search.node.test.ts @@ -0,0 +1,69 @@ +import { describe, expect, it } from "vitest"; +import { matchesNodeSearch, parseConfigSearchQuery } from "./config-form.node.ts"; + +const schema = { + type: "object", + properties: { + gateway: { + type: "object", + properties: { + auth: { + type: "object", + properties: { + token: { type: "string" }, + }, + }, + }, + }, + mode: { + type: "string", + enum: ["off", "token"], + }, + }, +}; + +describe("config form search", () => { + it("parses tag-prefixed query terms", () => { + const parsed = parseConfigSearchQuery("token tag:security tag:Auth"); + expect(parsed.text).toBe("token"); + expect(parsed.tags).toEqual(["security", "auth"]); + }); + + it("matches fields by tag through ui hints", () => { + const parsed = parseConfigSearchQuery("tag:security"); + const matched = matchesNodeSearch({ + schema: schema.properties.gateway, + value: {}, + path: ["gateway"], + hints: { + "gateway.auth.token": { tags: ["security", "secret"] }, + }, + criteria: parsed, + }); + expect(matched).toBe(true); + }); + + it("requires text and tag when combined", () => { + const positive = matchesNodeSearch({ + schema: schema.properties.gateway, + value: {}, + path: ["gateway"], + hints: { + "gateway.auth.token": { tags: ["security"] }, + }, + criteria: parseConfigSearchQuery("token tag:security"), + }); + expect(positive).toBe(true); + + const negative = matchesNodeSearch({ + schema: schema.properties.gateway, + value: {}, + path: ["gateway"], + hints: { + "gateway.auth.token": { tags: ["security"] }, + }, + criteria: parseConfigSearchQuery("mode tag:security"), + }); + expect(negative).toBe(false); + }); +}); diff --git a/ui/src/ui/views/config-form.shared.ts b/ui/src/ui/views/config-form.shared.ts index c7e7d81abe3..366671041da 100644 --- a/ui/src/ui/views/config-form.shared.ts +++ b/ui/src/ui/views/config-form.shared.ts @@ -4,6 +4,8 @@ export type JsonSchema = { type?: string | string[]; title?: string; description?: string; + tags?: string[]; + "x-tags"?: string[]; properties?: Record; items?: JsonSchema | JsonSchema[]; additionalProperties?: JsonSchema | boolean; diff --git a/ui/src/ui/views/config-search.node.test.ts b/ui/src/ui/views/config-search.node.test.ts new file mode 100644 index 00000000000..d1a5a09d837 --- /dev/null +++ b/ui/src/ui/views/config-search.node.test.ts @@ -0,0 +1,50 @@ +import { describe, expect, it } from "vitest"; +import { + appendTagFilter, + getTagFilters, + hasTagFilter, + removeTagFilter, + replaceTagFilters, + toggleTagFilter, +} from "./config-search.ts"; + +describe("config search tag helper", () => { + it("adds a tag when query is empty", () => { + expect(appendTagFilter("", "security")).toBe("tag:security"); + }); + + it("appends a tag to existing text query", () => { + expect(appendTagFilter("token", "security")).toBe("token tag:security"); + }); + + it("deduplicates existing tag filters case-insensitively", () => { + expect(appendTagFilter("token tag:Security", "security")).toBe("token tag:Security"); + }); + + it("detects exact tag terms", () => { + expect(hasTagFilter("tag:security token", "security")).toBe(true); + expect(hasTagFilter("tag:security-hard token", "security")).toBe(false); + }); + + it("removes only the selected active tag", () => { + expect(removeTagFilter("token tag:security tag:auth", "security")).toBe("token tag:auth"); + }); + + it("toggle removes active tag and keeps text", () => { + expect(toggleTagFilter("token tag:security", "security")).toBe("token"); + }); + + it("toggle adds missing tag", () => { + expect(toggleTagFilter("token", "channels")).toBe("token tag:channels"); + }); + + it("extracts unique normalized tags from query", () => { + expect(getTagFilters("token tag:Security tag:auth tag:security")).toEqual(["security", "auth"]); + }); + + it("replaces only tag filters and preserves free text", () => { + expect(replaceTagFilters("token tag:security mode", ["auth", "channels"])).toBe( + "token mode tag:auth tag:channels", + ); + }); +}); diff --git a/ui/src/ui/views/config-search.ts b/ui/src/ui/views/config-search.ts new file mode 100644 index 00000000000..f6973d3a2cd --- /dev/null +++ b/ui/src/ui/views/config-search.ts @@ -0,0 +1,92 @@ +function escapeRegExp(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +} + +function normalizeTag(tag: string): string { + return tag.trim().toLowerCase(); +} + +export function getTagFilters(query: string): string[] { + const seen = new Set(); + const tags: string[] = []; + const pattern = /(^|\s)tag:([^\s]+)/gi; + const raw = query.trim(); + let match: RegExpExecArray | null = pattern.exec(raw); + while (match) { + const normalized = normalizeTag(match[2] ?? ""); + if (normalized && !seen.has(normalized)) { + seen.add(normalized); + tags.push(normalized); + } + match = pattern.exec(raw); + } + return tags; +} + +export function hasTagFilter(query: string, tag: string): boolean { + const normalizedTag = normalizeTag(tag); + if (!normalizedTag) { + return false; + } + const pattern = new RegExp(`(^|\\s)tag:${escapeRegExp(normalizedTag)}(?=\\s|$)`, "i"); + return pattern.test(query.trim()); +} + +export function appendTagFilter(query: string, tag: string): string { + const normalizedTag = normalizeTag(tag); + const trimmed = query.trim(); + if (!normalizedTag) { + return trimmed; + } + if (!trimmed) { + return `tag:${normalizedTag}`; + } + if (hasTagFilter(trimmed, normalizedTag)) { + return trimmed; + } + return `${trimmed} tag:${normalizedTag}`; +} + +export function removeTagFilter(query: string, tag: string): string { + const normalizedTag = normalizeTag(tag); + const trimmed = query.trim(); + if (!normalizedTag || !trimmed) { + return trimmed; + } + const pattern = new RegExp(`(^|\\s)tag:${escapeRegExp(normalizedTag)}(?=\\s|$)`, "ig"); + return trimmed.replace(pattern, " ").replace(/\s+/g, " ").trim(); +} + +export function replaceTagFilters(query: string, tags: readonly string[]): string { + const uniqueTags: string[] = []; + const seen = new Set(); + for (const tag of tags) { + const normalized = normalizeTag(tag); + if (!normalized || seen.has(normalized)) { + continue; + } + seen.add(normalized); + uniqueTags.push(normalized); + } + + const trimmed = query.trim(); + const withoutTags = trimmed + .replace(/(^|\s)tag:([^\s]+)/gi, " ") + .replace(/\s+/g, " ") + .trim(); + const tagTokens = uniqueTags.map((tag) => `tag:${tag}`).join(" "); + if (withoutTags && tagTokens) { + return `${withoutTags} ${tagTokens}`; + } + if (withoutTags) { + return withoutTags; + } + return tagTokens; +} + +export function toggleTagFilter(query: string, tag: string): string { + if (hasTagFilter(query, tag)) { + return removeTagFilter(query, tag); + } + return appendTagFilter(query, tag); +} diff --git a/ui/src/ui/views/config.browser.test.ts b/ui/src/ui/views/config.browser.test.ts index cdb7fc195c4..ec58ef6c8aa 100644 --- a/ui/src/ui/views/config.browser.test.ts +++ b/ui/src/ui/views/config.browser.test.ts @@ -198,4 +198,35 @@ describe("config view", () => { input.dispatchEvent(new Event("input", { bubbles: true })); expect(onSearchChange).toHaveBeenCalledWith("gateway"); }); + + it("shows all tag options in compact tag picker", () => { + const container = document.createElement("div"); + render(renderConfig(baseProps()), container); + + const options = Array.from(container.querySelectorAll(".config-search__tag-option")).map( + (option) => option.textContent?.trim(), + ); + expect(options).toContain("tag:security"); + expect(options).toContain("tag:advanced"); + expect(options).toHaveLength(15); + }); + + it("updates search query when toggling a tag option", () => { + const container = document.createElement("div"); + const onSearchChange = vi.fn(); + render( + renderConfig({ + ...baseProps(), + onSearchChange, + }), + container, + ); + + const option = container.querySelector( + '.config-search__tag-option[data-tag="security"]', + ); + expect(option).toBeTruthy(); + option?.click(); + expect(onSearchChange).toHaveBeenCalledWith("tag:security"); + }); }); diff --git a/ui/src/ui/views/config.ts b/ui/src/ui/views/config.ts index 221f31e0050..5fa88c53aac 100644 --- a/ui/src/ui/views/config.ts +++ b/ui/src/ui/views/config.ts @@ -2,6 +2,7 @@ import { html, nothing } from "lit"; import type { ConfigUiHints } from "../types.ts"; import { hintForPath, humanize, schemaType, type JsonSchema } from "./config-form.shared.ts"; import { analyzeConfigSchema, renderConfigForm, SECTION_META } from "./config-form.ts"; +import { getTagFilters, replaceTagFilters } from "./config-search.ts"; export type ConfigProps = { raw: string; @@ -34,6 +35,24 @@ export type ConfigProps = { onUpdate: () => void; }; +const TAG_SEARCH_PRESETS = [ + "security", + "auth", + "network", + "access", + "privacy", + "observability", + "performance", + "reliability", + "storage", + "models", + "media", + "automation", + "channels", + "tools", + "advanced", +] as const; + // SVG Icons for sidebar (Lucide-style) const sidebarIcons = { all: html` @@ -443,6 +462,7 @@ export function renderConfig(props: ConfigProps) { hasChanges && (props.formMode === "raw" ? true : canSaveForm); const canUpdate = props.connected && !props.applying && !props.updating; + const selectedTags = new Set(getTagFilters(props.searchQuery)); return html`
@@ -460,35 +480,91 @@ export function renderConfig(props: ConfigProps) {
- - - - - props.onSearchChange((e.target as HTMLInputElement).value)} - /> - ${ - props.searchQuery - ? html` - - ` - : nothing - } +
+ + + + + props.onSearchChange((e.target as HTMLInputElement).value)} + /> + ${ + props.searchQuery + ? html` + + ` + : nothing + } +
+
+ Tag filters: +
+ + ${ + selectedTags.size === 0 + ? html` + Add tags + ` + : html` +
+ ${Array.from(selectedTags) + .slice(0, 2) + .map( + (tag) => + html`tag:${tag}`, + )} + ${ + selectedTags.size > 2 + ? html` + +${selectedTags.size - 2} + ` + : nothing + } +
+ ` + } + + +
+ ${TAG_SEARCH_PRESETS.map((tag) => { + const active = selectedTags.has(tag); + return html` + + `; + })} +
+
+