fix(openclaw): 0.4.2 — verified Pinata install flow + security warnings preamble

[paulgnz]

A live Pinata Agents install of 0.4.1 surfaced one code bug, two doc lies, and one missing operator preamble. This bundle ships all four fixes as 0.4.2.

Code: Plugin loaded: now reports the actual tool count

The README told operators to grep for [xpr-agents] Plugin loaded: 72 tools (35 read, 37 write) — a string the code never emitted (it logged Plugin loaded: <network> (<rpc>), no count). Rather than backing out the README claim, this PR instruments registration: xprAgentsPlugin() wraps api.registerTool with a counter and logs:

[xpr-agents] Plugin loaded: 72 tools, mainnet (https://proton.eosusa.io)

The count is computed from real registrations, so the README claim stays true even if tools are added.

Doc lie 1: harness install path was unverified

The docs hand-waved "register with your harness" because we'd never actually traced what an OpenClaw harness does with the package. Now verified empirically on a live Pinata Agents container running OpenClaw 2026.3.x:

• Plain npm install @xpr-agents/openclaw is NOT sufficient — the harness does not auto-scan workspace node_modules.
• The supported install is openclaw plugins install @xpr-agents/openclaw, which downloads from npm, copies to ~/.openclaw/extensions/openclaw/, and auto-writes plugins.entries.openclaw.enabled + plugins.installs.openclaw.* metadata to ~/.openclaw/openclaw.json.

Docs now show the verified command + the exact JSON diff the installer writes + explicit "npm install is not enough" callout.

Doc lie 2: XPR_ACCOUNT placement was ambiguous

PINATA.md suggested XPR_ACCOUNT could go in the plugin's config tree. It can't — the plugin reads process.env.XPR_ACCOUNT, which comes from env.vars in openclaw.json, NOT from plugins.entries.openclaw.config. Operators who put it in the config tree silently end up in read-only mode.

Docs now show the correct env.vars.XPR_ACCOUNT surface with a contrastive note pointing at the wrong location.

Missing preamble: 19 install-time security warnings

OpenClaw's installer scans tarballs and flags risky patterns. It finds 19 in @xpr-agents/openclaw — every one intentional, now explained in a new "Security notes" section in the README:

Count	Pattern	Why it's intentional
16×	env-var + network send	Each skill reads its own service API key (Replicate, GitHub, Pinata, Shellbook, CoinGecko, A2A) and calls that service. No blockchain key is read from env.
1×	child_process exec	The proton CLI shell-out — literally the post-charliebot security feature. The whole point of v0.4.x is the blockchain key never enters the agent process.
2×	Dynamic code execution	The code-sandbox skill's entire purpose.

Pre-empts the 19-lines-of-red-text-at-install moment that was making operators bail.

Pinata-specific restart mechanism

openclaw gateway restart doesn't work on Pinata's container — they don't expose systemctl, command errors with "Gateway service disabled." The actual mechanism: patching openclaw.json makes the harness emit SIGUSR1 to the gateway process. PINATA.md now documents this with the expected restart event shape.

Harness-vs-standalone registration gap

Standalone scaffold auto-registers via ensureRegistered(). Harness path doesn't. Every xpr_update_* / xpr_set_agent_status fails with Agent not found until the operator explicitly calls xpr_register_agent. Docs now name this and use xpr_register_agent as the canonical first-signed-test (replacing the previous "send 0.0001 XPR" recipe — the plugin has no transfer tool, it's domain-scoped).

Verification

• 80 openclaw tests pass
• Smoke-test confirms Plugin loaded: 72 tools, mainnet (...) line emits from dist/index.js
• All harness-flow specifics verified against a live OpenClaw 2026.3.x install (Pinata Agents container)