Claw Relay , Browser Access for AI Agents

intent

control a remote browser instance through Claw Relay's CLI client when your agent needs to interact with authenticated websites, fill forms, click buttons, take screenshots, or read page content. use this skill if your platform doesn't support MCP (message passing protocol) or if you need access to the user's real browser with real cookies and real sessions. unlike headless browser tools, Claw Relay runs the browser on the user's machine while your agent runs anywhere, giving you authenticated access without storing credentials.

inputs

environment variables or CLI flags (flags override env vars):

• CLAW_RELAY_URL: websocket endpoint for the relay server (e.g., wss://relay.clawrelay.dev/)
• CLAW_RELAY_TOKEN: authentication token issued by the relay admin
• CLAW_RELAY_AGENT: your agent ID as declared in the relay's config.yaml (case-sensitive)

external connections:

• claw relay server: requires active websocket connection to CLAW_RELAY_URL. expects outbound TLS on port 443. relay must be running and reachable from your agent's network.
• user's browser: must have relay client running and authenticated to the same relay server. browser session includes real cookies, local storage, and authentication state.

client script:

• relay-client.cjs: CommonJS script (not ES modules) located in the claw-relay repo at skills/openclaw/relay-client.cjs or equivalent. requires Node.js 14+ and the ws npm package (npm install ws in the relay-server directory).

prerequisites:

• relay server deployed and running (admin task)
• your agent ID registered in relay's config.yaml with appropriate scopes
• claw relay token generated and stored securely
• node CLI available in agent's execution environment
• outbound websocket connectivity to relay server (firewall permitting)

procedure

1. verify relay connectivity and credentials

   • input: CLAW_RELAY_URL, CLAW_RELAY_TOKEN, CLAW_RELAY_AGENT
   • run: node relay-client.cjs snapshot (or any action)
   • output: JSON response with ok: true or error message indicating auth failure, agent not found, or network timeout
   • if auth fails, check token, agent ID casing, and relay server status before proceeding

2. navigate to target URL

   • input: target URL (e.g., https://github.com)
   • run: node relay-client.cjs navigate <url>
   • output: JSON object {"ok": true} on success; {"ok": false, "error": "..."} if URL is blocklisted or agent lacks navigate scope
   • wait for response before next step

3. capture page snapshot to identify elements

   • input: none (reads current page state)
   • run: node relay-client.cjs snapshot
   • output: JSON object with keys accessibility_tree (nested text structure) and elements (array of clickable/interactive refs like e1, e3, e7)
   • parse the elements array to locate refs for buttons, inputs, links, or text you need to interact with

4. perform action: click, fill, type, press, hover, select, or evaluate

   • input: action name and required arguments (e.g., ref e3, text "search term", key name "Enter")
   • run one of: node relay-client.cjs click <ref> | node relay-client.cjs fill <ref> <text> | node relay-client.cjs type <ref> <text> | node relay-client.cjs press <key> | node relay-client.cjs hover <ref> | node relay-client.cjs select <ref> <values...> | node relay-client.cjs evaluate <javascript>
   • output: JSON {"ok": true} or error (invalid ref, element not found, scope not granted)
   • do not assume the action succeeded; verify in the next snapshot

5. verify result by taking new snapshot

   • input: none
   • run: node relay-client.cjs snapshot
   • output: updated accessibility tree and element refs
   • compare with previous snapshot to confirm page changed, new elements appeared, or error state was reached

6. capture visual evidence (optional)

   • input: file path for screenshot (optional; if omitted, screenshot is not saved)
   • run: node relay-client.cjs screenshot [filepath]
   • output: JSON {"ok": true, "path": "/tmp/page.png", "bytes": 12345} on success; error if filepath is not writable or browser state is invalid
   • screenshot captures the remote user's browser viewport

7. close browser session (optional cleanup)

   • input: none
   • run: node relay-client.cjs close
   • output: JSON {"ok": true}
   • closes the tab on the remote browser. omit if you expect the user to continue in that browser

decision points

if initial snapshot fails with "Invalid token or agent_id":

• check that CLAW_RELAY_AGENT matches the exact casing in config.yaml (e.g., Rusty not rusty)
• verify CLAW_RELAY_TOKEN has no leading/trailing whitespace
• confirm relay server is running and reachable at CLAW_RELAY_URL
• if token expired, request a new one from relay admin
• retry snapshot after checking credentials

if action fails with "Agent lacks scope for 'ACTION'":

• agent's scopes in relay config don't include the action (e.g., navigate, interact, read, execute)
• contact relay admin to add required scope to your agent's config
• relay must be restarted after config change
• do not attempt the action again until scope is granted

if URL is blocklisted or navigate fails:

• check relay's allowlist (which domains your agent can access)
• check global blocklist: banking, email, and auth providers are always blocked
• request admin to add domain to allowlist if needed
• some sites block automated access; fallback to asking user to navigate manually

if element ref from snapshot is stale or "element not found":

• page may have reloaded, navigated, or DOM changed since snapshot
• take a fresh snapshot to get current refs
• locate the element again in the new accessibility tree
• click/fill using the new ref

if rate limit encountered (429 or action rejected):

• relay enforces per-agent rate limits to prevent abuse
• back off: wait 5-10 seconds before retrying the same action
• if limits are too restrictive, contact relay admin

if JavaScript evaluate returns null or undefined:

• the expression may not exist on page (e.g., querying a removed element)
• check the expression syntax (must be valid JavaScript)
• wrap in try-catch if needed: evaluate "try { ... } catch(e) { e.message }"
• undefined typically means the element or property doesn't exist; treat as a no-op

if screenshot path is invalid or not writable:

• pass a valid absolute path (e.g., /tmp/page.png or /home/user/screenshots/page.png)
• ensure directory exists and agent process has write permissions
• on windows, use forward slashes or escape backslashes (e.g., C:/Users/user/page.png)
• if no path given, screenshot is not persisted (only metadata returned)

if websocket connection times out or relay is unreachable:

• check network connectivity and firewall rules (outbound TLS on port 443)
• confirm CLAW_RELAY_URL is correct and relay server is running
• check relay server logs for errors or overload
• implement exponential backoff (retry after 2s, 4s, 8s) before giving up

output contract

action responses are always JSON. all actions return one of:

• success: {"ok": true, ...} with action-specific fields:

  • navigate: no extra fields
  • snapshot: includes accessibility_tree (string, nested text hierarchy) and elements (array of {ref: "eN", type: "button|input|link|...", text: "...", visible: true|false})
  • screenshot: includes path (file location) and bytes (file size in bytes)
  • click, fill, type, press, hover, select, close: no extra fields
  • evaluate: includes result (JSON-serializable value or null)

• failure: {"ok": false, "error": "human-readable error message"}

  • common errors: "Invalid token or agent_id", "Agent lacks scope for 'ACTION'", "URL is blocklisted", "Element ref not found", "Rate limit exceeded", "Network timeout"

file outputs:

• screenshot saves to the provided filepath as PNG; returns path and byte size in JSON response
• all other outputs are JSON printed to stdout

side effects on remote browser:

• navigate loads a new page in the browser tab
• click, fill, type, press, hover, select modify form state, trigger events, or navigate if the action targets a link
• evaluate may have side effects if the JavaScript modifies the DOM
• close closes the tab

outcome signal

you know the skill worked when:

1. JSON response contains "ok": true , the relay accepted the command, authenticated the agent, and executed the action without error.

2. snapshot returns elements with refs , you can see the accessibility tree and locate interactive elements (e.g., {ref: "e3", type: "input", text: "Search..."}). if the tree is empty or contains only static text, the page may not be fully loaded; wait and retry.

3. page state changes after action , taking a new snapshot after click, fill, or type shows different content, new elements, or a different URL. compare accessibility trees before and after to confirm change.

4. screenshot is written to disk , the file exists at the specified path and is a valid PNG (byte size > 0). open it to visually verify the remote browser state.

5. form is filled or button is clicked , if you fill an input and then snapshot, the input's text value in the accessibility tree matches what you typed. if you click a button, the resulting page (from next snapshot) reflects the button's action (e.g., form submitted, modal opened, navigation occurred).

6. JavaScript evaluate returns a value , if you run evaluate "document.title", the result field contains the page title. if you run evaluate "document.querySelectorAll('button').length", result is the button count.

7. no "Invalid token", "lacks scope", or "blocklisted" errors , successful auth and scope check. if you see these errors, the skill failed before any browser action occurred; fix credentials and scopes.

8. network round-trip completes within timeout , CLI exits cleanly with JSON output (not hanging or timing out). if it times out, relay server or network is unreachable.

human-readable signal: you can read the accessibility tree, interact with the page using element refs, see the page change after each action, and take screenshots of the remote user's real browser. no errors means the agent is authenticated, scoped, and the relay is reachable.