@mulsok/traders-client

mulsok-traders 데스크톱 클라이언트 — 한국 주식 AI 자율 트레이더 (macOS · claude CLI).

베타 1라운드 · macOS only · claude CLI (Claude Code) 권장

🖥 → ⌨ SSH · 헤드리스 환경 사용자: 이 패키지의 모든 운영을 webui 없이 CLI 만으로 진행할 수 있습니다. 단계별 가이드 → mulsok-traders.vercel.app/guide?mode=cli

설치

npm install -g @mulsok/traders-client

설치 직후 postinstall 이 자동으로:

1. macOS LaunchAgent 등록 (~/Library/LaunchAgents/com.mulsok.traders.client.plist)
2. 부팅 시 자동 시작 + 비정상 종료 시 30초 후 재기동
3. http://127.0.0.1:5903 에서 webui 가동

사전 요구사항

node --version    # v20.0.0 이상
claude --version  # 2.x 이상 (https://claude.com/claude-code)

첫 사용

1. 브라우저 → http://127.0.0.1:5903/
2. 「설정」 페이지 6 탭 입력:
   • 구독 (트레이더 받기)
   • AI 모델 (claude CLI 권장)
   • 증권사 (키움 AppKey/Secret · 모의투자 권장)
   • 자본 배정 (미설정 시 계좌 예수금 전체)
   • 디바이스 토큰 (mulsok-traders.vercel.app 에서 발급)
   • 안전망 (긴급 정지 토글)
3. PersonasPage → 「지금 분석」 한 번 → 이후 watchdog 자동

명령어

CLI 가 모든 운영 명령을 제공합니다 — webui 없이도 헤드리스 / SSH 환경에서 daemon 을 완전히 제어할 수 있습니다.

Daemon lifecycle

mulsok-client status [--json]  # daemon · 인증 · 설정 · 계좌 · 감시자 · readiness
mulsok-client logs              # 로그 실시간 tail (Ctrl+C 종료)
mulsok-client update            # npm update + daemon 재시작
mulsok-client uninstall         # 데몬 제거 (데이터 보존)
mulsok-client help              # 도움말

설정 (config — webui 우회)

mulsok-client config show                       # 현재 설정 (마스킹 표 출력)
mulsok-client config token <T>                  # 디바이스 인증 (인자 없으면 stdin 비밀 입력)
mulsok-client config llm <provider> [--api-key=K] [--model=M]
                                                # provider: claude-cli·anthropic·openai·gemini
mulsok-client config broker kiwoom \
        --app-key=K --app-secret=S [--demo|--live]
mulsok-client config subs list                  # 구독 목록
mulsok-client config subs add <slug>            # 구독 추가
mulsok-client config subs remove <slug>         # 구독 제거

운영

mulsok-client safety status                     # 현재 safety 상태
mulsok-client safety halt [reason]              # 긴급 정지
mulsok-client safety resume                     # 정상 가동 재개
mulsok-client cycle <slug>                      # 수동 cycle (7~13분 · 분석 후 요약)
mulsok-client diary <slug> [--date=YYYY-MM-DD]  # 일기 본문 (markdown ANSI · default 오늘)
mulsok-client diary <slug> --list [--limit=30]  # 일기 목록 (날짜·길이·발췌)
mulsok-client journal [--days=7] [--tail=10]    # 최근 이벤트 timeline
mulsok-client watchers [--persona=slug]         # active 감시자 표

모든 명령은 daemon HTTP API (127.0.0.1:5903) thin wrapper 입니다. webui 와 동일한 데이터 흐름이라 인증 토큰·종목 정보 등은 daemon 안에 그대로 보관되며 외부로 송신되지 않습니다.

업데이트

npm update -g @mulsok/traders-client
# 또는
mulsok-client update

postinstall 이 자동으로 데몬 재시작 — 별도 명령 불필요.

데이터 위치

~/.mulsok-traders/
├── config.json       # 설정 (0600)
├── market.db         # SQLite (universe + candles + watchers)
├── logs/             # 데몬 로그
├── personas/<slug>/  # 페르소나 메모리
├── trade-journal/    # 의사결정 + 주문 (월별 jsonl)
└── diary/<slug>/     # 페르소나별 일기

제거

# 데몬 + 패키지 제거 (데이터 보존)
npm uninstall -g @mulsok/traders-client

# 데이터까지 완전 삭제 (되돌릴 수 없음)
rm -rf ~/.mulsok-traders

⚠️ 베타 1R 한계

• macOS only (Windows/Linux 추후)
• CLIENT_HOST=0.0.0.0 으로 바꾸지 마세요 — 인증 미들웨어 미구현
• 자동 업데이트 X · 사용자가 mulsok-client update
• 장애 대응: 사용자 직접 운영 + 피드백

문서

• DOC-704 · 베타 빠른 시작
• DOC-703 · 클라이언트 설정 가이드
• Web 대시보드

보안

• 모든 비밀값 (키움 키 · LLM 키 · 디바이스 토큰) 은 ~/.mulsok-traders/config.json (0600 권한) 에만 저장
• 서버는 사용자 자격증명·계좌 정보 보관 X (ADR-008 분산 자율 에이전트)
• 페르소나 프롬프트는 supabase bundle API 로 동적 fetch (HMAC 검증)

License

UNLICENSED — 베타 1라운드 · 사용자 운영 책임.