후니아오 브라우저 컨트롤 연동
MBAgent가 "정말로 후니아오 브라우저를 조작할 수 있는" 이유는 후니아오 클라이언트 ControlV2라는 통신 프로토콜 덕분입니다. 본 장에서는 MBAgent와 후니아오 브라우저의 연결 방법과 자주 발생하는 문제의 분리를 자세히 소개합니다.
1. 후니아오 브라우저 컨트롤이란 무엇인가?
후니아오 브라우저 컨트롤(Houniao Client ControlV2)은 후니아오 브라우저가 외부에 제공하는 양방향 통신 프로토콜로, 다른 프로그램(MBAgent 포함)이 다음을 할 수 있도록 합니다:
- 🔍 로컬에서 실행 중인 후니아오 인스턴스 발견
- 🤝 후니아오 인스턴스와 핸드셰이크
- 🔑 후니아오 계정으로 로그인
- 📦 후니아오 설정 (환경·프록시·지문) 읽기
- 🚀 후니아오 환경 실행 / 중지
- 🌐 후니아오 환경 내의 페이지 조작
NOTE
비유: ControlV2를 후니아오 브라우저의 "리모컨 프로토콜"로 이해할 수 있습니다. MBAgent가 리모컨이고, 후니아오 브라우저가 TV입니다.
2. MBAgent와 후니아오의 3가지 연결 모드
1. MBAgent 컨트롤 (권장)
MBAgent 시작 시 로컬에서 후니아오 컨트롤 서비스를 자동으로 시작하며, 후니아오 브라우저가 클라이언트로 연결됩니다.
적용 시나리오:
- 단일 후니아오 인스턴스
- 대부분의 개인 사용자
- 후니아오 + MBAgent가 동일 머신에서 실행
2. ApiServer 컨트롤
후니아오 브라우저 내장 ApiServer 인터페이스(http://127.0.0.1:8186)를 통해 연결.
적용 시나리오:
- 후니아오를 원격 제어
- 후니아오 브라우저가 다른 머신에 있는 경우
- 자동화 스크립트 (Selenium / Puppeteer / Playwright)
3. 동일 인스턴스
MBAgent와 후니아오 브라우저가 동일한 클라이언트 인스턴스 내에서 내부 통신을 직접 수행.
적용 시나리오:
- 개발 디버깅
- 성능 중시 시나리오
3. 최초 연결
전제 조건
✅ 후니아오 브라우저가 시작되어 계정에 로그인되어 있음 ✅ MBAgent가 설치되어 있음 ✅ MBAgent 시작 시 선택한 작업 디렉터리에 권한이 있음
자동 연결 흐름
MBAgent는 시작 시 자동으로 다음 흐름을 실행:
[1] 로컬 ControlV2 서비스 시작
↓
[2] 로컬 후니아오 인스턴스 스캔
- UDP 브로드캐스트 / 로컬 포트 스캔으로
- 후니아오 브라우저의 ControlV2 포트 발견
↓
[3] 핸드셰이크
- 프로토콜 버전 번호 교환
- 암호화 방식 협상
↓
[4] 계정 로그인
- MBAgent가 후니아오 계정으로 ControlV2에 로그인
- 자동으로 Token 읽기
↓
[5] 설정 읽기
- 후니아오 계정 하의 모든 환경
- 후니아오 계정 하의 프록시 설정
↓
[6] 능력 탐지
- 환경 실행 / 중지 테스트
- 웹 인계 테스트
- 파일 조작 테스트
↓
[7] 연결 성공 ✅연결 상태 확인
- "설정 → 공식 서비스 탐지" 진입
- "후니아오 클라이언트 ControlV2" 옵션 클릭
- "탐지 시작" 클릭
- 수 초 후 표시:
- ✅ 정상: 모든 점검 합격
- ⚠️ 이상: 구체적인 실패 단계
- ⚪ 미활성: ControlV2가 미활성
- ⏳ 탐지 중: 탐지 중
4. 탐지 결과 해석
✅ 정상
후니아오 클라이언트 ControlV2는 정상 사용 가능
실시간 준비 왕복 탐지로 연결·로그인·설정·실행 가능 능력을 검증했습니다.MBAgent가 후니아오 브라우저를 정상적으로 조작할 수 있음을 나타냅니다.
⚠️ 이상: 연결 실패
가능한 원인:
- 후니아오 브라우저가 시작되지 않음
- ControlV2 포트가 점유됨
- 방화벽에 차단됨
분리:
- 후니아오 브라우저가 시작되어 있는지 확인
- 후니아오 브라우저 → 설정 → ControlV2가 활성화되어 있는지 확인
- 방화벽 / 안티바이러스 소프트웨어를 닫고 재시도
⚠️ 이상: 계정 미로그인
가능한 원인:
- 후니아오 계정 Token 만료
- MBAgent가 Token을 읽지 못함
분리:
- 후니아오 브라우저 내에서 재로그인
- MBAgent 재시작
⚠️ 이상: 설정 읽기 실패
가능한 원인:
- 후니아오 계정 하에 환경이 생성되지 않음
- 후니아오 데이터베이스 연결 실패
분리:
- 후니아오 브라우저 내에서 환경을 1개 생성
- MBAgent 재시작
⚠️ 이상: 실행 가능 능력 불합격
가능한 원인:
- 후니아오 브라우저와 MBAgent의 버전 비호환
- 시스템 권한 부족
분리:
- 후니아오 브라우저가 최신 버전인지 확인
- 관리자 권한으로 MBAgent 시작
- 후니아오 고객 지원에 연락
5. 후니아오 컨트롤 인스턴스 전환
로컬에 여러 후니아오 브라우저 인스턴스(개발 시나리오)가 있는 경우 전환 가능:
1단계: 모든 후니아오 인스턴스 표시
- "설정 → 후니아오 클라이언트 ControlV2" 진입
- "후니아오 인스턴스" 옵션 클릭
- 현재 발견된 후니아오 인스턴스 목록 표시:
후니아오 인스턴스 #1 (기본)
- 포트: 8186
- 버전: v3.0.0
- 상태: 연결됨
후니아오 인스턴스 #2 (개발)
- 포트: 8286
- 버전: v3.0.0
- 상태: 미연결2단계: 전환
- 대상 후니아오 인스턴스 선택
- "전환" 버튼 클릭
- MBAgent가 현재 인스턴스를 끊고 새 인스턴스에 연결
- 주의: 전환은 현재 모든 후니아오 조작을 중지합니다
TIP
일상 사용: 99%의 사용자는 1개의 후니아오 인스턴스만 필요로 하며, 전환할 필요 없음.
6. AI가 후니아오 브라우저를 조작하는 과정
MBAgent가 "후니아오 조작" 지시를 받으면 자동으로 다음 흐름을 실행:
[1] AI가 작업 파싱
"223223 이 매장을 열고 오늘 주문 확인"
↓
[2] ControlV2 인터페이스 호출
- control.browser.start({ environment_id: "223223" })
↓
[3] 후니아오 브라우저가 환경 실행
- 223223 환경 생성 / 재사용
- 지문 / 프록시 / Cookie 적용
- browser_handle 반환
↓
[4] MBAgent가 CDP로 페이지 인계
- attach({ handle })
- 페이지 스크린샷, DOM 구조 수신
↓
[5] AI가 페이지 분석 후 다음 단계 결정
"주문 페이지가 보인다, 이제 숫자 추출"
↓
[6] 동작 실행
- click / type / extract
↓
[7] 작업 완료, 환경 닫기 (또는 열어둔 채)
↓
[8] 사용자에게 결과 정리
"오늘 주문 23건, 금액 $1234.56"핵심 개념
- handle: 후니아오 브라우저가 MBAgent에 반환하는 "환경 핸들", 구체적인 환경 참조
- attach: MBAgent가 후니아오 환경의 페이지를 인계
- CDP: Chrome DevTools Protocol, 후니아오 브라우저가 내부에서 사용하는 프로토콜
7. 자주 묻는 질문
Q1: MBAgent 시작 후 "후니아오 CDP 대기 중"이 표시된다
원인: 후니아오 브라우저가 시작되지 않았거나 환경이 실행되지 않음.
해결:
- 후니아오 브라우저가 시작되어 로그인되어 있는지 확인
- 후니아오 브라우저 내에서 환경을 수동 실행
- MBAgent가 자동으로 인계
Q2: AI의 후니아오 환경 조작이 항상 실패한다
가능한 원인:
- ControlV2 이상 (공식 서비스 탐지 확인)
- 후니아오 계정 크레딧 소진
- 후니아오 환경 손상
분리:
- 설정 → 공식 서비스 탐지에서 ControlV2가 정상인지 확인
- 후니아오 계정 AI 크레딧 확인
- 후니아오 브라우저 내에서 해당 환경을 수동 테스트
Q3: 후니아오 페이지 인계 후 화면이 새까맣다
가능한 원인:
- 후니아오 브라우저가 막 시작되어 환경 준비 미완료
- 후니아오 계정이 2차 인증 필요
해결:
- 5-10초 기다린 후 재시도
- 후니아오 브라우저 내에서 수동으로 인증 완료
Q4: MBAgent로 원격의 후니아오 브라우저를 제어할 수 있나?
❌ 불가능. MBAgent의 후니아오 클라이언트 ControlV2 연결은 구현 층에서 127.0.0.1로 강제 제한되어 있습니다(ControlClientError::NonLoopbackEndpoint), loopback 외의 IP 주소는 받지 않습니다. 후니아오 브라우저의 ControlV2 포트를 외부에 공개(예: 0.0.0.0:8186)해도 MBAgent는 핸드셰이크 단계에서 직접 연결을 거부합니다.
올바른 원격 후니아오 제어 방법:
- Selenium / Puppeteer / Playwright 등 스크립트를 사용하여 후니아오 브라우저 내장 ApiServer(
http://127.0.0.1:8186)를 통해 원격 호출 - 이러한 시나리오에서는 MBAgent가 관여하지 않으며, 일반 HTTP 클라이언트로 후니아오 ApiServer 인터페이스를 호출할 뿐
NOTE
왜 loopback으로 제한하는가:
- ControlV2 프로토콜 자체에 강력한身份 검증이 없으며, TCP 포트를 공중 네트워크에 공개하는 것은 "후니아오 계정 제어 권한을 누구에게나 넘기는" 것을 의미
- MBAgent와 후니아오 브라우저가 같은 머신·같은 계정 컨텍스트에서 실행된다고 가정, loopback은 최저 위험의 경계
Q5: MBAgent가 후니아오 브라우저를 조작하지 않고도 사용할 수 있나?
✅ 완전히 가능. MBAgent의 핵심 기능(대화·문서·코드·지식베이스)은 후니아오 브라우저에 의존하지 않습니다. 명확하게 후니아오 계정 환경 조작을 요구할 때만 ControlV2 연결을 설정합니다.
8. 모범 사례
시작 순서
권장 시작 순서:
- 후니아오 브라우저 (먼저 시작하여 로그인)
- MBAgent (나중에 시작, 자동 연결)
역순은 피하세요.
장시간 미사용 시
후니아오 브라우저 조작을 장시간 하지 않는 경우:
- MBAgent 내의 "후니아오 RAG 지식베이스"와 "후니아오 클라이언트 ControlV2" 사이드바 진입점 닫기
- 작업 내에서 후니아오 조작 줄이기
- 후니아오 계정의 리소스 소비 절약
다인 협력
팀 여러 사람이 1개의 후니아오 계정을 공유하는 경우:
- 각자의 MBAgent가 독립적으로 연결 가능
- 단 동시 조작 1개의 환경은 충돌
- 피크 시간을 분산하여 사용하거나 각자에게 독립된 후니아오 서브 계정 개설