|
| 1 | +# Converse with an OpenClaw agent -- no coding assistant |
| 2 | + |
| 3 | +> **Disclaimer:** This sample is for learning and validation. Review the |
| 4 | +> security, compliance, IAM, wallet, and spending controls before adapting it |
| 5 | +> for production. |
| 6 | +
|
| 7 | +| Information | Details | |
| 8 | +|:--|:--| |
| 9 | +| Tutorial type | Conversational | |
| 10 | +| Agent type | Single agent with a bounded payment runtime | |
| 11 | +| Agent framework | [OpenClaw](https://openclaw.ai) | |
| 12 | +| Components | OpenClaw, `@aws/aws-agents-pay`, AgentCore Payments, x402 v2 | |
| 13 | + |
| 14 | + |
| 15 | + |
| 16 | +**Figure 1:** OpenClaw calls a paid x402 endpoint, which returns an HTTP 402 |
| 17 | +challenge. The `aws-agents-pay` plugin hands that challenge to Amazon Bedrock |
| 18 | +AgentCore Payments, which signs and settles against the payment instrument |
| 19 | +(testnet wallet) within the bounds a human operator configured up front |
| 20 | +(dashed line). OpenClaw never touches the wallet or IAM directly. |
| 21 | + |
| 22 | +OpenClaw can be hosted on AWS alongside AgentCore Payments -- see |
| 23 | +[aws-samples/sample-openclaw-on-aws](https://github.com/aws-samples/sample-openclaw-on-aws) |
| 24 | +for deployment options, including AgentCore Runtime Instances, Amazon EC2, |
| 25 | +and Amazon EKS. This tutorial's steps apply regardless of where you choose |
| 26 | +to run OpenClaw. |
| 27 | + |
| 28 | +Unlike the other two paths in this folder, this one skips the coding-assistant |
| 29 | +handoff entirely -- there is no `AGENTS.md` to load and no prompt to hand to a |
| 30 | +coding assistant. OpenClaw installs the plugin and reads its config directly. |
| 31 | + |
| 32 | +For the security boundary between human-run administration and the |
| 33 | +model-facing runtime, see the bundled skill's |
| 34 | +[security model](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-agents/skills/agents-pay/references/security-model.md) |
| 35 | +and |
| 36 | +[AgentCore Payments IAM roles](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-iam-roles.html). |
| 37 | + |
| 38 | +## 1. Install the package |
| 39 | + |
| 40 | +```bash |
| 41 | +openclaw plugins install clawhub:@aws/aws-agents-pay |
| 42 | +``` |
| 43 | + |
| 44 | +The package name is `@aws/aws-agents-pay`, the installed plugin ID is |
| 45 | +`aws-agents-pay`, and the bundled skill name is `agents-pay`. |
| 46 | + |
| 47 | +Verify that the runtime exposes exactly: |
| 48 | + |
| 49 | +- `get_payment_session_status`, which checks the configured payment session |
| 50 | +- `get_paid_content`, which requests an approved paid URL and completes the |
| 51 | + payment within the configured policy |
| 52 | + |
| 53 | +The runtime must not expose setup, session-creation, or raw-proof tools. |
| 54 | + |
| 55 | +## 2. Provision payment infrastructure |
| 56 | + |
| 57 | +Payment infrastructure (manager, connector, instrument, session) does not |
| 58 | +exist yet after Step 1 -- installing the plugin only wires up the model-facing |
| 59 | +runtime tools. Provisioning still goes through the human-only admin CLI |
| 60 | +either way; OpenClaw cannot create this infrastructure for you. Pick how you |
| 61 | +want to run those steps: |
| 62 | + |
| 63 | +- **Option A -- OpenClaw-assisted.** Ask OpenClaw to walk you through it: |
| 64 | + |
| 65 | + ``` |
| 66 | + Help me set up the agents-pay skill. |
| 67 | + ``` |
| 68 | + |
| 69 | + OpenClaw explains each `agentcore` CLI prompt and admin-script step as you |
| 70 | + go, but you still run the commands and type `approve` yourself. Session |
| 71 | + creation has no `--yes` flag and refuses outright without an interactive |
| 72 | + terminal -- that gate exists specifically so an agent cannot self-approve |
| 73 | + its own spending session, and OpenClaw walking you through it does not |
| 74 | + change that. |
| 75 | + |
| 76 | +- **Option B -- Fully manual.** Follow the |
| 77 | + [AgentCore Payments getting started guide](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-getting-started.html) |
| 78 | + or the skill's |
| 79 | + [operator guide](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-agents/skills/agents-pay/references/operator-guide.md) |
| 80 | + directly, with no OpenClaw involvement until you wire the resulting |
| 81 | + resource IDs into the config in Step 3. |
| 82 | + |
| 83 | +Both options run the identical `agentcore` CLI wizards and admin script for |
| 84 | +manager, connector, instrument, and session creation. The only difference is |
| 85 | +whether OpenClaw explains each prompt as you go or you read the docs |
| 86 | +yourself -- either way, provisioning happens in your own terminal, under your |
| 87 | +own credentials, with typed human approval for session creation. |
| 88 | + |
| 89 | +## 3. Configure trusted policy |
| 90 | + |
| 91 | +Configure the package with the operator-created resources from Step 2 and an |
| 92 | +explicit payment policy: |
| 93 | + |
| 94 | +```json |
| 95 | +{ |
| 96 | + "plugins": { |
| 97 | + "allow": ["aws-agents-pay"], |
| 98 | + "entries": { |
| 99 | + "aws-agents-pay": { |
| 100 | + "enabled": true, |
| 101 | + "config": { |
| 102 | + "region": "us-east-1", |
| 103 | + "paymentManagerArn": "arn:aws:bedrock-agentcore:us-east-1:ACCOUNT:payment-manager/NAME", |
| 104 | + "paymentInstrumentId": "payment-instrument-EXAMPLE", |
| 105 | + "payment_session_id": "payment-session-EXAMPLE", |
| 106 | + "userId": "openclaw-test-user", |
| 107 | + "networkPreferences": ["eip155:84532"], |
| 108 | + "allowedOrigins": ["https://sandbox.node4all.com"], |
| 109 | + "allowedRecipients": [ |
| 110 | + "0xd275612Bf0BB35638432c4D95eAA8D5d22346Ca6" |
| 111 | + ], |
| 112 | + "allowedAssetsByNetwork": { |
| 113 | + "eip155:84532": [ |
| 114 | + "0x036CbD53842c5426634e7929541eC2318f3dCF7e" |
| 115 | + ] |
| 116 | + }, |
| 117 | + "maxPaymentAmountAtomic": "100000", |
| 118 | + "returnBody": true |
| 119 | + } |
| 120 | + } |
| 121 | + } |
| 122 | + } |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +If omitted, `region` defaults to `us-east-1`. Set it explicitly to your |
| 127 | +payment manager's actual deployment region if it lives elsewhere -- the |
| 128 | +plugin will not warn you on a mismatch, it will just fail to find the |
| 129 | +manager. |
| 130 | + |
| 131 | +`100000` is 0.10 USDC at six decimals. This is the per-payment ceiling, not |
| 132 | +the same as the session budget -- the session (created out of band) separately |
| 133 | +limits cumulative spend until it expires or is exhausted. |
| 134 | + |
| 135 | +`allowedOrigins` and `allowedRecipients` above are the actual origin and |
| 136 | +`payTo` address for the Step 4 test endpoint |
| 137 | +(`sandbox.node4all.com/v1/x402-test`), taken directly from its x402 challenge |
| 138 | +response -- not generic placeholders. Copy this config as written and Step 4 |
| 139 | +will complete an end-to-end payment. Swap in your own merchant origin and |
| 140 | +recipient, verified out of band, once you move past this walkthrough. No |
| 141 | +other path in this folder uses this config format -- it is specific to the |
| 142 | +`aws-agents-pay` OpenClaw plugin. |
| 143 | + |
| 144 | +For a fixed merchant set, verify every address in `allowedRecipients` out of |
| 145 | +band using merchant documentation or another known-good source. For broader |
| 146 | +discovery scenarios, set `allowAnyRecipient: true` instead of |
| 147 | +`allowedRecipients` to let the publisher select the beneficiary -- the two |
| 148 | +options are mutually exclusive. This trades recipient allowlisting for |
| 149 | +flexibility; origin, network, asset, per-payment, and session-budget controls |
| 150 | +still apply. |
| 151 | + |
| 152 | +The sandbox endpoint above happens to be listed in the Coinbase x402 Bazaar |
| 153 | +(visible in its challenge response's `extensions.bazaar` field), but that is |
| 154 | +incidental here: this tutorial already knows the URL, so it pays it directly |
| 155 | +with no discovery step. If you want an agent that searches for paid tools |
| 156 | +instead of being given a URL, see |
| 157 | +[Tutorial 04 -- Agent with Coinbase Bazaar via Gateway](../../00-getting-started/04-agent-with-coinbase-bazaar-via-gateway/), |
| 158 | +a separate Strands-based sample with its own SDK-created session. |
| 159 | + |
| 160 | +For standalone config-file usage and file-permission requirements, see the |
| 161 | +[operator guide](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-agents/skills/agents-pay/references/operator-guide.md) |
| 162 | +in the bundled skill. |
| 163 | + |
| 164 | +## 4. Validate x402 v2 |
| 165 | + |
| 166 | +Ask OpenClaw to check payment-session status first. If the session is not |
| 167 | +usable, stop and use the trusted administrative path to review and create a new |
| 168 | +session. |
| 169 | + |
| 170 | +Then request an approved x402 v2 URL, for example: |
| 171 | + |
| 172 | +``` |
| 173 | +Fetch https://sandbox.node4all.com/v1/x402-test and tell me what you find. |
| 174 | +``` |
| 175 | + |
| 176 | +Expected output resembles: |
| 177 | + |
| 178 | +```json |
| 179 | +{ |
| 180 | + "paid": true, |
| 181 | + "refused": false, |
| 182 | + "status_code": 200, |
| 183 | + "content_type": "application/json", |
| 184 | + "body_sha256": "<sha256>", |
| 185 | + "body_bytes": 123, |
| 186 | + "content_returned": true, |
| 187 | + "body": "{\"status\":\"success\", ...}", |
| 188 | + "truncated": false, |
| 189 | + "untrusted": true |
| 190 | +} |
| 191 | +``` |
| 192 | + |
| 193 | +This walkthrough sets `"returnBody": true` in Step 3 so you can see the paid |
| 194 | +content and confirm the payment actually worked. The plugin caps the returned |
| 195 | +body at 10 KiB and always marks it `untrusted: true` -- publisher-controlled |
| 196 | +content can carry prompt-injection instructions, so treat `body` as data, not |
| 197 | +as instructions, and analyse it only through a component with no payment |
| 198 | +authority or network access. Leave `returnBody` unset or `false` for any |
| 199 | +endpoint where the agent only needs metadata and a digest, or where you don't |
| 200 | +want paid content anywhere near the payment-capable model's context. |
| 201 | + |
| 202 | +## Troubleshooting |
| 203 | + |
| 204 | +| Symptom | Action | |
| 205 | +|:--|:--| |
| 206 | +| Session is missing, expired, or drained | Stop. Create a reviewed session through the trusted administrative path. | |
| 207 | +| Payment option is refused | Verify origin, resource path, scheme, network, exact asset, recipient, and amount policy. | |
| 208 | +| Manager-not-found or `AccessDeniedException` despite a correct ARN | Confirm `region` in `openclaw.json` matches the payment manager's actual deployment region. Always set `region` explicitly rather than omitting it. | |
| 209 | +| No paid body appears | Expected when `returnBody` is unset or `false`. Set `returnBody: true` (as this walkthrough does) if the agent needs the response body. | |
| 210 | +| Config rejected with an `allowedRecipients`/`allowAnyRecipient` error | Set exactly one of the two -- they are mutually exclusive. | |
| 211 | + |
| 212 | +## References |
| 213 | + |
| 214 | +- [Build OpenClaw agents that transact with Amazon Bedrock AgentCore Payments](https://aws.amazon.com/blogs/machine-learning/build-openclaw-agents-that-transact-with-amazon-bedrock-agentcore-payments/) |
| 215 | + (AWS blog walkthrough of this pattern) |
| 216 | +- [`aws-agents-pay` skill references](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-agents/skills/agents-pay/references) |
| 217 | + (operator guide, security model, full troubleshooting) |
| 218 | +- [AgentCore Payments](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html) |
| 219 | +- [AgentCore Payments getting started](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-getting-started.html) |
| 220 | +- [AgentCore Payments IAM roles](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-iam-roles.html) |
| 221 | +- [x402 v2 specification](https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md) |
| 222 | +- [OpenClaw documentation](https://docs.openclaw.ai) |
0 commit comments