playclaw-custom

Connect any HTTP/REST agent to PlayClaw — the professional AI agent testing playground.

Works with any agent that has an HTTP endpoint: your own backend, an n8n workflow, a LangChain server, a Flowise chatflow, a Botpress bot, a local LLM with an API, or anything else.

Quick start

npx playclaw-custom PC-XXXX-XXXX-XXXX --endpoint https://my-agent.com/api/chat

Requirements

• A PlayClaw account and connection token (PC-XXXX-XXXX-XXXX) from playclaw.info
• Your agent must be reachable via HTTP/HTTPS POST (or GET/PUT)
• Node.js 18+

Usage

npx playclaw-custom <PC-TOKEN> --endpoint <URL> [options]

Options:
  -e, --endpoint <URL>           Your agent's HTTP endpoint URL (required)
      --auth <value>             Authorization header (e.g. "Bearer sk-..." or "ApiKey abc")
      --method <method>          HTTP method: GET, POST, PUT (default: POST)
      --request-field <name>     JSON field for the user message (default: "message")
      --response-field <path>    Dot-notation path for the reply (default: "response")
      --headers <json>           Extra headers as JSON string
      --timeout <ms>             Request timeout in ms (default: 30000)
  -v, --version                  Show version
  -h, --help                     Show help

Environment variables

| Variable | Description | |---|---| | PLAYCLAW_CUSTOM_ENDPOINT | Agent endpoint URL | | PLAYCLAW_CUSTOM_AUTH | Authorization header value | | PLAYCLAW_CUSTOM_METHOD | HTTP method | | PLAYCLAW_CUSTOM_REQUEST_FIELD | Request body field name | | PLAYCLAW_CUSTOM_RESPONSE_FIELD | Response field dot-path | | PLAYCLAW_CUSTOM_HEADERS | Extra headers as JSON string | | PLAYCLAW_CUSTOM_TIMEOUT | Timeout in ms |

Examples

Basic agent (any framework)

Your agent receives { "message": "..." } and returns { "response": "..." }:

npx playclaw-custom PC-XXXX --endpoint https://my-agent.com/chat

Custom field names

Your agent uses different field names:

npx playclaw-custom PC-XXXX --endpoint https://api.mybot.io/reply \
  --request-field "query" --response-field "answer"

With authentication

npx playclaw-custom PC-XXXX --endpoint https://api.mybot.io/chat \
  --auth "Bearer my-secret-token"

OpenAI-compatible endpoint (e.g. local LLM, LiteLLM proxy)

npx playclaw-custom PC-XXXX --endpoint http://localhost:11434/v1/chat/completions \
  --response-field "choices.0.message.content"

n8n webhook

npx playclaw-custom PC-XXXX \
  --endpoint https://my-n8n.com/webhook/agent-chat \
  --request-field "chatInput" \
  --response-field "output"

Extra headers (tenant, API version, etc.)

npx playclaw-custom PC-XXXX --endpoint https://api.myplatform.com/agent \
  --headers '{"X-Tenant-ID":"acme","X-API-Version":"2"}' \
  --auth "ApiKey abc123"

Response field auto-detection

If your --response-field path doesn't match, the bridge automatically tries common field names before giving up: response, reply, message, content, text, output, answer, choices.0.message.content, completion, result

How it works

PlayClaw Playground → Supabase Realtime → playclaw-custom CLI → Your HTTP endpoint → response back

The bridge sends a POST request with your message to your endpoint on every turn, and forwards whatever your agent replies back to the PlayClaw playground.

Part of the PlayClaw bridge family:

• playclaw — OpenClaw agents
• playclaw-claude — Claude / Anthropic API agents
• playclaw-openai — OpenAI / GPT agents
• playclaw-custom — Any HTTP/REST agent ← you are here