Como construir agentes OpenClaw com pagamentos via Amazon Bedrock AgentCore

Agentes autônomos que precisam pagar por serviços

Um dos desafios práticos de agentes de IA autônomos é que, ao navegar pela web, chamar APIs ou consultar servidores MCP (Protocolo de Contexto de Modelo), eles frequentemente encontram serviços que exigem pagamento antes de liberar o acesso. O problema: pausar para aguardar aprovação humana a cada transação destrói a proposta de valor de um agente autônomo.

Para resolver isso, a AWS anunciou uma integração entre o OpenClaw e o AgentCore Payments, uma capacidade do Amazon Bedrock AgentCore. A solução permite que agentes realizem pagamentos programáticos dentro de limites previamente aprovados por um operador humano, sem expor credenciais de carteira ao runtime do modelo.

Por que agentes precisam de uma camada de pagamento

Agentes de longa duração — como os que executam pesquisas ou pipelines de trabalho automatizados — podem se deparar com APIs pagas ou endpoints de conteúdo sem que nenhum operador esteja presente. Uma camada de pagamento delimitada permite que o agente continue operando dentro de limites definidos antecipadamente: destinatário aprovado, ativo, rede, valor por pagamento, orçamento acumulado e prazo de expiração.

Muitas APIs, serviços de dados e ferramentas MCP usam precificação por uso. Transações individuais podem custar menos de um dólar ou frações de centavo. As taxas mínimas de processamento de cartão tornam transações nessa escala economicamente inviáveis, enquanto pagamentos em stablecoin suportam valores pequenos com liquidação quase em tempo real. Isso torna protocolos nativos de HTTP como o x402 adequados para pagamentos programáticos iniciados por agentes.

Implementar isso diretamente exigiria integração com provedores de carteira, proteção de credenciais, autorização de pagamentos, limites determinísticos e observabilidade. Além disso, é preciso considerar que o modelo pode ser manipulado por entradas não confiáveis. O design não previne injeção de prompt — em vez disso, ele assume que entradas não confiáveis podem manipular o modelo e limita a autoridade do runtime por destinatário, ativo, rede, valor por pagamento, orçamento da sessão e prazo de expiração.

Visão geral da solução

O AgentCore Payments oferece uma camada de pagamento consistente à medida que os protocolos de pagamento para agentes evoluem. A integração com o OpenClaw demonstra o padrão usando x402 v2: processa o desafio HTTP 402 de um comerciante por meio de um provedor de carteira configurado e retorna uma autorização assinada que o cliente usa para repetir a requisição.

Outras capacidades do Amazon Bedrock AgentCore também entram em cena:

• AgentCore Identity armazena as credenciais do provedor de carteira com segurança.
• AgentCore Observability pode fornecer logs, métricas e rastreamentos via Amazon CloudWatch e AWS X-Ray quando a entrega de telemetria está configurada.

O AgentCore Payments suporta carteira Coinbase ou carteira Stripe Privy como conexão de pagamento. Ambas fornecem uma carteira de stablecoin embutida. Sujeito à disponibilidade do provedor e geográfica, é possível financiar a carteira por stablecoin ou moeda fiduciária usando cartão de débito. Ambos os provedores usam armazenamento de credenciais do AgentCore Identity e limites de gastos por sessão.

O OpenClaw é um assistente de IA que roda nos seus dispositivos e conecta modelos, ferramentas e canais de mensagens por meio de um Gateway local. A OpenClaw Foundation mantém o projeto, e plugins estendem o que o assistente pode fazer.

O design separa claramente a administração de pagamentos (executada por humanos) do runtime voltado ao modelo. Um humano provisiona a carteira, cria a sessão de pagamento, aprova destinatários e define o orçamento em um terminal confiável. O plugin aws-agents-pay expõe apenas duas ferramentas visíveis ao modelo:

• get_payment_session_status: verifica o status da sessão de pagamento configurada.
• get_paid_content: requisita uma URL paga aprovada e conclui o pagamento dentro da política configurada.

O runtime pode iniciar um pagamento dentro da sessão aprovada, mas não pode criar, estender ou substituir uma sessão.

Fluxo típico de pagamento

Um fluxo de pagamento típico funciona assim:

