Codex CLI 이미지 입력 방법: --image로 오류 스크린샷 처음 붙이는 법

TL;DR

핵심 3줄 요약

이 글에서 다룰 내용

Codex CLI 이미지 입력은 무엇이고 언제 쓰면 좋은가

터미널 오류를 복사할 수 있어도 화면 배치와 주변 상태까지 글로 옮기기는 번거롭습니다. IDE 경고, 브라우저 레이아웃 깨짐, 테스트 실패 화면처럼 시각적 맥락이 문제의 일부일 때 이미지 입력이 유용합니다.

Codex CLI 이미지 입력은 로컬 이미지 파일을 첫 프롬프트의 맥락으로 첨부해 Codex가 화면을 살펴보게 하는 기능입니다. 공식 문서는 오류 스크린샷, 아키텍처 다이어그램, 디자인 참고 이미지를 예로 듭니다. 대화형 작성기에 이미지를 붙여 넣는 방법도 안내합니다.

이미지 입력과 이미지 생성은 목적이 다릅니다. 기존 화면이나 다이어그램을 검토하려면 이미지 입력을 사용합니다. 새 이미지를 만들거나 편집하려는 작업은 이미지 생성 기능의 범위입니다.

시작 전에 확인할 조건과 경계

공식 Codex 명령어 문서는 --image, -i 의 입력값을 path[,path...] 로 설명합니다. 한 장 이상을 첫 프롬프트에 붙일 수 있으며 여러 경로는 쉼표로 나누거나 같은 옵션을 반복합니다.

공식 이미지 입력 문서는 PNG와 JPEG를 포함한 일반 이미지 형식을 지원한다고 안내합니다. 다만 해당 문서에서 계정별 제공 조건, 지역, 최대 파일 크기, 정확한 전체 확장자 목록은 따로 확인되지 않습니다. 현재 환경에서 옵션이 보이지 않거나 첨부가 실패하면 설치된 Codex CLI와 공식 문서의 현재 화면을 다시 확인하세요.

스크린샷에는 API 키, 토큰, 고객 정보, 내부 주소가 보일 수 있습니다. 첨부 전에 문제와 무관한 영역을 잘라 내고 민감정보가 남지 않았는지 사람이 확인합니다. 이미지가 화면 밖의 로그나 실행 상태까지 증명한다고 가정해서도 안 됩니다.

--image로 오류 스크린샷을 처음 붙이는 순서

1. 문제 영역이 보이는 이미지를 준비합니다

오류 문구, 파일명, 줄 번호, 문제가 난 UI 영역이 읽히도록 캡처합니다. 공식 문서가 명시한 일반 형식인 PNG나 JPEG로 저장하세요.

전체 화면을 무조건 붙이지 않습니다. 문제와 상관없는 알림, 계정명, 저장소 주소, 비밀값은 자르거나 제거한 뒤 저장한 이미지를 다시 열어 확인합니다.

2. 이미지 경로를 확인합니다

현재 프로젝트 폴더에서 이미지 위치를 확인합니다. 예시에서는 screenshot.png 를 프로젝트 폴더에 둡니다.

명령에 넣을 경로가 실제 파일을 가리키는지 먼저 확인하세요. 이 단계는 이미지가 빠진 채 텍스트 요청만 전달되는 상황과 경로 문제를 구분하는 데 도움이 됩니다.

3. -i와 첫 프롬프트를 한 명령에 넣습니다

공식 문서의 첫 예시는 다음과 같습니다.

codex -i screenshot.png "Explain this error and suggest the smallest fix"

처음부터 수정을 맡기지 말고 관찰과 확인 순서부터 요청하세요.

codex -i screenshot.png "화면에서 직접 확인되는 오류 문구와 위치를 적고, 추정 원인은 따로 구분해줘. 아직 파일은 수정하지 말고 확인할 파일과 명령만 제안해줘."

4. 긴 옵션 --image도 같은 방식으로 씁니다

-i 대신 --image 를 사용할 수 있습니다.

codex --image screenshot.png "오류 화면에서 직접 읽을 수 있는 사실을 적고 다음 확인 순서를 제안해줘."

명령을 실행한 뒤 답변이 실제 이미지의 파일명·오류 문구·UI 위치를 제대로 짚었는지 확인합니다. 읽지 못한 부분을 그럴듯하게 채웠다면 그 내용을 근거로 수정하지 않습니다.

5. 여러 이미지는 역할을 나눠 설명합니다

공식 문서는 쉼표로 경로를 구분하거나 --image 를 반복하라고 안내합니다. 예시는 다음과 같습니다.

codex --image before.png,after.png "두 화면을 비교하고 퇴행한 항목만 목록으로 정리해줘."

이미지가 여러 장이면 “첫 번째는 변경 전, 두 번째는 변경 후”처럼 역할을 적습니다. 비교 대상과 바꾸지 말아야 할 범위도 함께 지정하세요.

6. 실제 파일과 로그를 확인한 뒤 수정합니다

Codex가 읽은 오류 문구를 원본 로그와 대조합니다. 제안된 원인이 실제 코드와 설정에 있는지 관련 파일을 열어 확인하세요.

수정이 필요하다면 허용 파일과 검증 명령을 정한 뒤 별도 승인합니다. 변경 뒤에는 diff와 테스트 결과를 읽고 가능하면 새 스크린샷으로 화면 상태도 다시 확인합니다.

그대로 복사해 쓸 프롬프트

이 요청문은 진단을 확정하지 않습니다. 이미지에서 읽은 사실과 실제 프로젝트 근거를 연결하는 첫 점검표를 만듭니다.

실전 활용 팁

주의할 점

자주 묻는 질문

출처

마무리

Codex CLI에서 오류 스크린샷을 처음 붙일 때는 codex -i screenshot.png "요청" 으로 시작하면 됩니다. 긴 표기인 --image 를 써도 되고 여러 장은 쉼표나 반복 옵션으로 첨부합니다.

이미지에서 직접 보이는 사실과 추정 원인을 분리해 달라고 요청하세요. 답변을 받은 뒤에는 원본 로그, 관련 파일, diff, 테스트 결과를 사람이 확인해야 이미지 입력을 안전한 디버깅 시작점으로 쓸 수 있습니다.