AI 代理验证码在本地可用但在云端失败：解决方法

摘要

• 当验证码处理在本地正常、但在云端失败时，在修改智能体提示词之前，先比较部署时的运行时环境和浏览器。
• 安装在你桌面浏览器中的扩展程序，并不会自动出现在云端工作进程或远程服务创建的浏览器中。
• CapSolver 面向浏览器的 Core SDK 方法需要 Playwright 依赖；仅安装 token 模式并不能提供同样的功能。
• 仅仅“无头模式”并不会让扩展变得不可能：Playwright 文档给出了受支持的 Chromium 配置，而托管浏览器也有自己的能力范围。
• 在真正调用 solver 的进程中检查凭证和出站连通性，并确认它实际控制的是预期的页面。
• 重现一个被允许的任务，修复一个部署差异，并在恢复定时任务前确认应用的最终结果。

你的 AI 智能体在开发机上能处理验证码，但部署后在同一步骤停住。模型可能根本没有变化。缺失的环节往往要简单得多：云镜像缺依赖、浏览器没有扩展，或者工作进程无法读取配置的 API 密钥。

CapSolver 提供多种验证码集成路径，把智能体迁到云端可能会改变实际运行的路径。本文用一个本地运行成功的案例与云端失败的部署做对比。目标场景是假定已有合法授权的工作流，而不是从零开始接一个新框架。目的在于在不增加更多工具、不重构智能体的前提下，找到一个可复现的环境差异。

从本地与云端部署差异入手

最快的起点，是并排记录两次运行所用的浏览器、solver 处理器、凭证与页面。

“本地”可以指智能体进程本身在本机运行，而它控制的浏览器托管在远程。“云端”可以指你自己的虚拟机、容器，或某个托管浏览器服务。这些结构暴露出的控制点不同，因此不要只依赖“本地 / 云端”的标签，要写清实际组件。

对比最近一次本地成功运行与一次云端失败运行，记录：

组件	要比较的内容
浏览器	可执行文件或托管服务、版本、启动模式和会话标识符
验证码处理器	扩展、直接 API、Core SDK、智能体工具或托管浏览器特性
运行时	已安装包的版本及可选依赖
凭证	实际执行进程是否收到了预期的机密版本
网络	哪个组件必须能访问 solver API、代理和目标页面
页面	最终 URL、选中的标签页、挑战类型和导航时序

这是在比较配置和观测结果，而不是要你导出整个浏览器配置文件。请涂抹掉 token、密码、cookie 和私密页面内容。

尽量对两次观测使用同一个小型且被允许的浏览任务。如果目标 URL、任务或应用状态不同，也要把差异记下来。否则，页面变更可能会被误认为部署回退问题。

检查 solver 是否真正接入了已部署的浏览器

云端浏览器需要自己的、可用的验证码处理器，即便你的桌面浏览器已经装好了。

常见的开发环境是：在本地浏览器中手工安装扩展，再由智能体控制同一个浏览器。干净的部署不会继承这份扩展安装。先确认 worker 创建或连接的是哪一个浏览器，然后通过受支持的管理接口检查其扩展或工具配置。

CapSolver 扩展介绍说明了其安装和设置。核实目标版本是否存在、是否对相关页面启用，并用该界面需要的账号信息完成配置。在另一个浏览器配置文件上成功的扩展安装，并不能证明云端会话也是如此。

如果你自己启动 Chromium

遵循该浏览器自动化库当前对扩展的要求。

Playwright 的扩展文档要求在 Chromium 中使用持久上下文，并推荐使用其自带的 Chromium 进行侧载。文档还说明了一个支持在无头模式下运行扩展的 Chromium 通道。因此，“扩展在无头模式下无法运行”并不是可靠的泛化诊断。

无头浏览器指没有可见界面的浏览器。关键问题是你用的是哪个可执行文件、什么启动配置，以及这种组合是否支持扩展。把所有云端任务都切换成有界面浏览器，无法修复缺失的扩展包或错误的浏览器连接。

检查部署中实际的启动参数和浏览器安装情况，和官方示例对照。在排查运行中保持这一已知配置不变。

如果由服务商启动浏览器

使用服务商文档中的扩展或验证码功能，而不是想当然地照搬桌面端安装步骤。

服务商可能提供扩展上传、内建验证码解决方案，或者仅提供浏览器连接而没有这些控制项。根据你使用的具体服务与账号配置，确认支持的路径。不要假定每个托管浏览器都自带自动验证码处理；也不要在不了解现有方案的情况下再叠加第二个处理器。

已有的 Browser Use 本地与云端指南解释了该框架的选择。这里的诊断原则更普适：找出失败运行中浏览器实际装的、实际启用的 handler。

比较已安装依赖和可用方法

部署时的包可能只支持 token 请求，却缺少本地代码所依赖的、与浏览器交互的方法。

CapSolver Core SDK 文档区分了 token 模式与面向浏览器的操作。文档写明，需要可选的 Playwright 依赖，才能使用检测和页面处理等浏览器方法。对比部署清单和已安装包，而不是只确认“存在一个叫 CapSolver 的包”。

如果失败点是 import 错误或缺少依赖，先解决这个问题，再去排查验证码本身。如果方法能运行但报告没有挑战，先检查所选页面和时序，不要立刻假定是云环境改变了挑战类型。

对于智能体工具，要确认该工具已在部署的 worker 中注册。在 notebook 或开发进程里本地注册的工具，不会自动配置到新启动的服务中。对比当前暴露的工具名称与官方 agent-tools 参考，并保证安装版本与示例保持一致。

这一检查不需要新增适配器。先确认预期的 handler 已可用，并能收到你现有集成期望的那些参数。

兑换你的 CapSolver 奖励码

