---
title: OpenClaw (run agent sessions on a remote gateway)
---

# OpenClaw (alternative provider on a remote gateway)

## What it is

### What it is

OpenClaw is an **alternative agent provider** you can connect Omniscio to — instead of spawning a local `claude` CLI, OpenClaw sessions run through a WebSocket JSON-RPC v3 connection to a remote gateway server that executes the agent in the cloud. You still drive it from Omniscio's UI (same sidebar, same input, same streaming output), but the heavy work happens off your machine. Good for long-running jobs, resource-intensive work, or keeping your laptop fan quiet. OpenClaw sessions live in a dedicated virtual project (`__openclaw__`) that's auto-created when you connect; the project has a purple indicator in the sidebar so it's visually distinct from your local Claude-CLI projects.

## Where to find it

**Settings → Providers → OpenClaw**, where you enter the gateway address and auth token. Once connected, OpenClaw appears as a provider in the normal session-creation surfaces.

## How it behaves

### How to use it

1. **Get gateway credentials.** You need a gateway URL (e.g., `ws://your-gateway-host:18789`) and an auth token. If you don't have one, OpenClaw is probably not for you — this is a bring-your-own-gateway feature, not a hosted service.
2. **Connect.** Settings → **Advanced** → **OpenClaw**. Paste the gateway URL (WebSocket, `ws://` or `wss://`) and the auth token. Click **Connect**. On success, Omniscio creates the `__openclaw__` project automatically, saves your config for auto-reconnect on app restart, and the project appears in the sidebar.
3. **Launch sessions from the OpenClaw project.** Only sessions launched from the OpenClaw project use the gateway — other projects always use your local Claude CLI. This is deliberate: you pick the provider by picking the project.
4. **Use it like any other session.** Send messages, stream output, interrupt, archive. Same UI, same shortcuts. Image attachments work. Sessions survive reconnects — the client replays context to the gateway on rehydration.
5. **Know the limitations.** Pause and snooze are **not implemented** for OpenClaw sessions (yet). Restart-session isn't either — if a session dies, create a new one. Also: no crash recovery, no recipe/auto-run matching, no codebase-stats collection — the `__openclaw__` project is exempt from all those guards because its semantics don't line up with the local-CLI model.

## For agents

### How it works

The client is [/src/main/services/openclaw-client.ts](/src/main/services/openclaw-client.ts) — implements JSON-RPC v3 over WebSocket, runs a `connect.challenge` handshake on connect, keeps the socket alive with 60-second pings, and reconnects with exponential backoff (up to 6 attempts). Session routing sits in [/src/main/services/openclaw-session-manager.ts](/src/main/services/openclaw-session-manager.ts): every session with `provider: 'openclaw'` goes through here instead of the normal process manager. Session keys follow the format `agent:default:amc:{sessionId}` so the gateway can correlate. IPC surface is 12 channels via [/src/main/ipc/openclaw-handlers.ts](/src/main/ipc/openclaw-handlers.ts): setup, status, disconnect, config get/save, health, cron list, logs tail, reload, plus import-config, gather-setup, and port-start (the OpenClaw-port feature). The `__openclaw__` virtual-project constant is declared in [/src/shared/types.ts](/src/shared/types.ts); virtual-project session guards explicitly exempt it per the rule list in [MEMORY.md](/.claude/memory/MEMORY.md). Timeouts: 10 s handshake, 120 s RPC, 30 s first-response per session. Gateway compatibility is enforced by protocol version only — the client requires protocol v3 (`minProtocol: 3` / `maxProtocol: 3` in `openclaw-client.ts`); there is no gateway-version pin. Config persists under `openclawConfig` (`gatewayUrl`, `token`, `enabled`, `projectId`) with three polling intervals — 60 s for config, 30 s for health/cron, 10 s for logs. Setup walkthrough, protocol details, and gateway-host specifics live in [/docs/openclaw-setup-guide.md](../openclaw-setup-guide.md).

## Related

### Related

- [cli-control.md](cli-control.md) — unrelated localhost HTTP server (not the same as the gateway WebSocket)
- [ssh-remote.md](ssh-remote.md) — an alternative way to run sessions off-box (SSH → local CLI vs OpenClaw → gateway)