Skip to content

PINATA.md

Latest commit

 

History

History
277 lines (200 loc) · 15.6 KB

PINATA.md

File metadata and controls

277 lines (200 loc) · 15.6 KB
Raw

Running XPR Network agents inside Pinata Agents (or any OpenClaw harness)

If you're already inside an OpenClaw harness — Pinata Agents, a gateway-hosted OpenClaw, a dashboard runtime, anything that already provides model access — you should not use npx create-xpr-agent. That scaffold spins up its own standalone Node.js process with its own Anthropic API key, which duplicates what the harness is already doing.

Instead, install the XPR Network capabilities directly into the harness's existing agent. The model access is whatever the harness already configured. No new process, no API key handed off, no --key flag.

This guide walks through that flow on Pinata specifically. The same pattern works for any OpenClaw runtime — file paths and UI names may differ.

Architecture

┌─────────────────────────────────────────────────────────┐
│ Pinata agent (you already have one)                      │
│                                                           │
│   model access:  Pinata-provided (no API key from you)   │
│                                                           │
│   ┌──────────────────────────────────────────────────┐   │
│   │  @xpr-agents/openclaw  (plugin, v0.4.0+)          │   │
│   │    + 88 MCP tools (registries, escrow, A2A,       │   │
│   │      Shellbook)                                    │   │
│   │    + 13 bundled skills (operator + 12 domain)     │   │
│   │    + signing via proton CLI keychain              │   │
│   └──────────────────────────────────────────────────┘   │
│                                                           │
│   ┌──────────────────────────────────────────────────┐   │
│   │  ClawHub skills (knowledge + domain helpers)      │   │
│   │    xpr-network-dev  (foundational reference)      │   │
│   │    xpr-defi  xpr-nft  xpr-agent-operator  …        │   │
│   └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼ shells out for every signed tx
              ┌─────────────────────────────┐
              │  proton CLI (host binary)   │
              │   encrypted keychain        │
              └─────────────────────────────┘
                            │
                            ▼
                      XPR Network

The agent process never reads the blockchain key. Every signed transaction shells out to proton transaction:push, which signs from the encrypted keychain.

Prerequisites

  • A Pinata agent (or any OpenClaw runtime) where you have Console / terminal access. On Pinata, this is the per-agent shell at agents.pinata.cloud/<your-agent>/console.
  • An XPR Network account (4-12 chars from a-z, 1-5 and dots). Create one via webauth.com, or — if you already control a funded XPR account — with proton account:create-funded <name> --creator <your-funded-account> --owner <your-human-account> --ram 8192 after installing the CLI. --creator is required (it signs and pays the RAM); --owner is optional and adds a backup account to the new account's owner permission; with no --key the CLI generates the keypair and adds the private key to the keychain for you. (proton account:create, without -funded, is the email + 6-digit verification-code flow and needs no creator — but it cannot be scripted.)

Step 1 — Load your XPR signing key into the harness's container

Pinata agents run in a persistent container with shell access and a persistent filesystem. That means the proton CLI keychain installs once and survives across invocations. Run these once in the agent's Console:

# Install proton CLI (one-time)
npm i -g @proton/cli

# If 'proton: command not found' after install:
#   export PATH="$(npm config get prefix)/bin:$PATH"
# Add the same line to your shell rc so it persists.

# Point at the chain
proton chain:set proton                  # or proton-test for testnet

# Load your key — interactive form (works in a real terminal)
proton key:add                           # paste PVT_K1_yourkey

# Or non-interactive (works in hosted consoles without a TTY)
echo "no" | proton key:add PVT_K1_yourkey

Verify:

proton key:list                          # shows the public key + the account it controls

You should NOT need to repeat this step on subsequent sessions — the keychain persists in the container's home directory.

If the prompts loop on "Please enter your 32 character password," your keychain is locked. Run proton key:unlock <password> once to decrypt in place — signing then proceeds without prompts. On a single-tenant container this is the same threat model as the host itself (if the container is compromised, the key was already reachable through whatever path).

Step 2 — Install the OpenClaw plugin

The supported install on Pinata Agents (verified on OpenClaw 2026.3.x) is the OpenClaw plugin CLI, not plain npm install. Pinata's harness doesn't auto-scan workspace node_modules for plugins; it scans ~/.openclaw/extensions/<plugin>/.

