Claude Code와 Codex용 html2wp 플러그인

설치

플러그인은 GitHub 저장소 두 곳에 있습니다. 하나는 Claude Code용, 하나는 Codex용입니다. 두 저장소의 내용과 버전 번호는 같습니다. 다른 점은 각 도구가 플러그인을 불러오는 방식뿐입니다. 다른 쪽 저장소는 불러와지지 않으므로 사용하는 도구에 맞는 저장소를 설치하세요.

사용하는 도구로 전환한 뒤 두 명령을 차례로 실행하세요.

첫 번째 명령은 GitHub에서 플러그인 카탈로그(마켓플레이스)를 추가합니다. 두 번째 명령은 그 카탈로그에서 html2wp를 설치합니다. Codex는 .agents/plugins/marketplace.json 파일로 플러그인을 찾는데, Claude Code 저장소에는 이 파일이 없어서 Codex용 저장소가 따로 필요합니다.

업데이트

업데이트 명령의 이름은 도구마다 다릅니다. Codex에서는 upgrade, Claude Code에서는 update입니다.

설치된 버전을 보려면 Codex에서 codex plugin list를 실행하세요. Claude Code에서는 /plugin → Marketplaces → html2wp로 이동합니다.

업데이트한 뒤에도 Codex의 버전이 바뀌지 않았다면 Codex에 오래된 사본이 저장되어 있는 것입니다. 사본을 지우고 플러그인을 다시 설치하세요.

그래도 해결되지 않으면 Codex에 수동 설치로 생긴 또 다른 오래된 사본이 있을 수 있습니다. codex plugin marketplace list 명령은 모든 카탈로그를 출력합니다. 목록에 html2wp@<other-name>이 보이면 codex plugin remove html2wp@<that-name>으로 제거하세요.

작업 대부분은 html2wp 서비스에서 이루어지고 서비스는 스스로 업데이트되므로, 다음 변환은 이미 새 버전으로 실행됩니다. 업데이트해야 하는 것은 내 컴퓨터에서 실행되는 부분, 즉 검사, 스크립트, 외부로 나가는 데이터의 필터뿐입니다. 버전별 변경 사항은 GitHub의 커밋 기록에 있습니다.

요구 사항

직접 확인할 필요는 없습니다. 변환을 시작하면 플러그인이 먼저 컴퓨터를 검사하고 빠진 것을 알려 줍니다.

Node.js                ok        v22.14.0
Python                 ok        3.12.4
Playwright             MISSING   mirroring, prerendering and every screenshot
Docker                 NOT RUNNING  installed, but the daemon is not up

Playwright나 chromium 브라우저처럼 사용자 폴더에만 설치되는 패키지는 플러그인이 대신 설치해 주겠다고 제안합니다. 명령을 실행할 때마다 먼저 묻습니다. Docker Desktop이나 새 Node.js처럼 시스템 전체를 바꾸는 것은 알리기만 하고, 직접 설치할 때까지 기다립니다.

Python 패키지를 직접 설치하려면 다음을 실행하세요.

사용할 모델

변환하는 동안 AI는 많은 결정을 내려야 합니다. 예를 들어 어느 페이지가 홈페이지인지, 검사가 왜 실패했는지, 두 스크린샷의 차이를 클라이언트가 알아차리기나 할지 같은 것입니다. 그래서 모델 선택은 다른 어떤 설정보다 결과에 큰 영향을 줍니다.

Claude Code에서는 Opus 5가 작업을 하고, 변환이 가장 자주 잘못되는 중요한 결정에서 Fable 5에게 조언을 구합니다.

라이선스 키

무료 요금제에서는 키가 필요 없으니 이 부분은 건너뛰세요. 라이선스가 있다면 첫 변환 전에 키를 컴퓨터에 저장하세요. 이 작업은 어느 폴더에서든 한 번만 하면 됩니다.

키를 환경 변수 H2WP_KEY로 넘길 수도 있으며, 이 경우 파일보다 우선합니다. 파일 쪽이 더 안전합니다. 키가 터미널 기록에 남지 않기 때문입니다.

