vilvona 1.0.0

package/docs/tools/lobster.md

@@ -0,0 +1,365 @@
+---
+summary: "Typed workflow runtime for OpenClaw with resumable approval gates."
+title: Lobster
+read_when:
+  - You want deterministic multi-step workflows with explicit approvals
+  - You need to resume a workflow without re-running earlier steps
+---
+
+Lobster is a workflow shell that lets OpenClaw run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints.
+
+Lobster is one authoring layer above detached background work. For flow orchestration above individual tasks, see [Task Flow](/automation/taskflow) (`openclaw tasks flow`). For the task activity ledger, see [`openclaw tasks`](/automation/tasks).
+
+## Hook
+
+Your assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state.
+
+## Why
+
+Today, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime:
+
+- **One call instead of many**: OpenClaw runs one Lobster tool call and gets a structured result.
+- **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved.
+- **Resumable**: Halted workflows return a token; approve and resume without re-running everything.
+
+## Why a DSL instead of plain programs?
+
+Lobster is intentionally small. The goal is not "a new language," it's a predictable, AI-friendly pipeline spec with first-class approvals and resume tokens.
+
+- **Approve/resume is built in**: A normal program can prompt a human, but it can't _pause and resume_ with a durable token without you inventing that runtime yourself.
+- **Determinism + auditability**: Pipelines are data, so they're easy to log, diff, replay, and review.
+- **Constrained surface for AI**: A tiny grammar + JSON piping reduces "creative" code paths and makes validation realistic.
+- **Safety policy baked in**: Timeouts, output caps, sandbox checks, and allowlists are enforced by the runtime, not each script.
+- **Still programmable**: Each step can call any CLI or script. If you want JS/TS, generate `.lobster` files from code.
+
+## How it works
+
+OpenClaw runs Lobster workflows **in-process** using an embedded runner. No external CLI subprocess is spawned; the workflow engine executes inside the gateway process and returns a JSON envelope directly.
+If the pipeline pauses for approval, the tool returns a `resumeToken` so you can continue later.
+
+## Pattern: small CLI + JSON pipes + approvals
+
+Build tiny commands that speak JSON, then chain them into a single Lobster call. (Example command names below - swap in your own.)
+
+```bash
+inbox list --json
+inbox categorize --json
+inbox apply --json
+```
+
+```json
+{
+  "action": "run",
+  "pipeline": "exec --json --shell 'inbox list --json' | exec --stdin json --shell 'inbox categorize --json' | exec --stdin json --shell 'inbox apply --json' | approve --preview-from-stdin --limit 5 --prompt 'Apply changes?'",
+  "timeoutMs": 30000
+}
+```
+
+If the pipeline requests approval, resume with the token:
+
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+AI triggers the workflow; Lobster executes the steps. Approval gates keep side effects explicit and auditable.
+
+Example: map input items into tool calls:
+
+```bash
+gog.gmail.search --query 'newer_than:1d' \
+  | openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'
+```
+
+## JSON-only LLM steps (llm-task)
+
+For workflows that need a **structured LLM step**, enable the optional
+`llm-task` plugin tool and call it from Lobster. This keeps the workflow
+deterministic while still letting you classify/summarize/draft with a model.
+
+Enable the tool:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": { "enabled": true }
+    }
+  },
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": { "alsoAllow": ["llm-task"] }
+      }
+    ]
+  }
+}
+```
+
+### Important limitation: embedded Lobster vs `openclaw.invoke`
+
+The bundled Lobster plugin runs workflows **in-process** inside the gateway. In that embedded mode, `openclaw.invoke` does **not** automatically inherit a gateway URL/auth context for nested OpenClaw CLI tool calls.
+
+That means this pattern is **not currently reliable in the embedded runner**:
+
+```lobster
+openclaw.invoke --tool llm-task --action json --args-json '{ ... }'
+```
+
+Use the example below only when running the **standalone Lobster CLI** in an environment where `openclaw.invoke` is already configured with the correct gateway/auth context.
+
+Use it in a standalone Lobster CLI pipeline:
+
+```lobster
+openclaw.invoke --tool llm-task --action json --args-json '{
+  "prompt": "Given the input email, return intent and draft.",
+  "thinking": "low",
+  "input": { "subject": "Hello", "body": "Can you help?" },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "intent": { "type": "string" },
+      "draft": { "type": "string" }
+    },
+    "required": ["intent", "draft"],
+    "additionalProperties": false
+  }
+}'
+```
+
+If you are using the embedded Lobster plugin today, prefer either:
+
+- a direct `llm-task` tool call outside Lobster, or
+- non-`openclaw.invoke` steps inside the Lobster pipeline until a supported embedded bridge is added.
+
+See [LLM Task](/tools/llm-task) for details and configuration options.
+
+## Workflow files (.lobster)
+
+Lobster can run YAML/JSON workflow files with `name`, `args`, `steps`, `env`, `condition`, and `approval` fields. In OpenClaw tool calls, set `pipeline` to the file path.
+
+```yaml
+name: inbox-triage
+args:
+  tag:
+    default: "family"
+steps:
+  - id: collect
+    command: inbox list --json
+  - id: categorize
+    command: inbox categorize --json
+    stdin: $collect.stdout
+  - id: approve
+    command: inbox apply --approve
+    stdin: $categorize.stdout
+    approval: required
+  - id: execute
+    command: inbox apply --execute
+    stdin: $categorize.stdout
+    condition: $approve.approved
+```
+
+Notes:
+
+- `stdin: $step.stdout` and `stdin: $step.json` pass a prior step's output.
+- `condition` (or `when`) can gate steps on `$step.approved`.
+
+## Install Lobster
+
+Bundled Lobster workflows run in-process; no separate `lobster` binary is required. The embedded runner ships with the Lobster plugin.
+
+If you need the standalone Lobster CLI for development or external pipelines, install it from the [Lobster repo](https://github.com/openclaw/lobster) and ensure `lobster` is on `PATH`.
+
+## Enable the tool
+
+Lobster is an **optional** plugin tool (not enabled by default).
+
+Recommended (additive, safe):
+
+```json
+{
+  "tools": {
+    "alsoAllow": ["lobster"]
+  }
+}
+```
+
+Or per-agent:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "alsoAllow": ["lobster"]
+        }
+      }
+    ]
+  }
+}
+```
+
+Avoid using `tools.allow: ["lobster"]` unless you intend to run in restrictive allowlist mode.
+
+<Note>
+Allowlists are opt-in for optional plugins. `alsoAllow` enables only the named optional plugin tools while preserving the normal core tool set. To restrict core tools, use `tools.allow` with the core tools or groups you want.
+</Note>
+
+## Example: Email triage
+
+Without Lobster:
+
+```
+User: "Check my email and draft replies"
+→ openclaw calls gmail.list
+→ LLM summarizes
+→ User: "draft replies to #2 and #5"
+→ LLM drafts
+→ User: "send #2"
+→ openclaw calls gmail.send
+(repeat daily, no memory of what was triaged)
+```
+
+With Lobster:
+
+```json
+{
+  "action": "run",
+  "pipeline": "email.triage --limit 20",
+  "timeoutMs": 30000
+}
+```
+
+Returns a JSON envelope (truncated):
+
+```json
+{
+  "ok": true,
+  "status": "needs_approval",
+  "output": [{ "summary": "5 need replies, 2 need action" }],
+  "requiresApproval": {
+    "type": "approval_request",
+    "prompt": "Send 2 draft replies?",
+    "items": [],
+    "resumeToken": "..."
+  }
+}
+```
+
+User approves → resume:
+
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+One workflow. Deterministic. Safe.
+
+## Tool parameters
+
+### `run`
+
+Run a pipeline in tool mode.
+
+```json
+{
+  "action": "run",
+  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
+  "cwd": "workspace",
+  "timeoutMs": 30000,
+  "maxStdoutBytes": 512000
+}
+```
+
+Run a workflow file with args:
+
+```json
+{
+  "action": "run",
+  "pipeline": "/path/to/inbox-triage.lobster",
+  "argsJson": "{\"tag\":\"family\"}"
+}
+```
+
+### `resume`
+
+Continue a halted workflow after approval.
+
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+### Optional inputs
+
+- `cwd`: Relative working directory for the pipeline (must stay within the gateway working directory).
+- `timeoutMs`: Abort the workflow if it exceeds this duration (default: 20000).
+- `maxStdoutBytes`: Abort the workflow if output exceeds this size (default: 512000).
+- `argsJson`: JSON string passed to `lobster run --args-json` (workflow files only).
+
+## Output envelope
+
+Lobster returns a JSON envelope with one of three statuses:
+
+- `ok` → finished successfully
+- `needs_approval` → paused; `requiresApproval.resumeToken` is required to resume
+- `cancelled` → explicitly denied or cancelled
+
+The tool surfaces the envelope in both `content` (pretty JSON) and `details` (raw object).
+
+## Approvals
+
+If `requiresApproval` is present, inspect the prompt and decide:
+
+- `approve: true` → resume and continue side effects
+- `approve: false` → cancel and finalize the workflow
+
+Use `approve --preview-from-stdin --limit N` to attach a JSON preview to approval requests without custom jq/heredoc glue. Resume tokens are now compact: Lobster stores workflow resume state under its state dir and hands back a small token key.
+
+## OpenProse
+
+OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep, then run a Lobster pipeline for deterministic approvals. If a Prose program needs Lobster, allow the `lobster` tool for sub-agents via `tools.subagents.tools`. See [OpenProse](/prose).
+
+## Safety
+
+- **Local in-process only** - workflows execute inside the gateway process; no network calls from the plugin itself.
+- **No secrets** - Lobster doesn't manage OAuth; it calls OpenClaw tools that do.
+- **Sandbox-aware** - disabled when the tool context is sandboxed.
+- **Hardened** - timeouts and output caps enforced by the embedded runner.
+
+## Troubleshooting
+
+- **`lobster timed out`** → increase `timeoutMs`, or split a long pipeline.
+- **`lobster output exceeded maxStdoutBytes`** → raise `maxStdoutBytes` or reduce output size.
+- **`lobster returned invalid JSON`** → ensure the pipeline runs in tool mode and prints only JSON.
+- **`lobster failed`** → check gateway logs for the embedded runner error details.
+
+## Learn more
+
+- [Plugins](/tools/plugin)
+- [Plugin tool authoring](/plugins/building-plugins#registering-agent-tools)
+
+## Case study: community workflows
+
+One public example: a "second brain" CLI + Lobster pipelines that manage three Markdown vaults (personal, partner, shared). The CLI emits JSON for stats, inbox listings, and stale scans; Lobster chains those commands into workflows like `weekly-review`, `inbox-triage`, `memory-consolidation`, and `shared-task-sync`, each with approval gates. AI handles judgment (categorization) when available and falls back to deterministic rules when not.
+
+- Thread: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)
+- Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)
+
+## Related
+
+- [Automation](/automation) - scheduling Lobster workflows
+- [Automation Overview](/automation) - all automation mechanisms
+- [Tools Overview](/tools) - all available agent tools

