浏览器 (clawd 托管)

文档

工具（Tools）

浏览器 (clawd 托管)

适用范围

在以下情况使用此页面：

添加代理控制的浏览器自动化
调试 clawd 为什么干扰你自己的 Chrome
在 macOS 应用中实现浏览器设置 + 生命周期

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

如果收到"浏览器已禁用"，请在配置中启用它（见下文）并重启网关。

配置文件：`clawd` vs `chrome`

clawd：托管、隔离的浏览器（不需要扩展）。
chrome：到你的系统浏览器的扩展中继（需要将 Moltbot 扩展附加到标签页）。

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

配置

浏览器设置位于 ~/.moltbot/moltbot.json 中。

{
  browser: {
    enabled: true,                    // 默认：true
    controlUrl: "http://127.0.0.1:18791",
    cdpUrl: "http://127.0.0.1:18792", // 默认为 controlUrl + 1
    remoteCdpTimeoutMs: 1500,         // 远程 CDP HTTP 超时（毫秒）
    remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒）
    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" }
    }
  }
}

注意：

controlUrl 默认为 http://127.0.0.1:18791。
如果你覆盖网关端口（gateway.port 或 MOLTBOT_GATEWAY_PORT），默认浏览器端口会移动以保持在同一"系列"中（control = gateway + 2）。
cdpUrl 在未设置时默认为 controlUrl + 1。
remoteCdpTimeoutMs 适用于远程（非环回）CDP 可达性检查。
remoteCdpHandshakeTimeoutMs 适用于远程 CDP WebSocket 可达性检查。
attachOnly: true 意味着"永远不启动本地浏览器；仅在其已经运行时附加"。
color + 每个配置文件的 color 会为浏览器 UI 着色，以便你可以看到哪个配置文件处于活动状态。
默认配置文件是 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"
  }
}

本地 vs 远程控制

本地控制（默认）： controlUrl 是环回（127.0.0.1/localhost）。网关启动控制服务器并可以启动本地浏览器。
远程控制： controlUrl 是非环回。网关不启动本地服务器；它假设你指向其他地方的服务器。
远程 CDP： 设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以附加到远程基于 Chromium 的浏览器。在这种情况下，Moltbot 不会启动本地浏览器。

远程浏览器（控制服务器）

你可以在另一台机器上运行浏览器控制服务器，并将你的网关指向它，使用远程 controlUrl。这允许代理驱动主机之外的浏览器（实验室机器、VM、远程桌面等）。

关键点：

控制服务器通过 CDP 与基于 Chromium 的浏览器（Chrome/Brave/Edge/Chromium）通信。
网关只需要 HTTP 控制 URL。
配置文件在控制服务器端解析。

示例：

{
  browser: {
    enabled: true,
    controlUrl: "http://10.0.0.42:18791",
    defaultProfile: "work"
  }
}

如果你希望网关直接与基于 Chromium 的浏览器实例通信而无需远程控制服务器，请对远程 CDP 使用 profiles.<name>.cdpUrl。

远程 CDP URL 可以包含身份验证：

查询令牌（例如，https://provider.example?token=<token>）
HTTP 基本身份验证（例如，https://user:[email protected]）

