Browser（clawd 托管）

浏览器工具：Clawd 可控制 Chrome/Brave，本文介绍如何配置。Moltbot 可运行专用 Chrome/Brave/Edge/Chromium 配置供代理控制，与个人浏览器隔离，通过网关内的小型本地控制服务（仅回环）管理。入门理解：

可视为独立的、仅代理使用的浏览器。
clawd 配置不会触碰你的个人浏览器配置。
代理可打开标签、阅读页面、点击、输入，在安全通道内操作。
默认 chrome 配置通过扩展中继使用系统默认 Chromium 浏览器；可切换到 clawd 使用隔离托管浏览器。

你能做什么

名为 clawd 的独立浏览器配置（默认橙色强调）。
确定性标签控制（列表/打开/聚焦/关闭）。
代理操作（点击/输入/拖拽/选择）、快照、截图、PDF。
可选多配置支持（clawd、work、remote 等）。

该浏览器不是日常主力浏览器，而是代理自动化与验证用的安全隔离界面。

快速开始


moltbot browser --browser-profile clawd status
moltbot browser --browser-profile clawd start
moltbot browser --browser-profile clawd open https://example.com
moltbot browser --browser-profile clawd snapshot

若出现“Browser disabled”，在配置中启用（见下）并重启网关。

配置：`clawd` 与 `chrome`

clawd：托管、隔离浏览器（无需扩展）。
chrome：通过扩展中继到系统浏览器（需将 Moltbot 扩展附加到某标签）。

若希望默认使用托管模式，设置 browser.defaultProfile: "clawd"。

配置

浏览器设置在 ~/.clawdbot/moltbot.json。


{
  browser: {
    enabled: true,
    remoteCdpTimeoutMs: 1500,
    remoteCdpHandshakeTimeoutMs: 3000,
    defaultProfile: "chrome",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      clawd: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }
    }
  }
}

说明：浏览器控制服务绑定在由 gateway.port 派生的回环端口（默认 18791，即 gateway + 2）。中继使用下一端口（18792）。若覆盖网关端口（gateway.port 或 CLAWDBOT_GATEWAY_PORT），派生的浏览器端口会随之调整。未设置时 cdpUrl 默认为中继端口。remoteCdpTimeoutMs 用于远程（非回环）CDP 可达性检查。remoteCdpHandshakeTimeoutMs 用于远程 CDP WebSocket 可达性检查。attachOnly: true 表示“从不启动本地浏览器；仅附加到已运行的实例”。color 与每配置的 color 用于区分活动配置。默认配置为 chrome（扩展中继）。使用 defaultProfile: "clawd" 可默认使用托管浏览器。自动检测顺序：若为基于 Chromium 的系统默认浏览器则使用；否则 Chrome → Brave → Edge → Chromium → Chrome Canary。本地 clawd 配置会自动分配 cdpPort/cdpUrl；仅对远程 CDP 需手动设置。

使用 Brave（或其他 Chromium 系浏览器）

若系统默认浏览器为 Chromium 系（Chrome/Brave/Edge 等），Moltbot 会自动使用。可通过 browser.executablePath 覆盖自动检测。CLI 示例：


moltbot config set browser.executablePath "/usr/bin/google-chrome"


// 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" } }

本地与远程控制

本地控制（默认）：网关启动回环控制服务并可启动本地浏览器。
远程控制（节点主机）：在拥有浏览器的机器上运行节点主机；网关将浏览器操作代理到该节点。
远程 CDP：设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以附加到远程 Chromium 系浏览器。此时 Moltbot 不会启动本地浏览器。

远程 CDP URL 可含认证：查询 token（如 https://provider.example?token=<token>）、HTTP Basic 认证（如 https://user:pass@provider.example）。Moltbot 在调用 /json/* 端点及连接 CDP WebSocket 时保留认证。建议将 token 放在环境变量或密钥管理中，不要写入配置文件。

节点浏览器代理（零配置默认）

若在拥有浏览器的机器上运行节点主机，Moltbot 可将浏览器工具调用自动路由到该节点，无需额外浏览器配置。这是远程网关的默认方式。说明：节点主机通过代理命令暴露其本地浏览器控制服务。配置来自节点自身的 browser.profiles（与本地相同）。若不希望启用：在节点上设 nodeHost.browserProxy.enabled=false；在网关上设 gateway.nodes.browser.mode="off"。

