RPC and API
Gateway integrations for external apps
External apps should talk to OpenClaw through the Gateway protocol today. Use Gateway WebSocket and RPC methods 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.
What is available today
| Surface | Status | Use it for |
|---|---|---|
| Gateway protocol | Ready | WebSocket transport, connect handshake, auth scopes, protocol versioning, and events. |
| Gateway RPC reference | Ready | Current Gateway methods for agents, sessions, tasks, models, tools, artifacts, and approvals. |
openclaw agent |
Ready | One-shot script integration when shelling out to the CLI is enough. |
openclaw message |
Ready | Sending messages or channel actions from scripts. |
The source tree contains internal package work for a future client library, but that is not a public install surface. Treat it as preview implementation detail until the packages are published and versioned.
Recommended path
- Run or discover a Gateway.
- Connect over the Gateway protocol.
- Call documented RPC methods from Gateway RPC reference.
- Pin the OpenClaw version you test against.
- Recheck the RPC reference when upgrading OpenClaw.
For agent runs, start with the agent RPC and pair it with agent.wait when
you need 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.
