PinchTab + CapSolver：验证码处理 for 浏览器代理

简要说明

• PinchTab 0.15.2 包含一个 AutoSolver 注册表，当配置了 autoSolver.external.capsolverKey 时，可以加载 CapSolver。
• 将 PinchTab 绑定到本地回环地址，要求其服务器令牌，并限制浏览器导航仅限于您自动化任务批准的域名。
• 使用 GET /solvers 确认提供者注册，然后再调用 POST /solve/capsolver 或 tab 作用域的解决路由。
• 将 solved: true 视为挑战步骤的结果，而不是原始表单、测试或数据任务成功的证明。
• 当挑战类型、会话或授权边界不明确时，集成应在有限尝试后停止，并将控制权交给人工处理。

PinchTab 为 AI 代理提供了紧凑的 HTTP、CLI 和 MCP 控制平面，用于 Chrome 浏览器。其当前的 AutoSolver 层还可以注册外部提供者，包括 CapSolver，因此经过授权的浏览器工作流可以处理支持的 CAPTCHA，而无需向模型教授原始 API 负载。

本指南展示了如何在 PinchTab 中配置 CapSolver，验证本地服务，调用命名求解器，并将最终工作流检查保留在求解器之外。示例使用 PinchTab 0.15.2 和占位符凭证。它们旨在用于 QA、RPA 和您被允许自动化的公共数据工作流。

PinchTab 和 CapSolver 集成的功能

PinchTab 和 CapSolver 的集成为 PinchTab 已控制的浏览器会话添加了一个命名的 CAPTCHA 处理步骤。

PinchTab 的 AutoSolver 文档 描述了一个内部和外部求解器的注册表。capsolver 提供者通过 autoSolver.external.capsolverKey 配置字段启用。PinchTab 保持活动标签页和浏览器状态，而外部提供者处理支持的挑战任务。

这种分离对浏览器代理至关重要。代理不应发明任务类型，不应将凭证复制到提示中，也不应假设返回的解决方案完成了业务操作。PinchTab 拥有页面会话。CapSolver 返回记录的挑战结果。您的应用程序仍需决定是否继续、重试、停止或请求人工审核。

先决条件

在配置集成之前，您需要以下内容：

• PinchTab 0.15.2 或后续版本，其发布说明和求解器参考仍记录相同的字段。
• Chrome 或其他 PinchTab 支持的 Chromium 运行时。
• 存储在源代码控制之外的 CapSolver 账户和 API 密钥。
• 用于工作流的专用、低权限浏览器配置文件。
• 您拥有或明确授权的测试页面，可以显示支持的挑战。

PinchTab 的 安全指南 建议使用服务器令牌、绑定到本地回环地址和域名控制。这些保护措施即使在本地机器上也很重要，因为任何可以访问控制平面的本地进程都可能驱动浏览器。

本文的验证运行使用了官方的 PinchTab 0.15.2 macOS ARM64 二进制文件。该二进制文件返回 pinchtab 0.15.2，其经过认证的 /health 路由返回 HTTP 200 和 authRequired: true。由于此环境没有经过批准的 CapSolver 密钥或授权的 CAPTCHA 测试目标，因此未提交完整的付费挑战。

安装 PinchTab 并确认版本

从官方发布或项目文档中记录的安装方法安装 PinchTab，然后确认您正在运行的二进制文件。

pinchtab version

本指南验证的版本预期输出：

pinchtab 0.15.2

初始化专用配置文件，而不是修改用于非相关工作的个人浏览器设置。

export PINCHTAB_CONFIG="$PWD/pinchtab-config.json"
pinchtab config init

config init 会创建一个服务器令牌。不要在 CI 日志中打印该令牌，也不要提交生成的文件。

在 PinchTab AutoSolver 中配置 CapSolver

在 autoSolver.external 下配置 CapSolver，并将浏览器控制服务器保留在 127.0.0.1，除非您有经过审查的远程访问设计。

{
  "server": {
    "bind": "127.0.0.1",
    "port": "9867",
    "token": "PINCHTAB_SERVER_TOKEN"
  },
  "security": {
    "allowedDomains": ["qa.example.com"],
    "idpi": {
      "enabled": true,
      "strictMode": true,
      "scanContent": true,
      "wrapContent": true
    }
  },
  "autoSolver": {
    "enabled": true,
    "autoTrigger": false,
    "triggerOnNavigate": false,
    "triggerOnAction": false,
    "maxAttempts": 3,
    "solverTimeoutSec": 30,
    "retryBaseDelayMs": 500,
    "retryMaxDelayMs": 5000,
    "solvers": ["capsolver", "cloudflare", "semantic"],
    "llmFallback": false,
    "external": {
      "capsolverKey": "CAPSOLVER_API_KEY"
    }
  }
}

使用您的密钥管理器将实际值注入运行时配置。上述占位符不是可用的凭证。

从禁用自动触发器开始，使第一次测试更容易审计。只有当您的应用程序将页面分类为批准的验证检查点时，才能调用命名求解器。工作流稳定后，单独评估自动触发器，并保持相同的尝试和超时限制。

领取您的 CapSolver 奖励代码

