Cursor에 프라이빗 키를 붙여넣지 마세요: 코딩 에이전트에게 지갑을 부여하는 방법

빌드에 한창 몰두하고 있습니다. Cursor의 에이전트가 컨트랙트 호출을 작성하고 네트워크를 선택했으며, 테스트 트랜잭션을 보낼 준비가 되었습니다. 계획과 서명된 트랜잭션 사이에 남은 건 하나, 바로 키입니다. 그래서 에이전트가 읽을 수 있는 .env 파일에 프라이빗 키를 붙여넣고 계속 작업을 진행합니다.

숙련된 개발자들이 실제 자금과 관련된 작업에서 AI를 배제하는 이유가 바로 이 한 단계 때문입니다. 프라이빗 키는 전부 아니면 전무입니다. 에이전트가 그것을 읽을 수 있게 되는 순간, 어떤 체인에서든 그 지갑의 모든 자산을 영구적으로, 되돌릴 방법 없이 이동시킬 수 있습니다. 그리고 에이전트는 본질적으로 확률적입니다. 대부분은 매우 정확하지만, 가끔은 확신에 찬 채로 틀립니다.

이보다 나은 방법이 있습니다. 키를 넘기지 않고 에이전트에게 지갑을 넘기는 것입니다. 아래는 Alchemy CLI의 에이전트 지갑이 어떻게 작동하는지, 그리고 실제 한계는 어디에 있는지에 대한 설명입니다.

문제는 에이전트가 아니라 키다

에이전트를 위험 요소로 취급하고 싶어지지만, 사실 에이전트 자체가 문제는 아닙니다. 프라이빗 키는 애초에 공유하도록 설계되지 않았습니다. "이 금액까지만 보낼 수 있다", "이 체인들에서만", "다음 한 시간 동안만", "지금 당장 중단"과 같은 개념이 전혀 없습니다. 프라이빗 키는 전체 통제권을 부여하는 단일한 비밀이며, 이를 사용하는 유일한 방법은 그것을 노출시키는 것뿐입니다.

지금까지 개발자에게는 두 가지 선택지가 있었고, 둘 다 실질적인 비용을 수반했습니다. 키를 .env에 붙여넣고 에이전트가 자금을 완전히 통제하도록 두는 방법이 있는데, 이는 잘못된 프롬프트 하나로 지갑이 비워질 수 있는 상태를 의미합니다. 아니면 지갑 SDK를 커스텀 백엔드에 연결하고 인증, 서명, 취소를 직접 처음부터 구축하는 방법도 있지만, 이는 대부분의 팀이 감당하기 어려운 수 주간의 작업입니다. 전자는 너무 위험하고, 후자는 너무 비쌉니다.

실제로 필요한 건 스택 내 다른 곳에서 이미 접근 권한을 다루는 방식과 비슷합니다. 루트 비밀번호를 그대로 나눠주지 않습니다. 범위가 제한된 자격 증명을 발급하고, 그것이 할 수 있는 일을 정하고, 필요 없어지면 취소합니다. 지갑도 같은 방식으로 작동해야 합니다.

에이전트 지갑의 작동 방식

Alchemy CLI의 에이전트 지갑을 사용하면 대시보드에서 지갑을 생성하고, 터미널에 범위가 제한되고 기간이 한정된 세션을 부여한 다음, 에이전트가 명령줄에서 실제 트랜잭션을 보내도록 할 수 있습니다. 프라이빗 키는 CLI에 닿지 않고, Alchemy에도 닿지 않으며, .env 파일에 저장되는 일도 없습니다. 이는 각각 다른 주체가 소유하는 세 개의 레이어로 이해하면 도움이 됩니다.

커스터디 레이어: 키는 다른 누군가가 보관한다

