跳转到主要内容
Gologin Cloud Browser 可以作为 AI 智能体的远程浏览器运行环境。 智能体(Claude、Codex 或任何支持工具调用的智能体)可以触发您的代码连接到 Cloud Browser 会话,并执行真实的浏览器操作,例如导航、点击、输入和数据提取。 这使得以下智能体工作流成为可能:
  • JavaScript 渲染和真实的用户交互(点击、滚动、填写表单)
  • 通过配置文件实现持久会话(Cookie/存储)
  • 代理路由和可重复使用的浏览器配置
不想从零开始编写工具? 使用 Agent Browser CLI 或 AI Skills 即可获得现成的智能体能力,无需编写 Puppeteer/Playwright 代码。
注意:本页介绍的是一种技术集成模式。它不会改变目标网站的规则,也不保证一定能够访问。

集成模式概览

AI 智能体通常不会直接“连接到浏览器”。它们的工作方式是:
  1. 规划下一步要做什么
  2. 调用您提供的工具/函数(工具调用)
  3. 读取结构化结果并继续执行
使用 Gologin Cloud Browser 时,您的工具/函数会执行以下操作:
  1. 连接到云端会话(令牌 + 可选的配置文件)
  2. 执行浏览器操作(导航、点击、提取、截图)
  3. 将结构化结果返回给智能体

推荐架构

AI 智能体(Claude / Codex / 其他) -> 调用您的工具服务器(您的 Node/Python 服务) -> 工具服务器使用 Playwright/Puppeteer -> 连接到 Gologin Cloud Browser(远程端点) -> 将结果(文本/JSON/截图引用)返回给智能体 采用此模式的原因:
  • 您的 Gologin 令牌始终保留在服务器端
  • 您可以应用速率限制、重试、日志记录和安全检查
  • 您可以一致地复用配置文件和代理

前提条件

1) API 令牌(服务器端)

在 Gologin 应用中创建您的令牌:API & MCP → API → 新代币。
请将令牌视为机密信息,不要在客户端代码中暴露它。

2)(推荐)通过 REST API 管理配置文件和代理

Cloud Browser 是执行/运行时层。要管理配置文件(创建/更新)并配置代理,请使用 REST API:
重要提示: 如果配置文件的代理配置有误或无法访问,云浏览器会话将因代理超时错误而无法启动。连接前请确认代理可以访问,或在测试时将代理模式设置为 none。

两种 URL——了解其区别

Gologin 为 Cloud Browser 提供两种不同的 URL,它们的用途不同: 只有 /connect 端点适用于 Puppeteer/Playwright。 实时视图 URL 返回的是 HTML 流式界面,不能用作 browserWSEndpoint。

连接到云端会话

请使用标准的 Cloud Browser 端点:
  • token — 您的 Gologin API 令牌
  • profile — 配置文件 ID(可选)
    • 如果需要持久会话和可控的配置,请使用 profileId
    • 如果省略 profile,可能会为该会话创建一个新的配置文件
/connect 端点会自动启动浏览器会话,连接之前无需单独调用 API。 实现示例(Puppeteer/Playwright): https://gologin.com/docs/api-reference/cloud-browser/getting-started

预置 CLI 工具与自定义工具

为智能体提供浏览器访问能力有两种方式:

方式 A:使用 Gologin CLI 工具(适合大多数情况,推荐)

  • Agent Browser CLI — 现成的 CLI,包含 open、snapshot、click、type、fill、screenshot、close 以及 30 多个其他命令。内置常驻守护进程、基于引用的交互方式,以及专为智能体循环设计的精简输出。
  • Web Access CLI — 将抓取(Web Unlocker)与浏览器交互合二为一的统一 CLI。
  • AI Skills — 适用于 Claude Code 的即插即用技能,可自动处理所有事项。

方式 B:使用 Puppeteer/Playwright 构建自定义工具

如果您需要完全的控制权,可以围绕 Playwright/Puppeteer 实现一小组封装函数,并将它们作为工具提供出来。 通常一组最小集合就足够了:
  • open_url(url)
  • click(selector)
  • type(selector, text)
  • wait_for(selector | timeout)
  • extract_text(selector | page)
  • screenshot()
  • close_session()
这些并不是 Gologin 的专有 API,而是对标准 Playwright/Puppeteer 命令的轻量封装,针对 Cloud Browser 会话执行。

关键:跨工具调用的会话管理

这是智能体工作流中最重要的架构问题。 AI 智能体会在多个步骤中依次调用工具。每次工具调用都必须复用同一个浏览器连接——如果每次工具调用都创建新的 puppeteer.connect(),就会丢失步骤之间的 Cookie、本地存储和页面状态。 推荐模式: 在您的工具服务器上维护一个会话单例。
随后,每个工具通过调用 getSession() 来获取共享实例:

工具应向智能体返回什么?

请返回精简的结构化结果,以便智能体可靠地继续执行,例如:
  • 当前 URL
  • 提取的文本 / JSON
  • 是否找到了元素
  • 截图引用(如果您保存了截图)
  • 错误类型(超时、导航错误等)

运维说明

  • 安全: 将令牌保留在服务器端,切勿将其嵌入客户端应用。
  • 会话管理: 完成后请关闭会话,以避免达到并发上限。智能体工作流完成时请调用 closeSession()。
  • 可靠性: 针对临时性故障(超时、导航错误)添加重试/退避机制。
  • 可观测性: 调试时,可在可用的情况下打开实时视图。URL 格式示例: https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/

限制

  • 结果取决于目标网站和您的配置。
  • 网站可能会阻止自动化操作;Cloud Browser 只是一个运行环境,不能保证一定成功。
  • 同时从多个会话连接到同一个配置文件可能会引起冲突——同一时间每个配置文件请只使用一个连接。
  • 适用配额和速率限制: https://gologin.com/docs/api-reference/limitations/rate-limits