feat: add Tutorial 08 — OpenClaw Agent with AgentCore Payments (zero-code) - #1797
feat: add Tutorial 08 — OpenClaw Agent with AgentCore Payments (zero-code)#1797wirjo wants to merge 26 commits into
Conversation
Add a zero-code tutorial for using the @aws/openclaw-x402-payments plugin from ClawHub to transparently pay x402 paywalls via natural language conversation. - No Python/code required — install plugin and configure via chat - Agent-guided setup creates full payment infrastructure - Official AWS plugin published on ClawHub (source-linked, verified) - Covers: install → setup → fund → pay → inspect → clean up - Comparison table vs Strands/LangGraph/Browser approaches
✅ End-to-End Validation CompleteSuccessfully tested the full x402 payment flow on a live OpenClaw instance: Test endpoint: Plugin source updated: wirjo/agentcore-x402-payments-for-openclaw@68d5e98 with key fixes for x402 v2 compliance:
|
|
|
||
| > **You:** "Create a payment session with a $5 budget" | ||
|
|
||
| The agent calls `create_payment_session` which: |
There was a problem hiding this comment.
Do we have a way to make sure this tool by default requires customer approval? This might be the default behavior already - but good to check and make sure. Let's also call out the guidance here - something like it's best practice for customer to approve session creation each and every single time to avoid unexpected agent spending.
This is to make sure that customer does provide consent to create a session with budget, so their Claw agent won't go rogue and spends more than they should.
There was a problem hiding this comment.
Fixed in d2b6927. The plugin is designed so that create_payment_session requires explicit user approval by default — the SKILL.md instructs the agent to always ask.
Strengthened the guidance in Step 4 with:
- "The agent MUST request explicit user approval before creating any session"
- "Review the budget amount and duration before approving every single time"
- "This is a safety-critical control. The agent is configured to always ask before spending. If an agent creates sessions without asking, that is a bug — report it."
This makes it unmistakably clear that autonomous spending without consent is not acceptable.
| - **AWS credentials** configured (`aws sts get-caller-identity` to verify) | ||
| - **Coinbase CDP API key** — get one at [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com) | ||
|
|
||
| > **Testnet only.** All payments use Base Sepolia (Ethereum) with free USDC from [faucet.circle.com](https://faucet.circle.com/). Testnet USDC has no real-world value. |
There was a problem hiding this comment.
This is just for this sample right? The setup (instrument etc) can be used for real mainnet money as long as the customer funds it. Let's be clear about that so the readers have the right expectation.
There was a problem hiding this comment.
Fixed in d2b6927. Added explicit note: "The infrastructure you create here is production-capable; only the network and funding differ." Makes clear that the same setup supports real mainnet money.
| - Install: `npm install -g openclaw` — see [docs.openclaw.ai](https://docs.openclaw.ai) | ||
| - **AWS account** with AgentCore Payments access (preview) | ||
| - **AWS credentials** configured (`aws sts get-caller-identity` to verify) | ||
| - **Coinbase CDP API key** — get one at [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com) |
There was a problem hiding this comment.
Please inlcude both Privy and CDP instructions and change the sample documentation to be wallet agnosttic - can be used with any wallet or both.
There was a problem hiding this comment.
Done — both CDP and Privy have been included since the 3rd revision (Option A / Option B in Step 2). The plugin and documentation are wallet-agnostic.
| The agent will guide you through: | ||
|
|
||
| 1. **Provide your CDP credentials:** | ||
| - CDP API Key ID (UUID from portal.cdp.coinbase.com) |
There was a problem hiding this comment.
+1 - Please include both CDP and Privy or point to documentation that has both.
There was a problem hiding this comment.
Done — both CDP and Privy paths are documented in Step 2 (Option A / Option B).
Changes: - Make tutorial fully standalone (no dependency on Tutorial 00) - Add both Coinbase CDP and Stripe/Privy wallet provider paths (Option A/B) - Add prominent spending controls section with best practices - Add explicit user approval guidance for session creation - Add Production Deployment section (mainnet networks, checklist) - Add supported networks table (Base Sepolia/Mainnet, Solana Devnet/Mainnet) - Remove all personal repository references - Align formatting with repo conventions (table headers, notes style) - Add Security & Spending Controls section - Clarify testnet is for learning; same setup supports production Addresses review comments from: - @peterjiang-dev: spending approval best practices, testnet/mainnet clarity - @mvangara10: wallet-agnostic (CDP + Privy), include both paths
|
Updated the README to address all review comments. Key changes:
cc @royosherove for review |
This is a getting-started sample — removed the mainnet production deployment section and checklist. Added a note clarifying that the same pattern supports mainnet by changing the network parameter.
mvangara10
left a comment
mvangara10
left a comment
There was a problem hiding this comment.
Please add AgentCore CLI command to create payment manager - or links
The plugin now auto-creates a payment manager when none exists, using the IAM role ARN provided by the user during setup. - Added IAM role creation command to Prerequisites - Added role_arn as first parameter in setup flow (both CDP and Privy) - Links to AgentCore Payments IAM setup docs Addresses: @mvangara10 review comment about AgentCore CLI command
| | Agent type | Single, payment-enabled | | ||
| | Agentic Framework | [OpenClaw](https://openclaw.ai) | | ||
| | LLM model | Any (Claude, Nova, GPT, Gemini — configured via OpenClaw) | | ||
| | Components | OpenClaw Gateway, `@aws/openclaw-x402-payments` plugin, AgentCore Payments, x402 | |
There was a problem hiding this comment.
Chethan had a comment that this needs to be updated to not to have x402.
There was a problem hiding this comment.
Fixed in d2b6927. Renamed folder from 08-openclaw-x402-payments-plugin → 08-openclaw-payments-plugin and updated the title to "Tutorial 08 — OpenClaw Agent Payments Plugin" (removed x402).
|
|
||
| > **Zero code required.** This tutorial installs an official plugin from [ClawHub](https://clawhub.ai/packages/@aws/openclaw-x402-payments) and walks through the entire payment setup and usage via natural conversation with your AI agent. | ||
|
|
||
| > **Supported regions:** `us-east-1`, `us-west-2`, `eu-central-1`, `ap-southeast-2`. |
There was a problem hiding this comment.
Shall we link official doc instead of hardcoding the regions - we are expanding to 10 more regions in Aug: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html
There was a problem hiding this comment.
Fixed in d2b6927. Replaced hardcoded region list with: "See AgentCore region availability for the latest list."
Adds the full aws-agent-payments plugin source alongside the tutorial README, making the sample self-contained. Users can now either: - Option A: Install from ClawHub (zero-code, recommended) - Option B: Build from source (for development/customization) The plugin/ directory contains: - TypeScript reference implementation (x402 protocol + AgentCore API) - Runtime plugin manifest (openclaw.plugin.json) - Agent-agnostic skill (SKILL.md + references) This is the same source submitted to awslabs/agent-plugins PR awslabs#243 for inclusion in the official Agent Plugins for AWS collection.
|
@mvangara10 @peterjiang-dev — Updated this PR to include the full plugin source code alongside the tutorial. What changed: The tutorial now offers two installation paths:
New This makes the tutorial fully self-contained — reviewers can inspect the complete implementation without needing an external repo. The same source code has also been submitted to awslabs/agent-plugins#243 as the |
|
Latest scan for commit: Security Scan ResultsScan Metadata
SummaryScanner ResultsThe table below shows findings by scanner, with status based on severity thresholds and dependencies: Column Explanations: Severity Levels (S/C/H/M/L/I):
Other Columns:
Scanner Results:
Severity Thresholds (Thresh Column):
Threshold Source: Values in parentheses indicate where the threshold is configured:
Statistics calculation:
|
…isclaimer - Add pragma:allowlist comments to suppress false positive on apiKeySecretSource/walletSecretSource field names in payments.ts (these are AWS SDK config field names, not actual secrets) - Add disclaimer at top of README: learning purposes only, AWS Shared Responsibility Model applies, user responsible for security in the cloud
| ### AWS Account Setup | ||
|
|
||
| 1. **Enable AgentCore Payments** in your AWS account (available in us-east-1, us-west-2, eu-central-1, ap-southeast-2) | ||
| 2. **Create an IAM role** with the following trust policy: |
There was a problem hiding this comment.
Is there a way to separate the processPayment permission with createPaymentSession permission? Some write up on the best practice: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-iam-roles.html
Ideally can we have createPaymentSession using one IAM role and processPayment using another role?
Or - if we can make sure that the user approves createPaymentSession and processPayment tool call separately that should be sufficient too.
There was a problem hiding this comment.
Fixed in d2b6927. Updated setup.md to:
- Link to the official IAM roles best practices doc
- Recommend separate IAM roles for setup vs runtime:
- Setup role (one-time):
CreatePaymentManager,CreatePaymentCredentialProvider,CreatePaymentConnector,CreatePaymentInstrument - Agent runtime role:
ProcessPayment,GetPaymentSession,CreatePaymentSession
- Setup role (one-time):
This ensures the running agent can't modify its own payment infrastructure.
Additionally, the agent is configured in SKILL.md to always request user approval separately for CreatePaymentSession (budget approval) before any ProcessPayment calls.
|
|
||
| | Error | Meaning | Resolution | | ||
| |---|---|---| | ||
| | `PaymentSessionExpired` | Session TTL exceeded | Create new session | |
There was a problem hiding this comment.
Let's highlight that - ask user for permission and budget then create new session
There was a problem hiding this comment.
Fixed in d2b6927. SKILL.md Step 2 now explicitly states:
Would you like to approve this?
And adds: "Always ask for budget and duration confirmation before proceeding."
The tool table also now says "requires user approval" rather than "locks USDC".
| |---|---|---| | ||
| | Infrastructure setup | `setup_x402_payments` | One-shot creation of Payment Manager, Connector, Wallet | | ||
| | Session status check | `get_payment_session_status` | Check if current session is usable | | ||
| | Session creation | `create_payment_session` | Mint a fresh session (locks USDC) | |
There was a problem hiding this comment.
Mint a fresh session with budget - let's not mentioned locks USDC - it confuses with some other operations.
There was a problem hiding this comment.
Fixed in d2b6927. Removed all "locks USDC" phrasing throughout. Now uses "sets a spending budget" which is clearer and doesn't confuse with DeFi locking/staking concepts.
Fixes based on detailed review (awslabs/agent-plugins#243): - Fix drained session reporting usable:true (now checks remainingUsd) - Fix credential provider naming (underscore → hyphen per naming rules) - Fix cross-origin redirect vulnerability (use redirect:manual, verify origin) - Fix v1 amount field compatibility (amount ?? maxAmountRequired) - Update SKILL.md: fix frontmatter, add reference links, fix retry guidance - Update references: remove false idempotency claims, fix field names, add security guidance for redirects and credentials
| } | ||
| ``` | ||
|
|
||
| ### Coinbase CDP Setup |
There was a problem hiding this comment.
For this setup - do we ask the user to put the credentials on .env file? Let's make sure the credentials are not passes as part of parameters to the LLM. It should be local to the user's environment all the time.
There was a problem hiding this comment.
Fixed in d2b6927. Credentials now have explicit guidance to use .env files with a code example:
# .env (add to .gitignore!)
CDP_API_KEY_ID=your-key-id
CDP_API_KEY_SECRET=your-key-secret
CDP_WALLET_SECRET=your-wallet-secretThe plugin reads these from the environment at execution time. The LLM never sees the raw values — only the agent host process has access. This is also emphasized in the SKILL.md guidelines.
1. Remove x402 from tutorial folder name (08-openclaw-payments-plugin) per Chethan's feedback via Peter 2. Replace hardcoded region list with link to official AgentCore regions docs (expanding to 10+ in Aug) 3. Recommend IAM role separation (setup vs runtime) with link to official IAM best practices docs 4. Remove 'locks USDC' phrasing — use 'sets spending budget' instead 5. Strengthen user approval guidance — explicitly state this is a safety-critical control, agent MUST ask every time 6. Add .env credential guidance — credentials must NEVER be passed as tool parameters to the LLM, read from environment only 7. Clarify testnet vs mainnet — same infrastructure is production-capable, only network parameter and funding differ 8. Update SKILL.md tool table and session creation guidance Addresses all comments from @peterjiang-dev on PR awslabs#1797
Update all references from @aws/openclaw-x402-payments to @aws/aws-agent-payments to match the new ClawHub package name. Reset version to 1.0.0 for the new package identity.
The tutorial should stand alone without cross-referencing the agent-plugins repository. Replaced PR links with ClawHub links.
Each reference file now links to its official source (x402 spec, AgentCore docs) with a note explaining these are agent-optimized extracts for runtime use.
Addressing all @mvangara10 feedbackQ: "Include both Privy and CDP, be wallet agnostic"A: Done — the tutorial has had both paths since the 3rd revision:
The README and plugin are wallet-agnostic by design. Q: "Add AgentCore CLI command to create payment manager"A: Done — Prerequisites now includes the Q: "Clean up this PR with everything that is already in the docs and add relevant docs link"A: Added canonical source links to the top of each reference file (commit 5d53837):
Why we keep the reference files: These are not human documentation — they are agent-optimized extracts used at runtime by the AI agent. The skill system (SKILL.md + references/) follows the AgentSkills progressive disclosure pattern: SKILL.md loads first (~5KB), references load on-demand only when the agent encounters a specific situation. Replacing them with raw doc URLs would require the agent to fetch and parse full documentation pages at runtime, degrading performance and reliability. Q: "Is that a part of openclaw skill?"A: Yes. The
This is the standard structure for OpenClaw plugins that include agent guidance alongside executable tools. It is published as-is to ClawHub. Q: "The folder does not have the sample? Can we consolidate the sample that uses this skill?"A: This tutorial is intentionally conversational/zero-code — unlike the other tutorials (00–07) which are Python scripts, this one demonstrates installing a plugin and using it through natural language conversation. The "sample" is the conversation flow documented in the README (Steps 2–6), and the The folder structure is: There is no separate Python script because the entire point is zero-code operation through an installed plugin. |
- Folder: 08-openclaw-payments-plugin → 08-openclaw-agent-with-agentcore-payments (consistent with repo pattern: agent + capability) - Skill: x402-payments → agentcore-payments (generic name, protocol-agnostic) - Updated README title, internal references, and added skill mapping note - x402 references in protocol descriptions and tool names remain (that's the protocol name)
Addressed: Folder rename + skill naming + consistencyChanges (commit 40e11a3): Q: Folder naming consistency with other tutorials Q: Skill name should be generic
Q: "08 folder will have the tutorial of a sample openclaw agent with agentcore payments which uses/maps to the openclaw skill within the folder" The README explicitly notes: "This tutorial uses the |
Security fix (highest priority): - Remove cdp_api_key_secret, wallet_secret, cdp_api_key_id from setup_x402_payments tool parameter schema entirely - Secrets are now read from environment variables at execution time (CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET) - Tool description explicitly states 'do NOT ask user to provide secrets in chat' - Returns clear error if env vars are missing Double-spend fix: - Derive stable clientToken from sha256(challengePayload + sessionId) - Same challenge retries are now idempotent (SDK won't generate fresh UUID per call) - Prevents double-charging when agent retries after timeout
1. Payment-Signature → X-PAYMENT everywhere (code, docs, skill)
The x402 spec uses X-PAYMENT as the canonical header name.
2. Added skill-only fallback section to SKILL.md showing how to use
AgentCore Payments via AWS CLI when runtime plugin isn't available.
Satisfies RFC graceful-degradation principle.
3. Added preview-status disclosure banner to README (AgentCore Payments
is in preview, APIs/pricing may change).
4. Reconciled protocol.md envelope to match documented cryptoX402 schema:
- Shows full flow: challenge → ProcessPayment input → signed output
- Input uses paymentInput.cryptoX402.{version, payload}
- Output uses paymentOutput.cryptoX402.payload
- X-PAYMENT header = base64(output payload)
Documents three tiers of enforcement for CreatePaymentSession: 1. Host-native approval gate (hard guarantee, e.g., OpenClaw) 2. IAM role separation (hard guarantee, human runs script) 3. Conversational confirmation (soft, LLM-enforceable only) Recommends Tier 1 or 2 for unattended agents. Explains that OpenClaw implements Tier 1 via elevated-permission approval cards.
The tool now requires a two-phase call pattern: 1. First call (confirmed=false) → returns AWAITING_USER_APPROVAL 2. Agent presents approval prompt to user 3. Only after user explicitly approves → second call (confirmed=true) This prevents autonomous session creation without human consent. The LLM cannot skip phase 1 since the tool returns a prompt instead of executing. Combined with the before_tool_call hook (for hosts that support it), this provides defense-in-depth for budget control.
F4 (Content re-entry): Add content-type allowlist and 64KB body cap in
replayWithHeader and probeUrl. Tag paid content with untrusted=true.
Suppress content from unsupported types.
F7 (Proof exposure): probeUrl now uses redirect:'manual' to prevent
leaking payment context. Content bounds prevent unbounded memory use.
Also: probe uses redirect:'manual' (was 'follow') to align with the
replay function's cross-origin protection.
|
Updated the tutorial README:
|
a1b0d9a to
adf7992
Compare
wirjo
changed the title
3 participants
Summary
Adds Tutorial 08 for using AWS AgentCore Payments from OpenClaw with x402 v2. The tutorial installs the published
@aws/aws-agents-paypackage from ClawHub and keeps payment administration outside the model-facing runtime.The tutorial does not carry a plugin source snapshot. The canonical package and bundled
agents-payskill are maintained inaws/agent-toolkit-for-aws.Install
The runtime exposes exactly:
get_payment_session_statusget_paid_contentValidation