MINARA
참조환경 변수

x402 페이월 사전 승인

x402 페이월 사전 승인 (PR-X)

이 변수들은 "세션 수준 사전 승인" 기능의 범위를 한정합니다. 이 기능은 운영자가 주어진 스코프에 대해 x402 페이월 결제를 한 번 승인하면, 만료 / 예산 소진 / 명시적 취소 전까지 자동 결제(호출별 확인 없음)하도록 합니다. 승인(grant) 호출 자체는 항상 통합 확인 게이트를 거칩니다. 세션 행이 안착된 후에는, 세션 스코프와 일치하는 창 내 x402 결제가 호출별 사용자 프롬프트를 건너뛰고 transfer_token 을 통해 직접 실행됩니다. 모든 자동 지출은 감사 메타데이터(세션 id + 남은 예산)를 기록하므로 사용자가 각 청구를 추적할 수 있습니다. 연결 위치: - src/minara/x402-preauth-store.ts (SQLite 스토어 + 상한 계산) - src/minara/x402-preauth-config.ts (env 로더 + 상한 헬퍼) - src/tools/_shared/confirm.ts (shouldAutoExecuteX402) - src/tools/trade.ts (transfer_token 이 자동 실행 경로를 참조하고, 미일치 결제는 통합 확인 게이트에 남음) - src/tools/x402-preauth.ts (LLM 호출 가능 grant / list / revoke) - src/gateway/repl-commands.ts (/x402 preauth CLI 표면)

X402_PREAUTH_DEFAULT_TTL_HOURS

사용자 / LLM이 지정하지 않을 때의 기본 세션 만료 시간입니다.

  • 제어 대상: x402_preauth_grant가 ttl_hours 없이 호출될 때 적용되는 TTL입니다.
  • 사용처: src/minara/x402-preauth-config.ts.
  • 설정 시점: grant를 단기로 유지하려면 줄이고(예: 4 = 4h), 장기 실행 배치 작업에 더 여유를 주려면 늘리세요.
  • 미설정 시: 24시간.
  • 형식: 양의 정수(시간 단위).
  • 설정 위치: 사용자 대상 설정 아님

X402_PREAUTH_MAX_TTL_HOURS

forever가 아닌 세션 TTL의 강제 상한입니다.

  • 제어 대상: ttl_hours > this value인 grant 요청은 field: "ttlMs"로 거부됩니다. cap 헬퍼가 LLM tool, REPL 명령, 직접 store 접근 전반에 걸쳐 이를 균일하게 적용합니다.
  • 설정 시점: 운영자 신뢰 기간을 더 짧게 강제하려면 줄이고, 장기 세션이 배포 요구사항일 때만 늘리세요.
  • 미설정 시: 168 (7일).
  • 형식: 양의 정수(시간 단위).
  • 설정 위치: 사용자 대상 설정 아님

X402_PREAUTH_ALLOW_FOREVER

ttl_hours: "forever"(시간 기반 만료 없음) grant를 허용할지 여부입니다.

  • 제어 대상: 0이면 LLM tool + REPL + store가 forever-grant 요청을 field: "forever"로 거부합니다. forever-budget cap은 문서화를 위해 여전히 읽히지만 도달할 수 없습니다. 모든 grant에 강제로 만료 한도를 두려는 환경(audit / compliance)에서는 0으로 설정하세요.
  • 미설정 시: 1(forever grant 허용, REPL에서 사용자의 명시적 이중 확인으로 게이트되며 LLM은 forever를 자동으로 제안하지 않음).
  • 형식: 1/true/yes/on(허용) 또는 0/false/no/off.
  • 설정 위치: 사용자 대상 설정 아님

X402_PREAUTH_MAX_PER_CALL_USDC

