자금 이동 확인

자금을 이동하는 모든 도구는 미리 보기 후 실행 게이트를 거칩니다. 그 이유, 적용 범위, 그리고 단 하나의 예외를 설명합니다.

Agent에게 "100 USDC를 ETH로 스왑해 줘"라고 말하면, Agent는 즉시 실행하지 않습니다. 먼저 거래 내용이 담긴 확인 카드가 표시됩니다.

Sell: 100 USDC (Ethereum)
Buy:  ~0.0286 ETH (estimated, 0.5% slippage)
Route: Uniswap V3
Gas estimate: ~$1.20

내용을 확인하고 의도와 일치한다고 판단하면 수락합니다. 그 이후에야 Agent가 트랜잭션을 브로드캐스트합니다.

Agent가 즉시 실행하지 않는 이유는 무엇인가요? LLM은 잘못 읽는 경우가 있기 때문입니다. "100 USDC"가 "1000 USDC"가 될 수도 있고, 입력한 주소의 문자 하나가 달라질 수도 있으며, 체인이 Ethereum에서 Base로 조용히 바뀔 수도 있습니다. 한번 브로드캐스트된 트랜잭션은 되돌릴 수 없습니다. 따라서 모든 자금 이동 도구는 구조적으로 2단계, 즉 미리 보기 후 실행 방식으로 동작합니다.

계약

자금을 이동하는 모든 도구는 ToolEntry에 controlPolicy.confirm을 선언합니다. 제어 정책 게이트는 도구 호출 거부 지점에서 미리 보기를 실행하고 동의를 수집한 뒤, 실행 전용 핸들러로 넘깁니다. 이는 하네스가 강제하며, 프롬프트 수준도 핸들러 내부도 아닙니다.

하드 제약을 사용하는 이유는 무엇인가요? LLM은 프롬프트 인젝션, 악의적인 스킬의 교묘한 조작, 또는 LLM이 명령으로 해석하는 적대적인 도구 결과로 인해 프롬프트 수준 규칙을 "잊을" 수 있습니다. 모델은 동작 파라미터로 도구를 한 번만 호출합니다. 확인 증거가 없으면 게이트는 미리 보기 봉투를 반환하며, 트랜잭션은 발생하지 않습니다. 클라이언트가 카드를 렌더링합니다. 모델은 미리 보기를 보지 않으며, 두 번째 도구 호출도 없습니다.

정책은 tool-control-policy.ts에 있습니다. 이를 해석하는 훅은 tier-gate.ts에 있습니다. 새로운 자금 이동 도구는 반드시 controlPolicy.confirm을 선언해야 하며, 이를 누락한 PR은 코드 리뷰에서 거부됩니다. 확인 경로가 없는 자금 이동 항목은 fail-closed 됩니다.

적용 대상 도구

툴 레지스트리에서 isFundMoving: true로 표시된 도구들입니다. 목적별로 분류하면 다음과 같습니다.

토큰 거래

swap_tokens, 체인 간 DEX 스왑
buy_token / sell_token, 명시적 매수 / 매도
transfer_token, 지갑에서 주소로 전송

무기한 선물

open_perps_position / close_perps_position
minara_perps_wallet_sweep, 서브 계정 간 잔액 이동
minara_perps_wallet_transfer, 무기한 선물 잔액 전송
minara_wallet_fund_perp, 현물에서 무기한 선물 계정으로 자금 이동 (USDC 입금)

Autopilot, 자율 거래 활성화 또는 비활성화

minara_autopilot_enable / minara_autopilot_disable

Autopilot 토글은 자금 이동에 해당합니다. 활성화하는 것이 곧 운영자가 Agent에게 자율 거래를 허가하는 순간이기 때문입니다. 활성화 이후 개별 Autopilot 거래는 해당 권한을 상속하므로, 거래마다 재확인을 요구하지 않습니다.

워크플로

workflow_activate / workflow_deactivate

동일한 원칙입니다. 워크플로를 활성화하는 것이 "이 자동화가 자체적으로 실행되도록 승인한다"는 순간입니다.

Strategy Studio, 자신의 전략

