Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

references/browser.md

View on GitHub
# Browser Tool — Detailed Reference

Full browser automation via CDP (Chrome DevTools Protocol). OpenClaw manages a separate browser profile for the agent with deterministic tab control.

## What You Get

- A separate browser profile named `openclaw` (orange accent by default).
- Deterministic tab control (list/open/focus/close).
- Agent actions (click/type/drag/select), snapshots, screenshots, PDFs.
- Optional multi-profile support (`openclaw`, `work`, `remote`, …).

## Quick Start

```bash
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```

## Profiles: `openclaw` vs `chrome`

- **`openclaw`**: Managed, isolated browser (no extension required).
- **`chrome`**: Extension relay to your system browser (requires the OpenClaw extension attached to a tab).

```json5
{ browser: { defaultProfile: "openclaw" } }
```

### Profile Types

- **openclaw-managed**: Dedicated Chromium instance with own user data dir + CDP port.
- **remote**: Explicit CDP URL (browser running elsewhere).
- **extension relay**: Existing Chrome tab(s) via relay + Chrome extension.

Notes:
- `openclaw` profile is auto-created if missing.
- `chrome` profile is built-in for the extension relay (points at `http://127.0.0.1:18792` by default).
- Local CDP ports allocate from 18800–18899 by default.
- Deleting a profile moves its local data directory to Trash.

## Configuration

```json5
{
  browser: {
    enabled: true,                    // default: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true,  // default trusted-network mode
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    remoteCdpTimeoutMs: 1500,        // remote CDP HTTP timeout
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket timeout
    defaultProfile: "chrome",         // "openclaw" for managed browser
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,                // never launch; attach only
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work:     { cdpPort: 18801, color: "#0066CC" },
      remote:   { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}
```

### Port Convention

- Browser control service: `gateway.port + 2` (default: 18791).
- Relay port: 18792.
- Per-profile CDP ports: 18800–18899.

If you override `gateway.port`, derived browser ports shift to the same "family".

## Use Brave (or Another Chromium Browser)

```json5
// macOS
{ browser: { executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" } }
// Windows
{ browser: { executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe" } }
// Linux
{ browser: { executablePath: "/usr/bin/brave-browser" } }
```

Or via CLI:

```bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"
```

### Browser Auto-Detection Order

1. Chrome → 2. Brave → 3. Edge → 4. Chromium → 5. Chrome Canary

- macOS: checks `/Applications` and `~/Applications`.
- Linux: looks for `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.
- Windows: checks common install locations.

## Local vs Remote Control

- **Local control** (default): Gateway starts loopback control service, can launch a local browser.
- **Remote control (node host)**: Run a node host on the browser machine; Gateway proxies browser actions.
- **Remote CDP**: Set `browser.profiles.<name>.cdpUrl` or `browser.cdpUrl` to attach to a remote Chromium browser. No local browser launched.

Auth for remote CDP:
- Query tokens: `https://provider.example?token=<token>`
- HTTP Basic auth: `https://user:pass@provider.example`

## Node Browser Proxy (Zero-Config Default)

- Node host exposes its local browser control server via proxy.
- Profiles come from the node's own `browser.profiles` config.
- Disable:
  - On the node: `nodeHost.browserProxy.enabled=false`
  - On the gateway: `gateway.nodes.browser.mode="off"`

## Browserless (Hosted Remote CDP)

```json5
{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}
```

## Chrome Extension Relay

[Chrome extension](https://docs.openclaw.ai/tools/chrome-extension):
- Gateway or node host runs locally (same machine).
- Local relay server listens at loopback `cdpUrl` (default: `http://127.0.0.1:18792`).
- You click the OpenClaw Browser Relay extension icon on a tab to attach.
- Agent controls that tab via the normal `browser` tool by selecting the right profile.

## Isolation Guarantees

- **Dedicated user data dir**: Never touches your personal browser profile.
- **Dedicated ports**: Avoids 9222 to prevent collisions with dev workflows.
- **Deterministic tab control**: Target tabs by `targetId`, not "last tab".

## Agent Tool API

The `browser` tool supports:

- `browser snapshot` — returns a stable UI tree (AI or ARIA mode).
- `browser act` — uses snapshot `ref` IDs to click/type/drag/select.
- `browser screenshot` — captures pixels (full page or element).

Parameters:
- `profile` — choose a named browser profile.
- `target` — `sandbox | host | node` to select where the browser lives.
  - Sandboxed sessions default to `sandbox`, non-sandbox to `host`.
  - `target: "host"` in sandbox requires `agents.defaults.sandbox.browser.allowHostControl=true`.
  - If a browser-capable node is connected, auto-routes unless you pin `target`.

## Control API (Optional)

HTTP endpoints (optional, for programmatic control):

| Endpoint | Description |
|---|---|
| `GET /`, `POST /start`, `POST /stop` | Status/start/stop |
| `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` | Tab control |
| `GET /snapshot`, `POST /screenshot` | Snapshot/screenshot |
| `POST /navigate`, `POST /act` | Navigation and actions |
| `POST /hooks/file-chooser`, `POST /hooks/dialog` | Hooks |
| `POST /download`, `POST /wait/download` | Downloads |
| `GET /console`, `POST /pdf` | Debugging |
| `GET /errors`, `GET /requests` | Error/request logs |
| `POST /trace/start`, `POST /trace/stop`, `POST /highlight` | Tracing |
| `POST /response/body` | Network responses |
| `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear` | Cookie state |
| `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear` | Storage |
| `POST /set/offline`, `POST /set/headers`, `POST /set/credentials` | Settings |
| `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone` | Settings |
| `POST /set/locale`, `POST /set/device` | Settings |

Auth: `Authorization: Bearer <gateway token>` or `x-openclaw-password: <gateway password>`.

Profile selection: append `?profile=<name>` to any endpoint.

## Security & Privacy

- The `openclaw` browser profile may contain logged-in sessions; treat as sensitive.
- `browser act kind=evaluate` / `openclaw browser evaluate` and `wait --fn` execute arbitrary JavaScript. Disable with `browser.evaluateEnabled=false`.
- For logins and anti-bot notes (X/Twitter, etc.), see [Browser login](https://docs.openclaw.ai/tools/browser-login).
- Keep Gateway/node host private (loopback or tailnet-only).
- Remote CDP endpoints are powerful; tunnel and protect them.

### SSRF Policy

```json5
{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,            // strict public-only
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"],
    },
  },
}
```

- `dangerouslyAllowPrivateNetwork` defaults to `true` (trusted-network model).
- Navigation is SSRF-guarded before navigation and re-checked on final URL.

## CLI Quick Reference

```bash
openclaw browser status                              # Browser status
openclaw browser start --browser-profile openclaw    # Start managed browser
openclaw browser profiles                             # List profiles
openclaw browser open <url>                           # Open URL
openclaw browser snapshot                             # Take snapshot
openclaw browser screenshot                           # Take screenshot
openclaw browser evaluate "<js>"                      # Run JavaScript
```

## Troubleshooting

See [Browser troubleshooting](https://docs.openclaw.ai/tools/browser-linux-troubleshooting) for Linux-specific issues.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall