키움 OpenAPI+ 설치·오류 해결 완전 가이드 — 자주 막히는 12가지

키움 OpenAPI+는 한국 주식 자동매매에서 가장 많이 쓰이는 API지만, 설치와 첫 실행에서 막히는 사람이 가장 많은 API이기도 합니다. 이유는 단순합니다 — 키움 OpenAPI+는 32bit COM 컴포넌트(KHOpenAPI.OCX) 기반이라, 최신 64bit 환경과 충돌하는 지점이 곳곳에 있기 때문입니다.

이 글은 설치 → 로그인 → TR 요청 → 실시간 4단계에서 자주 막히는 오류 12가지를 증상·원인·해결책으로 정리했습니다. 지금 막혀 있는 단계의 번호로 바로 이동하셔도 됩니다.

0. 먼저 알아야 할 것 — 왜 32bit인가

키움 OpenAPI+의 핵심은 KHOpenAPI.OCX라는 32bit COM 컴포넌트입니다. 모든 호출(로그인, 시세, 주문)이 이 OCX를 거칩니다. 그래서 다음이 강제됩니다:

• Python은 반드시 32bit(x86) — 64bit Python은 32bit OCX를 못 불러옵니다
• OS는 Windows 전용 — Mac/Linux 불가 (COM이 Windows 기술)
• GUI 프레임워크로 보통 PyQt5의 QAxWidget 사용

이 제약이 싫다면 처음부터 REST 기반인 KIS API를 쓰는 선택지도 있습니다. 비교는 → 키움 OpenAPI vs KIS API 참고.

설치 단계 오류

164bit Python 충돌 → OCX 로드 실패

증상: QAxBase: Error, 또는 CoCreateInstance failed, 또는 QAxWidget 생성 시 빈 객체.

원인: 64bit Python에서 32bit OCX를 로드하려 함.

해결: 32bit Python 설치. python.org에서 "Windows installer (32-bit)"를 받습니다(파일명에 x86). 설치 확인:

python -c "import platform; print(platform.architecture())"
# ('32bit', 'WindowsPE') 가 나와야 정상

버전은 3.8~3.10 32bit가 PyQt5·OpenAPI와 호환성이 가장 좋습니다. 최신 3.12+는 32bit 빌드·일부 패키지 호환 이슈가 있을 수 있습니다.

2영웅문만 설치, OpenAPI+ 누락

증상: 영웅문은 잘 켜지는데 Python에서 OCX를 못 찾음.

원인: 영웅문(HTS)과 OpenAPI+는 별개 프로그램. HTS만 깔았다.

해결: 키움증권 홈페이지 → OpenAPI 메뉴 → 사용 신청 후 전용 설치 파일을 받아 설치. 신청 즉시 또는 영업일 기준 처리 후 사용 가능합니다.

3KHOpenAPI.OCX 미등록

증상: 설치는 했는데 Class not registered 오류.

원인: OCX가 시스템에 COM 등록이 안 됨(드물게 설치 중 권한 문제).

해결: 관리자 권한 명령 프롬프트에서 수동 등록:

cd C:\OpenAPI
regsvr32 KHOpenAPI.OCX
# "DllRegisterServer ... 성공" 메시지 확인

4관리자 권한 / KOA Studio 동작 확인

증상: 코드 일부 기능(특히 주문)이 조용히 실패.

해결: 개발 단계에서는 IDE·터미널을 관리자 권한으로 실행하세요. 그리고 Python 코드를 짜기 전에 키움이 제공하는 KOA Studio로 로그인·시세 조회가 되는지 먼저 확인하세요. KOA Studio가 안 되면 Python 코드 문제가 아니라 설치 문제입니다.

로그인 단계 오류

5로그인 창이 안 뜨거나, 떠도 코드가 그냥 지나감

증상: CommConnect()를 불렀는데 창이 안 뜨거나, 떠도 다음 코드가 먼저 실행됨.

원인: 키움 로그인은 비동기입니다. CommConnect()는 요청만 보내고, 완료는 OnEventConnect 콜백으로 옵니다. 콜백을 기다리는 이벤트 루프가 없으면 코드가 그냥 지나갑니다.

