@zmeel/adapter-openclaw-gateway 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paperclip AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# OpenClaw Gateway Adapter
+
+This document describes how `@zmeel/adapter-openclaw-gateway` invokes OpenClaw over the Gateway protocol.
+
+## Transport
+
+This adapter always uses WebSocket gateway transport.
+
+- URL must be `ws://` or `wss://`
+- Connect flow follows gateway protocol:
+1. receive `connect.challenge`
+2. send `req connect` (protocol/client/auth/device payload)
+3. send `req agent`
+4. wait for completion via `req agent.wait`
+5. stream `event agent` frames into zmeel logs/transcript parsing
+
+## Auth Modes
+
+Gateway credentials can be provided in any of these ways:
+
+- `authToken` / `token` in adapter config
+- `headers.x-openclaw-token`
+- `headers.x-openclaw-auth` (legacy)
+- `password` (shared password mode)
+
+When a token is present and `authorization` header is missing, the adapter derives `Authorization: Bearer <token>`.
+
+## Device Auth
+
+By default the adapter sends a signed `device` payload in `connect` params.
+
+- set `disableDeviceAuth=true` to omit device signing
+- set `devicePrivateKeyPem` to pin a stable signing key
+- without `devicePrivateKeyPem`, the adapter generates an ephemeral Ed25519 keypair per run
+- when `autoPairOnFirstConnect` is enabled (default), the adapter handles one initial `pairing required` by calling `device.pair.list` + `device.pair.approve` over shared auth, then retries once.
+
+## Session Strategy
+
+The adapter supports the same session routing model as HTTP OpenClaw mode:
+
+- `sessionKeyStrategy=issue|fixed|run`
+- `sessionKey` is used when strategy is `fixed`
+
+Resolved session key is sent as `agent.sessionKey`.
+
+## Payload Mapping
+
+The agent request is built as:
+
+- required fields:
+  - `message` (wake text plus optional `payloadTemplate.message`/`payloadTemplate.text` prefix)
+  - `idempotencyKey` (zmeel `runId`)
+  - `sessionKey` (resolved strategy)
+- optional additions:
+  - all `payloadTemplate` fields merged in
+  - `agentId` from config if set and not already in template
+
+## Timeouts
+
+- `timeoutSec` controls adapter-level request budget
+- `waitTimeoutMs` controls `agent.wait.timeoutMs`
+
+If `agent.wait` returns `timeout`, adapter returns `openclaw_gateway_wait_timeout`.
+
+## Log Format
+
+Structured gateway event logs use:
+
+- `[openclaw-gateway] ...` for lifecycle/system logs
+- `[openclaw-gateway:event] run=<id> stream=<stream> data=<json>` for `event agent` frames
+
+UI/CLI parsers consume these lines to render transcript updates.

package/dist/cli/format-event.d.ts

@@ -0,0 +1,2 @@
+export declare function printOpenClawGatewayStreamEvent(raw: string, debug: boolean): void;
+//# sourceMappingURL=format-event.d.ts.map

package/dist/cli/format-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-event.d.ts","sourceRoot":"","sources":["../../src/cli/format-event.ts"],"names":[],"mappings":"AAEA,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAoBjF"}

package/dist/cli/format-event.js

@@ -0,0 +1,20 @@
+import pc from "picocolors";
+export function printOpenClawGatewayStreamEvent(raw, debug) {
+    const line = raw.trim();
+    if (!line)
+        return;
+    if (!debug) {
+        console.log(line);
+        return;
+    }
+    if (line.startsWith("[openclaw-gateway:event]")) {
+        console.log(pc.cyan(line));
+        return;
+    }
+    if (line.startsWith("[openclaw-gateway]")) {
+        console.log(pc.blue(line));
+        return;
+    }
+    console.log(pc.gray(line));
+}
+//# sourceMappingURL=format-event.js.map

