What environment variables and headers are required?

You must set CAPTCHAS_ENDPOINT and CAPTCHAS_API_KEY; pass the API key in the x-api-key header; x-domain is optional; site_key is optional and may be resolved from the API key or account default.

Which API calls are considered canonical for CAPTCHAS with OpenClaw?

The canonical calls are /v1/agent/verify, /v1/agent/challenge/:id/complete, and /v1/agent/token-verify as noted in the references.

What should I avoid sending in signals?

Avoid sending PII in signals to protect user privacy and comply with data handling practices.

CAPTCHAS OpenClaw

Scanned

@CAPTCHASCO

npx machina-cli add skill @CAPTCHASCO/captchas-openclaw --openclaw

Files (1)

SKILL.md

3.9 KB

CAPTCHAS + OpenClaw

Use this skill when integrating CAPTCHAS with OpenClaw via OpenResponses tools or OpenClaw plugin tools.

Configuration

Set environment variables:

CAPTCHAS_ENDPOINT = https://agent.captchas.co
CAPTCHAS_API_KEY = <your-api-key>

Headers:

x-api-key: required (use CAPTCHAS_API_KEY).
x-domain: optional; validated if provided.

Notes:

site_key is optional; if omitted, it resolves from the API key or account default.
Avoid sending PII in signals.

OpenResponses Tool Schemas (OpenClaw Gateway)

Use the OpenClaw tools array shape when calling the Gateway /v1/responses endpoint.

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "captchas_agent_verify",
        "description": "Run CAPTCHAS Agent Verify and return a decision (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": "Complete a challenge and mint a verification token when passed.",
        "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": "Verify an opaque CAPTCHAS token before completing a sensitive action.",
        "parameters": {
          "type": "object",
          "properties": {
            "token": {"type": "string"},
            "site_key": {"type": "string"},
            "domain": {"type": "string"}
          },
          "required": ["token"],
          "additionalProperties": false
        }
      }
    }
  ]
}

OpenClaw Plugin Tool Registration

Example:

api.registerTool({
  name: "captchas_agent_verify",
  description: "Run CAPTCHAS Agent Verify and return a decision (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) }] };
  }
});

References

Use /v1/agent/verify, /v1/agent/challenge/:id/complete, and /v1/agent/token-verify as the canonical API calls.
See captchas-human-verification/SKILL.md for workflow guidance.

Source

git clone https://clawhub.ai/CAPTCHASCO/captchas-openclawView on GitHub

Overview

This skill explains how to connect CAPTCHAS with OpenClaw using OpenResponses tools and plugin tools. It covers required environment variables, headers, and the OpenClaw gateway schemas for verification, challenge completion, and token verification.

How This Skill Works

Configure CAPTCHAS_ENDPOINT and CAPTCHAS_API_KEY, then send requests through the OpenClaw gateway to /v1/responses using a tools array of CAPTCHAS agent functions. Each function maps to verify, complete, or token verification and defines parameters like site_key, action, signals, and verification_mode.

When to Use It

When integrating CAPTCHAS into an OpenClaw workflow to obtain a decision (allow|deny|challenge) via captchas_agent_verify.
When you need to complete a challenge with a challenge_id and answer to mint a verification token via captchas_agent_challenge_complete.
When validating a CAPTCHAS token before performing sensitive actions with captchas_agent_token_verify.
When supplying signals, capabilities, and domain context to improve risk scoring in OpenClaw.
When registering CAPTCHAS tools in your OpenClaw plugin with api.registerTool using the documented schemas.

Quick Start

Step 1: Set environment variables CAPTCHAS_ENDPOINT to https://agent.captchas.co and CAPTCHAS_API_KEY to your key; ensure the x-api-key header uses CAPTCHAS_API_KEY and x-domain is optional.
Step 2: Call the OpenClaw gateway /v1/responses with a tools array that includes captchas_agent_verify and its parameters such as site_key, action, signals, capabilities, and verification_mode.
Step 3: Register the tool in your OpenClaw plugin with api.registerTool using the same JSON schema as shown in the example.

Best Practices

Set CAPTCHAS_ENDPOINT and CAPTCHAS_API_KEY as env vars and pass x-api-key in headers (x-domain is optional).
Rely on site_key from API key or account default if not provided.
Avoid sending PII in signals to protect user privacy.
Provide structured signals and capabilities to improve decision quality (object or array).
Mirror the exact function schemas for captchas_agent_verify, captchas_agent_challenge_complete, and captchas_agent_token_verify in both gateway calls and plugin registration.

Example Use Cases

Login flow: use captchas_agent_verify to decide allow, deny, or challenge for a login attempt.
Post-login risk check: verify the response token with captchas_agent_token_verify before granting access.
Challenge flow: complete a challenge via captchas_agent_challenge_complete after user solves it.
Signals enrichment: send device, user agent, and domain signals to improve risk scoring.
Tool registration: register captchas_agent_verify with api.registerTool using the provided schema.

Frequently Asked Questions

Add this skill to your agents