ContextQMD
Back to Openclaw

Gateway integrations for external apps

docs/gateway/external-apps.md

2026.7.13.3 KB
Original Source

External apps talk to OpenClaw through the Gateway protocol: WebSocket transport plus RPC methods. Use it when a script, dashboard, CI job, IDE extension, or another process wants to start agent runs, stream events, wait for results, cancel work, or inspect Gateway resources.

<Warning> There is no public npm client package yet. Do not add OpenClaw client package names as application dependencies until release notes announce a published package and this page includes install instructions. </Warning> <Note> This page is for code outside the OpenClaw process. Plugin code that runs inside OpenClaw should use documented `openclaw/plugin-sdk/*` subpaths instead. </Note>

What is available today

SurfaceStatusUse it for
Gateway protocolReadyWebSocket transport, connect handshake, auth scopes, protocol versioning, and events.
Gateway RPC referenceReadyCurrent Gateway methods for agents, sessions, tasks, models, tools, artifacts, and approvals.
openclaw agentReadyOne-shot script integration when shelling out to the CLI is enough.
openclaw messageReadySending messages or channel actions from scripts.

A future client library package is in progress internally, but it is not a public install surface yet. Treat it as preview implementation detail until a release announces a published, versioned package.

  1. Run or discover a Gateway.
  2. Connect over the Gateway protocol.
  3. Call documented RPC methods from Gateway RPC reference.
  4. Pin the OpenClaw version you test against.
  5. Recheck the RPC reference when upgrading OpenClaw.

For agent runs, start with the agent RPC and pair it with agent.wait for a terminal result. For durable conversation state, use the sessions.* methods. For UI integrations, subscribe to Gateway events and render only the event families your app understands.

App code vs plugin code

Use Gateway RPC when code lives outside OpenClaw:

  • Node scripts that start or observe agent runs
  • CI jobs that call a Gateway
  • dashboards and admin panels
  • IDE extensions
  • external bridges that do not need to become channel plugins
  • integration tests with fake or real Gateway transports

Use the Plugin SDK when code runs inside OpenClaw:

  • provider plugins
  • channel plugins
  • tool or lifecycle hooks
  • agent harness plugins
  • trusted runtime helpers

External apps should not import openclaw/plugin-sdk/*; those subpaths are for plugins loaded by OpenClaw.