• O agente chama get_payment_session_status para confirmar que a sessão provisionada pelo operador está disponível.
• O agente chama get_paid_content para uma URL aprovada.
• O plugin realiza uma sondagem de rede delimitada e recebe uma resposta HTTP 402 contendo um desafio x402 v2.
• Após receber o desafio, o plugin verifica se o recurso do desafio tem a mesma origem e caminho da URL requisitada, e valida rede, ativo, destinatário e valor contra a política do operador antes de chamar ProcessPayment.
• Para uma nova tentativa da mesma requisição de pagamento, o plugin reutiliza o mesmo token de idempotência em vez de criar um segundo pagamento.
• O plugin aguarda até o horário validAfter da autorização assinada e, então, repete a requisição original com a assinatura de pagamento.
• Com returnBody habilitado, o plugin retorna o corpo da resposta paga, com limite de 10 KiB, marcado como untrusted: true. O plugin não retorna a prova de pagamento assinada ao modelo.

Pré-requisitos

Para seguir o guia, são necessários:

• OpenClaw versão 2026.3.24 ou posterior: npm install -g openclaw
• Node.js e npm
• Uma conta AWS com acesso ao AgentCore Payments
• Funções de Gerenciamento de Identidade e Acesso (IAM) separadas para administração e runtime, seguindo o guia de funções IAM do AgentCore Payments. A função de runtime do OpenClaw precisa apenas das operações de leitura necessárias para status e ProcessPayment — não deve ter permissões de escrita de sessão.
• Credenciais Coinbase CDP ou Stripe com Privy, inseridas apenas na CLI interativa do AgentCore.
• Um endpoint x402 v2 na Base Sepolia que você controla ou aprovou de forma independente. É possível usar o Coinbase x402 Bazaar para descobrir serviços candidatos, mas verifique o endpoint, destinatário, rede, ativo e preço antes de adicioná-los à política de pagamento.

Aviso de segurança: a segurança desta solução segue o modelo de responsabilidade compartilhada da AWS. A AWS é responsável pela segurança da nuvem, enquanto você é responsável pela segurança dentro da nuvem. Suas responsabilidades incluem configurar permissões IAM, proteger credenciais do provedor de carteira e definir políticas de pagamento.

Passos de implementação

1. Instalar o plugin pelo ClawHub

Confirme que o pacote @aws/aws-agents-pay está disponível no ClawHub e instale-o:

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

O nome do pacote é @aws/aws-agents-pay, o ID do plugin instalado é aws-agents-pay e o nome da skill embutida é agents-pay. Para inspecionar o guia de configuração embutido:

openclaw skills info agents-pay

Para inspecionar o plugin instalado:

openclaw plugins inspect aws-agents-pay

O runtime visível ao modelo deve expor apenas get_payment_session_status e get_paid_content. Se aparecer qualquer outra ferramenta de configuração, criação de sessão, shell ou outro tipo visível ao modelo, pare — isso pode indicar um pacote diferente, desatualizado ou modificado.

2. Configuração supervisionada por humano

Instalar o plugin não cria o gerenciador de pagamentos, conector, instrumento ou sessão de pagamento. Existem duas opções de provisionamento:

• Opção A – Configuração assistida pelo OpenClaw: peça ao OpenClaw: “Help me set up the agents-pay skill.” O OpenClaw pode explicar cada etapa, mas você deve executar os comandos administrativos e aprovar a criação da sessão por conta própria.
• Opção B – Configuração totalmente manual: siga o guia de configuração do OpenClaw diretamente, sem envolver o OpenClaw.

Em qualquer caso, siga o guia de configuração do OpenClaw em um terminal confiável supervisionado por humano. O guia cobre a criação do projeto AgentCore, provisionamento de recursos de pagamento, execução do assistente de configuração e adição da configuração gerada ao OpenClaw. Você deve inserir credenciais e digitar approve manualmente.

3. Configurar o plugin com uma política explícita

Revise a configuração gerada antes de habilitar o plugin. Ela deve incluir o ARN do gerenciador de pagamentos, ID do instrumento, ID da sessão, ID do usuário, rede, contrato exato do ativo, destinatários aprovados e um teto positivo por pagamento.

Para o walkthrough em sandbox, use a política de pagamento no Passo 3 do código de exemplo. Ela contém a rede Base Sepolia, origem, destinatário, ativo USDC, limite de pagamento e configuração de returnBody compatíveis com o endpoint de teste.

