Quelle schema.base.generated.ts
Sprache: JAVA
|
|
Spracherkennung für: .ts vermutete Sprache: Unknown {[0] [0] [0]} [Methode: Schwerpunktbildung, einfache Gewichte, sechs Dimensionen]
// Auto-generated by scripts/generate-base-config-schema.ts. Do not edit directly.
import type { BaseConfigSchemaResponse } from "./schema-base.js";
export const GENERATED_BASE_CONFIG_SCHEMA: BaseConfigSchemaResponse = {
schema: {
$schema: " http://json-schema.org/draft-07/schema#",
type: "object",
properties: {
meta: {
type: "object",
properties: {
lastTouchedVersion: {
type: "string",
title: "Config Last Touched Version",
description: "Auto-set when OpenClaw writes the config.",
},
lastTouchedAt: {
anyOf: [
{
type: "string",
},
{},
],
title: "Config Last Touched At",
description: "ISO timestamp of the last config write (auto-set).",
},
},
additionalProperties: false,
title: "Metadata",
description:
"Metadata fields automatically maintained by OpenClaw to record write/version history for t his config file. Keep these values system-managed and avoid manual edits unless debugging migration history.",
},
env: {
type: "object",
properties: {
shellEnv: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Shell Environment Import Enabled",
description:
"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.",
},
timeoutMs: {
type: "integer",
minimum: 0,
maximum: 9007199254740991,
title: "Shell Environment Import Timeout (ms)",
description:
"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.",
},
},
additionalProperties: false,
title: "Shell Environment Import",
description:
"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.",
},
vars: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "string",
},
title: "Environment Variable Overrides",
description:
"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.",
},
},
additionalProperties: {
type: "string",
},
title: "Environment",
description:
"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.",
},
wizard: {
type: "object",
properties: {
lastRunAt: {
type: "string",
title: "Wizard Last Run Timestamp",
description:
"ISO timestamp for when the setup wizard most recently completed on this host. Use this to confirm setup recency during support and operational audits.",
},
lastRunVersion: {
type: "string",
title: "Wizard Last Run Version",
description:
"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 setup changes.",
},
lastRunCommit: {
type: "string",
title: "Wizard Last Run Commit",
description:
"Source commit identifier recorded for the last wizard execution in development builds. Use this to correlate setup behavior with exact source state during debugging.",
},
lastRunCommand: {
type: "string",
title: "Wizard Last Run Command",
description:
"Command invocation recorded for the latest wizard run to preserve execution context. Use this to reproduce setup steps when verifying setup regressions.",
},
lastRunMode: {
anyOf: [
{
type: "string",
const: "local",
},
{
type: "string",
const: "remote",
},
],
title: "Wizard Last Run Mode",
description:
'Wizard execution mode recorded as "local" or "remote" for the most recent setup flow. Use this to understand whether setup targeted direct local runtime or remote gateway topology.',
},
},
additionalProperties: false,
title: "Setup Wizard State",
description:
"Setup wizard state tracking fields that record the most recent guided setup run details. Keep these fields for observability and troubleshooting of setup flows across upgrades.",
},
diagnostics: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Diagnostics Enabled",
description:
"Master toggle for diagnostics instrumentation output in logs and telemetry wiring paths. Defaults to enabled; set false only in tightly constrained environments.",
},
flags: {
type: "array",
items: {
type: "string",
},
title: "Diagnostics Flags",
description:
'Enable targeted diagnostics logs by flag (e.g. ["telegram.http"]). Supports wildcards like "telegram.*" or "*".',
},
stuckSessionWarnMs: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "Stuck Session Warning Threshold (ms)",
description:
"Age threshold in milliseconds for emitting stuck-session warnings while a session remains in processing state. Increase for long multi-tool turns to reduce false positives; decrease for faster hang detection.",
},
otel: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "OpenTelemetry Enabled",
description:
"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.",
},
endpoint: {
type: "string",
title: "OpenTelemetry Endpoint",
description:
"Collector endpoint URL used for OpenTelemetry export transport, including scheme and port. Use a reachable, trusted collector endpoint and monitor ingestion errors after rollout.",
},
protocol: {
anyOf: [
{
type: "string",
const: "http/protobuf",
},
{
type: "string",
const: "grpc",
},
],
title: "OpenTelemetry Protocol",
description:
'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.',
},
headers: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "string",
},
title: "OpenTelemetry Headers",
description:
"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.",
},
serviceName: {
type: "string",
title: "OpenTelemetry Service Name",
description:
"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.",
},
traces: {
type: "boolean",
title: "OpenTelemetry Traces Enabled",
description:
"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.",
},
metrics: {
type: "boolean",
title: "OpenTelemetry Metrics Enabled",
description:
"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.",
},
logs: {
type: "boolean",
title: "OpenTelemetry Logs Enabled",
description:
"Enable log signal export through OpenTelemetry in addition to local logging sinks. Use this when centralized log correlation is required across services and agents.",
},
sampleRate: {
type: "number",
minimum: 0,
maximum: 1,
title: "OpenTelemetry Trace Sample Rate",
description:
"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.",
},
flushIntervalMs: {
type: "integer",
minimum: 0,
maximum: 9007199254740991,
title: "OpenTelemetry Flush Interval (ms)",
description:
"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.",
},
captureContent: {
anyOf: [
{
type: "boolean",
},
{
type: "object",
properties: {
enabled: {
type: "boolean",
title: "OpenTelemetry Content Capture Enabled",
description:
"Master switch for granular OTEL content capture fields. Keep disabled unless your collector is approved for raw prompt, response, or tool content.",
},
inputMessages: {
type: "boolean",
title: "OpenTelemetry Input Messages Capture",
description:
"Capture model input message text on OTEL spans when content capture is enabled.",
},
outputMessages: {
type: "boolean",
title: "OpenTelemetry Output Messages Capture",
description:
"Capture model output message text on OTEL spans when content capture is enabled.",
},
toolInputs: {
type: "boolean",
title: "OpenTelemetry Tool Inputs Capture",
description:
"Capture tool input text on OTEL spans when content capture is enabled.",
},
toolOutputs: {
type: "boolean",
title: "OpenTelemetry Tool Outputs Capture",
description:
"Capture tool output text on OTEL spans when content capture is enabled.",
},
systemPrompt: {
type: "boolean",
title: "OpenTelemetry System Prompt Capture",
description:
"Capture system prompt text on OTEL spans when content capture is enabled. This remains off unless explicitly enabled.",
},
},
additionalProperties: false,
},
],
title: "OpenTelemetry Content Capture",
description:
"Opt-in OTEL span content capture. Defaults to off; boolean true captures non-system message/tool content, while the object form lets you enable specific content classes.",
},
},
additionalProperties: false,
title: "OpenTelemetry",
description:
"OpenTelemetry export settings for traces, metrics, and logs emitted by gateway components. Use this when integrating with centralized observability backends and distributed tracing pipelines.",
},
cacheTrace: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Cache Trace Enabled",
description: "Log cache trace snapshots for embedded agent runs (default: false).",
},
filePath: {
type: "string",
title: "Cache Trace File Path",
description:
"JSONL output path for cache trace logs (default: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).",
},
includeMessages: {
type: "boolean",
title: "Cache Trace Include Messages",
description: "Include full message payloads in trace output (default: true).",
},
includePrompt: {
type: "boolean",
title: "Cache Trace Include Prompt",
description: "Include prompt text in trace output (default: true).",
},
includeSystem: {
type: "boolean",
title: "Cache Trace Include System",
description: "Include system prompt in trace output (default: true).",
},
},
additionalProperties: false,
title: "Cache Trace",
description:
"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.",
},
},
additionalProperties: false,
title: "Diagnostics",
description:
"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.",
},
logging: {
type: "object",
properties: {
level: {
anyOf: [
{
type: "string",
const: "silent",
},
{
type: "string",
const: "fatal",
},
{
type: "string",
const: "error",
},
{
type: "string",
const: "warn",
},
{
type: "string",
const: "info",
},
{
type: "string",
const: "debug",
},
{
type: "string",
const: "trace",
},
],
title: "Log Level",
description:
'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.',
},
file: {
type: "string",
title: "Log File Path",
description:
"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.",
},
maxFileBytes: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
},
consoleLevel: {
anyOf: [
{
type: "string",
const: "silent",
},
{
type: "string",
const: "fatal",
},
{
type: "string",
const: "error",
},
{
type: "string",
const: "warn",
},
{
type: "string",
const: "info",
},
{
type: "string",
const: "debug",
},
{
type: "string",
const: "trace",
},
],
title: "Console Log Level",
description:
'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.',
},
consoleStyle: {
anyOf: [
{
type: "string",
const: "pretty",
},
{
type: "string",
const: "compact",
},
{
type: "string",
const: "json",
},
],
title: "Console Log Style",
description:
'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.',
},
redactSensitive: {
anyOf: [
{
type: "string",
const: "off",
},
{
type: "string",
const: "tools",
},
],
title: "Sensitive Data Redaction Mode",
description:
'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.',
},
redactPatterns: {
type: "array",
items: {
type: "string",
},
title: "Custom Redaction Patterns",
description:
"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.",
},
},
additionalProperties: false,
title: "Logging",
description:
"Logging behavior controls for severity, output destinations, formatting, and sensitive-data redaction. Keep levels and redaction strict enough for production while preserving useful diagnostics.",
},
cli: {
type: "object",
properties: {
banner: {
type: "object",
properties: {
taglineMode: {
anyOf: [
{
type: "string",
const: "random",
},
{
type: "string",
const: "default",
},
{
type: "string",
const: "off",
},
],
title: "CLI Banner Tagline Mode",
description:
'Controls tagline style in the CLI startup banner: "random" (default) picks from the rotating tagline pool, "default" always shows the neutral default tagline, and "off" hides tagline text while keeping the banner version line.',
},
},
additionalProperties: false,
title: "CLI Banner",
description:
"CLI startup banner controls for title/version line and tagline style behavior. Keep banner enabled for fast version/context checks, then tune tagline mode to your preferred noise level.",
},
},
additionalProperties: false,
title: "CLI",
description:
"CLI presentation controls for local command output behavior such as banner and tagline style. Use this section to keep startup output aligned with operator preference without changing runtime behavior.",
},
update: {
type: "object",
properties: {
channel: {
anyOf: [
{
type: "string",
const: "stable",
},
{
type: "string",
const: "beta",
},
{
type: "string",
const: "dev",
},
],
title: "Update Channel",
description: 'Update channel for git + npm installs ("stable", "beta", or "dev").',
},
checkOnStart: {
type: "boolean",
title: "Update Check on Start",
description: "Check for npm updates when the gateway starts (default: true).",
},
auto: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Auto Update Enabled",
description: "Enable background auto-update for package installs (default: false).",
},
stableDelayHours: {
type: "number",
minimum: 0,
maximum: 168,
title: "Auto Update Stable Delay (hours)",
description: "Minimum delay before stable-channel auto-apply starts (default: 6).",
},
stableJitterHours: {
type: "number",
minimum: 0,
maximum: 168,
title: "Auto Update Stable Jitter (hours)",
description: "Extra stable-channel rollout spread window in hours (default: 12).",
},
betaCheckIntervalHours: {
type: "number",
exclusiveMinimum: 0,
maximum: 24,
title: "Auto Update Beta Check Interval (hours)",
description: "How often beta-channel checks run in hours (default: 1).",
},
},
additionalProperties: false,
},
},
additionalProperties: false,
title: "Updates",
description:
"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.",
},
browser: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Browser Enabled",
description:
"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.",
},
evaluateEnabled: {
type: "boolean",
title: "Browser Evaluate Enabled",
description:
"Enables browser-side evaluate helpers for runtime script evaluation capabilities where supported. Keep disabled unless your workflows require evaluate semantics beyond snapshots/navigation.",
},
cdpUrl: {
type: "string",
title: "Browser CDP URL",
description:
"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.",
},
remoteCdpTimeoutMs: {
type: "integer",
minimum: 0,
maximum: 9007199254740991,
title: "Remote CDP Timeout (ms)",
description:
"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.",
},
remoteCdpHandshakeTimeoutMs: {
type: "integer",
minimum: 0,
maximum: 9007199254740991,
title: "Remote CDP Handshake Timeout (ms)",
description:
"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.",
},
actionTimeoutMs: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "Browser Action Timeout (ms)",
description:
"Default timeout in milliseconds for browser act requests before the client gives up waiting. Raise this when healthy waits or UI interactions exceed the default request budget.",
},
color: {
type: "string",
title: "Browser Accent Color",
description:
"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.",
},
executablePath: {
type: "string",
title: "Browser Executable Path",
description:
"Explicit browser executable path when auto-discovery is insufficient for your host environment. Use absolute stable paths so launch behavior stays deterministic across restarts.",
},
headless: {
type: "boolean",
title: "Browser Headless Mode",
description:
"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.",
},
noSandbox: {
type: "boolean",
title: "Browser No-Sandbox Mode",
description:
"Disables Chromium sandbox isolation flags for environments where sandboxing fails at runtime. Keep this off whenever possible because process isolation protections are reduced.",
},
attachOnly: {
type: "boolean",
title: "Browser Attach-only Mode",
description:
"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.",
},
cdpPortRangeStart: {
type: "integer",
minimum: 1,
maximum: 65535,
title: "Browser CDP Port Range Start",
description:
"Starting local CDP port used for auto-allocated browser profile ports. Increase this when host-level port defaults conflict with other local services.",
},
defaultProfile: {
type: "string",
title: "Browser Default Profile",
description:
"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.",
},
snapshotDefaults: {
type: "object",
properties: {
mode: {
type: "string",
const: "efficient",
title: "Browser Snapshot Mode",
description:
"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.",
},
},
additionalProperties: false,
title: "Browser Snapshot Defaults",
description:
"Default snapshot capture configuration used when callers do not provide explicit snapshot options. Tune this for consistent capture behavior across channels and automation paths.",
},
ssrfPolicy: {
type: "object",
properties: {
dangerouslyAllowPrivateNetwork: {
type: "boolean",
title: "Browser Dangerously Allow Private Network",
description:
"Allows access to private-network address ranges from browser tooling. Default is disabled when unset; enable only for explicitly trusted private-network destinations.",
},
allowedHostnames: {
type: "array",
items: {
type: "string",
},
title: "Browser Allowed Hostnames",
description:
"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.",
},
hostnameAllowlist: {
type: "array",
items: {
type: "string",
},
title: "Browser Hostname Allowlist",
description:
"Legacy/alternate hostname allowlist field used by SSRF policy consumers for explicit host exceptions. Use stable exact hostnames and avoid wildcard-like broad patterns.",
},
},
additionalProperties: false,
title: "Browser SSRF Policy",
description:
"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.",
},
profiles: {
type: "object",
propertyNames: {
type: "string",
pattern: "^[a-z0-9-]+$",
},
additionalProperties: {
type: "object",
properties: {
cdpPort: {
type: "integer",
minimum: 1,
maximum: 65535,
title: "Browser Profile CDP Port",
description:
"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.",
},
cdpUrl: {
type: "string",
title: "Browser Profile CDP URL",
description:
"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.",
},
userDataDir: {
type: "string",
title: "Browser Profile User Data Dir",
description:
"Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory on the selected host or browser node.",
},
driver: {
anyOf: [
{
type: "string",
const: "openclaw",
},
{
type: "string",
const: "clawd",
},
{
type: "string",
const: "existing-session",
},
],
title: "Browser Profile Driver",
description:
'Per-profile browser driver mode. Use "openclaw" (or legacy "clawd") for CDP-based profiles, or use "existing-session" for Chrome DevTools MCP attachment on the selected host or browser node.',
},
headless: {
type: "boolean",
title: "Browser Profile Headless Mode",
description:
"Per-profile headless override for locally launched browser instances. Use this when one profile should stay headless without forcing browser.headless for every other profile.",
},
executablePath: {
type: "string",
},
attachOnly: {
type: "boolean",
title: "Browser Profile Attach-only Mode",
description:
"Per-profile attach-only override that skips local browser launch and only attaches to an existing CDP endpoint. Useful when one profile is externally managed but others are locally launched.",
},
color: {
type: "string",
pattern: "^#?[0-9a-fA-F]{6}$",
title: "Browser Profile Accent Color",
description:
"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.",
},
},
required: ["color"],
additionalProperties: false,
},
title: "Browser Profiles",
description:
"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.",
},
extraArgs: {
type: "array",
items: {
type: "string",
},
},
},
additionalProperties: false,
title: "Browser",
description:
"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.",
},
ui: {
type: "object",
properties: {
seamColor: {
type: "string",
pattern: "^#?[0-9a-fA-F]{6}$",
title: "Accent Color",
description:
"Primary accent color used by UI surfaces for emphasis, badges, and visual identity cues. Use high-contrast values that remain readable across light/dark themes.",
},
assistant: {
type: "object",
properties: {
name: {
type: "string",
maxLength: 50,
title: "Assistant Name",
description:
"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.",
},
avatar: {
type: "string",
maxLength: 200,
title: "Assistant Avatar",
description:
"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.",
},
},
additionalProperties: false,
title: "Assistant Appearance",
description:
"Assistant display identity settings for name and avatar shown in UI surfaces. Keep these values aligned with your operator-facing persona and support expectations.",
},
},
additionalProperties: false,
title: "UI",
description:
"UI presentation settings for accenting and assistant identity shown in control surfaces. Use this for branding and readability customization without changing runtime behavior.",
},
secrets: {
type: "object",
properties: {
providers: {
type: "object",
properties: {},
additionalProperties: {
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
allowlist: {
maxItems: 256,
type: "array",
items: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
},
required: ["source"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
path: {
type: "string",
minLength: 1,
},
mode: {
anyOf: [
{
type: "string",
const: "singleValue",
},
{
type: "string",
const: "json",
},
],
},
timeoutMs: {
type: "integer",
exclusiveMinimum: 0,
maximum: 120000,
},
maxBytes: {
type: "integer",
exclusiveMinimum: 0,
maximum: 20971520,
},
allowInsecurePath: {
type: "boolean",
},
},
required: ["source", "path"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
command: {
type: "string",
minLength: 1,
},
args: {
maxItems: 128,
type: "array",
items: {
type: "string",
maxLength: 1024,
},
},
timeoutMs: {
type: "integer",
exclusiveMinimum: 0,
maximum: 120000,
},
noOutputTimeoutMs: {
type: "integer",
exclusiveMinimum: 0,
maximum: 120000,
},
maxOutputBytes: {
type: "integer",
exclusiveMinimum: 0,
maximum: 20971520,
},
jsonOnly: {
type: "boolean",
},
env: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "string",
},
},
passEnv: {
maxItems: 128,
type: "array",
items: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
trustedDirs: {
maxItems: 64,
type: "array",
items: {
type: "string",
minLength: 1,
},
},
allowInsecurePath: {
type: "boolean",
},
allowSymlinkCommand: {
type: "boolean",
},
},
required: ["source", "command"],
additionalProperties: false,
},
],
},
},
defaults: {
type: "object",
properties: {
env: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
file: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
exec: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
},
additionalProperties: false,
},
resolution: {
type: "object",
properties: {
maxProviderConcurrency: {
type: "integer",
exclusiveMinimum: 0,
maximum: 16,
},
maxRefsPerProvider: {
type: "integer",
exclusiveMinimum: 0,
maximum: 4096,
},
maxBatchBytes: {
type: "integer",
exclusiveMinimum: 0,
maximum: 5242880,
},
},
additionalProperties: false,
},
},
additionalProperties: false,
},
auth: {
type: "object",
properties: {
profiles: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "object",
properties: {
provider: {
type: "string",
},
mode: {
anyOf: [
{
type: "string",
const: "api_key",
},
{
type: "string",
const: "oauth",
},
{
type: "string",
const: "token",
},
],
},
email: {
type: "string",
},
displayName: {
type: "string",
},
},
required: ["provider", "mode"],
additionalProperties: false,
},
title: "Auth Profiles",
description: "Named auth profiles (provider + mode + optional email).",
},
order: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "array",
items: {
type: "string",
},
},
title: "Auth Profile Order",
description: "Ordered auth profile IDs per provider (used for automatic failover).",
},
cooldowns: {
type: "object",
properties: {
billingBackoffHours: {
type: "number",
exclusiveMinimum: 0,
title: "Billing Backoff (hours)",
description:
"Base backoff (hours) when a profile fails due to billing/insufficient credits (default: 5).",
},
billingBackoffHoursByProvider: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "number",
exclusiveMinimum: 0,
},
title: "Billing Backoff Overrides",
description: "Optional per-provider overrides for billing backoff (hours).",
},
billingMaxHours: {
type: "number",
exclusiveMinimum: 0,
title: "Billing Backoff Cap (hours)",
description: "Cap (hours) for billing backoff (default: 24).",
},
authPermanentBackoffMinutes: {
type: "number",
exclusiveMinimum: 0,
title: "Auth-Permanent Backoff (minutes)",
description:
"Base backoff (minutes) for high-confidence auth_permanent failures (default: 10). Keep this shorter than billing so providers recover automatically after transient upstream auth incidents.",
},
authPermanentMaxMinutes: {
type: "number",
exclusiveMinimum: 0,
title: "Auth-Permanent Backoff Cap (minutes)",
description: "Cap (minutes) for auth_permanent backoff (default: 60).",
},
failureWindowHours: {
type: "number",
exclusiveMinimum: 0,
title: "Failover Window (hours)",
description: "Failure window (hours) for backoff counters (default: 24).",
},
overloadedProfileRotations: {
type: "integer",
minimum: 0,
maximum: 9007199254740991,
title: "Overloaded Profile Rotations",
description:
"Maximum same-provider auth-profile rotations allowed for overloaded errors before switching to model fallback (default: 1).",
},
overloadedBackoffMs: {
type: "integer",
minimum: 0,
maximum: 9007199254740991,
title: "Overloaded Backoff (ms)",
description:
"Fixed delay in milliseconds before retrying an overloaded provider/profile rotation (default: 0).",
},
rateLimitedProfileRotations: {
type: "integer",
minimum: 0,
maximum: 9007199254740991,
title: "Rate-Limited Profile Rotations",
description:
"Maximum same-provider auth-profile rotations allowed for rate-limit errors before switching to model fallback (default: 1).",
},
},
additionalProperties: false,
title: "Auth Cooldowns",
description:
"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.",
},
},
additionalProperties: false,
title: "Auth",
description:
"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.",
},
acp: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "ACP Enabled",
description:
"Global ACP feature gate. Keep disabled unless ACP runtime + policy are configured.",
},
dispatch: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "ACP Dispatch Enabled",
description:
"Independent dispatch gate for ACP session turns (default: true). Set false to keep ACP commands available while blocking ACP turn execution.",
},
},
additionalProperties: false,
},
backend: {
type: "string",
title: "ACP Backend",
description:
"Default ACP runtime backend id (for example: acpx). Must match a registered ACP runtime plugin backend.",
},
defaultAgent: {
type: "string",
title: "ACP Default Agent",
description:
"Fallback ACP target agent id used when ACP spawns do not specify an explicit target.",
},
allowedAgents: {
type: "array",
items: {
type: "string",
},
title: "ACP Allowed Agents",
description:
"Allowlist of ACP target agent ids permitted for ACP runtime sessions. Empty means no additional allowlist restriction.",
},
maxConcurrentSessions: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "ACP Max Concurrent Sessions",
description: "Maximum concurrently active ACP sessions across this gateway process.",
},
stream: {
type: "object",
properties: {
coalesceIdleMs: {
type: "integer",
minimum: 0,
maximum: 9007199254740991,
title: "ACP Stream Coalesce Idle (ms)",
description:
"Coalescer idle flush window in milliseconds for ACP streamed text before block replies are emitted.",
},
maxChunkChars: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "ACP Stream Max Chunk Chars",
description:
"Maximum chunk size for ACP streamed block projection before splitting into multiple block replies.",
},
repeatSuppression: {
type: "boolean",
title: "ACP Stream Repeat Suppression",
description:
"When true (default), suppress repeated ACP status/tool projection lines in a turn while keeping raw ACP events unchanged.",
},
deliveryMode: {
anyOf: [
{
type: "string",
const: "live",
},
{
type: "string",
const: "final_only",
},
],
title: "ACP Stream Delivery Mode",
description:
"ACP delivery style: live streams projected output incrementally, final_only buffers all projected ACP output until terminal turn events.",
},
hiddenBoundarySeparator: {
anyOf: [
{
type: "string",
const: "none",
},
{
type: "string",
const: "space",
},
{
type: "string",
const: "newline",
},
{
type: "string",
const: "paragraph",
},
],
title: "ACP Stream Hidden Boundary Separator",
description:
"Separator inserted before next visible assistant text when hidden ACP tool lifecycle events occurred (none|space|newline|paragraph). Default: paragraph.",
},
maxOutputChars: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "ACP Stream Max Output Chars",
description:
"Maximum assistant output characters projected per ACP turn before truncation notice is emitted.",
},
maxSessionUpdateChars: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "ACP Stream Max Session Update Chars",
description:
"Maximum characters for projected ACP session/update lines (tool/status updates).",
},
tagVisibility: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "boolean",
},
title: "ACP Stream Tag Visibility",
description:
"Per-sessionUpdate visibility overrides for ACP projection (for example usage_update, available_commands_update).",
},
},
additionalProperties: false,
title: "ACP Stream",
description:
"ACP streaming projection controls for chunk sizing, metadata visibility, and deduped delivery behavior.",
},
runtime: {
type: "object",
properties: {
ttlMinutes: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "ACP Runtime TTL (minutes)",
description:
"Idle runtime TTL in minutes for ACP session workers before eligible cleanup.",
},
installCommand: {
type: "string",
title: "ACP Runtime Install Command",
description:
"Optional operator install/setup command shown by `/acp install` and `/acp doctor` when ACP backend wiring is missing.",
},
},
additionalProperties: false,
},
},
additionalProperties: false,
title: "ACP",
description:
"ACP runtime controls for enabling dispatch, selecting backends, constraining allowed agent targets, and tuning streamed turn projection behavior.",
},
models: {
type: "object",
properties: {
mode: {
anyOf: [
{
type: "string",
const: "merge",
},
{
type: "string",
const: "replace",
},
],
title: "Model Catalog Mode",
description:
'Controls provider catalog behavior: "merge" keeps built-ins and overlays your custom providers, while "replace" uses only your configured providers. In "merge", matching provider IDs preserve non-empty agent models.json baseUrl values, while apiKey values are preserved only when the provider is not SecretRef-managed in current config/auth-profile context; SecretRef-managed providers refresh apiKey from current source markers, and matching model contextWindow/maxTokens use the higher value between explicit and implicit entries.',
},
providers: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "object",
properties: {
baseUrl: {
type: "string",
minLength: 1,
title: "Model Provider Base URL",
description:
"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.",
},
apiKey: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider API Key",
description:
"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.",
},
auth: {
anyOf: [
{
type: "string",
const: "api-key",
},
{
type: "string",
const: "aws-sdk",
},
{
type: "string",
const: "oauth",
},
{
type: "string",
const: "token",
},
],
title: "Model Provider Auth Mode",
description:
'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.',
},
api: {
type: "string",
enum: [
"openai-completions",
"openai-responses",
"openai-codex-responses",
"anthropic-messages",
"google-generative-ai",
"github-copilot",
"bedrock-converse-stream",
"ollama",
"azure-openai-responses",
],
title: "Model Provider API Adapter",
description:
"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.",
},
injectNumCtxForOpenAICompat: {
type: "boolean",
title: "Model Provider Inject num_ctx (OpenAI Compat)",
description:
"Controls whether OpenClaw injects `options.num_ctx` for Ollama providers configured with the OpenAI-compatible adapter (`openai-completions`). Default is true. Set false only if your proxy/upstream rejects unknown `options` payload fields.",
},
headers: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
},
title: "Model Provider Headers",
description:
"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.",
},
authHeader: {
type: "boolean",
title: "Model Provider Authorization Header",
description:
"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.",
},
request: {
type: "object",
properties: {
headers: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
},
title: "Model Provider Request Headers",
description:
"Extra headers merged into provider requests after default attribution and auth resolution.",
},
auth: {
anyOf: [
{
type: "object",
properties: {
mode: {
type: "string",
const: "provider-default",
title: "Model Provider Request Auth Mode",
description:
'Auth override mode: "provider-default", "authorization-bearer", or "header".',
},
},
required: ["mode"],
additionalProperties: false,
},
{
type: "object",
properties: {
mode: {
type: "string",
const: "authorization-bearer",
title: "Model Provider Request Auth Mode",
description:
'Auth override mode: "provider-default", "authorization-bearer", or "header".',
},
token: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Bearer Token",
description:
"Bearer token used when auth mode is authorization-bearer.",
},
},
required: ["mode", "token"],
additionalProperties: false,
},
{
type: "object",
properties: {
mode: {
type: "string",
const: "header",
title: "Model Provider Request Auth Mode",
description:
'Auth override mode: "provider-default", "authorization-bearer", or "header".',
},
headerName: {
type: "string",
minLength: 1,
title: "Model Provider Request Auth Header Name",
description: "Custom auth header name used when auth mode is header.",
},
value: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Auth Header Value",
description:
"Custom auth header value used when auth mode is header.",
},
prefix: {
type: "string",
title: "Model Provider Request Auth Header Prefix",
description:
"Optional prefix prepended to request.auth.value when auth mode is header.",
},
},
required: ["mode", "headerName", "value"],
additionalProperties: false,
},
],
title: "Model Provider Request Auth Override",
description:
"Override provider request authentication behavior for this provider.",
},
proxy: {
anyOf: [
{
type: "object",
properties: {
mode: {
type: "string",
const: "env-proxy",
title: "Model Provider Request Proxy Mode",
description:
'Proxy override mode for model-provider requests: "env-proxy" or "explicit-proxy".',
},
tls: {
type: "object",
properties: {
ca: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Proxy TLS CA",
description:
"Custom CA bundle used to verify the proxy TLS certificate chain.",
},
cert: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Proxy TLS Cert",
description:
"Client TLS certificate presented to the proxy when mutual TLS is required.",
},
key: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Proxy TLS Key",
description:
"Private key paired with request.proxy.tls.cert for proxy mutual TLS.",
},
passphrase: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Proxy TLS Passphrase",
description:
"Optional passphrase used to decrypt request.proxy.tls.key.",
},
serverName: {
type: "string",
title: "Model Provider Request Proxy TLS Server Name",
description:
"Optional SNI/server-name override used when establishing TLS to the proxy.",
},
insecureSkipVerify: {
type: "boolean",
title: "Model Provider Request Proxy TLS Skip Verify",
description:
"Skips proxy TLS certificate verification. Use only for controlled development environments.",
},
},
additionalProperties: false,
title: "Model Provider Request Proxy TLS",
description:
"Optional TLS settings used when connecting to the configured proxy.",
},
},
required: ["mode"],
additionalProperties: false,
},
{
type: "object",
properties: {
mode: {
type: "string",
const: "explicit-proxy",
title: "Model Provider Request Proxy Mode",
description:
'Proxy override mode for model-provider requests: "env-proxy" or "explicit-proxy".',
},
url: {
type: "string",
minLength: 1,
title: "Model Provider Request Proxy URL",
description:
"Explicit proxy URL used when request.proxy.mode is explicit-proxy. Credentials embedded in the URL are treated as sensitive and redacted from snapshots.",
},
tls: {
type: "object",
properties: {
ca: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Proxy TLS CA",
description:
"Custom CA bundle used to verify the proxy TLS certificate chain.",
},
cert: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Proxy TLS Cert",
description:
"Client TLS certificate presented to the proxy when mutual TLS is required.",
},
key: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Proxy TLS Key",
description:
"Private key paired with request.proxy.tls.cert for proxy mutual TLS.",
},
passphrase: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request Proxy TLS Passphrase",
description:
"Optional passphrase used to decrypt request.proxy.tls.key.",
},
serverName: {
type: "string",
title: "Model Provider Request Proxy TLS Server Name",
description:
"Optional SNI/server-name override used when establishing TLS to the proxy.",
},
insecureSkipVerify: {
type: "boolean",
title: "Model Provider Request Proxy TLS Skip Verify",
description:
"Skips proxy TLS certificate verification. Use only for controlled development environments.",
},
},
additionalProperties: false,
title: "Model Provider Request Proxy TLS",
description:
"Optional TLS settings used when connecting to the configured proxy.",
},
},
required: ["mode", "url"],
additionalProperties: false,
},
],
title: "Model Provider Request Proxy",
description:
'Optional proxy override for model-provider requests. Use "env-proxy" to honor environment proxy settings or "explicit-proxy" to route through a specific proxy URL.',
},
tls: {
type: "object",
properties: {
ca: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request TLS CA",
description:
"Custom CA bundle used to verify the upstream TLS certificate chain.",
},
cert: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request TLS Cert",
description:
"Client TLS certificate presented to the upstream endpoint when mutual TLS is required.",
},
key: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request TLS Key",
description:
"Private key paired with request.tls.cert for upstream mutual TLS.",
},
passphrase: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Model Provider Request TLS Passphrase",
description: "Optional passphrase used to decrypt request.tls.key.",
},
serverName: {
type: "string",
title: "Model Provider Request TLS Server Name",
description:
"Optional SNI/server-name override used when establishing upstream TLS.",
},
insecureSkipVerify: {
type: "boolean",
title: "Model Provider Request TLS Skip Verify",
description:
"Skips upstream TLS certificate verification. Use only for controlled development environments.",
},
},
additionalProperties: false,
title: "Model Provider Request TLS",
description:
"Optional TLS settings used when connecting directly to the upstream model endpoint.",
},
allowPrivateNetwork: {
type: "boolean",
title: "Model Provider Request Allow Private Network",
description:
"When true, allow HTTPS to the model base URL when DNS resolves to private, CGNAT, or similar ranges, via the provider HTTP fetch guard (fetchWithSsrFGuard). OpenAI Responses WebSocket reuses request for headers/TLS but does not use that fetch SSRF path. Use only for operator-controlled self-hosted OpenAI-compatible endpoints (LAN, overlay, split DNS). Default is false.",
},
},
additionalProperties: false,
title: "Model Provider Request Overrides",
description:
"Optional request overrides for model-provider requests, including extra headers, auth overrides, proxy routing, TLS client settings, and optional allowPrivateNetwork for trusted self-hosted endpoints. Use these only when your upstream or enterprise network path requires transport customization.",
},
models: {
type: "array",
items: {
type: "object",
properties: {
id: {
type: "string",
minLength: 1,
},
name: {
type: "string",
minLength: 1,
},
api: {
type: "string",
enum: [
"openai-completions",
"openai-responses",
"openai-codex-responses",
"anthropic-messages",
"google-generative-ai",
"github-copilot",
"bedrock-converse-stream",
"ollama",
"azure-openai-responses",
],
},
baseUrl: {
type: "string",
minLength: 1,
},
reasoning: {
type: "boolean",
},
input: {
type: "array",
items: {
anyOf: [
{
type: "string",
const: "text",
},
{
type: "string",
const: "image",
},
],
},
},
cost: {
type: "object",
properties: {
input: {
type: "number",
},
output: {
type: "number",
},
cacheRead: {
type: "number",
},
cacheWrite: {
type: "number",
},
tieredPricing: {
type: "array",
items: {
type: "object",
properties: {
input: {
type: "number",
},
output: {
type: "number",
},
cacheRead: {
type: "number",
},
cacheWrite: {
type: "number",
},
range: {
anyOf: [
{
type: "array",
items: [
{
type: "number",
},
{
type: "number",
},
],
},
{
type: "array",
items: [
{
type: "number",
},
],
},
],
},
},
required: ["input", "output", "cacheRead", "cacheWrite", "range"],
additionalProperties: false,
},
},
},
additionalProperties: false,
},
contextWindow: {
type: "number",
exclusiveMinimum: 0,
},
contextTokens: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
},
maxTokens: {
type: "number",
exclusiveMinimum: 0,
},
headers: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "string",
},
},
compat: {
type: "object",
properties: {
supportsStore: {
type: "boolean",
},
supportsPromptCacheKey: {
type: "boolean",
},
supportsDeveloperRole: {
type: "boolean",
},
supportsReasoningEffort: {
type: "boolean",
},
supportsUsageInStreaming: {
type: "boolean",
},
supportsTools: {
type: "boolean",
},
supportsStrictMode: {
type: "boolean",
},
requiresStringContent: {
type: "boolean",
},
visibleReasoningDetailTypes: {
type: "array",
items: {
type: "string",
minLength: 1,
},
},
maxTokensField: {
anyOf: [
{
type: "string",
const: "max_completion_tokens",
},
{
type: "string",
const: "max_tokens",
},
],
},
thinkingFormat: {
anyOf: [
{
type: "string",
const: "openai",
},
{
type: "string",
const: "openrouter",
},
{
type: "string",
const: "deepseek",
},
{
type: "string",
const: "zai",
},
{
type: "string",
const: "qwen",
},
{
type: "string",
const: "qwen-chat-template",
},
],
},
requiresToolResultName: {
type: "boolean",
},
requiresAssistantAfterToolResult: {
type: "boolean",
},
requiresThinkingAsText: {
type: "boolean",
},
toolSchemaProfile: {
type: "string",
},
unsupportedToolSchemaKeywords: {
type: "array",
items: {
type: "string",
minLength: 1,
},
},
nativeWebSearchTool: {
type: "boolean",
},
toolCallArgumentsEncoding: {
type: "string",
},
requiresMistralToolIds: {
type: "boolean",
},
requiresOpenAiAnthropicToolPayload: {
type: "boolean",
},
},
additionalProperties: false,
},
metadataSource: {
type: "string",
const: "models-add",
},
},
required: ["id", "name"],
additionalProperties: false,
},
title: "Model Provider Model List",
description:
"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.",
},
},
required: ["baseUrl", "models"],
additionalProperties: false,
},
title: "Model Providers",
description:
"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.",
},
},
additionalProperties: false,
title: "Models",
description:
"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.",
},
nodeHost: {
type: "object",
properties: {
browserProxy: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Node Browser Proxy Enabled",
description:
"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.",
},
allowProfiles: {
type: "array",
items: {
type: "string",
},
title: "Node Browser Proxy Allowed Profiles",
description:
"Optional allowlist of browser profile names exposed through node proxy routing. Leave empty to preserve the default full profile surface, including profile create/delete routes. When set, OpenClaw enforces least-privilege profile access and blocks persistent profile create/delete through the proxy.",
},
},
additionalProperties: false,
title: "Node Browser Proxy",
description:
"Groups browser-proxy settings for exposing local browser control through node routing. Enable only when remote node workflows need your local browser profiles.",
},
},
additionalProperties: false,
title: "Node Host",
description:
"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.",
},
agents: {
type: "object",
properties: {
defaults: {
type: "object",
properties: {
params: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {},
},
embeddedHarness: {
type: "object",
properties: {
runtime: {
type: "string",
title: "Default Agent Runtime",
description:
"Embedded harness runtime: pi, auto, or a registered plugin harness id such as codex. Omitted runtime uses built-in OpenClaw Pi.",
},
fallback: {
type: "string",
enum: ["pi", "none"],
title: "Default Embedded Harness Fallback",
description:
"Embedded harness fallback when no plugin harness matches. Auto mode defaults to pi; explicit plugin runtimes default to none and do not inherit broader fallback settings. Selected plugin harness failures surface directly.",
},
},
additionalProperties: false,
title: "Default Agent Runtime Settings",
description:
"Default embedded agent harness policy. Omitted runtime uses built-in OpenClaw Pi. Use runtime=auto for plugin harness selection, or a registered harness id such as codex.",
},
model: {
anyOf: [
{
type: "string",
},
{
type: "object",
properties: {
primary: {
type: "string",
title: "Primary Model",
description: "Primary model (provider/model).",
},
fallbacks: {
type: "array",
items: {
type: "string",
},
title: "Model Fallbacks",
description:
"Ordered fallback models (provider/model). Used when the primary model fails.",
},
},
additionalProperties: false,
},
],
},
imageModel: {
anyOf: [
{
type: "string",
},
{
type: "object",
properties: {
primary: {
type: "string",
title: "Image Model",
description:
"Optional image model (provider/model) used when the primary model lacks image input.",
},
fallbacks: {
type: "array",
items: {
type: "string",
},
title: "Image Model Fallbacks",
description: "Ordered fallback image models (provider/model).",
},
},
additionalProperties: false,
},
],
},
imageGenerationModel: {
anyOf: [
{
type: "string",
},
{
type: "object",
properties: {
primary: {
type: "string",
title: "Image Generation Model",
description:
"Optional image-generation model (provider/model) used by the shared image generation capability.",
},
fallbacks: {
type: "array",
items: {
type: "string",
},
title: "Image Generation Model Fallbacks",
description: "Ordered fallback image-generation models (provider/model).",
},
},
additionalProperties: false,
},
],
},
videoGenerationModel: {
anyOf: [
{
type: "string",
},
{
type: "object",
properties: {
primary: {
type: "string",
title: "Video Generation Model",
description:
"Optional video-generation model (provider/model) used by the shared video generation capability.",
},
fallbacks: {
type: "array",
items: {
type: "string",
},
title: "Video Generation Model Fallbacks",
description: "Ordered fallback video-generation models (provider/model).",
},
},
additionalProperties: false,
},
],
},
musicGenerationModel: {
anyOf: [
{
type: "string",
},
{
type: "object",
properties: {
primary: {
type: "string",
title: "Music Generation Model",
description:
"Optional music-generation model (provider/model) used by the shared music generation capability.",
},
fallbacks: {
type: "array",
items: {
type: "string",
},
title: "Music Generation Model Fallbacks",
description: "Ordered fallback music-generation models (provider/model).",
},
},
additionalProperties: false,
},
],
},
mediaGenerationAutoProviderFallback: {
type: "boolean",
title: "Media Generation Auto Provider Fallback",
description:
"When true (default), shared image, music, and video generation automatically appends other auth-backed provider defaults after explicit primary/fallback refs. Set false to disable implicit cross-provider fallback while keeping explicit fallbacks.",
},
pdfModel: {
anyOf: [
{
type: "string",
},
{
type: "object",
properties: {
primary: {
type: "string",
title: "PDF Model",
description:
"Optional PDF model (provider/model) for the PDF analysis tool. Defaults to imageModel, then session model.",
},
fallbacks: {
type: "array",
items: {
type: "string",
},
title: "PDF Model Fallbacks",
description: "Ordered fallback PDF models (provider/model).",
},
},
additionalProperties: false,
},
],
},
pdfMaxBytesMb: {
type: "number",
exclusiveMinimum: 0,
title: "PDF Max Size (MB)",
description: "Maximum PDF file size in megabytes for the PDF tool (default: 10).",
},
pdfMaxPages: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "PDF Max Pages",
description:
"Maximum number of PDF pages to process for the PDF tool (default: 20).",
},
models: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "object",
properties: {
alias: {
type: "string",
},
params: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {},
},
streaming: {
type: "boolean",
},
},
additionalProperties: false,
},
title: "Models",
description: "Configured model catalog (keys are full provider/model IDs).",
},
workspace: {
type: "string",
title: "Workspace",
description:
"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.",
},
skills: {
type: "array",
items: {
type: "string",
},
title: "Skills",
description:
"Optional default skill allowlist inherited by agents that omit agents.list[].skills. Omit for unrestricted skills, set [] to give inheriting agents no skills, and remember explicit agents.list[].skills replaces this default instead of merging with it.",
},
silentReply: {
type: "object",
properties: {
direct: {
anyOf: [
{
type: "string",
const: "allow",
},
{
type: "string",
const: "disallow",
},
],
},
group: {
anyOf: [
{
type: "string",
const: "allow",
},
{
type: "string",
const: "disallow",
},
],
},
internal: {
anyOf: [
{
type: "string",
const: "allow",
},
{
type: "string",
const: "disallow",
},
],
},
},
additionalProperties: false,
},
silentReplyRewrite: {
type: "object",
properties: {
direct: {
type: "boolean",
},
group: {
type: "boolean",
},
internal: {
type: "boolean",
},
},
additionalProperties: false,
},
repoRoot: {
type: "string",
title: "Repo Root",
description:
"Optional repository root shown in the system prompt runtime line (overrides auto-detect).",
},
systemPromptOverride: {
type: "string",
},
promptOverlays: {
type: "object",
properties: {
gpt5: {
type: "object",
properties: {
personality: {
anyOf: [
{
type: "string",
const: "friendly",
},
{
type: "string",
const: "on",
},
{
type: "string",
const: "off",
},
],
title: "GPT-5 Personality Overlay",
description:
'Friendly interaction-style layer for GPT-5-family models ("friendly" or "on" enables it; "off" disables only that layer). The tagged behavior contract remains enabled for matching GPT-5 models.',
},
},
additionalProperties: false,
title: "GPT-5 Prompt Overlay",
description:
"Shared GPT-5-family prompt overlay applied to matching model ids across providers such as OpenAI, OpenRouter, OpenCode, Codex, and compatible gateways.",
},
},
additionalProperties: false,
title: "Prompt Overlays",
description:
"Provider-independent prompt overlays applied by model family before provider-specific prompt hooks.",
},
skipBootstrap: {
type: "boolean",
},
contextInjection: {
anyOf: [
{
type: "string",
const: "always",
},
{
type: "string",
const: "continuation-skip",
},
{
type: "string",
const: "never",
},
],
title: "Context Injection",
description:
'Controls when workspace bootstrap files are injected into the system prompt: "always" (default) or "continuation-skip" for safe continuation turns after a completed assistant response.',
},
bootstrapMaxChars: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "Bootstrap Max Chars",
description:
"Max characters of each workspace bootstrap file injected into the system prompt before truncation (default: 12000).",
},
bootstrapTotalMaxChars: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "Bootstrap Total Max Chars",
description:
"Max total characters across all injected workspace bootstrap files (default: 60000).",
},
experimental: {
type: "object",
properties: {
localModelLean: {
type: "boolean",
title: "Enable Lean Local Model Mode (Experimental)",
description:
"Experimental local-model prompt trim. When enabled, OpenClaw drops heavyweight default tools like browser, cron, and message for weaker or smaller local-model backends.",
},
},
additionalProperties: false,
title: "Experimental Agent Flags",
description:
"Experimental agent-default flags. Keep these off unless you are intentionally testing a preview surface.",
},
bootstrapPromptTruncationWarning: {
anyOf: [
{
type: "string",
const: "off",
},
{
type: "string",
const: "once",
},
{
type: "string",
const: "always",
},
],
title: "Bootstrap Prompt Truncation Warning",
description:
'Inject agent-visible warning text when bootstrap files are truncated: "off", "once" (default), or "always".',
},
userTimezone: {
type: "string",
},
startupContext: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Enable Startup Context",
description:
"Enable the startup-context prelude for bare session resets (default: true). Disable this to fall back to prompt-only behavior with no runtime-loaded daily memory.",
},
applyOn: {
type: "array",
items: {
anyOf: [
{
type: "string",
const: "new",
},
{
type: "string",
const: "reset",
},
],
},
title: "Startup Context Apply On",
description:
'Chooses which bare reset commands get startup context: include "new", "reset", or both (default: ["new","reset"]).',
},
dailyMemoryDays: {
type: "integer",
minimum: 1,
maximum: 14,
title: "Startup Context Daily Memory Days",
description:
"Number of dated memory files to load counting backward from today in the configured user timezone (default: 2 for today + yesterday).",
},
maxFileBytes: {
type: "integer",
minimum: 1,
maximum: 65536,
title: "Startup Context Max File Bytes",
description:
"Maximum bytes allowed per daily memory file when building startup context (default: 16384). Files over this boundary-safe read limit are skipped.",
},
maxFileChars: {
type: "integer",
minimum: 1,
maximum: 10000,
title: "Startup Context Max File Chars",
description:
"Maximum characters retained from each loaded daily memory file in the startup prelude (default: 1200).",
},
maxTotalChars: {
type: "integer",
minimum: 1,
maximum: 50000,
title: "Startup Context Max Total Chars",
description:
"Maximum total characters retained across all loaded daily memory files in the startup prelude (default: 2800). Additional files are truncated from the prelude once this cap is reached.",
},
},
additionalProperties: false,
title: "Startup Context",
description:
'Runtime-owned first-turn prelude for bare "/new" and "/reset". Use this to control whether recent daily memory files are preloaded into the first prompt instead of asking the model to decide what to read.',
},
contextLimits: {
type: "object",
properties: {
memoryGetMaxChars: {
type: "integer",
minimum: 1,
maximum: 250000,
title: "Default memory_get Max Chars",
description:
"Default max characters returned by memory_get before truncation metadata and continuation notice are added. Increase to approximate older larger excerpts, but keep it bounded.",
},
memoryGetDefaultLines: {
type: "integer",
minimum: 1,
maximum: 5000,
title: "Default memory_get Line Window",
description:
"Default memory_get line window used when requests omit lines. This controls how many source lines are selected before the max-char cap is applied.",
},
toolResultMaxChars: {
type: "integer",
minimum: 1,
maximum: 250000,
title: "Default Tool Result Max Chars",
description:
"Default max characters kept for a single live tool result before truncation. This affects both persisted live tool-result writes and overflow-recovery truncation heuristics.",
},
postCompactionMaxChars: {
type: "integer",
minimum: 1,
maximum: 50000,
title: "Default Post-compaction Max Chars",
description:
"Default max characters retained from AGENTS.md during post-compaction context refresh injection. Lower this to make compaction recovery cheaper, or raise it for agents that depend on longer startup guidance.",
},
},
additionalProperties: false,
title: "Default Context Limits",
description:
"Focused per-agent-context budget defaults for selected high-volume excerpts and injected prompt blocks. Use this to tune bounded read/injection sizes without reopening any unbounded call paths.",
},
timeFormat: {
anyOf: [
{
type: "string",
const: "auto",
},
{
type: "string",
const: "12",
},
{
type: "string",
const: "24",
},
],
},
envelopeTimezone: {
type: "string",
title: "Envelope Timezone",
description:
'Timezone for message envelopes ("utc", "local", "user", or an IANA timezone string).',
},
envelopeTimestamp: {
anyOf: [
{
type: "string",
const: "on",
},
{
type: "string",
const: "off",
},
],
title: "Envelope Timestamp",
description: 'Include absolute timestamps in message envelopes ("on" or "off").',
},
envelopeElapsed: {
anyOf: [
{
type: "string",
const: "on",
},
{
type: "string",
const: "off",
},
],
title: "Envelope Elapsed",
description: 'Include elapsed time in message envelopes ("on" or "off").',
},
contextTokens: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
},
cliBackends: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "object",
properties: {
command: {
type: "string",
},
args: {
type: "array",
items: {
type: "string",
},
},
output: {
anyOf: [
{
type: "string",
const: "json",
},
{
type: "string",
const: "text",
},
{
type: "string",
const: "jsonl",
},
],
},
resumeOutput: {
anyOf: [
{
type: "string",
const: "json",
},
{
type: "string",
const: "text",
},
{
type: "string",
const: "jsonl",
},
],
},
jsonlDialect: {
type: "string",
const: "claude-stream-json",
},
liveSession: {
type: "string",
const: "claude-stdio",
},
input: {
anyOf: [
{
type: "string",
const: "arg",
},
{
type: "string",
const: "stdin",
},
],
},
maxPromptArgChars: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
},
env: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "string",
},
},
clearEnv: {
type: "array",
items: {
type: "string",
},
},
modelArg: {
type: "string",
},
modelAliases: {
type: "object",
propertyNames: {
type: "string",
},
additionalProperties: {
type: "string",
},
},
sessionArg: {
type: "string",
},
sessionArgs: {
type: "array",
items: {
type: "string",
},
},
resumeArgs: {
type: "array",
items: {
type: "string",
},
},
sessionMode: {
anyOf: [
{
type: "string",
const: "always",
},
{
type: "string",
const: "existing",
},
{
type: "string",
const: "none",
},
],
},
sessionIdFields: {
type: "array",
items: {
type: "string",
},
},
systemPromptArg: {
type: "string",
},
systemPromptFileConfigArg: {
type: "string",
},
systemPromptFileConfigKey: {
type: "string",
},
systemPromptMode: {
anyOf: [
{
type: "string",
const: "append",
},
{
type: "string",
const: "replace",
},
],
},
systemPromptWhen: {
anyOf: [
{
type: "string",
const: "first",
},
{
type: "string",
const: "always",
},
{
type: "string",
const: "never",
},
],
},
imageArg: {
type: "string",
},
imageMode: {
anyOf: [
{
type: "string",
const: "repeat",
},
{
type: "string",
const: "list",
},
],
},
imagePathScope: {
anyOf: [
{
type: "string",
const: "temp",
},
{
type: "string",
const: "workspace",
},
],
},
serialize: {
type: "boolean",
},
reliability: {
type: "object",
properties: {
watchdog: {
type: "object",
properties: {
fresh: {
type: "object",
properties: {
noOutputTimeoutMs: {
type: "integer",
minimum: 1000,
maximum: 9007199254740991,
},
noOutputTimeoutRatio: {
type: "number",
minimum: 0.05,
maximum: 0.95,
},
minMs: {
type: "integer",
minimum: 1000,
maximum: 9007199254740991,
},
maxMs: {
type: "integer",
minimum: 1000,
maximum: 9007199254740991,
},
},
additionalProperties: false,
},
resume: {
type: "object",
properties: {
noOutputTimeoutMs: {
type: "integer",
minimum: 1000,
maximum: 9007199254740991,
},
noOutputTimeoutRatio: {
type: "number",
minimum: 0.05,
maximum: 0.95,
},
minMs: {
type: "integer",
minimum: 1000,
maximum: 9007199254740991,
},
maxMs: {
type: "integer",
minimum: 1000,
maximum: 9007199254740991,
},
},
additionalProperties: false,
},
},
additionalProperties: false,
},
},
additionalProperties: false,
},
},
required: ["command"],
additionalProperties: false,
},
title: "CLI Backends",
description: "Optional CLI backends for text-only fallback (claude-cli, etc.).",
},
memorySearch: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Enable Memory Search",
description:
"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.",
},
sources: {
type: "array",
items: {
anyOf: [
{
type: "string",
const: "memory",
},
{
type: "string",
const: "sessions",
},
],
},
title: "Memory Search Sources",
description:
'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.',
},
extraPaths: {
type: "array",
items: {
type: "string",
},
title: "Extra Memory Paths",
description:
"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; when multimodal memory is enabled, matching image/audio files under these paths are also eligible for indexing.",
},
qmd: {
type: "object",
properties: {
extraCollections: {
type: "array",
items: {
type: "object",
properties: {
path: {
type: "string",
},
name: {
type: "string",
},
pattern: {
type: "string",
},
},
required: ["path"],
additionalProperties: false,
},
title: "QMD Extra Collections",
description:
"Use this when you need directional transcript search across agents; add collections here to scope QMD recalls without creating a shared global transcript namespace.",
},
},
additionalProperties: false,
title: "Memory Search QMD Collections",
description:
"Use this when one agent should query another agent's transcript collections; QMD-specific extra collections let you opt into cross-agent memory search without flattening everything into one shared namespace.",
},
multimodal: {
type: "object",
properties: {
enabled: {
type: "boolean",
title: "Enable Memory Search Multimodal",
description:
"Enables image/audio memory indexing from extraPaths. This currently requires Gemini embedding-2, keeps the default memory roots Markdown-only, disables memory-search fallback providers, and uploads matching binary content to the configured remote embedding provider.",
},
modalities: {
type: "array",
items: {
anyOf: [
{
type: "string",
const: "image",
},
{
type: "string",
const: "audio",
},
{
type: "string",
const: "all",
},
],
},
title: "Memory Search Multimodal Modalities",
description:
'Selects which multimodal file types are indexed from extraPaths: "image", "audio", or "all". Keep this narrow to avoid indexing large binary corpora unintentionally.',
},
maxFileBytes: {
type: "integer",
exclusiveMinimum: 0,
maximum: 9007199254740991,
title: "Memory Search Multimodal Max File Bytes",
description:
"Sets the maximum bytes allowed per multimodal file before it is skipped during memory indexing. Use this to cap upload cost and indexing latency, or raise it for short high-quality audio clips.",
},
},
additionalProperties: false,
title: "Memory Search Multimodal",
description:
'Optional multimodal memory settings for indexing image and audio files from configured extra paths. Keep this off unless your embedding model explicitly supports cross-modal embeddings, and set `memorySearch.fallback` to "none" while it is enabled. Matching files are uploaded to the configured remote embedding provider during indexing.',
},
experimental: {
type: "object",
properties: {
sessionMemory: {
type: "boolean",
title: "Memory Search Session Index (Experimental)",
description:
"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.",
},
},
additionalProperties: false,
},
provider: {
type: "string",
title: "Memory Search Provider",
description:
'Selects the embedding backend used to build/query memory vectors: "openai", "gemini", "voyage", "mistral", "bedrock", "lmstudio", "ollama", or "local". Keep your most reliable provider here and configure fallback for resilience.',
},
remote: {
type: "object",
properties: {
baseUrl: {
type: "string",
title: "Remote Embedding Base URL",
description:
"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.",
},
apiKey: {
anyOf: [
{
type: "string",
},
{
oneOf: [
{
type: "object",
properties: {
source: {
type: "string",
const: "env",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
pattern: "^[A-Z][A-Z0-9_]{0,127}$",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "file",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
{
type: "object",
properties: {
source: {
type: "string",
const: "exec",
},
provider: {
type: "string",
pattern: "^[a-z][a-z0-9_-]{0,63}$",
},
id: {
type: "string",
},
},
required: ["source", "provider", "id"],
additionalProperties: false,
},
],
},
],
title: "Remote Embedding API Key",
description:
"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.", | |