자동 결제되는 단일 x402 결제의 강제 상한입니다(USDC).

  • 제어 대상: (a) LLM tool + REPL이 per_call_cap_usdc > this value인 grant를 거부합니다. (b) shouldAutoExecuteX402는 이 금액을 초과하는 단일 결제에 대해 amount_over_cap으로 단락되어 일반적인 2단계 확인으로 폴백합니다. 이것이 가장 중요한 단일 안전 한도로, 사용자가 기존 세션 안에서 더 높은 cap을 부여했더라도 잘못된 paywall 하나가 빼낼 수 있는 금액을 제한합니다.
  • 설정 시점: 공유 인프라에서는 호출당 피해 범위를 제한하려면 줄이세요. paywall이 정당하게 더 비쌀 때만 늘리세요.
  • 미설정 시: 0.5 (USDC).
  • 형식: 양수(USDC).
  • 설정 위치: 사용자 대상 설정 아님

X402_PREAUTH_MAX_BUDGET_USDC

forever가 아닌 세션의 총 예산 강제 상한입니다(USDC).

  • 제어 대상: total_budget_usdc > this이면서 ttl_hours가 non-null인 grant 요청은 거부됩니다. forever-grant 예산은 아래의 별도(보통 더 엄격한) cap을 사용합니다.
  • 미설정 시: 5 (USDC).
  • 형식: 양수(USDC).
  • 설정 위치: 사용자 대상 설정 아님

X402_PREAUTH_MAX_FOREVER_BUDGET_USDC

forever 세션의 총 예산 강제 상한입니다(USDC).

  • 제어 대상: MAX_BUDGET_USDC와 형태가 같지만 ttl_hours: "forever"일 때만 적용됩니다. 시간 제한을 없애면 더 엄격한 금액 통제가 필요하므로 독립적입니다. forever 예산은 시간 제한 예산보다 높거나 낮을 수 있으며 운영자가 선택합니다. 기본값이 더 높게 설정된 이유는 forever grant가 보통 호출당 소액이면서 여러 달에 걸쳐 누적되기 때문입니다("$0.01/call x 2000 calls").
  • 미설정 시: 20 (USDC).
  • 형식: 양수(USDC).
  • 설정 위치: 사용자 대상 설정 아님

X402_PREAUTH_DISABLE

전역 kill 스위치입니다.

  • 제어 대상: 1이면 모든 preauth 코드 경로가 단락됩니다. transfer_token은 x402_context를 무시하고, LLM tool은 disabled 오류를 반환하며, REPL은 "x402 preauth disabled by env"를 출력하고 grant를 거부합니다. 모든 x402 결제는 일반적인 2단계 확인 플로우로 폴백합니다.
  • 설정 시점: 인시던트 대응(폭주 의심 paywall), 모든 결제를 사용자의 명시적 확인과 함께 기록해야 하는 compliance audit 기간, 또는 이 기능을 전혀 원하지 않는 운영자를 위한 것입니다.
  • 미설정 시: 0(preauth 메커니즘 활성).
  • 형식: 1/true/yes/on이면 비활성화하고, 그 외 값(기본값)은 활성 상태로 유지합니다.
  • 설정 위치: 사용자 대상 설정 아님

OpenClaw 워크스페이스 통합

에이전트는 ~/.minara/workspace/(--workspace 로 재정의)에 있는 워크스페이스 디렉터리를 읽고 씁니다. 이 디렉터리에는 OpenClaw 의 AGENTS.default 스키마를 본뜬 마크다운 파일이 들어 있습니다: SOUL.md (정체성), AGENTS.md (규칙), IDENTITY.md, USER.md, MEMORY.md (선별된 장기 기억), HEARTBEAT.md (세션 간 메모), BOOTSTRAP.md (최초 실행 전용), 그리고 memory/YYYY-MM-DD-*.md (일일 로그). 템플릿은 src/workspace/templates/ 아래에 제공됩니다. minara setup 이 최초 실행 시 이를 시드합니다. 시드는 멱등적이며 사용자가 이미 편집한 파일을 절대 덮어쓰지 않습니다.

WORKSPACE_HEARTBEAT_ENABLED

