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

⚠️ 베타 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 에서 토큰을 받아 mulsok-client config token 으로 등록합니다.

1. 대시보드 → 「Step 3 토큰 발급」 카드 → 「토큰 발급」
2. mtd_… 토큰 복사 (창 닫으면 다시 못 봄)
3. 서버 터미널에서 한 줄 등록:

# 인자로 직접 (자동화 가능 · 단점: shell history 노출)
mulsok-client config token mtd_xxx…

# 또는 인자 생략 → stdin 비밀 입력 (history 안 남음 · 권장)
mulsok-client config token

✓ 확인: ✓ 인증 성공: … 출력. 또는 mulsok-client status 의 인증 항목이 OK.

mulsok-client config 하위 명령으로 차례로 등록. 모든 값은 daemon 의 ~/.mulsok-traders/config.json (0600) 에만 저장 · 서버 송신 0회.

# 1. 구독 — sub slug 추가 (dashboard 에서 사용자 slug 확인)
mulsok-client config subs add <slug>
mulsok-client config subs list           # 확인

# 2. AI 모델 — Claude Code CLI 권장 (별도 키 불필요)
mulsok-client config llm claude-cli --model=sonnet
# 또는 anthropic 직접 호출:
# mulsok-client config llm anthropic --api-key=sk-ant-… --model=claude-sonnet-4-6

# 3. 증권사 — 키움 모의투자 (실거래는 --live · ⚠ 사고 주의)
mulsok-client config broker kiwoom --app-key=K --app-secret=S
# 실거래: 위 명령에 --live 추가 (모의투자에서 충분히 검증 후)

# 4. 안전망 — 긴급 정지가 필요한 경우
mulsok-client safety status              # 현재 상태
mulsok-client safety halt "사유"          # 즉시 정지
mulsok-client safety resume              # 재가동

⚠ --app-key=… 는 shell history 에 남습니다. 민감 환경이면 ~/.mulsok-traders/config.json 직접 편집 (0600 권한 유지).

자본 배정은 미설정 시 키움 예수금 전체 (MAX) 자동 사용. 별도 명령 불필요.

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 미설치 등.

mulsok-client cycle <slug> 한 번이면 첫 분석 + 자율 사이클 활성화. 이후 watchdog 가 LLM 응답의 wake_plan 시각에 자동 발화.

mulsok-client cycle <slug>          # 분석 7~13분 · 종료 시 콘솔 요약
mulsok-client diary <slug>          # 오늘자 일기 본문 (마크다운 ANSI)
mulsok-client diary <slug> --list   # 일기 목록
mulsok-client journal --days=7      # 최근 7일 이벤트 timeline

✓ 확인: cycle 종료 후 dashboard 가 정상 모드로 전환 + 평일 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 응답.