AI Agents

AI 에이전트 · 자동화

kiwoom-cli는 AI 에이전트와 자동화 스크립트가 도구로 쓰는 것을 처음부터 염두에 두고 설계됐습니다. Claude Code 같은 코딩 에이전트, 크론잡, CI 파이프라인에 바로 연결됩니다.

왜 에이전트 친화적인가

설계	효과
프롬프트 제로 (v2.1)	비밀번호·생체인증 프롬프트가 없어 에이전트 세션이 중간에 멈추지 않음
구조화된 JSON 출력	-f json — 파싱 불필요, jq 파이프라인 조합
일관된 exit code	0/1/2/3 — 에이전트가 실패 원인을 코드로 판별
명시적 주문 게이트	기본은 대화형 확인, 자동화는 --confirm으로 의도를 명시
자동 페이지네이션	연속조회를 CLI가 처리 — 에이전트가 커서 관리 불필요
자동 시장 라우팅	티커만 주면 국내/미국 판별 — 분기 로직 불필요

JSON 출력

kiwoom -f json stock info 005930
kiwoom -f json account balance          # {"kr": ..., "us": ...} 단일 문서
kiwoom -f json market rank volume | jq '.[].stk_nm'
kiwoom -f csv stock daily 005930 > samsung_daily.csv

Exit Code 계약

코드	의미	에이전트 대응
0	성공	결과 사용
1	입력 오류	인자 수정 후 재시도
2	API/네트워크 오류	백오프 후 재시도
3	인증 필요	kiwoom auth login 실행 후 재시도

kiwoom stock price 005930
case $? in
  3) kiwoom auth login && kiwoom stock price 005930 ;;
esac

주문 자동화

주문은 기본적으로 미리보기 + 대화형 확인을 거칩니다. 스크립트·에이전트에서는 --confirm으로 명시적으로 스킵합니다:

kiwoom order buy 005930 10 --type market --confirm
kiwoom order buy NVDA 10 --price 213.04 --confirm

팁: 에이전트에게 주문 권한을 줄 때는 --confirm 사용을 에이전트 정책으로 통제하세요. --confirm 없이 실행하면 프롬프트에서 멈추므로, 사람의 승인이 필요한 워크플로에서는 오히려 그 동작을 활용할 수 있습니다.

크론잡 예시

프롬프트가 전혀 없으므로 크론에서 그대로 동작합니다:

# 매일 장 마감 후 잔고 스냅샷
30 16 * * 1-5  kiwoom -f json account balance > ~/logs/balance-$(date +\%Y\%m\%d).json

# 매일 아침 관심종목 시세 CSV
0 8 * * 1-5    kiwoom -f csv stock watchlist "005930|000660" > ~/logs/watchlist.csv

Claude Code / 코딩 에이전트에서 쓰기

에이전트 프로젝트의 CLAUDE.md(또는 시스템 프롬프트)에 이렇게 안내하면 됩니다:

- 시세/계좌 조회: `kiwoom -f json <command>` — JSON으로 파싱
- exit code 3이면 `kiwoom auth login` 후 재시도
- 주문은 반드시 사용자 승인 후 `--confirm`으로 실행

모의투자 도메인(kiwoom config domain mock)에서 에이전트 워크플로를 충분히 검증한 뒤 실거래로 전환하는 것을 권장합니다.

샌드박스 환경 (키체인 접근 불가)

샌드박스 셸, CI, 컨테이너에서는 OS 키체인을 읽을 수 없어 인증 명령이 실패합니다. 이때는 본인 터미널에서 토큰을 발급받아 KIWOOM_TOKEN 환경변수로 전달하세요:

# 본인 터미널에서 (하루 1회 정도)
kiwoom auth login
export KIWOOM_TOKEN=$(security find-generic-password -s kiwoom-cli -a "default:token" -w)  # macOS

# 이 셸에서 에이전트/CI를 실행하면 환경변수가 상속됩니다
kiwoom auth status   # → 토큰 있음 (환경변수 KIWOOM_TOKEN)

• appkey/secretkey는 키체인 밖으로 나가지 않습니다 (환경변수 미지원 정책 유지)
• 토큰은 만료·폐기 가능(kiwoom auth logout)하므로 노출 위험이 제한적입니다
• KIWOOM_TOKEN은 키체인 토큰보다 우선합니다 — 제거는 unset KIWOOM_TOKEN

멀티 프로필과 자동화

KIWOOM_PROFILE=isa kiwoom account balance   # 환경변수로 프로필 지정
kiwoom -p main account balance              # 옵션으로 지정

관련 페이지

• 출력 형식 — JSON/CSV 상세
• 보안 — 프롬프트 제로 설계의 배경
• 멀티 프로필 — 계좌별 프로필