IDE 없는 CLI 터미널 환경에서 Codex와 Playwright MCP 웹 자동화 구축

아래 안내만 따라 하시면 VS Code 없이도 터미널에서 Codex CLI로 Playwright MCP를 붙여 웹 자동화(접속, 클릭, 스크린샷, PDF 저장 등)를 실전에서 바로 쓰실 수 있습니다.

빠른 요약 (TL;DR)

1. Rust 설치 → Codex CLI 설치

   sudo apt update
   sudo apt install -y build-essential pkg-config libssl-dev curl git
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source $HOME/.cargo/env
   
   git clone https://github.com/openai/codex.git ~/openai/codex
   cd ~/openai/codex
   cargo install --path codex-rs/cli
   
   echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   codex --version

2. Playwright 런타임 준비

   # Node 필요. 없다면: sudo apt install -y nodejs npm
   npx playwright install chromium   # 또는 전체: npx playwright install

3. ~/.codex/config.toml에 MCP 서버 등록

   model = "gpt-5-codex"
   
   [mcp_servers.playwright]
   command = "npx"
   args = ["-y", "@modelcontextprotocol/server-playwright"]
   startup_timeout_sec = 20
   tool_timeout_sec = 60

4. 확인

   codex mcp list
   codex mcp get playwright --json

5. 사용(예시)

   # 대화 시작(터미널 인터랙티브)
   codex chat
   # 프롬프트 예: “Playwright 도구로 https://example.com 접속→ 제목 추출→ 스크린샷을 ./shot.png 로 저장”

배경 & 구성 이해

• Codex CLI: 터미널에서 모델과 상호작용하고, 필요 시 도구(툴) 를 호출해 작업(파일 수정, 로컬 명령, 웹 자동화 등)을 수행합니다. VS Code 플러그인 없이 단독 사용 가능.
• MCP (Model Context Protocol): 모델이 도구/리소스를 안전하게 호출하도록 하는 표준 프로토콜.
  • Codex는 config.toml의 [mcp_servers.<id>] 정의에 따라 외부 MCP 서버를 표준 입출력(stdio) 로 실행해 도구를 로딩합니다.
  • HTTP(S)/SSE 기반 MCP 서버는 직접 연결이 아니라 mcp-proxy 같은 어댑터를 통해 붙일 수 있습니다(필요 시).
• Playwright MCP 서버: 브라우저 자동화를 MCP 툴로 노출해 주는 Node 패키지. npx로 간편 실행.

설치 상세 (Ubuntu 24.04 기준)

1. Rust & Codex CLI

sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev curl git
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

git clone https://github.com/openai/codex.git ~/openai/codex
cd ~/openai/codex

# 핵심: CLI는 이 경로입니다 (codex-rs/cli)
cargo install --path codex-rs/cli

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
codex --version

🔎 과거 오류 정리

• cargo: command not found → rustup 설치 필요
• --path cli is not a directory → 실제 경로는 codex-rs/cli
• codex: command not found → $HOME/.cargo/bin PATH 추가 필요

2. Playwright 준비

# Node가 없다면 설치
sudo apt install -y nodejs npm

# Playwright 브라우저 설치
npx playwright install chromium
# 또는 전부 설치: npx playwright install

서버/CI에서 헤드리스로 쓸 때 디스플레이 필요 시

sudo apt install -y xvfb
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99

Codex 설정 (~/.codex/config.toml)

1. 최소 설정 + Playwright MCP

# 모델
model = "gpt-5-codex"

# (권장) 기본은 읽기전용 샌드박스
# sandbox_mode = "read-only"

# Playwright MCP 서버(표준 입출력 기반)
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-playwright"]
startup_timeout_sec = 20
tool_timeout_sec = 60

# (선택) 네트워크·쓰기 작업이 필요하면 workspace-write로 전환
# sandbox_mode = "workspace-write"
# [sandbox_workspace_write]
# network_access = true

패키지 매니저 대체

• pnpm: command = "pnpm", args = ["dlx", "@modelcontextprotocol/server-playwright"]
• bun: command = "bunx", args = ["@modelcontextprotocol/server-playwright"]

2. 환경변수/프록시/브라우저 캐시

[mcp_servers.playwright]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-playwright"]
env = { "PLAYWRIGHT_BROWSERS_PATH" = "0", "HTTP_PROXY" = "http://proxy:3128", "HTTPS_PROXY" = "http://proxy:3128" }
startup_timeout_sec = 20
tool_timeout_sec = 90

3. 쉘 환경 필터(민감정보 차단)

[shell_environment_policy]
inherit = "core"
exclude = ["AWS_*", "AZURE_*"]
# include_only = ["PATH", "HOME", "USER"]   # 더 엄격히 할 때

동작 확인 & 기초 사용

1. 서버 인식 확인

codex mcp list
codex mcp get playwright
codex mcp get playwright --json    # 제공 툴/리소스 목록 확인

2. 기본 프롬프트 예시 (대화형)

codex chat

아래처럼 지시하세요(모델이 Playwright MCP를 자동 선택/호출):

• “Playwright 도구로 https://example.com 접속한 뒤, 페이지 제목을 추출해서 알려줘.”
• “위 페이지의 스크린샷을 ./shot.png로 저장해줘.”
• “검색창에 ‘wazuh’ 입력 → 제출 → 첫 결과 링크 텍스트 5개를 리스트로 출력해줘.”