Moltbot 在调用 /json/* 端点和连接到 CDP WebSocket 时保留身份验证。最好使用环境变量或机密管理器来存储令牌，而不是将它们提交到配置文件中。

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

如果你在具有浏览器的机器上运行节点主机，Moltbot 可以自动将浏览器工具调用路由到该节点，而无需任何自定义 controlUrl 设置。这是远程网关的默认路径。

注意：

节点主机通过代理命令公开其本地浏览器控制服务器。
配置文件来自节点自己的 browser.profiles 配置（与本地相同）。
如果你不想使用它，请禁用它：
- 在节点上：nodeHost.browserProxy.enabled=false
- 在网关上：gateway.nodes.browser.mode="off"

Browserless（托管的远程 CDP）

Browserless 是一项托管的 Chromium 服务，通过 HTTPS 暴露 CDP 端点。你可以将 Moltbot 浏览器配置文件指向 Browserless 区域端点，并使用你的 API 密钥进行身份验证。

示例：

{
  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 令牌。
选择与你的 Browserless 账户匹配的区域端点（参见他们的文档）。

在浏览器机器上运行控制服务器

运行独立的浏览器控制服务器（当你的网关是远程时推荐）：

# 在运行 Chrome/Brave/Edge 的机器上
moltbot browser serve --bind <browser-host> --port 18791 --token <token>

然后将你的网关指向它：

{
  browser: {
    enabled: true,
    controlUrl: "http://<browser-host>:18791",

    // 选项 A（推荐）：将令牌保留在网关的环境中
    // （避免将机密写入配置文件）
    // controlToken: "<token>"
  }
}

并在网关环境中设置身份验证令牌：

export MOLTBOT_BROWSER_CONTROL_TOKEN="<token>"

选项 B：将令牌存储在网关配置中（相同的共享令牌）：

{
  browser: {
    enabled: true,
    controlUrl: "http://<browser-host>:18791",
    controlToken: "<token>"
  }
}

安全

本节涵盖用于代理浏览器自动化的浏览器控制服务器（browser.controlUrl）。

关键思想：

将浏览器控制服务器视为管理 API：仅限专用网络。
当服务器可从机器外部访问时，始终使用令牌身份验证。
优先使用仅 Tailnet连接，而不是 LAN 暴露。

令牌（什么与什么共享？）

browser.controlToken / MOLTBOT_BROWSER_CONTROL_TOKEN 仅用于对 browser.controlUrl 的浏览器控制 HTTP 请求进行身份验证。
它不是网关令牌（gateway.auth.token），也不是节点配对令牌。
你可以重用相同的字符串值，但最好将它们分开以减少爆炸半径。

绑定（不要意外暴露到 LAN）

TLS / HTTPS（推荐方法：前端终止）

最佳实践：将 moltbot browser serve 保留在 HTTP 上，并在前端终止 TLS。

如果你已经在使用 Tailscale，你有两个不错的选择：

仅 Tailnet，仍然是 HTTP（传输由 Tailscale 加密）：

将 controlUrl 保留为 http://…，但确保只能通过你的 tailnet 访问。

通过 Tailscale 提供 HTTPS（良好的 UX：https://… URL）：

# 在浏览器机器上
moltbot browser serve --bind 127.0.0.1 --port 18791 --token <token>
tailscale serve https / http://127.0.0.1:18791

然后将你的网关配置 browser.controlUrl 设置为 HTTPS URL（MagicDNS/ts.net），并继续使用相同的令牌。

注意：

除非你明确想要将端点公开，否则不要为此使用 Tailscale Funnel。
有关 Tailnet 设置/后台，请参见网关 Web 表面和网关 CLI。

配置文件（多浏览器）

Moltbot 支持多个命名配置文件（路由配置）。配置文件可以是：

clawd 托管：具有自己的用户数据目录 + CDP 端口的专用基于 Chromium 的浏览器实例
远程：明确的 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
扩展中继：通过本地中继 + Chrome 扩展的现有 Chrome 标签页

默认值：

如果缺少 clawd 配置文件，则会自动创建。
chrome 配置文件是为 Chrome 扩展中继内置的（默认指向 http://127.0.0.1:18792）。
本地 CDP 端口默认从 18800–18899 分配。
删除配置文件会将其本地数据目录移动到废纸篓。

所有控制端点都接受 ?profile=<name>；CLI 使用 --browser-profile。

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

Moltbot 还可以通过本地 CDP 中继 + Chrome 扩展驱动你现有的 Chrome 标签页（没有单独的"clawd" Chrome 实例）。

完整指南：Chrome 扩展

流程：

你运行一个浏览器控制服务器（同一台机器上的网关，或 moltbot browser serve）。
本地中继服务器在环回 cdpUrl（默认：http://127.0.0.1:18792）上侦听。
你单击要控制的标签页上的 Moltbot Browser Relay 扩展图标以附加（它不会自动附加）。
代理通过选择正确的配置文件，通过正常的 browser 工具控制该标签页。

如果网关与 Chrome 在同一台机器上运行（默认设置），你通常不需要 moltbot browser serve。仅当网关在其他地方运行时（远程模式）才使用 browser serve。

沙箱会话

如果代理会话被沙箱化，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"

注意：

此模式依赖于 CDP 上的 Playwright 来执行大多数操作（截图/快照/操作）。
再次单击扩展图标以分离。

隔离保证

专用用户数据目录：从不接触你的个人浏览器配置文件。
专用端口：避免 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：

状态/启动/停止：GET /、POST /start、POST /stop
标签页：GET /tabs、POST /tabs/open、POST /tabs/focus、DELETE /tabs/:targetId
快照/截图：GET /snapshot、POST /screenshot
操作：POST /navigate、POST /act
钩子：POST /hooks/file-chooser、POST /hooks/dialog
下载：POST /download、POST /wait/download
调试：GET /console、POST /pdf
调试：GET /errors、GET /requests、POST /trace/start、POST /trace/stop、POST /highlight
网络：POST /response/body
状态：GET /cookies、POST /cookies/set、POST /cookies/clear
状态：GET /storage/:kind、POST /storage/:kind/set、POST /storage/:kind/clear
设置：POST /set/offline、POST /set/headers、POST /set/credentials、POST /set/geolocation、POST /set/media、POST /set/timezone、POST /set/locale、POST /set/device

所有端点都接受 ?profile=<name>。

Playwright 要求

某些功能（导航/操作/AI 快照/角色快照、元素截图、PDF）需要 Playwright。如果未安装 Playwright，这些端点会返回明确的 501 错误。ARIA 快照和基本截图对于 clawd 托管的 Chrome 仍然有效。对于 Chrome 扩展中继驱动程序，ARIA 快照和截图需要 Playwright。

如果你看到 Playwright is not available in this gateway build，请安装完整的 Playwright 包（不是 playwright-core）并重启网关，或重新安装支持浏览器的 Moltbot。

工作原理（内部）

高级流程：

一个小型控制服务器接受 HTTP 请求。
它通过 CDP 与基于 Chromium 的浏览器（Chrome/Brave/Edge/Chromium）连接。
对于高级操作（单击/输入/快照/PDF），它在 CDP 之上使用 Playwright。
当缺少 Playwright 时，仅非 Playwright 操作可用。

这种设计使代理保持稳定、确定性的接口，同时允许你交换本地/远程浏览器和配置文件。

CLI 快速参考

所有命令都接受 --browser-profile <name> 以定位特定的配置文件。所有命令还接受 --json 以获得机器可读的输出（稳定有效负载）。

基础：

moltbot browser status
moltbot browser start
moltbot browser stop
moltbot browser tabs
moltbot browser tab
moltbot browser tab new
moltbot browser tab select 2
moltbot browser tab close 2
moltbot browser open https://example.com
moltbot browser focus abcd1234
moltbot browser close abcd1234

检查：

moltbot browser screenshot
moltbot browser screenshot --full-page
moltbot browser screenshot --ref 12
moltbot browser screenshot --ref e12
moltbot browser snapshot
moltbot browser snapshot --format aria --limit 200
moltbot browser snapshot --interactive --compact --depth 6
moltbot browser snapshot --efficient
moltbot browser snapshot --labels
moltbot browser snapshot --selector "#main" --interactive
moltbot browser snapshot --frame "iframe#main" --interactive
moltbot browser console --level error
moltbot browser errors --clear
moltbot browser requests --filter api --clear
moltbot browser pdf
moltbot browser responsebody "**/api" --max-chars 5000