strategy-codegen 스킬의 deploy.sh

배포는 일회성 권한 부여입니다. 자세한 내용은 아래 전략 배포는 일회성 권한 부여를 참조하십시오.

다른 크리에이터의 전략을 라이브로 실행

minara_top_strategies_apply_start, 추천 Top Strategies 전략 실행

이 동작들은 사용자의 자금으로 자율 거래를 시작하거나 중지하며, 작성 시점의 별도 승인 순간이 없습니다. 따라서 Autopilot과 동일한 확인 게이트를 거칩니다 (apply_start / sub_start는 MANUAL_ONLY, sub_stop은 ALWAYS_CONFIRM).

직접 거래소 주문 실행

모든 hyperliquid_* 주문 / 취소 / 출금 엔드포인트

새로운 자금 이동 도구를 추가할 때는 isFundMoving: true로 표시하고 controlPolicy.confirm을 선언하십시오. 누락하면 코드 리뷰에서 PR이 차단됩니다.

실제 흐름

Agent 호출부터 수락까지:

LLM: swap_tokens({
  sell_token: "USDC",
  sell_amount: 100,
  buy_token: "ETH",
  chain: "ethereum"
})

→ 게이트: 확인 증거 없음
→ 선언된 preview(시뮬레이션)를 실행하고 minara-confirm 봉투로 차단
→ 클라이언트가 미리 보기 카드를 렌더링. 모델은 보지 않음

카드에서 수락

→ 같은 호출이 실행 전용 핸들러로 진행
→ 핸들러가 서명하고 브로드캐스트
→ {tx_hash: "0x...", executed: true} 반환

호출자가 넘긴 confirm: true는 대화형 동의 증거로 여전히 인정됩니다. 검사는 느슨합니다(true, "true", 1, "yes", "on"). 일부 도구 호출 프로토콜이 boolean을 문자열로 바꾸기 때문입니다. UI 경로는 모델이 그 플래그를 넘기는 데 의존하지 않습니다.

전략 배포는 일회성 권한 부여

전략 배포는 다르게 작동합니다. strategy-codegen 스킬의 deploy.sh는 배포 시점에 한 번의 2단계 확인을 수행합니다. --confirm 없이 실행하면 전체 배포 미리 보기(심볼, 캔들 주기, 레버리지, 서브 계정, 낙폭 한도)만 출력합니다. 이를 확인하고 한 번 결정한 뒤, 같은 명령을 --confirm과 함께 다시 실행합니다.

이후 전략의 라이프사이클 스크립트인 start.sh, stop.sh, reconfig.sh도 각각 동일한 "미리 보기 → --confirm" 2단계를 수행하며, stop은 기본적으로 미결제 포지션을 시장가로 청산합니다. 이 스크립트들은 이미 승인된 전략에 대한 스케줄링 작업이며, 새로운 자금 이동이 아닙니다.

다른 크리에이터의 전략을 실행하는 경우는 다릅니다. 작성 시점의 승인이 없으므로, Top Strategies의 minara_top_strategies_apply_start는 Autopilot 활성화와 동일하게 확인 게이트를 거칩니다.

이 예외를 두는 이유는 무엇인가요? 알고리즘 거래마다 사람의 확인이 필요하다면, 그 전략은 수동 매매 스크립트와 다를 바 없습니다. Strategy Studio의 목적은 사전에 설정한 제약 안에서 권한을 위임하는 것입니다. 배포는 운영 범위를 승인하는 순간이며, 이후 전략은 배포 구성에 설정된 낙폭 한도, 배분 한도, 심볼 허용 목록에 의해 제한됩니다. 거래마다 프롬프트를 띄우지 않습니다.

이 예외는 Strategy Studio에만 적용됩니다. 다른 도구에서 이 패턴을 모방하지 마십시오. 나머지 도구 영역은 통합 확인 게이트를 사용합니다.

`MINARA_SKIP_FUND_CONFIRM`, 운영자 수준 우회

