From a251a535712f2cce61153dc638d3271a3c0a7692 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Sat, 7 Mar 2026 09:52:01 -0600
Subject: [PATCH] fix(openclaw): embed explicit heartbeat workflow in wake text

Include the full Paperclip API workflow (checkout, fetch, update) and
endpoint bans in the wake text sent to OpenClaw agents, preventing
them from guessing non-existent endpoints. Applied to both openclaw
and openclaw_gateway adapters.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../openclaw-gateway/src/server/execute.ts    | 35 +++++++++++++++++--
 .../openclaw/src/server/execute-common.ts     | 35 +++++++++++++++++--
 2 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/packages/adapters/openclaw-gateway/src/server/execute.ts b/packages/adapters/openclaw-gateway/src/server/execute.ts
index 3cc20533..407e455b 100644
--- a/packages/adapters/openclaw-gateway/src/server/execute.ts
+++ b/packages/adapters/openclaw-gateway/src/server/execute.ts
@@ -328,15 +328,21 @@ function buildWakeText(payload: WakePayload, paperclipEnv: Record<string, string
     envLines.push(`${key}=${value}`);
   }
 
+  const issueIdHint = payload.taskId ?? payload.issueId ?? "";
+  const apiBaseHint = paperclipEnv.PAPERCLIP_API_URL ?? "<set PAPERCLIP_API_URL>";
+
   const lines = [
     "Paperclip wake event for a cloud adapter.",
     "",
+    "Run this procedure now. Do not guess undocumented endpoints and do not ask for additional heartbeat docs.",
+    "",
     "Set these values in your run context:",
     ...envLines,
     `PAPERCLIP_API_KEY=<token from ${claimedApiKeyPath}>`,
     "",
     `Load PAPERCLIP_API_KEY from ${claimedApiKeyPath} (the token you saved after claim-api-key).`,
     "",
+    `api_base=${apiBaseHint}`,
     `task_id=${payload.taskId ?? ""}`,
     `issue_id=${payload.issueId ?? ""}`,
     `wake_reason=${payload.wakeReason ?? ""}`,
@@ -344,9 +350,34 @@ function buildWakeText(payload: WakePayload, paperclipEnv: Record<string, string
     `approval_id=${payload.approvalId ?? ""}`,
     `approval_status=${payload.approvalStatus ?? ""}`,
     `linked_issue_ids=${payload.issueIds.join(",")}`,
+    "",
+    "HTTP rules:",
+    "- Use Authorization: Bearer $PAPERCLIP_API_KEY on every API call.",
+    "- Use X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID on every mutating API call.",
+    "- Use only /api endpoints listed below.",
+    "- Do NOT call guessed endpoints like /api/cloud-adapter/*, /api/cloud-adapters/*, /api/adapters/cloud/*, or /api/heartbeat.",
+    "",
+    "Workflow:",
+    "1) GET /api/agents/me",
+    `2) Determine issueId: PAPERCLIP_TASK_ID if present, otherwise issue_id (${issueIdHint}).`,
+    "3) If issueId exists:",
+    "   - POST /api/issues/{issueId}/checkout with {\"agentId\":\"$PAPERCLIP_AGENT_ID\",\"expectedStatuses\":[\"todo\",\"backlog\",\"blocked\"]}",
+    "   - GET /api/issues/{issueId}",
+    "   - GET /api/issues/{issueId}/comments",
+    "   - Execute the issue instructions exactly.",
+    "   - If instructions require a comment, POST /api/issues/{issueId}/comments with {\"body\":\"...\"}.",
+    "   - PATCH /api/issues/{issueId} with {\"status\":\"done\",\"comment\":\"what changed and why\"}.",
+    "4) If issueId does not exist:",
+    "   - GET /api/companies/$PAPERCLIP_COMPANY_ID/issues?assigneeAgentId=$PAPERCLIP_AGENT_ID&status=todo,in_progress,blocked",
+    "   - Pick in_progress first, then todo, then blocked, then execute step 3.",
+    "",
+    "Useful endpoints for issue work:",
+    "- POST /api/issues/{issueId}/comments",
+    "- PATCH /api/issues/{issueId}",
+    "- POST /api/companies/{companyId}/issues (when asked to create a new issue)",
+    "",
+    "Complete the workflow in this run.",
   ];
-
-  lines.push("", "Run your Paperclip heartbeat procedure now.");
   return lines.join("\n");
 }
 
