名称： captchas-openclaw
描述： CAPTCHAS Agent API 与 OpenClaw 的集成指南，包含 OpenResponses 工具模式及插件工具注册。
主页： https://captchas.co
元数据： {"openclaw":{"emoji":"🧩","requires":{"env":["CAPTCHAS_API_KEY","CAPTCHAS_ENDPOINT"]},"primaryEnv":"CAPTCHAS_API_KEY"}}

CAPTCHAS + OpenClaw

本指南用于通过 OpenResponses 工具或 OpenClaw 插件工具将 CAPTCHAS 集成至 OpenClaw。

配置

设置环境变量：

• CAPTCHAS_ENDPOINT = https://agent.captchas.co
• CAPTCHAS_API_KEY = <你的 API 密钥>

请求头：

• x-api-key：必需（使用 CAPTCHAS_API_KEY）。
• x-domain：可选；若提供则会进行验证。

注意事项：

• site_key 为可选参数；若未提供，将从 API 密钥或账户默认值中解析。
• 请勿在 signals 中发送个人身份信息（PII）。

OpenResponses 工具模式（OpenClaw 网关）

调用网关 /v1/responses 端点时，请使用 OpenClaw 的 tools 数组结构。

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "captchas_agent_verify",
        "description": "运行 CAPTCHAS Agent Verify 并返回决策（allow|deny|challenge）。",
        "parameters": {
          "type": "object",
          "properties": {
            "site_key": {"type": "string"},
            "action": {"type": "string"},
            "signals": {"type": "object", "additionalProperties": true},
            "capabilities": {
              "oneOf": [
                {"type": "object", "additionalProperties": true},
                {"type": "array", "items": {"type": "string"}}
              ]
            },
            "verification_mode": {"type": "string", "enum": ["backend_linked", "agent_only"]},
            "challenge_source": {"type": "string", "enum": ["bank", "ai_generated"]},
            "input_type": {"type": "string", "enum": ["choice", "image", "behavioral"]},
            "media_url": {"type": "string"},
            "media_type": {"type": "string"}
          },
          "required": [],
          "additionalProperties": false
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "captchas_agent_challenge_complete",
        "description": "完成挑战并在通过后生成验证令牌。",
        "parameters": {
          "type": "object",
          "properties": {
            "challenge_id": {"type": "string"},
            "site_key": {"type": "string"},
            "answer": {"type": "string"}
          },
          "required": ["challenge_id", "answer"],
          "additionalProperties": false
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "captchas_agent_token_verify",
        "description": "在执行敏感操作前验证一个不透明的 CAPTCHAS 令牌。",
        "parameters": {
          "type": "object",
          "properties": {
            "token": {"type": "string"},
            "site_key": {"type": "string"},
            "domain": {"type": "string"}
          },
          "required": ["token"],
          "additionalProperties": false
        }
      }
    }
  ]
}

OpenClaw 插件工具注册

使用 api.registerTool(...) 及与上述相同的 JSON 模式参数来注册工具。

示例：

api.registerTool({
  name: "captchas_agent_verify",
  description: "运行 CAPTCHAS Agent Verify 并返回决策（allow|deny|challenge）。",
  parameters: {
    type: "object",
    properties: {
      site_key: { type: "string" },
      action: { type: "string" },
      signals: { type: "object", additionalProperties: true }
    },
    required: [],
    additionalProperties: false
  },
  async execute(_id, params) {
    return { content: [{ type: "text", text: JSON.stringify(params) }] };
  }
});

参考

• 核心 API 调用为 /v1/agent/verify、/v1/agent/challenge/:id/complete 和 /v1/agent/token-verify。
• 工作流指引请参阅 captchas-human-verification/SKILL.md。