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 current talk.event.turnId; 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 user utterance explicitly confirms that exact final execution action and the next consult supplies the confirmationId; 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.

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, raw root-file hash, 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 runs the gateway update flow and schedules a restart only if the update succeeded; callers with a session can include continuationMessage so startup resumes one follow-up agent turn through the restart continuation queue. Package-manager updates and supervised git-checkout updates from the control plane use a detached managed-service handoff instead of replacing the package tree or mutating checkout/build output inside the live gateway. 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 is delayed until the CLI verifies the restarted gateway and writes the final ok sentinel.
• 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. 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. 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.
• tasks.list, tasks.get, and tasks.cancel expose the gateway task ledger to SDK and operator clients. See 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.
• 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 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.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.
• 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.
• 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.