如何在Kimi Code CLI网页工作流程中处理验证码

TL;DR

• Kimi Code CLI 的 FetchURL 可以获取网页内容，但工作流仍需在调用步骤成功前拒绝 403 错误、空输出、挑战页面或缺乏预期证据的内容。
• 将挑战恢复过程置于模型的自由推理之外：首先授权目标，分类获取结果，允许最多一次恢复尝试，重新获取并验证预期内容。
• Kimi Code 可以从通用的 MCP 服务器发现工具。CapSolver 不需要声称拥有原生的 Kimi 集成；其文档中的 MCP 服务器可以通过标准工具边界提供受控的 CAPTCHA 能力。
• 限制 Agent 路径为当前文档记录的 reCAPTCHA v2、reCAPTCHA v3（包括企业版）和 Cloudflare Turnstile 能力，并在开始工作前在运行时确认支持。
• 在缺少授权、不支持的挑战、终端工具错误、尝试预算耗尽或恢复后验证失败时停止。这些情况应转交人工处理，而不是循环。
• 本指南中的配置和状态机固定装置已在本地测试。没有解决真实的 CAPTCHA，因为真实的 CapSolver 凭据和授权的挑战固定装置是部署前提。

引言：将网页检索视为证据生成步骤

Kimi Code CLI 可以读取文件、运行 shell 命令、获取网页内容，并使用 MCP 工具。这使其适用于依赖公共或用户授权网页内容的编码任务。困难的情况不总是硬性网络故障。请求可能会返回包含 403 错误、几乎为空的正文或看起来像内容的挑战页面。

可靠的流程应在结果进入代理的上下文之前对其进行分类。当失败是授权环境中的支持 CAPTCHA 时，CapSolver 可以在 MCP 边界后作为受控恢复能力。它不应成为无限重试机制或权限的替代品。

Kimi Code CLI 中的 CAPTCHA 处理意味着什么？

Kimi Code CLI 中的 CAPTCHA 处理意味着检测网页检索未产生预期证据，将授权且支持的挑战路由到受控工具，然后再次验证页面。它不意味着将每次获取失败都视为 CAPTCHA 或让模型重复工具调用直到有所改变。

官方 Kimi Code 仓库 列出了网页获取、MCP、技能和插件作为 CLI 的功能。其 内置工具参考 定义了 FetchURL，其输入为 url，输出为页面内容。HTML 被转换为正文文本，而纯文本和 Markdown 被直接传递。

该合同是故意简化的。它不承诺返回的文本是预期的文档，也不定义结构化的 { status, text } 响应。如果主机包装器暴露了 HTTP 状态或传输错误，请在适配器中规范化它们。然后在代理使用结果之前验证传输证据和内容语义。

这种分离为模型提供了狭窄的决策空间。它可能仅在验证器生成可恢复状态后请求恢复；控制器而非模型强制执行预算。

先决条件和信任边界

仅在您拥有或被授权自动化的页面和测试环境中使用此模式。技术访问不授予读取私有、受限、敏感或未经授权数据的权限。在启用任何恢复路径之前，请审查目标的条款、适用政策、数据处理规则和速率限制。

您需要：

• 具有可信项目的 Kimi Code CLI 并有权加载预期的 MCP 服务器。
• Python 3.10 或更高版本用于当前的 capsolver-core 包。
• 从 CapSolver MCP 服务指南 获取的官方 capsolver-core 和 capsolver-mcp 包。
• 存储在进程环境或秘密管理器中的 CapSolver API 密钥，永远不要提交到 .kimi-code/mcp.json。
• 受控页面固定装置或明确授权的工作流用于最终集成测试。
• 预期内容规则，例如页面标题、稳定标题或必需的 JSON 字段，以区分预期结果与挑战或外壳页面。

Kimi 的 官方 MCP 配置指南 支持用户级和项目级的 mcp.json 文件。项目配置需要信任，而单个 MCP 工具调用可能需要批准。保持该批准边界：避免广泛的通配符规则，审查服务器命令，并仅允许工作流需要的工具。

