openclaw-brokerkit

OpenClaw BrokerKit

openclaw-brokerkit is an OpenClaw plugin that adds a provider-neutral Approvals tab and /brokerkit commands to OpenClaw. It connects to one or more BrokerKit Operator V1 sources; the brokers remain authoritative and retain all provider credentials and executable plans.

The minimum supported host is openclaw@2026.7.1, the first stable SDK used by this package that includes public tab descriptors.

Install

Install an exact release from npm through OpenClaw:

openclaw plugins install npm:openclaw-brokerkit@<version>

For a local monorepo checkout, build and link the package explicitly:

pnpm --filter openclaw-brokerkit build
openclaw plugins install --link ./plugins/openclaw

The enabled plugin automatically provides gh-broker, hf-broker, and sudo-broker skills. An installation without plugin configuration defaults to skills-only mode, which registers no approval UI, routes, commands, or background service. Configure direct or delegated-web mode when OpenClaw should also expose approval surfaces.

The skills teach agents to use the installed broker clients instead of looking for upstream provider credentials or unrestricted privilege escalation. OpenClaw loads them from the plugin package; it does not copy them into the agent workspace. A skill becomes eligible only when its matching broker executable is available, and the skill itself grants no access.

Operator V1 consumers

Trusted hosts can consume the same generated Operator V1 types and runtime validators as the plugin without installing OpenClaw:

import {
  parseRequestPage,
  type RequestPage,
} from "openclaw-brokerkit/operator-v1";

const page: RequestPage = parseRequestPage(await response.json());

The subpath is generated from BrokerKit's canonical OpenAPI document. Its standalone validators use no runtime code generation and reject unknown fields, invalid bounds, unsafe integers, and protocol drift.

Choose a trust mode

• skills-only is the default when configuration is absent. It loads the packaged client skills without registering approval surfaces.
• direct trusts the OpenClaw process with operator SecretRefs and enables the tab, background reconciliation, /brokerkit commands, and channel delivery.
• delegated-web packages only the tab UI and delegates authenticated browser requests to a same-origin trusted backend. It gives OpenClaw no broker credential and registers no command or background source service.

Direct mode configuration

{
  plugins: {
    entries: {
      brokerkit: {
        enabled: true,
        config: {
          mode: "direct",
          brokers: [
            {
              id: "hf-primary",
              label: "Hugging Face",
              endpoint: "https://hf-broker.example.com",
              operatorCredential: {
                source: "env",
                provider: "default",
                id: "HF_BROKER_OPERATOR_SECRET",
              },
            },
          ],
        },
      },
    },
  },
}

Literal operator credentials are rejected; operatorCredential.source is env, file, or exec. Non-loopback endpoints require HTTPS. Each endpoint is the broker's Operator V1 listener, not its agent listener. The plugin stores only cursors, opaque handles, generic channel destinations, and delivery bookkeeping under the OpenClaw service state directory.

Commands

/brokerkit subscribe
/brokerkit unsubscribe
/brokerkit pending
/brokerkit show <handle>
/brokerkit approve <handle>
/brokerkit deny <handle>
/brokerkit revoke <handle>

Commands are registered only in direct mode. They require an authorized sender and the operator.approvals scope. Requesters cancel their own pending requests through the authenticated broker client API, not through this operator surface. Subscriptions use OpenClaw's generic outbound adapter, so this package contains no Telegram, Discord, Slack, or other channel-specific implementation.

Delegated web mode

For a deployment that treats OpenClaw as untrusted:

{
  plugins: {
    entries: {
      brokerkit: {
        enabled: true,
        config: {
          mode: "delegated-web",
          delegatedWeb: {
            basePath: "/trusted-host/api/brokerkit",
          },
        },
      },
    },
  },
}

The trusted backend implements brokerkit.io/delegated-web/v1, authenticates the human operator, and issues an in-memory decision token lasting no more than five minutes. The base path must be a normalized same-origin absolute path. The OpenClaw gateway must set gateway.controlUi.embedSandbox to scripts so the approval tab can run while retaining its opaque sandbox origin; do not use trusted.