package/dist/cli/format-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-event.js","sourceRoot":"","sources":["../../src/cli/format-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,UAAU,+BAA+B,CAAC,GAAW,EAAE,KAAc;IACzE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,CAAC,IAAI;QAAE,OAAO;IAElB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,CAAC,0BAA0B,CAAC,EAAE,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export { printOpenClawGatewayStreamEvent } from "./format-event.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,2 @@
+export { printOpenClawGatewayStreamEvent } from "./format-event.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export declare const type = "openclaw_gateway";
+export declare const label = "OpenClaw Gateway";
+export declare const models: {
+    id: string;
+    label: string;
+}[];
+export declare const agentConfigurationDoc = "# openclaw_gateway agent configuration\n\nAdapter: openclaw_gateway\n\nUse when:\n- You want zmeel to invoke OpenClaw over the Gateway WebSocket protocol.\n- You want native gateway auth/connect semantics instead of HTTP /v1/responses or /hooks/*.\n\nDon't use when:\n- You only expose OpenClaw HTTP endpoints.\n- Your deployment does not permit outbound WebSocket access from the zmeel server.\n\nCore fields:\n- url (string, required): OpenClaw gateway WebSocket URL (ws:// or wss://)\n- headers (object, optional): handshake headers; supports x-openclaw-token / x-openclaw-auth\n- authToken (string, optional): shared gateway token override\n- password (string, optional): gateway shared password, if configured\n\nGateway connect identity fields:\n- clientId (string, optional): gateway client id (default gateway-client)\n- clientMode (string, optional): gateway client mode (default backend)\n- clientVersion (string, optional): client version string\n- role (string, optional): gateway role (default operator)\n- scopes (string[] | comma string, optional): gateway scopes (default [\"operator.admin\"])\n- disableDeviceAuth (boolean, optional): disable signed device payload in connect params (default false)\n\nRequest behavior fields:\n- payloadTemplate (object, optional): additional fields merged into gateway agent params\n- workspaceRuntime (object, optional): reserved workspace runtime metadata; workspace runtime services are manually controlled from the workspace UI and are not auto-started by heartbeats\n- timeoutSec (number, optional): adapter timeout in seconds (default 120)\n- waitTimeoutMs (number, optional): agent.wait timeout override (default timeoutSec * 1000)\n- autoPairOnFirstConnect (boolean, optional): on first \"pairing required\", attempt device.pair.list/device.pair.approve via shared auth, then retry once (default true)\n- zmeelApiUrl (string, optional): absolute zmeel base URL advertised in wake text\n\nSession routing fields:\n- sessionKeyStrategy (string, optional): issue (default), fixed, or run\n- sessionKey (string, optional): fixed session key when strategy=fixed (default zmeel)\n\nStandard outbound payload additions:\n- zmeel (object): standardized zmeel context added to every gateway agent request\n- zmeel.workspace (object, optional): resolved execution workspace for this run\n- zmeel.workspaces (array, optional): additional workspace hints zmeel exposed to the run\n- zmeel.workspaceRuntime (object, optional): reserved workspace runtime metadata when explicitly supplied outside normal heartbeat execution\n\nStandard result metadata supported:\n- meta.runtimeServices (array, optional): normalized adapter-managed runtime service reports\n- meta.previewUrl (string, optional): shorthand single preview URL\n- meta.previewUrls (string[], optional): shorthand multiple preview URLs\n";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI,qBAAqB,CAAC;AACvC,eAAO,MAAM,KAAK,qBAAqB,CAAC;AAExC,eAAO,MAAM,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAO,CAAC;AAE1D,eAAO,MAAM,qBAAqB,myFAgDjC,CAAC"}

package/dist/index.js

@@ -0,0 +1,53 @@
+export const type = "openclaw_gateway";
+export const label = "OpenClaw Gateway";
+export const models = [];
+export const agentConfigurationDoc = `# openclaw_gateway agent configuration
+
+Adapter: openclaw_gateway
+
+Use when:
+- You want zmeel to invoke OpenClaw over the Gateway WebSocket protocol.
+- You want native gateway auth/connect semantics instead of HTTP /v1/responses or /hooks/*.
+
+Don't use when:
+- You only expose OpenClaw HTTP endpoints.
+- Your deployment does not permit outbound WebSocket access from the zmeel server.
+
+Core fields:
+- url (string, required): OpenClaw gateway WebSocket URL (ws:// or wss://)
+- headers (object, optional): handshake headers; supports x-openclaw-token / x-openclaw-auth
+- authToken (string, optional): shared gateway token override
+- password (string, optional): gateway shared password, if configured
+
+Gateway connect identity fields:
+- clientId (string, optional): gateway client id (default gateway-client)
+- clientMode (string, optional): gateway client mode (default backend)
+- clientVersion (string, optional): client version string
+- role (string, optional): gateway role (default operator)
+- scopes (string[] | comma string, optional): gateway scopes (default ["operator.admin"])
+- disableDeviceAuth (boolean, optional): disable signed device payload in connect params (default false)
+
+Request behavior fields:
+- payloadTemplate (object, optional): additional fields merged into gateway agent params
+- workspaceRuntime (object, optional): reserved workspace runtime metadata; workspace runtime services are manually controlled from the workspace UI and are not auto-started by heartbeats
+- timeoutSec (number, optional): adapter timeout in seconds (default 120)
+- waitTimeoutMs (number, optional): agent.wait timeout override (default timeoutSec * 1000)
+- autoPairOnFirstConnect (boolean, optional): on first "pairing required", attempt device.pair.list/device.pair.approve via shared auth, then retry once (default true)
+- zmeelApiUrl (string, optional): absolute zmeel base URL advertised in wake text
+
+Session routing fields:
+- sessionKeyStrategy (string, optional): issue (default), fixed, or run
+- sessionKey (string, optional): fixed session key when strategy=fixed (default zmeel)
+
+Standard outbound payload additions:
+- zmeel (object): standardized zmeel context added to every gateway agent request
+- zmeel.workspace (object, optional): resolved execution workspace for this run
+- zmeel.workspaces (array, optional): additional workspace hints zmeel exposed to the run
+- zmeel.workspaceRuntime (object, optional): reserved workspace runtime metadata when explicitly supplied outside normal heartbeat execution
+
+Standard result metadata supported:
+- meta.runtimeServices (array, optional): normalized adapter-managed runtime service reports
+- meta.previewUrl (string, optional): shorthand single preview URL
+- meta.previewUrls (string[], optional): shorthand multiple preview URLs
+`;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG,kBAAkB,CAAC;AACvC,MAAM,CAAC,MAAM,KAAK,GAAG,kBAAkB,CAAC;AAExC,MAAM,CAAC,MAAM,MAAM,GAAoC,EAAE,CAAC;AAE1D,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDpC,CAAC"}

package/dist/server/execute.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterExecutionContext, AdapterExecutionResult } from "@zmeel/adapter-utils";
+export declare function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/server/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/server/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EAEvB,MAAM,sBAAsB,CAAC;AA+9B9B,wBAAsB,OAAO,CAAC,GAAG,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAsb3F"}