diff --git a/packages/adapters/openclaw/src/server/execute-common.ts b/packages/adapters/openclaw/src/server/execute-common.ts
index d2c71583..63deee6e 100644
--- a/packages/adapters/openclaw/src/server/execute-common.ts
+++ b/packages/adapters/openclaw/src/server/execute-common.ts
@@ -290,15 +290,21 @@ export function buildWakeText(payload: WakePayload, paperclipEnv: Record<string,
     envLines.push(`${key}=${value}`);
   }
 
+  const issueIdHint = payload.taskId ?? payload.issueId ?? "";
+  const apiBaseHint = paperclipEnv.PAPERCLIP_API_URL ?? "<set PAPERCLIP_API_URL>";
+
   const lines = [
     "Paperclip wake event for a cloud adapter.",
     "",
+    "Run this procedure now. Do not guess undocumented endpoints and do not ask for additional heartbeat docs.",
+    "",
     "Set these values in your run context:",
     ...envLines,
     `PAPERCLIP_API_KEY=<token from ${claimedApiKeyPath}>`,
     "",
     `Load PAPERCLIP_API_KEY from ${claimedApiKeyPath} (the token you saved after claim-api-key).`,
     "",
+    `api_base=${apiBaseHint}`,
     `task_id=${payload.taskId ?? ""}`,
     `issue_id=${payload.issueId ?? ""}`,
     `wake_reason=${payload.wakeReason ?? ""}`,
@@ -306,9 +312,34 @@ export function buildWakeText(payload: WakePayload, paperclipEnv: Record<string,
     `approval_id=${payload.approvalId ?? ""}`,
     `approval_status=${payload.approvalStatus ?? ""}`,
     `linked_issue_ids=${payload.issueIds.join(",")}`,
+    "",
+    "HTTP rules:",
+    "- Use Authorization: Bearer $PAPERCLIP_API_KEY on every API call.",
+    "- Use X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID on every mutating API call.",
+    "- Use only /api endpoints listed below.",
+    "- Do NOT call guessed endpoints like /api/cloud-adapter/*, /api/cloud-adapters/*, /api/adapters/cloud/*, or /api/heartbeat.",
+    "",
+    "Workflow:",
+    "1) GET /api/agents/me",
+    `2) Determine issueId: PAPERCLIP_TASK_ID if present, otherwise issue_id (${issueIdHint}).`,
+    "3) If issueId exists:",
+    "   - POST /api/issues/{issueId}/checkout with {\"agentId\":\"$PAPERCLIP_AGENT_ID\",\"expectedStatuses\":[\"todo\",\"backlog\",\"blocked\"]}",
+    "   - GET /api/issues/{issueId}",
+    "   - GET /api/issues/{issueId}/comments",
+    "   - Execute the issue instructions exactly.",
+    "   - If instructions require a comment, POST /api/issues/{issueId}/comments with {\"body\":\"...\"}.",
+    "   - PATCH /api/issues/{issueId} with {\"status\":\"done\",\"comment\":\"what changed and why\"}.",
+    "4) If issueId does not exist:",
+    "   - GET /api/companies/$PAPERCLIP_COMPANY_ID/issues?assigneeAgentId=$PAPERCLIP_AGENT_ID&status=todo,in_progress,blocked",
+    "   - Pick in_progress first, then todo, then blocked, then execute step 3.",
+    "",
+    "Useful endpoints for issue work:",
+    "- POST /api/issues/{issueId}/comments",
+    "- PATCH /api/issues/{issueId}",
+    "- POST /api/companies/{companyId}/issues (when asked to create a new issue)",
+    "",
+    "Complete the workflow in this run.",
   ];
-
-  lines.push("", "Run your Paperclip heartbeat procedure now.");
   return lines.join("\n");
 }