验证环境中的依赖兼容性说明

本文的隔离验证使用 Kimi Code CLI 0.38.0、capsolver-core 0.1.0 和 capsolver-mcp 0.1.0 在 Python 3.12 上。2026 年 8 月 26 日，无约束安装选择了 MCP 2.1.1，而当前的 CapSolver MCP 包导入了 MCP 1.x 的 FastMCP 模块。固定 mcp<2 产生了 MCP 1.29.1 并恢复了此隔离固定装置中的文档命令。

将此固定视为过时的兼容性解决方案，而不是永久要求。检查当前官方包并在依赖项支持 MCP 2.x 时删除它。

为 Kimi Code CLI 配置 CapSolver MCP

CapSolver 可以通过 Kimi Code 的标准 MCP 配置连接；这是一个通用的 MCP 连接，而不是对原生 Kimi 集成的声称。创建一个隔离环境并安装文档包：

python3.12 -m venv .venv-capsolver-mcp
.venv-capsolver-mcp/bin/python -m pip install \
  "mcp<2" \
  "capsolver-core @ git+https://github.com/capsolver/capsolver-core-python.git" \
  "capsolver-mcp @ git+https://github.com/capsolver/capsolver-mcp.git"
.venv-capsolver-mcp/bin/capsolver-mcp --help

通过您的 CI 秘密存储或本地进程环境设置 CAPSOLVER_API_KEY。然后使用项目 .kimi-code/mcp.json，例如：

{
  "mcpServers": {
    "capsolver": {
      "command": "/absolute/path/to/.venv-capsolver-mcp/bin/python",
      "args": ["-m", "capsolver_mcp"],
      "startupTimeoutMs": 10000,
      "toolTimeoutMs": 30000,
      "enabledTools": [
        "detect_captchas",
        "solve_captcha",
        "solve_on_page",
        "get_balance",
        "get_supported_captchas"
      ]
    }
  }
}

在已提供 CAPSOLVER_API_KEY 的进程中启动 Kimi；MCP 子进程将继承该环境。Kimi 还支持 MCP 服务器的 env 对象，但将真实密钥写入项目文件会带来源代码暴露的风险。如果您的部署无法继承进程秘密，请使用受保护的运行时配置。

Kimi 会用服务器名称前缀发现的工具，因此模型会看到如 mcp__capsolver__detect_captchas 的名称。此指南的本地握手确认发现了所有五个文档工具。它有意在未提供真实凭证或授权挑战固定装置的情况下停止调用。

在工作流开始前，调用 get_supported_captchas 或在控制器中强制执行版本化允许列表。对于此 Agent 工作流，将允许列表限制为 reCAPTCHA v2、reCAPTCHA v3 及其企业变体和 Cloudflare Turnstile。如果检测产生其他内容，请停止以供人工审查。

领取您的 CapSolver 奖励代码

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

检测 403、空内容和挑战页面的假成功

在获取结果到达检索内存、摘要器或编码决策之前进行验证。可靠的分类器检查几个独立信号：

1. 传输失败：主机适配器报告 403 或其他非成功状态。
2. 内容过少：返回的文本为空或太短，无法包含预期文档。
3. 挑战语义：正文包含稳定的挑战标记，而不是请求的内容。
4. 缺少证据：响应看起来合理，但缺少所需的标题、字段或标识符。

以下经过测试的 JavaScript 是适配器级别的示例。其 { status, text } 对象是规范化的应用合同，而不是原始的 FetchURL 模式：

const CHALLENGE_MARKERS = [
  /verify you are human/i,
  /captcha/i,
  /cf-chl-/i,
  /g-recaptcha/i,
  /cf-turnstile/i,
];

