> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.ai2me.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway protocol talk, config, and agent methods

RPC method families for Talk and TTS, secrets, config, update, and wizard flows, and agent and workspace helpers.

## Talk and TTS

* `talk.catalog` returns the read-only Talk provider catalog for speech, streaming transcription, and realtime voice: canonical provider ids, registry aliases, labels, configured state, an optional group-level `ready` result, exposed model/voice ids, canonical modes, transports, brain strategies, and realtime audio/capability flags, without returning provider secrets or mutating global config. Current gateways set `ready` after applying runtime provider selection; treat its absence as unverified on older gateways.
* `talk.config` returns the effective Talk config payload; `includeSecrets` requires `operator.talk.secrets` (or `operator.admin`).
* `talk.session.create` (`operator.talk`) creates a gateway-owned Talk session for `realtime/gateway-relay`, `transcription/gateway-relay`, or `stt-tts/managed-room`. For `stt-tts/managed-room`, non-admin callers that pass `sessionKey` must also pass `spawnedBy` for scoped session-key visibility; unscoped `sessionKey` creation and `brain: "direct-tools"` require `operator.admin`.
* `talk.session.appendAudio` appends base64 PCM input audio to gateway-owned realtime relay and transcription sessions.
* `talk.session.cancelOutput` stops assistant audio output, primarily for VAD-gated barge-in in gateway relay sessions. Send the `turnId` from the current audio event's `talkEvent`; the result is `applied`, `stale`, or `idle`.
* `talk.session.submitToolResult` completes a provider tool call emitted by a gateway-owned realtime relay session. The request waits for any asynchronous completion signal exposed by the provider bridge; failed submissions keep the linked run active and do not emit a successful tool-result event. Pass `options: { willContinue: true }` for interim tool output or `options: { suppressResponse: true }` when the provider bridge advertises suppression support and the result should not start another response.
* `talk.session.steer` sends active-run voice control into a gateway-owned agent-backed Talk session: `{ sessionId, text, mode? }`, where `mode` is `status`, `steer`, `cancel`, or `followup`; omitted mode is classified from the spoken text. It selects only work bound to that logical voice call, not another call sharing the connection and agent session.
* `talk.session.close` closes a gateway-owned relay, transcription, or managed-room session and emits terminal Talk events.
* `talk.mode` sets/broadcasts the current Talk mode state for WebChat/Control UI clients.
* `talk.client.create` creates or resumes a client-owned realtime provider session using `webrtc` or `provider-websocket` while the gateway owns credentials, instructions, tool policy, and the returned `voiceSessionId`. Clients pass `sessionKey` and reuse `voiceSessionId` when replacing the provider transport during one call. Clients that negotiate `gateway-control-v1` keep WebRTC media direct but move the provider control channel and tool lifecycle to the Gateway.
* `talk.client.transcript` appends one finalized `{ role, text }` item to the normal agent session. The required `entryId` is idempotent within `voiceSessionId`; retries do not duplicate transcript messages.
* `talk.client.close` closes the logical voice session after pending transcript writes. Closing is idempotent and may deliver a mutation-only call digest to the session's last non-WebChat channel.
* `talk.client.toolCall` lets client-owned realtime transports forward provider tool calls to gateway policy. The first supported tool is `openclaw_agent_consult`; clients get `runId`, `agentId`, and canonical `agentSessionKey` and wait for normal chat lifecycle events before submitting the provider-specific tool result. Use the returned target for `chat.abort` and `chat.history`; keep the original key for voice-session requests. Voice-bound high-impact actions return `VOICE_CONFIRMATION_REQUIRED:<id>` until a later finalized, saved user utterance explicitly confirms that exact final execution action. Function-tool consults supply the `confirmationId` on the next consult, never on the underlying action tool. Native voice delegation resolves the current confirmation through the Gateway after the user transcript is saved. Policy or hook rewrites require confirmation again.
* `talk.client.steer` sends session-scoped active-run voice control for client-owned realtime transports. The gateway resolves owned active work from `sessionKey`, without a voice call ID, and returns a structured accepted/rejected result instead of silently dropping steering. Provider-attached Gateway controls are call-scoped instead.
* `talk.event` is the single Talk event channel for realtime, transcription, STT/TTS, managed-room, telephony, and meeting adapters.
* `talk.speak` synthesizes speech through the active Talk speech provider.
* `tts.status` returns TTS enabled state, active provider, fallback providers, and provider config state.
* `tts.providers` returns the visible TTS provider inventory.
* `tts.enable` and `tts.disable` toggle TTS prefs state.
* `tts.setProvider` updates the preferred TTS provider.
* `tts.convert` runs one-shot text-to-speech conversion.
* `tts.speak` (`operator.write`) renders non-empty `text` with the configured general TTS provider chain and returns one whole clip inline as `audioBase64`, plus `provider` and optional `outputFormat`, `mimeType`, and `fileExtension` metadata. Unlike `tts.convert`, it does not return a Gateway-local path; unlike `talk.speak`, it does not require a Talk provider. Text above `tts.maxTextLength` returns `INVALID_REQUEST`; synthesis failures return `UNAVAILABLE`.