이 파일에는 Pro를 구매할 때 받은 html2wp 라이선스 키를 넣습니다. Visual Edit Pro 키는 여기에 넣지 않습니다. 그 키는 편집하는 사이트의 Visual Edit 플러그인에 입력하며, 변환에는 쓸 수 없습니다.

키가 유효한지, 어디에 쓸 수 있는지, 언제까지인지 확인하려면 npx html2wp-license YOUR-KEY를 실행하세요. 결과의 의미는 라이선스 페이지의 키 확인 항목에서 설명합니다. 라이선스에 포함되는 내용과 구매 방법은 라이선스 페이지에 있습니다.

프로젝트 변환

변환할 프로젝트 폴더에서 터미널을 열고 그곳에서 에이전트를 시작하세요.

Claude Code를 쓴다면 마지막 줄에 codex 대신 claude를 입력하세요.

그다음 에이전트에게 명령 하나만 주면 됩니다.

이것으로 끝입니다. npm install이나 npm run build를 실행할 필요도, 따로 설정할 것도 없습니다. Bolt, v0, shadcn 프로젝트나 Next.js export도 같은 방식으로 변환됩니다. Claude Code에서 /html2wp:html2wp만 입력하거나 Codex에 html2wp를 사용하라고 요청해도 됩니다. 그러면 플러그인이 무엇을 변환할지 묻습니다.

변환의 처음 몇 분

> convert this project

  Checking this machine first…
    Node.js     ok    v22.14.0
    Playwright  MISSING
  Two Python packages are missing. Shall I install them? (they go in your
  user directory, no root)

> yes

  … installed. Building the project, then prerendering it.
  7 routes found: /, /about, /pricing, /blog, /blog/launch, /contact, /faq
  Decided: /blog is the listing, /blog/launch an article, the rest are pages.
  Written to the manifest; carrying on.

마지막 몇 줄에는 플러그인이 페이지를 어떻게 분류했는지 기록되어 있습니다. /blog는 글 목록, /blog/launch는 글이고 나머지는 일반 페이지입니다. 이 결정은 마지막에 완성된 사이트에서 확인하세요.

다른 입력

convert this project 명령은 현재 있는 폴더를 변환합니다. 파일이 다른 곳에 있다면 convert ./dist처럼 경로를 입력하세요.

입력은 항상 내 디스크에 있어야 합니다. 플러그인은 운영 중인 사이트의 주소를 변환하지 않습니다. 브라우저에 보이는 화면이 아니라 사이트를 구성하는 파일이 필요합니다.

Lovable 프로젝트가 변환되는 방식

Lovable 앱은 React로 만들어집니다. 앱의 index.html에는 빈 요소 하나와 스크립트만 있고, 페이지는 브라우저 안에서야 만들어집니다. 그래서 플러그인은 먼저 프로젝트를 빌드하고, 실제 브라우저에서 열어 각 페이지를 완성된 HTML로 저장합니다. 펼친 아코디언이나 드롭다운 메뉴처럼 스크립트가 실행된 뒤에야 나타나는 콘텐츠도 담아 둡니다. 그런 다음 이 페이지들로 테마를 만듭니다. 자세한 내용은 Lovable에서 WordPress로 옮기는 가이드에 있습니다.

플러그인이 대신 정하는 것

어느 페이지가 무엇인지

결과에 가장 큰 영향을 주는 결정은 하나입니다. 어느 페이지가 홈페이지이고, 어느 것이 글 목록이며, 어느 것이 글이고 상품인지입니다. 플러그인은 페이지 코드를 보고 이를 판단해 기록한 뒤 묻지 않고 계속 진행합니다. 판단할 수 없을 때만 멈춥니다. 예를 들어 사이트의 페이지 수가 한도를 넘거나, 두 페이지가 같은 페이지처럼 보일 때입니다.

이 판단이 틀려도 고치는 비용은 적습니다. 분류를 바로잡고 변환을 다시 실행하면 됩니다. 이것은 재실행이며 변환 한도에서 차감되지 않습니다.

그다음은 대부분 알아서 진행됩니다