export function classifyFetchResult(result, expectedTerms = []) {
  const status = Number(result?.status ?? 0);
  const text = String(result?.text ?? "").trim();

  if (status === 403) {
    return { kind: "recoverable", reason: "http_403", status };
  }
  if (status < 200 || status >= 400) {
    return { kind: "terminal", reason: "unexpected_http_status", status };
  }
  if (text.length < 80) {
    return { kind: "recoverable", reason: "empty_or_thin_content", status };
  }
  if (CHALLENGE_MARKERS.some((marker) => marker.test(text))) {
    return { kind: "recoverable", reason: "challenge_page", status };
  }

  const missingTerms = expectedTerms.filter(
    (term) => !text.toLowerCase().includes(term.toLowerCase()),
  );
  if (missingTerms.length > 0) {
    return { kind: "recoverable", reason: "expected_content_missing", status, missingTerms };
  }

  return { kind: "accepted", reason: "expected_content_present", status };
}

根据您拥有的固定装置调整阈值和标记，而不是任意第三方页面。标记匹配是需要检查的证据，而不是继续的权限。记录 URL 原始、状态类、内容哈希、匹配规则和跟踪 ID，但从日志中删除页面数据和凭证。

为了更广泛的诊断，MCP CAPTCHA 错误指南 解释了如何区分传输、检测、解决和注入失败。Kimi 的 MCP 边界应接收该结构化分类，而不是无限制的自然语言指令，如“继续尝试”。

运行一次受控恢复并验证结果

有界控制器应只有四个终端结果：接受、恢复并验证、停止或需要人工。它永远不应仅因 MCP 调用返回而没有抛出就推断成功。

export async function runBoundedRecovery({
  fetchPage,
  recoverThroughMcp,
  url,
  expectedTerms,
  authorized,
  maxRecoveryAttempts = 1,
}) {
  const evidence = [];
  let recoveryAttempts = 0;

  const first = await fetchPage(url);
  const firstCheck = classifyFetchResult(first, expectedTerms);
  evidence.push({ stage: "initial_fetch", check: firstCheck });

  if (firstCheck.kind === "accepted") {
    return { state: "accepted", recoveryAttempts, evidence };
  }
  if (firstCheck.kind === "terminal") {
    return { state: "stopped", stopReason: firstCheck.reason, recoveryAttempts, evidence };
  }
  if (!authorized) {
    return { state: "human_required", stopReason: "authorization_required", recoveryAttempts, evidence };
  }
  if (maxRecoveryAttempts < 1) {
    return { state: "stopped", stopReason: "recovery_budget_exhausted", recoveryAttempts, evidence };
  }

  recoveryAttempts += 1;
  const recovery = await recoverThroughMcp({
    url,
    reason: firstCheck.reason,
    attempt: recoveryAttempts,
  });
  evidence.push({ stage: "mcp_recovery", result: recovery });

  if (recovery?.status !== "recovered") {
    return {
      state: recovery?.retryable ? "human_required" : "stopped",
      stopReason: recovery?.errorCode ?? "recovery_failed",
      recoveryAttempts,
      evidence,
    };
  }

  const second = await fetchPage(url);
  const secondCheck = classifyFetchResult(second, expectedTerms);
  evidence.push({ stage: "verification_fetch", check: secondCheck });

  if (secondCheck.kind === "accepted") {
    return { state: "recovered_and_verified", recoveryAttempts, evidence };
  }

  return {
    state: "human_required",
    stopReason: "verification_failed_after_recovery",
    recoveryAttempts,
    evidence,
  };
}

recoverThroughMcp 适配器是批准的编排层调用文档 CapSolver 工具的地方。其输入应包括授权的 URL、检测到的挑战证据和尝试次数。其输出应规范化成功、脱敏错误代码和可重试性。将服务特定的任务输入保留在该适配器内，并根据当前官方文档验证它们，而不是要求模型发明字段。

控制器的第二次获取是强制性的。使用与第一次请求相同的预期术语和内容规则进行验证。令牌或工具响应是中间结果；页面内容是接受证据。

实用停止规则

