코덱스(Codex) CLI 사용법: 블로그 본문 구조 점검 도구 만들기

Codex CLI로 HTML 파일의 제목과 인용 블록을 집계하는 작은 도구를 만듭니다. 결과를 미리 아는 HTML 파일로 시험하고, 출력이 다를 때 고쳐 달라고 요청하는 순서를 설명합니다.

홍승협(준이아빠)게시 2026.08.16수정 2026.10.04약 20분

지금까지 100명 넘게 읽었어요, 63%가 끝까지 읽었어요

#AI #바이브코딩 #자동화 #SEO

코덱스(Codex) CLI 사용법: 블로그 본문 구조 점검 도구 만들기 대표 이미지

준이아빠AI가 일하는 법AI 친구들의 작업실 구경하기 ↗

설치 다음에는 작은 도구 하나를 만듭니다
실행 환경과 작업 폴더 준비
결과를 미리 아는 HTML 파일
Codex에 실행 방법과 기대값을 함께 주는 요청
codex exec로 파일 만들기
직접 실행해 기대값과 맞춰 보기
개수를 점수로 바꾸지 않는 이유
실행되는 도구와 믿고 쓰는 도구
참고 자료
3줄 요약

세 줄로 먼저 읽기

Codex CLI의 codex exec는 대화 화면 없이 요청을 한 번 실행하며 --sandbox workspace-write를 붙여야 작업 폴더에 파일을 씁니다.
요청문에는 node check.mjs sample.html 같은 실행 방법과 h2 2개, 질문형 1개, blockquote 1개 같은 기대값, 수정해도 되는 파일 범위를 함께 적습니다.
집계 도구가 매긴 자체 점수는 임의 배점의 합계이고, Google은 AI 검색을 위해 특별한 문장 구성이나 전용 구조화 데이터가 필요하지 않다고 안내합니다.

설치 다음에는 작은 도구 하나를 만듭니다

Codex CLI는 터미널에서 파일을 읽고 만들며 명령을 실행하는 OpenAI의 AI 도구입니다. 설치를 마쳐도 무엇부터 맡길지 정하기는 쉽지 않습니다. 여기서는 블로그 본문 HTML에 소제목(h2)과 인용 블록(blockquote)이 몇 개 있는지 집계하는 도구를 만들고, 그 도구가 맞게 작동하는지 시험합니다.

맥 설치 안내나 윈도우 설치 안내를 마치고 로그인한 상태에서 시작합니다. 순서는 준비, 요청, 결과 대조, 수정 요청입니다. Codex를 실행할 때마다 계정 사용량이 차감됩니다.

이 도구는 GEO 작업을 하며 글 구조를 훑어볼 때 쓸 수 있습니다. GEO는 생성형 AI의 검색 답변에서 콘텐츠가 발견되고 인용되도록 개선하는 활동입니다. 다만 구조를 집계하는 일과 글이 정확하고 유용한지, 실제로 인용되는지를 평가하는 일은 다릅니다. Google도 AI 검색을 위해 특별한 문장 구성이나 전용 구조화 데이터가 필요하지 않다고 안내합니다. GEO 개념은 생성형 엔진 최적화 이해하기에서 이어 볼 수 있습니다.

실행 환경과 작업 폴더 준비

이번 도구는 JavaScript를 컴퓨터에서 실행하는 프로그램인 Node.js로 돌아갑니다. Codex 설치에는 Node.js가 없어도 되지만, 여기서 만들 check.mjs를 실행하려면 필요합니다. 없다면 Node.js 공식 다운로드에서 LTS 버전을 내려받습니다. LTS는 장기간 지원하는 버전입니다.

도구를 만들기 전 준비 순서

1. 버전 확인codex, node, git
세 명령 모두 버전이 나오면 성공
2. 새 폴더 만들기중요한 자료와 떨어진
빈 작업 폴더
3. git init폴더를 로컬 저장소로 준비
.git 폴더가 생기면 성공

1. 버전을 확인합니다. 일반 터미널에서 아래 명령을 하나씩 실행합니다. Codex 대화 입력칸이 아니라 터미널에 입력합니다.

codex --version
node --version
git --version