페이지 수와 컴퓨터 속도에 따라 Flash는 약 30분, Full은 약 1시간이 걸립니다. 그동안 플러그인은 사이트를 빌드하고, 원본과 비교하고, 변환을 위해 html2wp 서비스로 보냅니다. 그 후 완성된 테마를 내 컴퓨터의 Docker에 있는 임시 WordPress에 설치하고 그곳에서 테스트합니다.

건너뛸 수 없는 검토

마지막에 플러그인은 각 페이지를 원본과 나란히 한 이미지로 보여 줍니다. 모든 이미지를 보고 무엇이 보이는지 말해 주세요.

받게 되는 결과물

• ZIP 파일로 된 테마. WordPress의 외모(Appearance) → 테마 → 새로 추가 → 테마 업로드에서 업로드합니다. 플러그인은 망가진 테마는 아예 만들지 않습니다. 예를 들어 PHP에 문법 오류가 있거나, 콘텐츠가 빠졌거나, 테마 스크린샷의 크기가 틀렸거나, 쇼핑몰에서 아무것도 살 수 없는 경우입니다.
• 보고서 CONVERSION-REPORT.md는 ZIP과 같은 폴더에 있습니다. 변환된 페이지, 연결된 메뉴, 검토에서 발견한 모든 것, 변환 중의 모든 경고, 아직 남은 작업이 적혀 있습니다.
• Visual Edit Lite 링크도 함께 받습니다. 클릭해서 편집하는 무료 에디터입니다. 에디터는 테마에 포함되지 않으며, 테마는 에디터 없이도 작동합니다. Visual Edit Pro는 별도의 유료 라이선스입니다.

테마는 독립형입니다. 페이지, 블로그, 양식, 메뉴, SEO, 리디렉션이 테마 코드에 들어 있어 플러그인 없이 작동합니다. 코드는 읽기 쉬운 PHP, CSS, JavaScript입니다. 코드는 사용자의 소유이며 저희에게 묶여 있지 않습니다. 테마는 외부 어디에도 연결하지 않습니다. 클릭으로 편집하는 방법은 앱 문서의 Visual Edit 부분에 있습니다.

컴퓨터 밖으로 나가는 데이터

브라우저 작업은 내 컴퓨터가 합니다. 페이지 빌드, 스크린샷 비교, 최종 검사를 위한 Docker의 임시 WordPress 실행이 여기에 해당합니다. 테마 자체는 html2wp 서비스가 만듭니다. 그래서 플러그인은 빌드된 사이트를 서비스로 보내고 테마를 돌려받습니다.

테마 검사는 사용자 쪽에서 실행되므로 서비스는 그 결과를 보지 못합니다. 그래서 플러그인이 마지막에 결과를 서비스로 보냅니다. 이 전송은 필수입니다. 이전 변환이 결과를 보내기 전에는 서비스가 다음 변환을 시작하지 않습니다.

• 전송되는 것: 검사 이름, 통과 여부, 페이지 수, 가장 낮은 일치율, 실패한 페이지의 짧은 이름(about, pricing 등)입니다.
• 전송되지 않는 것: 사이트 주소나 도메인, 코드, 텍스트, 스크린샷, 파일 경로, 라이선스 키, 사이트 이름입니다. 플러그인은 미리 정한 필드만 보내고 그 밖에는 아무것도 보내지 않습니다.
• 직접 확인하기: send-verdicts.sh <workspace> --dry-run 명령은 전송될 내용을 그대로 출력하지만 실제로는 아무것도 보내지 않습니다. 직접 읽어 볼 수 있는 짧은 스크립트 하나입니다.

플러그인은 다른 데이터를 보내지 않으며, 완성된 테마는 아무것도 보내지 않습니다. 데이터 보관 기간을 포함한 전체 설명은 개인정보 페이지에 있습니다.

버그 신고

변환기 자체가 실수를 하면 다음 명령으로 신고하세요.

모든 신고는 사람이 읽습니다. 수정 사항은 서비스에 반영되므로 모든 사용자에게 도움이 됩니다.