操作：

moltbot browser navigate https://example.com
moltbot browser resize 1280 720
moltbot browser click 12 --double
moltbot browser click e12 --double
moltbot browser type 23 "hello" --submit
moltbot browser press Enter
moltbot browser hover 44
moltbot browser scrollintoview e12
moltbot browser drag 10 11
moltbot browser select 9 OptionA OptionB
moltbot browser download e12 /tmp/report.pdf
moltbot browser waitfordownload /tmp/report.pdf
moltbot browser upload /tmp/file.pdf
moltbot browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
moltbot browser dialog --accept
moltbot browser wait --text "Done"
moltbot browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
moltbot browser evaluate --fn '(el) => el.textContent' --ref 7
moltbot browser highlight e12
moltbot browser trace start
moltbot browser trace stop

状态：

moltbot browser cookies
moltbot browser cookies set session abc123 --url "https://example.com"
moltbot browser cookies clear
moltbot browser storage local get
moltbot browser storage local set theme dark
moltbot browser storage session clear
moltbot browser set offline on
moltbot browser set headers --json '{"X-Debug":"1"}'
moltbot browser set credentials user pass
moltbot browser set credentials --clear
moltbot browser set geo 37.7749 -122.4194 --origin "https://example.com"
moltbot browser set geo --clear
moltbot browser set media dark
moltbot browser set timezone America/New_York
moltbot browser set locale en-US
moltbot browser set device "iPhone 14"

