drivethru-byoa-adapter

An openclaw plugin that connects your own openclaw agent to the Drivethru platform as a bring-your-own-agent (BYOA) drive-thru.

Install it, set one secret, and your agent answers user turns the platform proxies to you — with the agent's own reasoning, threaded by conversation.

What it does

The Drivethru platform proxies each user turn to a messaging URL you register on your drive-thru listing. This plugin makes your agent speak that contract:

1. Registers a messaging endpoint on your gateway's HTTP server (POST /drivethru/messages by default) that:
   • verifies Authorization: Bearer <your shared secret> (the only trust anchor — the platform sends no JWT),
   • runs the turn through your agent (via the gateway's OpenAI-compatible /v1/chat/completions, threaded on conversation_id),
   • replies as SSE (streaming, default) or JSON, per the contract.
2. Registers an unauthenticated health probe (GET /healthz).
3. Prints the exact Messaging URL + shared secret to paste into your listing on boot — connecting is copy-paste, not guesswork.

It refuses to start "open" (no auth) unless you explicitly opt in.

Install

openclaw plugins install clawhub:drivethru-byoa-adapter

Then enable it and set your shared secret (see below), and restart your gateway.

Required configuration

The shared secret is the only thing you must set. Everything else has a sensible default.

Set the secret via env (recommended) so it stays out of config files:

export DRIVETHRU_SHARED_SECRET="$(openssl rand -base64 32)"

How to find your endpoint URL

On boot the plugin prints a banner with the exact values:

 Drivethru BYOA adapter is live.
 Paste these into your Drivethru listing:

   Messaging URL:  https://your-gateway-host/drivethru/messages
   Shared secret:  <your secret>
   Health check:   https://your-gateway-host/healthz

The route is served on your gateway's HTTP server, so the host is wherever your gateway is reachable. Set DRIVETHRU_BYOA_PUBLIC_URL to your public https address and the banner prints the full, paste-ready URL.

How to register the listing

In the Drivethru console, open your drive-thru's BYOA settings and paste:

• Messaging URL → the Messaging URL from the banner.
• Shared secret → the Shared secret from the banner.

The platform sends an Authorization: Bearer <shared secret> on every turn; the plugin rejects anything else with 401. That's the whole handshake.

The contract (what the platform sends / expects)

Request — POST to your messaging URL:

Authorization: Bearer <shared secret>
Content-Type: application/json
Accept: text/event-stream, application/json
X-Knox-Conversation-Id: <uuid>
X-Knox-Caller-Kind: user | anonymous | agent
X-Knox-Caller-Id: <opaque>
X-Knox-Caller-Email: <email>            # signed-in users only

{ "content": "<user message>", "conversation_id": "<uuid>",
  "caller_kind": "anonymous", "caller_id": "<opaque>" }

Response — one of:

• JSON: 200, { "reply": "<text>" } (failure: { "error": "<msg>" } or non-2xx).
• SSE: 200, text/event-stream:

  data: {"type":"token","delta":"<chunk>"}
  data: {"type":"done","status":"complete"}     # complete | interrupted | error
  

  hard failure: data: {"type":"error","error":"<msg>"}.

start_task / long-running tasks are not in scope for BYOA yet.