如何通过TinyFish AgentQL解决CAPTCHA – 使用CapSolver的分步指南

当你的AI驱动的网页自动化遇到验证码墙时，整个流程都会停滞。页面无法加载，表单无法提交，数据提取也会停止——这一切都是因为验证码设计用来阻止机器人。TinyFish AgentQL 是一个强大的工具套件，用于将AI连接到网络，具有自然语言查询、Playwright集成和企业级结构化数据提取功能。但像任何浏览器自动化框架一样，它也会被验证码卡住。

CapSolver 完全改变了这一点。通过将 CapSolver Chrome 扩展加载到 AgentQL 的 Playwright 驱动的浏览器上下文中，验证码会在后台自动且不可见地被解决。无需手动解决，也不需要在你的端进行复杂的 API 协调。你的自动化脚本可以继续运行，就像没有验证码一样。

最棒的是？你的 AgentQL 查询和脚本不需要任何一行验证码相关的代码。扩展程序会自行处理检测、解决和令牌注入，而你的代理则专注于它最擅长的事情——提取数据和自动化工作流程。

什么是 TinyFish AgentQL？

TinyFish AgentQL是一个企业级工具包，用于将AI代理和LLM连接到实时网络环境。由 TinyFish 开发，它提供了一种AI驱动的查询语言，允许你使用自然语言定位页面元素并提取结构化数据——无需脆弱的CSS选择器或XPaths。

主要功能

• AI驱动的查询语言：根据页面内容直观地查找元素。随着UI随时间变化，查询会自我修复。
• Playwright集成：Python 和 JavaScript SDK 可与 Playwright 无缝集成，实现高级浏览器自动化。
• 结构化数据提取：定义输出结构，从任何页面（公开或私有，静态或动态）获取干净的结构化数据。
• REST API：通过REST 端点执行查询，无需 SDK。
• 浏览器调试器：一个Chrome 扩展，用于实时测试和优化查询。
• 跨站点弹性：无需修改即可在类似网站上运行，动态适应页面变化。
• 企业级规模：专为高吞吐量工作负载设计，可并行运行数百个任务。

AgentQL 可以在任何页面上运行——包括经过身份验证的内容和动态生成的页面——使其成为大规模网页自动化、数据收集和AI代理工作流程的理想选择。

什么是 CapSolver？

CapSolver是一个领先的AI驱动的验证码解决服务，可以自动解决各种验证码挑战。凭借快速的响应时间和广泛的兼容性，CapSolver 可无缝集成到自动化工作流中。

支持的验证码类型

• reCAPTCHA v2（复选框和不可见）
• reCAPTCHA v3 & v3 企业版
• Cloudflare Turnstile
• Cloudflare 5秒挑战
• AWS WAF 验证码
• 更多

为什么这个集成与众不同

大多数验证码解决集成需要你编写样板代码：创建任务、轮询结果、将令牌注入隐藏字段。这是使用原始 Playwright 或 Puppeteer 脚本的标准方法。

AgentQL + CapSolver 采用了根本不同的方法：

关键洞察：CapSolver 扩展运行在 AgentQL 的 Playwright 浏览器上下文中。当 AgentQL 导航到包含验证码的页面时，扩展会检测到它，在后台解决它，并注入令牌——在你的脚本与表单交互之前。你的自动化代码保持简洁、专注且无验证码。

前提条件

在设置集成之前，请确保你已：

• 安装 TinyFish AgentQL（Python SDK 或 JavaScript SDK）
• 一个 CapSolver 账户和 API 密钥（注册在这里）
• Node.js 16+和 **Python 3.8+**（根据你的 SDK 选择）
• 安装 Playwright并包含 Chromium

重要提示：Chrome 扩展仅在 Chromium 中使用持久上下文时有效。这是 Playwright 的要求，而不是 AgentQL 的限制。

分步设置

步骤 1：安装 AgentQL

Python SDK:

pipinstallagentql playwrightinstallchromium

JavaScript SDK:

npminstallagentql npx playwrightinstallchromium

步骤 2：下载 CapSolver Chrome 扩展

将 CapSolver Chrome 扩展下载到专用目录：

