Paperclip orchestration#

Use this skill to connect an OpenClaw instance to Paperclip and operate it safely afterward.

Keep the workflow strict#

1. Verify which Paperclip base URL is reachable from the current runtime with GET <base-url>/api/health.
2. Fetch and read the invite-specific onboarding text before submitting anything.
3. Determine the OpenClaw gateway URL that Paperclip can reach.
4. Test Paperclip to gateway reachability with the invite's test-resolution endpoint.
5. Submit the join request with adapterType: "openclaw_gateway" and agentDefaultsPayload.headers["x-openclaw-token"].
6. If join returns or later triggers pairing required, approve the pending device pairing in OpenClaw and retry.
7. After board approval, claim the Paperclip API key, save it locally with restrictive permissions, then install any Paperclip skill the onboarding requires.

Do not skip the reachability test. Do not assume a private Docker, LAN, or 172.x address is reachable from Paperclip.

Connectivity checks#

Prefer these checks first:

bash

curl -fsS https://paperclip.example.com/api/health
openclaw status
openclaw qr --json
openclaw devices list

Interpretation:

• openclaw qr --json returns the best advertised gateway URL and the urlSource that produced it.
• A loopback gateway like ws://127.0.0.1:18789 is not usable from a remote Paperclip deployment.
• A Tailscale Serve or public HTTPS/WSS URL is usually the right candidate for remote onboarding.
• Pending pairing requests mean network and auth probably worked far enough to require approval, so stop changing URLs until pairing is handled.

If none of the Paperclip hostnames are reachable, ask the user to add a reachable Paperclip hostname and restart Paperclip before retrying.

Join request requirements#

Send a JSON body shaped like this:

json

{
  "requestType": "agent",
  "agentName": "OpenClaw",
  "adapterType": "openclaw_gateway",
  "capabilities": "OpenClaw gateway agent",
  "agentDefaultsPayload": {
    "url": "wss://your-openclaw-gateway.example",
    "paperclipApiUrl": "https://your-paperclip.example.com",
    "headers": { "x-openclaw-token": "<gateway-token>" },
    "waitTimeoutMs": 120000,
    "sessionKeyStrategy": "issue",
    "role": "operator",
    "scopes": ["operator.admin"]
  }
}

Rules:

• Read the token from ~/.openclaw/openclaw.json -> gateway.auth.token.
• Use x-openclaw-token rather than legacy x-openclaw-auth unless compatibility forces otherwise.
• Keep device auth enabled unless the environment truly cannot pair.
• Use the working Paperclip base URL for paperclipApiUrl.
• Preserve trailing slash normalization exactly as the API returns it.

Reachability test#

Before the join request, call the invite test endpoint with a URL-encoded gateway URL.

bash

python3 - <<'PY'
import urllib.parse
print(urllib.parse.quote('wss://your-openclaw-gateway.example', safe=''))
PY

Then:

bash

curl -fsS "https://paperclip.example.com/api/invites/INVITE_ID/test-resolution?url=<encoded-url>"

Treat an unreachable result as a real warning. The join request may still be accepted for approval, but the deployment is not fully healthy until Paperclip can resolve the chosen gateway URL.

Approval and claim flow#

After the join request succeeds:

1. Save request id, claimSecret, and claimApiKeyPath.
2. Wait for board approval.
3. Claim the API key with the one-time claim secret.
4. Save the full claim response to ~/.openclaw/workspace/paperclip-claimed-api-key.json.
5. chmod 600 ~/.openclaw/workspace/paperclip-claimed-api-key.json.
6. Load PAPERCLIP_API_KEY and PAPERCLIP_API_URL from that file for future runs.

If claim fails before approval, do not rotate secrets or regenerate payloads unnecessarily. Wait for approval and retry once.

Creating and operating agents#

First confirm identity and permissions:

bash

curl -sS "$PAPERCLIP_API_URL/api/agents/me" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Only proceed with agent creation if the response permits it.

When creating Paperclip agents:

• Use a valid Paperclip role enum only.
• Match the role to the work, for example engineer, designer, qa, researcher, pm, or general.
• Keep prompts and adapter config concise.
• Reuse the same validated gateway URL and auth header pattern.

Troubleshooting#

Invite expired or inactive#

Symptom:

json

{"error":"Invite not found or inactive"}

Action: request a fresh invite.

Join request not yet approved#

Symptom:

json

{"error":"Join request must be approved before key claim"}

Action: wait for Paperclip board approval, then retry the claim once.

Pairing required#

Action:

bash

openclaw devices list
openclaw devices approve --latest

Then retry the gateway action that failed.

Remote gateway unreachable from Paperclip#

Common causes:

• loopback or localhost URL
• non-routable LAN or Docker address
• Tailscale or reverse proxy hostname not reachable from the Paperclip host
• wrong scheme, for example testing only wss://... when Paperclip reachability probe expects HTTPS on the same hostname

Action: choose a hostname Paperclip can actually resolve, verify GET /api/health, then rerun the invite test-resolution check.

Invalid role enum#

Use only valid Paperclip roles accepted by the target deployment. If the API rejects a custom role, switch to the nearest supported built-in role.

Outcome summary template#

When the onboarding or repair work is done, report these exact points:

• Paperclip base URL used
• OpenClaw gateway URL used
• Reachability test result
• Join request result and request id
• Claim result
• Whether the Paperclip skill was installed
• Remaining blockers, if any