턴마다 HEARTBEAT.md 상태를 기록하는 라이터입니다.

  • 제어 대상: on이면 매 턴 이후 에이전트가 <workspace>/HEARTBEAT.md에 last_seen, session_id, surface, turn_count, last_user_query와 응답에서 추출한 휴리스틱 open_loops를 기록합니다. 라이터는 사용자가 편집한 ## Schedule 섹션을 여러 번의 쓰기에 걸쳐 그대로 보존합니다.
  • When to disable: 읽기 전용 workspace 마운트, CI 실행, 세션 메모를 디스크에 남기고 싶지 않은 프라이버시 민감 컨텍스트를 위한 것입니다.
  • 미설정 시: ON.
  • 형식: 0/false/no/off이면 비활성화하고, 그 외 값(기본값)은 활성 상태로 유지합니다.
  • 설정 위치: 설정 → 환경설정 (schema 키)

WORKSPACE_DAILY_LOG_ENABLED

세션별 일일 로그를 추가합니다.

  • 제어 대상: on이면 각 주기마다 내구성 있는 SQLite 워터마크 이후의 저널링되지 않은 모든 chat_turns 행을 <workspace>/memory/YYYY-MM-DD-<session>.md로 플러시합니다. 행은 실제 session id, surface, runtime source를 유지하며, correlation id는 session id로 절대 사용되지 않습니다. 세션별 파일은 다중 프로세스 추가 경쟁을 방지합니다.
  • When to enable: 에이전트가 나중에 MEMORY.md로 승격할 수 있는 작업 메모리를 축적하기를 원하는 장기 실행 배포를 위한 것입니다.
  • 미설정 시: OFF(명시적으로 opt-in할 때까지 workspace는 작게 유지됩니다).
  • 형식: 1/true/yes/on이면 활성화합니다.
  • 설정 위치: 설정 → 환경설정 (schema 키)

WORKSPACE_DAILY_LOG_INTERVAL

일일 로그 추가 사이의 턴 수입니다.

  • 제어 대상: 위 chat_turns 백로그를 플러시하는 주기입니다. 예정된 플러시마다 워터마크 이후의 모든 행을 기록하므로, 간격을 늘리면 영속화가 지연될 뿐 중간 턴을 샘플링하거나 버리지 않습니다.
  • 미설정 시: 5턴.
  • 형식: 양의 정수.
  • 설정 위치: 사용자 대상 설정 아님

WORKSPACE_DREAM_ENABLED

WORKSPACE_DREAM_ENABLED: 개인 메모리 요약을 주기적으로 저장합니다.

  • 제어 대상: 공유 개인 메모리 처리를 갱신한 뒤 선택한 활성 사실을 최대 20개까지 MEMORY.md의 생성 블록에 저장합니다. 한도는 12 KB이며, 비밀 키와 지갑 주소로 보이는 내용은 제외하고 수정과 삭제를 반영합니다. 블록 밖의 직접 작성한 내용은 유지하고 기존 생성 섹션은 교체 전에 보관합니다. 일일 로그를 읽거나 활성화할 필요가 없습니다.
  • When to enable: 작업 공간에서 메모리 요약을 읽으려면 활성화하세요. 대상이 되는 새 대화가 있으면 일반 추출 및 검토 처리를 실행합니다. 파일 저장 자체는 모델을 호출하지 않습니다.
  • 미설정 시: OFF.
  • 형식: 1/true/yes/on으로 활성화합니다.
  • 설정 위치: 설정 → 환경설정 (schema 키)

WORKSPACE_DREAM_INTERVAL_HOURS

dream 통합 주기입니다.

  • 제어 대상: dreaming 실행 사이의 간격(시간 단위)입니다. 이전 실행이 아직 진행 중이면 스케줄러가 tick을 건너뛰므로 느린 LLM 호출이 쌓이지 않습니다. WORKSPACE_DREAM_ENABLED가 off이면 효과가 없습니다.
  • 미설정 시: 24(하루에 한 번 통합 패스).
  • 형식: 양수(시간 단위, 소수 가능).
  • 설정 위치: 사용자 대상 설정 아님

WORKSPACE_DREAM_LOCK_TTL_MS

