/agents-pay

OpenClaw Setup

OpenClaw uses the @aws/aws-agents-pay package from ClawHub. Its canonical source lives at plugins/aws-agents/skills/agents-pay/packages/openclaw/ in this repository.

For background on AgentCore Payments, see the getting started guide.

Step 0: Choose your user identity

Pick a stable userId before provisioning any payment resources. This identity must be used consistently across create-instrument, new-session, and your OpenClaw plugin config — a mismatch means the session cannot spend the instrument.

export PAYMENT_USER_ID="my-openclaw-agent"

Pass --user-id $PAYMENT_USER_ID to every admin command, or run init-config first (which generates and stores one in ~/.agents-pay/config.json for you).

Install

openclaw plugins install clawhub:@aws/aws-agents-pay

The plugin can load before payment resources are configured so the bundled setup skill remains discoverable. Both payment tools still fail closed until a complete trusted configuration exists.

Provision the AgentCore project

Create an AgentCore project before adding and deploying the payment resources:

npm install -g @aws/agentcore
PROJECT_NAME=openclaw-payments
agentcore create --project-name "$PROJECT_NAME" --no-agent
cd "$PROJECT_NAME"
agentcore add payment-manager
agentcore add payment-connector
agentcore deploy
export AGENTCORE_PROJECT_DIR="$PWD"

Run both agentcore add commands without flags so credentials remain in the interactive terminal. Keep AGENTCORE_PROJECT_DIR set while running the setup wizard from the plugin directory.

Quick Setup (Recommended)

After deploying the AgentCore project, run the interactive wizard. It creates the payment instrument and session, then generates the OpenClaw configuration:

cd ~/.openclaw/extensions/aws-agents-pay/skills/agents-pay
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python scripts/agents_pay_admin.py setup-openclaw \
  --project-dir "$AGENTCORE_PROJECT_DIR"

The wizard walks through: user identity → network → recipients → spend limits → instrument creation → delegation/funding → session approval → generates your OpenClaw config JSON ready to paste.

Manual Setup

Add to your OpenClaw config (~/.openclaw/openclaw.json or via openclaw config). Explicitly allow the installed plugin:

If payment infrastructure or a session does not exist, stop the LLM workflow. Open a separate terminal and run the human setup from the bundled skill:

cd ~/.openclaw/extensions/aws-agents-pay/skills/agents-pay
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python scripts/agents_pay_admin.py init-config \
  --max-per-payment-usd 0.05 \
  --network eip155:84532 \
  --recipient 0xMerchantWalletAddress
python scripts/agents_pay_admin.py create-instrument --email you@example.com
python scripts/agents_pay_admin.py new-session \
  --budget 1.00 \
  --expiry-minutes 60

The two agentcore add commands must run without flags so credentials remain in the interactive terminal. Do not paste credentials, command output, deployed state, or generated identifiers into an LLM conversation.

Complete delegation and testnet funding before creating the session. Then edit the OpenClaw config locally in the same terminal or a local editor.

Important: The userId below must match the identity used in create-instrument and new-session. A mismatch means the session cannot spend the instrument.

{
  "plugins": {
    "allow": ["aws-agents-pay"],
    "entries": {
      "aws-agents-pay": {
        "enabled": true,
        "config": {
          "region": "us-east-1",
          "paymentManagerArn": "arn:aws:bedrock-agentcore:us-east-1:ACCOUNT:payment-manager/NAME",
          "paymentInstrumentId": "payment-instrument-XXXX",
          "payment_session_id": "payment-session-XXXX",
          "userId": "your-user-id",
          "networkPreferences": ["eip155:84532"],
          "allowedOrigins": ["https://merchant.example"],
          "allowedRecipients": ["0xMerchantWalletAddress"],
          "allowedAssetsByNetwork": {
            "eip155:84532": [
              "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
            ]
          },
          "maxPaymentAmountAtomic": "100000"
        }
      }
    }
  }
}

The paymentManagerArn, paymentInstrumentId, payment_session_id, and userId come from the human-run administrative setup. Configure origins, recipients, networks, and exact asset contracts from values approved out of band. To deliberately allow publisher-selected beneficiaries, replace allowedRecipients with "allowAnyRecipient": true; the plugin rejects both fields together. The example maxPaymentAmountAtomic value is 100000 (0.10 USDC with 6 decimals), and no default is supplied.

How it works

OpenClaw executes payments through this TypeScript plugin, using get_paid_content. Policy validation, SSRF controls, idempotency, proof isolation, and merchant replay remain in TypeScript. The plugin invokes a fixed package-relative Python helper, without a shell, only for GetPaymentSession and ProcessPayment; the package-local .venv created above supplies boto3 and the standard AWS credential chain. It does not invoke the Python x402_fetch runtime. For other agent hosts, use the Python runtime described in SKILL.md instead, and never enable both paths at once.

The plugin exposes two scoped OpenClaw runtime tools only:

Security boundaries

• No general shell access. The agent cannot choose a command, script, path, or environment variable. The plugin starts only its fixed AgentCore helper with shell: false, bounded JSON, a timeout, and output limits.
• No setup at runtime. Payment Manager, connector, credential provider, instrument, and session creation happen outside the model-visible runtime.
• No credential exposure. Wallet provider secrets never appear in the tool interface. Rotate any provider credential previously entered through chat.
• No replacement sessions. The runtime cannot mint a fresh session. If the configured session expires or drains, create a new one through the trusted management path and update config.
• No signed proof exposure. The signed payment proof is attached only inside trusted request handling code and is never returned as tool output.
• Trusted challenge policy. Runtime code selects an approved offer instead of trusting accepts[0], and enforces HTTPS, public destinations, no redirects, configured origin and network, exact asset, positive bounded amount, approved recipient, and matching resource before ProcessPayment.
• x402 v2 only. The paid replay uses the required PAYMENT-SIGNATURE header. v1 challenges fail closed.
• Stable retries. The AgentCore client token binds the session, resource, network, asset, recipient, and amount while excluding publisher-controlled nonces.
• Publisher content isolation. Paid response bodies are not returned to the payment-capable model context. get_paid_content returns status, content type, byte count, and SHA-256 hash only.
• Budget enforcement. The AgentCore service enforces maxSpendAmount and expiryTimeInMinutes server-side regardless of what the agent requests.

Publish updates

See plugins/aws-agents/skills/agents-pay/packages/openclaw/PUBLISHING.md in the source repository for the build and publication workflow.