From 8e42c6cdac1efe11738e4a316d3dbd654a0c29f2 Mon Sep 17 00:00:00 2001
From: Wes Belt <wes@diydev.io>
Date: Fri, 3 Apr 2026 11:25:58 -0400
Subject: [PATCH 1/2] fix(openclaw-gateway): make claimedApiKeyPath
 configurable per agent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The openclaw_gateway adapter hardcodes the Paperclip API key path to
~/.openclaw/workspace/paperclip-claimed-api-key.json in buildWakeText().
In multi-agent OpenClaw deployments, each agent has its own workspace
with its own key file. The hardcoded path forces all agents to share
one key, breaking agent identity isolation.

Add a claimedApiKeyPath field to the adapter config (with UI input)
that allows operators to set a per-agent path. Falls back to the
current default when unset — zero behavior change for existing
deployments.

Fixes #930
---
 .../adapters/openclaw-gateway/src/server/execute.ts  | 12 +++++++++---
 ui/src/adapters/openclaw-gateway/config-fields.tsx   | 10 ++++++++++
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/packages/adapters/openclaw-gateway/src/server/execute.ts b/packages/adapters/openclaw-gateway/src/server/execute.ts
index f1c85c11..16116041 100644
--- a/packages/adapters/openclaw-gateway/src/server/execute.ts
+++ b/packages/adapters/openclaw-gateway/src/server/execute.ts
@@ -313,6 +313,12 @@ function resolvePaperclipApiUrlOverride(value: unknown): string | null {
   }
 }
 
+const DEFAULT_CLAIMED_API_KEY_PATH = "~/.openclaw/workspace/paperclip-claimed-api-key.json";
+
+function resolveClaimedApiKeyPath(value: unknown): string {
+  return nonEmpty(value) ?? DEFAULT_CLAIMED_API_KEY_PATH;
+}
+
 function buildPaperclipEnvForWake(ctx: AdapterExecutionContext, wakePayload: WakePayload): Record<string, string> {
   const paperclipApiUrlOverride = resolvePaperclipApiUrlOverride(ctx.config.paperclipApiUrl);
   const paperclipEnv: Record<string, string> = {
@@ -335,8 +341,7 @@ function buildPaperclipEnvForWake(ctx: AdapterExecutionContext, wakePayload: Wak
   return paperclipEnv;
 }
 
-function buildWakeText(payload: WakePayload, paperclipEnv: Record<string, string>): string {
-  const claimedApiKeyPath = "~/.openclaw/workspace/paperclip-claimed-api-key.json";
+function buildWakeText(payload: WakePayload, paperclipEnv: Record<string, string>, claimedApiKeyPath: string): string {
   const orderedKeys = [
     "PAPERCLIP_RUN_ID",
     "PAPERCLIP_AGENT_ID",
@@ -1053,7 +1058,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
 
   const wakePayload = buildWakePayload(ctx);
   const paperclipEnv = buildPaperclipEnvForWake(ctx, wakePayload);
-  const wakeText = buildWakeText(wakePayload, paperclipEnv);
+  const claimedApiKeyPath = resolveClaimedApiKeyPath(ctx.config.claimedApiKeyPath);
+  const wakeText = buildWakeText(wakePayload, paperclipEnv, claimedApiKeyPath);
 
   const sessionKeyStrategy = normalizeSessionKeyStrategy(ctx.config.sessionKeyStrategy);
   const configuredSessionKey = nonEmpty(ctx.config.sessionKey);
diff --git a/ui/src/adapters/openclaw-gateway/config-fields.tsx b/ui/src/adapters/openclaw-gateway/config-fields.tsx
index 19780d94..82bff3e2 100644
--- a/ui/src/adapters/openclaw-gateway/config-fields.tsx
+++ b/ui/src/adapters/openclaw-gateway/config-fields.tsx
@@ -150,6 +150,16 @@ export function OpenClawGatewayConfigFields({
             />
           </Field>
 
+          <Field label="Claimed API key path">
+            <DraftInput
+              value={eff("adapterConfig", "claimedApiKeyPath", String(config.claimedApiKeyPath ?? ""))}
+              onCommit={(v) => mark("adapterConfig", "claimedApiKeyPath", v || undefined)}
+              immediate
+              className={inputClass}
+              placeholder="~/.openclaw/workspace/paperclip-claimed-api-key.json"
+            />
+          </Field>
+
           <Field label="Session strategy">
             <select
               value={sessionStrategy}

From 1ce800c158923c8f8d8a0f665b3deedbbdd46230 Mon Sep 17 00:00:00 2001
From: Wes Belt <wes@diydev.io>
Date: Fri, 3 Apr 2026 14:15:36 -0400
Subject: [PATCH 2/2] docs: add claimedApiKeyPath to agentConfigurationDoc

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/adapters/openclaw-gateway/src/index.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/adapters/openclaw-gateway/src/index.ts b/packages/adapters/openclaw-gateway/src/index.ts
index 1bdf66f2..137cd340 100644
--- a/packages/adapters/openclaw-gateway/src/index.ts
+++ b/packages/adapters/openclaw-gateway/src/index.ts
@@ -36,6 +36,7 @@ Request behavior fields:
 - 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)
 - paperclipApiUrl (string, optional): absolute Paperclip base URL advertised in wake text
+- claimedApiKeyPath (string, optional): path to the claimed API key JSON file read by the agent at wake time (default ~/.openclaw/workspace/paperclip-claimed-api-key.json)
 
 Session routing fields:
 - sessionKeyStrategy (string, optional): issue (default), fixed, or run