지갑의 프라이빗 키는 저희의 임베디드 지갑 파트너인 Privy의 인프라에 보관됩니다. 사용자의 노트북에도, 리포지토리에도, 저희 시스템에도 존재하지 않습니다. 이 부분이 위험 계산 자체를 바꿉니다. 방금 .env에 붙여넣으려던 그 비밀은 이제 사용자도 에이전트도 직접 다루지 않는 대상이 됩니다.

세션 레이어: 에이전트는 비밀이 아니라 권한을 받는다

alchemy wallet connect를 실행하면 CLI가 사용자의 머신에서 새로운 P-256 키쌍을 생성하고, 그 쌍의 프라이빗 부분은 기기를 떠나지 않습니다. 브라우저가 Alchemy 대시보드로 열리고, 여기서 지갑을 선택하고 세션을 승인합니다. 승인이 이루어지면 CLI의 퍼블릭 키가 특정 기능으로 범위가 제한되고 사용자가 설정한 만료 시점으로 한정된 서명자로 해당 지갑에 등록됩니다.

그 이후로 모든 서명 호출은 2단계 챌린지로 진행됩니다. 저희 백엔드가 Privy가 요구하는 정확한 페이로드를 구성하고, 사용자의 CLI가 그 정확한 바이트를 로컬에서 서명하며, 그런 다음에야 요청이 Privy에 도달합니다. 세션이 만료되었거나, 취소되었거나, 바인딩 검사를 통과하지 못하면 다음 서명 시도는 저희 인프라를 벗어나기도 전에 거부됩니다. 에이전트는 자신이 쥔 비밀을 통해서가 아니라, 사용자가 정의한 세션을 통해 동작하는 것입니다.

통제 레이어: 킬 스위치는 사용자가 갖는다

지갑을 생성하거나 취소할 수 있는 곳은 대시보드뿐이며, 취소는 클릭 한 번으로 즉시 적용됩니다. 터미널에서 alchemy wallet disconnect를 실행할 수도 있습니다. 세션이 의도하지 않은 동작을 시작하면 즉시 종료할 수 있고, 서명도 함께 멈춥니다. 세션이 알아서 잘 동작하기를 그저 바라기만 하는 상황은 없습니다. 언제든 끝낼 수 있기 때문입니다.

에이전트가 실제로 할 수 있는 일

세션이 활성화되면 에이전트는 전체 트랜잭션 범위를 다룰 수 있습니다. EVM 체인에서는 네이티브 토큰과 ERC-20을 전송하고, 컨트랙트 호출을 하고, ERC-20 승인을 관리하고, 스왑하고, 메인넷 간 브리지를 할 수 있습니다. Solana에서는 SOL과 SPL 토큰을 전송할 수 있습니다. 트랜잭션은 저희 Wallet APIs를 통해 실행되므로, Gas Manager를 통한 가스 스폰서십, 배칭, 자동 재시도, ERC-20 가스 결제도 함께 사용할 수 있습니다.

CLI가 에이전트를 위한 툴 서페이스로 설계되었기 때문에, 에이전트는 이 명령들을 스스로 파악합니다. --json 플래그는 구조화된 출력을 반환하고, --no-interactive은 명령이 프롬프트에서 멈추지 않도록 하며, alchemy agent-prompt은 모든 명령, 플래그, 오류 코드를 설명하는 JSON 문서를 출력합니다. 이를 시스템 프롬프트에 넣으면 에이전트는 전체 범위를 한 번에 학습합니다. 통합할 SDK도 없고, 문서에서 추론해야 할 것도 없습니다.

누구를 위한 것이며 어떤 흐름에 맞는가

이는 Cursor나 Claude Code에서 생활하며 온체인 작업을 하는 개발자를 위한 것입니다. DeFi 프로토콜을 통합하거나, 결제 흐름을 구성하거나, 컨트랙트를 테스트하면서, 서명이 필요한 지점에서 멈추지 않고 에이전트가 실제로 트랜잭션을 실행하기를 원하는 사람입니다. 지금까지 에이전트에게 코드를 작성하게 한 뒤 온체인 부분은 직접 손으로 마무리해왔다면, 이 도구가 그 공백을 메워줍니다. 두 가지 흐름이 이 도구의 쓸모를 보여줍니다.