세 명령 모두 버전 숫자가 나오면 다음으로 갑니다. node나 git을 찾을 수 없다고 나오면 그 프로그램을 설치하고 터미널을 다시 엽니다. Git은 파일 변경 이력을 관리하는 프로그램이고, 여기서는 codex exec가 요구하는 저장소를 준비하는 데 씁니다. 설치 방법은 Git 공식 설치 안내에 있습니다.

2. 새 작업 폴더를 만들고 3. 저장소로 준비합니다. 같은 이름의 폴더가 이미 있다면 다른 이름을 씁니다. macOS 터미널에서는 한 줄씩 실행합니다.

mkdir -p ~/Projects/blog-structure-practice
cd ~/Projects/blog-structure-practice
pwd
git init

Windows PowerShell에서는 다음을 실행합니다.

New-Item -ItemType Directory -Force -Path "$HOME\Projects\blog-structure-practice"
Set-Location "$HOME\Projects\blog-structure-practice"
Get-Location
git init

표시된 경로가 방금 만든 폴더이면 성공입니다. git init은 이 폴더를 로컬 저장소로 준비하는 명령이며 인터넷에 아무것도 올리지 않습니다. 실행 뒤 기본 브랜치 이름에 관한 안내가 나와도 정상이고, 숨김 폴더 .git이 생깁니다.

결과를 미리 아는 HTML 파일

도구의 출력이 맞는지 보려면 개수를 이미 아는 파일이 하나 필요합니다. macOS에서는 터미널에 open ., Windows에서는 explorer .를 입력하면 지금 폴더가 열립니다. VS Code 같은 텍스트 편집기로 아래 내용을 sample.html로 저장합니다.

<!doctype html>
<html lang="ko">
<head><meta charset="utf-8"><title>독서 모임</title></head>
<body>
<h1>독서 모임 안내</h1>
<h2>언제 만나나요?</h2>
<p>2026년 10월 12일에 만납니다.</p>
<h2>준비물</h2>
<blockquote>읽은 책 한 권을 가져옵니다.</blockquote>
</body>
</html>

저장할 때는 한글이 깨지지 않도록 UTF-8을 고릅니다. macOS 텍스트 편집기에서는 먼저 서식 메뉴에서 일반 텍스트로 바꿉니다. Windows 메모장에서는 다른 이름으로 저장할 때 파일 형식을 모든 파일로 고르고, 파일 이름이 sample.html.txt로 저장되지 않았는지 봅니다.

h2는 두 번째 수준의 제목을, blockquote는 인용문을 표시하는 HTML 태그입니다. 이 파일의 개수는 아래와 같고, 이 숫자가 도구의 출력과 맞춰 볼 기대값입니다.

sample.html의 기대값

2개h2 제목
1개물음표로 끝나는 h2언제 만나나요?
1개blockquote

실제 웹페이지에는 메뉴나 다른 글 목록의 제목도 섞여 있습니다. 이 작은 파일로 통과한 도구라도 실제 페이지에서는 본문 밖의 제목까지 집계할 수 있습니다.

Codex에 실행 방법과 기대값을 함께 주는 요청

요청을 파일에 적어 두면 어떤 조건을 전달했는지 나중에 다시 볼 수 있습니다. 같은 폴더에 prompt.txt를 만들고 아래 내용을 UTF-8로 저장합니다.

이 폴더의 sample.html을 읽는 본문 구조 점검 도구를 만들어 줘.
사용 방법은 node check.mjs sample.html로 해 줘.

출력할 항목:
- h2 태그 개수
- h2 제목 중 물음표로 끝나는 제목 개수
- blockquote 태그 개수

확인 기준:
- 현재 sample.html에서는 순서대로 2개, 1개, 1개가 나와야 해.
- 없는 파일을 입력하면 파일을 찾지 못했다고 안내하고 실패 상태로 종료해.
- 개수를 AI 인용 점수나 검색 순위 점수로 바꾸지 마.

작업 범위:
- Node.js 기본 기능만 사용하고 외부 패키지나 인터넷은 사용하지 마.
- check.mjs와 README.md만 새로 만들고 sample.html과 prompt.txt는 수정하지 마.
- 이름이 같은 결과 파일이 이미 있으면 덮어쓰지 말고 상황을 알려 줘.
- README.md에 실행 방법과 복잡한 HTML을 처리할 때의 한계를 적어 줘.
- 만든 뒤 정상 입력과 없는 파일을 각각 시험하고 실제 결과를 알려 줘.
- 환경이나 권한 문제로 시험하지 못하면 완료했다고 하지 말고 이유를 남겨 줘.

