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.

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.

Note

This page is for code outside the OpenClaw process. Plugin code that runs inside OpenClaw should use documented openclaw/plugin-sdk/* subpaths instead.

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

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 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.

Related

• Gateway protocol
• Gateway RPC reference
• CLI agent command
• CLI message command
• Agent loop
• Agent runtimes
• Sessions
• Background tasks
• ACP agents
• Plugin SDK overview