📝 도구 이름/파라미터는 서버 버전에 따라 다릅니다.
codex mcp get playwright --json으로 실제 툴 시그니처를 확인하고, 프롬프트에서 해당 툴의 파라미터 명(예: url, path, selector)을 그대로 써주면 정확도가 올라갑니다.

300x250

실전 시나리오 예시

1. 스크린샷 자동화

프롬프트(예)

“Playwright 툴로 https://news.sites.com 방문 → 첫 화면을 ./hn.png로 저장. 뷰포트는 1366x768, 로딩 완료까지 대기.”

2. 데이터 스크래핑(내부 테스트용)

“https://example.com/prices에서 .item 카드의 .name과 .price를 모두 수집해 JSON으로 반환. 5초 대기 후 콘텐츠 로딩 확인.”

3. PDF 렌더링

“https://example.com/report 페이지를 A4, 여백 10mm, 배경 그래픽 포함으로 ./report.pdf 에 저장.”

4. 폼 제출 + 결과 검증

“https://httpbin.org/forms/post 폼의 custname에 Pages in Korea, custtel에 010-0000-0000 입력 후 제출. 결과 페이지의 텍스트에 Pages in Korea 포함 여부를 불리언으로 알려줘.”

보안 점검 포인트

1. 권한 최소화(기본 정책)
   • 기본은 sandbox_mode = "read-only" 권장.
   • 꼭 필요한 작업에 한해서만 workspace-write + network_access = true 사용.
   • danger-full-access는 금지 수준(POC/격리 환경에서만).
2. 실행 바이너리/패키지 신뢰성
   • MCP 서버 패키지의 버전 고정(예: @modelcontextprotocol/server-playwright@x.y.z) 및 해시 검증을 고려.
   • 사내 레지스트리/미러로 공급망 리스크 축소.
3. 프록시/아웃바운드 제어
   • Playwright가 나가는 도메인 화이트리스트(테스트 대상만) + L7 로깅 활성화.
   • 파일 저장 경로를 격리된 워크스페이스로 지정하고, 외부 업로드 자동화 금지.
4. 환경변수·비밀관리
   • mcp_servers.<id>.env에는 민감정보 저장 금지. 필요 시 런타임에만 주입, 범위 최소화.
   • shell_environment_policy로 *KEY*, *TOKEN* 등 자동 필터 유지(기본값) + 추가 exclude.
5. 승인(Approval) 정책
   • 운영: approval_policy = "untrusted" 또는 "on-failure" 권장.
   • 개발/POC: "on-request" 가능. "never"는 CI/격리 환경 한정.
6. 감사·포렌식
   • ~/.codex/history.jsonl 보관(권한 600).
   • 외부 로깅: notify 훅으로 JSON 이벤트를 수신 → SIEM/Wazuh/Slack 연동.
   • MCP 호출(툴·파라미터·대상 URL) 감사 로그 남기기.
7. 브라우저 샌드박스/헤드리스
   • Playwright 자체의 헤드리스/권한 제한 옵션 활용.
   • 서버 환경은 Xvfb 또는 컨테이너 seccomp/AppArmor 병행 적용.
8. 데이터 최소화
   • 스크린샷/HTML 덤프에 민감정보 포함되지 않도록 테스트 URL/시나리오를 엄격 분리.
   • 산출물 자동 업로드 금지, 로컬 격리 디렉토리 사용.

운영 팁 & 트러블슈팅

• 서버 시작 지연 → startup_timeout_sec = 30 정도로 증가
• 도구 호출 타임아웃 → tool_timeout_sec = 120
• 브라우저 없음 오류 → npx playwright install 재실행, 오프라인이면 미러/캐시 지정
• 헤드리스 렌더 실패 → DISPLAY=:99 (Xvfb) 또는 Playwright 옵션에서 headless: true 확인
• 네트워크 차단 → workspace-write 모드 + [sandbox_workspace_write].network_access = true
• PATH 문제 → $HOME/.cargo/bin PATH 설정 재확인
• 툴 시그니처 불명확 → codex mcp get playwright --json으로 정확한 파라미터명 확인 후 프롬프트 수정

고급 설정(선택)

1. CLI에서 MCP 항목 추가/조회(실험적)

codex mcp add playwright -- npx -y @modelcontextprotocol/server-playwright
codex mcp list
codex mcp get playwright

2. 모델 추론/출력 제어

# 응답 길이/디테일 (Responses API 대상)
model_verbosity = "medium"  # low/medium/high

# 추론 노력/요약
model_reasoning_effort = "medium"  # minimal/low/medium/high
model_reasoning_summary = "concise"  # auto/concise/detailed/none

활용사례 아이디어

• 크롤링 QA: 사내 포털 접근성 점검(네비게이션 가능 여부, ARIA 속성 유무)
• CI 파이프라인: 배포 후 헬스체크 + 스크린샷 저장, 실패 시 Slack 알림
• 보안검증 지원: 로그인 화면의 오류 메시지 과다 노출 여부, 비밀번호 정책 안내 존재 여부 등 UI 보안 점검 자동화

체크리스트

• codex CLI 최신 설치 및 PATH 반영
• ~/.codex/config.toml에 [mcp_servers.playwright] 등록
• sandbox_mode 기본 read-only 유지 (필요 시 최소한으로 완화)
• 프록시/도메인 화이트리스트/로깅 적용
• 민감 환경변수 전달 차단(shell_environment_policy)
• notify/SIEM 연계로 호출·산출물 추적성 확보
• 정기 패키지 업데이트 + 버전 고정(서명/해시 검증)