Para um conjunto fixo de comerciantes, verifique cada endereço em allowedRecipients fora de banda usando documentação do comerciante ou outra fonte confiável — não aprove um destinatário apenas porque ele apareceu em uma resposta HTTP 402. Para cenários de descoberta mais amplos, defina allowAnyRecipient: true para permitir que o publicador selecione o beneficiário; os controles de origem, rede, ativo, valor por pagamento e orçamento da sessão ainda se aplicam.

maxPaymentAmountAtomic limita um pagamento na menor unidade do ativo. Para um ativo USDC de seis decimais, 100000 representa 0,10 USDC. O orçamento da sessão de pagamento limita separadamente o gasto acumulado até a sessão expirar ou ser esgotada.

Segredos do provedor de carteira não pertencem à configuração do OpenClaw. Trate o ID da sessão de pagamento, identificadores de recursos, política de destinatários e outros valores de configuração como dados operacionais sensíveis.

Reinicie o gateway após salvar ~/.openclaw/openclaw.json:

openclaw gateway restart

4. Verificar status da sessão e pagar por conteúdo

Peça ao agente OpenClaw para verificar se a sessão configurada está disponível:

What's the status of my payment session?

Se a sessão estiver indisponível, expirada ou esgotada, pare. Use o caminho administrativo confiável para revisar a situação e criar uma sessão substituta — o runtime voltado ao modelo não pode criar nem expandir seu próprio orçamento.

Em seguida, peça ao agente para buscar o endpoint de teste:

Fetch https://sandbox.node4all.com/v1/x402-test

O plugin realiza uma sondagem delimitada, valida o desafio retornado contra a política do operador, chama o AgentCore Payments, aguarda até que a autorização assinada seja válida e repete a requisição. Com returnBody habilitado, a ferramenta retorna o corpo da resposta paga com content_returned: true, limitado a 10 KiB e marcado como untrusted: true. A prova de pagamento assinada não é retornada ao modelo.

Trate respostas de comerciantes e todo conteúdo recuperado como não confiável. O design não previne injeção de prompt — ele assume que o modelo pode ser manipulado e limita a autoridade de pagamento por separação de IAM, destinatários e ativos aprovados, teto por pagamento, orçamento acumulado da sessão e prazo de expiração. Habilite returnBody apenas quando o agente precisar da resposta paga, e trate essa resposta como dados, não como instruções.

Verifique o status da sessão novamente para confirmar que o orçamento restante reflete o pagamento realizado.

Limpeza

Para remover o plugin do OpenClaw e reiniciar o gateway:

openclaw plugins uninstall aws-agents-pay
openclaw gateway restart

Use o mesmo caminho administrativo confiável para remover os recursos de pagamento na AWS. Não exponha exclusão de infraestrutura ou criação de sessão ao runtime voltado ao modelo, e mantenha a função IAM do runtime sem essas permissões.

Colaboração com a OpenClaw Foundation

A AWS tem colaborado com a OpenClaw Foundation nessa integração, incluindo suporte a eventos da comunidade como o ClawCon, e trabalhou diretamente com a equipe de engenharia da Fundação para trazer o AgentCore Payments para o framework de plugins. Na visão da Fundação, pagamentos são uma extensão natural do que os plugins já fazem no OpenClaw: oferecer ao agente uma nova capacidade por meio de uma ferramenta bem definida.

Conclusão

Com o AgentCore Payments, um agente pode acessar APIs pagas, feeds de dados por uso e ferramentas MCP metered dentro de limites definidos antecipadamente por um humano. O AgentCore Payments cuida da integração com carteiras, limites de gastos e orquestração de pagamentos.

Nesse padrão com OpenClaw, o humano mantém as credenciais do provedor de carteira e a autoridade sobre destinatários, ativos, limites por pagamento, orçamento acumulado da sessão e prazo de expiração fora do runtime voltado ao modelo. O agente pode iniciar pagamentos apenas dentro dos limites aprovados.

Recursos

• Plugin no ClawHub: aws-agents-pay
• Código de exemplo: agente OpenClaw com AgentCore Payments
• Guia do desenvolvedor do Amazon Bedrock AgentCore Payments
• Especificação do protocolo x402
• Modelo de responsabilidade compartilhada da AWS
• Guia de funções IAM do AgentCore Payments
• Código de exemplo: OpenClaw na AWS

Fonte

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/)