Browser

Name: Browser
Rating: 3.5 (1 reviews)
Author: yungookim

By yungookim 👁 5 views ▲ 0 votes

Native browser plugin for OpenClaw. Replace flaky relay-baed controls

GitHub

Install

pip install git+https://github.com/yungookim/openclaw-browser.git

Configuration Example

{
  "channels": ["direct", "api", "mcp", "cli"],
  "heartbeat_interval_seconds": 5,
  "channel_timeout_seconds": 2,
  "api_port": 8080,
  "debug": true
}

README

# OpenClaw Native Browser Skill

A native browser plugin for OpenClaw using pywebview with WKWebView, providing stable, multi-channel browser automation for macOS.

## Features

- **Native WKWebView Embedding**: Direct browser control via pywebview on macOS
- **Multi-Channel Redundancy**: Direct, API, MCP, and CLI channels with automatic failover
- **Heartbeat Monitoring**: 5-second health checks ensure channel stability
- **Dev Tools Support**: Full WebKit Inspector access for debugging
- **Minimal Dependencies**: Python 3.12+, pywebview, requests, pyzmq
- **pip-Installable**: Easy installation via pip for OpenClaw agents

## Architecture

```
OpenClaw Agent
    ↓
Skill Interface (skill_interface.py)
    ↓
Channel Router (channels.py)
    ├→ Direct Embed (browser_engine.py)
    ├→ API Port (api_server.py, localhost:8080)
    ├→ MCP Channel (mcp_handler.py)
    └→ CLI Wrapper (cli_wrapper.py)
    ↓
WKWebView (native macOS)
```

### Channel Priority

1. **Direct**: In-process Python calls (fastest)
2. **API**: HTTP/REST on localhost:8080 (fallback)
3. **MCP**: Message Control Protocol via ZeroMQ (isolation)
4. **CLI**: Subprocess-based (recovery)

Automatic failover on timeout >2s; heartbeats check every 5s.

## Installation

### From GitHub

```bash
pip install git+https://github.com/yungookim/openclaw-browser.git
```

### Manual

```bash
git clone https://github.com/yungookim/openclaw-browser.git
cd openclaw-browser
pip install -e .
```

## Quick Start

### Python Usage

```python
from src.skill_interface import NativeBrowserSkill

skill = NativeBrowserSkill()
skill.load('https://example.com')
result = skill.execute_js('document.title')
print(result)  # → "Example Domain"
```

### CLI Usage

```bash
native-browser load https://example.com
native-browser execute-js "document.body.innerText"
native-browser get-dom "h1"
```

### OpenClaw Agent Prompt

```
Install the native browser skill:
pip install git+https://github.com/yungookim/openclaw-browser.git

Then use it:
skill.load('https://perplexity.ai')
skill.execute_js('document.querySelector("input").focus()')
```

## Configuration

Edit `channels.json` to customize channel priority and timeouts:

```json
{
  "channels": ["direct", "api", "mcp", "cli"],
  "heartbeat_interval_seconds": 5,
  "channel_timeout_seconds": 2,
  "api_port": 8080,
  "debug": true
}
```

## API Reference

### `load(url: str) → None`

Load a URL in the browser.

```python
skill.load('https://example.com')
```

### `execute_js(code: str) → Any`

Execute JavaScript and return result.

```python
title = skill.execute_js('document.title')
```

### `get_dom(selector: str) → str`

Get HTML of a DOM element.

```python
html = skill.get_dom('h1')
```

### `screenshot() → bytes`

Capture page screenshot (PNG).

```python
png = skill.screenshot()
```

## Testing

```bash
pytest tests/
```

## Logs

Logs are written to `native_browser.log` (configurable).

```bash
tail -f native_browser.log
```

## macOS Requirements

- macOS 10.14+ (Mojave or later)
- Python 3.12+
- Xcode Command Line Tools (for compilation)

## Security

- HTTPS enforcement by default
- Input sanitization for JS execution
- Sandboxed WKWebView
- No external relay dependencies

## Limitations

- **macOS only** (uses native WKWebView)
- Single window per instance (extensible for multiple windows)
- JS execution limited to WKWebView capabilities

## Future Enhancements

- [ ] Multiple window support
- [ ] Video recording
- [ ] Custom certificate validation
- [ ] Proxy support
- [ ] Headless mode (via xvfb-run on Linux)

## Development

Clone and install in editable mode:

```bash
git clone https://github.com/yungookim/openclaw-browser.git
cd openclaw-browser
pip install -e .
python -m pytest tests/ -v
```

## License

MIT License — see LICENSE file.

## Support

Issues and PRs welcome: [GitHub Issues](https://github.com/yungookim/openclaw-browser/issues)

tools