openclaw/openclaw · error · Error

Sandbox browser is unavailable. Enable agents.defaults.sandb

Error message

Sandbox browser is unavailable. Enable agents.defaults.sandbox.browser.enabled or use target="host" if allowed.

What it means

Thrown by resolveBrowserBaseUrl when target resolves to 'sandbox' (explicitly or by default because sandboxBridgeUrl was provided at tool creation) but no sandboxBridgeUrl is available at call time. The sandbox browser must be enabled via agents.defaults.sandbox.browser.enabled which provides the bridge URL; without it, sandbox routing is impossible.

Source

Thrown at extensions/browser/src/browser-tool.ts:263

        commands: node.commands ?? [],
        pendingDeclaredCommands: node.pendingDeclaredCommands ?? [],
      }
    : null;
}

function resolveBrowserBaseUrl(params: {
  target?: "sandbox" | "host";
  sandboxBridgeUrl?: string;
  allowHostControl?: boolean;
}): string | undefined {
  const cfg = getRuntimeConfig();
  const resolved = resolveBrowserConfig(cfg.browser, cfg);
  const normalizedSandbox = params.sandboxBridgeUrl?.trim() ?? "";
  const target = params.target ?? (normalizedSandbox ? "sandbox" : "host");

  if (target === "sandbox") {
    if (!normalizedSandbox) {
      throw new Error(
        'Sandbox browser is unavailable. Enable agents.defaults.sandbox.browser.enabled or use target="host" if allowed.',
      );
    }
    return normalizedSandbox.replace(/\/$/, "");
  }

  if (params.allowHostControl === false) {
    throw new Error("Host browser control is disabled by sandbox policy.");
  }
  if (!resolved.enabled) {
    throw new Error(
      "Browser control is disabled. Set browser.enabled=true in ~/.openclaw/openclaw.json.",
    );
  }
  return undefined;
}

/**

View on GitHub (pinned to 01804a7531)

Solutions

1. Enable the sandbox browser: set agents.defaults.sandbox.browser.enabled = true in openclaw.json so the bridge URL is provisioned.
2. Alternatively, use target: 'host' (if allowHostControl permits) to bypass the sandbox browser entirely.
3. Restart the sandbox/gateway after enabling so the bridge URL is injected into the tool.

Example fix

// config: ~/.openclaw/openclaw.json
// before
{ "agents": { "defaults": { "sandbox": { "browser": { "enabled": false } } } } }

// after
{ "agents": { "defaults": { "sandbox": { "browser": { "enabled": true } } } } }

// or in the tool call:
await browser({ action: 'snapshot', target: 'host' });

// Check sandbox browser config before requesting sandbox target
import { getRuntimeConfig } from './browser-tool.runtime.js';
const cfg = getRuntimeConfig();
const sandboxBrowserEnabled = cfg.agents?.defaults?.sandbox?.browser?.enabled === true;

if (!sandboxBrowserEnabled && args.target === 'sandbox') {
  // fall back to host or surface a config error
}

When it happens

Trigger: The browser tool was created with sandboxBridgeUrl but it is empty/whitespace at execution, or target: 'sandbox' is requested when no sandbox bridge was configured. The tool defaults target to 'sandbox' when sandboxBridgeUrl was provided at creation.

Common situations: Sandbox browser not enabled in config (agents.defaults.sandbox.browser.enabled is false/missing); sandbox started without the browser bridge; config drift between tool creation and execution; operator wants host browser instead.

Related errors

• Node browser control is disabled by sandbox policy.
• Host browser control is disabled by sandbox policy.
• browser.executablePath not found: ${resolved.executablePath}
• browser.executablePath must point to the browser executable,
• Browser profile "${profile.name}" cannot launch: ${err insta

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/3d7494167dd457ab. Report an issue: GitHub.