注意：

upload 和 dialog 是武装调用；在触发选择器/对话框的单击/按下之前运行它们。
upload 也可以通过 --input-ref 或 --element 直接设置文件输入。
snapshot：
- --format ai（安装 Playwright 时的默认值）：返回带有数字引用的 AI 快照（aria-ref="<n>"）。
- --format aria：返回可访问性树（无引用；仅检查）。
- --efficient（或 --mode efficient）：紧凑的角色快照预设（interactive + compact + depth + 更低的 maxChars）。
- 配置默认值（仅限工具/CLI）：设置 browser.snapshotDefaults.mode: "efficient" 以在调用方未传递模式时使用高效快照（参见网关配置）。
- 角色快照选项（--interactive、--compact、--depth、--selector、--frame）强制使用带有像 ref=e12 这样的引用的基于角色的快照。
- --frame "<iframe selector>" 将角色快照限制为 iframe（与像 e12 这样的角色引用配对）。
- --interactive 输出交互元素的扁平、易于选择的列表（最适合驱动操作）。
- --labels 添加带有覆盖引用标签的仅视口截图（打印 MEDIA:<path>）。
click/type/等需要来自 snapshot 的 ref（数字 12 或角色引用 e12）。故意不支持操作使用 CSS 选择器。

快照和引用

Moltbot 支持两种"快照"样式：

AI 快照（数字引用）：moltbot browser snapshot（默认；--format ai）
- 输出：包含数字引用的文本快照。
- 操作：moltbot browser click 12、moltbot browser type 23 "hello"。
- 内部，引用通过 Playwright 的 aria-ref 解析。
角色快照（像 e12 这样的角色引用）：moltbot browser snapshot --interactive（或 --compact、--depth、--selector、--frame）
- 输出：带有 [ref=e12]（以及可选的 [nth=1]）的基于角色的列表/树。
- 操作：moltbot browser click e12、moltbot browser highlight e12。
- 内部，引用通过 getByRole(...)（加上 nth() 用于重复项）解析。
- 添加 --labels 以包含带有覆盖的 e12 标签的视口截图。

引用行为：

引用在导航之间不稳定；如果失败，请重新运行 snapshot 并使用新的引用。
如果角色快照是用 --frame 拍摄的，角色引用将限制为该 iframe，直到下一个角色快照。

等待增强功能

你可以等待的不仅仅是时间/文本：

等待 URL（Playwright 支持 glob）：
- moltbot browser wait --url "**/dash"
等待加载状态：
- moltbot browser wait --load networkidle
等待 JS 谓词：
- moltbot browser wait --fn "window.ready===true"
等待选择器变得可见：
- moltbot browser wait "#main"

