Skip to main content

Overview

OpenClawGatewayService turns OpenClaw Gateway traffic into frames, and frames into Gateway calls. The Gateway is the websocket an OpenClaw agent publishes for other programs to drive it, so a pipeline can start a run, redirect it while it’s going, and stop it. An agent run is not a spoken turn. It can take minutes and it answers in prose, so the service deliberately reads and writes no conversational frames — what a run should sound like belongs to whatever wraps it. The usual shape is a voice loop that answers the user itself and forwards real work to the agent, so asking for something that takes ten minutes doesn’t cost you the conversation for ten minutes.

Example Implementation

Voice loop with an OpenClaw agent behind it

Installation

No extra required — the service is part of the base install.

Prerequisites

A running OpenClaw agent with its Gateway enabled. openclaw gateway status reports which port it’s on and whether it’s running.
The token is gateway.auth.token in ~/.openclaw/openclaw.json.
The token is required even on loopback. Without a shared secret the Gateway asks for a paired device identity instead and refuses the connection with NOT_PAIRED.
A NemoClaw sandbox prints its own token with nemoclaw <sandbox> gateway-token --quiet and republishes the Gateway on port 18790, so a bot running outside the sandbox points OPENCLAW_GATEWAY_URL at that port.

Configuration

str
default:"ws://127.0.0.1:18789"
The Gateway websocket, or the port a NemoClaw sandbox republishes it on.
str | None
default:"None"
The Gateway’s shared token. Required even on loopback.
str | None
default:"None"
Gateway password, for a deployment that uses one instead of a token.
str
default:"agent:main:main"
Which OpenClaw session to run in.
float
default:"15.0"
Seconds to wait for the handshake.
float
default:"30.0"
Seconds to wait for a Gateway method to answer.
float
default:"300.0"
Seconds the agent is given to finish a run.
list[str] | None
default:"None"
Handshake scopes.
str
default:"operator"
Handshake role.
int
default:"26214400"
Largest websocket frame to accept, in bytes. Defaults to 25 MB.
bool
default:"True"
Whether to reconnect after the socket fails.
float
default:"4.0"
Minimum time, in seconds, to wait between reconnection attempts.
float
default:"10.0"
Maximum time, in seconds, to wait between reconnection attempts.
float
default:"2.0"
Maximum time, in seconds, to wait for the Gateway to acknowledge the closing handshake before dropping the connection.
float | None
default:"5.0"
Maximum time, in seconds, a single send may wait on a Gateway that has stopped reading before the connection is dropped. None waits indefinitely.

Properties

client

The underlying Gateway client, which can also be used on its own without a pipeline.

Frames

Sent to the service: Pushed by the service: status is "completed", "cancelled", or "failed".

Usage

Notes

  • One run at a time: a session runs one turn at a time, so a send arriving while a run is live stops that run first.
  • Paired frames: every OpenClawStartedFrame is followed by exactly one OpenClawEndFrame, whatever the outcome.
  • Connects during setup: the Gateway connection is established in setup(), before frames start flowing, rather than on the StartFrame.