"알아서 끝까지 해 줘"라고만 쓴 요청과 비교하면, 이 요청에는 결과가 맞는지 판단할 기준이 들어 있습니다.

요청문에 기준이 있을 때 달라지는 것

요청에 담긴 것	알아서 해 줘한 줄 요청	prompt.txt기준을 적은 요청
실행 명령	제공하지 않음	제공
맞춰 볼 기대값	제공하지 않음	제공
만들고 고칠 수 있는 파일	제공하지 않음	제공
오류 입력 시험과 결과 보고	제공하지 않음	제공

같은 요청에도 Codex는 매번 다른 코드를 만들 수 있습니다. 그래서 기대값을 요청에 넣어 두고, 결과도 직접 실행해서 맞춰 봅니다.

codex exec로 파일 만들기

codex exec는 대화 화면 없이 요청을 한 번 실행하는 명령입니다. 실행하면 실제 AI 작업이 시작됩니다. 폴더에 sample.html과 prompt.txt가 있는지 본 뒤, 아래 명령을 입력합니다. 명령은 macOS와 Windows에서 같습니다.

codex exec --sandbox workspace-write "prompt.txt를 읽고 그 안의 요청을 수행해 줘."

--sandbox workspace-write는 작업 폴더 안에 파일을 쓸 수 있게 하는 옵션입니다. exec는 기본이 읽기 전용이라 설정을 바꾸지 않았다면 이 옵션 없이는 파일을 만들지 못합니다. 권한은 사용자 설정이나 연결된 도구에 따라서도 달라집니다. 요청문에 적은 작업 범위는 Codex에 주는 지시일 뿐이고, 폴더 안 다른 파일의 수정을 기술적으로 막는 장치는 아닙니다.

이 작업에는 인터넷이 필요하지 않습니다. 접속 오류가 나더라도 전체 접근 권한을 켜거나 요청과 관계없는 설정을 바꾸지 않습니다. Git 저장소 관련 오류가 나오면 지금 경로와 git init 실행 여부부터 봅니다.

작업이 끝나면 폴더에 check.mjs와 README.md가 생겼는지 봅니다. 답변에 "완료"라고 적혀 있어도 파일이 실제로 생겼는지, 시험 결과가 적혀 있는지는 따로 봐야 합니다.

직접 실행해 기대값과 맞춰 보기

이제 Codex가 아니라 일반 터미널에서 도구를 직접 실행합니다. 정상 입력과 없는 파일을 차례로 넣고, 각각 종료 코드까지 봅니다. 종료 코드는 프로그램이 끝날 때 남기는 숫자이며 0은 정상 종료입니다.

터미널, blog-structure-practice

node check.mjs sample.html

h2 2개
물음표로 끝나는 h2 1개
blockquote 1개

기대값 2, 1, 1과 같은지 봅니다

node check.mjs missing.html

파일을 찾지 못했습니다 missing.html

echo $?

설명을 위해 만든 화면입니다. 출력 문구는 Codex가 만든 코드마다 다릅니다.

1. 정상 입력을 넣습니다. node check.mjs sample.html을 실행합니다. 출력 문구는 코드마다 달라도 숫자는 h2 2개, 질문형 h2 1개, blockquote 1개여야 합니다. 이어서 macOS에서는 echo $?, PowerShell에서는 $LASTEXITCODE를 입력해 0이 나오는지 봅니다.

2. 없는 파일을 넣습니다. missing.html이 실제로 없는 상태에서 node check.mjs missing.html을 실행합니다. 파일을 찾지 못했다는 안내가 나오고, 바로 이어서 확인한 종료 코드가 0이 아닌 값이면 성공입니다.

3. 숫자가 다르면 같은 대화에서 고쳐 달라고 합니다. codex resume을 입력하면 이전 대화 목록이 나옵니다. 방금 작업한 대화를 고르고, 작업 폴더가 맞는지 본 뒤 아래처럼 실제 개수와 출력을 함께 알려 줍니다.

sample.html의 h2는 2개이고 그중 "언제 만나나요?" 하나가 물음표로 끝나.
그런데 질문형 제목이 0개라고 나와.
현재 파일을 확인해 check.mjs를 수정해 줘.
정상 입력과 없는 파일 시험을 다시 해 줘. 원본 HTML은 바꾸지 마.