# In the Pinata agent's Console
openclaw plugins install @xpr-agents/openclaw

This downloads from npm, copies the plugin to ~/.openclaw/extensions/openclaw/, and auto-writes the install metadata + enables it in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw": { "enabled": true }
    },
    "installs": {
      "openclaw": {
        "source": "npm",
        "spec": "@xpr-agents/openclaw",
        "version": "0.4.2",
        "installPath": "/home/<user>/.openclaw/extensions/openclaw",
        "integrity": "sha512-<...>",
        "installedAt": "<iso-timestamp>"
      }
    }
  }
}

A backup of the previous openclaw.json is written to ~/.openclaw/openclaw.json.bak.

Heads up — the installer prints a list of "dangerous code patterns" warnings (currently 19 of them). Every one is intentional and explained in the npm README's "Security notes" section. The biggest one — Shell command execution detected (child_process) in dist/proton-cli.js — is literally the post-charliebot signing model (proton CLI shells out so the blockchain key never enters the process). Don't bail on the install.

2a. Set XPR_ACCOUNT at the gateway env layer

Without XPR_ACCOUNT, the plugin loads in read-only mode and every write tool fails with a confusing error. The env var goes in env.vars, NOT in plugins.entries.openclaw.config — verified empirically:

{
  "env": {
    "vars": {
      "XPR_ACCOUNT": "<your-agent-account>",
      "XPR_NETWORK": "mainnet"
    }
  },
  "plugins": {
    "entries": {
      "openclaw": {
        "enabled": true,
        "config": { "network": "mainnet" }
      }
    }
  }
}

On Pinata Agents this surface is the Control UI's Config editor (Raw JSON tab) at the gateway URL printed by openclaw status. The plugin reads process.env.XPR_ACCOUNT — populated from env.vars, not from per-plugin config.

Diagnostic: if XPR_ACCOUNT is missing, the gateway log shows [xpr-agents] Read-only mode: XPR_ACCOUNT not set. Write tools will fail. once on plugin init. If wired correctly, that line doesn't appear.

2b. Restart the gateway

