From 914f73ac996ca758da4f2132e5266fba30372830 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 9 Aug 2026 20:30:43 -0700 Subject: [PATCH] docs: replace retired config keys with canonical schema keys (#121330) --- docs/channels/ambient-room-events.md | 8 +-- docs/channels/broadcast-groups.md | 61 +++++++++++----------- docs/channels/buzz.md | 8 +-- docs/channels/channel-routing.md | 8 ++- docs/channels/discord.md | 2 +- docs/channels/feishu.md | 18 +++---- docs/channels/imessage.md | 8 +-- docs/channels/slack.md | 6 ++- docs/channels/yuanbao.md | 10 ++-- docs/cli/config.md | 2 +- docs/cli/dns.md | 2 +- docs/concepts/delegate-architecture.md | 18 +++---- docs/concepts/experimental-features.md | 8 +-- docs/concepts/parallel-specialist-lanes.md | 1 - docs/concepts/queue.md | 12 ++--- docs/gateway/bonjour.md | 4 +- docs/gateway/config-agents.md | 5 +- docs/gateway/config-channels.md | 23 ++++---- docs/gateway/configuration-reference.md | 9 ++-- docs/gateway/configuration.md | 26 ++++----- docs/gateway/openshell.md | 8 +-- docs/gateway/sandboxing.md | 16 +++--- docs/gateway/security/index.md | 33 ++++++------ docs/help/faq.md | 11 ++-- docs/install/fly.md | 7 ++- docs/nodes/index.md | 8 +-- docs/plugins/codex-harness.md | 10 ++-- docs/plugins/hooks.md | 8 +-- docs/plugins/llama-cpp.md | 10 +--- docs/plugins/memory-wiki.md | 5 +- docs/plugins/sdk-agent-harness.md | 8 +-- docs/providers/alibaba.md | 6 ++- docs/providers/comfy.md | 24 ++++++--- docs/providers/fal.md | 36 ++++++++----- docs/providers/google.md | 18 ++++--- docs/providers/litellm.md | 8 +-- docs/providers/minimax.md | 6 +-- docs/providers/ollama.md | 30 ++++------- docs/providers/openai.md | 4 +- docs/providers/pixverse.md | 6 ++- docs/providers/qwen.md | 2 +- docs/providers/runway.md | 6 ++- docs/providers/together.md | 6 ++- docs/providers/vydra.md | 12 +++-- docs/providers/xai.md | 12 +++-- docs/reference/memory-config.md | 19 +++---- docs/tools/acp-agents.md | 11 ++-- docs/tools/browser-control.md | 3 +- docs/tools/browser.md | 2 +- docs/tools/image-generation.md | 52 ++++++++++-------- docs/tools/lobster.md | 16 +++--- docs/tools/loop-detection.md | 8 +-- docs/tools/music-generation.md | 20 ++++--- docs/tools/pdf.md | 4 +- docs/tools/skills-config.md | 10 ++-- docs/tools/skills.md | 10 ++-- docs/tools/slash-commands.md | 16 ++---- docs/tools/subagents.md | 8 +-- docs/tools/swarm.md | 9 ++-- docs/tools/tts.md | 8 +-- docs/tools/video-generation.md | 22 ++++---- 61 files changed, 397 insertions(+), 360 deletions(-) diff --git a/docs/channels/ambient-room-events.md b/docs/channels/ambient-room-events.md index 180bb599b600..55f5235c2b9e 100644 --- a/docs/channels/ambient-room-events.md +++ b/docs/channels/ambient-room-events.md @@ -182,15 +182,15 @@ Use an agent override when several agents share the same room but only one shoul }, }, agents: { - list: [ - { - id: "main", + entries: { + main: { + default: true, groupChat: { unmentionedInbound: "room_event", mentionPatterns: ["@openclaw", "openclaw"], }, }, - ], + }, }, } ``` diff --git a/docs/channels/broadcast-groups.md b/docs/channels/broadcast-groups.md index 3f1f58f0d96b..093487904f36 100644 --- a/docs/channels/broadcast-groups.md +++ b/docs/channels/broadcast-groups.md @@ -64,26 +64,24 @@ Every listed agent id must exist in `agents.entries`: config validation reports ```json { "agents": { - "list": [ - { - "id": "code-reviewer", + "entries": { + "code-reviewer": { + "default": true, "name": "Code Reviewer", "workspace": "/path/to/code-reviewer", "sandbox": { "mode": "all" } }, - { - "id": "security-auditor", + "security-auditor": { "name": "Security Auditor", "workspace": "/path/to/security-auditor", "sandbox": { "mode": "all" } }, - { - "id": "docs-generator", + "docs-generator": { "name": "Documentation Generator", "workspace": "/path/to/docs-generator", "sandbox": { "mode": "all" } } - ] + } }, "broadcast": { "strategy": "parallel", @@ -178,11 +176,11 @@ In group `120363403215116621@g.us` with agents `["alfred", "baerbel"]`: ```json { "agents": { - "list": [ - { "id": "security-scanner", "name": "Security Scanner" }, - { "id": "code-formatter", "name": "Code Formatter" }, - { "id": "test-generator", "name": "Test Generator" } - ] + "entries": { + "security-scanner": { "default": true, "name": "Security Scanner" }, + "code-formatter": { "name": "Code Formatter" }, + "test-generator": { "name": "Test Generator" } + } } } ``` @@ -191,10 +189,13 @@ In group `120363403215116621@g.us` with agents `["alfred", "baerbel"]`: ```json { "agents": { - "list": [ - { "id": "reviewer", "tools": { "allow": ["read", "exec"] } }, - { "id": "fixer", "tools": { "allow": ["read", "write", "edit", "exec"] } } - ] + "entries": { + "reviewer": { + "default": true, + "tools": { "allow": ["read", "exec"] } + }, + "fixer": { "tools": { "allow": ["read", "write", "edit", "exec"] } } + } } } ``` @@ -287,24 +288,22 @@ Broadcast groups work alongside existing routing: ] }, "agents": { - "list": [ - { - "id": "code-formatter", + "entries": { + "code-formatter": { + "default": true, "workspace": "~/agents/formatter", "tools": { "allow": ["read", "write"] } }, - { - "id": "security-scanner", + "security-scanner": { "workspace": "~/agents/security", "tools": { "allow": ["read", "exec"] } }, - { - "id": "test-coverage", + "test-coverage": { "workspace": "~/agents/testing", "tools": { "allow": ["read", "exec"] } }, - { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } } - ] + "docs-checker": { "workspace": "~/agents/docs", "tools": { "allow": ["read"] } } + } } } ``` @@ -320,11 +319,11 @@ Broadcast groups work alongside existing routing: "+15555550123": ["detect-language", "translator-en", "translator-de"] }, "agents": { - "list": [ - { "id": "detect-language", "workspace": "~/agents/lang-detect" }, - { "id": "translator-en", "workspace": "~/agents/translate-en" }, - { "id": "translator-de", "workspace": "~/agents/translate-de" } - ] + "entries": { + "detect-language": { "default": true, "workspace": "~/agents/lang-detect" }, + "translator-en": { "workspace": "~/agents/translate-en" }, + "translator-de": { "workspace": "~/agents/translate-de" } + } } } ``` diff --git a/docs/channels/buzz.md b/docs/channels/buzz.md index 00a697470bc2..dd71aae09b67 100644 --- a/docs/channels/buzz.md +++ b/docs/channels/buzz.md @@ -272,10 +272,10 @@ workspace, or model while one Gateway and Buzz bot serve all of them: ```json5 { agents: { - list: [ - { id: "support", workspace: "~/.openclaw/workspace-support" }, - { id: "engineering", workspace: "~/.openclaw/workspace-engineering" }, - ], + entries: { + support: { default: true, workspace: "~/.openclaw/workspace-support" }, + engineering: { workspace: "~/.openclaw/workspace-engineering" }, + }, }, bindings: [ { diff --git a/docs/channels/channel-routing.md b/docs/channels/channel-routing.md index d6ae5640a2ff..dfa502f2c34d 100644 --- a/docs/channels/channel-routing.md +++ b/docs/channels/channel-routing.md @@ -124,7 +124,13 @@ Example: ```json5 { agents: { - list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }], + entries: { + support: { + default: true, + name: "Support", + workspace: "~/.openclaw/workspace-support", + }, + }, }, bindings: [ { match: { channel: "slack", teamId: "T123" }, agentId: "support" }, diff --git a/docs/channels/discord.md b/docs/channels/discord.md index b1ca9206cde1..935717e91744 100644 --- a/docs/channels/discord.md +++ b/docs/channels/discord.md @@ -1689,7 +1689,7 @@ Primary reference: [Configuration reference - Discord](/gateway/config-channels# - startup/auth: `enabled`, `token`, `applicationId`, `accounts.*`, `allowBots` - policy: `groupPolicy`, `dmPolicy`, `allowFrom`, `dm.*`, `guilds.*`, `guilds.*.channels.*` -- command: `commands.native`, `commands.useAccessGroups` (global), `configWrites`, `slashCommand.ephemeral` +- command: `commands.native`, `commands.allowFrom` (global), `configWrites`, `slashCommand.ephemeral` - gateway: `proxy` - reply/history: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - delivery: `textChunkLimit` (default `2000`), `maxLinesPerMessage` (default `17`) diff --git a/docs/channels/feishu.md b/docs/channels/feishu.md index d0b197878b82..58a621f44660 100644 --- a/docs/channels/feishu.md +++ b/docs/channels/feishu.md @@ -404,9 +404,9 @@ Feishu/Lark supports ACP for DMs and group thread messages. Feishu/Lark ACP is t ```json5 { agents: { - list: [ - { - id: "codex", + entries: { + codex: { + default: true, runtime: { type: "acp", acp: { @@ -417,7 +417,7 @@ Feishu/Lark supports ACP for DMs and group thread messages. Feishu/Lark ACP is t }, }, }, - ], + }, }, bindings: [ { @@ -460,11 +460,11 @@ Use `bindings` to route Feishu/Lark DMs or groups to different agents. ```json5 { agents: { - list: [ - { id: "main" }, - { id: "agent-a", workspace: "/home/user/agent-a" }, - { id: "agent-b", workspace: "/home/user/agent-b" }, - ], + entries: { + main: { default: true }, + "agent-a": { workspace: "/home/user/agent-a" }, + "agent-b": { workspace: "/home/user/agent-b" }, + }, }, bindings: [ { diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md index 2bccbb28f945..46fc176b8bd8 100644 --- a/docs/channels/imessage.md +++ b/docs/channels/imessage.md @@ -411,15 +411,15 @@ Example: ```json5 { agents: { - list: [ - { - id: "codex", + entries: { + codex: { + default: true, runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent" }, }, }, - ], + }, }, bindings: [ { diff --git a/docs/channels/slack.md b/docs/channels/slack.md index 429c8d4fc6ff..c51aeb8d6718 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -2010,8 +2010,10 @@ openclaw pairing list slack Slack does not create or remove slash commands automatically. `commands.native: "auto"` does not enable Slack native commands; use `true` and create the matching commands in the Slack app. In HTTP mode, every Slack slash command must include the Gateway URL. In Socket Mode, command payloads arrive over the websocket and Slack ignores `slash_commands[].url`. - Also check `commands.useAccessGroups`, DM authorization, channel allowlists, - and per-channel `users` allowlists. Slack returns ephemeral errors for + Also check `commands.allowFrom` (when configured), DM authorization, + channel allowlists, and per-channel `users` allowlists. Access-group + entries in channel allowlists are resolved automatically. Slack returns + ephemeral errors for blocked slash-command senders, including: - `This channel is not allowed.` diff --git a/docs/channels/yuanbao.md b/docs/channels/yuanbao.md index 623883af8daf..8de0e65b8dd1 100644 --- a/docs/channels/yuanbao.md +++ b/docs/channels/yuanbao.md @@ -283,11 +283,11 @@ Use `bindings` to route Yuanbao DMs or groups to different agents: ```json5 { agents: { - list: [ - { id: "main" }, - { id: "agent-a", workspace: "/home/user/agent-a" }, - { id: "agent-b", workspace: "/home/user/agent-b" }, - ], + entries: { + main: { default: true }, + "agent-a": { workspace: "/home/user/agent-a" }, + "agent-b": { workspace: "/home/user/agent-b" }, + }, }, bindings: [ { diff --git a/docs/cli/config.md b/docs/cli/config.md index 1ad471ae40e7..9e18b6f1f7c5 100644 --- a/docs/cli/config.md +++ b/docs/cli/config.md @@ -201,7 +201,7 @@ Use `--replace` only when the provided value should intentionally become the com -SecretRef assignments are rejected on unsupported runtime-mutable surfaces (for example `hooks.token`, `commands.ownerDisplaySecret`, Discord thread-binding webhook tokens, and WhatsApp creds JSON). See [SecretRef Credential Surface](/reference/secretref-credential-surface). +SecretRef assignments are rejected on unsupported runtime-mutable surfaces (for example `hooks.token`, Discord thread-binding webhook tokens, and WhatsApp creds JSON). See [SecretRef Credential Surface](/reference/secretref-credential-surface). Batch parsing always uses the batch payload (`--batch-json`/`--batch-file`) as the source of truth; `--strict-json` / `--json` do not change batch parsing behavior. diff --git a/docs/cli/dns.md b/docs/cli/dns.md index a759b120d3b3..35b0f4336643 100644 --- a/docs/cli/dns.md +++ b/docs/cli/dns.md @@ -30,7 +30,7 @@ openclaw dns setup --apply | `--domain ` | Wide-area discovery domain (for example `openclaw.internal`). | | `--apply` | Install/update CoreDNS config and (re)start the service. Requires sudo, macOS only. | -Without `--domain`, OpenClaw uses `discovery.wideArea.domain` from config. +Without `--domain`, OpenClaw uses `discovery.wideArea.domain` from config. Setting that domain enables wide-area discovery. Without `--apply`, the command only prints: diff --git a/docs/concepts/delegate-architecture.md b/docs/concepts/delegate-architecture.md index abc6fac47be6..8186b124c65e 100644 --- a/docs/concepts/delegate-architecture.md +++ b/docs/concepts/delegate-architecture.md @@ -209,16 +209,15 @@ Route inbound messages to the delegate agent using [Multi-Agent Routing](/concep ```json5 { agents: { - list: [ - { id: "main", workspace: "~/.openclaw/workspace" }, - { - id: "delegate", + entries: { + main: { default: true, workspace: "~/.openclaw/workspace" }, + delegate: { workspace: "~/.openclaw/workspace-delegate", tools: { deny: ["browser", "canvas"], }, }, - ], + }, }, bindings: [ // Route a specific channel account to the delegate @@ -255,10 +254,9 @@ A complete delegate configuration handling email, calendar, and social media: ```json5 { agents: { - list: [ - { id: "main", default: true, workspace: "~/.openclaw/workspace" }, - { - id: "org-assistant", + entries: { + main: { default: true, workspace: "~/.openclaw/workspace" }, + "org-assistant": { name: "[Organization] Assistant", workspace: "~/.openclaw/workspace-org", agentDir: "~/.openclaw/agents/org-assistant/agent", @@ -268,7 +266,7 @@ A complete delegate configuration handling email, calendar, and social media: deny: ["write", "edit", "apply_patch", "browser", "canvas"], }, }, - ], + }, }, bindings: [ { diff --git a/docs/concepts/experimental-features.md b/docs/concepts/experimental-features.md index cdee28e7bda8..87c2e9bf0435 100644 --- a/docs/concepts/experimental-features.md +++ b/docs/concepts/experimental-features.md @@ -90,15 +90,15 @@ For one agent only: ```json5 { agents: { - list: [ - { - id: "local", + entries: { + local: { + default: true, model: "lmstudio/gemma-4-e4b-it", experimental: { localModelLean: true, }, }, - ], + }, }, } ``` diff --git a/docs/concepts/parallel-specialist-lanes.md b/docs/concepts/parallel-specialist-lanes.md index 76433ef185a9..38e34b502b7c 100644 --- a/docs/concepts/parallel-specialist-lanes.md +++ b/docs/concepts/parallel-specialist-lanes.md @@ -64,7 +64,6 @@ Tune queue and model capacity around the business value of each lane: messages: { queue: { mode: "collect", - debounceMs: 1000, cap: 20, drop: "summarize", }, diff --git a/docs/concepts/queue.md b/docs/concepts/queue.md index 90fab94a2b1f..68718d2dc98c 100644 --- a/docs/concepts/queue.md +++ b/docs/concepts/queue.md @@ -26,7 +26,7 @@ OpenClaw serializes inbound auto-reply runs (all channels) through a tiny in-pro When unset, all inbound channel surfaces use: - `mode: "steer"` -- `debounceMs: 500` +- a built-in 500ms debounce for steer, followup, and collect batching - `cap: 20` - `drop: "summarize"` @@ -50,10 +50,10 @@ Configure globally or per channel via `messages.queue`: messages: { queue: { mode: "steer", - debounceMs: 500, cap: 20, drop: "summarize", byChannel: { discord: "collect" }, + debounceMsByChannel: { discord: 1000 }, }, }, } @@ -61,15 +61,15 @@ Configure globally or per channel via `messages.queue`: ## Queue options -Options apply to queued delivery. `debounceMs` also sets the Codex steering quiet window in `steer` mode: +Per-session `/queue` options apply to queued delivery. The `debounce` option also sets the Codex steering quiet window in `steer` mode: -- `debounceMs`: quiet window before draining queued followups or collect batches; in Codex `steer` mode, quiet window before sending batched `turn/steer`. Bare numbers are milliseconds; units `ms`, `s`, `m`, `h`, and `d` are accepted by `/queue` options. +- `debounce`: quiet window before draining queued followups or collect batches; in Codex `steer` mode, quiet window before sending batched `turn/steer`. Bare numbers are milliseconds; units `ms`, `s`, `m`, `h`, and `d` are accepted. - `cap`: max queued messages per session. Values below `1` are ignored. - `drop: "summarize"` (default): drop the oldest queued entries as needed, keep compact summaries, and inject them as a synthetic followup prompt. - `drop: "old"`: drop the oldest queued entries as needed, without preserving summaries. - `drop: "new"`: reject the newest message when the queue is already full. -Defaults: `debounceMs: 500`, `cap: 20`, `drop: summarize`. +The queue uses a built-in 500ms debounce. `cap` defaults to `20`, and `drop` defaults to `summarize`. ## Steer and streaming @@ -90,7 +90,7 @@ For mode selection, OpenClaw resolves: 3. `messages.queue.mode`. 4. Default `steer`. -For options, inline or stored `/queue` options win over config. Then channel-specific debounce (`messages.queue.debounceMsByChannel`), plugin debounce defaults, global `messages.queue` options, and built-in defaults are applied, in that order. `cap` and `drop` are global/session options, not per-channel config keys. +For options, inline or stored `/queue` options win over config. Then channel-specific debounce (`messages.queue.debounceMsByChannel`), plugin debounce defaults, and built-in defaults are applied, in that order. `cap` and `drop` are global/session options, not per-channel config keys. ## Per-session overrides diff --git a/docs/gateway/bonjour.md b/docs/gateway/bonjour.md index 84595acebfe6..b35594cead40 100644 --- a/docs/gateway/bonjour.md +++ b/docs/gateway/bonjour.md @@ -23,11 +23,11 @@ If the node and gateway are on different networks, multicast mDNS can't cross th ```json5 { gateway: { bind: "tailnet" }, // tailnet-only (recommended) - discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } }, + discovery: { wideArea: { domain: "openclaw.internal" } }, } ``` -`discovery.wideArea.domain` also accepts the `OPENCLAW_WIDE_AREA_DOMAIN` env var as a fallback when unset. +Setting `discovery.wideArea.domain` enables wide-area discovery. OpenClaw also accepts the `OPENCLAW_WIDE_AREA_DOMAIN` env var as a fallback when the config key is unset. ### One-time DNS server setup (gateway host, macOS only) diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md index ed4cd48e1f54..76d9d9693b0a 100644 --- a/docs/gateway/config-agents.md +++ b/docs/gateway/config-agents.md @@ -1290,7 +1290,6 @@ Membership and visibility changes are written into the session transcript as sys ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all | off | none queue: { mode: "steer", // steer (default) | followup | collect | interrupt - debounceMs: 500, cap: 20, drop: "summarize", // old | new | summarize (default) byChannel: { @@ -1346,11 +1345,11 @@ Variables are case-insensitive. `{think}` is an alias for `{thinkingLevel}`. - `followup`: run the new prompt after the active run finishes. - `collect`: batch compatible messages and run them together later. - `interrupt`: abort the active run before starting the newest prompt. -- `debounceMs`: delay before dispatching a queued/steered message. Default: `500`. +- The queue uses a built-in 500ms debounce for steer, followup, and collect batching. - `cap`: maximum queued messages before the drop policy applies. Default: `20`. - `drop`: strategy when the cap is exceeded. `"summarize"` (default) drops oldest entries but keeps compact summaries; `"old"` drops oldest without summaries; `"new"` rejects the newest item. - `byChannel`: per-channel `mode` overrides keyed by provider id. -- `debounceMsByChannel`: per-channel `debounceMs` overrides keyed by provider id. +- `debounceMsByChannel`: per-channel debounce overrides in milliseconds, keyed by provider id. ### Inbound debounce diff --git a/docs/gateway/config-channels.md b/docs/gateway/config-channels.md index 40e2b1f79b7f..8d3703c30764 100644 --- a/docs/gateway/config-channels.md +++ b/docs/gateway/config-channels.md @@ -836,7 +836,12 @@ Fix: either pick a stronger tool-calling model, remove the explicit `"message_to }, }, agents: { - list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }], + entries: { + main: { + default: true, + groupChat: { mentionPatterns: ["@openclaw", "openclaw"] }, + }, + }, }, } ``` @@ -879,12 +884,12 @@ Include your own number in `allowFrom` to enable self-chat mode (ignores native }, }, agents: { - list: [ - { - id: "main", + entries: { + main: { + default: true, groupChat: { mentionPatterns: ["reisponde", "@openclaw"] }, }, - ], + }, }, } ``` @@ -905,13 +910,10 @@ Include your own number in `allowFrom` to enable self-chat mode (ignores native debug: false, // allow /debug restart: true, // allow /restart + external SIGUSR1 restart requests ownerAllowFrom: ["discord:123456789012345678"], - ownerDisplay: "raw", // raw | hash - ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", allowFrom: { "*": ["user1"], discord: ["user:123"], }, - useAccessGroups: true, }, } ``` @@ -934,9 +936,8 @@ Include your own number in `allowFrom` to enable self-chat mode (ignores native - For multi-account channels, `channels..accounts..configWrites` also gates writes that target that account (for example `/allowlist --config --account ` or `/config set channels..accounts....`). - `restart: false` disables `/restart` and external `SIGUSR1` restart requests. Default: `true`. - `ownerAllowFrom` is the explicit owner allowlist for owner-only commands and owner-gated channel actions. It is separate from `allowFrom`. -- `ownerDisplay: "hash"` hashes owner ids in the system prompt. Set `ownerDisplaySecret` to control hashing. -- `allowFrom` is per-provider. When set, it is the **only** authorization source (channel allowlists/pairing and `useAccessGroups` are ignored). -- `useAccessGroups: false` allows commands to bypass access-group policies when `allowFrom` is not set. +- `allowFrom` is per-provider. When set, it is the **only** authorization source for commands and directives. +- When `allowFrom` is unset, command authorization follows channel allowlists and pairing state. Access-group entries in channel allowlists are resolved automatically. - Command docs map: - built-in + bundled catalog: [Slash Commands](/tools/slash-commands) - channel-specific command surfaces: [Channels](/channels) diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index acb0709e2f62..bcf960c35d10 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -420,8 +420,7 @@ See [Plugins](/tools/plugin). ssrfPolicy: { // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access // allowPrivateNetwork: true, // legacy alias - // hostnameAllowlist: ["*.example.com", "example.com"], - // allowedHostnames: ["localhost"], + // allowedHostnames: ["*.example.com", "example.com", "localhost"], }, tabCleanup: { enabled: true, @@ -478,7 +477,7 @@ See [Plugins](/tools/plugin). - Set `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` only when you intentionally trust private-network browser navigation. - In strict mode, remote CDP profile endpoints (`profiles.*.cdpUrl`) are subject to the same private-network blocking during reachability/discovery checks. - `ssrfPolicy.allowPrivateNetwork` remains supported as a legacy alias. -- In strict mode, use `ssrfPolicy.hostnameAllowlist` and `ssrfPolicy.allowedHostnames` for explicit exceptions. +- In strict mode, use the wildcard-aware `ssrfPolicy.allowedHostnames` for exact-host and pattern exceptions. - Remote profiles are attach-only (start/stop/reset disabled). - `profiles.*.cdpUrl` accepts `http://`, `https://`, `ws://`, and `wss://`. Use HTTP(S) when you want OpenClaw to discover `/json/version`; use WS(S) @@ -1065,12 +1064,12 @@ Validation and safety notes: ```json5 { discovery: { - wideArea: { enabled: true }, + wideArea: { domain: "openclaw.internal" }, }, } ``` -Writes a unicast DNS-SD zone under `~/.openclaw/dns/`. For cross-network discovery, pair with a DNS server (CoreDNS recommended) + Tailscale split DNS. +Setting `discovery.wideArea.domain` enables wide-area discovery and writes a unicast DNS-SD zone under `~/.openclaw/dns/`. For cross-network discovery, pair with a DNS server (CoreDNS recommended) + Tailscale split DNS. Setup: `openclaw dns setup --apply`. diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 495105186ae2..c12493937809 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -201,14 +201,14 @@ candidate contains a redacted secret placeholder such as `***` or `[redacted]`. }, }, agents: { - list: [ - { - id: "main", + entries: { + main: { + default: true, groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, }, - ], + }, }, channels: { whatsapp: { @@ -235,11 +235,11 @@ candidate contains a redacted secret placeholder such as `***` or `[redacted]`. defaults: { skills: ["github", "weather"], }, - list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills - ], + entries: { + writer: { default: true }, // inherits github, weather + docs: { skills: ["docs-search"] }, // replaces defaults + "locked-down": { skills: [] }, // no skills + }, }, } ``` @@ -466,10 +466,10 @@ candidate contains a redacted secret placeholder such as `***` or `[redacted]`. ```json5 { agents: { - list: [ - { id: "home", default: true, workspace: "~/.openclaw/workspace-home" }, - { id: "work", workspace: "~/.openclaw/workspace-work" }, - ], + entries: { + home: { default: true, workspace: "~/.openclaw/workspace-home" }, + work: { workspace: "~/.openclaw/workspace-work" }, + }, }, bindings: [ { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }, diff --git a/docs/gateway/openshell.md b/docs/gateway/openshell.md index 27d00fb74cc6..efda2166c1b5 100644 --- a/docs/gateway/openshell.md +++ b/docs/gateway/openshell.md @@ -231,9 +231,9 @@ Sandbox-level settings (`mode`, `scope`, `workspaceAccess`) live under defaults: { sandbox: { mode: "off" }, }, - list: [ - { - id: "researcher", + entries: { + researcher: { + default: true, sandbox: { mode: "all", backend: "openshell", @@ -241,7 +241,7 @@ Sandbox-level settings (`mode`, `scope`, `workspaceAccess`) live under workspaceAccess: "rw", }, }, - ], + }, }, plugins: { entries: { diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md index 9ed9fa133f68..9854178b4fe4 100644 --- a/docs/gateway/sandboxing.md +++ b/docs/gateway/sandboxing.md @@ -311,9 +311,9 @@ This example gives the `research` agent a writable primary workspace, read-only scope: "agent", }, }, - list: [ - { - id: "research", + entries: { + research: { + default: true, workspace: "/srv/openclaw/research-workspace", sandbox: { workspaceAccess: "rw", @@ -324,7 +324,7 @@ This example gives the `research` agent a writable primary workspace, read-only }, }, }, - ], + }, }, } ``` @@ -364,16 +364,16 @@ openclaw sandbox recreate --agent research }, }, }, - list: [ - { - id: "build", + entries: { + build: { + default: true, sandbox: { docker: { binds: ["/mnt/cache:/cache:rw"], }, }, }, - ], + }, }, } ``` diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 433368c6089f..3728ad54164c 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -287,7 +287,7 @@ Hook payloads are untrusted content even when delivery comes from systems you co ## Command authorization -Slash commands and directives are honored only for authorized senders, derived from channel allowlists/pairing plus `commands.useAccessGroups` (see [Configuration](/gateway/configuration) and [Slash commands](/tools/slash-commands)). If a channel allowlist is empty or includes `"*"`, commands are effectively open for that channel. +Slash commands and directives are honored only for authorized senders. Configure an explicit per-provider `commands.allowFrom` list, or let command authorization follow channel allowlists and pairing state. Access-group entries referenced by channel allowlists are resolved automatically; there is no opt-in toggle. If a channel allowlist is empty or includes `"*"`, commands are effectively open for that channel. See [Access groups](/channels/access-groups) and [Slash commands](/tools/slash-commands). `/exec` is a session-only convenience for authorized operators - it does not write config or change other sessions. @@ -396,9 +396,13 @@ Common patterns: personal agent (full access, no sandbox), family/work agent (sa ```json5 { agents: { - list: [ - { id: "personal", workspace: "~/.openclaw/workspace-personal", sandbox: { mode: "off" } }, - ], + entries: { + personal: { + default: true, + workspace: "~/.openclaw/workspace-personal", + sandbox: { mode: "off" }, + }, + }, }, } ``` @@ -408,9 +412,9 @@ Common patterns: personal agent (full access, no sandbox), family/work agent (sa ```json5 { agents: { - list: [ - { - id: "family", + entries: { + family: { + default: true, workspace: "~/.openclaw/workspace-family", sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" }, tools: { @@ -418,7 +422,7 @@ Common patterns: personal agent (full access, no sandbox), family/work agent (sa deny: ["write", "edit", "apply_patch", "exec", "process", "browser"], }, }, - ], + }, }, } ``` @@ -428,9 +432,9 @@ Common patterns: personal agent (full access, no sandbox), family/work agent (sa ```json5 { agents: { - list: [ - { - id: "public", + entries: { + public: { + default: true, workspace: "~/.openclaw/workspace-public", sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" }, tools: { @@ -465,7 +469,7 @@ Common patterns: personal agent (full access, no sandbox), family/work agent (sa ], }, }, - ], + }, }, } ``` @@ -506,7 +510,7 @@ Private/internal destinations stay blocked unless you explicitly opt in. - Default: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` unset, so private/internal/special-use destinations stay blocked. Legacy alias `allowPrivateNetwork` still accepted. - Opt-in: set `dangerouslyAllowPrivateNetwork: true` to allow those destinations. -- In strict mode, use `hostnameAllowlist` (patterns like `*.example.com`) and `allowedHostnames` (exact host exceptions, including otherwise-blocked names like `localhost`) for explicit exceptions. +- In strict mode, use wildcard-aware `allowedHostnames` entries for patterns like `*.example.com` and exact host exceptions, including otherwise-blocked names like `localhost`. - Direct navigation requests are preflight checked. During the action and bounded post-action grace, guarded Playwright interactions (click, coordinate click, hover, drag, scroll, select, press, type, form fill, and evaluate) intercept policy-denied top-level and subframe document loads before HTTP request bytes, then best-effort re-check the final `http(s)` URL. - Before each fresh managed Chrome launch, OpenClaw best-effort disables network prediction, suppressing Chromium's observed speculative preconnect for those denied loads. This is defense in depth, not a policy boundary: a browser reused across a control-service restart and other browser backends may not share the hardening. Page routing remains request-level interception, not a network firewall: redirect hops, a popup's first request, Service Worker traffic, page code that runs after the bounded guard window, and some background/subresource paths can bypass it. Final-URL checks remain detection/quarantine defense; complete prevention requires owner-side egress isolation or a policy-enforcing proxy. @@ -515,8 +519,7 @@ Private/internal destinations stay blocked unless you explicitly opt in. browser: { ssrfPolicy: { dangerouslyAllowPrivateNetwork: false, - hostnameAllowlist: ["*.example.com", "example.com"], - allowedHostnames: ["localhost"], + allowedHostnames: ["*.example.com", "example.com", "localhost"], }, }, } diff --git a/docs/help/faq.md b/docs/help/faq.md index 8866bf186ef1..5dd68b651c52 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -150,20 +150,19 @@ First-run Q&A - install, onboard, auth routes, subscriptions, initial failures - ```json5 { agents: { - list: [ - { - id: "coder", + entries: { + coder: { + default: true, model: "xiaomi/mimo-v2.5-pro", thinkingDefault: "high", params: { temperature: 0.1 }, }, - { - id: "chat", + chat: { model: "xiaomi/mimo-v2.5-pro", thinkingDefault: "off", params: { temperature: 0.8 }, }, - ], + }, }, } ``` diff --git a/docs/install/fly.md b/docs/install/fly.md index 292c56664a5d..e729b58229e9 100644 --- a/docs/install/fly.md +++ b/docs/install/fly.md @@ -146,12 +146,11 @@ read_when: }, "maxConcurrent": 4 }, - "list": [ - { - "id": "main", + "entries": { + "main": { "default": true } - ] + } }, "auth": { "profiles": { diff --git a/docs/nodes/index.md b/docs/nodes/index.md index d741961e3d42..1e36f38c1bbd 100644 --- a/docs/nodes/index.md +++ b/docs/nodes/index.md @@ -525,12 +525,12 @@ Per-agent exec node override: ```json5 { agents: { - list: [ - { - id: "main", + entries: { + main: { + default: true, tools: { exec: { node: "build-node" } }, }, - ], + }, }, } ``` diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index 4c652903d390..c246a833f49d 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -562,18 +562,16 @@ Keep Claude as the default agent and add a named Codex agent: defaults: { model: "anthropic/claude-opus-4-6", }, - list: [ - { - id: "main", + entries: { + main: { default: true, model: "anthropic/claude-opus-4-6", }, - { - id: "codex", + codex: { name: "Codex", model: "openai/gpt-5.6-sol", }, - ], + }, }, } ``` diff --git a/docs/plugins/hooks.md b/docs/plugins/hooks.md index 601b5c1f4999..90085662c3c0 100644 --- a/docs/plugins/hooks.md +++ b/docs/plugins/hooks.md @@ -454,12 +454,12 @@ Load the file directly and restart the Gateway: ```json5 { agents: { - list: [ - { - id: "maintenance-agent", + entries: { + "maintenance-agent": { + default: true, workspace: "~/.openclaw/workspace-maintenance", }, - ], + }, }, bindings: [ { diff --git a/docs/plugins/llama-cpp.md b/docs/plugins/llama-cpp.md index 6a2c420530cb..36e9ea69dc32 100644 --- a/docs/plugins/llama-cpp.md +++ b/docs/plugins/llama-cpp.md @@ -113,14 +113,8 @@ Set `memory.search.provider` to `local`: `local.modelPath` defaults to the `hf:` URI shown above (`embeddinggemma-300m-qat-Q8_0.gguf`). Point it at a different `hf:` URI or a local `.gguf` file to use another -model. `local.modelCacheDir` overrides where downloaded models are cached -(default: `~/.node-llama-cpp/models`), and `local.contextSize` accepts an -integer or `"auto"`. - -When `local.contextSize` is numeric, the provider also gives that requirement -to node-llama-cpp's automatic GPU-layer placement. This lets node-llama-cpp fit -the model and embedding context together while retaining its memory-safety -checks. With `"auto"`, node-llama-cpp keeps its normal automatic placement. +model. Cache placement and embedding context sizing are managed by the +llama.cpp provider; `memory.search.local` exposes only `modelPath`. ## Native runtime diff --git a/docs/plugins/memory-wiki.md b/docs/plugins/memory-wiki.md index d6a4084e6e58..34d1140951f8 100644 --- a/docs/plugins/memory-wiki.md +++ b/docs/plugins/memory-wiki.md @@ -408,7 +408,10 @@ normalized agent id: ```json5 { agents: { - list: [{ id: "support" }, { id: "marketing" }], + entries: { + support: { default: true }, + marketing: {}, + }, }, plugins: { entries: { diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md index fc10551a8abe..05b3ce2a833e 100644 --- a/docs/plugins/sdk-agent-harness.md +++ b/docs/plugins/sdk-agent-harness.md @@ -448,9 +448,9 @@ Per-agent overrides use the same model-scoped shape: ```json { "agents": { - "list": [ - { - "id": "codex-only", + "entries": { + "codex-only": { + "default": true, "model": "openai/gpt-5.6-sol", "models": { "openai/gpt-5.6-sol": { @@ -458,7 +458,7 @@ Per-agent overrides use the same model-scoped shape: } } } - ] + } } } ``` diff --git a/docs/providers/alibaba.md b/docs/providers/alibaba.md index 0a5d2dbf2021..07d49cf96091 100644 --- a/docs/providers/alibaba.md +++ b/docs/providers/alibaba.md @@ -48,8 +48,10 @@ The bundled `alibaba` plugin registers a video-generation provider for Wan model { agents: { defaults: { - videoGenerationModel: { - primary: "alibaba/wan2.6-t2v", + mediaModels: { + video: { + primary: "alibaba/wan2.6-t2v", + }, }, }, }, diff --git a/docs/providers/comfy.md b/docs/providers/comfy.md index 1a8158004f19..6d6ae4cf7435 100644 --- a/docs/providers/comfy.md +++ b/docs/providers/comfy.md @@ -78,8 +78,10 @@ Choose between running ComfyUI on your own machine or using Comfy Cloud. { agents: { defaults: { - imageGenerationModel: { - primary: "comfy/workflow", + mediaModels: { + image: { + primary: "comfy/workflow", + }, }, }, }, @@ -153,8 +155,10 @@ Choose between running ComfyUI on your own machine or using Comfy Cloud. { agents: { defaults: { - imageGenerationModel: { - primary: "comfy/workflow", + mediaModels: { + image: { + primary: "comfy/workflow", + }, }, }, }, @@ -250,8 +254,10 @@ The `image` and `video` sections also support a reference-image input node: { agents: { defaults: { - imageGenerationModel: { - primary: "comfy/workflow", + mediaModels: { + image: { + primary: "comfy/workflow", + }, }, }, }, @@ -291,8 +297,10 @@ The `image` and `video` sections also support a reference-image input node: { agents: { defaults: { - videoGenerationModel: { - primary: "comfy/workflow", + mediaModels: { + video: { + primary: "comfy/workflow", + }, }, }, }, diff --git a/docs/providers/fal.md b/docs/providers/fal.md index adebd7972c5b..2cc23bf8520c 100644 --- a/docs/providers/fal.md +++ b/docs/providers/fal.md @@ -35,8 +35,10 @@ generation. { agents: { defaults: { - imageGenerationModel: { - primary: "fal/fal-ai/flux/dev", + mediaModels: { + image: { + primary: "fal/fal-ai/flux/dev", + }, }, }, }, @@ -110,8 +112,10 @@ To use Krea 2 Medium: { agents: { defaults: { - imageGenerationModel: { - primary: "fal/krea/v2/medium/text-to-image", + mediaModels: { + image: { + primary: "fal/krea/v2/medium/text-to-image", + }, }, }, }, @@ -166,8 +170,10 @@ The bundled `fal` video-generation provider defaults to { agents: { defaults: { - videoGenerationModel: { - primary: "fal/bytedance/seedance-2.0/fast/text-to-video", + mediaModels: { + video: { + primary: "fal/bytedance/seedance-2.0/fast/text-to-video", + }, }, }, }, @@ -180,8 +186,10 @@ The bundled `fal` video-generation provider defaults to { agents: { defaults: { - videoGenerationModel: { - primary: "fal/bytedance/seedance-2.0/fast/reference-to-video", + mediaModels: { + video: { + primary: "fal/bytedance/seedance-2.0/fast/reference-to-video", + }, }, }, }, @@ -200,8 +208,10 @@ The bundled `fal` video-generation provider defaults to { agents: { defaults: { - videoGenerationModel: { - primary: "fal/fal-ai/heygen/v2/video-agent", + mediaModels: { + video: { + primary: "fal/fal-ai/heygen/v2/video-agent", + }, }, }, }, @@ -228,8 +238,10 @@ Use fal as the default music provider: { agents: { defaults: { - musicGenerationModel: { - primary: "fal/fal-ai/minimax-music/v2.6", + mediaModels: { + music: { + primary: "fal/fal-ai/minimax-music/v2.6", + }, }, }, }, diff --git a/docs/providers/google.md b/docs/providers/google.md index f2cfcd80aeed..c7be4f28c281 100644 --- a/docs/providers/google.md +++ b/docs/providers/google.md @@ -224,8 +224,10 @@ To use Google as the default image provider: { agents: { defaults: { - imageGenerationModel: { - primary: "google/gemini-3.1-flash-image", + mediaModels: { + image: { + primary: "google/gemini-3.1-flash-image", + }, }, }, }, @@ -252,8 +254,10 @@ To use Google as the default video provider: { agents: { defaults: { - videoGenerationModel: { - primary: "google/veo-3.1-fast-generate-preview", + mediaModels: { + video: { + primary: "google/veo-3.1-fast-generate-preview", + }, }, }, }, @@ -282,8 +286,10 @@ To use Google as the default music provider: { agents: { defaults: { - musicGenerationModel: { - primary: "google/lyria-3-clip-preview", + mediaModels: { + music: { + primary: "google/lyria-3-clip-preview", + }, }, }, }, diff --git a/docs/providers/litellm.md b/docs/providers/litellm.md index 0629bc4511a3..94c83cc4eaa3 100644 --- a/docs/providers/litellm.md +++ b/docs/providers/litellm.md @@ -104,9 +104,11 @@ LiteLLM can back the `image_generate` tool through OpenAI-compatible `/images/ge }, agents: { defaults: { - imageGenerationModel: { - primary: "litellm/gpt-image-2", - timeoutMs: 180_000, + mediaModels: { + image: { + primary: "litellm/gpt-image-2", + timeoutMs: 180000, + }, }, }, }, diff --git a/docs/providers/minimax.md b/docs/providers/minimax.md index 6d898cf02b39..41684fed0589 100644 --- a/docs/providers/minimax.md +++ b/docs/providers/minimax.md @@ -213,7 +213,7 @@ The MiniMax plugin registers the `image-01` model for the `image_generate` tool { agents: { defaults: { - imageGenerationModel: { primary: "minimax/image-01" }, + mediaModels: { image: { primary: "minimax/image-01" } }, }, }, } @@ -260,7 +260,7 @@ The bundled MiniMax plugin registers music generation through the shared `music_ { agents: { defaults: { - musicGenerationModel: { primary: "minimax/music-2.6" }, + mediaModels: { music: { primary: "minimax/music-2.6" } }, }, }, } @@ -283,7 +283,7 @@ The bundled MiniMax plugin registers video generation through the shared `video_ { agents: { defaults: { - videoGenerationModel: { primary: "minimax/MiniMax-Hailuo-2.3" }, + mediaModels: { video: { primary: "minimax/MiniMax-Hailuo-2.3" } }, }, }, } diff --git a/docs/providers/ollama.md b/docs/providers/ollama.md index 5ffaff2a10de..c9453df4afff 100644 --- a/docs/providers/ollama.md +++ b/docs/providers/ollama.md @@ -727,15 +727,15 @@ Replace model IDs with exact names from `ollama list` or ```json5 { agents: { - list: [ - { - id: "local", + entries: { + local: { + default: true, experimental: { localModelLean: true, }, model: { primary: "ollama/gemma4" }, }, - ], + }, }, models: { providers: { @@ -1077,28 +1077,17 @@ For full setup and behavior, see [Ollama Web Search](/tools/ollama-search). | --- | --- | | Default model | `nomic-embed-text` | | Auto-pull | Yes, if not present locally | - | Default inline concurrency | 1 (other providers default higher; raise with `nonBatchConcurrency` if the host can take it) | + | Embedding concurrency | Provider-owned; no memory-search tuning key is required | Query-time embeddings use retrieval prefixes for models that require or recommend them: `nomic-embed-text`, `qwen3-embedding`, and `mxbai-embed-large`. Document batches stay raw, so existing indexes need no format migration. - ```json5 - { - memory: { - search: { - provider: "ollama", - remote: { - // Default for Ollama. Raise on larger hosts if reindexing is too slow. - nonBatchConcurrency: 1, - }, - }, - }, - } - ``` - - For a remote embedding host, keep auth scoped to that host: + Embedding concurrency and batching behavior are owned by the Ollama + memory provider. For a remote embedding host, use the supported + `remote.baseUrl` and `remote.apiKey` fields to keep auth scoped to that + host: ```json5 { @@ -1109,7 +1098,6 @@ For full setup and behavior, see [Ollama Web Search](/tools/ollama-search). remote: { baseUrl: "http://gpu-box.local:11434", apiKey: "ollama-local", - nonBatchConcurrency: 2, }, }, }, diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 992830b3b157..131e72c11a4f 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -690,7 +690,7 @@ generation through the same `openai/gpt-image-2` model ref. { agents: { defaults: { - imageGenerationModel: { primary: "openai/gpt-image-2" }, + mediaModels: { image: { primary: "openai/gpt-image-2" } }, }, }, } @@ -786,7 +786,7 @@ uploaded video in the `video` field. { agents: { defaults: { - videoGenerationModel: { primary: "openai/sora-2" }, + mediaModels: { video: { primary: "openai/sora-2" } }, }, }, } diff --git a/docs/providers/pixverse.md b/docs/providers/pixverse.md index 78e9bf5a8db7..d55ca2ed06d3 100644 --- a/docs/providers/pixverse.md +++ b/docs/providers/pixverse.md @@ -94,8 +94,10 @@ The video provider accepts these optional provider-specific keys: { agents: { defaults: { - videoGenerationModel: { - primary: "pixverse/v6", + mediaModels: { + video: { + primary: "pixverse/v6", + }, }, }, }, diff --git a/docs/providers/qwen.md b/docs/providers/qwen.md index 0869dd9b6f87..7912c1162cf4 100644 --- a/docs/providers/qwen.md +++ b/docs/providers/qwen.md @@ -278,7 +278,7 @@ To make Qwen the default video provider: { agents: { defaults: { - videoGenerationModel: { primary: "qwen/wan2.6-t2v" }, + mediaModels: { video: { primary: "qwen/wan2.6-t2v" } }, }, }, } diff --git a/docs/providers/runway.md b/docs/providers/runway.md index 0fba1b591957..2967ce5d737e 100644 --- a/docs/providers/runway.md +++ b/docs/providers/runway.md @@ -68,8 +68,10 @@ Local image and video references are supported via data URIs. { agents: { defaults: { - videoGenerationModel: { - primary: "runway/gen4.5", + mediaModels: { + video: { + primary: "runway/gen4.5", + }, }, }, }, diff --git a/docs/providers/together.md b/docs/providers/together.md index 469a7107b590..f9f333678781 100644 --- a/docs/providers/together.md +++ b/docs/providers/together.md @@ -88,8 +88,10 @@ To use Together as the default video provider: { agents: { defaults: { - videoGenerationModel: { - primary: "together/Wan-AI/Wan2.2-T2V-A14B", + mediaModels: { + video: { + primary: "together/Wan-AI/Wan2.2-T2V-A14B", + }, }, }, }, diff --git a/docs/providers/vydra.md b/docs/providers/vydra.md index ca8af9398071..b3ea969cd15c 100644 --- a/docs/providers/vydra.md +++ b/docs/providers/vydra.md @@ -69,8 +69,10 @@ Use `https://www.vydra.ai/api/v1` as the base URL. Vydra's apex host (`https://v { agents: { defaults: { - imageGenerationModel: { - primary: "vydra/grok-imagine", + mediaModels: { + image: { + primary: "vydra/grok-imagine", + }, }, }, }, @@ -97,8 +99,10 @@ Use `https://www.vydra.ai/api/v1` as the base URL. Vydra's apex host (`https://v { agents: { defaults: { - videoGenerationModel: { - primary: "vydra/veo3", + mediaModels: { + video: { + primary: "vydra/veo3", + }, }, }, }, diff --git a/docs/providers/xai.md b/docs/providers/xai.md index d6144e9c911b..d44db2078acf 100644 --- a/docs/providers/xai.md +++ b/docs/providers/xai.md @@ -268,8 +268,10 @@ stale context metadata on active 4.20 rows. It does not pin active 4.20 { agents: { defaults: { - videoGenerationModel: { - primary: "xai/grok-imagine-video", + mediaModels: { + video: { + primary: "xai/grok-imagine-video", + }, }, }, }, @@ -309,8 +311,10 @@ stale context metadata on active 4.20 rows. It does not pin active 4.20 { agents: { defaults: { - imageGenerationModel: { - primary: "xai/grok-imagine-image", + mediaModels: { + image: { + primary: "xai/grok-imagine-image", + }, }, }, }, diff --git a/docs/reference/memory-config.md b/docs/reference/memory-config.md index 0253d1107c8d..80a55bb83e6c 100644 --- a/docs/reference/memory-config.md +++ b/docs/reference/memory-config.md @@ -316,11 +316,9 @@ Use `provider: "openai-compatible"` for a generic OpenAI-compatible - | Key | Type | Default | Description | - | --------------------- | ------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `local.modelPath` | `string` | auto-downloaded | Path to GGUF model file | - | `local.modelCacheDir` | `string` | node-llama-cpp default | Cache dir for downloaded models | - | `local.contextSize` | `number \| "auto"` | `4096` | Context window size for the embedding context. 4096 covers typical chunks (128-512 tokens) while bounding non-weight VRAM. Lower to 1024-2048 on constrained hosts. `"auto"` uses the model's trained maximum -- not recommended for 8B+ models (Qwen3-Embedding-8B: up to 40 960 tokens can push VRAM to ~32 GB). | + | Key | Type | Default | Description | + | ----------------- | -------- | --------------- | ----------------------- | + | `local.modelPath` | `string` | auto-downloaded | Path to GGUF model file | Install the official llama.cpp provider first: `openclaw plugins install @openclaw/llama-cpp-provider`. Default model: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, auto-downloaded). Source checkouts still require native build approval: `pnpm approve-builds` then `pnpm rebuild node-llama-cpp`. @@ -332,7 +330,7 @@ Use `provider: "openai-compatible"` for a generic OpenAI-compatible openclaw memory index --force --agent main ``` - Numeric `local.contextSize` values also inform node-llama-cpp's automatic GPU-layer placement so model weights and the requested embedding context are fitted together. `openclaw memory status --deep` reports last-known llama.cpp backend, device, offload, requested-context, and timestamped memory facts after the runtime has loaded; passive status does not load a model. + Cache placement and embedding context sizing are provider-owned. `openclaw memory status --deep` reports last-known llama.cpp backend, device, offload, requested-context, and timestamped memory facts after the runtime has loaded; passive status does not load a model. Set `provider: "local"` explicitly for local GGUF embeddings. `hf:` and HTTP(S) model references are supported for explicit local configs (via node-llama-cpp's model resolution), but they do not change the default provider. @@ -435,14 +433,13 @@ Prevents re-embedding unchanged text during reindex or transcript updates. ## Batch indexing -| Key | Type | Default | Description | -| ---------------------------- | --------- | ------- | -------------------------- | -| `remote.nonBatchConcurrency` | `number` | `4` | Parallel inline embeddings | -| `remote.batch.enabled` | `boolean` | `false` | Enable batch embedding API | +| Key | Type | Default | Description | +| ---------------------- | --------- | ------- | -------------------------- | +| `remote.batch.enabled` | `boolean` | `false` | Enable batch embedding API | Available for `gemini`, `openai`, and `voyage`. OpenAI batch is typically fastest and cheapest for large backfills. -Concurrency, polling, and timeout behavior are provider-owned. +Batch enablement is the only remote batching setting. Concurrency, polling, and timeout behavior are provider-owned. --- diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index c04e9e2a52f1..a124bb6e9805 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -377,9 +377,9 @@ Use `agents.entries.*.runtime` to define ACP defaults once per agent: ```json5 { agents: { - list: [ - { - id: "codex", + entries: { + codex: { + default: true, runtime: { type: "acp", acp: { @@ -390,14 +390,13 @@ Use `agents.entries.*.runtime` to define ACP defaults once per agent: }, }, }, - { - id: "claude", + claude: { runtime: { type: "acp", acp: { agent: "claude", backend: "acpx", mode: "persistent" }, }, }, - ], + }, }, bindings: [ { diff --git a/docs/tools/browser-control.md b/docs/tools/browser-control.md index fe09c88bbf26..764674f065bf 100644 --- a/docs/tools/browser-control.md +++ b/docs/tools/browser-control.md @@ -474,8 +474,7 @@ Strict-mode example (block private/internal destinations by default): browser: { ssrfPolicy: { dangerouslyAllowPrivateNetwork: false, - hostnameAllowlist: ["*.example.com", "example.com"], - allowedHostnames: ["localhost"], // optional exact allow + allowedHostnames: ["*.example.com", "example.com", "localhost"], }, }, } diff --git a/docs/tools/browser.md b/docs/tools/browser.md index c89a6f865a84..ad7948640fbb 100644 --- a/docs/tools/browser.md +++ b/docs/tools/browser.md @@ -907,7 +907,7 @@ Important behavior details: Security guidance: - Do **not** relax browser SSRF policy by default. -- Prefer narrow host exceptions such as `hostnameAllowlist` or `allowedHostnames` over broad private-network access. +- Prefer narrow wildcard-aware `allowedHostnames` exceptions over broad private-network access. - Use `dangerouslyAllowPrivateNetwork: true` only in intentionally trusted environments where private-network browser access is required and reviewed. ## Agent tools + how control works diff --git a/docs/tools/image-generation.md b/docs/tools/image-generation.md index b040fba230e9..97d584106572 100644 --- a/docs/tools/image-generation.md +++ b/docs/tools/image-generation.md @@ -37,9 +37,11 @@ or sign in with OpenAI ChatGPT/Codex OAuth. { agents: { defaults: { - imageGenerationModel: { - primary: "openai/gpt-image-2", - timeoutMs: 180_000, + mediaModels: { + image: { + primary: "openai/gpt-image-2", + timeoutMs: 180000, + }, }, }, }, @@ -209,14 +211,16 @@ translation. { agents: { defaults: { - imageGenerationModel: { - primary: "openai/gpt-image-2", - timeoutMs: 180_000, - fallbacks: [ - "openrouter/google/gemini-3.1-flash-image-preview", - "google/gemini-3.1-flash-image", - "fal/fal-ai/flux/dev", - ], + mediaModels: { + image: { + primary: "openai/gpt-image-2", + timeoutMs: 180000, + fallbacks: [ + "openrouter/google/gemini-3.1-flash-image-preview", + "google/gemini-3.1-flash-image", + "fal/fal-ai/flux/dev", + ], + }, }, }, }, @@ -228,8 +232,8 @@ translation. OpenClaw tries providers in this order: 1. **`model` parameter** from the tool call (if the agent specifies one). -2. **`imageGenerationModel.primary`** from config. -3. **`imageGenerationModel.fallbacks`** in order. +2. **`agents.defaults.mediaModels.image.primary`** from config. +3. **`agents.defaults.mediaModels.image.fallbacks`** in order. 4. **Auto-detection** - auth-backed provider defaults only: - current default provider first; - remaining registered image-generation providers in provider-id order. @@ -360,9 +364,11 @@ and ComfyUI support 1. { agents: { defaults: { - imageGenerationModel: { - primary: "microsoft-foundry/", - timeoutMs: 600_000, + mediaModels: { + image: { + primary: "microsoft-foundry/", + timeoutMs: 600000, + }, }, }, }, @@ -400,8 +406,10 @@ and ComfyUI support 1. { agents: { defaults: { - imageGenerationModel: { - primary: "openrouter/google/gemini-3.1-flash-image-preview", + mediaModels: { + image: { + primary: "openrouter/google/gemini-3.1-flash-image-preview", + }, }, }, }, @@ -431,8 +439,10 @@ and ComfyUI support 1. { agents: { defaults: { - imageGenerationModel: { - primary: "fal/krea/v2/medium/text-to-image", + mediaModels: { + image: { + primary: "fal/krea/v2/medium/text-to-image", + }, }, }, }, @@ -567,5 +577,5 @@ as ignored for them. - [OpenAI](/providers/openai) - OpenAI Images provider setup - [Vydra](/providers/vydra) - Vydra image, video, and speech setup - [xAI](/providers/xai) - Grok image, video, search, code execution, and TTS setup -- [Configuration reference](/gateway/config-agents#agent-defaults) - `imageGenerationModel` config +- [Configuration reference](/gateway/config-agents#agent-defaults) - `agents.defaults.mediaModels.image` config - [Models](/concepts/models) - model configuration and failover diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md index ad99e2390d04..1d6fe52c663b 100644 --- a/docs/tools/lobster.md +++ b/docs/tools/lobster.md @@ -92,14 +92,14 @@ Or per-agent: ```json { "agents": { - "list": [ - { - "id": "main", + "entries": { + "main": { + "default": true, "tools": { "alsoAllow": ["lobster"] } } - ] + } } } ``` @@ -166,12 +166,12 @@ For a **structured LLM step** inside a workflow, enable the optional } }, "agents": { - "list": [ - { - "id": "main", + "entries": { + "main": { + "default": true, "tools": { "alsoAllow": ["llm-task"] } } - ] + } } } ``` diff --git a/docs/tools/loop-detection.md b/docs/tools/loop-detection.md index 6a6150cde816..15e7eaf00ba3 100644 --- a/docs/tools/loop-detection.md +++ b/docs/tools/loop-detection.md @@ -48,16 +48,16 @@ Per-agent override (optional, at `agents.entries.*.tools.loopDetection`): ```json5 { agents: { - list: [ - { - id: "safe-runner", + entries: { + "safe-runner": { + default: true, tools: { loopDetection: { enabled: true, }, }, }, - ], + }, }, } ``` diff --git a/docs/tools/music-generation.md b/docs/tools/music-generation.md index 046cb8e5f7b7..512b19c43335 100644 --- a/docs/tools/music-generation.md +++ b/docs/tools/music-generation.md @@ -41,8 +41,10 @@ idempotent direct fallback with just the missing audio. { agents: { defaults: { - musicGenerationModel: { - primary: "google/lyria-3-clip-preview", + mediaModels: { + music: { + primary: "google/lyria-3-clip-preview", + }, }, }, }, @@ -238,9 +240,11 @@ openclaw tasks cancel { agents: { defaults: { - musicGenerationModel: { - primary: "google/lyria-3-clip-preview", - fallbacks: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"], + mediaModels: { + music: { + primary: "google/lyria-3-clip-preview", + fallbacks: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"], + }, }, }, }, @@ -252,8 +256,8 @@ openclaw tasks cancel OpenClaw tries providers in this order: 1. `model` parameter from the tool call (if the agent specifies one). -2. `musicGenerationModel.primary` from config. -3. `musicGenerationModel.fallbacks` in order. +2. `agents.defaults.mediaModels.music.primary` from config. +3. `agents.defaults.mediaModels.music.fallbacks` in order. 4. Auto-detection using auth-backed provider defaults only: - current default text-model provider first, if it also offers music generation; @@ -382,7 +386,7 @@ sections are configured. - [Background tasks](/automation/tasks) — task tracking for detached `music_generate` runs - [ComfyUI](/providers/comfy) -- [Configuration reference](/gateway/config-agents#agent-defaults) — `musicGenerationModel` config +- [Configuration reference](/gateway/config-agents#agent-defaults) — `agents.defaults.mediaModels.music` config - [Google (Gemini)](/providers/google) - [MiniMax](/providers/minimax) - [Models](/concepts/models) — model configuration and failover diff --git a/docs/tools/pdf.md b/docs/tools/pdf.md index ad2178274ec3..57ba9c6e26ac 100644 --- a/docs/tools/pdf.md +++ b/docs/tools/pdf.md @@ -100,7 +100,7 @@ Details: primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - pdfMaxBytesMb: 10, + pdfMaxMb: 10, pdfMaxPages: 20, }, }, @@ -186,4 +186,4 @@ Encrypted PDF with extraction fallback: ## Related - [Tools Overview](/tools) - all available agent tools -- [Configuration Reference](/gateway/config-agents#agent-defaults) - pdfMaxBytesMb and pdfMaxPages config +- [Configuration Reference](/gateway/config-agents#agent-defaults) - `pdfMaxMb` and `pdfMaxPages` config diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md index 690aa4ddace4..b3402ce515b6 100644 --- a/docs/tools/skills-config.md +++ b/docs/tools/skills-config.md @@ -294,11 +294,11 @@ different visible skill set per agent. defaults: { skills: ["github", "weather"], // shared baseline }, - list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults entirely - { id: "locked-down", skills: [] }, // no skills - ], + entries: { + writer: { default: true }, // inherits github, weather + docs: { skills: ["docs-search"] }, // replaces defaults entirely + "locked-down": { skills: [] }, // no skills + }, }, } ``` diff --git a/docs/tools/skills.md b/docs/tools/skills.md index d49efa1ab201..bf10191931bd 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -106,11 +106,11 @@ regardless of where they are loaded from. defaults: { skills: ["github", "weather"], // shared baseline }, - list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults entirely - { id: "locked-down", skills: [] }, // no skills - ], + entries: { + writer: { default: true }, // inherits github, weather + docs: { skills: ["docs-search"] }, // replaces defaults entirely + "locked-down": { skills: [] }, // no skills + }, }, } ``` diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md index 171fa3d6206c..d3b1270af0a9 100644 --- a/docs/tools/slash-commands.md +++ b/docs/tools/slash-commands.md @@ -68,13 +68,10 @@ command handling is enabled for the surface. debug: false, restart: true, ownerAllowFrom: ["discord:123456789012345678"], - ownerDisplay: "raw", - ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", allowFrom: { "*": ["user1"], discord: ["user:123"], }, - useAccessGroups: true, }, } ``` @@ -139,20 +136,17 @@ command handling is enabled for the surface. scope. A wildcard `allowFrom` entry is **not** sufficient. - - Controls how owner ids appear in the system prompt. - - - - HMAC secret used when `commands.ownerDisplay: "hash"`. - - Per-provider allowlist for command authorization. When configured, it is the **only** authorization source for commands and directives. Use `"*"` for a global default; provider-specific keys override it. +When `commands.allowFrom` is not configured, command authorization follows +the channel's allowlists and pairing state. Access-group entries referenced by +channel allowlists are resolved automatically; there is no command-level +access-group toggle. + ## Command list Commands come from three sources: diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index 5cdf97eea4c5..d3b7489fda9b 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -175,12 +175,12 @@ Per-agent override: `agents.entries.*.subagents.delegationMode`. maxConcurrent: 4, }, }, - list: [ - { - id: "coordinator", + entries: { + coordinator: { + default: true, subagents: { delegationMode: "prefer" }, }, - ], + }, }, } ``` diff --git a/docs/tools/swarm.md b/docs/tools/swarm.md index 8d4a89890317..01290a5f7298 100644 --- a/docs/tools/swarm.md +++ b/docs/tools/swarm.md @@ -252,14 +252,13 @@ it can be spawned but cannot start swarms from its own top-level sessions: { tools: { swarm: { enabled: true, defaultAgentId: "worker" } }, agents: { - list: [ - { - id: "main", + entries: { + main: { default: true, subagents: { allowAgents: ["worker"] }, }, - { id: "worker", tools: { swarm: false } }, - ], + worker: { tools: { swarm: false } }, + }, }, } ``` diff --git a/docs/tools/tts.md b/docs/tools/tts.md index 6e3591e1e72e..424a431e317c 100644 --- a/docs/tools/tts.md +++ b/docs/tools/tts.md @@ -528,16 +528,16 @@ voice, model, persona, or auto-TTS mode. The agent block deep-merges over }, }, agents: { - list: [ - { - id: "reader", + entries: { + reader: { + default: true, tts: { providers: { elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" }, }, }, }, - ], + }, }, } ``` diff --git a/docs/tools/video-generation.md b/docs/tools/video-generation.md index 9e59bc224750..c88e38972571 100644 --- a/docs/tools/video-generation.md +++ b/docs/tools/video-generation.md @@ -289,8 +289,8 @@ aggregated error includes the skip reason for each. OpenClaw resolves the model in this order: 1. **`model` tool parameter** - if the agent specifies one in the call. -2. **`videoGenerationModel.primary`** from config. -3. **`videoGenerationModel.fallbacks`** in order. +2. **`agents.defaults.mediaModels.video.primary`** from config. +3. **`agents.defaults.mediaModels.video.fallbacks`** in order. 4. **Auto-detection** - providers that have valid auth, starting with the current default provider, then remaining providers in alphabetical order. @@ -305,10 +305,12 @@ Automatic fallback across authenticated providers is always enabled. A per-call { agents: { defaults: { - videoGenerationModel: { - primary: "google/veo-3.1-fast-generate-preview", - fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"], - timeoutMs: 180000, // optional per-tool provider request timeout override + mediaModels: { + video: { + primary: "google/veo-3.1-fast-generate-preview", + fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"], + timeoutMs: 180000, // optional per-tool provider request timeout override + }, }, }, }, @@ -525,9 +527,11 @@ Set the default video-generation model in your OpenClaw config: { agents: { defaults: { - videoGenerationModel: { - primary: "qwen/wan2.6-t2v", - fallbacks: ["qwen/wan2.6-r2v-flash"], + mediaModels: { + video: { + primary: "qwen/wan2.6-t2v", + fallbacks: ["qwen/wan2.6-r2v-flash"], + }, }, }, },