如何在LangChain中解决reCAPTCHA
Ethan Collins
Pattern Recognition Specialist
reCAPTCHA是AI代理在浏览网页时最常见的验证挑战。执行数据收集、表单提交或多步骤工作流的LangChain代理在登录页面、搜索结果和受保护内容上会遇到reCAPTCHA v2复选框和不可见挑战。本教程演示了如何使用CapSolver的capsolver-agent包在LangChain中解决reCAPTCHA v2，提供Token模式和Browser模式的完整代码示例。
TL;DR
- reCAPTCHA v2是LangChain网络代理最常遇到的验证码类型
- CapSolver的LangChain工具在5-12秒内平均解决reCAPTCHA v2（复选框和不可见）
- Token模式只需站点密钥和URL——无需浏览器
- Browser模式可自动检测页面上的reCAPTCHA并将令牌填回DOM
capsolver-agent包为LangChain的ReAct代理提供了原生的BaseTool实现
为什么reCAPTCHA会阻止LangChain代理
reCAPTCHA v2部署在数百万个网站上，用于区分人类用户和自动化流量。当LangChain代理导航到受保护页面时——无论是用于潜在客户增强、数据提取还是工作流自动化——Google的风险分析引擎会评估会话。自动化浏览器、无头环境和快速导航模式会触发reCAPTCHA挑战，暂停代理的执行。
挑战有两种形式：可见的复选框（"我不是机器人"）需要交互，以及基于风险评分无声触发的不可见变体。两种形式都需要有效的令牌提交才能继续。没有解决机制，LangChain代理无法继续其任务，整个链将失败。
Google的reCAPTCHA文档确认该系统使用包括浏览器环境检查、交互模式和历史行为在内的高级风险分析。这使得reCAPTCHA对缺乏人类浏览模式的自动化代理特别具有挑战性。
CapSolver的AI驱动解决服务通过其云基础设施生成有效令牌来处理reCAPTCHA v2，绕过了代理上下文中对像素级交互或图像识别的需求。
开始前需要准备什么
安装所需包：
bash
# 核心引擎（必需依赖项）
pip install git+https://github.com/capsolver-ai/capsolver-core.git
# 带有LangChain支持的代理工具
pip install "capsolver-agent[langchain] @ git+https://github.com/capsolver-ai/capsolver-agent.git"
# LangChain运行时
pip install langchain-openai langgraph设置环境变量：
bash
export CAPSOLVER_API_KEY="your-capsolver-api-key"
export OPENAI_API_KEY="your-openai-api-key"您还需要从目标页面获取reCAPTCHA站点密钥。使用CapSolver浏览器扩展来识别它，或检查页面源代码中的data-sitekey属性。reCAPTCHA识别指南解释了如何区分v2复选框、v2不可见和v3变体。
第1步——在目标页面上识别reCAPTCHA v2参数
要做什么
在目标页面上找到reCAPTCHA站点密钥。打开浏览器开发者工具并搜索页面源代码：
html
<!-- 可见的reCAPTCHA v2（复选框） -->
<div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<!-- 不可见的reCAPTCHA v2 -->
<div class="g-recaptcha" data-sitekey="6LeIxAcT..." data-size="invisible"></div>记录三个值：data-sitekey、完整页面URL以及是否可见（检查data-size="invisible"）。
使用CapSolver SDK进行程序化检测：
python
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright
async def detect_recaptcha(url: str):
cap = create_capsolver(api_key="YOUR_API_KEY")
async with async_playwright() as p:
browser = await p.chromium.launch()
page = await browser.new_page()
await page.goto(url)
# 自动检测页面上的所有CAPTCHAs
infos = await cap.get_captcha_info(page)
for info in infos:
print(f"类型: {info.type}, 密钥: {info.website_key}")
await browser.close()
await cap.aclose()为什么这很重要
站点密钥是reCAPTCHA解决的关键参数。没有它，解决服务无法为特定站点生成有效令牌。同一域的不同页面可能使用不同的站点密钥，因此请始终按页面验证。
避免的常见错误
- 在生产中使用测试密钥：Google提供测试密钥（如
6LeIxAcT...）总是通过。真实站点使用需要实际解决的独特密钥。 - 混淆v2和v3：reCAPTCHA v3使用不同的任务类型并需要
page_action。检查脚本源——v3通过?render=SITE_KEY加载，而不是div元素。
第2步——使用LangChain工具（Token模式）解决reCAPTCHA v2
要做什么
使用capsolver-agent LangChain工具在代理的工作流中解决reCAPTCHA v2：
python
import asyncio
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from capsolver_agent.langchain import get_langchain_tools
async def solve_recaptcha_with_agent():
# 获取CapSolver LangChain工具
tools = get_langchain_tools(api_key="YOUR_CAPSOLVER_API_KEY")
# 创建ReAct代理
llm = ChatOpenAI(model="gpt-4o", temperature=0)
agent = create_react_agent(llm, tools=tools)
# 要求代理解决reCAPTCHA
result = await agent.ainvoke({
"messages": [("user",
"在https://example.com/login上解决reCAPTCHA v2。 "
"站点密钥是6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI。 "
"返回我可以用来提交表单的令牌。"
)]
})
print(result["messages"][-1].content)
asyncio.run(solve_recaptcha_with_agent())对于不需要代理循环的直接执行（当您需要程序控制时）：
python
from capsolver_agent.schema import create_executor
async def solve_recaptcha_direct():
executor = create_executor(api_key="YOUR_CAPSOLVER_API_KEY")
result = await executor.execute("solve_captcha", {
"captcha_type": "reCaptchaV2",
"website_url": "https://example.com/login",
"website_key": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
})
if result["success"]:
token = result["solution"]["token"]
print(f"reCAPTCHA已解决！令牌: {token[:60]}...")
# 将此令牌作为'g-recaptcha-response'提交到表单POST
return token
else:
print(f"失败: {result['error']}")
return None返回的令牌应作为表单POST请求中的g-recaptcha-response字段提交。reCAPTCHA v2解决文档提供了有关令牌提交模式的其他详细信息。
为什么这很重要
Token模式是reCAPTCHA v2最快的解决方案——平均解决时间为5-12秒，没有浏览器开销。对于已经知道目标站点参数的LangChain代理，这提供了立即清除CAPTCHA的能力，而无需启动浏览器实例。
避免的常见错误
- 未快速提交令牌：reCAPTCHA令牌大约在120秒后过期。收到令牌后立即提交表单。
- 遗漏不可见标志：对于不可见的reCAPTCHA v2，解决方法相同，但您可能需要在注入后触发表单提交回调。
第3步——处理不可见的reCAPTCHA v2
要做什么
不可见的reCAPTCHA v2在API方面与可见版本相同——相同的reCaptchaV2任务类型处理两种变体：
python
# 不可见的reCAPTCHA v2 —— 相同的API调用
result = await executor.execute("solve_captcha", {
"captcha_type": "reCaptchaV2",
"website_url": "https://example.com/checkout",
"website_key": "6Ld_SITE_KEY_HERE"
# 无需额外标志——CapSolver自动处理不可见
})区别在于如何注入令牌。不可见的reCAPTCHA通常绑定到按钮点击或表单提交事件。获得令牌后，触发回调：
python
# 在解决后的Playwright/浏览器上下文中：
await page.evaluate(f"""() => {{
document.getElementById('g-recaptcha-response').innerHTML = '{token}';
// 触发绑定的回调
if (typeof ___grecaptcha_cfg !== 'undefined') {{
const clients = ___grecaptcha_cfg.clients;
for (const key in clients) {{
const client = clients[key];
// 查找并调用回调
if (client && client.L && client.L.L && client.L.L.callback) {{
client.L.L.callback('{token}');
}}
}}
}}
}}""")reCAPTCHA回调识别指南解释了如何为任何网站定位正确的回调函数。
第4步——使用Browser模式自动检测和解决reCAPTCHA
要做什么
当您的LangChain代理驱动浏览器并动态遇到reCAPTCHA时，使用solve_on_page()进行自动检测和填回：
python
import asyncio
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright
async def auto_solve_recaptcha(target_url: str):
"""自动检测并解决任何页面上的reCAPTCHA。"""
cap = create_capsolver(api_key="YOUR_CAPSOLVER_API_KEY")
async with async_playwright() as p:
browser = await p.chromium.launch(headless=True)
page = await browser.new_page()
await page.goto(target_url)
await page.wait_for_load_state("networkidle")
# 一个调用处理所有事情：检测→解决→填回
results = await cap.solve_on_page(page)
for r in results:
if r.solution:
print(f"解决 {r.info.type}: token={r.solution.token[:50]}...")
print(f"令牌已填入页面: {r.filled}")
else:
print(f"无法解决 {r.info.type}: {r.error}")
# 解决后，页面已准备就绪——提交表单
submit_button = page.locator('button[type="submit"]')
if await submit_button.count() > 0:
await submit_button.click()
await page.wait_for_navigation()
print(f"表单已提交。当前URL: {page.url}")
await browser.close()
await cap.aclose()
asyncio.run(auto_solve_recaptcha("https://example.com/login"))Browser模式特别强大，因为它直接从实时DOM中读取reCAPTCHA参数——无需手动提取站点密钥。SDK会识别CAPTCHA类型，读取data-sitekey，解决它，并自动将令牌写入g-recaptcha-response文本区域。
领取您的优惠码：在CapSolver仪表板使用代码WEBS，每次充值可额外获得5%的奖励。非常适合构建处理reCAPTCHA挑战的LangChain开发人员。
第5步——构建具有reCAPTCHA处理功能的生产级LangChain代理
要做什么
将reCAPTCHA解决与其他工具结合，实现完整的生产工作流：
python
import asyncio
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from capsolver_agent.langchain import get_langchain_tools
async def production_agent():
capsolver_tools = get_langchain_tools(api_key="YOUR_CAPSOLVER_API_KEY")
llm = ChatOpenAI(model="gpt-4o", temperature=0)
agent = create_react_agent(llm, tools=capsolver_tools)
# 需要reCAPTCHA解决的多步骤任务
result = await agent.ainvoke({
"messages": [("user",
"我需要访问受保护的资源。 "
"首先，在https://example.com/gate解决reCAPTCHA v2 "
"(站点密钥: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI)， "
"然后告诉我令牌，以便我继续我的请求。"
)]
})
return result["messages"][-1].content
asyncio.run(production_agent())对于需要处理不同网站上多个reCAPTCHA版本的代理，相同的工具可以处理v2和v3——只需将captcha_type参数从reCaptchaV2更改为reCaptchaV3。
CapSolver产品页面列出了所有支持的CAPTCHA类型及其定价，帮助您估算LangChain代理部署的成本。
结论
在LangChain中解决reCAPTCHA需要capsolver-agent包和LangChain额外功能，它提供了原生的BaseTool实现。Token模式在5-12秒内无需浏览器解决已知站点密钥，而Browser模式可自动检测并填回任何页面上的reCAPTCHA令牌。CapSolver为AI解决基础设施提供支持，通过统一接口支持reCAPTCHA v2复选框和不可见变体。
首先在目标页面上识别站点密钥，然后将get_langchain_tools()集成到您的ReAct代理中。代理的推理循环自然决定何时调用reCAPTCHA解决，使验证处理成为您自动化工作流中透明的一部分。
常见问题
使用CapSolver解决reCAPTCHA v2的成功率是多少？
CapSolver在reCAPTCHA v2挑战中实现95-99%的成功率。该AI驱动的解决服务处理复选框和不可见变体。失败尝试不会收费，结构化的错误响应允许您的代理自动重试。
解决reCAPTCHA v2需要多长时间？
reCAPTCHA v2的平均解决时间是5-12秒。这包括到CapSolver服务的网络往返时间和AI识别过程。对于时间敏感的工作流，SDK支持可配置的超时和轮询间隔。
LangChain工具能处理reCAPTCHA Enterprise吗？
是的。在调用solve_captcha时传递enterprise: true参数。reCAPTCHA Enterprise使用相同的v2/v3任务类型，但可能需要额外参数如"s"令牌。CapSolver服务会透明处理Enterprise变体。
在LangChain中解决reCAPTCHA是否需要浏览器？
不。令牌模式无需任何浏览器——您提供网站密钥和URL，然后会收到一个令牌。浏览器模式（需要Playwright）是可选的，用于在需要对实时页面进行自动检测和填写时。大多数LangChain集成使用令牌模式以简化流程和提高速度。
如何处理reCAPTCHA令牌过期？
reCAPTCHA令牌大约在120秒后过期。尽可能在表单提交前请求令牌。如果您的工作流在解决和提交之间有延迟，请采用“在提交前解决”的模式，而不是在流程早期解决。