1. 访问CapSolver Chrome 扩展 v1.17.0 发布页面
2. 下载CapSolver.Browser.Extension-chrome-v1.17.0.zip
3. 解压 zip 文件：

mkdir -p ~/capsolver-extensionunzip CapSolver.Browser.Extension-chrome-v*.zip-d ~/capsolver-extension/

4. 验证解压是否成功：

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", headless=False,# 扩展需要非无头模式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 就变得简单了。

黄金法则

不要编写验证码特定的代码。只需在与验证码保护的表单交互前添加等待时间，让扩展处理其工作。

示例 1：reCAPTCHA 后的表单提交

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("john@example.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()

示例 2：Cloudflare 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("me@example.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']}星)")

推荐的等待时间

提示：如果不确定，使用 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 时：

1. Chromium 启动并加载 CapSolver 扩展
2. 扩展激活 —— 其服务工作者启动，并将内容脚本注入每个页面
3. 在包含验证码的页面上 —— 内容脚本检测到小部件，调用 CapSolver API，并将解决方案令牌注入页面
4. AgentQL 正常运行 —— 查询、点击和数据提取如常进行，验证码已处理

完整配置参考

以下是 AgentQL + CapSolver 集成的完整 Python 设置：

importagentql from playwright.sync_apiimportsync_playwrightimportos# 配置CAPSOLVER_EXTENSION_PATH= os.path.expanduser("~/capsolver-extension")USER_DATA_DIR="./browser-data"withsync_playwright() as p:context= p.chromium.launch_persistent_context(user_data_dir=USER_DATA_DIR,headless=False,args=[f"--disable-extensions-except={CAPSOLVER_EXTENSION_PATH}", f"--load-extension={CAPSOLVER_EXTENSION_PATH}", ], )page= agentql.wrap(context.pages[0])# ... 你的自动化代码在这里context.close()

配置选项

CapSolver API 密钥直接在扩展的assets/config.js文件中配置（参见上文步骤 3）。

故障排除

扩展未加载

症状: CAPTCHAs 未被自动解决。

原因: 您可能使用了常规浏览器上下文而不是持久化上下文，或在无头模式下运行。

解决方案: Playwright 中的扩展需要持久化上下文和有头模式：

# ✅ 正确 — 持久化上下文，有头模式context= p.chromium.launch_persistent_context(user_data_dir="./browser-data",headless=False,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=:99

Google 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/

最佳实践

1. 始终使用较长的等待时间。更长的等待时间总是更安全。CAPTCHA 通常在 5-20 秒内解决，但网络延迟、复杂挑战或重试可能会增加时间。30-60 秒是最佳选择。

2. 保持自动化脚本简洁。不要在 AgentQL 查询中添加特定于 CAPTCHA 的逻辑。扩展会处理一切 —— 您的代码应专注于数据提取和交互。

3. 监控您的 CapSolver 余额。每次 CAPTCHA 解决都会消耗积分。定期查看capsolver.com/dashboard以避免中断。

4. 一致地使用持久化上下文。当需要扩展时，始终使用launch_persistent_context()。这也可以在运行之间保留 cookies 和会话数据，从而减少 CAPTCHA 出现的频率。

5. 在无头服务器上使用 Xvfb。Chrome 扩展需要显示上下文。在没有物理显示器的服务器环境中设置 Xvfb。

结论

TinyFish AgentQL + CapSolver 集成将隐形 CAPTCHA 解决方案带入了目前最强大的网络自动化工具包之一。您无需编写复杂的 CAPTCHA 处理代码，只需：

1. 下载 CapSolver 扩展并配置您的 API 密钥
2. 通过持久化上下文加载扩展来启动 AgentQL 的 Playwright 浏览器
3. 按照常规方式编写自动化脚本 —— 在提交表单前添加等待时间

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 扩展需要有头浏览器。对于没有显示器的服务器环境，请使用 Xvfb（X 虚拟帧缓冲区）创建虚拟显示器。

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 被解决？

对于大多数 CAPTCHA，30-60 秒足够。实际解决时间通常为 5-20 秒，但添加额外的缓冲时间可以确保可靠性。如果不确定，使用 30 秒。