pi-kiwoom-cli

설치된 kiwoomcli를 Pi 에이전트가 안전하고 예측 가능하게 사용할 수 있도록 안내하는 스킬 패키지입니다.

[!WARNING] 이 스킬은 실계좌 주문을 전송할 수 있습니다. 처음에는 실계좌와 모의계좌 주문 정책을 모두 기본값인 deny로 유지하고, 모의계좌에서 충분히 검증하세요.

패키지와 CLI의 관계

• kiwoomcli: 키움 REST API를 실제로 호출하는 CLI
• pi-kiwoom-cli: Pi 에이전트가 kiwoomcli를 사용하는 절차와 안전 정책을 제공하는 스킬

이 패키지는 CLI 실행 파일, App Key/Secret 또는 계좌 정보를 포함하지 않습니다. 키움증권 공식 제품이 아니며, Kiwoom 및 키움증권 관련 명칭은 각 권리자에게 귀속됩니다.

사전 요구사항

먼저 키움증권의 Kiwoom REST API 사용자 가이드를 따라 다음 준비를 완료하세요.

1. Python과 uv 설치
2. uv tool install kwcli로 CLI 설치
3. App Key/Secret 발급
4. 터미널에서 kiwoomcli setup을 직접 실행해 인증 설정
5. kiwoomcli auth status로 인증 상태 확인

다음 명령이 정상적으로 동작해야 합니다.

kiwoomcli --help
kiwoomcli auth status

대화형 초기 설정은 이 스킬의 지원 범위 밖입니다. App Key/Secret을 Pi 대화에 입력하지 마세요.

설치

npm에서 전역 Pi 패키지로 설치합니다.

pi install npm:pi-kiwoom-cli

특정 프로젝트에만 설치하려면 -l을 사용합니다.

pi install -l npm:pi-kiwoom-cli

영구 설치 없이 시험할 수도 있습니다.

pi -e npm:pi-kiwoom-cli

Git 저장소에서 설치하려면 다음과 같이 실행합니다.

pi install git:github.com/wjdhan/pi-kiwoom-cli

사용 예시

Pi에 자연어로 요청하면 스킬이 적절한 kiwoomcli 명령을 선택하고 현재 --help를 확인한 후 실행합니다.

삼성전자 현재가를 조회해줘.
내 모의계좌의 보유 종목을 보여줘.
저장된 조건검색식 목록을 조회해줘.
삼성전자 10주 지정가 매수 주문을 미리보기 해줘.

설치 또는 인증 문제를 확인하려면 다음과 같이 요청할 수 있습니다.

kiwoomcli 상태를 진단해줘.

지원 기능

• 인증 수명주기 관리 및 상태 진단
• OpenAPI 스펙 탐색
• 국내 주식, 시세, 호가, 캔들, ETF, ELW, 투자자, 순위, 업종, 공매도, 대차거래 및 테마 조회
• 계좌, 잔고, 손익 및 거래 내역 조회
• 종료 조건이 있는 WebSocket 및 조건검색 스트림
• 국내 주식, 신용 및 금 현물 주문 조회·미리보기·실행

다음 기능은 의도적으로 지원 범위에서 제외합니다.

• 대화형 초기 설정(kiwoomcli setup)
• --watch를 사용하는 무제한 스트림 수집
• 조건검색식 생성 및 수정(영웅문 HTS에서 수행)

실제 주문 정책

실계좌와 모의계좌에 서로 다른 주문 정책을 설정할 수 있습니다.

KIWOOMCLI_SKILL_REAL_ORDER_POLICY=deny|ask|allow
KIWOOMCLI_SKILL_DEMO_ORDER_POLICY=deny|ask|allow

환경변수가 없거나 값이 유효하지 않으면 두 정책 모두 deny로 처리합니다.

• deny: 실제 주문을 차단하며 --confirm 없는 주문 미리보기는 허용합니다.
• ask: 전체 주문표를 표시하고 해당 주문에 대한 새로운 승인을 요구합니다.
• allow: 추가 승인 없이 실제 주문을 전송할 수 있습니다.

에이전트는 이 환경변수를 읽기만 하며 직접 설정하거나 변경하지 않습니다. 정책은 일반 주식, 신용 및 금 현물의 매수·매도·정정·취소 주문에 모두 적용됩니다.

예를 들어 모의계좌 주문은 매번 확인하고 실계좌 주문은 차단하려면 Pi를 시작하기 전에 다음과 같이 설정합니다.

export KIWOOMCLI_SKILL_REAL_ORDER_POLICY=deny
export KIWOOMCLI_SKILL_DEMO_ORDER_POLICY=ask
pi

allow는 추가 승인을 생략하므로 자동 실행의 영향을 이해한 경우에만 사용하세요. 자연어 요청으로 deny 정책을 우회할 수 없습니다.

보안 주의사항

• App Key/Secret을 대화, 로그 또는 저장소에 노출하지 마세요.
• kiwoomcli auth export는 자격 증명이 포함된 파일을 만들 수 있습니다.
• 계좌 및 실시간 계좌 이벤트에는 보유자산, 주문번호와 같은 민감한 금융정보가 포함될 수 있습니다.
• 실제 주문 전에는 대상 프로필이 real인지 demo인지 확인하세요.
• Pi 패키지의 스킬은 에이전트에게 시스템 명령 실행을 지시할 수 있으므로 설치 전에 내용을 검토하세요.

점진적 공개

메인 스킬에는 명령 라우팅, 실행 절차, 개인정보 보호, 스트림 및 주문 안전 규칙을 둡니다. 각 CLI 명령의 상세 도움말은 별도의 참조 파일에 두고 필요할 때만 불러옵니다.

pi-kiwoom-cli/
├── package.json
└── skills/
    └── kiwoom-cli/
        ├── SKILL.md
        └── references/
            ├── auth/
            ├── spec/
            ├── streams/
            ├── accounts/
            ├── orders/
            └── ...

참조 문서는 kiwoomcli --help를 바탕으로 작성했습니다. 스킬은 명령 실행 전에 kiwoomcli <command> --help로 설치된 CLI의 현재 문법을 다시 확인합니다.

로컬 개발

체크아웃을 영구 설치 없이 불러옵니다.

pi -e .

로컬 패키지로 설치합니다.

pi install .

npm에 포함될 파일을 확인합니다.

npm run pack:dry-run

라이선스

MIT