from PyQt5.QtWidgets import QApplication
from PyQt5.QAxContainer import QAxWidget
from PyQt5.QtCore import QEventLoop
import sys

app = QApplication(sys.argv)
ocx = QAxWidget("KHOPENAPI.KHOpenAPICtrl.1")

login_loop = QEventLoop()

def on_event_connect(err_code):
    if err_code == 0:
        print("로그인 성공")
    else:
        print(f"로그인 실패: {err_code}")
    login_loop.exit()   # ← 콜백이 와야 루프 종료

ocx.OnEventConnect.connect(on_event_connect)
ocx.dynamicCall("CommConnect()")
login_loop.exec_()   # ← 콜백 올 때까지 여기서 대기

6버전처리(자동 업데이트)에서 멈춤

증상: 로그인 창에서 "버전처리 중" 후 멈추거나, 자동화 스크립트가 여기서 무한 대기.

원인: 키움은 신버전 배포 시 로그인 과정에서 자동 업데이트(버전처리)를 강제합니다. 이 과정은 사용자 확인 클릭이 필요할 수 있어 완전 자동화를 막습니다.

해결:

• 새 버전이 떴을 때는 먼저 수동으로 1회 로그인해 버전처리를 끝낸다
• 무인 운영 봇이라면 버전처리 후 자동 재시작 로직을 둔다
• 버전처리는 보통 영업일 새벽에 발생 → 그 시간대 재시작 스케줄을 고려

7OnEventConnect 콜백이 안 옴

증상: 로그인은 한 것 같은데 콜백 함수가 호출 안 됨.

원인: ① 시그널 연결(.connect())을 CommConnect() 호출 전에 안 했다 ② QApplication 이벤트 루프가 안 돌고 있다.

해결: 위 5번 코드 순서대로 — connect() → CommConnect() → exec_(). 콘솔 스크립트라도 QApplication은 반드시 생성하고 이벤트 루프를 돌려야 합니다.

TR 요청(데이터 조회) 오류

8TR 요청을 보냈는데 데이터가 안 옴

증상: CommRqData()를 불렀는데 OnReceiveTrData가 안 오거나 빈 값.

원인 체크리스트:

• SetInputValue 누락: TR마다 필수 입력값이 다릅니다. 하나라도 빠지면 응답이 없습니다.
• rqname/screen 불일치: CommRqData("주식기본", "opt10001", 0, "0101")에서 쓴 rqname을 OnReceiveTrData에서 동일하게 비교해야 합니다.
• 이벤트 루프 부재: TR 응답도 비동기 → 5번처럼 QEventLoop로 대기.

def request_price(ocx, code):
    tr_loop = QEventLoop()
    result = {}

    def on_tr_data(screen, rqname, trcode, recordname, prev, *args):
        if rqname == "주식기본":
            price = ocx.dynamicCall(
                "GetCommData(QString,QString,int,QString)",
                trcode, rqname, 0, "현재가")
            result["price"] = price.strip()
        tr_loop.exit()

    ocx.OnReceiveTrData.connect(on_tr_data)
    ocx.dynamicCall("SetInputValue(QString,QString)", "종목코드", code)
    ocx.dynamicCall("CommRqData(QString,QString,int,QString)",
                    "주식기본", "opt10001", 0, "0101")
    tr_loop.exec_()
    return result.get("price")

9조회 제한 초과 — "조회가 안 됨"

증상: 처음 몇 번은 되다가 갑자기 TR 응답이 끊김.

원인: 키움은 초당·분당 TR 횟수 제한이 있습니다. 빠른 루프로 연속 조회하면 막힙니다.

해결: 연속 조회 사이에 최소 3.6초 간격을 두는 것이 안전합니다(보수적 권장값). 대량 종목 조회 시:

import time

for code in stock_codes:
    price = request_price(ocx, code)
    print(code, price)
    time.sleep(3.6)   # 조회 제한 회피 (보수적 간격)

제한값은 변경될 수 있으니, 대량 조회가 필요하면 TR 대신 실시간 등록이나 종목 일괄 조회 TR을 활용하는 설계가 낫습니다.

