如何在LangChain中解决reCAPTCHA

Ethan Collins

Pattern Recognition Specialist

08-Jul-2026

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秒后过期。尽可能在表单提交前请求令牌。如果您的工作流在解决和提交之间有延迟，请采用“在提交前解决”的模式，而不是在流程早期解决。

合规声明：本博客提供的信息仅供参考。CapSolver 致力于遵守所有适用的法律和法规。严禁以非法、欺诈或滥用活动使用 CapSolver 网络，任何此类行为将受到调查。我们的验证码解决方案在确保 100% 合规的同时，帮助解决公共数据爬取过程中的验证码难题。我们鼓励负责任地使用我们的服务。如需更多信息，请访问我们的服务条款和隐私政策。