dream lockfile의 TTL입니다.

  • 제어 대상: <workspace>/.dreaming.lock 파일이 오래된 것으로 간주되어 다른 프로세스가 회수할 수 있게 되기 전까지 얼마나 오래 유효한지를 정합니다. 패스 사이의 간격이 아니라 단일 dream 패스(LLM 호출 + IO)의 합리적인 최대 소요 시간을 반영해야 합니다. 이 lock은 tick 윈도우가 겹칠 때 REPL과 HTTP gateway가 MEMORY.md의 생성 블록을 동시에 갱신하는 것을 방지합니다. NFS workspace는 지원되지 않으며(기반이 되는 O_EXCL 시맨틱이 모든 NFS 클라이언트에서 원자적이라고 보장되지 않음), dreaming은 단일 호스트에서 유지하세요. WORKSPACE_DREAM_ENABLED가 off이면 효과가 없습니다.
  • 미설정 시: 1800000 (30분).
  • 형식: 양의 정수(밀리초 단위).
  • 설정 위치: 사용자 대상 설정 아님

REPORT_BUNDLE_CHART_PNGS

deep-research HTML / PDF 리포트에서 인터랙티브 ECharts 대신 PNG로 번들된 차트로 폴백합니다.

  • 제어 대상: 설정하면 gateway의 deep-research 분기가 renderDeepResearchReport에 ["html", "pdf", "charts"]를 전달하여 bundleChartPngs가 실행되고, HTML이 각 chart://<id>를 정적 <img src="charts/<id>.png"> 태그로 임베드합니다(headless playwright로 서버 사이드 렌더링). 설정하지 않으면(v7 이후 기본값) gateway는 ["html", "pdf"]만 전달하고 모든 chart:// 링크가 표준 ECharts 임베드 패턴(<div class="echart-host"> + 인라인 <script>, echarts CDN에서 하이드레이션)으로 확장됩니다. 기본값은 zoom + tooltip + saveAsImage PNG 다운로드가 있는 인터랙티브 차트를 생성합니다.
  • 이를 소비하는 skill / tool: deep-research 파이프라인(src/gateway/api.ts handleChatStream deep-research 분기).
  • When to set it: 리포트를 오프라인 배포용으로 내보내는(echarts CDN에 접근할 수 없는) 운영자, 또는 열 때 ~120 KB CDN 스크립트가 가져와지는 것을 허용할 수 없는 운영자를 위한 것입니다. 트레이드오프: PNG로 번들된 차트는 정적이며 zoom, tooltip, PNG 다운로드 버튼이 없습니다. 차트 구체화가 실행되도록 headless playwright가 설치되어 있어야 합니다(이미 프로젝트 의존성).
  • 미설정 시: 인터랙티브 ECharts(CDN 하이드레이션). 차트를 보려면 네트워크 접근이 가능한 브라우저에서 HTML을 여세요. 오프라인 차트는 임베드 스크립트의 try/catch에 따라 작은 "chart unavailable" 플레이스홀더로 저하됩니다.
  • 형식: 1 / true(활성화). 그 외 값이나 미설정은 비활성화합니다.
  • 설정 위치: 설정 → 환경설정 (schema 키)

WALLET DEPOSIT WATCH

