OpenClaw

OpenClaw is the primary agent runtime for the Oasis/OpenClaw product path. Oasis provides the body and world; OpenClaw owns the Gateway, session, memory, approvals, and tools.

Mental Model

There are two lanes:

Lane	Direction	Local default
Chat/control	Oasis browser -> OpenClaw Gateway WebSocket	ws://127.0.0.1:18789
World tools	OpenClaw -> Oasis MCP HTTP	http://127.0.0.1:4516/api/mcp/oasis?agentType=openclaw

Local setup feels simple because both lanes use loopback. Remote setup needs both lanes reachable.

Local Same-Machine Setup

With Oasis running at http://localhost:4516, register Oasis MCP in OpenClaw:

openclaw mcp set oasis '{"url":"http://127.0.0.1:4516/api/mcp/oasis?agentType=openclaw","transport":"streamable-http"}'

In Oasis, open the OpenClaw panel and use the default Gateway WS:

ws://127.0.0.1:18789

If pairing is required, approve the pending device on the machine running the Gateway.

VPS OpenClaw Setup

When OpenClaw runs on a VPS and Oasis runs on your laptop, use one SSH command with two forwards:

ssh -N -T -o ExitOnForwardFailure=yes -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -L 18789:127.0.0.1:18789 -R 4516:127.0.0.1:4516 user@openclaw-host

• -L 18789 lets local Oasis reach the remote OpenClaw Gateway.
• -R 4516 lets remote OpenClaw reach local Oasis MCP.
• ExitOnForwardFailure=yes fails fast if a tunnel port is already occupied.
• ServerAliveInterval=15 and ServerAliveCountMax=3 are SSH keepalives. If the bridge stops answering for about 45 seconds, SSH exits and frees the ports for reconnect.

Then:

1. In Oasis OpenClaw config, set Gateway WS to ws://127.0.0.1:18789.
2. On the VPS, register the MCP URL http://127.0.0.1:4516/api/mcp/oasis?agentType=openclaw.
3. Approve the pending Gateway pairing request on the VPS host.
4. Run the smoke test from the Quickstart.

For the Oasis config UI, keep one OpenClaw tab with local and remote modes. The remote mode should show two lane fields, Gateway WS and Oasis MCP, plus one combined copy button for the SSH command above.

Gateway Pairing Approval

The request id is generated by the OpenClaw Gateway when a new Oasis device connects and signs the Gateway challenge. Oasis can show local pending ids only when the Gateway is on the same machine. For a VPS Gateway, the pending id lives on the VPS.

On the Gateway host:

openclaw devices list
openclaw devices approve <requestId>

Approve only the Oasis device you expect, usually a gateway-client / node client. A remote OpenClaw agent may help run devices list on its own host, but it should not auto-approve a new device without explicit user approval.

Public WSS

wss:// means WebSocket over TLS. It is the browser-safe version of ws://, like https:// is the browser-safe version of http://.

A public Gateway URL can replace the -L 18789 SSH forward if the Gateway is deliberately exposed behind TLS and auth. It does not replace the MCP return path unless Oasis is also reachable by the remote OpenClaw process.

For early local/VPS testing, the double SSH bridge is simpler and more private. For normal users, a hosted relay is better UX.

Hosted Product Shape

For a deployed Oasis app, users should not run SSH. The product-grade flow should be:

1. User logs into Oasis.
2. Oasis creates a short-lived pairing URL or code for one OpenClaw agent.
3. OpenClaw connects to the public relay with that token.
4. The browser keeps an outbound live connection for screenshots and interaction.
5. OpenClaw calls an auth-guarded MCP URL that routes through the relay to the correct user/world/session.

This is how the app can support many users without one process per user. The service routes by user id, world id, session id, and agent id; worker processes are only needed for heavy jobs.

Security Principles

• Use short-lived pairing codes for first connect.
• Exchange the pairing code for a scoped, revocable device token.
• Bind tokens to one user, one agent/device identity, and a limited scope.
• Keep screenshots browser-mediated; the server does not need GPU access to see the user's rendered world.
• Require explicit approval for broader scopes.
• Rotate or revoke tokens from the Oasis account page and OpenClaw Gateway state.

Smoke Test

After pairing, ask OpenClaw:

describe this world, move your avatar a few steps, place one safe catalog object, then take a screenshot and tell me what changed

Expected tools:

• get_world_state or get_world_info
• walk_avatar_to
• search_assets and place_object
• screenshot_viewport or screenshot_avatar

If chat works but tools fail, fix MCP reachability. If tools work but screenshots fail, keep the Oasis browser tab open in the target world.