如何使用 Monid 为 AI Agent 添加验证码解决功能

摘要

• Monid 可以通过其代理用于其他 API 工具的同一套 discover、inspect 和 run 流程，暴露一个原生的 CAPTCHA 解决连接器。
• 拟议的首个版本涵盖无代理的 reCAPTCHA v2、reCAPTCHA v3 以及 Cloudflare Turnstile 任务，用于已授权的自动化工作流。
• 该连接器将 CapSolver 的 API 密钥保存在 Monid 的凭据注入层中，而不是放入代理提示词、fixture 或生命周期状态里。
• 提交的连接器可以编译进 Monid 目录，通过 Monid 的测试套件，并包含录制的 reCAPTCHA v2/v3 运行示例以及合成的 Turnstile 覆盖。
• 托管的 Monid 目录尚未包含此连接器。下面的代码和命令描述的是已测试的实现以及在上游审核完成前预期的用户流程。

为什么 Monid 中的 AI 代理需要 CAPTCHA 工具

浏览器代理可以导航页面并调用网络数据工具，但 CAPTCHA 检查点会引入一个独立的技术步骤。代理必须识别挑战类型、提交正确的页面 URL 和公开站点密钥、等待结果并将返回的 token 应用到已授权的浏览器会话。如果没有专用工具，每个代理框架都必须自行实现这一整套生命周期。

拟议的集成将 CapSolver 作为 Monid 的原生提供方。Monid 仍然负责工具发现和执行层，而 CapSolver 通过其文档化的 API 处理受支持的 CAPTCHA 任务。这种方式符合 Monid 现有模型：代理发现工具，检查其模式和定价，并通过一个接口启动结构化运行。Monid 在其官方介绍中记录了这一流程。

Monid 与 CapSolver 集成能实现什么

原生连接器为 AI 代理提供了一种结构化方式来请求 CAPTCHA 解决，而不必在每个工作流中嵌入提供方特定的 HTTP 逻辑。

首个连接器范围包含三个端点：

这一小范围的初始覆盖让连接器更易于审查。企业任务类型、基于代理的任务以及浏览器侧 token 应用，可以在核心 API 生命周期稳定后单独添加。

该集成旨在用于 QA、RPA、浏览器自动化以及被允许的公共网络数据工作流。技术能力本身并不授予访问私有、受限或敏感数据的权限。自动化之前，请审阅目标站点的条款并获得授权。

原生连接器的工作原理

原生连接器将 CapSolver 的异步任务 API 封装进 Monid 标准的提供方生命周期。

1. 代理发现或选择一个 CapSolver 端点。
2. Monid 校验 websiteURL、websiteKey 以及任何任务特定输入。
3. Monid 将受保护的 clientKey 注入 JSON 请求体。
4. 连接器调用 /createTask，并仅存储返回的任务 ID。
5. 当任务状态为 idle 或 processing 时，Monid 轮询 /getTaskResult。
6. 当任务变为 ready 时，连接器返回提供方的结构化解决方案。

这在设计上是一个原生 REST 连接器，而不是 MCP 到 MCP 的桥接。Monid 已经向 AI 客户端暴露了自己的MCP 接口；其下层提供方直接调用 CapSolver 的 API。

AI agent
  → Monid discover / inspect / run
  → CapSolver connector
  → createTask
  → getTaskResult polling
  → structured solution
  → authorized browser workflow continues

兑换你的 CapSolver 奖励码

立即提升你的自动化预算！
在为 CapSolver 账户充值时使用奖励码 CAP26，每次充值都可额外获得 5% 奖励 —— 无次数限制。
现在就去 CapSolver 控制台 兑换吧

将 CapSolver 配置为 Monid 提供方

CapSolver 的认证方式不同于使用 HTTP authorization 头的提供方。该 API 期望在 JSON body 中接收 clientKey，因此连接器会在 Monid 的凭据注入层中添加它。

提交的提供方定义使用了这种认证与超时模式；异步生命周期在同一提供方中单独实现：

export default defineProvider({
  name: "capsolver",
  auth: {
    inject: ({ data, utils }) => ({
      ...data.request,
      body: utils.json.merge(data.request.body ?? {}, {
        clientKey: data.params.apiKey,
      }),
    }),
  },
  request: {
    baseUrl: "https://api.capsolver.com",
  },
  timeouts: { requestMs: 30_000, runMs: 300_000, pollMs: 3_000 },
});

密钥不会出现在端点定义、重放 fixture、日志或生命周期状态中。只有传输层在发送提供方请求时才会接收到凭据。

你可以在官方的 createTask 和 getTaskResult 文档中查看当前 CapSolver 任务生命周期。

定义 reCAPTCHA v2 端点

每个 Monid 端点都将经验证的输入模式映射到一个 CapSolver 任务类型。reCAPTCHA v2 端点接受一个页面 URL、公开站点密钥，以及从小组件观察到的可选字段，包括隐形模式、页面 action、标准的 s 值、会话模式以及 API 域名。

const zBody = z.object({
  websiteURL: z.url(),
  websiteKey: z.string().min(1),
  isInvisible: z.boolean().optional(),
  pageAction: z.string().min(1).optional(),
  recaptchaDataSValue: z.string().optional(),
  isSession: z.boolean().optional(),
  apiDomain: z.string().optional(),
}).strict();

export default defineEndpoint({
  endpoint: "/solve/recaptcha-v2",
  request: { method: "POST", path: "/createTask" },
  input: {
    schema: { body: zBody },
    toRequest: ({ data, utils }) => ({
      ...data.input,
      body: {
        task: utils.json.merge(data.input.body ?? {}, {
          type: "ReCaptchaV2TaskProxyLess",
        }),
      },
    }),
  },
});

