@alfe.ai/openclaw-remote

OpenClaw plugin for Alfe's interactive remote-control relay. One outbound WebSocket carries browser co-browse and web-terminal sessions; the package also registers bounded browser automation and human-takeover tools.

The relay lifecycle, takeover flow, SSRF policy and tool catalog come from @alfe.ai/remote-host; this package adapts them to OpenClaw.

OpenClaw loads the default-only ./plugin entry. The package root exposes named runtime factories and types for tests and other library consumers.

Configuration

The plugin reads its optional entry from plugins.entries["@alfe.ai/openclaw-remote"].config:

| Key | Default | Boundary | | --- | --- | --- | | remoteWsUrl | Derived from the agent API URL | Credential-free wss:; ws: only on loopback | | browserExecutablePath | /usr/bin/google-chrome-stable | Absolute path, at most 4096 characters | | browserHeadless | true | Boolean | | browserNoSandbox | true | Boolean | | handoffTimeoutMs | 600000 | Integer from 1000 through 1800000 |

The shared browser.ssrfPolicy.dangerouslyAllowPrivateNetwork escape hatch is off by default. With the default policy, BrowserSession request interception blocks credential-bearing URLs and private, loopback, link-local, multicast, benchmark, documentation, and reserved literal addresses. DNS rebinding still requires a resolving policy upstream.

Tools

• browser_navigate
• browser_click
• browser_type
• browser_wait_for
• browser_screenshot
• browser_evaluate
• request_browser_takeover

Validation failures deliberately safe for the model are returned as structured tool errors. Unexpected browser, relay, and API diagnostics are redacted. Screenshots use OpenClaw image content and keep base64 out of JSON details.

Trusted local adapters

The root library exports two helpers for plugins in the same OpenClaw process:

• withRemoteBrowserOperation(callback, { signal? }) invokes the callback with { browserWSEndpoint, targetId, signal } under the existing automation queue. Connect to that exact target; reuse its profile and authenticated page. Disconnect the attachment and await child exit before the callback settles, including when aborted. Never close the owned Chrome or expose its endpoint.
• requestRemoteBrowserTakeover({ instructions, conversationId?, timeout?, signal? }) uses the existing takeover session and waits for hand-back. timeout is in milliseconds. Tell the user to open the Browser tab before invoking; provide conversationId to deliver the chat card during the wait. Its result includes sessionId, optional controlUrl, released, timedOut, url, and title.

Finish an operation before requesting takeover, then acquire a fresh operation after hand-back. Nested operations/handoffs deadlock on the shared queue. These helpers never launch a second runtime; an absent or outdated owner needs the remote plugin started or updated/restarted. A CDP adapter is trusted code, not a target-isolated sandbox. Its consuming tools must redact raw failures.

Development

pnpm --filter @alfe.ai/openclaw-remote lint
pnpm --filter @alfe.ai/openclaw-remote typecheck
pnpm --filter @alfe.ai/openclaw-remote test
pnpm --filter @alfe.ai/openclaw-remote build

See DEVELOPING.md for lifecycle and security invariants.