这些可以组合：

moltbot browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

调试工作流

当操作失败时（例如"不可见"、“严格模式违规”、“被覆盖”）：

moltbot browser snapshot --interactive
使用 click <ref> / type <ref>（在交互模式下优先使用角色引用）
如果仍然失败：moltbot browser highlight <ref> 以查看 Playwright 正在定位的内容
如果页面行为异常：
- moltbot browser errors --clear
- moltbot browser requests --filter api --clear
对于深度调试：记录跟踪：
- moltbot browser trace start
- 重现问题
- moltbot browser trace stop（打印 TRACE:<path>）

JSON 输出

--json 用于脚本和结构化工具。

示例：

moltbot browser status --json
moltbot browser snapshot --interactive --json
moltbot browser requests --filter api --json
moltbot browser cookies --json

JSON 中的角色快照包括 refs 加上一个小的 stats 块（行/字符/引用/交互），以便工具可以推理有效负载大小和密度。

状态和环境控制

这些对于"让站点表现得像 X"的工作流很有用：

Cookies：cookies、cookies set、cookies clear
Storage：storage local|session get|set|clear
Offline：set offline on|off
Headers：set headers --json '{"X-Debug":"1"}'（或 --clear）
HTTP 基本身份验证：set credentials user pass（或 --clear）
地理位置：set geo <lat> <lon> --origin "https://example.com"（或 --clear）
媒体：set media dark|light|no-preference|none
时区/区域设置：set timezone ...、set locale ...
设备/视口：
- set device "iPhone 14"（Playwright 设备预设）
- set viewport 1280 720

安全和隐私

clawd 浏览器配置文件可能包含登录的会话；将其视为敏感信息。
有关登录和反机器人注意事项（X/Twitter 等），请参见浏览器登录 + X/Twitter 发布。
保持控制 URL 仅限环回，除非你有意暴露服务器。
远程 CDP 端点功能强大；请通过隧道保护它们。

故障排除

有关 Linux 特定问题（特别是 snap Chromium），请参见浏览器故障排除。

代理工具 + 控制工作原理

代理获得一个工具用于浏览器自动化：

browser — 状态/启动/停止/标签页/打开/聚焦/关闭/快照/截图/导航/操作

如何映射：

browser snapshot 返回稳定的 UI 树（AI 或 ARIA）。
browser act 使用快照 ref ID 来单击/输入/拖动/选择。
browser screenshot 捕获像素（整页或元素）。
browser 接受：
- profile 以选择命名的浏览器配置文件（主机或远程控制服务器）。
- target（sandbox | host | custom）以选择浏览器的位置。
- controlUrl 隐式设置 target: "custom"（远程控制服务器）。
- 在沙箱会话中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
- 如果省略 target：沙箱会话默认为 sandbox，非沙箱会话默认为 host。
- 沙箱允许列表可以将 target: "custom" 限制为特定的 URL/主机/端口。
- 默认值：允许列表未设置（无限制），并且沙箱主机控制被禁用。

这使代理保持确定性，并避免了脆弱的选择器。

技能配置浏览器登录 + X/Twitter 发布

浏览器 (clawd 托管)

适用范围

你将获得

快速开始

配置文件：clawd vs chrome

配置

使用 Brave（或其他基于 Chromium 的浏览器）

本地 vs 远程控制

远程浏览器（控制服务器）

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

Browserless（托管的远程 CDP）

在浏览器机器上运行控制服务器

安全

令牌（什么与什么共享？）

绑定（不要意外暴露到 LAN）

TLS / HTTPS（推荐方法：前端终止）

配置文件（多浏览器）

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

沙箱会话

设置

隔离保证

浏览器选择

控制 API（可选）

Playwright 要求

工作原理（内部）

CLI 快速参考

快照和引用

等待增强功能

调试工作流

JSON 输出

状态和环境控制

安全和隐私

故障排除

代理工具 + 控制工作原理

配置文件：`clawd` vs `chrome`