对于 reCAPTCHA v3 和 Turnstile，结构相同，只是使用任务特定的模式和任务类型。Monid 的连接器编写指南要求在提供方加入托管目录之前，必须包含重放 fixture、类型检查以及一个拉取请求。

处理异步结果

连接器必须把 CapSolver 视为异步提供方。成功的 /createTask 响应通常提供任务 ID，而 /getTaskResult 会返回 idle、processing 或 ready。

已测试的生命周期遵循以下规则：

• idle 或 processing：保持 Monid 运行处于活动状态并再次轮询。
• ready：返回结构化解决方案并完成运行。
• 非零的 errorId：返回提供方错误，而不是成功结果。
• 非 2xx HTTP 响应：保留提供方响应并记录零完成用量。
• 缺失任务 ID 或未知状态：以清晰的连接器错误停止。

这种区分很重要，因为 Monid 将自身的运行状态与上游提供方的 HTTP 状态区分开来。其CLI 运行文档解释了异步工具如何启动运行并暴露最终的提供方响应。

本地检查并在发布后运行连接器

在托管发布之前，已验证的本地命令为：

deno task catalog endpoints --provider capsolver
deno task catalog inspect 'capsolver#solve/recaptcha-v2'

发布之后，MCP 客户端应先调用 Monid 的 monid_inspect 工具：

{ "provider": "capsolver", "endpoint": "/solve/recaptcha-v2" }

然后用经验证的输入调用 monid_run：

{
  "provider": "capsolver",
  "endpoint": "/solve/recaptcha-v2",
  "input": {
    "body": {
      "websiteURL": "https://authorized.example/test",
      "websiteKey": "PUBLIC_SITE_KEY"
    }
  }
}

请使用已授权的测试页面，并将 PUBLIC_SITE_KEY 替换为小组件的公开站点密钥。将 API 凭据保存在 Monid 的凭据配置中，而不要放在命令、提示词或源文件中。

在撰写本文时，托管端点仍不可用。提交的连接器通过了编译和 Monid 测试套件，在 PR 验证运行中共有 1,376 个测试通过。reCAPTCHA v2 和 v3 的 fixture 是从公共演示页面录制的，而 Turnstile 成功和失败覆盖则是显式的合成数据。在实现普遍可用之前，还需要完成 Monid 上游审核、托管部署以及非虚拟的 Turnstile 实机检查。

对于当前可用的直接代理集成，CapSolver MCP Server 向兼容客户端暴露 CAPTCHA 工具。更广泛的智能代理浏览器集成指南解释了 CAPTCHA 处理在浏览器代理工作流中的位置。

实现限制与后续步骤

首个连接器应保持小而精，直到基本生命周期在真实工作负载中被接受并观察到为止。

• 它不会自动从浏览器 DOM 内容检测 CAPTCHA。
• 它不会将返回的 token 应用于活动的 Playwright 或 Puppeteer 页面。
• 它不包含企业版或基于代理的 CapSolver 任务类型。
• 它要求调用工作流提供正确的 URL、公开站点密钥以及任务特定字段。
• 不应将其用于未经授权的访问、账号滥用或收集私有或敏感信息。

在上游审核之后，下一个有用的补充是一个非虚拟的 Turnstile 实机录制，以及一个经过验证的浏览器示例，展示代理如何检测受支持的小组件、调用 Monid 端点并将结果应用到同一授权会话。这两者都应使用明确的演示环境，而不是第三方生产站点。

结论

原生 Monid 连接器是在不向每个代理框架添加提供方特定代码的前提下，让 AI 代理能够发现 CAPTCHA 解决能力的最干净方式。提交的连接器证明 Monid 可以验证任务输入、保护 API 密钥、管理异步轮询，并通过其正常工具生命周期返回结构化结果。

剩余工作是流程和验证层面：解决两条次要的自动化评审意见，完成非虚拟的 Turnstile 实机检查，获得 Monid 批准，并在部署后验证托管 MCP 流程。在此之前需要直接访问的团队，可以通过官方的 CapSolver API 或 MCP Server 集成。

使用 CapSolver 构建可靠的自动化工作流

从 CapSolver 控制台 创建账户，查看受支持的集成文档，并仅在你被允许自动化的页面上进行测试。关于产品和账户问题，请参考 CapSolver FAQ。

常见问题

问：CapSolver 连接器已经在 Monid 中可用了吗？

没有。这个原生连接器已作为一个拉取请求提交，正在等待 Monid 的上游审核、托管部署以及目录发布。

问：Monid 会直接调用 CapSolver MCP Server 吗？

不会。Monid 应通过原生提供方连接器调用 CapSolver 的 REST API，而 Monid 自己的 MCP 服务器则将最终的工具暴露给兼容的 AI 客户端。

问：拟议首个版本包含哪些 CAPTCHA 类型？

首个版本涵盖无代理的 reCAPTCHA v2、reCAPTCHA v3 以及 Cloudflare Turnstile token 任务。

问：CapSolver API 密钥存储在哪里？

连接器通过 Monid 的凭据注入层传递 API 密钥，只在发送请求时才将其添加到提供方请求体中。

问：连接器能自动控制浏览器页面吗？

不能。初始连接器只返回结构化解决方案；已授权的浏览器工作流仍需负责将结果应用到其活动页面或会话。

问：这个集成可以用于任何网站吗？

不可以。仅在你被授权自动化的网站和工作流上使用该集成，并遵守适用的站点条款、隐私要求和法律。