⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.0.1

claw-relay

andreagriffiths11@andreagriffiths11⭐ 3 stars· last commit 1mo ago· 0 open issues

Control a remote browser through Claw Relay. Use when you need to navigate authenticated websites, click buttons, fill forms, take screenshots, or read page content on a user's real browser — especially when the agent runs on a different machine (cloud, container, server) than the browser. Triggers on remote browser control, authenticated browsing, real browser, cookie-based access, browser relay.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 3 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Claw Relay

Give your AI agents a real browser.

Deploy on Railway

Quick Start

npx @acolombiadev/claw-relay

Launches a dedicated Chrome window, starts the relay, generates config with random tokens. One command, zero setup.

First time: Sign into GitHub (or any site) in the Claw Relay Chrome window. Logins persist between restarts.

Restart: Ctrl+C stops the relay. Chrome stays open. Run npx @acolombiadev/claw-relay again — it reconnects without relaunching Chrome.

What It Does

Claw Relay sits between your AI agent and Chrome. The agent sends actions (navigate, click, read) via WebSocket — the relay enforces auth, permissions, rate limits, and site restrictions before forwarding to Chrome via CDP.

Capabilities

  • Navigation & snapshots — browse pages, read accessibility trees
  • Element interaction — click, type, fill, hover, select, drag & drop
  • Screenshots — full page, viewport, or individual elements
  • Batch actions — execute multiple actions in a single message
  • Tab targeting — pin actions to specific tabs via targetId
  • Wait conditions — wait for text, selectors, navigation, network idle, or custom JS
  • Console & network monitoring — capture logs and requests
  • PDF generation — render pages to PDF
  • Viewport resize — test responsive layouts
  • JavaScript evaluation — run arbitrary code in page context

Connect Your Agent

Works with Copilot CLI, OpenClaw, Claude Code, nanobot, ZeroClaw, or any MCP client.

MCP (Copilot CLI, Claude Code, any MCP client)

{
  "mcpServers": {
    "claw-relay": {
      "command": "node",
      "args": ["mcp/claw-relay-mcp.js"],
      "env": {
        "CLAW_RELAY_URL": "ws://localhost:9333",
        "CLAW_RELAY_TOKEN": "your-token",
        "CLAW_RELAY_AGENT": "default"
      }
    }
  }
}

OpenClaw Skill (OpenClaw, nanobot, ZeroClaw)

Use the bundled CLI client — no MCP required:

export CLAW_RELAY_URL="ws://localhost:9333"
export CLAW_RELAY_TOKEN="your-token"
export CLAW_RELAY_AGENT="your-agent"

node skills/openclaw/relay-client.cjs navigate https://github.com
node skills/openclaw/relay-client.cjs snapshot
node skills/openclaw/relay-client.cjs click e3

See skills/openclaw/SKILL.md for the full agent skill reference.

WebSocket (custom agents)

Connect directly via WebSocket for full control:

const ws = new WebSocket('ws://localhost:9333');
ws.send(JSON.stringify({ type: 'auth', token: 'your-token', agent_id: 'your-agent' }));

See protocol docs for the full action reference.

See MCP docs for MCP-specific setup.

Chrome Extension

Optional — lets your agent use your normal Chrome instead of the dedicated window:

  1. Install from the Chrome Web Store
  2. Click the toolbar icon on any tab to share it with the relay

For development: chrome://extensions → Developer mode → Load unpacked → select extension/

Configuration

Auto-generated config.yaml on first run. Or copy the example manually:

cp relay-server/config.example.yaml relay-server/config.yaml

Key settings:

agents:
  my-agent:
    token: "crly_..."           # auth token
    scopes: ["read", "navigate", "interact"]
    allowlist: ["github.com"]   # where the agent can go
    rateLimit: 30               # actions per minute

blocklist:
  - "*.bank.com"               # always blocked

CLI Options

npx @acolombiadev/claw-relay [options]

  --port <number>    Server port (default: 9333)
  --config <path>    Custom config path
  --no-chrome        Skip Chrome launch (assumes CDP on :9222)

Security

  • Auth — token + agent ID per connection
  • Scopes — read, navigate, interact, execute
  • Allowlist/Blocklist — per-agent URL restrictions
  • Rate limiting — per agent, per minute
  • Audit log — every action logged with timestamp

First-Time Agent Setup

💡 Quickest setup with GitHub Copilot CLI:

copilot --additional-mcp-config '{"mcpServers":{"claw-relay":{"command":"node","args":["mcp/claw-relay-mcp.js"],"env":{"CLAW_RELAY_URL":"ws://localhost:9333","CLAW_RELAY_TOKEN":"your-token","CLAW_RELAY_AGENT":"your-agent-id"}}}}'

That's it — Copilot CLI loads the MCP server and you're ready to browse. Get Copilot CLI free →

  1. Add your agent to config.yaml with a token, scopes, and allowlist
  2. Restart the relay (config is read at startup)
  3. Connect using your platform's method (MCP or OpenClaw skill)
  4. Test with a simple snapshot action

Common gotchas:

  • Agent ID is case-sensitive — Rusty ≠ rusty. Match config.yaml exactly.
  • Restart after config changes — the relay reads config.yaml at startup only
  • Check scopes — if an action fails with "permission_denied", the agent needs that scope added
  • One action per call (OpenClaw skill) — don't try to batch or keep connections open

Docs

Setup GuideInstall, configure, launch
MCP ServerConnect MCP clients
ProtocolWebSocket API reference
DashboardWeb UI for monitoring
TunnelsRemote access
TroubleshootingCommon issues
Responsible UseWhen to use Claw Relay (and when not to)

Agent Skills

Drop-in skill files that teach AI agents how to use Claw Relay:

