따라하기 — 설치부터 첫 분석까지

⚠️ 베타 1라운드 한계

• OS: macOS only · LLM: claude CLI 권장
• 외부 노출 (LAN): 비활성 · 127.0.0.1 만 · 키움증권만 지원
• 자동 업데이트 X · mulsok-client update 수동
• 활성 시간: 평일 09:00–15:30 KST · 장 외 wake_plan 분석 가능 · 주말·KRX 휴일 자동 휴장

Node.js 와 claude CLI 가 있는지 확인. 없으면 설치.

node --version    # v20.0.0 이상
claude --version  # 2.x 이상

없으면 설치 → Node.js · claude CLI

npm 한 줄. 자동으로 LaunchAgent 등록 + 데몬 가동 + 부팅 시 자동 시작.

npm install -g @mulsok/traders-client

✓ 확인: 아래 명령에 PID 가 보이면 데몬 가동 중

launchctl list | grep mulsok.traders

macOS 가 sleep 또는 사용자 로그아웃 상태이면 데몬이 멈춥니다. 24시간 운영을 위해 아래 점검 필수.

sudo pmset -c sleep 0

✓ 확인: pmset -g 의 sleep 값이 0

웹 dashboard 에서 토큰을 받아 클라이언트 webui 에 붙여넣습니다.

1. 대시보드 → 「Step 2 토큰 발급」 카드 → 「토큰 발급」
2. mtd_… 토큰 복사 (창 닫으면 다시 못 봄)
3. 새 탭 → http://127.0.0.1:5903/ → 설정 → 「디바이스 토큰」 탭 → 붙여넣기 + 저장

✓ 확인: dashboard 새로고침 → Step 2 카드 사라짐 → 「Step 3」 으로 진행

클라이언트 webui 의 「설정」 6탭에 차례로 입력.

모든 비밀값은 ~/.mulsok-traders/config.json (0600 권한) 에만 저장. 서버 송신 0회.

6 항목이 모두 ok 이어야 자율 사이클이 활성화됩니다.

curl http://127.0.0.1:5903/api/readiness | python3 -m json.tool

• server · device-auth · common-prompt
• bundle-sync · llm · broker

⚠ 막히는 항목 있으면 ⑤ 설정 점검 — 키움 키 오타 / claude CLI 미설치 등.

클라이언트 webui 의 「PersonasPage → 지금 분석」 클릭. 이후 watchdog 가 LLM 응답의 wake_plan 시각에 자동 발화.

✓ 확인: webui 「일지」 에서 분석 결과 (마크다운) 확인 + 이후 매일 09:00 ~ 15:30 KST 자동 운영

운영 명령

모든 명령은 daemon HTTP API (127.0.0.1:5903) thin wrapper — webui 없이도 헤드리스 / SSH 환경에서 완전히 제어할 수 있습니다.

데몬 lifecycle

mulsok-client status [--json]     # 데몬 · 인증 · 설정 · 계좌 · 감시자 · readiness
mulsok-client logs                # 로그 실시간 tail
mulsok-client update              # 새 버전 받기 + 자동 재시작
mulsok-client uninstall           # 데몬 제거 (데이터 보존)
mulsok-client help

설정 (webui 우회)

mulsok-client config show                        # 현재 설정 (마스킹)
mulsok-client config token [<T>]                 # 디바이스 인증 (인자 없으면 stdin)
mulsok-client config llm <provider> [--api-key=K] [--model=M]
mulsok-client config broker kiwoom --app-key=K --app-secret=S [--demo|--live]
mulsok-client config subs list | add <slug> | remove <slug>

운영

mulsok-client safety status | halt [reason] | resume
mulsok-client cycle <slug>                       # 수동 cycle (7~13분)
mulsok-client diary <slug> [--date=YYYY-MM-DD]   # 일기 본문 (마크다운 ANSI)
mulsok-client diary <slug> --list [--limit=30]
mulsok-client journal [--days=7] [--tail=10]
mulsok-client watchers [--persona=slug]

데이터 위치

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

완전 제거

npm uninstall -g @mulsok/traders-client    # 데몬 + 패키지 (데이터 보존)
rm -rf ~/.mulsok-traders                   # 데이터까지 삭제

🔐 보안 주의

• CLIENT_HOST=0.0.0.0 변경 금지 — 인증 미들웨어 미구현이라 LAN 의 다른 사용자가 데몬 제어 가능
• ~/.mulsok-traders/config.json 공유 금지 — 키움 키 평문
• 실거래 활성화 전 모의투자 권장 (3. 증권사 탭의 모의투자 토글 ON)

🚨 사고 시 즉시 차단 — webui 「설정 → 안전망」 → 긴급 정지 ON. (LLM 호출 · 주문 · watcher 발화 모두 차단)

막혔을 때

1. 로그 확인 — tail ~/.mulsok-traders/logs/client.err.log
2. readiness 점검 — mulsok-client status
3. npm 재설치 — npm install -g @mulsok/traders-client@latest

보고 시 함께: macOS 버전 (Apple Silicon / Intel) · 재현 단계 · tail -30 client.err.log · /api/readiness 응답.