Browserless（托管远程 CDP）

Browserless 是托管 Chromium 服务，通过 HTTPS 暴露 CDP 端点。可将 Moltbot 浏览器配置指向 Browserless 区域端点并用 API key 认证。示例：


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

将 <BROWSERLESS_API_KEY> 替换为真实 Browserless token。选择与账号匹配的区域端点（见其文档）。

安全

要点：浏览器控制仅限回环；访问经网关认证或节点配对。将网关与节点主机放在私有网络（如 Tailscale）；避免公网暴露。将远程 CDP URL/token 视为秘密；优先使用环境变量或密钥管理。远程 CDP 建议：优先使用 HTTPS 端点和短期 token；避免在配置中直接写长期 token。

配置（多浏览器）

Moltbot 支持多个命名配置（路由配置）。配置可以是：clawd 托管（专用 Chromium 实例 + 自有用户数据目录 + CDP 端口）、远程（显式 CDP URL）、扩展中继（通过本地中继 + Chrome 扩展使用现有 Chrome 标签）。默认：缺少时自动创建 clawd 配置。chrome 配置为扩展中继内置（默认指向 http://127.0.0.1:18792）。本地 CDP 端口默认从 18800–18899 分配。删除配置会将其本地数据目录移至废纸篓。所有控制端点接受 ?profile=<name>；CLI 使用 --browser-profile。

Chrome 扩展中继（使用现有 Chrome）

Moltbot 也可通过本地 CDP 中继 + Chrome 扩展驱动你现有的 Chrome 标签（无需单独“clawd”实例）。完整指南：Chrome 扩展。流程：网关在本地（同一机器）运行，或节点主机在浏览器所在机器运行。本地中继服务器在回环 cdpUrl 监听（默认 http://127.0.0.1:18792）。在要控制的标签上点击 Moltbot Browser Relay 扩展图标进行附加（不会自动附加）。代理通过常规 browser 工具、选择对应配置控制该标签。若网关在别处，在浏览器所在机器运行节点主机，以便网关代理浏览器操作。

沙箱会话

若代理会话处于沙箱，browser 工具可能默认 target="sandbox"（沙箱浏览器）。Chrome 扩展中继接管需要主机浏览器控制，因此要么在非沙箱会话中运行，要么设置 agents.defaults.sandbox.browser.allowHostControl: true 并在调用工具时使用 target="host"。

设置

加载扩展（开发/解压）：moltbot browser extension install。Chrome → chrome://extensions → 开启“开发者模式”→“加载已解压的扩展程序”→ 选择 moltbot browser extension path 打印的目录。固定扩展，然后在要控制的标签上点击它（徽章显示 ON）。
使用：CLI：moltbot browser --browser-profile chrome tabs。代理工具：browser 且 profile="chrome"。若需不同名称或中继端口，可自建配置：moltbot browser create-profile --name my-chrome --driver extension --cdp-url http://127.0.0.1:18792 --color "#00AA00"。

隔离保证

专用用户数据目录：从不触碰个人浏览器配置。
专用端口：避免使用 9222，防止与开发工作流冲突。
确定性标签控制：通过 targetId 指定标签，而非“最后一个标签”。

浏览器选择

本地启动时，Moltbot 按顺序选择第一个可用的：Chrome、Brave、Edge、Chromium、Chrome Canary。可通过 browser.executablePath 覆盖。平台：macOS 检查 /Applications 和 ~/Applications；Linux 查找 google-chrome、brave、microsoft-edge、chromium 等；Windows 检查常见安装路径。

控制 API（可选）

仅本地集成时，网关暴露小型回环 HTTP API：状态/启动/停止、标签、快照/截图、操作、钩子、下载、调试、网络、状态、设置等。所有端点接受 ?profile=<name>。Playwright 要求：部分功能（navigate/act/AI 快照/角色快照、元素截图、PDF）需要 Playwright。未安装时这些端点返回明确 501。ARIA 快照与基础截图在 clawd 托管 Chrome 上仍可用。Chrome 扩展中继驱动下，ARIA 快照与截图需要 Playwright。若看到 Playwright is not available in this gateway build，请安装完整 Playwright（非 playwright-core）并重启网关，或重新安装带浏览器支持的 Moltbot。