다른 대화를 골랐다면 요청을 보내지 말고 종료한 뒤 다시 고릅니다. 수정이 끝나면 1번과 2번을 직접 다시 실행해 숫자가 맞는지 봅니다.

개수를 점수로 바꾸지 않는 이유

이 도구를 온라인 글 주소를 받는 점검기로 넓히면 정의 문장, JSON-LD, 질문형 소제목처럼 볼 항목이 늘어납니다. JSON-LD는 페이지의 내용을 정해진 형식으로 설명하는 구조화 데이터입니다. 항목이 있는지 확인하는 일과 그 내용이 정확한지 판단하는 일은 별개입니다.

항목마다 배점을 정해 총점을 내게 하면 아래처럼 점수가 나옵니다.

85점은 이 스크립트가 임의로 정한 배점의 합계입니다. Codex나 검색 서비스의 공식 평가도, 실제 인용 확률도 아닙니다. 질문형 소제목 항목이 0점이어도 글의 품질은 따로 판단할 일이라서, 점수를 올리려고 질문형 제목을 늘리지 않습니다. 정의 문장이나 인용 블록도 내용에 필요할 때 씁니다. 앞의 요청문에 "개수를 점수로 바꾸지 마"를 넣은 이유가 여기에 있습니다.

온라인 주소를 처리하도록 넓힐 때는 공개 페이지를 읽을 권한, 접속 실패, 메뉴와 본문 구분, JavaScript로 나중에 표시되는 내용을 따로 다뤄야 합니다. 로컬 파일 하나로 통과한 시험은 이 문제들을 다루지 않습니다.

실행되는 도구와 믿고 쓰는 도구

코드를 모두 이해하지 못해도 작은 도구를 만들고 시험할 수는 있습니다. 그러나 "실행됐다"는 것만으로 정확하고 안전하다고 볼 수는 없습니다. 실제 업무 자료에 쓰기 전에 아래 순서를 거칩니다.

실제 자료에 쓰기 전에 거칠 단계

1. 정상 입력 시험기대값을 아는 파일로
숫자가 맞는지
2. 오류 입력 시험없는 파일, 빈 파일에서
실패로 끝나는지
3. 코드와 범위 검토README의 한계와
읽고 쓰는 파일
4. 실제 자료 연결중요한 자료와 외부 서비스는
마지막에

다른 사람에게 도구를 넘길 때는 check.mjs, README.md, 개인정보가 없는 예제 파일을 함께 보냅니다. 받는 사람의 컴퓨터에도 Node.js가 있어야 하고, 새 폴더에서 같은 숫자가 나오는지 시험해 보게 합니다. 계정 정보나 Codex 대화 기록은 보내지 않습니다.

2026년 10월 4일 안내 기준으로 Codex CLI의 이용 조건은 ChatGPT 앱의 무료 이용 조건과 다릅니다. 지원 요금제와 사용량, 별도 API 결제 조건은 공식 요금 안내에 정리돼 있습니다.

참고 자료

3줄 요약

Codex CLI의 codex exec는 대화 화면 없이 요청을 한 번 실행하며 --sandbox workspace-write를 붙여야 작업 폴더에 파일을 씁니다.
요청문에는 node check.mjs sample.html 같은 실행 방법과 h2 2개, 질문형 1개, blockquote 1개 같은 기대값, 수정해도 되는 파일 범위를 함께 적습니다.
집계 도구가 매긴 자체 점수는 임의 배점의 합계이고, Google은 AI 검색을 위해 특별한 문장 구성이나 전용 구조화 데이터가 필요하지 않다고 안내합니다.

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

예제 HTML에 h2가 2개, blockquote가 1개 있을 때 먼저 확인할 것은 무엇인가요?

이 글이 도움이 되었나요?

이 글 다음 배우기코딩 에이전트 입문입문 코스 · 9편

코딩 에이전트가 무엇이고 도구마다 무엇이 다른지, 비개발자 눈높이로 고르는 기준까지

코스 전체 보기 →

이어서 읽기 좋은 글Claude Code 단축키와 슬래시 명령어 정리 →

Claude Code 안에 입력할 명령과 터미널에서 쓸 명령을 구분합니다. 대화에 이름을 붙여 다시 여는 순서와 요약, 중단, 변경 확인에 쓰는 명령을 상황별로 정리했습니다.