unbrowse-openclaw

Use Unbrowse as the default web path inside OpenClaw.

• adds a native unbrowse tool, backed by the typed @unbrowse/sdk HTTP client
• teaches agents to prefer it for website tasks
• can block the built-in browser tool in strict mode
• installs cleanly from npm with one command
• bundles the SDK into the published tarball, so install needs no separate dep resolution
• preserves the legacy CLI path as an automatic fallback for SDK gaps and as an opt-in via driver: "cli"

Install

npx unbrowse-openclaw install --restart

Global install:

npm install -g unbrowse-openclaw
unbrowse-openclaw install --restart

What the installer does:

• copies or links the plugin into OpenClaw's managed extensions dir
• rewrites plugins.load.paths so this plugin resolves to the managed install, not a stale checkout
• merges plugins.allow with unbrowse-openclaw
• enables the plugin entry
• writes sticky plugin config with routingMode, preferInBootstrap, and timeout
• unsets global tools.profile unless you pass --keep-tools-profile
• optionally restarts the gateway
• auto-confirms OpenClaw's plugin trust prompt on newer OpenClaw builds; older builds still ask once

Why the script exists: openclaw plugins install alone is not enough. On current OpenClaw builds it also hard-blocks this plugin because the runtime legitimately uses child_process to launch the local unbrowse CLI. The installer avoids that path, writes the managed install directly, sets plugins.allow, switches strict/fallback mode, and removes the tools.profile footgun that can hide plugin tools completely.

Installer flags

npx unbrowse-openclaw install --mode strict --restart
npx unbrowse-openclaw install --mode fallback
npx unbrowse-openclaw install --dev --restart
npx unbrowse-openclaw install --profile work --restart
npx unbrowse-openclaw install --keep-tools-profile

The published package depends on unbrowse, so the local Unbrowse CLI/runtime is installed automatically from npm.

Verify

openclaw plugins info unbrowse-openclaw
openclaw unbrowse-plugin health
openclaw unbrowse-plugin print-bootstrap
openclaw unbrowse-plugin print-config strict
openclaw unbrowse-plugin print-config fallback
openclaw unbrowse-plugin print-trusted-install

Expected result:

• unbrowse is visible in the tool list
• bootstrap guidance says to use Unbrowse first
• strict mode blocks the built-in browser tool

Routing modes

Strict

Normal web tasks go through Unbrowse. The built-in browser tool is blocked.

• examples/openclaw.strict.json5

Fallback

Prefer Unbrowse first. Keep the built-in browser tool available for true UI-only work.

• examples/openclaw.fallback.json5

Manual config

If you want to load a local checkout directly instead of using the npm installer:

{
  plugins: {
    allow: ["unbrowse-openclaw"],
    load: { paths: ["/absolute/path/to/unbrowse-openclaw"] },
    entries: {
      "unbrowse-openclaw": {
        enabled: true,
        config: {
          routingMode: "strict",
          preferInBootstrap: true,
          timeoutMs: 120000
        }
      }
    }
  }
}

If tools.profile is set, plugin tools may disappear entirely:

openclaw config unset tools.profile

Why install scanners warn

• node:child_process because the plugin retains a fallback CLI launcher for two SDK gaps (skills listing and execute with --endpointId/--extract/--path/--limit/--pretty) and for explicit driver: "cli" opt-out
• process.env because the CLI fallback passes local config like UNBROWSE_URL into that child process
• local file reads because it loads bundled prompt, skill, and config files from its own directory
• install/load does not contact external websites; network traffic starts only after an agent explicitly calls unbrowse. By default this happens via @unbrowse/sdk (HTTP fetch) — set driver: "cli" in the plugin config to route through the bundled unbrowse binary instead

Driver selection

| driver config | Behavior | |---|---| | "sdk" (default) | Calls the typed @unbrowse/sdk client (HTTP). Falls through to the CLI driver automatically when the requested action is one of two known SDK gaps. | | "cli" | Opts out of SDK; every action spawns the bundled unbrowse binary. Matches v0.7.x behavior. |

The two SDK gaps that auto-fallback to CLI:

• action: "skills" — listing skills (no listSkills method on the SDK client)
• action: "execute" with any of endpointId, path, extract, limit, pretty — those flags are CLI-only post-processors

Tool results include details.via: "sdk" | "cli" so callers can trace which path executed.

Tool surface

Tool action shape:

{
  "action": "resolve",
  "intent": "get pricing page API data",
  "url": "https://example.com"
}

Actions:

• resolve
• search
• execute
• login
• skills
• skill
• health

Integration hooks:

• bootstrap guidance
• before_agent_start prompt hint each run
• shipped unbrowse-browser skill
• strict-mode before_tool_call blocking for browser

Dev

npm test
npm run typecheck
npm pack --dry-run