10한글 종목명이 깨져 보임

증상: GetMasterCodeName 결과가 ??? 또는 깨진 문자.

원인: 콘솔 인코딩 또는 파일 저장 인코딩 불일치(데이터 자체는 정상인 경우가 대부분).

해결: 출력·저장을 UTF-8로 통일. 콘솔이 의심되면 파일로 먼저 검증:

name = ocx.dynamicCall("GetMasterCodeName(QString)", "005930")
with open("check.txt", "w", encoding="utf-8") as f:
    f.write(name)   # 파일에서 정상이면 데이터는 OK, 콘솔 인코딩 문제

실시간·조건검색 오류

11실시간 등록이 일정 개수에서 막힘

증상: 종목을 계속 SetRealReg 하는데 어느 순간부터 실시간 데이터가 안 옴.

원인: 화면번호 하나당 실시간 등록 종목 수에 제한이 있습니다.

해결: 종목을 그룹으로 나눠 화면번호를 분산합니다.

# 종목을 100개씩 끊어 화면번호를 다르게 등록
def register_realtime(ocx, codes, fids="10;11;12"):
    for i in range(0, len(codes), 100):
        chunk = codes[i:i+100]
        screen = str(5000 + i // 100)   # 화면번호 분산
        ocx.dynamicCall(
            "SetRealReg(QString,QString,QString,QString)",
            screen, ";".join(chunk), fids, "0")

12조건검색(조건식)이 동작 안 함

증상: SendCondition을 불러도 결과가 안 옴.

원인: 조건검색은 조건식 목록을 먼저 비동기로 로드해야 합니다. GetConditionLoad() 호출 후 OnReceiveConditionVer 콜백이 와야 조건식을 쓸 수 있습니다.

cond_loop = QEventLoop()

def on_condition_ver(ret, msg):
    print("조건식 로드:", ret)   # 1이면 성공
    cond_loop.exit()

ocx.OnReceiveConditionVer.connect(on_condition_ver)
ocx.dynamicCall("GetConditionLoad()")
cond_loop.exec_()   # ← 조건식 로드 완료 대기

# 이제 SendCondition 사용 가능
conditions = ocx.dynamicCall("GetConditionNameList()")
print(conditions)

또한 조건검색은 HTS(영웅문)에서 미리 조건식을 만들어 저장해두어야 OpenAPI에서 불러올 수 있습니다.

빠른 진단 체크리스트

자주 묻는 질문

Q. 키움 OpenAPI+는 왜 32bit Python만 되나요?

KHOpenAPI.OCX가 32bit COM 컴포넌트라 64bit Python 프로세스가 직접 로드할 수 없습니다. 32bit Python이 필수입니다.

Q. 영웅문을 설치했는데 OpenAPI가 안 보입니다.

영웅문(HTS)과 OpenAPI+는 별개입니다. 키움 홈페이지에서 OpenAPI 사용 신청 후 전용 설치 파일을 따로 받으세요.

Q. 로그인 창이 안 뜨거나 멈춥니다.

CommConnect() 후 QEventLoop로 OnEventConnect 콜백을 대기해야 합니다. 최초 1회는 버전처리를 수동으로 끝내두세요.

Q. TR 요청을 보냈는데 데이터가 안 옵니다.

SetInputValue 누락, rqname/화면번호 불일치, 조회 제한 초과, 이벤트 루프 부재를 차례로 확인하세요.

Q. 키움 OpenAPI+와 KIS API 중 무엇이 좋나요?

Windows + 풍부한 자료·조건검색 → 키움. Mac/Linux·클라우드 무중단 → KIS. 자세히는 → 키움 OpenAPI vs KIS API

마무리

키움 OpenAPI+ 오류는 대부분 설치 단계 4가지(32bit, 별도 설치, 등록, KOA 확인)와 비동기 처리 누락에서 비롯됩니다. 이 2가지만 잡으면 나머지는 응용입니다.

설치·오류 대응에 시간을 쏟기보다 전략 개발에 집중하고 싶다면, 알고랩이 키움 OpenAPI+ 환경 구축부터 봇 제작·무중단 운영까지 통합 제작해드립니다.