package/docs/tools/loop-detection.md

@@ -0,0 +1,154 @@
+---
+summary: "How to enable and tune guardrails that detect repetitive tool-call loops"
+title: "Tool-loop detection"
+read_when:
+  - A user reports agents getting stuck repeating tool calls
+  - You need to tune repetitive-call protection
+  - You are editing agent tool/runtime policies
+  - You hit `compaction_loop_persisted` aborts after a context-overflow retry
+---
+
+OpenClaw has two cooperating guardrails for repetitive tool-call patterns:
+
+1. **Loop detection** (`tools.loopDetection.enabled`) — disabled by default. Watches the rolling tool-call history for repeated patterns and unknown-tool retries.
+2. **Post-compaction guard** (`tools.loopDetection.postCompactionGuard`) — enabled by default unless `tools.loopDetection.enabled` is explicitly `false`. Arms after every compaction-retry and aborts the run when the agent emits the same `(tool, args, result)` triple within the window.
+
+Both are configured under the same `tools.loopDetection` block, but the post-compaction guard runs whenever the master switch is not explicitly off. Set `tools.loopDetection.enabled: false` to silence both surfaces.
+
+## Why this exists
+
+- Detect repetitive sequences that do not make progress.
+- Detect high-frequency no-result loops (same tool, same inputs, repeated errors).
+- Detect specific repeated-call patterns for known polling tools.
+- Prevent context-overflow then compaction then same-loop cycles from running indefinitely.
+
+## Configuration block
+
+Global defaults, with every documented field shown:
+
+```json5
+{
+  tools: {
+    loopDetection: {
+      enabled: false, // master switch for the rolling-history detectors
+      historySize: 30,
+      warningThreshold: 10,
+      criticalThreshold: 20,
+      unknownToolThreshold: 10,
+      globalCircuitBreakerThreshold: 30,
+      detectors: {
+        genericRepeat: true,
+        knownPollNoProgress: true,
+        pingPong: true,
+      },
+      postCompactionGuard: {
+        windowSize: 3, // armed after compaction-retry; runs unless enabled is explicitly false
+      },
+    },
+  },
+}
+```
+
+Per-agent override (optional):
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "safe-runner",
+        tools: {
+          loopDetection: {
+            enabled: true,
+            warningThreshold: 8,
+            criticalThreshold: 16,
+          },
+        },
+      },
+    ],
+  },
+}
+```
+
+### Field behavior
+
+| Field                            | Default | Effect                                                                                                                          |
+| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`                        | `false` | Master switch for the rolling-history detectors. Setting `false` also disables the post-compaction guard.                       |
+| `historySize`                    | `30`    | Number of recent tool calls kept for analysis.                                                                                  |
+| `warningThreshold`               | `10`    | Threshold before a pattern is classified as warning-only.                                                                       |
+| `criticalThreshold`              | `20`    | Threshold for blocking repetitive no-progress loop patterns.                                                                    |
+| `unknownToolThreshold`           | `10`    | Block repeated calls to the same unavailable tool after this many misses.                                                       |
+| `globalCircuitBreakerThreshold`  | `30`    | Global no-progress breaker threshold across all detectors.                                                                      |
+| `detectors.genericRepeat`        | `true`  | Warns on repeated same-tool + same-params patterns and blocks when the same calls also return identical outcomes.               |
+| `detectors.knownPollNoProgress`  | `true`  | Detects known polling-like patterns with no state change.                                                                       |
+| `detectors.pingPong`             | `true`  | Detects alternating ping-pong patterns.                                                                                         |
+| `postCompactionGuard.windowSize` | `3`     | Number of post-compaction tool calls during which the guard stays armed and the count of identical triples that aborts the run. |
+
+For `exec`, no-progress checks compare stable command outcomes and ignore volatile runtime metadata such as duration, PID, session ID, and working directory. When a run id is available, recent tool-call history is evaluated only within that run so scheduled heartbeat cycles and fresh runs do not inherit stale loop counts from earlier runs.
+
+## Recommended setup
+
+- For smaller models, set `enabled: true` and leave the thresholds at their defaults. Flagship models rarely need rolling-history detection and can leave the master switch at `false` while still benefiting from the post-compaction guard.
+- Keep thresholds ordered as `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
+- If false positives occur:
+  - Raise `warningThreshold` and/or `criticalThreshold`.
+  - Optionally raise `globalCircuitBreakerThreshold`.
+  - Disable only the specific detector causing issues (`detectors.<name>: false`).
+  - Reduce `historySize` for less strict historical context.
+- To disable everything (including the post-compaction guard), set `tools.loopDetection.enabled: false` explicitly.
+
+## Post-compaction guard
+
+When the runner completes a compaction-retry after a context-overflow, it arms a short-window guard that watches the next few tool calls. If the agent emits the same `(toolName, argsHash, resultHash)` triple multiple times within the window, the guard concludes that compaction did not break the loop and aborts the run with a `compaction_loop_persisted` error.
+
+The guard is gated by the master `tools.loopDetection.enabled` flag with one twist: it stays **enabled when the flag is unset or `true`** and only deactivates when the flag is explicitly `false`. This is intentional. The guard exists to escape compaction loops that would otherwise burn unbounded tokens, so a no-config user still gets the protection.
+
+```json5
+{
+  tools: {
+    loopDetection: {
+      // master switch; set false to disable the guard along with the rolling detectors
+      enabled: true,
+      postCompactionGuard: {
+        windowSize: 3, // default
+      },
+    },
+  },
+}
+```
+
+- Lower `windowSize` is stricter (fewer attempts before abort).
+- Higher `windowSize` gives the agent more recovery attempts.
+- The guard never aborts when results are changing, only when results are byte-identical across the window.
+- It is intentionally narrow: it fires only in the immediate aftermath of a compaction-retry.
+
+<Note>
+  The post-compaction guard runs whenever the master flag is not explicitly `false`, even if you never wrote a `tools.loopDetection` block. To verify, look for `post-compaction guard armed for N attempts` in the gateway log immediately after a compaction event.
+</Note>
+
+## Logs and expected behavior
+
+When a loop is detected, OpenClaw reports a loop event and either dampens or blocks the next tool-cycle depending on severity. This protects users from runaway token spend and lockups while preserving normal tool access.
+
+- Warnings come first.
+- Suppression follows when patterns persist past the warning threshold.
+- Critical thresholds block the next tool-cycle and surface a clear loop-detection reason in the run record.
+- The post-compaction guard emits `compaction_loop_persisted` errors with the offending tool name and identical-call count.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Exec approvals" href="/tools/exec-approvals" icon="shield">
+    Allow/deny policy for shell execution.
+  </Card>
+  <Card title="Thinking levels" href="/tools/thinking" icon="brain">
+    Reasoning effort levels and provider-policy interaction.
+  </Card>
+  <Card title="Sub-agents" href="/tools/subagents" icon="users">
+    Spawning isolated agents to bound runaway behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full `tools.loopDetection` schema and merging semantics.
+  </Card>
+</CardGroup>

package/docs/tools/media-overview.md

@@ -0,0 +1,161 @@
+---
+summary: "Image, video, music, speech, and media-understanding capabilities at a glance"
+read_when:
+  - Looking for an overview of OpenClaw's media capabilities
+  - Deciding which media provider to configure
+  - Understanding how async media generation works
+title: "Media overview"
+sidebarTitle: "Media overview"
+---
+
+OpenClaw generates images, videos, and music, understands inbound media
+(images, audio, video), and speaks replies aloud with text-to-speech. All
+media capabilities are tool-driven: the agent decides when to use them based
+on the conversation, and each tool only appears when at least one backing
+provider is configured.
+
+Live speech uses the Talk session contract instead of the one-shot media tool
+path. Talk has three modes: provider-native `realtime`, local or streaming
+`stt-tts`, and `transcription` for observe-only speech capture. Those modes
+share provider catalogs, event envelopes, and cancellation semantics with
+telephony, meetings, browser realtime, and native push-to-talk clients.
+
+## Capabilities
+
+<CardGroup cols={2}>
+  <Card title="Image generation" href="/tools/image-generation" icon="image">
+    Create and edit images from text prompts or reference images via
+    `image_generate`. Async in chat sessions — runs in the background and
+    posts the result when ready.
+  </Card>
+  <Card title="Video generation" href="/tools/video-generation" icon="video">
+    Text-to-video, image-to-video, and video-to-video via `video_generate`.
+    Async — runs in the background and posts the result when ready.
+  </Card>
+  <Card title="Music generation" href="/tools/music-generation" icon="music">
+    Generate music or audio tracks via `music_generate`. Async in chat
+    sessions on the shared media-generation task lifecycle.
+  </Card>
+  <Card title="Text-to-speech" href="/tools/tts" icon="microphone">
+    Convert outbound replies to spoken audio via the `tts` tool plus
+    `messages.tts` config. Synchronous.
+  </Card>
+  <Card title="Media understanding" href="/nodes/media-understanding" icon="eye">
+    Summarize inbound images, audio, and video using vision-capable model
+    providers and dedicated media-understanding plugins.
+  </Card>
+  <Card title="Speech-to-text" href="/nodes/audio" icon="ear-listen">
+    Transcribe inbound voice messages through batch STT or Voice Call
+    streaming STT providers.
+  </Card>
+</CardGroup>
+
+## Provider capability matrix
+
+| Provider          | Image | Video | Music | TTS | STT | Realtime voice | Media understanding |
+| ----------------- | :---: | :---: | :---: | :-: | :-: | :------------: | :-----------------: |
+| Alibaba           |       |   ✓   |       |     |     |                |                     |
+| BytePlus          |       |   ✓   |       |     |     |                |                     |
+| ComfyUI           |   ✓   |   ✓   |   ✓   |     |     |                |                     |
+| DeepInfra         |   ✓   |   ✓   |       |  ✓  |  ✓  |                |          ✓          |
+| Deepgram          |       |       |       |     |  ✓  |       ✓        |                     |
+| ElevenLabs        |       |       |       |  ✓  |  ✓  |                |                     |
+| fal               |   ✓   |   ✓   |   ✓   |     |     |                |                     |
+| Google            |   ✓   |   ✓   |   ✓   |  ✓  |     |       ✓        |          ✓          |
+| Gradium           |       |       |       |  ✓  |     |                |                     |
+| Local CLI         |       |       |       |  ✓  |     |                |                     |
+| Microsoft         |       |       |       |  ✓  |     |                |                     |
+| Microsoft Foundry |   ✓   |       |       |     |     |                |                     |
+| MiniMax           |   ✓   |   ✓   |   ✓   |  ✓  |     |                |                     |
+| Mistral           |       |       |       |     |  ✓  |                |                     |
+| OpenAI            |   ✓   |   ✓   |       |  ✓  |  ✓  |       ✓        |          ✓          |
+| OpenRouter        |   ✓   |   ✓   |   ✓   |  ✓  |  ✓  |                |          ✓          |
+| Qwen              |       |   ✓   |       |     |     |                |                     |
+| Runway            |       |   ✓   |       |     |     |                |                     |
+| SenseAudio        |       |       |       |     |  ✓  |                |                     |
+| Together          |       |   ✓   |       |     |     |                |                     |
+| Vydra             |   ✓   |   ✓   |       |  ✓  |     |                |                     |
+| xAI               |   ✓   |   ✓   |       |  ✓  |  ✓  |                |          ✓          |
+| Xiaomi MiMo       |   ✓   |       |       |  ✓  |     |                |          ✓          |
+
+<Note>
+Media understanding uses any vision-capable or audio-capable model registered
+in your provider config. The matrix above lists providers with dedicated
+media-understanding support; most multimodal LLM providers (Anthropic, Google,
+OpenAI, etc.) can also understand inbound media when configured as the active
+reply model.
+</Note>
+
+## Async vs synchronous
+
+| Capability     | Mode         | Why                                                                                                  |
+| -------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
+| Image          | Asynchronous | Provider processing can outlive a chat turn; generated attachments use the shared completion path.   |
+| Text-to-speech | Synchronous  | Provider responses return in seconds; attached to the reply audio.                                   |
+| Video          | Asynchronous | Provider processing takes 30 s to several minutes; slow queues can run up to the configured timeout. |
+| Music          | Asynchronous | Same provider-processing characteristic as video.                                                    |
+
+For async tools, OpenClaw submits the request to the provider, returns a task
+id immediately, and tracks the job in the task ledger. The agent continues
+responding to other messages while the job runs. When the provider finishes,
+OpenClaw wakes the agent with the generated media paths so it can tell the
+user through the session's normal visible-reply mode: automatic final reply
+delivery when configured, or `message(action="send")` when the session requires
+the message tool. If the requester session is inactive or its active wake
+fails, and some generated media is still missing from the completion reply,
+OpenClaw sends an idempotent direct fallback with only the missing media. Media
+already delivered by the completion reply is not posted again.
+
+## Speech-to-text and Voice Call
+
+Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, OpenRouter, SenseAudio, and xAI can all transcribe
+inbound audio through the batch `tools.media.audio` path when configured.
+Channel plugins that preflight a voice note for mention gating or command
+parsing mark the transcribed attachment on the inbound context, so the shared
+media-understanding pass reuses that transcript instead of making a second
+STT call for the same audio.
+
+Deepgram, ElevenLabs, Mistral, OpenAI, and xAI also register Voice Call
+streaming STT providers, so live phone audio can be forwarded to the selected
+vendor without waiting for a completed recording.
+
+For live user conversations, prefer [Talk mode](/nodes/talk). Batch audio
+attachments stay on the media path; browser realtime, native push-to-talk,
+telephony, and meeting audio should use Talk events and the session-scoped
+catalogs returned by the Gateway.
+
+## Provider mappings (how vendors split across surfaces)
+
+<AccordionGroup>
+  <Accordion title="Google">
+    Image, video, music, batch TTS, backend realtime voice, and
+    media-understanding surfaces.
+  </Accordion>
+  <Accordion title="OpenAI">
+    Image, video, batch TTS, batch STT, Voice Call streaming STT, backend
+    realtime voice, and memory-embedding surfaces.
+  </Accordion>
+  <Accordion title="DeepInfra">
+    Chat/model routing, image generation/editing, text-to-video, batch TTS,
+    batch STT, image media understanding, and memory-embedding surfaces.
+    DeepInfra-native rerank/classification/object-detection models are not
+    registered until OpenClaw has dedicated provider contracts for those
+    categories.
+  </Accordion>
+  <Accordion title="xAI">
+    Image, video, search, code-execution, batch TTS, batch STT, and Voice
+    Call streaming STT. xAI Realtime voice is an upstream capability but is
+    not registered in OpenClaw until the shared realtime-voice contract can
+    represent it.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [Image generation](/tools/image-generation)
+- [Video generation](/tools/video-generation)
+- [Music generation](/tools/music-generation)
+- [Text-to-speech](/tools/tts)
+- [Media understanding](/nodes/media-understanding)
+- [Audio nodes](/nodes/audio)
+- [Talk mode](/nodes/talk)