diff --git a/packages/adapters/openclaw/README.md b/packages/adapters/openclaw/README.md new file mode 100644 index 00000000..10b7d4c1 --- /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.ts index 4ae9cdba..2d939d92 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.ts index fd0d6484..d2c71583 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 { const parsed = parseObject(value); const out: Record = {}; @@ -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.ts index f76d6729..a4f55989 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 { - 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 { + 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 { + 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 = { + 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 { + 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 { + 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 { 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.ts index 68b651ea..c560a067 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 { 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; + 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).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; - 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; - 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; + 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; + 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; + 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; + 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; + 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; + 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; const secondBody = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body ?? "{}")) as Record; - 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()