Menu
Search, reserve, inspect, and cancel KTX or Korail tickets in Korea with the korail2 + pycryptodome Python packages. Use when the user asks for KTX seats, Korail bookings, train changes, reservation status, remaining seat numbers, car-by-car seats, or power-outlet/good-seat tips.
| name | ktx-booking |
| description | Search, reserve, inspect, and cancel KTX or Korail tickets in Korea with the korail2 + pycryptodome Python packages. Use when the user asks for KTX seats, Korail bookings, train changes, reservation status, remaining seat numbers, car-by-car seats, or power-outlet/good-seat tips. |
| license | MIT |
| metadata | {"category":"travel","locale":"ko-KR","phase":"v1"} |
korail2 위에 scripts/ktx_booking.py helper 를 얹어 KTX/Korail 조회, 호차별 좌석번호 확인, 예약, 예약 확인, 취소를 처리한다.
최근 Korail 앱의 Dynapath anti-bot 체크 때문에 원본 korail2 0.4.0 예제만으로는 MACRO ERROR 가 날 수 있다. 이 스킬은 helper 가 x-dynapath-m-token, Sid, 최신 app version(250601002)을 붙여 실제 예매 흐름을 복구하는 것을 전제로 한다.
python3 -m pip install korail2-ncard pycryptodomeKSKILL_KTX_IDKSKILL_KTX_PASSWORD~/.config/k-skill/secrets.env (기본 fallback) — plain dotenv 파일, 퍼미션 0600.기본 경로에 저장하는 것은 fallback일 뿐, 강제가 아니다.
YYYYMMDDHHMMSStrain_idpython3 -c 'import korail2, Crypto' 가 실패하면 다른 구현으로 우회하지 말고 전역 Python 패키지 설치를 먼저 시도한다.
python3 -m pip install korail2-ncard pycryptodome
KSKILL_KTX_ID, KSKILL_KTX_PASSWORD 환경변수가 설정되어 있는지 확인한다. 없으면 위 credential resolution order에 따라 확보한다.
시크릿이 없다는 이유로 웹사이트를 직접 긁거나 다른 비공식 경로를 찾지 않는다.
항상 helper 를 통해 조회한다.
python3 scripts/ktx_booking.py search 서울 부산 20260328 090000 --limit 5
기본 --train-type 은 ktx 다. ITX-청춘(예: 남춘천↔용산)·ITX-새마을·무궁화호처럼 KTX 외 노선을 잡으려면 --train-type 으로 지정한다.
python3 scripts/ktx_booking.py search 남춘천 용산 20260503 150000 --train-type itx-cheongchun
선택지: ktx, itx-saemaeul, mugunghwa, nuriro, tonggeun, itx-cheongchun, airport, all.
예약 단계(reserve)에서도 같은 --train-type 값을 그대로 넘겨야 stable train_id 매칭이 깨지지 않는다.
좌석이 없는 열차도 후보에 포함하려면 --include-no-seats, 예약 대기 가능한 열차도 같이 보고 싶으면 --include-waiting-list 를 붙인다.
예매 전에 항상 아래를 확인한다.
indextrain_idtrain_type)search 의 좌석 가능 여부는 열차 단위 플래그다. 사용자가 "남은 좌석 번호", "호차별 좌석", "콘센트", "꿀팁 좌석", "창측/순방향 자리", "예약 전에 자리 확인"처럼 구체적인 좌석을 물으면 예약 전에 seats 를 호출한다.
기본 상세 좌석 조회:
python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id>
일반실/특실은 --room 으로 나눈다.
python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --room special
남은 좌석번호만 보고 싶으면 --available-only 를 쓴다.
python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --available-only
특정 호차를 지정하지 않으면 seats 는 승강장 이동 거리가 짧은 가운데 호차부터 탐색한다. 각 호차 안의 좌석은 콘센트 힌트가 있는 좌석(direct, adjacent)을 먼저, 같은 조건에서는 순방향 좌석을 먼저 보여준다.
특정 호차만 확인하려면 --car-no 를 쓴다.
python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --car-no 5 --available-only
콘센트 꿀팁 자리부터 확인하려면 --power-only 를 붙인다. 응답의 power_outlet 은 direct, adjacent, none 중 하나다.
python3 scripts/ktx_booking.py seats 서울 부산 20260328 090000 --train-id <train_id> --available-only --power-only
seats 도 search 와 같은 --train-type 을 넘겨야 한다. ITX-청춘 등 KTX 외 열차를 조회했다면 상세 좌석 조회에도 같은 값을 사용한다.
python3 scripts/ktx_booking.py seats 남춘천 용산 20260503 150000 \
--train-id <train_id> \
--train-type itx-cheongchun \
--available-only
상세 좌석 응답을 보여줄 때는 사용자 의도에 맞춰 아래를 우선 요약한다.
remaining_seats, available_seat_countavailable_seats)direction, position, seat_typepower_outlet)near_door)이 기능은 좌석을 선택/선점하지 않는다. 실제 예약은 다음 단계의 reserve 로만 진행한다.
조회 결과의 train_id 를 고른 뒤에만 예약한다. 이 값은 helper 가 열차 번호/운행일/시각/역 코드를 묶어 만든 stable selector 이므로, 재조회 시 같은 열차가 아직 있으면 그대로 잡고 없으면 실패한다.
python3 scripts/ktx_booking.py reserve 서울 부산 20260328 090000 --train-id <train_id> --seat-option general-first
ITX 등 KTX 외 노선을 search 단계에서 골랐다면 reserve 에도 똑같이 --train-type 을 넘긴다.
python3 scripts/ktx_booking.py reserve 남춘천 용산 20260503 150000 --train-id <train_id> --train-type itx-cheongchun --seat-option general-first
응답에는 예약번호, 운임, 구입기한이 포함된다. 결제는 자동화하지 않는다.
좌석이 없을 때는 조회 단계에서 --include-waiting-list 를 켜고 예약 단계에서 --try-waiting 으로 예약 대기까지 시도할 수 있다.
N카드 할인을 적용하려면 먼저 보유 N카드 목록을 조회해 카드 번호를 확인한다.
python3 scripts/ktx_booking.py ncard-list
N카드로 할인 열차를 조회한다 (--ncard-index 는 ncard-list 결과의 순번). ncard-list 는 로그/셸 노출을 줄이기 위해 카드 번호를 마스킹해 출력한다.
python3 scripts/ktx_booking.py ncard-search 대전 서울 20260512 100000 --ncard-index 1 --train-type ktx
응답의 train_id 를 복사해 reserve 에 같은 --ncard-index 를 붙여 예약한다.
python3 scripts/ktx_booking.py reserve 대전 서울 20260512 100000 \
--train-id <train_id> \
--ncard-index 1
--ncard-index 를 지정하면 --adults 등 승객 옵션은 무시되고 N카드 승객 1명으로 처리된다. --ncard-no 직접 입력도 지원하지만 셸 히스토리에 남을 수 있어 권장하지 않는다. 결제는 자동화하지 않는다.
N카드 기능은 korail2-ncard 패키지가 필요하다. 없으면 해당 커맨드 실행 시 설치 안내가 출력된다.
취소는 대상 예약을 다시 조회해 식별한 뒤에만 진행한다.
python3 scripts/ktx_booking.py reservations
python3 scripts/ktx_booking.py cancel <reservation_id>
scripts/ktx_booking.py 는 upstream korail2 anti-bot 회귀를 보완하는 helper 다korail2 는 KTX/Korail 전용 표면이라 train type 과 passenger model 이 분명하다Use when the user asks for nearby restaurants or 근처 맛집 and wants 블루리본 picks. Always ask the user's current location first, then search official Blue Ribbon nearby restaurants via k-skill-proxy.
네이버 지도(NAVER Cloud Platform Maps) 기반 출발지→목적지 자동차 길찾기·지오코딩·역지오코딩을 k-skill-proxy 경유로 조회한다. 수동 입력 MVP, mock 기본, live opt-in.
Look up available Korean national forest recreation lodging or camping slots on foresttrip.go.kr. Use when the user asks for 숲나들e or 자연휴양림 빈 객실/빈자리 조회, not for booking.
Kakao Local (장소 검색·주소-좌표 변환) + Kakao Mobility (자동차 길찾기) 를 k-skill-proxy 경유로 조회한다. 사용자 키 불필요.
Convert incoming Korean text into a deterministic Korean Middle Korean-style rewrite with archaic particles, endings, Hanja hints, and tone-mark flavor.
After installing the full k-skill bundle, configure and verify the shared cross-platform setup, then optionally wire update checks and GitHub starring with explicit user consent.