The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(openclaw): support /hooks/agent endpoint and multi-endpoint detection
Dotta514dc43923cb
diff --git a/packages/adapters/openclaw/README.md b/packages/adapters/openclaw/README.mdnew file mode 100644index 0000000000..10b7d4c173--- /dev/null+++ b/packages/adapters/openclaw/README.md@@ -0,0 +1,139 @@+# OpenClaw Adapter Modes++This document describes how `@paperclipai/adapter-openclaw` selects request shape and endpoint behavior.++## Transport Modes++The adapter has two transport modes:++- `sse` (default)+- `webhook`++Configured via `adapterConfig.streamTransport` (or legacy `adapterConfig.transport`).++## Mode Matrix++| streamTransport | configured URL path | behavior |+| --- | --- | --- |+| `sse` | `/v1/responses` | Sends OpenResponses request with `stream: true`, expects `text/event-stream` response until terminal event. |+| `sse` | `/hooks/*` | Rejected (`openclaw_sse_incompatible_endpoint`). Hooks are not stream-capable. |+| `sse` | other endpoint | Sends generic streaming payload (`stream: true`, `text`, `paperclip`) and expects SSE response. |+| `webhook` | `/hooks/wake` | Sends wake payload `{ text, mode }`. |+| `webhook` | `/hooks/agent` | Sends agent payload `{ message, ...hook fields }`. |+| `webhook` | `/v1/responses` | Compatibility flow: tries `/hooks/agent` first, then falls back to original `/v1/responses` if hook endpoint returns `404`. |+| `webhook` | other endpoint | Sends legacy generic webhook payload (`stream: false`, `text`, `paperclip`). |++## Webhook Payload Shapes++### 1) Hook Wake (`/hooks/wake`)++Payload:++```json+{+ "text": "Paperclip wake event ...",+ "mode": "now"+}+```++### 2) Hook Agent (`/hooks/agent`)++Payload:++```json+{+ "message": "Paperclip wake event ...",+ "name": "Optional hook name",+ "agentId": "Optional OpenClaw agent id",+ "wakeMode": "now",+ "deliver": true,+ "channel": "last",+ "to": "Optional channel recipient",+ "model": "Optional model override",+ "thinking": "Optional thinking override",+ "timeoutSeconds": 120+}+```++Notes:++- `message` is always used (not `text`) for `/hooks/agent`.+- `sessionKey` is **not** sent by default for `/hooks/agent`.+- To include derived session keys in `/hooks/agent`, set:+ - `hookIncludeSessionKey: true`++### 3) OpenResponses (`/v1/responses`)++When used directly (SSE mode or webhook fallback), payload uses OpenResponses shape:++```json+{+ "stream": false,+ "model": "openclaw",+ "input": "...",+ "metadata": {+ "paperclip_session_key": "paperclip"+ }+}+```++## Auth Header Behavior++You can provide auth either explicitly or via token headers:++- Explicit auth header:+ - `webhookAuthHeader: "Bearer ..."`+- Token headers (adapter derives `Authorization` automatically when missing):+ - `headers["x-openclaw-token"]` (preferred)+ - `headers["x-openclaw-auth"]` (legacy compatibility)++## Session Key Behavior++Session keys are resolved from:++- `sessionKeyStrategy`: `fixed` (default), `issue`, `run`+- `sessionKey`: used when strategy is `fixed` (default value `paperclip`)++Where session keys are applied:++- `/v1/responses`: sent via `x-openclaw-session-key` header + metadata.+- `/hooks/wake`: not sent as a dedicated field.+- `/hooks/agent`: only sent if `hookIncludeSessionKey=true`.+- Generic webhook fallback: sent as `sessionKey` field.++## Recommended Config Examples++### SSE (streaming endpoint)++```json+{+ "url": "http://127.0.0.1:18789/v1/responses",+ "streamTransport": "sse",+ "method": "POST",+ "headers": {+ "x-openclaw-token": "replace-me"+ }+}+```++### Webhook (hooks endpoint)++```json+{+ "url": "http://127.0.0.1:18789/hooks/agent",+ "streamTransport": "webhook",+ "method": "POST",+ "headers": {+ "x-openclaw-token": "replace-me"+ }+}+```++### Webhook with legacy URL retained++If URL is still `/v1/responses` and `streamTransport=webhook`, the adapter will:++1. try `.../hooks/agent`+2. fallback to original `.../v1/responses` when hook endpoint returns `404`++This lets older OpenClaw setups continue working while migrating to hooks.diff --git a/packages/adapters/openclaw/src/index.ts b/packages/adapters/openclaw/src/index.tsindex 4ae9cdba9c..2d939d9290 100644--- a/packages/adapters/openclaw/src/index.ts+++ b/packages/adapters/openclaw/src/index.ts@@ -11,7 +11,7 @@ Use when:- You run an OpenClaw agent remotely and wake it over HTTP.- You want selectable transport:- \`sse\` for streaming execution in one Paperclip run.- - \`webhook\` for wake-style callbacks (including /hooks/wake compatibility).+ - \`webhook\` for wake-style callbacks (\`/hooks/wake\`, \`/hooks/agent\`, or compatibility webhooks).Don't use when:- You need local CLI execution inside Paperclip (use claude_local/codex_local/opencode_local/process).@@ -25,6 +25,7 @@ Core fields:- webhookAuthHeader (string, optional): Authorization header value if your endpoint requires auth- payloadTemplate (object, optional): additional JSON payload fields merged into each wake payload- paperclipApiUrl (string, optional): absolute http(s) Paperclip base URL to advertise to OpenClaw as \`PAPERCLIP_API_URL\`+- hookIncludeSessionKey (boolean, optional): when true, include derived \`sessionKey\` in \`/hooks/agent\` webhook payloads (default false)Session routing fields:- sessionKeyStrategy (string, optional): \`fixed\` (default), \`issue\`, or \`run\`diff --git a/packages/adapters/openclaw/src/server/execute-common.ts b/packages/adapters/openclaw/src/server/execute-common.tsindex fd0d648490..d2c7158308 100644--- a/packages/adapters/openclaw/src/server/execute-common.ts+++ b/packages/adapters/openclaw/src/server/execute-common.ts@@ -5,6 +5,7 @@ import { parseOpenClawResponse } from "./parse.js";export type OpenClawTransport = "sse" | "webhook";export type SessionKeyStrategy = "fixed" | "issue" | "run";+export type OpenClawEndpointKind = "open_responses" | "hook_wake" | "hook_agent" | "generic";export type WakePayload = {runId: string;@@ -31,7 +32,7 @@ export type OpenClawExecutionState = {};const SENSITIVE_LOG_KEY_PATTERN =- /(^|[_-])(auth|authorization|token|secret|password|api[_-]?key|private[_-]?key)([_-]|$)|^x-openclaw-auth$/i;+ /(^|[_-])(auth|authorization|token|secret|password|api[_-]?key|private[_-]?key)([_-]|$)|^x-openclaw-(auth|token)$/i;export function nonEmpty(value: unknown): string | null {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;@@ -73,11 +74,54 @@ export function resolveSessionKey(input: {return fallback;}+function normalizeUrlPath(pathname: string): string {+ const trimmed = pathname.trim().toLowerCase();+ if (!trimmed) return "/";+ return trimmed.endsWith("/") && trimmed !== "/" ? trimmed.slice(0, -1) : trimmed;+}++function isWakePath(pathname: string): boolean {+ const normalized = normalizeUrlPath(pathname);+ return normalized === "/hooks/wake" || normalized.endsWith("/hooks/wake");+}++function isHookAgentPath(pathname: string): boolean {+ const normalized = normalizeUrlPath(pathname);+ return normalized === "/hooks/agent" || normalized.endsWith("/hooks/agent");+}++function isHookPath(pathname: string): boolean {+ const normalized = normalizeUrlPath(pathname);+ return (+ normalized === "/hooks" ||+ normalized.startsWith("/hooks/") ||+ normalized.endsWith("/hooks") ||+ normalized.includes("/hooks/")+ );+}++export function isHookEndpoint(url: string): boolean {+ try {+ const parsed = new URL(url);+ return isHookPath(parsed.pathname);+ } catch {+ return false;+ }+}+export function isWakeCompatibilityEndpoint(url: string): boolean {try {const parsed = new URL(url);- const path = parsed.pathname.toLowerCase();- return path === "/hooks/wake" || path.endsWith("/hooks/wake");+ return isWakePath(parsed.pathname);+ } catch {+ return false;+ }+}++export function isHookAgentEndpoint(url: string): boolean {+ try {+ const parsed = new URL(url);+ return isHookAgentPath(parsed.pathname);} catch {return false;}@@ -86,13 +130,38 @@ export function isWakeCompatibilityEndpoint(url: string): boolean {export function isOpenResponsesEndpoint(url: string): boolean {try {const parsed = new URL(url);- const path = parsed.pathname.toLowerCase();+ const path = normalizeUrlPath(parsed.pathname);return path === "/v1/responses" || path.endsWith("/v1/responses");} catch {return false;}}+export function resolveEndpointKind(url: string): OpenClawEndpointKind {+ if (isOpenResponsesEndpoint(url)) return "open_responses";+ if (isWakeCompatibilityEndpoint(url)) return "hook_wake";+ if (isHookAgentEndpoint(url)) return "hook_agent";+ return "generic";+}++export function deriveHookAgentUrlFromResponses(url: string): string | null {+ try {+ const parsed = new URL(url);+ const path = normalizeUrlPath(parsed.pathname);+ if (path === "/v1/responses") {+ parsed.pathname = "/hooks/agent";+ return parsed.toString();+ }+ if (path.endsWith("/v1/responses")) {+ parsed.pathname = `${path.slice(0, -"/v1/responses".length)}/hooks/agent`;+ return parsed.toString();+ }+ return null;+ } catch {+ return null;+ }+}+export function toStringRecord(value: unknown): Record<string, string> {const parsed = parseObject(value);const out: Record<string, string> = {};@@ -390,7 +459,12 @@ export function buildExecutionState(ctx: AdapterExecutionContext): OpenClawExecu}}- const openClawAuthHeader = nonEmpty(headers["x-openclaw-auth"] ?? headers["X-OpenClaw-Auth"]);+ const openClawAuthHeader = nonEmpty(+ headers["x-openclaw-token"] ??+ headers["X-OpenClaw-Token"] ??+ headers["x-openclaw-auth"] ??+ headers["X-OpenClaw-Auth"],+ );if (openClawAuthHeader && !headers.authorization && !headers.Authorization) {headers.authorization = toAuthorizationHeaderValue(openClawAuthHeader);}diff --git a/packages/adapters/openclaw/src/server/execute-webhook.ts b/packages/adapters/openclaw/src/server/execute-webhook.tsindex f76d6729e2..a4f559897f 100644--- a/packages/adapters/openclaw/src/server/execute-webhook.ts+++ b/packages/adapters/openclaw/src/server/execute-webhook.ts@@ -4,15 +4,16 @@ import {appendWakeTextToOpenResponsesInput,buildExecutionState,buildWakeCompatibilityPayload,- isOpenResponsesEndpoint,+ deriveHookAgentUrlFromResponses,isTextRequiredResponse,isWakeCompatibilityRetryableResponse,- isWakeCompatibilityEndpoint,readAndLogResponseText,redactForLog,+ resolveEndpointKind,sendJsonRequest,stringifyForLog,toStringRecord,+ type OpenClawEndpointKind,type OpenClawExecutionState,} from "./execute-common.js";import { parseOpenClawResponse } from "./parse.js";@@ -21,39 +22,132 @@ function nonEmpty(value: unknown): string | null {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;}-function buildWebhookBody(input: {- url: string;+function asBooleanFlag(value: unknown, fallback = false): boolean {+ if (typeof value === "boolean") return value;+ if (typeof value === "string") {+ const normalized = value.trim().toLowerCase();+ if (normalized === "true" || normalized === "1") return true;+ if (normalized === "false" || normalized === "0") return false;+ }+ return fallback;+}++function normalizeWakeMode(value: unknown): "now" | "next-heartbeat" | null {+ if (typeof value !== "string") return null;+ const normalized = value.trim().toLowerCase();+ if (normalized === "now" || normalized === "next-heartbeat") return normalized;+ return null;+}++function parseOptionalPositiveInteger(value: unknown): number | null {+ if (typeof value === "number" && Number.isFinite(value)) {+ const normalized = Math.max(1, Math.floor(value));+ return Number.isFinite(normalized) ? normalized : null;+ }+ if (typeof value === "string" && value.trim().length > 0) {+ const parsed = Number.parseInt(value.trim(), 10);+ if (Number.isFinite(parsed)) {+ const normalized = Math.max(1, Math.floor(parsed));+ return Number.isFinite(normalized) ? normalized : null;+ }+ }+ return null;+}++function buildOpenResponsesWebhookBody(input: {state: OpenClawExecutionState;- context: AdapterExecutionContext["context"];configModel: unknown;}): Record<string, unknown> {- const { url, state, context, configModel } = input;+ const { state, configModel } = input;const templateText = nonEmpty(state.payloadTemplate.text);const payloadText = templateText ? appendWakeText(templateText, state.wakeText) : state.wakeText;- const isOpenResponses = isOpenResponsesEndpoint(url);+ const openResponsesInput = Object.prototype.hasOwnProperty.call(state.payloadTemplate, "input")+ ? appendWakeTextToOpenResponsesInput(state.payloadTemplate.input, state.wakeText)+ : payloadText;- if (isOpenResponses) {- const openResponsesInput = Object.prototype.hasOwnProperty.call(state.payloadTemplate, "input")- ? appendWakeTextToOpenResponsesInput(state.payloadTemplate.input, state.wakeText)- : payloadText;+ return {+ ...state.payloadTemplate,+ stream: false,+ model:+ nonEmpty(state.payloadTemplate.model) ??+ nonEmpty(configModel) ??+ "openclaw",+ input: openResponsesInput,+ metadata: {+ ...toStringRecord(state.payloadTemplate.metadata),+ ...state.paperclipEnv,+ paperclip_session_key: state.sessionKey,+ paperclip_stream_transport: "webhook",+ },+ };+}- return {- ...state.payloadTemplate,- stream: false,- model:- nonEmpty(state.payloadTemplate.model) ??- nonEmpty(configModel) ??- "openclaw",- input: openResponsesInput,- metadata: {- ...toStringRecord(state.payloadTemplate.metadata),- ...state.paperclipEnv,- paperclip_session_key: state.sessionKey,- paperclip_stream_transport: "webhook",- },- };+function buildHookWakeBody(state: OpenClawExecutionState): Record<string, unknown> {+ const templateText = nonEmpty(state.payloadTemplate.text) ?? nonEmpty(state.payloadTemplate.message);+ const payloadText = templateText ? appendWakeText(templateText, state.wakeText) : state.wakeText;+ const wakeMode = normalizeWakeMode(state.payloadTemplate.mode ?? state.payloadTemplate.wakeMode) ?? "now";++ return {+ text: payloadText,+ mode: wakeMode,+ };+}++function buildHookAgentBody(input: {+ state: OpenClawExecutionState;+ includeSessionKey: boolean;+}): Record<string, unknown> {+ const { state, includeSessionKey } = input;+ const templateMessage = nonEmpty(state.payloadTemplate.message) ?? nonEmpty(state.payloadTemplate.text);+ const message = templateMessage ? appendWakeText(templateMessage, state.wakeText) : state.wakeText;+ const payload: Record<string, unknown> = {+ message,+ };++ const name = nonEmpty(state.payloadTemplate.name);+ if (name) payload.name = name;++ const agentId = nonEmpty(state.payloadTemplate.agentId);+ if (agentId) payload.agentId = agentId;++ const wakeMode = normalizeWakeMode(state.payloadTemplate.wakeMode ?? state.payloadTemplate.mode);+ if (wakeMode) payload.wakeMode = wakeMode;++ const deliver = state.payloadTemplate.deliver;+ if (typeof deliver === "boolean") payload.deliver = deliver;++ const channel = nonEmpty(state.payloadTemplate.channel);+ if (channel) payload.channel = channel;++ const to = nonEmpty(state.payloadTemplate.to);+ if (to) payload.to = to;++ const model = nonEmpty(state.payloadTemplate.model);+ if (model) payload.model = model;++ const thinking = nonEmpty(state.payloadTemplate.thinking);+ if (thinking) payload.thinking = thinking;++ const timeoutSeconds = parseOptionalPositiveInteger(state.payloadTemplate.timeoutSeconds);+ if (timeoutSeconds != null) payload.timeoutSeconds = timeoutSeconds;++ const explicitSessionKey = nonEmpty(state.payloadTemplate.sessionKey);+ if (explicitSessionKey) {+ payload.sessionKey = explicitSessionKey;+ } else if (includeSessionKey) {+ payload.sessionKey = state.sessionKey;}+ return payload;+}++function buildLegacyWebhookBody(input: {+ state: OpenClawExecutionState;+ context: AdapterExecutionContext["context"];+}): Record<string, unknown> {+ const { state, context } = input;+ const templateText = nonEmpty(state.payloadTemplate.text);+ const payloadText = templateText ? appendWakeText(templateText, state.wakeText) : state.wakeText;return {...state.payloadTemplate,stream: false,@@ -69,6 +163,27 @@ function buildWebhookBody(input: {};}+function buildWebhookBody(input: {+ endpointKind: OpenClawEndpointKind;+ state: OpenClawExecutionState;+ context: AdapterExecutionContext["context"];+ configModel: unknown;+ includeHookSessionKey: boolean;+}): Record<string, unknown> {+ const { endpointKind, state, context, configModel, includeHookSessionKey } = input;+ if (endpointKind === "open_responses") {+ return buildOpenResponsesWebhookBody({ state, configModel });+ }+ if (endpointKind === "hook_wake") {+ return buildHookWakeBody(state);+ }+ if (endpointKind === "hook_agent") {+ return buildHookAgentBody({ state, includeSessionKey: includeHookSessionKey });+ }++ return buildLegacyWebhookBody({ state, context });+}+async function sendWebhookRequest(params: {url: string;method: string;@@ -92,30 +207,50 @@ async function sendWebhookRequest(params: {export async function executeWebhook(ctx: AdapterExecutionContext, url: string): Promise<AdapterExecutionResult> {const { onLog, onMeta, context } = ctx;const state = buildExecutionState(ctx);+ const originalUrl = url;+ const originalEndpointKind = resolveEndpointKind(originalUrl);+ let targetUrl = originalUrl;+ let endpointKind = resolveEndpointKind(targetUrl);+ const remappedFromResponses = originalEndpointKind === "open_responses";++ // In webhook mode, /v1/responses is legacy wiring. Prefer hooks/agent.+ if (remappedFromResponses) {+ const rewritten = deriveHookAgentUrlFromResponses(targetUrl);+ if (rewritten) {+ await onLog(+ "stdout",+ `[openclaw] webhook transport selected; remapping ${targetUrl} -> ${rewritten}\n`,+ );+ targetUrl = rewritten;+ endpointKind = resolveEndpointKind(targetUrl);+ }+ }++ const headers = { ...state.headers };+ if (endpointKind === "open_responses" && !headers["x-openclaw-session-key"] && !headers["X-OpenClaw-Session-Key"]) {+ headers["x-openclaw-session-key"] = state.sessionKey;+ }if (onMeta) {await onMeta({adapterType: "openclaw",command: "webhook",- commandArgs: [state.method, url],+ commandArgs: [state.method, targetUrl],context,});}- const headers = { ...state.headers };- if (isOpenResponsesEndpoint(url) && !headers["x-openclaw-session-key"] && !headers["X-OpenClaw-Session-Key"]) {- headers["x-openclaw-session-key"] = state.sessionKey;- }-+ const includeHookSessionKey = asBooleanFlag(ctx.config.hookIncludeSessionKey, false);const webhookBody = buildWebhookBody({- url,+ endpointKind,state,context,configModel: ctx.config.model,+ includeHookSessionKey,});const wakeCompatibilityBody = buildWakeCompatibilityPayload(state.wakeText);- const preferWakeCompatibilityBody = isWakeCompatibilityEndpoint(url);- const initialBody = preferWakeCompatibilityBody ? wakeCompatibilityBody : webhookBody;+ const preferWakeCompatibilityBody = endpointKind === "hook_wake";+ const initialBody = webhookBody;const outboundHeaderKeys = Object.keys(headers).sort();await onLog(@@ -127,10 +262,10 @@ export async function executeWebhook(ctx: AdapterExecutionContext, url: string):`[openclaw] outbound payload (redacted): ${stringifyForLog(redactForLog(initialBody), 12_000)}\n`,);await onLog("stdout", `[openclaw] outbound header keys: ${outboundHeaderKeys.join(", ")}\n`);- await onLog("stdout", `[openclaw] invoking ${state.method} ${url} (transport=webhook)\n`);+ await onLog("stdout", `[openclaw] invoking ${state.method} ${targetUrl} (transport=webhook kind=${endpointKind})\n`);if (preferWakeCompatibilityBody) {- await onLog("stdout", "[openclaw] using wake text payload for /hooks/wake compatibility\n");+ await onLog("stdout", "[openclaw] using webhook wake payload for /hooks/wake\n");}const controller = new AbortController();@@ -138,7 +273,7 @@ export async function executeWebhook(ctx: AdapterExecutionContext, url: string):try {const initialResponse = await sendWebhookRequest({- url,+ url: targetUrl,method: state.method,headers,payload: initialBody,@@ -146,9 +281,70 @@ export async function executeWebhook(ctx: AdapterExecutionContext, url: string):signal: controller.signal,});- if (!initialResponse.response.ok) {+ let activeResponse = initialResponse;+ let activeEndpointKind = endpointKind;+ let activeUrl = targetUrl;+ let activeHeaders = headers;+ let usedLegacyResponsesFallback = false;++ if (+ remappedFromResponses &&+ targetUrl !== originalUrl &&+ initialResponse.response.status === 404+ ) {+ await onLog(+ "stdout",+ `[openclaw] remapped hook endpoint returned 404; retrying legacy endpoint ${originalUrl}\n`,+ );++ activeEndpointKind = originalEndpointKind;+ activeUrl = originalUrl;+ usedLegacyResponsesFallback = true;+ const fallbackHeaders = { ...state.headers };+ if (+ activeEndpointKind === "open_responses" &&+ !fallbackHeaders["x-openclaw-session-key"] &&+ !fallbackHeaders["X-OpenClaw-Session-Key"]+ ) {+ fallbackHeaders["x-openclaw-session-key"] = state.sessionKey;+ }++ const fallbackBody = buildWebhookBody({+ endpointKind: activeEndpointKind,+ state,+ context,+ configModel: ctx.config.model,+ includeHookSessionKey,+ });++ await onLog(+ "stdout",+ `[openclaw] fallback headers (redacted): ${stringifyForLog(redactForLog(fallbackHeaders), 4_000)}\n`,+ );+ await onLog(+ "stdout",+ `[openclaw] fallback payload (redacted): ${stringifyForLog(redactForLog(fallbackBody), 12_000)}\n`,+ );+ await onLog(+ "stdout",+ `[openclaw] invoking fallback ${state.method} ${activeUrl} (transport=webhook kind=${activeEndpointKind})\n`,+ );++ activeResponse = await sendWebhookRequest({+ url: activeUrl,+ method: state.method,+ headers: fallbackHeaders,+ payload: fallbackBody,+ onLog,+ signal: controller.signal,+ });+ activeHeaders = fallbackHeaders;+ }++ if (!activeResponse.response.ok) {const canRetryWithWakeCompatibility =- !preferWakeCompatibilityBody && isWakeCompatibilityRetryableResponse(initialResponse.responseText);+ (activeEndpointKind === "open_responses" || activeEndpointKind === "generic") &&+ isWakeCompatibilityRetryableResponse(activeResponse.responseText);if (canRetryWithWakeCompatibility) {await onLog(@@ -157,9 +353,9 @@ export async function executeWebhook(ctx: AdapterExecutionContext, url: string):);const retryResponse = await sendWebhookRequest({- url,+ url: activeUrl,method: state.method,- headers,+ headers: activeHeaders,payload: wakeCompatibilityBody,onLog,signal: controller.signal,@@ -172,11 +368,12 @@ export async function executeWebhook(ctx: AdapterExecutionContext, url: string):timedOut: false,provider: "openclaw",model: null,- summary: `OpenClaw webhook ${state.method} ${url} (wake compatibility)`,+ summary: `OpenClaw webhook ${state.method} ${activeUrl} (wake compatibility)`,resultJson: {status: retryResponse.response.status,statusText: retryResponse.response.statusText,compatibilityMode: "wake_text",+ usedLegacyResponsesFallback,response: parseOpenClawResponse(retryResponse.responseText) ?? retryResponse.responseText,},};@@ -203,20 +400,20 @@ export async function executeWebhook(ctx: AdapterExecutionContext, url: string):}return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage:- isTextRequiredResponse(initialResponse.responseText)- ? "OpenClaw endpoint rejected the payload as text-required."- : `OpenClaw webhook failed with status ${initialResponse.response.status}`,- errorCode: isTextRequiredResponse(initialResponse.responseText)+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorMessage:+ isTextRequiredResponse(activeResponse.responseText)+ ? "OpenClaw endpoint rejected the payload as text-required."+ : `OpenClaw webhook failed with status ${activeResponse.response.status}`,+ errorCode: isTextRequiredResponse(activeResponse.responseText)? "openclaw_text_required": "openclaw_http_error",resultJson: {- status: initialResponse.response.status,- statusText: initialResponse.response.statusText,- response: parseOpenClawResponse(initialResponse.responseText) ?? initialResponse.responseText,+ status: activeResponse.response.status,+ statusText: activeResponse.response.statusText,+ response: parseOpenClawResponse(activeResponse.responseText) ?? activeResponse.responseText,},};}@@ -227,11 +424,12 @@ export async function executeWebhook(ctx: AdapterExecutionContext, url: string):timedOut: false,provider: "openclaw",model: null,- summary: `OpenClaw webhook ${state.method} ${url}`,+ summary: `OpenClaw webhook ${state.method} ${activeUrl}`,resultJson: {- status: initialResponse.response.status,- statusText: initialResponse.response.statusText,- response: parseOpenClawResponse(initialResponse.responseText) ?? initialResponse.responseText,+ status: activeResponse.response.status,+ statusText: activeResponse.response.statusText,+ usedLegacyResponsesFallback,+ response: parseOpenClawResponse(activeResponse.responseText) ?? activeResponse.responseText,},};} catch (err) {diff --git a/packages/adapters/openclaw/src/server/execute.ts b/packages/adapters/openclaw/src/server/execute.tsindex 68b651ea3b..c560a06728 100644--- a/packages/adapters/openclaw/src/server/execute.ts+++ b/packages/adapters/openclaw/src/server/execute.ts@@ -1,6 +1,6 @@import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";import { asString } from "@paperclipai/adapter-utils/server-utils";-import { isWakeCompatibilityEndpoint } from "./execute-common.js";+import { isHookEndpoint } from "./execute-common.js";import { executeSse } from "./execute-sse.js";import { executeWebhook } from "./execute-webhook.js";@@ -35,12 +35,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};}- if (transport === "sse" && isWakeCompatibilityEndpoint(url)) {+ if (transport === "sse" && isHookEndpoint(url)) {return {exitCode: 1,signal: null,timedOut: false,- errorMessage: "OpenClaw /hooks/wake is not stream-capable. Use SSE transport with a streaming endpoint.",+ errorMessage: "OpenClaw /hooks/* endpoints are not stream-capable. Use webhook transport for hooks.",errorCode: "openclaw_sse_incompatible_endpoint",};}diff --git a/packages/adapters/openclaw/src/server/test.ts b/packages/adapters/openclaw/src/server/test.tsindex 00e252add7..ea5bcd85e7 100644--- a/packages/adapters/openclaw/src/server/test.ts+++ b/packages/adapters/openclaw/src/server/test.ts@@ -34,6 +34,16 @@ function isWakePath(pathname: string): boolean {return value === "/hooks/wake" || value.endsWith("/hooks/wake");}+function isHooksPath(pathname: string): boolean {+ const value = pathname.trim().toLowerCase();+ return (+ value === "/hooks" ||+ value.startsWith("/hooks/") ||+ value.endsWith("/hooks") ||+ value.includes("/hooks/")+ );+}+function normalizeTransport(value: unknown): "sse" | "webhook" | null {const normalized = asString(value, "sse").trim().toLowerCase();if (!normalized || normalized === "sse") return "sse";@@ -163,12 +173,12 @@ export async function testEnvironment(});}- if (streamTransport === "sse" && isWakePath(url.pathname)) {+ if (streamTransport === "sse" && (isWakePath(url.pathname) || isHooksPath(url.pathname))) {checks.push({code: "openclaw_wake_endpoint_incompatible",level: "error",- message: "Endpoint targets /hooks/wake, which is not stream-capable for SSE transport.",- hint: "Use an endpoint that returns text/event-stream for the full run duration.",+ message: "Endpoint targets /hooks/*, which is not stream-capable for SSE transport.",+ hint: "Use webhook transport for /hooks/* endpoints.",});}}diff --git a/server/src/__tests__/openclaw-adapter.test.ts b/server/src/__tests__/openclaw-adapter.test.tsindex e13319ba24..f3e5dd5980 100644--- a/server/src/__tests__/openclaw-adapter.test.ts+++ b/server/src/__tests__/openclaw-adapter.test.ts@@ -332,6 +332,31 @@ describe("openclaw adapter execute", () => {expect(headers.authorization).toBe("Bearer gateway-token");});+ it("derives Authorization header from x-openclaw-token when webhookAuthHeader is unset", async () => {+ const fetchMock = vi.fn().mockResolvedValue(+ sseResponse([+ "event: response.completed\n",+ 'data: {"type":"response.completed","status":"completed"}\n\n',+ ]),+ );+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(+ buildContext({+ url: "https://agent.example/sse",+ method: "POST",+ headers: {+ "x-openclaw-token": "gateway-token",+ },+ }),+ );++ expect(result.exitCode).toBe(0);+ const headers = (fetchMock.mock.calls[0]?.[1]?.headers ?? {}) as Record<string, string>;+ expect(headers["x-openclaw-token"]).toBe("gateway-token");+ expect(headers.authorization).toBe("Bearer gateway-token");+ });+it("derives issue session keys when configured", async () => {const fetchMock = vi.fn().mockResolvedValue(sseResponse([@@ -564,7 +589,7 @@ describe("openclaw adapter execute", () => {expect((body.paperclip as Record<string, unknown>).streamTransport).toBe("webhook");});- it("uses OpenResponses payload shape for webhook transport against /v1/responses", async () => {+ it("remaps legacy /v1/responses URLs to /hooks/agent in webhook transport", async () => {const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ ok: true }), {status: 200,@@ -586,16 +611,69 @@ describe("openclaw adapter execute", () => {expect(result.exitCode).toBe(0);expect(fetchMock).toHaveBeenCalledTimes(1);+ expect(String(fetchMock.mock.calls[0]?.[0] ?? "")).toBe("https://agent.example/hooks/agent");const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;- expect(body.foo).toBe("bar");- expect(body.stream).toBe(false);- expect(body.model).toBe("openclaw");- expect(String(body.input ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");- const metadata = body.metadata as Record<string, unknown>;- expect(metadata.PAPERCLIP_RUN_ID).toBe("run-123");- expect(metadata.paperclip_session_key).toBe("paperclip");- expect(metadata.paperclip_stream_transport).toBe("webhook");+ expect(typeof body.message).toBe("string");+ expect(String(body.message ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");+ expect(body.stream).toBeUndefined();+ expect(body.input).toBeUndefined();+ expect(body.metadata).toBeUndefined();expect(body.paperclip).toBeUndefined();+ const headers = (fetchMock.mock.calls[0]?.[1]?.headers ?? {}) as Record<string, string>;+ expect(headers["x-openclaw-session-key"]).toBeUndefined();+ });++ it("falls back to legacy /v1/responses when remapped /hooks/agent returns 404", async () => {+ const fetchMock = vi+ .fn()+ .mockResolvedValueOnce(+ new Response("Not Found", {+ status: 404,+ statusText: "Not Found",+ headers: {+ "content-type": "text/plain",+ },+ }),+ )+ .mockResolvedValueOnce(+ new Response(JSON.stringify({ ok: true }), {+ status: 200,+ statusText: "OK",+ headers: {+ "content-type": "application/json",+ },+ }),+ );+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(+ buildContext({+ url: "https://agent.example/v1/responses",+ streamTransport: "webhook",+ }),+ );++ expect(result.exitCode).toBe(0);+ expect(fetchMock).toHaveBeenCalledTimes(2);+ expect(String(fetchMock.mock.calls[0]?.[0] ?? "")).toBe("https://agent.example/hooks/agent");+ expect(String(fetchMock.mock.calls[1]?.[0] ?? "")).toBe("https://agent.example/v1/responses");++ const firstBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;+ expect(typeof firstBody.message).toBe("string");+ expect(String(firstBody.message ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");++ const secondBody = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body ?? "{}")) as Record<string, unknown>;+ expect(secondBody.stream).toBe(false);+ expect(typeof secondBody.input).toBe("string");+ expect(String(secondBody.input ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");++ const secondHeaders = (fetchMock.mock.calls[1]?.[1]?.headers ?? {}) as Record<string, string>;+ expect(secondHeaders["x-openclaw-session-key"]).toBe("paperclip");+ expect(result.resultJson).toEqual(+ expect.objectContaining({+ usedLegacyResponsesFallback: true,+ }),+ );});it("uses wake compatibility payloads for /hooks/wake when transport=webhook", async () => {@@ -624,6 +702,73 @@ describe("openclaw adapter execute", () => {expect(body.paperclip).toBeUndefined();});+ it("uses /hooks/agent payloads for webhook transport and omits sessionKey by default", async () => {+ const fetchMock = vi.fn().mockResolvedValue(+ new Response(JSON.stringify({ ok: true }), {+ status: 200,+ statusText: "OK",+ headers: {+ "content-type": "application/json",+ },+ }),+ );+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(+ buildContext({+ url: "https://agent.example/hooks/agent",+ streamTransport: "webhook",+ payloadTemplate: {+ name: "Paperclip Hook",+ wakeMode: "next-heartbeat",+ deliver: true,+ channel: "last",+ model: "openai/gpt-5.2-mini",+ },+ }),+ );++ expect(result.exitCode).toBe(0);+ expect(fetchMock).toHaveBeenCalledTimes(1);+ const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;+ expect(typeof body.message).toBe("string");+ expect(String(body.message)).toContain("PAPERCLIP_RUN_ID=run-123");+ expect(body.name).toBe("Paperclip Hook");+ expect(body.wakeMode).toBe("next-heartbeat");+ expect(body.deliver).toBe(true);+ expect(body.channel).toBe("last");+ expect(body.model).toBe("openai/gpt-5.2-mini");+ expect(body.sessionKey).toBeUndefined();+ expect(body.text).toBeUndefined();+ expect(body.paperclip).toBeUndefined();+ });++ it("includes sessionKey for /hooks/agent payloads only when hookIncludeSessionKey=true", async () => {+ const fetchMock = vi.fn().mockResolvedValue(+ new Response(JSON.stringify({ ok: true }), {+ status: 200,+ statusText: "OK",+ headers: {+ "content-type": "application/json",+ },+ }),+ );+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(+ buildContext({+ url: "https://agent.example/hooks/agent",+ streamTransport: "webhook",+ hookIncludeSessionKey: true,+ }),+ );++ expect(result.exitCode).toBe(0);+ expect(fetchMock).toHaveBeenCalledTimes(1);+ const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;+ expect(body.sessionKey).toBe("paperclip");+ });+it("retries webhook payloads with wake compatibility format on text-required errors", async () => {const fetchMock = vi.fn()@@ -649,7 +794,7 @@ describe("openclaw adapter execute", () => {const result = await execute(buildContext({- url: "https://agent.example/v1/responses",+ url: "https://agent.example/webhook",streamTransport: "webhook",}),);@@ -658,8 +803,8 @@ describe("openclaw adapter execute", () => {expect(fetchMock).toHaveBeenCalledTimes(2);const firstBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;const secondBody = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body ?? "{}")) as Record<string, unknown>;- expect(firstBody.model).toBe("openclaw");- expect(String(firstBody.input ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");+ expect(String(firstBody.text ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");+ expect(firstBody.paperclip).toBeTypeOf("object");expect(secondBody.mode).toBe("now");expect(String(secondBody.text ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");});@@ -697,7 +842,7 @@ describe("openclaw adapter execute", () => {const result = await execute(buildContext({- url: "https://agent.example/v1/responses",+ url: "https://agent.example/webhook",streamTransport: "webhook",}),);@@ -739,6 +884,21 @@ describe("openclaw adapter execute", () => {expect(result.errorCode).toBe("openclaw_sse_incompatible_endpoint");expect(fetchMock).not.toHaveBeenCalled();});++ it("rejects /hooks/agent endpoints in SSE mode", async () => {+ const fetchMock = vi.fn();+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(+ buildContext({+ url: "https://agent.example/hooks/agent",+ }),+ );++ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("openclaw_sse_incompatible_endpoint");+ expect(fetchMock).not.toHaveBeenCalled();+ });});describe("openclaw adapter environment checks", () => {@@ -766,6 +926,24 @@ describe("openclaw adapter environment checks", () => {expect(check?.level).toBe("error");});+ it("reports /hooks/agent endpoints as incompatible for SSE mode", async () => {+ const fetchMock = vi+ .fn()+ .mockResolvedValue(new Response(null, { status: 405, statusText: "Method Not Allowed" }));+ vi.stubGlobal("fetch", fetchMock);++ const result = await testEnvironment({+ companyId: "company-123",+ adapterType: "openclaw",+ config: {+ url: "https://agent.example/hooks/agent",+ },+ });++ const check = result.checks.find((entry) => entry.code === "openclaw_wake_endpoint_incompatible");+ expect(check?.level).toBe("error");+ });+it("reports unsupported streamTransport settings", async () => {const fetchMock = vi.fn()