Browser SkillTeaches any agent to navigate, click, type, screenshot — works with any framework
OpenClaw SkillStandalone relay client for OpenClaw, nanobot, ZeroClaw (no MCP required)

Copy the relevant SKILL.md into your agent's skills directory, or point your agent at the file directly.

Built With

License

MIT

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md5.0 KBupstream ↗
    ---
    name: claw-relay
    description: Control a remote browser through Claw Relay. Use when you need to navigate authenticated websites, click buttons, fill forms, take screenshots, or read page content on a user's real browser — especially when the agent runs on a different machine (cloud, container, server) than the browser. Triggers on remote browser control, authenticated browsing, real browser, cookie-based access, browser relay.
    ---
    
    # Claw Relay — Remote Browser Control
    
    You control a real Chrome browser through a WebSocket relay. The browser runs on the user's machine with their real cookies and sessions. You run anywhere.
    
    ## Connection
    
    Connect via WebSocket. Auth first, then send actions.
    
    ```javascript
    const ws = new WebSocket('wss://<relay-url>');
    
    // First message must be auth
    ws.send(JSON.stringify({
      type: 'auth',
      token: '<agent-token>',
      agent_id: '<your-agent-id>'
    }));
    ```
    
    The relay URL and token are provided by the user or set as environment variables:
    - `CLAW_RELAY_URL` — WebSocket URL (e.g. `wss://relay.example.com`)
    - `CLAW_RELAY_TOKEN` — agent auth token
    - `CLAW_RELAY_AGENT` — your agent identifier
    
    ## Actions
    
    After auth succeeds, send actions as JSON:
    
    | Action | Scope | Payload |
    |--------|-------|---------|
    | `snapshot` | `read` | `{"type": "snapshot"}` — returns accessibility tree |
    | `screenshot` | `read` | `{"type": "screenshot"}` — returns base64 PNG via WebSocket |
    | `click` | `interact` | `{"type": "click", "ref": "e5"}` |
    | `type` | `interact` | `{"type": "type", "ref": "e3", "text": "hello"}` |
    | `fill` | `interact` | `{"type": "fill", "ref": "e3", "text": "hello"}` |
    | `press` | `interact` | `{"type": "press", "key": "Enter"}` |
    | `hover` | `interact` | `{"type": "hover", "ref": "e2"}` |
    | `select` | `interact` | `{"type": "select", "ref": "e7", "values": ["opt1"]}` |
    | `navigate` | `navigate` | `{"type": "navigate", "url": "https://..."}` |
    | `evaluate` | `execute` | `{"type": "evaluate", "js": "document.title"}` |
    | `close` | `navigate` | `{"type": "close"}` — closes current tab |
    
    ## Responses
    
    ```json
    {"type": "result", "action": "snapshot", "ok": true, "data": "...accessibility tree..."}
    {"type": "result", "action": "screenshot", "ok": true, "data": "<base64-encoded-png>", "mimeType": "image/png"}
    {"type": "error", "code": "permission_denied", "message": "Agent lacks 'interact' scope"}
    {"type": "error", "code": "site_blocked", "message": "mail.google.com is blocked"}
    ```
    
    ## Workflow Pattern
    
    1. **Snapshot first** — read the page structure before acting
    2. **Find elements by ref** — the accessibility tree assigns refs (e.g. `e1`, `e5`) to interactive elements
    3. **Act on refs** — click, type, fill using the ref from the snapshot
    4. **Snapshot again** — verify the page changed as expected
    5. **Repeat** — navigate → snapshot → act → verify
    
    ```
    snapshot → find button ref → click ref → snapshot → verify
    ```
    
    ## Scopes (least privilege)
    
    Request only what you need:
    
    - **`read`** — snapshot, screenshot. Start here.
    - **`interact`** — click, type, fill, hover, select. Adds the ability to change things.
    - **`navigate`** — go to URLs. Can access any allowed site as the logged-in user.
    - **`execute`** — run JavaScript on the page. Nuclear option. Avoid unless necessary.
    
    ## 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 (token bucket)
    - **Audit log** — every action is logged with timestamps, agent ID, action, target, and result
    
    ## What Makes This Different
    
    Local browser tools require agent and browser on the same machine. Claw Relay doesn't. Your agent runs anywhere — cloud, server, container — and controls the user's real browser remotely. Real cookies, real sessions, real logins. No headless browser, no fake profiles.
    
    ## Setup
    
    Users set up the relay on their machine:
    
    ```bash
    npx @acolombiadev/claw-relay
    ```
    
    This launches Chrome, generates config with random tokens, and starts the relay. One command, zero setup.
    
    ## Common Tasks
    
    ### Read a page
    ```json
    {"type": "navigate", "url": "https://github.com/notifications"}
    // wait for response
    {"type": "snapshot"}
    ```
    
    ### Fill and submit a form
    ```json
    {"type": "snapshot"}
    // find input ref from tree, e.g. e3
    {"type": "fill", "ref": "e3", "text": "search query"}
    {"type": "press", "key": "Enter"}
    ```
    
    ### Click a button
    ```json
    {"type": "snapshot"}
    // find button ref, e.g. e7
    {"type": "click", "ref": "e7"}
    ```
    
    ## Error Handling
    
    - `permission_denied` — you lack the required scope. Ask the user to upgrade your agent config.
    - `site_blocked` — the site is on the global blocklist (cannot be overridden) or not in your allowlist. Ask the user to check the config.
    - `rate_limited` — slow down. Wait and retry.
    - `engine_error` — browser or CDP issue. The page may have navigated or the element may be stale. Re-snapshot and retry.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/andreagriffiths11-claw-relay.md

// REPO STATS

3 stars
0 open issues
Last commit: 1mo ago