Claw Relay — Browser Access for AI Agents

Control a remote browser through Claw Relay using the CLI client. Use when you need to navigate authenticated websites, click buttons, fill forms, take scree...

Security Scan

The skill appears to implement a legitimate remote-browser CLI, but there are multiple coherence issues (undeclared required credentials, missing install/dependency details, path mismatches) and it exposes highly sensitive capabilities (remote JS execution on a user's real browser), so proceed with caution.

Purpose & Capability

The skill's stated purpose (control a remote browser via a CLI client) matches the included script and actions (navigate, snapshot, click, evaluate, screenshot). However the registry metadata lists no required environment variables or primary credential while the SKILL.md explicitly requires CLAW_RELAY_URL, CLAW_RELAY_TOKEN, and CLAW_RELAY_AGENT — a clear mismatch. The script also has a different default URL (ws://localhost:9333) than the SKILL.md examples (wss://relay.clawrelay.dev/), and the SKILL.md references the script path 'skills/openclaw/relay-client.cjs' even though relay-client.cjs is provided at the package root. These inconsistencies suggest sloppy packaging or incomplete metadata.

Instruction Scope

The runtime instructions tell agents to run the included node script via exec and to supply a token/agent id; that's consistent with the goal. But the skill explicitly supports an 'evaluate' action that runs arbitrary JavaScript in the user's real browser and snapshot actions that expose DOM/accessibility trees — behaviors that can access sensitive data (cookies, page content, forms). The SKILL.md does not limit or audit what evaluate may run, and it instructs storing screenshots to disk (fs usage in code). These are expected for a remote-browser tool but materially increase risk and should be justified, scoped, and documented in metadata.

Install Mechanism

This is instruction-only with an included JS client and no formal install spec. The script requires the 'ws' npm module (const WebSocket = require('ws')) but there's no declared dependency or installation step. SKILL.md mentions running 'npm install' in a 'relay-server/' directory which is confusing (the client requires 'ws', not necessarily the server). Missing a clear install step for node dependencies is a packaging omission that could break runtime assumptions or hide needed setup commands.

Credentials

The SKILL.md requires CLAW_RELAY_TOKEN, CLAW_RELAY_URL, and CLAW_RELAY_AGENT (sensitive credentials granting control of a user's real browser), but the registry metadata declares none. Requesting a token that can control browser actions (including arbitrary JS execution) is proportionate to the stated capability only if declared, narrowly scoped, and audited — none of which is present in the registry. The absence of declared required env vars is an important coherence/privacy omission.

Persistence & Privilege

The skill does not request persistent installation or 'always: true'. Autonomous model invocation is allowed (platform default), meaning an agent could invoke the skill without an extra gate; combined with the ability to run arbitrary JS on a real browser and the missing metadata, that increases the potential blast radius. The skill itself instructs not to keep persistent connections, but the agent-level invocation policy is not controlled here.

What to consider before installing

Key things to consider before installing or enabling this skill: - Credentials and scope: The SKILL.md requires a CLAW_RELAY_TOKEN/URL/AGENT but the registry metadata lists none — ask the publisher to declare required env vars and describe token scope and expiry. Treat any token as highly sensitive because it grants control over a real user's browser and sessions. - Arbitrary JS: The 'evaluate' action runs arbitrary JavaScript in the user's real browser and can read cookies/page content; only enable this skill for trusted agents and ensure strong allowlisting/auditing on the relay side. - Dependency/install gaps: The client needs the 'ws' Node module but no install spec is provided. Request a clear install step or package.json so dependencies are explicit. - Verify endpoints: Confirm the relay URL is legitimate (don't blindly use the example wss://relay.clawrelay.dev/). The script defaults to ws://localhost:9333 — confirm which endpoint you intend to use. - Audit and least privilege: Use tokens scoped to the minimum actions needed, enable audit logging on the relay, and prefer time-limited tokens. Test in an isolated environment before granting access to real user sessions. - Packaging fixes: Ask the author to correct path references, add required env var declarations to registry metadata, include dependency manifest (package.json), and provide a homepage or source repo so you can verify the server-side implementation. Given the mismatches and the sensitive nature of remote-browser control, treat this skill as suspicious until those questions are resolved.

Claw Relay — OpenClaw CLI Client

If your platform supports MCP (Copilot CLI, Claude Desktop, Gemini CLI), use skills/browser/SKILL.md instead. This skill is for OpenClaw, nanobot, ZeroClaw, and other agents that call tools via exec.

⚠️ IMPORTANT: No MCP Required

Do NOT write an MCP server, bridge, or wrapper. You already have everything you need:

• The exec tool (built into OpenClaw)
• The relay-client.cjs script (in this folder)

That's it. One exec call per browser action. No MCP, no bridge, no custom server.

Setup

Set environment variables (or pass as flags):

export CLAW_RELAY_URL="wss://relay.clawrelay.dev/"
export CLAW_RELAY_TOKEN="your-token"
export CLAW_RELAY_AGENT="your-agent-id"

The client script is at skills/openclaw/relay-client.cjs in the claw-relay repo.

Usage

node relay-client.cjs [--url URL] [--token TOKEN] [--agent-id ID] ACTION [ARGS...]

Flags override env vars. Every invocation connects, authenticates, performs ONE action, prints JSON, and exits.

Actions

Action	Args	Description
navigate	<url>	Navigate to URL
snapshot	—	Get accessibility tree with element refs
screenshot	[filepath]	Take screenshot; saves to filepath if given
click	<ref>	Click element by ref
fill	<ref> <text>	Replace input content with text
type	<ref> <text>	Append text to input
press	<key>	Press keyboard key (Enter, Tab, Escape, etc.)
hover	<ref>	Hover over element
select	<ref> <values...>	Select dropdown option(s)
evaluate	<js>	Run JavaScript in the page
close	—	Close the browser tab

Workflow

navigate → snapshot → find ref → act → snapshot → verify

1. Navigate to the target URL
2. Snapshot to read the page and get element refs (e.g. e3, e7)
3. Act — click, fill, type, press using refs from the snapshot
4. Verify — snapshot again to confirm the page changed

Example: Search GitHub

# Step 1: Navigate
node relay-client.cjs navigate https://github.com

# Step 2: Snapshot to find the search input ref
node relay-client.cjs snapshot

# Step 3: Fill the search box (say ref is e3)
node relay-client.cjs fill e3 claw-relay

# Step 4: Press Enter
node relay-client.cjs press Enter

# Step 5: Snapshot to read results
node relay-client.cjs snapshot

Example: Click a Button

# Find the button
node relay-client.cjs snapshot
# Output shows button at ref e7

# Click it
node relay-client.cjs click e7

# Verify
node relay-client.cjs snapshot

Example: Take a Screenshot

node relay-client.cjs screenshot /tmp/page.png
# Output: {"ok":true,"path":"/tmp/page.png","bytes":...}

Example: Run JavaScript

node relay-client.cjs evaluate "document.title"

OpenClaw exec Integration

Use the exec tool directly. Each call connects, authenticates, performs one action, and exits:

exec: node /path/to/relay-client.cjs snapshot
exec: node /path/to/relay-client.cjs navigate https://github.com
exec: node /path/to/relay-client.cjs click e3

Set CLAW_RELAY_URL, CLAW_RELAY_TOKEN, and CLAW_RELAY_AGENT in your environment or pass them as flags each time.

Do NOT try to keep a persistent connection, start a background process, or write wrapper scripts. The CLI handles connection lifecycle automatically.

Security Constraints

• Allowlist — your agent can only access sites explicitly allowed in its config
• Blocklist — banking, email, and auth providers are always blocked regardless of allowlist
• Rate limiting — actions are rate-limited per agent
• Audit log — every action is logged with agent ID, action, target, and result

Troubleshooting

"Invalid token or agent_id"

• Agent ID is case-sensitive. Check config.yaml for exact casing (e.g., Rusty ≠ rusty)
• Make sure the token matches exactly — no extra spaces or line breaks
• The relay must be restarted after editing config.yaml

"Agent lacks scope for 'navigate'"

• Your agent's scopes in config.yaml don't include the action you're trying to use
• Common scopes: read (snapshot/screenshot), navigate, interact (click/fill/type), execute (evaluate)
• Ask the relay admin to update your scopes

Script errors

• "require is not defined" — the script must be .cjs, not .js (the repo uses ES modules)
• "Cannot find module 'ws'" — run npm install in the relay-server/ directory first

Common mistakes

• ❌ Writing an MCP server or bridge — you don't need one
• ❌ Keeping a persistent connection — each call is stateless
• ❌ Wrapping the CLI in another script — just call it directly via exec

What Makes This Different

Local browser tools require agent and browser on the same machine. Claw Relay doesn't. Your agent runs anywhere and controls the user's real browser remotely — real cookies, real sessions, real logins. No headless browser, no fake profiles.