첫 번째는 빌드-테스트 루프입니다. 프로토콜과 통합하는 중이고, 에이전트가 코드를 작성했습니다. 실제로 작동하는지 확인하려면 누군가 실제 트랜잭션을 보내야 합니다. 컨트랙트에 자금을 채우고, 호출하고, 결과 상태를 확인하고, 조정하고, 다시 실행하는 과정입니다. 이를 직접 손으로 하면 모든 트랜잭션을 사용자가 승인하고 붙여넣어야 하는데, 이는 애초에 에이전트를 도입한 이유인 반복 작업 그 자체입니다. 세션을 사용하면 지갑을 생성하고, 소액을 채우고, 짧은 만료 시간으로 범위가 제한된 세션을 승인한 뒤, 에이전트가 전체 루프를 실행하도록 둘 수 있습니다. 에이전트는 트랜잭션을 보내고, 결과를 읽고, 반복하는 동안 사용자는 지켜보면 되며, 세션이 만료되면 접근 권한도 자동으로 종료됩니다.

두 번째는 여러 단계로 구성된 온체인 작업을 실행하는 에이전트입니다. 어떤 작업은 단일 호출이 아니라 일련의 순서로 이루어집니다. 메인넷에서 토큰을 스왑하고, 그 결과물을 L2로 브리지하고, 포지션에 예치하는 식입니다. 결과만 설명하고, 각 단계를 직접 실행하는 대신 에이전트가 세션을 통해 수행하도록 둘 수 있습니다. 세션은 에이전트가 얼마나 이동시킬 수 있는지가 아니라 어떤 기능을 얼마 동안 사용할 수 있는지를 제한하므로, 작업에 필요한 만큼만 지갑에 자금을 채우고, 짧은 만료 시간을 설정하고, 작업이 끝나면 취소하면 됩니다.

한계에 대한 솔직한 설명

돈을 다루는 도구는 만든 쪽이 한계가 어디인지 명확히 밝힐 때 더 신뢰하기 쉽습니다. 실제 운영 환경에서 이 도구를 사용하기 전에 알아둘 만한 몇 가지 한계가 있습니다.

가스 및 수수료 스폰서십 정책은 트랜잭션 수수료를 제어합니다. 지갑 지출 한도가 아니므로, Gas Manager 정책을 에이전트가 이동시킬 수 있는 금액의 상한선으로 취급해서는 안 됩니다. 스왑과 브리지는 현재 EVM 메인넷에서만 가능합니다. 세션 서명자는 EVM 원시 트랜잭션을 직접 서명하지 않으며, 동작은 wallet_prepareCalls, wallet_sendCalls과 같은 Alchemy Wallet API 호출을 통해 실행됩니다. 그리고 세션은 대시보드에서 설정한 만큼만 정확히 범위가 제한되므로, 사용자가 설정한 만료 시간과 기능이 실제 경계이지, 단순한 권고 사항이 아닙니다.

이 중 어느 것도 우회책이 아니며, 시스템이 원래 그렇게 작동하도록 설계된 것입니다. 지갑이 커스터디를 유지하고, 세션이 권한을 전달하며, 사용자는 언제든 종료할 수 있는 능력을 갖습니다.

시작하기

CLI의 에이전트 지갑은 현재 사용 가능하며, 대기 명단도, 별도 등급도 없습니다. Node 22 이상과 Alchemy 계정이 필요합니다. 세 개의 명령이면 에이전트가 제어할 수 있는 지갑을 갖추게 됩니다.

connect 단계는 대시보드를 열어주며, 여기서 세션을 승인하고 범위와 만료 시간을 설정합니다. 상태를 변경하는 워크플로를 실행하기 전에는 에이전트가 먼저 세션을 확인하도록 하세요.

