- JavaScript 渲染和真实的用户交互(点击、滚动、填写表单)
- 通过配置文件实现持久会话(Cookie/存储)
- 代理路由和可重复使用的浏览器配置
注意:本页介绍的是一种技术集成模式。它不会改变目标网站的规则,也不保证一定能够访问。
集成模式概览
AI 智能体通常不会直接“连接到浏览器”。它们的工作方式是:- 规划下一步要做什么
- 调用您提供的工具/函数(工具调用)
- 读取结构化结果并继续执行
- 连接到云端会话(令牌 + 可选的配置文件)
- 执行浏览器操作(导航、点击、提取、截图)
- 将结构化结果返回给智能体
推荐架构
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:- Profiles API:https://gologin.com/docs/api-reference/profile
- Proxy API:https://gologin.com/docs/api-reference/proxy
重要提示: 如果配置文件的代理配置有误或无法访问,云浏览器会话将因代理超时错误而无法启动。连接前请确认代理可以访问,或在测试时将代理模式设置为 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()
关键:跨工具调用的会话管理
这是智能体工作流中最重要的架构问题。 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