内部原理

高层流程：小型控制服务器接受 HTTP 请求；通过 CDP 连接 Chromium 系浏览器；高级操作（点击/输入/快照/PDF）在 CDP 之上使用 Playwright；缺少 Playwright 时仅提供非 Playwright 操作。这样代理保持稳定、确定性接口，同时可切换本地/远程浏览器与配置。

CLI 速查

所有命令接受 --browser-profile <name> 指定配置，以及 --json 输出机器可读结果。基础：moltbot browser status、start、stop、tabs、tab、tab new、tab select 2、tab close 2、open https://...、focus、close。检查：screenshot、snapshot、console、errors、requests、pdf 等。操作：navigate、resize、click、type、press、hover、scrollintoview、drag、select、download、waitfordownload、upload、fill、dialog、wait、evaluate、highlight、trace start/stop。状态：cookies、storage、set offline/headers/credentials/geo/media/timezone/locale/device。upload 与 dialog 为“上膛”调用；在触发选择器/对话框的点击或按键之前执行。snapshot 的 --format ai（Playwright 安装时为默认）返回带数字 ref 的 AI 快照；--format aria 返回无障碍树；--interactive 等为基于角色的快照。click/type 等需要来自 snapshot 的 ref（数字 12 或角色 ref e12）。动作不支持 CSS 选择器。

快照与 ref

Moltbot 支持两种“快照”风格：AI 快照（数字 ref）：moltbot browser snapshot（默认 --format ai），输出含数字 ref 的文本快照；动作为 click 12、type 23 "hello"。角色快照（如 e12 的角色 ref）：moltbot browser snapshot --interactive（或 --compact、--depth、--selector、--frame），输出带 [ref=e12] 的列表/树；动作为 click e12、highlight e12。加 --labels 可包含带 ref 标签的视口截图。Ref 在导航间不稳定；失败时重新执行 snapshot 并使用新 ref。

等待增强

除时间/文本外，还可等待：URL（Playwright 支持 glob）、加载状态（--load networkidle）、JS 谓词（--fn "window.ready===true"）、选择器可见（wait "#main"）。可组合使用。

调试流程

当操作失败（如“not visible”、“strict mode violation”、“covered”）时：1. moltbot browser snapshot --interactive；2. 使用 click <ref>/type <ref>（interactive 模式优先用角色 ref）；3. 仍失败时：moltbot browser highlight <ref> 查看 Playwright 目标；4. 页面异常时：errors --clear、requests --filter api --clear；5. 深度调试：trace start，复现问题，trace stop（会打印 TRACE:<path>）。

JSON 输出

--json 用于脚本与结构化工具。示例：moltbot browser status --json、snapshot --interactive --json、requests --filter api --json、cookies --json。角色快照的 JSON 含 refs 及小型 stats 块，便于工具判断负载大小与密度。

安全与隐私

clawd 浏览器配置可能包含已登录会话；请按敏感数据对待。
browser act kind=evaluate / moltbot browser evaluate 与 wait --fn 在页面上下文中执行任意 JavaScript；提示注入可引导执行。若不需要可设置 browser.evaluateEnabled=false 关闭。
登录与反爬说明（X/Twitter 等）见 Browser 登录与 X/Twitter 发帖。
保持网关/节点主机私有（回环或仅 tailnet）。
远程 CDP 端点权限大；请通过隧道与访问控制保护。

故障排查

Linux 相关问题（尤其是 snap Chromium）见 Browser 故障排查。

代理工具与控制方式

代理获得一个浏览器自动化工具：browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act。映射关系：browser snapshot 返回稳定 UI 树（AI 或 ARIA）；browser act 使用快照中的 ref ID 进行点击/输入/拖拽/选择；browser screenshot 捕获像素（整页或元素）。browser 接受：profile 选择命名浏览器配置（clawd、chrome 或远程 CDP）；target（sandbox | host | node）选择浏览器所在位置。沙箱会话中 target: "host" 需 agents.defaults.sandbox.browser.allowHostControl=true。省略 target 时：沙箱会话默认为 sandbox，非沙箱默认为 host；若已连接具备浏览器的节点，工具可能自动路由到该节点，除非固定 target="host" 或 target="node"。这样代理保持确定性，避免脆弱选择器。