When OpenClaw is outside the credential trust boundary, the trusted backend must serve the packaged dist/ui files at the registered UI path itself. A framed popover may receive a server-enforced read or decide session: a read session shows requests without action controls, and a decide session lets the operator act directly in the frame. The OpenClaw Gateway approvals popover is an actionable surface and must receive decide; the trusted host must retain decision authority and validate that access on every request.

Session injection

The host injects the short-lived delegated session into the sandboxed response:

<meta name="brokerkit-delegated-session" content="BASE64URL_SESSION_JSON" />

Token-bearing HTML responses must enforce sandbox allow-scripts in their CSP, and immutable UI assets must be loadable by the opaque document (serve them without a same-origin CORP restriction or set Cross-Origin-Resource-Policy: cross-origin).

The content is a base64url-encoded brokerkit.io/delegated-web/v1 session object; the UI removes the element as soon as it reads it. Version 1 uses this closed payload:

{
  "api_version": "brokerkit.io/delegated-web/v1",
  "token": "opaque-short-lived-browser-session",
  "expires_at": "<no more than five minutes from issue time, RFC3339>",
  "access": "decide",
  "renewal_transport": "direct"
}

access is read or decide; the host enforces it on every endpoint. renewal_transport is direct (the UI posts the current session to <basePath>/session) or parent (the nonce-bound bridge below returns the replacement session in memory). The host preserves the token's access when it returns a replacement session.

Browser session transport

Every direct and delegated-web browser API call carries its raw session in one fixed HTTP field:

GET /trusted-host/api/brokerkit/snapshot HTTP/1.1
Origin: null
BrokerKit-Session: eyJ2ZXJzaW9uIjoxLCJhdWRpZW5jZSI6Ii4uLiJ9.signature
Accept: application/json

BrokerKit-Session has no authentication-scheme prefix. A host must reject empty, repeated, combined, malformed, or oversized values; tokens are 32 to 4096 bytes of visible ASCII excluding comma and whitespace. The same field protects POST /session, GET /snapshot, GET /events, request detail, approval, denial, and revocation; direct-mode capabilities use it on /plugins/brokerkit/api/v1 as well.

Standard Authorization is reserved for the hosting edge and for server-to-server Operator V1 clients. Browser clients never use it, and never put a delegated session in cookies, query parameters, local storage, or session storage. Tokens must not be logged, traced, reflected in errors, copied into an Operator V1 request, or persisted by the host or UI.

Because the packaged UI has an opaque origin under the required scripts-only sandbox, a delegated host must accept only the expected Origin: null, return Access-Control-Allow-Origin: null, allow BrokerKit-Session and Content-Type in preflight responses, allow only its fixed route methods, and set Vary: Origin plus Cache-Control: no-store. Delegated and direct API requests use credentials: "omit"; a delegated host must be reachable without ambient browser credentials. Every delegated route requires and validates the short-lived BrokerKit-Session.

Parent session bridge

When the parent application is trusted, a sandboxed tab that cannot call the delegated session endpoint directly may instead use this host-neutral bridge:

request:  { type: "brokerkit.delegated-web.session.request", version: 1, nonce }
response: { type: "brokerkit.delegated-web.session.response", nonce, session }

The trusted parent must answer only requests from the embedded BrokerKit frame and must bind each response to the supplied 128-bit nonce. session is the same brokerkit.io/delegated-web/v1 object returned by POST <basePath>/session. The bridge is a BrokerKit interface; it contains no host-product namespace or host-specific payload.

Session rebootstrap

A direct-renewal token can expire while a browser tab is suspended. If the host rejects renewal with not_authorized, a framed UI sends this credential-free message once:

{ type: "brokerkit.delegated-web.rebootstrap", version: 1 }

The host must accept it only from the embedded BrokerKit frame and reload only that protected frame so its HTML response can inject a fresh session. Hosts must rate-limit reloads and must not return a token through this message. This keeps rebootstrap host-neutral while leaving session issuance at the trusted HTTP boundary.