浏览器（CoderClaw 托管）

浏览器（coderclaw 托管）

CoderClaw 可以运行一个由智能体控制的专用 Chrome/Brave/Edge/Chromium 配置文件。它与你的个人浏览器隔离，通过 Gateway 网关内部的小型本地控制服务进行管理（仅限 loopback）。

新手视角：

把它想象成一个独立的、仅供智能体使用的浏览器。
coderclaw 配置文件不会触及你的个人浏览器配置文件。
智能体可以在安全的通道中打开标签页、读取页面、点击和输入。
默认的 chrome 配置文件通过扩展中继使用系统默认的 Chromium 浏览器；切换到 coderclaw 可使用隔离的托管浏览器。

功能概览

一个名为 coderclaw 的独立浏览器配置文件（默认橙色主题）。
确定性标签页控制（列出/打开/聚焦/关闭）。
智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。
可选的多配置文件支持（coderclaw、work、remote 等）。

此浏览器不是你的日常浏览器。它是一个安全、隔离的界面，用于智能体自动化和验证。

快速开始

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

如果出现”Browser disabled”，请在配置中启用它（见下文）并重启 Gateway 网关。

配置文件：`coderclaw` 与 `chrome`

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

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

配置

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

{
  browser: {
    enabled: true, // default: true
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    defaultProfile: "chrome",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      coderclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

注意事项：

浏览器控制服务绑定到 loopback 上的端口，该端口从 gateway.port 派生（默认：18791，即 gateway + 2）。中继使用下一个端口（18792）。
如果你覆盖了 Gateway 网关端口（gateway.port 或 CODERCLAW_GATEWAY_PORT），派生的浏览器端口会相应调整以保持在同一”系列”中。
未设置时，cdpUrl 默认为中继端口。
remoteCdpTimeoutMs 适用于远程（非 loopback）CDP 可达性检查。
remoteCdpHandshakeTimeoutMs 适用于远程 CDP WebSocket 可达性检查。
attachOnly: true 表示”永不启动本地浏览器；仅在浏览器已运行时附加”。
color + 每个配置文件的 color 为浏览器 UI 着色，以便你能看到哪个配置文件处于活动状态。
默认配置文件是 chrome（扩展中继）。使用 defaultProfile: "coderclaw" 来使用托管浏览器。
自动检测顺序：如果系统默认浏览器是基于 Chromium 的则使用它；否则 Chrome → Brave → Edge → Chromium → Chrome Canary。
本地 coderclaw 配置文件会自动分配 cdpPort/cdpUrl — 仅为远程 CDP 设置这些。

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

如果你的系统默认浏览器是基于 Chromium 的（Chrome/Brave/Edge 等），CoderClaw 会自动使用它。设置 browser.executablePath 可覆盖自动检测：

CLI 示例：

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

本地控制与远程控制

本地控制（默认）： Gateway 网关启动 loopback 控制服务，可以启动本地浏览器。
远程控制（节点主机）： 在有浏览器的机器上运行节点主机；Gateway 网关将浏览器操作代理到该节点。
远程 CDP： 设置 browser.profiles.<name>.cdpUrl（或 browser.cdpUrl）以附加到远程的基于 Chromium 的浏览器。在这种情况下，CoderClaw 不会启动本地浏览器。

远程 CDP URL 可以包含认证信息：

查询令牌（例如 https://provider.example?token=<token>）
HTTP Basic 认证（例如 https://user:[email protected]）

CoderClaw 在调用 /json/* 端点和连接 CDP WebSocket 时会保留认证信息。建议使用环境变量或密钥管理器存储令牌，而不是将其提交到配置文件中。

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

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

注意事项：

节点主机通过代理命令暴露其本地浏览器控制服务器。
配置文件来自节点自己的 browser.profiles 配置（与本地相同）。
如果不需要可以禁用：
- 在节点上：nodeHost.browserProxy.enabled=false
- 在 Gateway 网关上：gateway.nodes.browser.mode="off"

Browserless（托管远程 CDP）

Browserless 是一个托管的 Chromium 服务，通过 HTTPS 暴露 CDP 端点。你可以将 CoderClaw 浏览器配置文件指向 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 账户匹配的区域端点（请参阅其文档）。

安全性

核心理念：

浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对进行。
将 Gateway 网关和任何节点主机保持在私有网络上（Tailscale）；避免公开暴露。
将远程 CDP URL/令牌视为机密；优先使用环境变量或密钥管理器。

远程 CDP 提示：

尽可能使用 HTTPS 端点和短期令牌。
避免在配置文件中直接嵌入长期令牌。

配置文件（多浏览器）

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

coderclaw 托管：具有独立用户数据目录和 CDP 端口的专用基于 Chromium 的浏览器实例
远程：显式 CDP URL（在其他地方运行的基于 Chromium 的浏览器）
扩展中继：通过本地中继 + Chrome 扩展访问你现有的 Chrome 标签页

默认值：

如果缺少 coderclaw 配置文件，会自动创建。
chrome 配置文件是内置的，用于 Chrome 扩展中继（默认指向 http://127.0.0.1:18792）。
本地 CDP 端口默认从 18800–18899 分配。
删除配置文件会将其本地数据目录移至回收站。

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

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

CoderClaw 还可以通过本地 CDP 中继 + Chrome 扩展驱动你现有的 Chrome 标签页（无需单独的”coderclaw”Chrome 实例）。

完整指南：Chrome 扩展

流程：

Gateway 网关在本地运行（同一台机器）或节点主机在浏览器所在机器上运行。
本地中继服务器在 loopback 的 cdpUrl 上监听（默认：http://127.0.0.1:18792）。
你点击标签页上的 CoderClaw Browser Relay 扩展图标来附加（它不会自动附加）。
智能体通过选择正确的配置文件，使用普通的 browser 工具控制该标签页。

如果 Gateway 网关在其他地方运行，请在浏览器所在机器上运行节点主机，以便 Gateway 网关可以代理浏览器操作。

沙箱会话

如果智能体会话是沙箱隔离的，browser 工具可能默认为 target="sandbox"（沙箱浏览器）。 Chrome 扩展中继接管需要主机浏览器控制，因此要么：

在非沙箱模式下运行会话，或者
设置 agents.defaults.sandbox.browser.allowHostControl: true 并在调用工具时使用 target="host"。

设置

加载扩展（开发/未打包）：

coderclaw browser extension install

Chrome → chrome://extensions → 启用”开发者模式”
“加载已解压的扩展程序” → 选择 coderclaw browser extension path 打印的目录
固定扩展，然后在你想要控制的标签页上点击它（徽章显示 ON）。

使用它：

CLI：coderclaw browser --browser-profile chrome tabs
智能体工具：browser 配合 profile="chrome"

可选：如果你想要不同的名称或中继端口，创建你自己的配置文件：

coderclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

注意事项：

此模式依赖 Playwright-on-CDP 进行大多数操作（截图/快照/操作）。
再次点击扩展图标可分离。

隔离保证

专用用户数据目录：永不触及你的个人浏览器配置文件。
专用端口：避免使用 9222 以防止与开发工作流冲突。
确定性标签页控制：通过 targetId 定位标签页，而非”最后一个标签页”。

浏览器选择

本地启动时，CoderClaw 选择第一个可用的：

Chrome
Brave
Edge
Chromium
Chrome Canary

你可以使用 browser.executablePath 覆盖。

平台：

macOS：检查 /Applications 和 ~/Applications。
Linux：查找 google-chrome、brave、microsoft-edge、chromium 等。
Windows：检查常见安装位置。

控制 API（可选）

仅用于本地集成，Gateway 网关暴露一个小型的 loopback 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 要求

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

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

Docker Playwright 安装

如果你的 Gateway 网关在 Docker 中运行，避免使用 npx playwright（npm 覆盖冲突）。改用捆绑的 CLI：

docker compose run --rm coderclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

要持久化浏览器下载，设置 PLAYWRIGHT_BROWSERS_PATH（例如 /home/node/.cache/ms-playwright）并确保 /home/node 通过 CODERCLAW_HOME_VOLUME 或绑定挂载持久化。参见 Docker。

工作原理（内部）

高层流程：

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

这种设计使智能体保持在稳定、确定性的接口上，同时让你可以切换本地/远程浏览器和配置文件。

CLI 快速参考

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

基础操作：

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

检查：

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

操作：

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

状态：

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

注意事项：

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

快照和 ref

CoderClaw 支持两种”快照”风格：

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

ref 行为：

ref 在导航之间不稳定；如果出错，重新运行 snapshot 并使用新的 ref。
如果角色快照是使用 --frame 拍摄的，角色 ref 将限定在该 iframe 内，直到下一次角色快照。

等待增强功能

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

等待 URL（Playwright 支持通配符）：
- coderclaw browser wait --url "**/dash"
等待加载状态：
- coderclaw browser wait --load networkidle
等待 JS 断言：
- coderclaw browser wait --fn "window.ready===true"
等待选择器变得可见：
- coderclaw browser wait "#main"

这些可以组合使用：

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

调试工作流

当操作失败时（例如”not visible”、“strict mode violation”、“covered”）：

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

JSON 输出

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

示例：

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

JSON 格式的角色快照包含 refs 加上一个小的 stats 块（lines/chars/refs/interactive），以便工具可以推断负载大小和密度。

状态和环境开关

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

Cookies：cookies、cookies set、cookies clear
存储：storage local|session get|set|clear
离线：set offline on|off
请求头：set headers --json '{"X-Debug":"1"}'（或 --clear）
HTTP basic 认证：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

安全与隐私

coderclaw 浏览器配置文件可能包含已登录的会话；请将其视为敏感信息。
browser act kind=evaluate / coderclaw browser evaluate 和 wait --fn 在页面上下文中执行任意 JavaScript。提示注入可能会操纵它。如果不需要，请使用 browser.evaluateEnabled=false 禁用它。
有关登录和反机器人注意事项（X/Twitter 等），请参阅浏览器登录 + X/Twitter 发帖。
保持 Gateway 网关/节点主机私有（仅限 loopback 或 tailnet）。
远程 CDP 端点功能强大；请通过隧道保护它们。

故障排除

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

智能体工具 + 控制工作原理

智能体获得一个工具用于浏览器自动化：

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 来选择命名的浏览器配置文件（coderclaw、chrome 或远程 CDP）。
- target（sandbox | host | node）来选择浏览器所在位置。
- 在沙箱会话中，target: "host" 需要 agents.defaults.sandbox.browser.allowHostControl=true。
- 如果省略 target：沙箱会话默认为 sandbox，非沙箱会话默认为 host。
- 如果连接了具有浏览器能力的节点，工具可能会自动路由到该节点，除非你指定 target="host" 或 target="node"。

这使智能体保持确定性并避免脆弱的选择器。

浏览器（CoderClaw 托管）

浏览器（coderclaw 托管）

功能概览

快速开始

配置文件：coderclaw 与 chrome

配置

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

本地控制与远程控制

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

Browserless（托管远程 CDP）

安全性

配置文件（多浏览器）

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

沙箱会话

设置

隔离保证

浏览器选择

控制 API（可选）

Playwright 要求

Docker Playwright 安装

工作原理（内部）

CLI 快速参考

快照和 ref

等待增强功能

调试工作流

JSON 输出

状态和环境开关

安全与隐私

故障排除

智能体工具 + 控制工作原理

配置文件：`coderclaw` 与 `chrome`