⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
claw-relay
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.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Claw Relay
Give your AI agents a real browser.
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:
- Install from the Chrome Web Store
- Click the toolbar icon on any tab to share it with the relay
For development:
chrome://extensions→ Developer mode → Load unpacked → selectextension/
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 →
- Add your agent to
config.yamlwith a token, scopes, and allowlist - Restart the relay (config is read at startup)
- Connect using your platform's method (MCP or OpenClaw skill)
- Test with a simple
snapshotaction
Common gotchas:
- Agent ID is case-sensitive —
Rusty≠rusty. Matchconfig.yamlexactly. - Restart after config changes — the relay reads
config.yamlat 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 Guide | Install, configure, launch |
| MCP Server | Connect MCP clients |
| Protocol | WebSocket API reference |
| Dashboard | Web UI for monitoring |
| Tunnels | Remote access |
| Troubleshooting | Common issues |
| Responsible Use | When to use Claw Relay (and when not to) |
Agent Skills
Drop-in skill files that teach AI agents how to use Claw Relay:
| Browser Skill | Teaches any agent to navigate, click, type, screenshot — works with any framework |
| OpenClaw Skill | Standalone 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
- Node.js — runtime
- Hono — HTTP framework
- Playwright — browser automation
- Cloudflare Tunnels — secure remote access
- TanStack Router — dashboard SPA
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