openclaw - 💡(How to fix) Fix Talk API: allow per-session realtime instructions/context for gateway relay sessions

Summary

OpenClaw Talk currently accepts static realtime instructions from runtime config, but the talk.session.create / talk.client.create schemas reject per-session instructions. This makes it hard for external conversational channels to pass safe, user-selected context into a realtime voice session while still using the OpenClaw gateway relay.

In Clara Realtime, the voice UI should work as a thin OpenClaw channel. Alan can select an active workspace project, and that project context should be available to the OpenClaw realtime session. Without per-session context support in the relay path, the channel has to either force browser WebRTC or route more behavior locally, both of which are worse architecturally.

Observed behavior

When Clara passes instructions while creating a Talk session, OpenClaw rejects the request:

invalid talk.client.create params: at root: unexpected property 'instructions'
invalid talk.session.create params: at root: unexpected property 'instructions'

Installed package version observed locally:

openclaw 2026.5.18

Relevant current behavior:

• talk.client.create uses configured realtime instructions only.
• talk.session.create for transport="gateway-relay" uses configured realtime instructions only.
• The public schemas do not allow instructions on those create params.
• There does not appear to be a separate Talk session update/configure method for injecting session context after creation.

Expected behavior

A channel should be able to create a realtime Talk session with safe per-session context, for example:

{
  "mode": "realtime",
  "brain": "agent-consult",
  "transport": "gateway-relay",
  "sessionKey": "voice-session-key",
  "instructions": "Active workspace project context: ..."
}

OpenClaw should combine that with the configured realtime base instructions, preserving the same policies, tools, and runtime ownership.

Why this matters

This keeps voice/web/Telegram-like channels thin:

• The channel captures/transcribes user input.
• OpenClaw remains the decision-maker and tool executor.
• The channel can provide session context, such as selected workspace/project, without implementing hard-coded command routing.
• Long-running task feedback and final responses stay in the gateway relay path.

Proposed change

Allow optional instructions or a similarly named per-session context field on:

• TalkClientCreateParamsSchema
• TalkSessionCreateParamsSchema

Then, when creating realtime browser or gateway-relay sessions, use:

buildRealtimeInstructions(params.instructions ?? realtimeConfig.instructions)

or an equivalent merge strategy if both configured and request-level instructions should be preserved distinctly.

Acceptance criteria

• talk.session.create with transport="gateway-relay" accepts per-session context/instructions.
• talk.client.create accepts the same for browser WebRTC fallback.
• Existing configured realtime instructions still work when no per-session context is provided.
• The field is validated and bounded so callers cannot pass unbounded prompt payloads.
• Channels can keep using the gateway relay without forcing WebRTC just to provide context.

Real downstream case

Clara Realtime has a project selector for folders under an allowed workspace. The selected project should be context for OpenClaw, not a local command shortcut. With this API support, Clara can keep the relay path and pass the selected project summary into the OpenClaw realtime session cleanly.