### Relay output cancellation

For interruptible providers, `applied` confirms that output was cleared locally, not
that the provider has finished the interrupted response. If confirmation takes more
than one second, microphone input resumes while the Gateway continues discarding
that response's audio, assistant transcripts, and tool calls. Only its provider
boundary or a provider continuity reset releases that output owner. If the response
remains unfinished for another 30 seconds, the session fails instead of admitting
stale output.

While an interrupted response still owns output, cancelling a newer input-only turn
returns `stale`, including when `turnId` is omitted. Once the provider starts the newer
response, its own turn can be cancelled normally. Intentionally non-interruptible
providers ignore barge-in and end the session on an explicit output stop.
`talk.session.close` always ends the session.

## Secrets, config, update, and wizard

* `secrets.reload` re-resolves active SecretRefs and atomically publishes owner-aware runtime state. Eligible owner failures can publish as cold or stale degradation with `warningCount`; strict or unmapped failures reject the reload and preserve the active snapshot.
* `secrets.resolve` resolves command-target secret assignments for a specific command/target set.
* `secrets.store.list` (`operator.admin`) returns team-scoped metadata and values only for `kind: "env"` entries. `kind: "secret"` entries use a distinct result shape with no value field; there is no reveal method.
* `secrets.store.set` and `secrets.store.delete` (`operator.admin`) create/update or soft-delete one team-scoped entry. After a successful write, the Gateway refreshes the active secrets runtime only when the name is referenced by a `store` SecretRef in the active source config.
* `config.get` returns the current on-disk config snapshot, opaque authored `hash` covering root-file bytes and captured include identities and content, resolved `configRevisionHash`, and optional `appliedConfigHash` for the resolved revision accepted by the active Gateway runtime.
* `config.set` writes a validated config payload.
* `config.patch` merges a partial config update. Destructive array replacement requires the affected path in `replacePaths`; nested arrays under array entries use `[]` paths such as `agents.entries.*.skills`.
* `config.apply` validates + replaces the full config payload.
* `config.schema` returns the live config schema payload used by Control UI and CLI tooling: schema, `uiHints`, version, generation metadata, plugin + channel schema metadata when loadable. It includes `title` / `description` metadata from the same labels/help text as the UI, including nested object, wildcard, array-item, and `anyOf` / `oneOf` / `allOf` composition branches when matching field documentation exists.
* `config.schema.lookup` returns a path-scoped lookup payload for one config path: normalized path, a shallow schema node, matched hint + `hintPath`, optional `reloadKind`, and immediate child summaries for UI/CLI drill-down. `reloadKind` is one of `restart`, `hot`, or `none` (`src/config/schema.ts`) and mirrors the gateway config reload planner for the requested path. Lookup schema nodes keep the user-facing docs and common validation fields (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, numeric/string/array/object bounds, `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Child summaries expose `key`, normalized `path`, `type`, `required`, `hasChildren`, optional `reloadKind`, plus the matched `hint` / `hintPath`.
* `update.run` admits an update and returns its durable `runId`; acknowledgment is not completion, and callers with a session can include `continuationMessage` so startup resumes one follow-up agent turn through the restart continuation queue. Supported package-manager and Git-checkout updates from the control plane use the detached CLI updater. The Gateway keeps serving during validation and closes before its runtime files are replaced. A started handoff returns `ok: true` with `result.reason: "managed-service-handoff-started"` and `handoff.status: "started"`. A second concurrent `update.run` handled by the same Gateway process returns `ok: false` with `result.reason: "managed-service-handoff-already-running"` and `handoff.status: "already-running"`; its continuation is not accepted, so the caller can retry after the active update completes. Standalone CLI updaters and replacement Gateway processes are outside this process-local guard. Unavailable or failed handoffs return `ok: false` with `managed-service-handoff-unavailable` or `managed-service-handoff-failed`, plus `handoff.command` when a manual shell update is required. Unavailable means OpenClaw lacks a safe supervisor boundary or durable service identity, such as `OPENCLAW_SYSTEMD_UNIT` for systemd. During a started handoff, the restart sentinel may briefly report `stats.reason: "restart-health-pending"`; the continuation waits for verification of the restarted Gateway.
* `update.run` acknowledgment fields distinguish notification delivery from update completion: `ackDelivered` reports delivery, `ackQueued` reports acceptance by the notification owner, and optional `acknowledgement` contains the notice text. Read the durable run to determine the update outcome.
* `update.status` refreshes and returns the latest update restart sentinel, including the post-restart running version when available.
* `wizard.start`, `wizard.next`, `wizard.status`, and `wizard.cancel` expose the onboarding wizard over WS RPC.

## Agent and workspace helpers

* `agents.list` returns gateway-visible agent entries, including effective model/runtime metadata and optional semantic `kind` (`agent` or `system`). Entries with recorded creation provenance also include `createdVia` (`operator`, `agent`, or `claw`), nullable `creatorAgentId`, and millisecond `createdAt`; entries without provenance omit those fields. Clients advertise the `agent-kind` handshake capability to receive the complete typed roster; clients without it keep the legacy selector-safe roster without system rows. Kind-aware clients exclude `system` rows from ordinary selectors while retaining them in diagnostic views. Older v4 gateways may return rows without `kind`.
* `agents.create`, `agents.update`, and `agents.delete` manage agent records and workspace wiring.
* `claws.monitors` (`operator.admin`, rate-limited as a control-plane write for all phases) supports [Claw removal](/cli/claws#remove-an-installed-claw). Every request includes `binding: { configPath, statePath, cronStorePath }` for the local profile, checked against the serving owner. `{ phase: "inspect", agentId, binding }` returns at most two corroborated config-owned monitor snapshots, each with `id`, `name`, `enabled`, `agentId`, null `ownerAgentId`, `storeKey`, `declarationKey`, and `revision`. `{ phase: "quiesce", agentId, operationId, monitors, binding }` validates the current deletion journal and exact consented snapshots before cancelling scheduled work. `{ phase: "drain", agentId, operationId, binding }` also requires applied agent removal and monitor convergence. Successful quiescence or drainage returns `{ drained: true }`; incomplete drainage returns `UNAVAILABLE` after a five-second wait. The operation id must match the live journal in the serving Gateway's state; it is not standalone cleanup authority. Extra request fields are rejected.
* `agents.files.list`, `agents.files.get`, and `agents.files.set` manage the bootstrap workspace files exposed for an agent. `agents.files.get` and `agents.files.set` return the file's content `hash` (SHA-256 hex of the on-disk bytes, the same token `sessions.files.set` uses). `agents.files.set` accepts an optional `expectedHash`; when the file's current hash differs, the write is refused with an `INVALID_REQUEST` error whose `details.type` is `agent_file_conflict` and whose `details.currentHash` carries the hash to re-read and rebase against. Omitting `expectedHash` keeps the unconditional overwrite.
* `audit.activity.list` returns the versioned metadata-only activity ledger; `audit.run.inspect` discovers execution ids or inspects one exact execution identity context; `audit.list` remains the compatibility-safe run/tool RPC.
* `agents.workspace.list` and `agents.workspace.get` (`operator.read`) expose read-only, paginated browsing of an agent's workspace directory for clients in the trusted operator domain described in [Operator scopes](/gateway/operator-scopes). Requests accept workspace-relative paths only; reads stay confined to the realpathed workspace root (symlink and hardlink escapes rejected), size-capped, and limited to UTF-8 text plus common image types (base64). Responses do not expose the host workspace path. There are no write operations in this namespace.
* `transcripts.list` (`operator.read`) lists durable meeting captures newest first. Optional `limit` accepts 1–200 (default 50); `providerId` filters the source. The `sessions` result includes selectors, provider/source locators, times, active state, utterance counts, participants, summary availability, optional model/heuristic provenance, and an overview preview capped at 280 characters. Source locators expose only `providerId`, `accountId`, `guildId`, `channelId`, and `meetingUrl`, never free-form metadata.
* `transcripts.get` (`operator.read`) accepts `selector` and optional `includeUtterances`. It returns the session and stored summary, including its canonical Markdown; requested utterances are sanitized and bounded by the capture limit of 2,000. Missing summaries omit `summary` rather than generating notes. Both transcript methods read across one trusted Gateway domain, like `agents.workspace.*`; separate domains are required for reader isolation. They do not export files or change capture state. See [Transcripts CLI](/cli/transcripts#gateway-and-control-ui-reads).
* `tasks.list`, `tasks.get`, and `tasks.cancel` expose the gateway task ledger to SDK and operator clients. See [Task ledger RPCs](/gateway/protocol/ledgers#task-ledger-rpcs).
* `artifacts.list`, `artifacts.get`, and `artifacts.download` expose transcript-derived artifact summaries and downloads for an explicit `sessionKey`, `runId`, or `taskId` scope. Run and task queries resolve the owning session server-side and only return transcript media with matching provenance; unsafe or local URL sources return unsupported downloads instead of fetching server-side. Set `messageRole: "assistant"` on list, get, and download to select assistant-delivered artifacts, including delivery mirrors, and exclude uploaded inputs and raw tool observations. Omit the filter to keep all-role discovery. Combine it with `runId` for a particular run; a run ID alone does not identify generated output. Older Gateways reject the new filter; clients must surface that rejection instead of retrying without it.
* `artifacts.list` also accepts `type: "image"`, optional `limit` (1–4, default 4), and an opaque `cursor` for recent image discovery. Each page reads at most 32 transcript messages and 256 KiB, newest first; `nextCursor` continues into older messages even when a sparse page has no images. Image summaries include `image.url` from structured content, canonical uploaded media facts, or rendered Markdown references. Nonmanaged images use `preview_` ids, `source: "session-transcript-preview"`, and unsupported downloads: these are preview references, not identifiers for `artifacts.get` or `artifacts.download`. The Control UI uses the existing authenticated media routes and session media policy for local sources and the artifact download owner for managed media. Discovery never restores cold transcripts or rebuilds their projections; open the session to restore unavailable previews. `omittedOversized` reports skipped records; open the session to read them. Cursors expire after 15 minutes, belong to the originating connection, agent, session, and query, and reject transcript resets. Requests without `type` preserve the complete artifact listing; `limit` and `cursor` require the image filter.
* `environments.list` and `environments.status` (`operator.read`) remain available without cloud-worker profiles and preserve gateway-local and node environment discovery. `environments.list` also accepts an optional `runtimeId` from callers with `operator.write`. That request adds one Gateway-owned `requiredNodeCommand` result to each connected node when the runtime requires a node command. Its closed state is `invocable`, `pending-approval`, `undeclared`, or `unauthorized`; it never exposes the node's full pending declaration. Node environments include the durable `sessionHost` identity used to keep a known offline host visible, while current connected inventory is authoritative over that history. Missing identity means false. Exact bounded `{ total, available }` worker slots are live-only and omitted offline; worker-turn admission consumes a slot, while node-backed remote-exec does not. Configured profile summaries expose their bounded, canonically ordered `executionModes` array plus the existing singular `executionMode` primary/default display projection. Current clients select profiles only by membership in `executionModes`. Configured cloud workers and durable records left by earlier profiles add `worker` metadata with the configured `profileId`, `providerId`, optional `leaseId`, `state`, `ageMs`, optional `idleMs`, and `attachedSessionIds`. Worker lifecycle states are `requested`, `provisioning`, `bootstrapping`, `ready`, `attached`, `idle`, `draining`, `destroying`, `destroyed`, `failed`, and `orphaned`. A connected node may also include `workerBundle: { status: "installed", version }` or `workerBundle: { status: "missing" }`. This optional observation is reconnect-scoped and reports validation of one Gateway-retained bundle; it is not launch authority. The public result never exposes the bundle hash, Gateway namespace, node filesystem path, receipt, or protocol-feature details.
* `environments.list` with `{ projection: "profiles" }` reads only the configured profile catalog, including provider-authored machine and operating-system choices. It returns `environments: []` and omits `profiles` when none are advertised. Worker and paired-device inventory is not read, so inventory failures do not prevent profile discovery. Omitting `projection` keeps the full inventory behavior. Including `runtimeId` still requires `operator.write`, even with the profile projection.
* `environments.create` (`{ profileId, idempotencyKey }`) provisions an environment from a configured plugin provider profile; retries with the same key reuse the durable operation. Direct creation without a session does not select an execution mode, so the provider uses its intentional default; Crabbox prepares `worker-turn`. `environments.destroy` (`{ environmentId }`) requests idempotent teardown of a durable worker environment. Both require `operator.admin`, are control-plane writes, and return the same environment summary shape used by status responses.
* `environments.prepare` (`{ profileId, projectPath }`, `operator.admin`) admits a project build without a session and returns `{ environmentId, preparationKey, reused }`. It is a control-plane write gated on provider startup. The project must be a local Git checkout; the configured provider must support project preparation. A matching unconsumed build or reserve is reused. Known errors retain `details.code`: `profile_not_found`, `invalid_profile`, and `invalid_project` map to `INVALID_REQUEST`; `capacity` maps to `UNAVAILABLE`. Other failures return a generic `UNAVAILABLE` without provider details. Prepared summaries expose only `preparation: { purpose: "reserve" | "build", key }`. Use `environments.destroy` to cancel. See [Build on demand](/gateway/cloud-workers/warm-images#ready-workers) for pool policy and setup authorization.
* `worker.desktop.observe` (`{ environmentId, control? }`, `operator.admin`) starts or reuses the environment's desktop forward and returns `{ transport, wsPath, expiresAtMs, control, vncPassword? }`. `wsPath` carries a single-use 60-second token for the Gateway's desktop observer WebSocket; reconnecting requires a fresh observe call. Environments with an observable desktop advertise `worker.desktop: true` in `environments.list`. The method is advertised only when the `cloudWorkers.desktop` lab is enabled. See [Cloud workers](/gateway/cloud-workers#desktop-interactive).
* `desktop.release` (`{ wsPath }`, `operator.admin`) abandons an unclaimed result from `desktop.observe` or `worker.desktop.observe` on the original requesting Gateway connection. It returns `{ released }` and releases only that ticket's pending node stream. Unknown, expired, already-claimed, and other-connection tickets return `released: false`; existing viewers and control ownership are unchanged. Clients should retain cleanup responsibility until RFB authentication and release late results when their presenter has closed.
* `agent.identity.get` returns the effective assistant identity for an agent or session.
* `agent.wait` waits for a run to finish and returns the terminal snapshot when available.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.