이 부분은 교사가 외울 내용이 아닙니다. 직접 설정하거나 실습을 도와주는 사람이 실행 순서와 근거를 확인할 때 사용합니다.
준비와 프로필 분리
공식 요구 사항에 맞는 Node.js LTS와 npm, 안정 버전 Chrome, OpenCode를 승인된 절차로 준비합니다. opencode --version, node --version, npm --version, npx --version으로 설치 여부를 확인합니다. 설치 후 명령을 찾지 못하면 새 터미널에서 PATH를 확인합니다. Windows 실행 정책에 막히면 승인된 npm.cmd, npx.cmd를 사용하되 실행 정책을 완화하지 않습니다.
Chrome 136부터 기본 사용자 데이터 폴더에 원격 디버깅 옵션이 적용되지 않습니다. 아래처럼 비기본 --user-data-dir가 필요합니다. 기존 프로필을 복사하지 않습니다. 예시의 teacher-browser-profile이 이미 다른 용도이거나 동기화되는 위치라면 승인된 별도 로컬 경로로 바꿉니다. 같은 전용 프로필을 사용 중인 이전 실습 창은 먼저 닫습니다. 평소 Chrome은 닫을 필요가 없습니다.
Windows PowerShell
다음 명령은 일반적인 설치 위치를 찾고 전용 Chrome을 엽니다. 관리자 권한은 필요하지 않습니다.
$candidates = @(
"$env:ProgramFiles\Google\Chrome\Application\chrome.exe",
"${env:ProgramFiles(x86)}\Google\Chrome\Application\chrome.exe",
"$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe"
)
$chrome = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1
if (-not $chrome) { throw "Chrome path not found. Check the approved installation path." }
$profile = Join-Path $env:USERPROFILE "teacher-browser-profile"
Start-Process -FilePath $chrome -ArgumentList @(
'--remote-debugging-address=127.0.0.1',
'--remote-debugging-port=9222',
"--user-data-dir=`"$profile`"",
'https://example.com/'
)
사용자 지정 설치라면 Chrome 바로가기 속성에서 실행 파일 경로를 확인하고 $chrome에 실제 경로를 넣어 실행 부분을 사용합니다. 프로필 경로의 따옴표는 사용자 이름의 공백을 보존합니다.
macOS 터미널
일반적인 시스템 설치에서는 다음을 실행합니다. sudo는 사용하지 않습니다.
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--remote-debugging-address=127.0.0.1 \
--remote-debugging-port=9222 \
--user-data-dir="$HOME/teacher-browser-profile" \
https://example.com/
사용자별 설치가 ~/Applications에 있다면 첫 줄을 "$HOME/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"으로 바꿉니다. 다른 설치 위치는 Finder에서 확인합니다. 실행 로그가 계속 나오는 터미널은 그대로 두고 다음 확인은 새 탭에서 합니다.
로컬 연결 확인
전용 창의 chrome://version에서 프로필 경로가 teacher-browser-profile 아래인지 확인하고 그 탭을 닫습니다. 공개 연습 페이지만 남깁니다. Windows에서는 다음을 실행합니다.
Get-NetTCPConnection -LocalPort 9222 -State Listen |
Select-Object LocalAddress, LocalPort, OwningProcess
Invoke-RestMethod http://127.0.0.1:9222/json/version |
Select-Object Browser, webSocketDebuggerUrl
macOS에서는 다음을 실행합니다.
lsof -nP -iTCP:9222 -sTCP:LISTEN
curl --fail --silent --show-error http://127.0.0.1:9222/json/version
수신 주소가 127.0.0.1 또는 ::1 같은 루프백이고 JSON에 Browser, webSocketDebuggerUrl이 있는지 확인합니다. 이것은 Chrome의 응답 확인이며 아직 AI 연결 성공은 아닙니다. 0.0.0.0, *, :: 등 전체 인터페이스 수신이거나 다른 프로세스가 포트를 쓰면 중단하고 원인을 확인합니다. 다른 프로세스를 임의로 종료하지 않습니다. 방화벽 개방이나 포트 포워딩은 하지 않습니다. 디버깅 연결 정보는 대화나 공유 문서에 붙여 넣지 않습니다. 루프백도 같은 컴퓨터의 다른 프로그램으로부터 완전히 격리되는 것은 아닙니다.
OpenCode 연결 설정
teacher-web-assistant/opencode.json이 있으면 안전한 로컬 사본을 두고 기존 설정을 보존합니다. mcp 아래에 다음 chrome-devtools 항목만 병합합니다. 동일 이름이 있으면 수정하며 중복 키를 만들지 않습니다. 다음 전체 예시는 새 파일일 때만 그대로 사용합니다.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"chrome-devtools": {
"type": "local",
"command": [
"npx",
"-y",
"chrome-devtools-mcp@latest",
"--browser-url=http://127.0.0.1:9222",
"--no-usage-statistics",
"--no-performance-crux"
],
"enabled": true
}
}
}
OpenCode 형식은 실행 파일과 인수를 command 배열에 함께 넣습니다. 여기서 type은 local입니다. Chrome의 HTTP 주소를 원격 MCP 서버로 설정하지 않습니다. Windows에서 npx를 찾지 못하면 PATH와 설치를 확인하고 필요하면 첫 항목에 npx.cmd나 승인된 실행 파일 경로를 사용합니다.
-y는 패키지 설치 확인을 자동 수락하고 @latest는 최신 패키지를 가져오므로 설치 허가를 먼저 확인합니다. 첫 다운로드가 느리면 연결 제한 시간에 걸릴 수 있습니다. 설치 로그와 오류부터 확인하고 무작정 재시도하지 않습니다.
공식 옵션 문서에 따르면 마지막 두 옵션은 MCP 사용 통계와 성능 추적 URL의 CrUX 전송을 끕니다. 모델로 보내는 화면·텍스트나 Chrome 자체 통계를 모두 차단하는 옵션은 아닙니다. 읽기 전용 접근 통제도 아니므로 기관 정책에 맞는 도구 권한을 별도로 적용합니다.
저장 후 OpenCode 세션을 종료하고 이 작업 폴더에서 다시 시작합니다. MCP 상태에서 chrome-devtools 연결을 확인합니다. 실패하면 Chrome 포트 응답, 패키지 실행, OpenCode 설정 순서로 원인을 나눠 봅니다. 보안 경고나 기관 차단은 우회하지 않습니다.
💬 댓글
이 글에 대한 의견을 남겨주세요