Codex SEO란 무엇인가
Codex SEO는 OpenAI Codex CLI에서 실행되는 무료 오픈 소스 SEO 감사 스킬입니다. 웹사이트 주소만 제공하면 사이트를 검사하고, 서로 관련 없는 경고 목록이 아니라 우선순위가 정렬된 실행 계획을 생성합니다.
이 프로젝트는 Agrici Daniel의 claude-seo를 포팅한 것으로, 상위 프로젝트의 감사 방법, 스킬 및 스크립트를 Codex CLI에 맞게 적용했습니다. MIT 라이선스를 사용하며 사이트별 요금을 부과하지 않고, 타사 SEO 서비스 설치도 요구하지 않습니다.
Codex SEO 자체는 오픈 소스이며 사이트별 요금이 없지만, 감사를 실행할 때는 현재 Codex 세션에 설정된 모델을 사용합니다. 전체 감사에는 여러 역할을 실행하므로 일반적으로 단일 페이지 분석보다 더 많은 토큰이 소비됩니다.
핵심 기능
Codex SEO는 26개의 하위 스킬과 19개의 전문가 역할 스크립트로 구성됩니다. 전체 감사를 실행하면 최대 17개의 역할이 차례로 웹사이트를 분석하고, 각 역할의 발견 사항을 파일로 저장해 근거를 남깁니다.
- 기술 SEO: 크롤링 가능성, 색인 단서, XML sitemap, robots.txt, 리디렉션, 페이지 속도 및 Core Web Vitals를 점검합니다.
- 콘텐츠 및 E-E-A-T: 경험, 전문성, 권위성, 신뢰성, 저품질 콘텐츠 및 주제 범위를 분석합니다.
- 구조화된 데이터: 기존 Schema.org 마크업을 발견하고 검증하며, 권장 마크업도 생성할 수 있습니다.
- AI 검색 및 GEO: Google AI Overviews, AI Mode, ChatGPT, Perplexity 및 Gemini에 페이지가 인용될 가능성을 평가합니다.
- 에이전트 준비도: AI Agent 접근, llms.txt, Markdown, WebMCP 등의 관련 기능을 점검합니다.
- 로컬 및 이커머스 SEO: Google Business Profile, 리뷰, 지도 팩, 상품 페이지 및 다국어 웹사이트를 다룹니다.
- 전략 및 지속적인 모니터링: 업종별 계획, 경쟁사 페이지, 콘텐츠 브리프, 의미론적 클러스터링 및 SQLite 스냅샷 기반 SEO 변동 모니터링을 제공합니다.
설치 전 준비
시작하기 전에 다음 환경을 준비해야 합니다.
- 스킬을 지원하는 OpenAI Codex CLI
- Python 3.11~3.14
- 저장소를 복제하기 위한 Git
기본적으로 SEO 서비스 API key는 필요하지 않습니다. 설치 프로그램은 스킬을 Codex가 사용자 스킬을 검색하는 위치인 ~/.agents/skills/에 복사합니다. 또한 헤드리스 브라우저가 포함된 격리된 Python 런타임을 생성하며, 시스템 전역 Python 환경은 수정하지 않습니다.
Codex SEO 설치
macOS 및 Linux
저장소를 복제하고 설치 스크립트를 실행합니다.
git clone --depth 1 https://github.com/zhtyyx/codex-seo.git
bash codex-seo/install.shWindows PowerShell
PowerShell에서 실행합니다.
git clone --depth 1 https://github.com/zhtyyx/codex-seo.git
powershell -ExecutionPolicy Bypass -File codex-seo\install.ps1초기화 및 환경 점검
격리된 런타임과 Chromium을 생성하거나 새로 고쳐야 한다면 Codex CLI에서 다음을 실행합니다.
$seo setup시스템을 수정하지 않고 환경만 점검하려면 다음을 실행합니다.
$seo doctor$seo doctor는 읽기 전용 점검 명령으로, 설치 후 또는 문제가 발생했을 때 의존성 상태를 확인하는 데 적합합니다.
첫 SEO 감사 실행
- 터미널에서
codex를 실행해 Codex CLI를 시작합니다. $seo로 스킬을 호출합니다.- 분석할 웹사이트 또는 페이지 주소를 제공합니다.
- 각 전문가 역할의 분석이 완료되면 생성된 실행 계획을 확인합니다.
codex
$seo audit https://example.com$seo audit는 전체 사이트 감사를 실행하므로, 처음 웹사이트의 전반적인 문제를 파악할 때 적합합니다. 시스템은 SaaS, 로컬 서비스, 이커머스, 콘텐츠 사이트 또는 에이전시 등의 비즈니스 유형을 자동으로 식별하고, 그에 따라 점검 항목을 조정합니다.
다음과 같이 자연어로 직접 요청할 수도 있습니다.
SEO 감사를 진행해 주세요. 주소는 https://example.com입니다자주 사용하는 입문 명령 4가지
전체 사이트 감사
$seo audit https://example.com전체 전문가 프로세스를 실행하고, 우선순위에 따라 정렬된 수정 및 최적화 계획을 출력합니다. 각 권장 사항에는 중요도, 판단 근거, 의존 항목 및 적용 여부를 검증하는 방법이 설명됩니다.
단일 페이지 심층 분석
$seo page https://example.com/pricing가격 페이지, 제품 페이지, 랜딩 페이지 또는 글 페이지만 관심이 있다면 단일 페이지 분석을 사용해 비용이 더 높은 전체 감사를 바로 실행하는 것을 피할 수 있습니다.
AI 검색 준비도 분석
$seo geo https://example.com이 명령은 생성형 엔진 최적화를 대상으로 하며, 페이지가 AI 검색에 인용되기 쉬운지, AI 크롤러가 접근할 수 있는지, Wikipedia, Reddit, YouTube 및 LinkedIn 등의 공개 플랫폼에서 브랜드가 얼마나 존재감을 갖는지 평가합니다.
구조화된 데이터 점검
$seo schema https://example.com이 명령은 페이지의 Schema.org 마크업을 발견하고 검증하며, 구조화된 데이터 생성에 대한 권장 사항을 제공합니다.
목표에 따른 감사 명령 선택
기술 SEO
$seo technical https://example.com: 9개 주요 영역의 기술 감사를 실행합니다.$seo sitemap https://example.com: 웹사이트의 XML sitemap을 분석합니다.$seo sitemap generate: XML sitemap을 생성합니다.$seo images https://example.com: 이미지 최적화 문제를 분석합니다.$seo hreflang https://example.com: 다국어 hreflang 설정을 감사하거나 생성합니다.$seo programmatic https://example.com: 프로그램 방식 SEO를 분석하고 계획합니다.$seo unlighthouse https://example.com: 로컬에서 여러 페이지의 Lighthouse 분석을 수행합니다.
콘텐츠 및 검색 경험
$seo content https://example.com: E-E-A-T 및 콘텐츠 품질을 분석합니다.$seo content-brief 목표 주제: 목표 키워드, 개요 및 내부 링크 권장 사항이 포함된 콘텐츠 브리프를 생성합니다.$seo cluster 목표 키워드: SERP 기반 의미론적 클러스터링을 수행합니다.$seo sxo https://example.com: 페이지 유형, 사용자 스토리 및 사용자 페르소나 등의 검색 경험 요소를 분석합니다.$seo competitor-pages https://example.com: 경쟁사 비교 페이지 권장 사항을 생성합니다.
로컬, 백링크 및 이커머스
$seo local https://example.com: GBP, 인용, 리뷰 및 지도 팩 성과를 점검합니다.$seo maps [command]: geo-grid, GBP 감사 및 경쟁사 반경 등의 지도 인텔리전스 기능을 사용합니다.$seo backlinks https://example.com: Moz, Bing 및 Common Crawl 등의 출처를 통해 백링크 프로필을 분석합니다.$seo ecommerce https://example.com: 이커머스 SEO 및 시장 인텔리전스 분석을 수행합니다.
전체 감사의 작동 방식
- 웹사이트 유형 식별: 먼저 웹사이트가 SaaS, 로컬 서비스, 이커머스, 콘텐츠 사이트 또는 에이전시 중 어디에 해당하는지 판단하고 이후 점검 범위를 조정합니다.
- 전문가의 순차 분석: 기술, 콘텐츠, 구조화된 데이터, 속도 및 AI 검색 등의 역할이 순서대로 작업을 실행합니다.
- 발견 사항 저장: 각 역할이 완료되면 자체 발견 사항 파일을 저장해 결론의 근거를 남깁니다.
- 문제 점수화: 시스템은 발견 사항을 단순히 발생 순서대로 표시하지 않고 점수를 매깁니다.
- 실행 계획 생성: 최종 보고서는 권장 사항을 우선순위에 따라 구성하고, 이유, 의존 관계 및 검증 방법을 설명합니다.
보고서는 기본적으로 Markdown으로 저장됩니다. PDF가 필요하다면 Codex에 “PDF 보고서 생성”을 요청하고 $seo google report를 통해 출력할 수 있습니다.
고급 사용 팁
소규모 분석 후 전체 사이트 감사 실행
전체 $seo audit는 기본 세션에서 최대 17개의 역할을 실행하므로 단일 페이지 점검보다 많은 토큰을 소비합니다. 대규모 웹사이트라면 먼저 $seo page, $seo technical, $seo content 또는 $seo schema를 사용해 주요 페이지를 검증한 다음 전체 사이트 감사를 실행할지 결정할 수 있습니다.
업종별 전략 계획 생성
$seo plan은 SaaS, 로컬 서비스, 이커머스, 콘텐츠 퍼블리셔 및 에이전시 등의 유형을 지원합니다.
$seo plan saas
$seo plan local
$seo plan ecommerce
$seo plan publisher
$seo plan agency비즈니스에 맞는 유형을 사용하면 올바른 검색 상황을 중심으로 계획을 수립하는 데 도움이 됩니다.
Google 데이터 연결
Codex SEO는 API key 없이 사용할 수 있습니다. 실제 필드 데이터를 사용하려면 다음 명령을 실행해 무료 Google API를 설정할 수 있습니다.
$seo google setup연결할 수 있는 데이터에는 PageSpeed Insights, Chrome UX Report, Google Search Console 및 GA4가 포함됩니다. 키는 로컬 컴퓨터에만 저장됩니다.
Google API key를 설정하지 않으면 Core Web Vitals는 실험적 추정치이며, 색인 상태도 주로 페이지 정보를 바탕으로 추론됩니다. 중요한 의사결정에는 실제 필드 데이터 및 검색 플랫폼 데이터를 함께 사용해 재확인해야 합니다.
SEO 변동 모니터링
Codex SEO는 SQLite 스냅샷을 통해 기준선을 설정하고, 변경 사항을 비교하며, 기록을 확인할 수 있습니다.
$seo drift baseline https://example.com
$seo drift compare https://example.com
$seo drift history https://example.com이 명령 그룹은 사이트 개편, 마이그레이션, 템플릿 업데이트 또는 지속적인 콘텐츠 게시 후 SEO 상태가 변했는지 점검하는 데 적합합니다.
AI Agent의 웹사이트 사용 가능 여부 점검
$seo agentic https://example.com이 명령은 Lighthouse Agentic Browsing X/N, AI 에이전트 액세스, llms.txt, Markdown 및 WebMCP 등의 항목을 검사합니다. $seo geo와는 중점이 다릅니다. 전자는 에이전트가 웹사이트를 사용할 수 있는 기능에 초점을 맞추고, 후자는 생성형 검색에서 페이지의 검색 가능성과 인용 가능성에 더 중점을 둡니다.
JavaScript 웹사이트 감사
Codex SEO는 Next.js, React, Vue 및 JavaScript 렌더링에 의존하는 기타 웹사이트를 지원합니다. 페이지에 콘텐츠를 표시하려면 JavaScript 실행이 필요한 경우 자동으로 헤드리스 브라우저를 사용하고 방문자에게 표시되는 페이지를 기준으로 감사합니다.
핵심 콘텐츠가 스크롤이나 클릭 후에만 로드되면 결과에 여전히 잡음이 발생할 수 있습니다. 이러한 상호작용 영역은 수동으로 확인하고, 자동 감사 결과를 브라우저의 실제 동작과 대조하는 것이 좋습니다.
선택적 확장 기능
기본 감사에는 유료 확장 기능이 필요하지 않지만, 프로젝트는 몇 가지 선택적 통합을 제공합니다. 이러한 서비스를 사용하려면 해당 계정이나 구성을 직접 준비해야 합니다.
$seo image-gen [use-case]: SEO 자료용 AI 이미지를 생성합니다.$seo seranking [command]: ChatGPT, Gemini, Perplexity, AI Overviews 및 AI Mode에서 AI 점유율을 분석합니다.$seo profound [command]: LLM 인용 및 시간 경과에 따른 추이를 추적합니다.$seo bing [command] https://example.com: Bing 웹마스터 도구 및 IndexNow 제출 기능을 사용합니다.
개인정보 보호, 범위 및 제거
데이터 처리 방식
Codex SEO는 Codex CLI에서 실행되며, 분석 대상 페이지와 관련 데이터는 현재 Codex 세션을 지원하는 OpenAI 모델로 전송됩니다. 처리 방식은 다른 Codex 작업과 동일합니다. 생성된 보고서는 파일 형태로 로컬 컴퓨터에 저장됩니다.
확장 기능이나 API를 직접 연결하지 않는 한 추가 SEO 서비스로 데이터가 전송되지 않습니다. 일부 검사는 Wikipedia, Reddit 및 Common Crawl과 같은 공개 출처를 읽을 수 있습니다.
유의해야 할 범위
- Google API에 연결하지 않으면 Core Web Vitals는 실험적 추정치입니다.
- 실제 플랫폼 데이터에 연결하지 않으면 색인 상태는 주로 페이지를 기반으로 추론됩니다.
- 스크롤, 클릭 또는 복잡한 상호작용을 통해서만 핵심 콘텐츠를 로드하는 페이지에서는 잡음이 발생할 수 있습니다.
- 전체 감사에는 더 많은 토큰이 사용되므로 웹사이트 규모에 따라 명령을 선택해야 합니다.
제거
더 이상 사용하지 않는 경우 저장소에서 제공하는 제거 스크립트를 실행할 수 있습니다.
bash uninstall.sh이 명령은 설치된 스킬을 제거합니다.
마무리
Codex SEO는 기술 검사, 콘텐츠 품질, Schema, GEO, 로컬 SEO, 전자상거래 SEO 및 지속적인 모니터링을 Codex CLI에 통합합니다. 먼저 $seo doctor로 환경을 확인한 다음 $seo page 또는 전문 명령으로 작업 흐름을 익히고, 마지막으로 $seo audit을 사용해 전체 우선순위 실행 계획을 생성하는 것이 좋습니다.
전체 매개변수와 확장 구성은 프로젝트의 GitHub 저장소 및 저장소에 포함된 설치, 명령, 아키텍처, 문제 해결, 보안 및 개인정보 보호 문서에서 확인할 수 있습니다.