이 영상에서 단테는 Codex CLI의 non-interactive 모드와, JSON Schema로 응답 형식을 지정해 받는 커스텀 출력 기능을 직접 실행해 보며 설명합니다. Codex를 CI나 자체 애플리케이션에 붙여 사람 대신 프로그램이 호출하게 만들고 싶은 개발자에게 맞는 내용입니다.
interactive 모드와 non-interactive 모드
지금까지 Codex를 쓸 때는 보통 한 턴씩 번갈아 대화했습니다. 질문하면 답이 오고, 답에 피드백을 주면 다시 답이 오는 식입니다. 이렇게 사용자와 상호작용하며 대화를 이어 가는 방식을 interactive 모드라고 합니다. 사용자가 명시적으로 종료하지 않으면 대화가 계속됩니다.
반대로 요청 한 번에 답변 한 번만 받고 추가 대화를 하지 않는 방식이 non-interactive 모드입니다. 사람이 쓰기에는 대화형이 편해 보이는데, 굳이 non-interactive 모드가 필요한 이유는 무엇일까요.
단테의 설명은 이 모드가 사람보다 프로그램끼리 통신할 때 쓰기 좋다는 것입니다. 예를 들어 코드를 작성해 GitHub에 올리면, CI(지속적 통합) 과정에서 테스트를 돌리거나 코드 리뷰를 받는 작업이 이어집니다. 이때 CI 서버가 Codex에게 코드 리뷰를 요청한다고 해 봅시다. interactive 모드라면 서버가 언제 대화를 끝내야 할지 고민해야 합니다. non-interactive 모드라면 한 번 요청하고 응답을 받으면 바로 다음 단계로 넘어가 결과를 전달할 수 있습니다.
codex exec로 실행하기
Codex CLI는 codex 명령 뒤에 하위 명령을 붙여 non-interactive 모드를 지원합니다. exec 명령 끝에 프롬프트를 이어 붙이면 됩니다.
codex exec "<프롬프트>"
실행하면 사용자 턴과 Codex의 응답이 출력되고, 응답이 끝나면 그대로 종료됩니다. 대화가 이어지지 않으므로 스크립트나 CI 단계 안에서 호출하기 좋습니다.
JSON Schema로 응답 형식 정하기
non-interactive 모드와 함께 알아 두면 좋은 기능이 사용자 정의 형식으로 응답을 받는 것입니다. 이를 위해 JSON Schema 파일을 준비합니다. JSON Schema는 일반 JSON 데이터가 아니라 "데이터가 어떤 필드와 타입으로 구성되어야 하는지"를 정의하는 형식이며, 자세한 스펙은 공식 페이지에서 확인할 수 있습니다.
영상의 스키마는 응답에 status, summary, next steps 세 필드를 포함하도록 정의했습니다. 앞에서는 응답을 텍스트로만 받았지만, 이 스키마를 넘기면 세 필드가 들어간 JSON으로 받을 수 있습니다. 실행할 때는 --output-schema 옵션에 스키마 파일을 넘기고, 현재 디렉터리에 대한 추가 확인 없이 바로 실행해도 된다는 옵션을 함께 붙였습니다.
codex exec --output-schema schema.json "<프롬프트>"
스키마 파일이 JSON Schema 형식을 제대로 지키면 별다른 오류 없이 실행됩니다. 단테는 다이어트를 어떻게 시작하면 좋은지 물었고, 응답은 다음과 같은 구조로 왔습니다.
- status: success
- summary: 건강 검진과 목표 설정으로 시작해 식단과 운동 계획을 세우고, 점검과 기록으로 조정하며 장기 유지 전략까지 준비해야 한다는 요약
- next steps: 배열 형태로, 기초 건강 검진과 현재 식습관·활동량 기록으로 출발점 파악하기, 현실적인 체중·체지방 목표 세우기, 자신에게 맞는 식단과 운동 설계하기 등
왜 구조화된 출력이 유용한가
애플리케이션 안에서 Codex와 직접 소통하는 단계가 있고, 그 결과를 프론트엔드에 보여 줘야 한다고 가정해 봅시다. 응답이 정해진 필드로 오면 프론트엔드 개발자는 status, summary, next steps 필드만 신경 쓰면 됩니다. 자유 텍스트를 파싱해 필요한 부분을 뽑는 고민은 하지 않아도 되고, 필드를 채우는 일은 Codex가 맡습니다. 영상에서는 다이어트 예시를 썼지만, 코드 리뷰 결과를 같은 방식으로 받아 Slack 같은 협업 도구로 보내거나 화면에 그리는 것도 간단해집니다.
단테가 꼽은 JSON Schema의 장점은 두 가지입니다. 첫째, 잘못된 형식의 데이터가 들어오면 애플리케이션이 앞단에서 바로 잡아낼 수 있어 데이터가 오염되지 않습니다. 둘째, Codex 같은 AI 에이전트에게 "데이터는 이렇게 생겼다"는 지침을 주는 효과가 있어 더 정확한 응답을 받는 데 도움이 됩니다.
다음 영상에서는 이 커스텀 출력으로 코드 리뷰를 받아 HTML에 그대로 표시하는 실습을 이어서 다룰 예정이라고 예고했습니다.
정리
- interactive 모드는 사람과 턴을 주고받는 방식이고, non-interactive 모드는 요청 한 번에 응답 한 번으로 끝나는 방식입니다.
- non-interactive 모드는 CI 코드 리뷰처럼 프로그램이 Codex를 호출하는 상황에 적합하며,
codex exec뒤에 프롬프트를 붙여 실행합니다. --output-schema에 JSON Schema 파일을 넘기면 응답을 정해진 필드의 JSON으로 받을 수 있습니다.- 구조화된 출력은 프론트엔드 표시, 협업 도구 연동을 단순하게 만들고, 잘못된 데이터를 앞단에서 걸러 줍니다.