• 简体中文

      • 浏览器 API

      aiod 连接已经启动的 Chromium，不负责启动浏览器。连接地址由两个环境变量决定：

      环境变量默认值含义
      BROWSER_REMOTE_DEBUGGING_HOST127.0.0.1Chromium 调试端口所在主机
      BROWSER_REMOTE_DEBUGGING_PORT9222Chromium 调试端口

      可以使用 Playwright、Puppeteer 等 CDP 客户端，也可以直接调用 REST API。/v1/browser/* 和 /v2/browser/* 的请求体相同；桌面操作除外：v1 使用 POST /v1/browser/actions，v2 使用 /v2/computer。详见 Computer Use。

      运行要求

      GET /v2/sandbox 返回 capabilities.browser：

      GET /v1/capabilities 返回 browser.status：

      状态何时仍然可用
      ready调试端口上 CDP 有应答全部路由
      degraded找到了浏览器可执行文件，但 CDP 不可达info、network/requests
      absent两者都没有info、network/requests

      不是 ready 时，其余工具不可用。见 Sandbox。

      CDP

      获取 CDP URL

      aiod 向 BROWSER_REMOTE_DEBUGGING_HOST:PORT 上的 Chromium 请求 /json/version，取其中的 webSocketDebuggerUrl，再按请求头改写成对外地址：

      组成取值
      主机X-Forwarded-Host，没有则取 Host
      协议X-Forwarded-Proto 为 https 时用 wss，否则用 ws
      路径前缀X-Forwarded-Prefix，没有则为空
      # BASE_URL=https://sandbox.example.com
curl "$BASE_URL/v2/browser/info"
      # BASE_URL=https://sandbox.example.com
curl "$BASE_URL/v1/browser/info"
      {
  "data": {
    "cdp_url": "wss://sandbox.example.com/cdp/devtools/browser/46164812-5f92-4ec5-891a-8c138aeb93a4",
    "cdp_ui_url": null
  }
}

      Chromium 没有应答时，cdp_url 仍按同样格式返回一个占位地址，恢复后重新调用即可。

      Playwright 和 Puppeteer 直接连接 cdp_url，示例见 浏览器（CDP）。反向代理、路径前缀和鉴权参数的处理见 CDP 接入。

      发送原始 CDP 命令

      路由作用说明
      POST /cdp发送一条原始 CDP 命令结果放在 data 里

      REST 没有覆盖的能力走这个入口。需要连续发多条命令时，直接用 cdp_url 建立 CDP 连接。

      REST 接口

      不需要完整 CDP 客户端的操作，aiod 提供一套精简 REST。返回结构都是标准的 {success, message, data}，完整的请求和响应结构见 API 参考。

      这些路由挂在 /v2/browser 下：

      这些路由挂在 /v1/browser 下：

      navigate、evaluate、snapshot、click、fill、upload 和 cdp 可以用 tab_id 指定标签页，不传时作用于列表中的第一个标签页。screenshot 不支持 tab_id，始终截取第一个标签页。

      导航与脚本执行

      路由作用说明
      POST /navigate加载 URL，或在历史记录里移动传 url 或 history，两者都传时以 url 为准
      POST /evaluate在页面主世界里执行 JavaScript按值返回结果，await_promise 会等待 Promise
      {
  "url": "https://example.com",
  "wait_until": "load"
}
      • wait_until 可选 load、domcontentloaded、networkidle、commit，默认 load。
      • timeout 默认 30 秒，超时返回 503，标签页仍可继续使用。
      • history 可取 back、forward、reload。
      • evaluate 的结果在 data.value，JavaScript 异常在 data.exception，HTTP 状态仍是 200。

      截图

      路由作用说明
      GET /screenshot截取当前页面响应体就是图片

      format 可选 png（默认）、jpeg、jpg；quality 取 0–100，只对 jpeg 生效，默认 85。full_page=true 截取整个可滚动页面。PNG 响应带 x-image-width 和 x-image-height。

      页面快照

      路由作用说明
      POST /snapshot返回页面结构interactive_only 只保留可操作元素
      POST /click点击元素用 ref 或 CSS selector
      POST /fill填写输入框用 ref 或 CSS selector
      POST /upload上传文件用 ref 或 CSS selector

      ref 来自 snapshot。每次导航后都要重新取快照，旧的 ref 不再有效。

      标签页

      路由作用说明
      GET /tabs列出标签页每项包含 id、title、url、type
      POST /tabs打开标签页url 可选，默认 about:blank
      POST /tabs/{tab_id}/activate把标签页切到最前它会移到列表最前面，未知 id 返回 404
      DELETE /tabs/{tab_id}关闭标签页未知 id 返回 404

      新打开的标签页排在列表最前面，并成为默认目标。

      路由作用说明
      POST /cookies设置 cookiebody 里的 cookies 是一个列表，响应返回条数
      GET /cookies读取 cookie可按 url 或 domain 收窄
      DELETE /cookies删除一条或全部name 配合 url 或 domain，或者 all=true

      结构沿用 CDP 的定义。设置时必须提供 name，以及 url 或 domain 和 path，其他字段可选。

      请求日志

      路由作用说明
      GET /network/requests页面请求的只读日志limit 限制条数，clear=true 读取后清空

      从第一次调用后开始收集，最多保留最近 300 条。不支持请求拦截和请求头改写。

      窗口大小

      路由作用说明
      POST /config通过 CDP 调整窗口大小resolution 必须是支持的尺寸，其他组合返回 422

      不传 resolution 时不修改窗口。

      错误处理

      状态码说明
      400参数缺失或请求体不是 JSON
      404元素或标签页不存在
      422参数值不受支持
      503CDP 不可达、导航超时或 CDP 执行失败

      JavaScript 异常不算 HTTP 错误：evaluate 仍返回 200，异常放在 data.exception 里。

      桌面操作

      真实的鼠标和键盘事件由 computer-use worker 执行，不是页面级操作，worker 未运行时返回 503。

      调用 POST /v2/computer/actions，见 Computer Use。

      调用 POST /v1/browser/actions，见 Computer Use。

      MCP 工具

      支持 MCP 的 agent 通过 /mcp 调用浏览器工具。daemon 自带 browser_get_info，以及 computer-use 可用时的 browser_gui_screenshot 和 browser_gui_execute_action。

      AIO 镜像在 loopback 上运行 @agent-infra/mcp-server-browser，并把它注册成 /mcp 的上游，镜像里页面级的 browser_* 导航工具由此而来。注册方式见 MCP。

      选择调用方式

      三种入口操作的是同一个 Chromium：

      入口提供代价
      CDP 客户端完整的页面自动化能力需要 CDP 客户端和 WebSocket
      REST API常用浏览器操作一次请求执行一个操作
      MCP以工具形式调用浏览器需要 MCP 客户端

      需要完整的页面自动化时使用 CDP；只做常用操作时直接调用 REST API；已经接入 MCP 的 agent 可以使用 MCP。

      Human in the loop

      人可以直接查看或接管 agent 正在操作的 Chromium。两种查看方式连接的是同一个浏览器环境：

      查看方式地址可以看到
      noVNC/vnc/index.html?autoconnect=true整个桌面，包括 Chromium、对话框和其他窗口
      DevTools/browser-ui、/cdp/devtools/*当前 Chromium 页面

      noVNC 连接的是整个桌面，而不是单独的浏览器窗口。因此可以操作文件选择框、地址栏和其他应用窗口。即使 Chromium 重启，桌面仍会保留。noVNC 页面也可以嵌入 iframe。

      人和 agent 共享同一个浏览器状态。例如，在 noVNC 中完成登录后，agent 下一次调用 snapshot 就能看到登录后的页面。

      daemon 只提供 API；noVNC 和 DevTools 页面由镜像网关提供。部署和访问方式见 Computer Use。