ewilliams28/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-08-12 21:53:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: replace retired config keys with canonical schema keys (#121330)

Browse Source
This commit is contained in:
Peter Steinberger
2026-08-09 20:30:43 -07:00
committed by GitHub
parent 6c1879e5e7
commit 914f73ac99
61 changed files with 397 additions and 360 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/channels/ambient-room-events.md
+4 -4
View File
@@ -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"],
},
},
],
},
},
}
```
docs/channels/broadcast-groups.md
+30 -31
View File
@@ -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" }
}
}
}
```
docs/channels/buzz.md
+4 -4
View File
@@ -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: [
{
docs/channels/channel-routing.md
+7 -1
View File
@@ -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" },
docs/channels/discord.md
+1 -1
View File
@@ -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`)
docs/channels/feishu.md
+9 -9
View File
@@ -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: [
{
docs/channels/imessage.md
+4 -4
View File
@@ -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: [
{
docs/channels/slack.md
+4 -2
View File
@@ -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.`
docs/channels/yuanbao.md
+5 -5
View File
@@ -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: [
{
docs/cli/config.md
+1 -1
View File
@@ -201,7 +201,7 @@ Use `--replace` only when the provided value should intentionally become the com
</Tabs>
<Warning>
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).
</Warning>
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.
docs/cli/dns.md
+1 -1
View File
@@ -30,7 +30,7 @@ openclaw dns setup --apply
| `--domain <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:
docs/concepts/delegate-architecture.md
+8 -10
View File
@@ -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: [
{
docs/concepts/experimental-features.md
+4 -4
View File
@@ -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,
},
},
],
},
},
}
```
docs/concepts/parallel-specialist-lanes.md
-1
View File
@@ -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",
},
docs/concepts/queue.md
+6 -6
View File
@@ -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
docs/gateway/bonjour.md
+2 -2
View File
@@ -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)
docs/gateway/config-agents.md
+2 -3
View File
@@ -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
docs/gateway/config-channels.md
+12 -11
View File
@@ -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.<provider>.accounts.<id>.configWrites` also gates writes that target that account (for example `/allowlist --config --account <id>` or `/config set channels.<provider>.accounts.<id>...`).
- `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)
docs/gateway/configuration-reference.md
+4 -5
View File
@@ -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`.
docs/gateway/configuration.md
+13 -13
View File
@@ -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" } },
docs/gateway/openshell.md
+4 -4
View File
@@ -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: {
docs/gateway/sandboxing.md
+8 -8
View File
@@ -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"],
},
},
},
],
},
},
}
```
docs/gateway/security/index.md
+18 -15
View File
@@ -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"],
},
},
}
docs/help/faq.md
+5 -6
View File
@@ -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 },
},
],
},
},
}
```
docs/install/fly.md
+3 -4
View File
@@ -146,12 +146,11 @@ read_when:
},
"maxConcurrent": 4
},
"list": [
{
"id": "main",
"entries": {
"main": {
"default": true
}
]
}
},
"auth": {
"profiles": {
docs/nodes/index.md
+4 -4
View File
@@ -525,12 +525,12 @@ Per-agent exec node override:
```json5
{
agents: {
list: [
{
id: "main",
entries: {
main: {
default: true,
tools: { exec: { node: "build-node" } },
},
],
},
},
}
```
docs/plugins/codex-harness.md
+4 -6
View File
@@ -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",
},
],
},
},
}
```
docs/plugins/hooks.md
+4 -4
View File
@@ -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: [
{
docs/plugins/llama-cpp.md
+2 -8
View File
@@ -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
docs/plugins/memory-wiki.md
+4 -1
View File
@@ -408,7 +408,10 @@ normalized agent id:
```json5
{
agents: {
list: [{ id: "support" }, { id: "marketing" }],
entries: {
support: { default: true },
marketing: {},
},
},
plugins: {
entries: {
docs/plugins/sdk-agent-harness.md
+4 -4
View File
@@ -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:
}
}
}
]
}
}
}
```
docs/providers/alibaba.md
+4 -2
View File
@@ -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",
},
},
},
},
docs/providers/comfy.md
+16 -8
View File
@@ -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",
},
},
},
},
docs/providers/fal.md
+24 -12
View File
@@ -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",
},
},
},
},
docs/providers/google.md
+12 -6
View File
@@ -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",
},
},
},
},
docs/providers/litellm.md
+5 -3
View File
@@ -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,
},
},
},
},
docs/providers/minimax.md
+3 -3
View File
@@ -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" } },
},
},
}
docs/providers/ollama.md
+9 -21
View File
@@ -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,
},
},
},
docs/providers/openai.md
+2 -2
View File
@@ -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" } },
},
},
}
docs/providers/pixverse.md
+4 -2
View File
@@ -94,8 +94,10 @@ The video provider accepts these optional provider-specific keys:
{
agents: {
defaults: {
videoGenerationModel: {
primary: "pixverse/v6",
mediaModels: {
video: {
primary: "pixverse/v6",
},
},
},
},
docs/providers/qwen.md
+1 -1
View File
@@ -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" } },
},
},
}
docs/providers/runway.md
+4 -2
View File
@@ -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",
},
},
},
},
docs/providers/together.md
+4 -2
View File
@@ -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",
},
},
},
},
docs/providers/vydra.md
+8 -4
View File
@@ -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",
},
},
},
},
docs/providers/xai.md
+8 -4
View File
@@ -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",
},
},
},
},
docs/reference/memory-config.md
+8 -11
View File
@@ -316,11 +316,9 @@ Use `provider: "openai-compatible"` for a generic OpenAI-compatible
</Accordion>
<Accordion title="Local (GGUF + llama.cpp)">
| 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.
---
docs/tools/acp-agents.md
+5 -6
View File
@@ -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: [
{
docs/tools/browser-control.md
+1 -2
View File
@@ -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"],
},
},
}
docs/tools/browser.md
+1 -1
View File
@@ -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
docs/tools/image-generation.md
+31 -21
View File
@@ -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/<deployment-name>",
timeoutMs: 600_000,
mediaModels: {
image: {
primary: "microsoft-foundry/<deployment-name>",
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
docs/tools/lobster.md
+8 -8
View File
@@ -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"] }
}
]
}
}
}
```
docs/tools/loop-detection.md
+4 -4
View File
@@ -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,
},
},
},
],
},
},
}
```
docs/tools/music-generation.md
+12 -8
View File
@@ -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 <taskId>
{
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 <taskId>
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
docs/tools/pdf.md
+2 -2
View File
@@ -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
docs/tools/skills-config.md
+5 -5
View File
@@ -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
},
},
}
```
docs/tools/skills.md
+5 -5
View File
@@ -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
},
},
}
```
docs/tools/slash-commands.md
+5 -11
View File
@@ -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.
</ParamField>
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
Controls how owner ids appear in the system prompt.
</ParamField>
<ParamField path="commands.ownerDisplaySecret" type="string">
HMAC secret used when `commands.ownerDisplay: "hash"`.
</ParamField>
<ParamField path="commands.allowFrom" type="object">
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.
</ParamField>
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:
docs/tools/subagents.md
+4 -4
View File
@@ -175,12 +175,12 @@ Per-agent override: `agents.entries.*.subagents.delegationMode`.
maxConcurrent: 4,
},
},
list: [
{
id: "coordinator",
entries: {
coordinator: {
default: true,
subagents: { delegationMode: "prefer" },
},
],
},
},
}
```
docs/tools/swarm.md
+4 -5
View File
@@ -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 } },
},
},
}
```
docs/tools/tts.md
+4 -4
View File
@@ -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" },
},
},
},
],
},
},
}
```
docs/tools/video-generation.md
+13 -9
View File
@@ -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"],
},
},
},
},