当你的AI驱动的网页自动化遇到验证码墙时整个流程都会停滞。页面无法加载表单无法提交数据提取也会停止——这一切都是因为验证码设计用来阻止机器人。TinyFish AgentQL 是一个强大的工具套件用于将AI连接到网络具有自然语言查询、Playwright集成和企业级结构化数据提取功能。但像任何浏览器自动化框架一样它也会被验证码卡住。CapSolver 完全改变了这一点。通过将 CapSolver Chrome 扩展加载到 AgentQL 的 Playwright 驱动的浏览器上下文中验证码会在后台自动且不可见地被解决。无需手动解决也不需要在你的端进行复杂的 API 协调。你的自动化脚本可以继续运行就像没有验证码一样。最棒的是你的 AgentQL 查询和脚本不需要任何一行验证码相关的代码。扩展程序会自行处理检测、解决和令牌注入而你的代理则专注于它最擅长的事情——提取数据和自动化工作流程。什么是 TinyFish AgentQLTinyFish AgentQL是一个企业级工具包用于将AI代理和LLM连接到实时网络环境。由 TinyFish 开发它提供了一种AI驱动的查询语言允许你使用自然语言定位页面元素并提取结构化数据——无需脆弱的CSS选择器或XPaths。主要功能AI驱动的查询语言根据页面内容直观地查找元素。随着UI随时间变化查询会自我修复。Playwright集成Python 和 JavaScript SDK 可与 Playwright 无缝集成实现高级浏览器自动化。结构化数据提取定义输出结构从任何页面公开或私有静态或动态获取干净的结构化数据。REST API通过REST 端点执行查询无需 SDK。浏览器调试器一个Chrome 扩展用于实时测试和优化查询。跨站点弹性无需修改即可在类似网站上运行动态适应页面变化。企业级规模专为高吞吐量工作负载设计可并行运行数百个任务。AgentQL 可以在任何页面上运行——包括经过身份验证的内容和动态生成的页面——使其成为大规模网页自动化、数据收集和AI代理工作流程的理想选择。什么是 CapSolverCapSolver是一个领先的AI驱动的验证码解决服务可以自动解决各种验证码挑战。凭借快速的响应时间和广泛的兼容性CapSolver 可无缝集成到自动化工作流中。支持的验证码类型reCAPTCHA v2复选框和不可见reCAPTCHA v3 v3 企业版Cloudflare TurnstileCloudflare 5秒挑战AWS WAF 验证码更多为什么这个集成与众不同大多数验证码解决集成需要你编写样板代码创建任务、轮询结果、将令牌注入隐藏字段。这是使用原始 Playwright 或 Puppeteer 脚本的标准方法。AgentQL CapSolver 采用了根本不同的方法传统基于代码AgentQL CapSolver 扩展编写 CapSolver 服务类在 Playwright 上下文中加载扩展调用createTask()/getTaskResult()扩展自动处理一切通过page.evaluate()注入令牌令牌注入是不可见的在代码中处理错误、重试、超时扩展在内部管理重试每种验证码类型需要不同的代码自动处理所有类型关键洞察CapSolver 扩展运行在 AgentQL 的 Playwright 浏览器上下文中。当 AgentQL 导航到包含验证码的页面时扩展会检测到它在后台解决它并注入令牌——在你的脚本与表单交互之前。你的自动化代码保持简洁、专注且无验证码。前提条件在设置集成之前请确保你已安装 TinyFish AgentQLPython SDK 或 JavaScript SDK一个 CapSolver 账户和 API 密钥注册在这里Node.js 16和 **Python 3.8**根据你的 SDK 选择安装 Playwright并包含 Chromium重要提示Chrome 扩展仅在 Chromium 中使用持久上下文时有效。这是 Playwright 的要求而不是 AgentQL 的限制。分步设置步骤 1安装 AgentQLPython SDK:pipinstallagentql playwrightinstallchromiumJavaScript SDK:npminstallagentql npx playwrightinstallchromium步骤 2下载 CapSolver Chrome 扩展将 CapSolver Chrome 扩展下载到专用目录访问CapSolver Chrome 扩展 v1.17.0 发布页面下载CapSolver.Browser.Extension-chrome-v1.17.0.zip解压 zip 文件mkdir -p ~/capsolver-extensionunzip CapSolver.Browser.Extension-chrome-v*.zip-d ~/capsolver-extension/验证解压是否成功ls ~/capsolver-extension/manifest.json你应该看到manifest.json—— 这确认了扩展已放置在正确的位置。步骤 3配置你的 CapSolver API 密钥打开扩展配置文件~/capsolver-extension/assets/config.js并将apiKey值替换为你的密钥exportconstdefaultConfig { apiKey:CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX,// ← 你的密钥在这里useCapsolver:true,// ...其余配置};你可以从你的CapSolver 仪表板获取你的 API 密钥。步骤 4使用 CapSolver 扩展启动 AgentQL关键步骤是使用持久上下文启动 Playwright 的 Chromium加载 CapSolver 扩展。Python 示例:importagentqlfromplaywright.sync_apiimportsync_playwrightimporttimeimportos# CapSolver 扩展路径CAPSOLVER_EXTENSION_PATH os.path.expanduser(~/capsolver-extension)defmain():withsync_playwright()asp:# 使用持久上下文和 CapSolver 扩展启动 Chromiumcontext p.chromium.launch_persistent_context( user_data_dir./browser-data, headlessFalse,# 扩展需要非无头模式args[f--disable-extensions-except{CAPSOLVER_EXTENSION_PATH},f--load-extension{CAPSOLVER_EXTENSION_PATH}, ], )# 使用 AgentQL 包装页面进行 AI 驱动的查询page agentql.wrap(context.pages[0])# 导航到目标页面page.goto(https://example.com/protected-page)# 等待 CapSolver 检测并解决任何验证码time.sleep(30)# 使用 AgentQL 的自然语言查询查找并点击提交按钮response page.query_elements( { submit_button } )# 点击提交按钮 —— 验证码已解决response.submit_button.click()# 提交后提取数据result page.query_data( { confirmation_message } )print(f结果:{result[confirmation_message]}) context.close()if__name__ __main__: main()JavaScript 示例:const{ chromium } require(playwright);constagentql require(agentql);constpath require(path);constos require(os);constCAPSOLVER_EXTENSION_PATH path.join(os.homedir(),capsolver-extension); (async() {// 使用持久上下文和 CapSolver 扩展启动 Chromiumconstcontext awaitchromium.launchPersistentContext(./browser-data, {headless:false,// 扩展需要非无头模式args: [--disable-extensions-except${CAPSOLVER_EXTENSION_PATH},--load-extension${CAPSOLVER_EXTENSION_PATH}, ], });// 获取第一个页面并用 AgentQL 包装constpage agentql.wrap(context.pages()[0]);// 导航到目标页面awaitpage.goto(https://example.com/protected-page);// 等待 CapSolver 处理任何验证码awaitpage.waitForTimeout(30000);// 使用 AgentQL 查询进行交互 —— 验证码已解决constresponse awaitpage.queryElements({ submit_button });awaitresponse.submit_button.click();// 提取结果数据constresult awaitpage.queryData({ confirmation_message });console.log(结果:, result.confirmation_message);awaitcontext.close(); })();步骤 5验证扩展是否已加载启动浏览器后你可以在浏览器窗口中导航到chrome://extensions来验证 CapSolver 扩展是否已激活。你应该看到 CapSolver 扩展已列出并启用。或者在浏览器控制台中检查 CapSolver 日志消息确认服务工作者正在运行。如何使用一旦设置完成使用 CapSolver 与 AgentQL 就变得简单了。黄金法则不要编写验证码特定的代码。只需在与验证码保护的表单交互前添加等待时间让扩展处理其工作。示例 1reCAPTCHA 后的表单提交page.goto(https://example.com/contact)# 使用 AgentQL 查询填写表单response page.query_elements( { contact_form { name_field email_field message_field submit_button } } ) response.contact_form.name_field.fill(John Doe) response.contact_form.email_field.fill(johnexample.com) response.contact_form.message_field.fill(Hello, I have a question about your services.)# 等待 CapSolver 解决验证码time.sleep(30)# 提交 —— 验证码令牌已注入response.contact_form.submit_button.click()示例 2Cloudflare Turnstile 登录页面page.goto(https://example.com/login)# 等待 CapSolver 解决 Turnstile 挑战time.sleep(25)# 使用 AgentQL 查找登录表单元素response page.query_elements( { login_form { email_input password_input login_button } } )# 填写表单 —— Turnstile 已处理response.login_form.email_input.fill(meexample.com) response.login_form.password_input.fill(mypassword123)# 点击登录response.login_form.login_button.click()示例 3受保护页面的数据提取page.goto(https://example.com/data)# 等待任何验证码挑战清除time.sleep(30)# 使用 AgentQL 提取结构化数据data page.query_data( { products[] { name price rating availability } } )forproductindata[products]:print(f{product[name]}: ${product[price]}({product[rating]}星))推荐的等待时间验证码类型典型解决时间推荐等待reCAPTCHA v2复选框5-15 秒30-60 秒reCAPTCHA v2不可见5-15 秒30 秒reCAPTCHA v33-10 秒20-30 秒Cloudflare Turnstile3-10 秒20-30 秒提示如果不确定使用 30 秒。等待更长时间比过早提交更好。额外的时间不会影响结果。背后的工作原理以下是 AgentQL 在加载 CapSolver 扩展时发生的情况你的 AgentQL 脚本 ─────────────────────────────────────────────────── page.goto(https://...) ──► Chromium 加载页面 │ ▼ ┌─────────────────────────────┐ │ 包含验证码小部件的页面 │ │ │ │ CapSolver 扩展 │ │1. 内容脚本检测页面上的验证码 │ │2. 服务工作者调用 CapSolver API │ │3. 接收令牌 │ │4. 将令牌注入隐藏表单字段 │ └─────────────────────────────┘ │ ▼time.sleep(30) 扩展解决验证码... │ ▼ page.query_elements(...) AgentQL 找到表单元素 submit_button.click() 表单提交带有有效令牌 │ ▼验证成功扩展如何加载当 Playwright 使用--load-extension标志启动 Chromium 时Chromium 启动并加载 CapSolver 扩展扩展激活 —— 其服务工作者启动并将内容脚本注入每个页面在包含验证码的页面上 —— 内容脚本检测到小部件调用 CapSolver API并将解决方案令牌注入页面AgentQL 正常运行 —— 查询、点击和数据提取如常进行验证码已处理完整配置参考以下是 AgentQL CapSolver 集成的完整 Python 设置importagentql from playwright.sync_apiimportsync_playwrightimportos# 配置CAPSOLVER_EXTENSION_PATH os.path.expanduser(~/capsolver-extension)USER_DATA_DIR./browser-datawithsync_playwright() as p:context p.chromium.launch_persistent_context(user_data_dirUSER_DATA_DIR,headlessFalse,args[f--disable-extensions-except{CAPSOLVER_EXTENSION_PATH}, f--load-extension{CAPSOLVER_EXTENSION_PATH}, ], )page agentql.wrap(context.pages[0])# ... 你的自动化代码在这里context.close()配置选项选项描述user_data_dir存储浏览器配置文件数据cookie、会话的目录。对于持久上下文是必需的。headless必须为False— Chrome 扩展在无头模式下无法运行。--disable-extensions-except限制哪些扩展可以加载防止冲突。--load-extension未打包的 CapSolver 扩展目录的路径。CAPSOLVER_EXTENSION_PATH包含manifest.json的已解压 CapSolver 扩展的完整路径。CapSolver API 密钥直接在扩展的assets/config.js文件中配置参见上文步骤 3。故障排除扩展未加载症状: CAPTCHAs 未被自动解决。原因: 您可能使用了常规浏览器上下文而不是持久化上下文或在无头模式下运行。解决方案: Playwright 中的扩展需要持久化上下文和有头模式# ✅ 正确 — 持久化上下文有头模式context p.chromium.launch_persistent_context(user_data_dir./browser-data,headlessFalse,args[...扩展参数...])# ❌ 错误 — 常规上下文扩展不会加载browser p.chromium.launch()context browser.new_context()CAPTCHA 未被解决表单失败可能原因:等待时间不足— 增加至 60 秒无效的 API 密钥— 检查您的 CapSolver 仪表板余额不足— 为您的 CapSolver 账户充值扩展未加载— 参见“扩展未加载”部分无头模式不被支持症状: 脚本运行但无扩展显示。原因: Chrome 扩展在无头模式下无法运行。解决方案: 在服务器上使用有头模式和虚拟显示# 安装 Xvfbsudo apt-getinstall xvfb# 启动虚拟显示Xvfb :99 -screen 0 1280x720x24 # 设置 DISPLAYexportDISPLAY:99Google Chrome 137 兼容性症状: 扩展标志被静默忽略。原因: Google Chrome 137 移除了品牌构建中对--load-extension的支持。解决方案: 使用 Playwright 的捆绑 Chromium推荐或 Chrome for Testing:# 安装 Playwright 的 Chromium推荐npx playwright install chromium# 或下载 Chrome for Testing# 访问: https://googlechromelabs.github.io/chrome-for-testing/最佳实践始终使用较长的等待时间。更长的等待时间总是更安全。CAPTCHA 通常在 5-20 秒内解决但网络延迟、复杂挑战或重试可能会增加时间。30-60 秒是最佳选择。保持自动化脚本简洁。不要在 AgentQL 查询中添加特定于 CAPTCHA 的逻辑。扩展会处理一切 —— 您的代码应专注于数据提取和交互。监控您的 CapSolver 余额。每次 CAPTCHA 解决都会消耗积分。定期查看capsolver.com/dashboard以避免中断。一致地使用持久化上下文。当需要扩展时始终使用launch_persistent_context()。这也可以在运行之间保留 cookies 和会话数据从而减少 CAPTCHA 出现的频率。在无头服务器上使用 Xvfb。Chrome 扩展需要显示上下文。在没有物理显示器的服务器环境中设置 Xvfb。结论TinyFish AgentQL CapSolver 集成将隐形 CAPTCHA 解决方案带入了目前最强大的网络自动化工具包之一。您无需编写复杂的 CAPTCHA 处理代码只需下载 CapSolver 扩展并配置您的 API 密钥通过持久化上下文加载扩展来启动 AgentQL 的 Playwright 浏览器按照常规方式编写自动化脚本 —— 在提交表单前添加等待时间CapSolver Chrome 扩展会处理其余部分 —— 检测 CAPTCHA、通过 CapSolver API 解决它们并将令牌注入页面。您的 AgentQL 脚本根本不需要知道任何关于 CAPTCHA 的信息。当您将 AI 驱动的网络自动化与 AI 驱动的 CAPTCHA 解决方案结合时这就是 CAPTCHA 解决方案的样子隐形、自动且无需代码。准备好开始了吗注册 CapSolver并使用优惠码AGENTQL在首次充值时获得额外 6% 的优惠FAQ我需要在 AgentQL 脚本中编写特定于 CAPTCHA 的代码吗不需要。CapSolver 扩展在 Playwright 浏览器上下文中完全在后台运行。在提交表单前添加time.sleep()或waitForTimeout()扩展会自动处理检测、解决和令牌注入。为什么需要持久化上下文Playwright 仅在使用launch_persistent_context()时支持 Chrome 扩展。这是 Playwright 架构的要求。通过browser.new_context()创建的常规浏览器上下文无法加载扩展。我可以在无头模式下运行吗不可以。Chrome 扩展需要有头浏览器。对于没有显示器的服务器环境请使用 XvfbX 虚拟帧缓冲区创建虚拟显示器。CapSolver 支持哪些 CAPTCHA 类型CapSolver 支持 reCAPTCHA v2复选框和隐形、reCAPTCHA v3、Cloudflare Turnstile、AWS WAF CAPTCHA 等。扩展会自动检测 CAPTCHA 类型并相应解决。CapSolver 的费用是多少CapSolver 提供基于 CAPTCHA 类型和数量的具有竞争力的定价。访问capsolver.com查看当前价格。TinyFish AgentQL 是免费的吗AgentQL 提供免费和付费版本。SDK 和查询语言可用于开发和测试。访问tinyfish.ai查看定价详情。我应该等待多久让 CAPTCHA 被解决对于大多数 CAPTCHA30-60 秒足够。实际解决时间通常为 5-20 秒但添加额外的缓冲时间可以确保可靠性。如果不确定使用 30 秒。