立刻提升你的自动化预算！
在为 CapSolver 账号充值时使用奖励码 CAP26，每次充值都可额外获得 5% 奖励——无次数上限。
立即前往 CapSolver 控制台 进行兑换

在执行进程内验证凭证和网络访问

调用 solver 的进程必须拥有正确凭证，并有权限访问该服务。

开发者命令行、应用容器和后台 worker 可以接收到不同的环境变量。通过运行时支持的配置或诊断能力检查机密是否存在，但不要打印其值。如果平台要求“重启 / 重部署后配置才生效”，确认 worker 已按要求重启。

查看真实错误。CapSolver 的错误参考区分账号密钥、余额、任务数据和服务错误。从未到达 API 的请求则是单独的网络问题。多装几个浏览器包，无法修复缺失的账号密钥或被拒绝的出站连接。

如果工作流使用代理，先弄清代理配置在何处。浏览器代理、solver 任务代理和 API 客户端使用的网络代理，分别为不同的连接服务。只在任务文档要求的地方对比它们，不要假定一个设置会自动传播到三者。

对容器或远程 worker，还要理解本地地址的含义。localhost 上的端点指的是调用者自己的环境。在你笔记本上运行的浏览器服务，远程机器无法通过同一个本地地址访问。请使用部署环境支持的私有连接方式，而不是把浏览器调试端口暴露到公网。

确保 handler 绑定到正确的页面

solver 必须作用在当前存在挑战的真实页面上，而不是旧标签页或新建的空上下文。

远程浏览器连接代码可以“连接成功”，但却没有选择智能体正在使用的页面。调用 handler 前记录当前页面 URL 和浏览器会话，在其返回后再检查一次，尤其是当智能体可能在等待过程中导航、打开新标签或重启浏览器时。

Playwright 的BrowserType API 文档描述了其浏览器连接方式，包括仅适用于 Chromium 的 CDP 路径，以及它相较于 Playwright 协议连接的较低保真度。要把这些连接方式视为带有不同限制的文档化选择，而不要假定“本地启动”和“随便 attach 一个远程浏览器”会有完全一致的行为。

排障期间保持页面变化“可见”

在检查某个挑战时，暂停无关的智能体操作。刷新或上下文替换可能会导致一个迟到的结果指向更早的页面状态。

假设某个云端 worker 为截屏打开了第二个标签页，然后把那个标签页传给验证码 handler。即使 API 密钥、模型和包都正确，检测仍然会失败。关键证据是 handler 实际收到的是哪个页面。把提示词改成“再努力一点”，并不能修复标签页的选择错误。

另一个假设部署为每个工具调用都启动一个全新浏览器。那么“解决验证码”步骤和“应用的下一步操作”就发生在不同的会话中。修复方法是，在该操作结束前保持预期的浏览器所有权，并用集成所支持的连接生命周期来实现。

这些只是可能的配置错误示例，而不是对所有智能体框架的测量结论或泛化断言。

检查时间因素，而不是把所有失败都变成重试

云端部署可能增加排队或浏览器启动时间，因此要在失败步骤处对比时间戳，而不是一上来就延长整个任务的等待。

把浏览器启动、页面加载、提交 solver、solver 完成以及应用下一步动作区分开来。缺失扩展不会因为等待更久而自动出现。结果返回后页面已被替换，则需要重新评估上下文，而不是机械复用旧结果。

对 reCAPTCHA 而言，Google 的服务器端验证文档说明，响应 token 的有效期为两分钟，且只能验证一次。这是文档中对 reCAPTCHA 响应 token 的特定规定，而不是对所有验证码解决方案或浏览器会话的一般有效期。

让工作流的下一步尽量靠近“可用结果出现”的时间点。如果任务被取消或页面发生变化，停止旧操作并检查当前状态，再发起另一轮已授权的尝试。避免让多个 worker 操作同一个挑战。

在恢复调度前，先证明一次修正后的云端运行是成功的

修正后的部署应该能完成与本地成功时相同的、被允许的应用操作。

回到环境对比，只更改已确认的差异：缺失的依赖、未安装的扩展、丢失的机密，或错误的浏览器绑定。重复一次小任务，并检查最终页面或应用确认。

简要记录修正后的配置与观测结果，把失败和成功的部署版本也一并记录下来，以免后续重建镜像时悄悄把问题带回来。如果问题仍然存在，可以参考更通用的AI 智能体验证码疑难排查指南，那里给出了更广泛的失败路径图。

在需要受支持验证码处理器的场景下使用 CapSolver，然后让应用的最终结果来判断智能体是否完成任务。一旦弄清真实使用的浏览器和执行进程，实际的修复往往只是一个小小的部署改动。

常见问题（FAQ）

问：为什么验证码在我笔记本上能过，在容器里就失败？

容器可能缺少本地的扩展、浏览器安装、可选依赖、凭证或网络访问。先对比两边的有效环境和第一个失败步骤，再考虑修改智能体逻辑。

问：验证码扩展一定要在可见浏览器中才能用吗？

不一定。Playwright 文档指出，有一种 Chromium 配置支持在无头模式下运行扩展。兼容性取决于可执行文件、启动配置和托管服务，因此要检查这些具体条件。

问：安装 Core SDK 后，浏览器检测会自动可用吗？

文档中的“依赖浏览器的方法”需要可选的 Playwright 依赖。仅有 token 模式的安装，并不会提供等价的浏览器环境。

问：solver 返回成功后，云端智能体还会卡住吗？

会。页面可能已经变化，handler 可能附着在另一个标签页，或者应用本身没有接受这个结果。请分别检查当前页面以及预期的最终动作。

问：部署后出现这类问题时，我应该先换模型吗？

先检查部署差异。缺失扩展、不可用工具或错误的浏览器连接，即使更换语言模型也依然会存在。