환경 변수

이 페이지에서는 minara-agent-v2가 환경 변수를 로드하는 규약과 새 환경 변수를 도입할 때 필요한 단계를 설명합니다. 모든 변수의 기본값, 형식, 소비 파일, 미설정 시 문제점 등 변수별 참조 정보는 참조 → 환경 변수를 확인하십시오.

정식 템플릿은 프로젝트 루트의 .env.example에 있습니다. 이 파일을 두 페이지 모두와 동기화하여 유지하십시오.

MINARA_는 Minara 플랫폼 전용 변수(MINARA_API_KEY, MINARA_BASE_URL, MINARA_SKIP_FUND_CONFIRM, MINARA_DATA_DIR, MINARA_OPENAI_BASE_URL, MINARA_OPENAI_CHAT_PATH)를 위해 예약되어 있습니다. 에이전트 루프 인프라 변수(게이트웨이, 로그, 모델, 시나리오, 메모리 조정값)에는 이 접두사를 사용하지 않습니다.

사용자에게 보이는 스위치는 Settings(settings.json#preferences)에 저장합니다. 시크릿은 credentials.json(설정 → API Keys / Messaging)에 저장합니다. 호출부는 prefs.get / secrets.* / infra.get으로 읽습니다. Env는 부팅 시 운영 계층이자, 덮어쓰기 체인에 문서화된 폴백입니다.

TL;DR 규약

API 키, 시크릿, 토큰, 또는 재정의 가능한 URL이 필요한 새 스킬 또는 도구는 다음을 반드시 따라야 합니다.

1. 올바른 저장소에 쓰고, façade로 읽습니다. 시크릿은 API-key / messaging 레지스트리와 secrets.dataSource / secrets.messaging입니다. 사용자 스위치는 preferences schema와 prefs.get입니다. 운영 인프라(GATEWAY_PORT, MINARA_DATA_DIR)는 config/infra/schema.ts와 infra.get입니다. 시크릿을 하드코딩하지 마십시오. CLI 인수로 받아 에코하는 방식도 사용하지 마십시오.

2. 같은 커밋에 apps/agent/src/config/env-docs/에 문서화된 항목을 추가한 뒤 .env.example을 재생성합니다. 항목에는 다음 내용이 포함되어야 합니다. 제어 대상, 소비하는 스킬/도구, 운영자가 설정하는 시점, 미설정 시 기본 동작, 허용 값 형식. 한 줄 스텁(# FOO_KEY=)은 허용되지 않습니다.

3. 도메인 스킬(apps/agent/src/skills/builtin/*.ts 또는 apps/agent/src/skills/external/<id>/)의 경우 requires_env에 변수를 선언하여 자격 증명이 없을 때 SkillRegistry가 스킬을 완전히 숨기도록 합니다.

   export const myNewSkill: DomainSkill = {
     id: "research.my_provider",
     // ...
     requires_env: ["MY_PROVIDER_API_KEY"],
   };

4. 도구(apps/agent/src/tools/*.ts)의 경우 시크릿이 없을 때 팩토리가 빈 ToolEntry[]를 반환해야 합니다. 툴 레지스트리는 등록되지 않은 이름을 자동으로 제외하므로, 다운스트림 스킬의 tool_names 참조는 자연스럽게 저하됩니다.

   export function createMyProviderTools(): ToolEntry[] {
     const apiKey = secrets.dataSource("MY_PROVIDER_API_KEY");
     if (!apiKey) return [];
     // ...
   }

5. 실제 시크릿을 커밋하지 마십시오. .env는 git에서 무시되며, .env.example이 빈 값으로 커밋되는 공식 템플릿입니다.

.env 로딩 방법

로딩은 apps/agent/src/config/load-env.ts가 처리합니다. 이 모듈은 Node 22의 내장 process.loadEnvFile(".env")를 호출하는 사이드 이펙트 모듈입니다. 모든 진입점의 첫 번째 줄에서 임포트됩니다.

• apps/agent/src/gateway/cli.ts, REPL 모드
• apps/agent/src/gateway/server.ts, HTTP 모드

ESM 평가 순서에 따라 임포트 시점에 process.env.<NAME>을 읽는 다운스트림 모듈보다 로더가 먼저 실행됩니다.

우선순위: 셸, CI, systemd에서 이미 내보낸 변수가 .env의 값보다 우선합니다. 로더는 기존 키를 덮어쓰지 않습니다. 이는 Node의 기본 동작과 일치하며, CI에서 주입된 시크릿이 예상치 못하게 가려지지 않으므로 가장 안전한 규칙입니다.

dotenv 의존성 없음. Node 22.5부터 안정화된 process.loadEnvFile만 사용합니다. .env가 없어도 오류 없이 무시됩니다.

목록

변수별 상세 문서(기본값, 형식, 소비 파일, 미설정 시 문제점)는 참조 → 환경 변수를 확인하십시오. 아래 표는 빠른 참조 요약입니다.

LLM 공급자

적어도 하나가 확인되어야 합니다(직접 설정 또는 minara auth login에서 저장된 OAuth 프로필을 통해). 하나도 확인되지 않으면 Agent 시작이 거부됩니다.

Minara 코어

HTTP 게이트웨이

안전 및 자금 이동

하이브리드 메모리 검색

EMBEDDING_PROVIDER=disabled(기본값)일 때 하이브리드 검색 코드 경로는 비활성 상태입니다. 모든 메모리 행은 embedding_state='pending'과 NULL embedding 열을 유지하며, searchMemoriesHybrid는 기존 FTS5 BM25 경로로 폴백하여 바이트 동일한 결과를 반환합니다. 교차 어휘 검색 향상이 필요할 때만(예: 중국어 쿼리 山寨币最近怎么样으로 영어 altcoin drawdown 교훈 검색) 활성화합니다. 쓰기 경로는 동기 방식을 유지합니다. 임베딩은 행이 커밋된 후 queueMicrotask에서 처리되므로 사용자 대면 지연 시간에는 영향이 없습니다.

공급자가 활성화되었으나 일시적인 API 오류가 발생하면 행이 embedding_state='failed'로 기록됩니다. minara doctor(Phase E1)는 운영자가 대량의 실패를 발견할 수 있도록 상태별 수를 표시합니다. minara doctor --fix --apply(Phase E2)는 MemoryStore.backfillEmbeddings()를 통해 백필을 수행합니다. failed와 pending 모두 백필 대상입니다. 성공적으로 임베딩이 완료되어 embedded 상태가 될 때까지 동일한 행이 반복될 수 있습니다. 10자 미만이거나 방법론 주입 스캐너에 걸리는 행은 skipped 상태로 설정되며 임베딩되지 않습니다.

백테스팅 피드백 루프(Sprint 6, 온라인 결과 채우기)

대상 실행의 학습 루프를 마무리하는 주기적 작업입니다. 결정론적 거래 후 시장 결과("+5.20% in 24h")를 계산·저장하고 선택적 추론 평가를 실행합니다. 통합 Trading Memory 출처 규칙이 먼저 적용되므로 자동 또는 출처 불명 perps는 수동 평가 경로에 들어오지 않습니다.

과거 결정을 다시 실행하지 않습니다. trade_executions의 pending 행만 평가합니다. 활성화 시 정규 간격 전에 gateway 시작 시 지연 작업을 한 번 처리합니다. 기본값은 비활성입니다(BACKTEST_ENABLED=false).

롤아웃 프로토콜(plan dapper-coalescing-shell §Sprint 6):

1. BACKTEST_ENABLED=true + BACKTEST_DRY_RUN=true를 설정하고 하나의 크론 주기를 실행합니다. shadow_runs WHERE facet='backtest_outcome'을 검사하여 결과 문자열이 ±N.NN% in Xh 형식과 일치하고 건너뜀 이유가 합리적인지 확인합니다.
2. BACKTEST_DRY_RUN=false로 전환합니다. Runner가 결정론적 outcome과 종료 state를 trade_executions에 기록하며 evaluation run과 observation은 append-only로 유지됩니다.
3. 귀속이 깨끗한 경우에만 LEARNING_RECORD_USAGE=true로 전환합니다. evaluation_runs, methodology_observations, methodology_metric_stats를 profile version별로 모니터링합니다. promoted primary run만 새 통계에 영향을 줍니다.

개인화 재빌드(M3.2 이벤트 기반 임계값)

Minara는 PersonalizationRebuilder를 통해 모든 대화에서 거래 선호도를 학습합니다. M3.2 이전에는 재빌더가 쿨다운 방식으로 10분마다 실행되었습니다. M3.2는 이를 이벤트 기반 + 임계값 게이팅 방식으로 전환합니다. 데이터 쓰기(거래, 메모리, 채팅 턴)가 이벤트를 발생시켜 재빌더를 깨우며, 각 재빌드는 두 개의 독립적인 게이트를 통과해야 합니다. 최소 새 입력 수와 마지막 재빌드 이후 최소 경과 시간이 모두 충족되어야 합니다. 하나만으로는 재빌드가 실행되지 않습니다.

60분 안전망 스케줄러는 손실된 이벤트(예: 쓰기와 구독자 사이의 프로세스 재시작)를 처리하기 위해 여전히 작동하지만, 조용한 시스템에서는 LLM 호출과 info 로그가 전혀 발생하지 않습니다.

거래 요약 임계값

거래 빈도로 인해 요약이 너무 자주 변경된다면 임계값을 높이십시오. 백테스트 또는 온보딩 중에 요약을 최대한 빨리 수렴시키려면 임계값을 낮추십시오.

메모리 추출 임계값

rebuildMemories는 커서 last_indexed_chat_id 이후 기록된 chat_turns 행을 스캔하여 개별 사실을 추출합니다. 기본적으로 ADD 전용 프롬프트(UPDATE/DELETE 없음)를 사용하므로 모순은 이전 사실과 함께 ADD되어 검색 시 해결됩니다. MEMORY_CONSOLIDATION_ENABLED가 켜져 있으면 후속 리졸버 단계가 각 사실에 대해 ADD / UPDATE / SUPERSEDE를 판단하여 오래되고 모순된 행을 기록 시점에 정리합니다(Minara Memory 참고). 추출된 각 사실은 fact_type, attributed_to, entities_json, linked_memory_ids 메타데이터와 함께 공유 memories 테이블의 행으로 기록됩니다.

공유 조정값

운영 팁: 새 배포 첫날에는 FIN_PROFILE_TRADING_SUMMARY_MIN_NEW_TRADES=1과 FIN_PROFILE_MEMORIES_MIN_NEW_TURNS=2로 설정하여 재빌더가 빠르게 워밍업되도록 하십시오. 프로필이 안정화되면 기본값으로 복원합니다.

에이전트 외 거래 이력 미러

개인화 재빌더는 세 가지 소스를 사용합니다: 로컬 trade_history(에이전트 내), perps_fills(Minara /v1/perp-wallets/fills 서브월렛 미러), external_spot_activities(Minara /v1/tx/cross-chain/activities). 아래 조정값은 MinaraHistorySync의 동기화 전략과 LLM이 읽는 양을 제어합니다.

동기화 트리거 모델. MinaraHistorySync.scheduleSync()는 세 경로로 발화됩니다: (1) 임의의 trade:recorded 이벤트(에이전트가 거래를 실행했다면 사용자도 web/mobile에서 무언가 했을 가능성이 높음), (2) PersonalizationRefreshTask의 매시간 세이프티넷 tick(이벤트 누락 보완), (3) 명시적인 /refresh-personalization --force / POST /v1/profile/refresh 경로. 5분 스로틀로 윈도우당 API는 한 번만 호출됩니다.

워터마크 단위. minara_history_sync_state 키는 (source, sub_account_id). 단일 서브어카운트의 일시적 실패는 동료 워터마크나 전역 spot 커서를 오염시키지 않습니다.

Hyperliquid 무기한 선물

MINARA_HL_DEX_DISCOVERY는 무기한 선물 스냅샷을 구성하고 거래 내역을 동기화할 때 Minara가 Hyperliquid 명명된 무기한 DEX를 얼마나 폭넓게 탐색할지 제어합니다.

Strategy Studio(베타)

하나의 운영자 조정값이 strategy-rl 벤치마크 러너가 사용하는 오프라인 전략 코드젠 서브에이전트를 제어합니다. 기본값이 적절하므로 미설정 상태도 괜찮습니다.

Harness RL

기관 모드(멀티 에이전트 운용팀 시뮬레이션)

minara_institution_analyze 도구는 고위험 단일 자산 분석을 위해 6단계 파이프라인(4명의 분석가 병렬 → 강세/약세 리서치 토론 → 리서치 매니저 → 트레이더 → 3자 리스크 토론 → 포트폴리오 매니저)을 소집합니다. TradingAgents를 참고하여 설계되었으며, 라운드 수의 기본값은 해당 프로젝트의 default_config.py와 동일하게 설정되었고, 타임아웃/token 상한은 Minara의 deep-research와 에이전트 루프 규약을 따릅니다.

아래 모든 변수는 에이전트 루프 인프라이므로 프로젝트 규약에 따라 MINARA_ 접두사를 사용하지 않습니다. 모두 미설정 상태로 두면 TradingAgents 기준 기본값이 적용됩니다.

메소돌로지 감사 서브시스템(수동 옵저버)

학습 루프 위에 얹는 읽기 전용 감사 서브시스템으로 종합 건강 점수를 출력합니다. 6개 차원이 종합 점수를 구성: synthesis 판단 안정성, 졸업 후 단기 강등률, 귀속 건강도, 자산 클래스 커버리지, 격리 반복 검출, cron 건강도. 서브시스템은 학습 상태를 절대 변경하지 않으며, 유일한 쓰기는 methodology_audit_reports로 패스당 한 행입니다. 종단간 테스트가 매 감사 패스 전후 4개 학습 테이블을 해시하여 쓰기를 도입하는 회귀를 즉시 잡습니다.

cron은 에이전트 루프와 협력합니다. 각 tick은 공유 BusyTracker를 확인하고, 사용자 턴이 진행 중이거나 에이전트 유휴 시간이 임계값 미만이면 tick을 연기합니다. 연속 N회 연기 후 굶주림 가드가 강제 실행하여 항상 바쁜 배포에서도 감사 커버리지를 잃지 않게 합니다. 패스 실행 중 오케스트레이터가 SQL 단계 사이에서 이벤트 루프에 양보하고, 턴이 들어오면 busy tracker에서 즉시 일시 정지합니다.

기본 주기는 하루 한 번. cron_health는 methodology_cron_runs 하트비트 테이블(src/learning/methodology-cron.ts가 매 학습 tick 끝에 기록)을 읽습니다. 귀속 레인이 조용해도(처리할 case 없음) 죽은 루프로 오판하지 않습니다.

CLI:

minara learning audit run [--window-days N]  # 인라인 단일 패스
minara learning audit show [--latest|--pass <id>]
minara learning audit trend [--days N]       # 복합 점수 이력 + sparkline
minara learning audit findings [--severity high|medium|low]

프로액티브 자산 관리 에이전트

활성화된 각 맨데이트를 백그라운드에서 운용하는 감독 루프(포지션 시가 평가, 익절/손절/리밸런싱, 손익 스냅샷, 작업 로그 기록)와 새로운 기회를 찾는 느린 재탐색입니다. 세 가지 모두 설정 → 프로액티브(및 프로액티브 모듈 자체의 설정 탭)에서 실시간으로 편집할 수 있으며, 아래 환경 변수는 부팅 시 폴백입니다. 멀티 워커 배포에서는 IS_PRIMARY_WORKER=1 워커에서만 루프가 실행됩니다.

Point-in-time 재무 스냅샷

과거 스냅샷에는 SEC accepted time이 요청 기준 시각 이전인 fact만 포함됩니다. FMP 데이터는 SEC filing과 명확하게 일치할 때만 fact를 보완합니다. Yahoo 현재 요약, 시가총액, 섹터, 산업, TTM 값, DCF는 latest-only approximation으로 처리합니다.

행동 메모리

BEHAVIOR_MEMORY_ENABLED=true로 옵트인합니다. 범주는 개별 제어되며 자산 컨텍스트, 거래, 대화는 명시적으로 켜지 않으면 수집되지 않습니다. 본문, 비밀, 주소, 주문 매개변수, 개별 포지션은 저장하지 않습니다.