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

주기적인 MEMORY.md 통합입니다.

  • 제어 대상: on이면 setInterval 작업이 WORKSPACE_DREAM_INTERVAL_HOURS마다 깨어나 memory/에서 최근 일일 로그를 읽고, 활성 LLM에게 지속적인 fact / preference / decision을 추출하도록 요청합니다. 결과는 MEMORY.md에 추가되는 ## Dreamed YYYY-MM-DD 섹션으로 기록됩니다(추가 전용이며 사용자 편집은 절대 덮어쓰지 않음). 자동화 출처의 저널 턴은 디스크에서 감사 가능한 상태로 유지되지만 LLM 프롬프트 전에 제거되므로, Autopilot, strategy, workflow, 또는 알 수 없는 perps 실행이 사용자 preference가 될 수 없습니다.
  • When to enable: 운영자가 수동 큐레이션 없이 단기 로그에서 장기 메모리가 진화하기를 원하는 장기 실행 배포를 위한 것입니다. LLM 호출 비용이 들므로 비용에 민감한 컨텍스트에서는 off로 두세요.
  • 미설정 시: OFF.
  • 형식: 1/true/yes/on이면 활성화합니다.
  • 설정 위치: 설정 → 환경설정 (schema 키)

WORKSPACE_DREAM_INTERVAL_HOURS

dream 통합 주기입니다.

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

WORKSPACE_DREAM_TOTAL_INPUT_BYTES

dream 프롬프트 입력(모든 일일 로그를 합친)에 대한 전역 바이트 예산입니다.

  • 제어 대상: 한 번의 dream 패스에서 LLM으로 전송되는 총 바이트를 제한합니다. 일일 로그는 예산 범위 내에서 최신 항목이 먼저 오는 연속된 접미사로 유지되므로, 모델은 항상 가장 최근 활동을 포함한 시간순으로 연속된 조각을 봅니다. 이는 밀도 높은 로그의 긴 윈도우가 모델의 컨텍스트 윈도우를 넘어서는 것을 방지합니다. 파일별 내용은 여전히 64 KB(파일별 cap)로 끝부분이 잘리며, 가장 최근 로그는 단독으로 이 예산을 초과하더라도 항상 유지됩니다. WORKSPACE_DREAM_ENABLED가 off이면 효과가 없습니다.
  • 미설정 시: 262144 (256 KB).
  • 형식: 양의 정수(바이트 단위).
  • 설정 위치: 사용자 대상 설정 아님

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_TOTAL_INPUT_BYTESWORKSPACE_DREAM_LOCK_TTL_MSREPORT_BUNDLE_CHART_PNGSWALLET DEPOSIT WATCHWALLET_DEPOSIT_WATCH_ENABLEDALCHEMY_API_KEYALCHEMY_NETWORKARBITRUM_RPC_URLSOLANA_RPC_URLDEPOSIT_WATCH_TIMEOUT_MS