在缺少授权、URL 离开批准的原始集或验证器返回终端传输错误时，无需工具调用即可停止。在工具调用后，如果挑战不支持、服务报告非可重试错误、时间预算到期或余额检查失败，则停止。在单次恢复尝试后，如果验证获取仍为空、被挑战或缺少预期内容，则需要人工。

这些规则还可防止上下文污染。只有接受的页面内容应进入 Kimi 任务历史或下游检索存储。将失败的正文保留在隔离的证据记录中，保留时间短且脱敏。

Kimi Code 网络工作流的可观测性

可观测性应解释步骤状态变化的原因，而不暴露秘密或完整页面正文。为每个转换发出一个结构化事件：

{
"traceId": "retrieval-7f2c",
  "stage": "verification_fetch",
  "origin": "authorized.example",
  "classification": "expected_content_missing",
  "recoveryAttempts": 1,
  "finalState": "human_required"
}

有用的字段包括标准化的状态类别、验证器规则、内容长度、脱敏内容哈希、MCP工具名称、经过时间、尝试次数和最终状态。切勿记录API密钥、完整的挑战令牌、敏感页面数据或包含秘密的MCP配置。

设置人工需求率、验证失败率和工具超时的警报。403错误率上升可能表明访问策略已更改、获取适配器损坏或存在挑战；仅凭此证据不足以确定原因。有关一般协议上下文，请参阅什么是AI系统中的MCP模型上下文协议。

负责任的使用和操作护栏

此设计适用于公共、自有或明确授权的自动化。遵守适用的条款、访问控制、机器人指令、速率限制、数据最小化和保留要求。不要使用CAPTCHA工具访问私人或受限内容，或在网站已明确撤回权限后继续操作。

保持目标允许列表、每个授权记录的所有者、过期日期和关闭开关。在允许的情况下应用低请求速率并缓存已接受的公共内容。当工作流更改来源、目的、数据类别或执行频率时，需要新的批准。

MCP层应使用最小的工具集和最小权限的批准。CapSolver的AI代理指南描述了支持的代理工作流；您的控制器仍需负责权限、尝试限制、输出验证和停止。

结论：使恢复可衡量且有限

可靠的Kimi Code CLI CAPTCHA处理始于拒绝虚假成功。标准化FetchURL证据，测试预期内容，授权目标，允许一次支持的恢复，然后再次获取和验证。任何模糊或仍受挑战的内容应停止以进行人工审核。

通用的MCP边界将Kimi的网络工作流与服务细节分离，同时状态机控制重试并记录证据。如果您的授权代理工作流需要记录的CAPTCHA恢复层，请在生产环境中启用之前使用自有设备评估CapSolver。

FAQ

问：Kimi Code CLI 是否具有原生的 CapSolver 集成？

答：不。本指南使用 Kimi Code 的文档化通用 MCP 配置来连接 CapSolver MCP 服务器；它不声称具有原生集成或官方合作伙伴关系。

问：FetchURL 是否返回 HTTP 状态和正文对象？

答：根据文档化的内置工具合同，不返回。FetchURL 接收 URL 并返回页面内容；主机适配器必须在应用示例分类器之前标准化可用的传输错误或状态信息。

问：每个 Kimi Code FetchURL 403 是否应触发 CAPTCHA 恢复？

答：不。403 可能有多种原因，包括策略或授权失败。对响应进行分类，确认权限，检测支持的挑战，并在原因不明确时停止。

问：哪些挑战类型应包含在此代理工作流中？

答：将允许列表保持为当前记录的 reCAPTCHA v2、reCAPTCHA v3（包括企业版）和 Cloudflare Turnstile 功能。确认运行时支持并在遇到任何未识别类型时停止。

问：代理应进行多少次 CAPTCHA 恢复尝试？

答：此模式允许一次恢复尝试后进行一次验证获取。如果验证失败，工作流将停止并请求人工审核，而不是重复工具调用。

问：模型能否仅根据 MCP 响应判断恢复成功？

答：不能。将 MCP 响应视为中间结果；在接受内容之前，重复授权获取并验证预期的页面证据。