立即提升您的自动化预算！
在充值 CapSolver 账户时使用奖励代码 CAP26，每次充值可获得额外 5% 奖励——无限制。
立即在您的 CapSolver 仪表板 中领取

启动服务器并验证提供者注册

在打开目标工作流之前，验证控制平面和求解器注册。

使用专用配置启动 PinchTab：

PINCHTAB_CONFIG="$PWD/pinchtab-config.json" pinchtab server

在第二个终端中，从您的密钥存储中读取服务器令牌并调用本地健康路由：

curl -sS \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  http://127.0.0.1:9867/health

健康的响应报告 status: "ok"。在检查求解器列表之前，等待默认浏览器实例就绪。

curl -sS \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  http://127.0.0.1:9867/solvers

PinchTab 的 求解路由参考 指出，当配置了其 API 密钥时，capsolver 会被包含。如果缺失，请检查活动配置路径，重启服务，并确认密钥已注入启动 PinchTab 的进程。

为当前标签页调用 CapSolver

当当前标签页到达授权的挑战页面时，调用命名的 capsolver 路由。

curl -sS -X POST \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:9867/solve/capsolver \
  -d '{"maxAttempts": 3, "timeout": 30000}'

对于特定标签页，使用标签页作用域的路由，以防止并发代理在任意活动标签页上操作：

curl -sS -X POST \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  "http://127.0.0.1:9867/tabs/TAB_ID/solve/capsolver" \
  -d '{"maxAttempts": 3, "timeout": 30000}'

记录的响应包括标签页 ID、求解器名称、已解决标志、挑战类型、尝试次数和最终页面标题。将这些字段与浏览器任务的关联 ID 一起存储。不要将 API 密钥或返回的挑战工件存储在普通应用程序日志中。

验证原始浏览器任务

挑战步骤返回后，原始浏览器任务需要自己的接受检查。

对于 QA 工作流，验证同一标签页中的预期 URL、页面标题、认证状态或表单结果。对于数据工作流，验证预期的记录模式是否存在，并且响应不是另一个挑战或错误页面。仅靠浏览器标题是不够的。

使用小型状态机，而不是将每个非错误响应视为成功：

CapSolver 的 任务结果文档 区分了处理任务和就绪结果。PinchTab 抽象了该提供者交互，但您的应用程序仍必须强制执行整体工作流截止日期和最终接受规则。

常见问题

capsolver 不出现在 /solvers 中

当前的 PinchTab 进程可能使用了不同的配置文件，未重启，或未接收到外部 API 密钥。确认 PINCHTAB_CONFIG，重启服务器，并在不打印密钥的情况下重新查询注册表。

/solvers 返回 503

PinchTab 浏览器实例可能仍在启动或重启中。检查 /health，检查实例状态，并确认配置的 Chromium 二进制文件可以使用选定的配置文件启动。

求解器报告成功但表单仍失败

页面可能已导航，令牌可能属于不同的浏览器上下文，或应用程序可能拒绝了原始操作。保持标签页所有权稳定，并在处理挑战后验证业务结果。

代理在同一个挑战上循环

重复求解不应无限制。保持 maxAttempts 小，保留第一次失败证据，并在相同检查点返回时将工作流转移到 needs_review。

工作流到达登录、2FA 或账户验证

CAPTCHA 处理不授权凭证输入、账户创建、电话验证或对受限数据的访问。在应用程序的正常访问策略下停止并请求人工操作。

结论

PinchTab 已经暴露了使用 CapSolver 作为命名外部求解器所需的集成点。生产设置应将服务器保留在本地或强认证，限制目标域名，将每个求解绑定到特定标签页，限制尝试次数，并验证原始页面结果。

仅在您被允许自动化的流程中使用 CapSolver。提供者结果是浏览器状态机中的一个受控步骤，而不是继续的通用信号。

将受控 CAPTCHA 处理添加到您的浏览器代理工作流

创建一个 CapSolver 账户，在您拥有的 QA 页面上测试 PinchTab 集成，并将 API 密钥保留在运行时密钥存储中。从手动求解器调用和严格的尝试预算开始，再启用任何自动触发器。

常见问题

Q: PinchTab 是否直接支持 CapSolver？

是的。PinchTab 的 AutoSolver 文档和 solve 参考将 capsolver 列为通过 autoSolver.external.capsolverKey 启用的外部提供者。

Q: 我可以通过 PinchTab 的 MCP 使用 CapSolver 吗？

PinchTab 通过 MCP 暴露浏览器控制，而其 HTTP AutoSolver 路由处理命名求解器。在安装的 PinchTab 版本中确认确切的工具表面，并将求解器调用保留在有限的应用程序工作流中。

Q: 我应该立即启用自动求解吗？

不。从批准的测试页面上显式调用开始，验证标签页作用域的响应，并在拥有清晰的检测、停止和审计规则后，再添加自动触发器。

Q: solved: true 证明了什么？

solved: true 报告了挑战步骤的结果。您的应用程序仍需验证原始导航、表单提交、测试断言或数据请求是否成功。

Q: 当挑战类型不受支持时，代理应如何处理？

代理应在配置的尝试预算后停止并请求人工审核。它不应随意更改提供者字段，切换到未经批准的目标，或继续进入登录、2FA 或身份验证。