실시간 입금 감지 SSE 엔드포인트 (POST /v1/wallet/deposits/watch). perps USDC/Arbitrum 주소에 대해 Portfolio DepositModal 의 그린-플립을 구동합니다. 두 가지 체인 트랜스포트가 있으며, 에이전트가 부팅 시 선택합니다: 1. Alchemy (선호) — ALCHEMY_API_KEY 설정. 실제 mempool 관측을 위해 alchemy_getAssetTransfers(수신 전송 전용 쿼리) + alchemy_pendingTransactions WS 구독을 사용합니다. 무료 등급: 월 300M CU. 2. Public RPC 폴백 — ALCHEMY_API_KEY 가 없을 때. 입금 주소로 필터링된 USDC Transfer 이벤트를 위해 5초마다 eth_getLogs 를 폴링합니다. mempool 가시성 없음(이 모드에서는 pending 이벤트가 방출되지 않음). 제어 대상: WALLET_DEPOSIT_WATCH_ENABLED — SSE 엔드포인트의 마스터 스위치. dev 에서는 기본 ON 이라 기능이 즉시 동작합니다. 깔끔하게 비활성화하려면 false / 0 으로 설정하세요. off 이면 web-ui 의 DepositStatus pill 이 "Live updates unavailable" 를 표시하고, 사용자는 여전히 주소를 정상적으로 복사할 수 있습니다. 소비하는 스킬 / 도구: apps/agent/src/wallet-watch/* 와 api.ts handleWalletDepositsWatch 핸들러.

WALLET_DEPOSIT_WATCH_ENABLED

WALLET_DEPOSIT_WATCH_ENABLED=true

  • 설정 위치: 설정 → 환경설정 (schema 키)

ALCHEMY_API_KEY

Arbitrum용 Alchemy API 키입니다. 하나의 키가 모든 Alchemy 체인에서 작동합니다. 선택 사항이며, 없으면 watcher가 공용 Arbitrum RPC로 폴백합니다(mempool 감지 없음). ALCHEMY_API_KEY=abc123...

  • 설정 위치: 설정 → API 키

ALCHEMY_NETWORK

Alchemy 네트워크 enum 문자열입니다. arb-mainnet이 현재 우리가 신경 쓰는 유일한 값입니다(perps 지갑 입금 = Arbitrum의 USDC). end-to-end QA를 위해 ALCHEMY_API_KEY를 테스트넷으로 지정하는 경우에만 재정의하세요. ALCHEMY_NETWORK=arb-mainnet

  • 설정 위치: 사용자 대상 설정 아님

ARBITRUM_RPC_URL

공용 Arbitrum RPC URL — ALCHEMY_API_KEY가 미설정일 때 사용됩니다.

  • 기본값: https://arb1.arbitrum.io/rpc (Arbitrum Foundation).
  • 운영자는 확인 후 감지만 필요하다면 Alchemy를 활성화하지 않고
  • 유료 HTTPS 엔드포인트로 교체할 수 있습니다.
  • ARBITRUM_RPC_URL=https://arb1.arbitrum.io/rpc
  • 설정 위치: 사용자 대상 설정 아님

SOLANA_RPC_URL

공용 Solana RPC URL — spot 입금 watcher가 Solana 체인에 사용합니다. Non-EVM이라 Alchemy가 자동 연결되지 않으며, 이 URL을 먼저 시도한 뒤 foundation 등급 공용 목록(api.mainnet-beta.solana.com, solana-rpc.publicnode.com, …)을 순서대로 시도합니다. 트랜스포트는 사용자의 USDC 토큰 계정에서 getSignaturesForAddress를 5초마다 폴링하고 confirmed commitment에서 credited로 전환합니다.

DEPOSIT_WATCH_TIMEOUT_MS

watch 세션이 자동 종료되기 전까지 유지되는 시간(ms)입니다. 기본값 20분으로, 느린 체인 확인에는 충분히 길지만 열어둔 채 잊힌 모달의 리소스 사용을 제한합니다. DEPOSIT_WATCH_TIMEOUT_MS=1200000

  • 설정 위치: 사용자 대상 설정 아님

백테스팅 피드백 루프

백테스팅 피드백 루프 (Sprint 6 — online outcome filler)

숏컷 질문

숏컷 질문 (Chat 랜딩 페이지)

목차

X402_PREAUTH_DEFAULT_TTL_HOURSX402_PREAUTH_MAX_TTL_HOURSX402_PREAUTH_ALLOW_FOREVERX402_PREAUTH_MAX_PER_CALL_USDCX402_PREAUTH_MAX_BUDGET_USDCX402_PREAUTH_MAX_FOREVER_BUDGET_USDCX402_PREAUTH_DISABLEOpenClaw 워크스페이스 통합WORKSPACE_HEARTBEAT_ENABLEDWORKSPACE_DAILY_LOG_ENABLEDWORKSPACE_DAILY_LOG_INTERVALWORKSPACE_DREAM_ENABLEDWORKSPACE_DREAM_INTERVAL_HOURSWORKSPACE_DREAM_LOCK_TTL_MSREPORT_BUNDLE_CHART_PNGSWALLET DEPOSIT WATCHWALLET_DEPOSIT_WATCH_ENABLEDALCHEMY_API_KEYALCHEMY_NETWORKARBITRUM_RPC_URLSOLANA_RPC_URLDEPOSIT_WATCH_TIMEOUT_MS