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):

bash

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#

bash

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#

ActionArgsDescriptionnavigate``<url>Navigate to URLsnapshot—Get accessibility tree with element refsscreenshot``[filepath]Take screenshot; saves to filepath if givenclick``<ref>Click element by reffill``<ref> <text>Replace input content with texttype``<ref> <text>Append text to inputpress``<key>Press keyboard key (Enter, Tab, Escape, etc.)hover``<ref>Hover over elementselect``<ref> <values...>Select dropdown option(s)evaluate``<js>Run JavaScript in the pageclose—Close the browser tab

Workflow#

text

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#

bash

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

bash

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

bash

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

Example: Run JavaScript#

bash

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

OpenClaw exec Integration#

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

bash

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.