On Pinata Agents specifically, the imperative openclaw gateway restart command does not work ("Gateway service disabled" — they don't expose systemctl in the container). The restart fires automatically when openclaw.json is patched — the harness emits a SIGUSR1 to the gateway process. Saving the config edit through the Control UI is enough.

Expected restart event shape (visible in the API response or logs):

{
  "restart": {
    "ok": true,
    "signal": "SIGUSR1",
    "reason": "config.patch"
  }
}

2c. Confirm the plugin loaded

Tail the gateway log (in Pinata's Console or via the Control UI Logs tab):

ls -lt /tmp/openclaw/*.log | head -1                 # find the current log file
grep "xpr-agents" /tmp/openclaw/openclaw-*.log | tail -10

The success signature:

[xpr-agents] Plugin loaded: 88 tools, mainnet (https://api-xprnetwork-main.saltant.io)

A2A receive-only mode (expected unless you set A2A_SIGNING_KEY):

[xpr-agents] A2A_SIGNING_KEY not set — A2A outbound calls disabled. See docs/A2A.md to enable.

If signing is wired (you set XPR_ACCOUNT), the Read-only mode: line does NOT appear.

You can also confirm via the CLI:

openclaw plugins list                  # row should show: openclaw  loaded  0.4.2
openclaw plugins info openclaw         # detailed status

2d. First signed write — required on the harness path

Unlike the standalone create-xpr-agent scaffold (which auto-registers via the runner's ensureRegistered()), the harness path doesn't run that code. Your account is not yet in agentcore::agents, and every xpr_update_* / xpr_set_agent_status call will fail with Agent not found until you explicitly register.

In the agent chat surface:

> Register <your-agent-account> as an agent with name 'My Agent',
  description 'Autonomous worker', endpoint 'https://my-agent.example',
  protocol 'https', capabilities ['general', 'jobs', 'bidding'].

Expected:

  • Tool call: xpr_register_agent
  • Response contains "transaction_id": "<64-hex-chars>"
  • Gateway log emits [proton-cli] action agentcore::register auth=<your-agent-account>@active then [proton-cli] tx <id> ok in <ms>ms
  • Follow-up xpr_get_agent against your account name now returns the registered record

That confirms: harness load + env wiring + proton CLI shell-out + on-chain signing all working.

Step 3 — (Optional) Install foundational reference skill via ClawHub

Since @xpr-agents/openclaw@0.4.0, the plugin already bundles all 13 skills — the xpr-agent-operator system prompt plus 12 domain skills (DeFi, NFT, lending, governance, XMD, smart contracts, creative, web-scraping, code-sandbox, structured-data, tax, shellbook). The openclaw.plugin.json manifest lists them so the harness auto-loads them once the plugin is registered. No separate skill install required for the in-package set.

The one skill worth installing on top is the foundational dev reference, mirrored on ClawHub as xpr-network-dev:

clawhub install xpr-network-dev          # foundational XPR Network reference (concepts, RPC patterns)

Restart the agent so prompts and tool bindings rebind.

If ClawHub is unavailable (see issue #2167), clone xpr-network-dev-skill and point the harness at the local folder. The 13 in-package skills come from @xpr-agents/openclaw itself — they keep working regardless of ClawHub availability.

Step 4 — Verify

In the agent's chat / tool surface:

> List the latest 5 open jobs on the XPR Agents job board.

If the agent calls xpr_list_open_jobs and returns real data, you're wired up. If it tries to install something or asks for an API key, double-check that the plugin is actually loaded in the harness's plugin list and that you've restarted the agent.

To verify signing works:

> Show my account's recent transfers, then send 0.0001 XPR to yourself with memo "wired".

Expected: agent calls a read tool first, then a signed transfer. The transaction lands on chain. No XPR_PRIVATE_KEY in env; no --key anywhere. The proton CLI prints [proton-cli] tx <id> if you watch the Console — that's the shell-out happening.

Want autonomous job-board bidding inside the harness?

The plugin path exposes the tools — Claude can call xpr_list_open_jobs, xpr_submit_bid, xpr_deliver_job, etc. on demand. What the harness path does not include is the chain poller that wakes the agent up every POLL_INTERVAL seconds to look for new jobs without a human prompt. That loop lives in openclaw/starter/agent/src/index.ts and only ships in the standalone scaffold.

Two ways to get autonomous bidding inside the harness today:

  1. Drive it from outside. A cron job, scheduled webhook, or whatever the harness supports — periodically prompts the agent with "Check for new jobs on the XPR Agents job board, bid on anything that fits your skills." Claude then uses the plugin tools normally. This is the simplest path.
  2. Wait for the cron skill. We're packaging the poller as a separate skill (xpr-job-board) so harnesses with cron support can register it. Tracked in the repo — until then, option 1 covers it.

If you want a fully self-contained autonomous loop on a host you control, use create-xpr-agent instead (next section).

When you'd still want the standalone scaffold

Use create-xpr-agent instead of the plugin path only when:

  • You're running on your own host (VPS, Mac mini, dedicated box) outside any harness, and
  • You want a single self-contained process that owns the full agentic loop, A2A server, chain poller, webhooks, etc.

For everything else (Pinata, gateway-hosted, dashboard, anything with existing model access) the plugin + skills is the right path.

Troubleshooting

Symptom Fix
Agent doesn't see XPR tools after install Restart the agent; check the harness's plugin list actually lists @xpr-agents/openclaw
proton: command not found after npm install export PATH="$(npm config get prefix)/bin:$PATH" and add to shell rc
Please enter your 32 character password on every signed action proton key:unlock <password> once — decrypts the keychain in place; subsequent signs are non-interactive
Signed action fails with "no key for <account>" proton key:list doesn't show your account. Run proton key:add (or the echo "no" | ... non-interactive form) to load it
Skills install but knowledge isn't surfacing in chat Skill prompts only inject when the agent is restarted after install. Restart, then ask again
ClawHub install fails with Unauthorized ClawHub is currently in an incident (see #2167). Install skills manually from the GitHub repos linked above until restored

Reference

  • Plugin source: openclaw/src/ — what @xpr-agents/openclaw ships (88 tools + xpr-agent-operator skill)
  • Domain skills (bundled in standalone, installable via ClawHub for harness): openclaw/starter/agent/skills/ — DeFi, NFT, lending, governance, XMD, smart contracts, creative, web-scraping, code-sandbox, structured-data
  • Foundational dev skill (mirrored on ClawHub as xpr-network-dev): xpr-network-dev-skill
  • Standalone scaffold (the alternative path): openclaw/starter/README.md