작업이 끝나면 세션을 종료합니다.

온체인에서 가장 까다로운 제품을 만드는 팀들은 이미 Alchemy 위에서 운영하며, 100개 이상의 체인에서 연간 1조 달러가 넘는 자금을 이동시키고 있습니다. 에이전트 지갑의 핵심은 바로 이 인프라가 이제 코딩 에이전트에게 넘겨주는 지갑도 뒷받침한다는 점이며, 키를 넘기지 않고도 그렇게 할 수 있다는 것입니다. Cursor에 프라이빗 키를 붙여넣는 대신, 에이전트에게 범위가 제한된 세션을 주고 언제든 취소할 수 있는 능력을 유지할 수 있습니다.

에이전트 지갑 문서를 읽어보거나, 에이전트를 위한 Alchemy를 살펴보거나, CLI를 설치해서 직접 사용해보세요.

FAQ

프라이빗 키를 공유하지 않고 AI 코딩 에이전트에게 지갑을 주려면 어떻게 하나요?

Alchemy 대시보드에서 지갑을 생성한 다음, 터미널에서 alchemy wallet connect --mode session을 실행하세요. CLI가 로컬 키쌍을 생성하고, 대시보드가 범위가 제한되고 기간이 한정된 세션을 승인합니다. 에이전트는 그 세션을 통해 트랜잭션을 보내며, 프라이빗 키는 지갑 제공업체에 남아 있고 절대 노출되지 않습니다.

프라이빗 키는 실제로 어디에 저장되나요?

지갑의 프라이빗 키는 Alchemy의 임베디드 지갑 파트너인 Privy의 인프라에 보관됩니다. 사용자의 머신, 리포지토리, .env 파일에 기록되는 일이 없으며, CLI나 Alchemy 자체 시스템에도 닿지 않습니다. 에이전트는 키 자체가 아니라 승인된 세션을 통해 동작합니다.

에이전트의 지갑 접근 권한을 취소할 수 있나요?

네. Alchemy 대시보드에서 클릭 한 번으로 세션을 취소하거나, 터미널에서 alchemy wallet disconnect을 실행할 수 있습니다. 취소는 즉시 적용되며, 해당 세션의 다음 서명 시도는 거부됩니다. 세션은 승인할 때 설정한 시점에 자동으로 만료되기도 합니다.

에이전트 지갑으로 에이전트는 무엇을 할 수 있나요?

EVM 체인에서 에이전트는 네이티브 토큰과 ERC-20을 전송하고, 컨트랙트를 호출하고, 승인을 관리하고, 스왑하고, 메인넷 간 브리지를 할 수 있습니다. Solana에서는 SOL과 SPL 토큰을 전송할 수 있습니다. 트랜잭션은 Alchemy의 Wallet API를 통해 실행되므로 가스 스폰서십, 배칭, 재시도, ERC-20 가스 결제를 사용할 수 있습니다.

스폰서십 정책이 에이전트가 지출할 수 있는 금액을 제한하나요?

아닙니다. 가스 및 수수료 스폰서십 정책은 트랜잭션 수수료를 제어하는 것이지 지갑 잔액을 제어하는 것이 아닙니다. 지출 한도가 아닙니다. 에이전트가 할 수 있는 일에 대한 실제 경계는 대시보드에서 세션에 설정한 기능과 만료 시간이므로, 세션의 범위를 신중하게 설정해야 합니다.

시작하려면 무엇이 필요한가요?

Node 22 이상과 Alchemy 계정이 필요합니다. CLI의 에이전트 지갑은 대기 명단도 별도 등급도 없이 현재 사용 가능합니다. npm i -g @alchemy/cli@latest로 설치하고, alchemy auth를 실행한 다음, alchemy wallet connect --mode session으로 대시보드에서 세션을 승인하세요.