비대화형 환경을 위한 단 하나의 예외 경로가 있습니다. 환경 변수 MINARA_SKIP_FUND_CONFIRM=1(또는 설정 safety.skipFundConfirm)을 켜면 확인 게이트가 해당 호출을 이미 증거 있는 것으로 취급합니다. 사용이 적절한 경우와 그렇지 않은 경우는 다음과 같습니다.

합리적인 사용 사례 (극히 일부의 정당한 경우):

백테스트. 호출자는 Python 하네스이고, 미리 보기를 읽을 사람이 없으며, 실행 자체가 과거 데이터에 대한 샌드박스 환경입니다.
워크플로 엔진 실행. 워크플로는 활성화 시점에 이미 승인되었습니다. 실행 루프는 승인된 워크플로를 디스패치하는 것이며, 사용자에게 각 단계를 재확인하는 것이 아닙니다.
CI 스모크 테스트. 자금 이동 경로를 구동하고 실제 호출을 검증하는 것이 목적입니다.

절대 사용하지 말아야 할 경우:

대화형 REPL 세션. 사용자를 보호하는 마지막 방어선을 우회하는 것입니다.
"프로덕션 서버에서 매번 확인하는 것이 불편해서". 이는 안전 기능을 끄는 것입니다.
셸 rc 파일. export MINARA_SKIP_FUND_CONFIRM=1을 .zshrc에 추가하고 잊어버리지 마십시오. 다음 번에 Agent를 시작하면 무방비 상태로 실행됩니다.

전체 환경 변수 참조는 환경 변수 → MINARA_SKIP_FUND_CONFIRM에서 확인하십시오.

Layer 3 vs Layer 4, 각각 무엇을 감지하는가

가장 흔한 혼동은 게이트가 Layer 3(이 페이지)인지 Layer 4(스크립트 위험 게이트)인지입니다. 빠른 참조 표:

Agent에게 요청한 내용	감지 계층
"100 USDC를 ETH로 스왑해 줘", 직접 거래 요청	Layer 3, 제어 정책 게이트가 미리 보기 후 확인
`subprocess.run(["minara","swap",…])`를 포함한 Python 스크립트 실행	Layer 4, 스크립트 위험 게이트가 자금 이동 CLI를 감지하고 YELLOW 프롬프트 표시
`terminal`에서 `cast send 0x… 1ether` 실행	Layer 4, 게이트가 쉘 명령을 검사하고 YELLOW 프롬프트 표시
파일 수정 후 내용에 `minara swap`이 포함된 경우	Layer 4, 게이트가 적용 후 내용을 스캔하고 YELLOW 프롬프트 표시
codegen 스킬의 `deploy.sh`를 통한 전략 배포	스크립트 수준 2단계 확인, `--confirm` 없이는 미리 보기만, 붙이면 실행, 백엔드 리스크 계층이 뒷받침

요약하면 다음과 같습니다. Layer 3는 Agent의 직접 자금 이동 도구 호출을 감지하고, Layer 4는 Agent가 실행하는 스크립트와 명령 안의 자금 이동 코드를 감지합니다. 두 계층은 동일한 위협의 서로 다른 부분을 담당하며 병렬로 작동합니다.

운영자 체크리스트

✅ 미리 보기가 표시되면 반드시 읽으십시오. 목적지, 체인, 금액, 슬리피지가 요청한 내용과 일치하는지 확인하십시오. 2단계 확인은 사용자 본인의 실수도 잡아낼 수 있도록 존재합니다.
✅ 전략을 배포할 때는 배포 구성을 꼼꼼히 검토하십시오. 확인을 요청받는 것은 이 순간뿐입니다.
✅ 워크플로를 활성화할 때는 워크플로 정의를 처음부터 끝까지 읽은 후 승인하십시오. 이후 해당 워크플로 실행 시에는 재확인을 요청하지 않습니다.
❌ 대화형 REPL 세션에서 MINARA_SKIP_FUND_CONFIRM=1을 설정하지 마십시오. .zshrc 또는 .envrc에 추가하지 마십시오.
❌ 읽지 않은 미리 보기를 수락하지 마십시오. 확인은 사용자의 판단이며, Agent의 역할이 아닙니다.

계약