MBAgent 자주 묻는 질문 FAQ
본 장에서는 MBAgent 사용 중 자주 묻는 질문과 해결책을 정리합니다. 여기에 없는 문제는 후니아오 고객 지원에 연락해주세요.
1. 설치 및 시작
Q1.1: MBAgent 아이콘을 더블 클릭해도 반응하지 않음
가능한 원인:
- 후니아오 브라우저가 시작되지 않음
- 후니아오 계정에 로그인하지 않음
- 작업 디렉터리의 권한 부족
해결:
- 후니아오 브라우저 시작 및 로그인
- MBAgent 작업 디렉터리가 존재하는지 확인
- 관리자 권한으로 MBAgent 시작
Q1.2: 시작 후 계속 "작업 디렉터리 선택"이 표시됨
원인: 후니아오 브라우저 메인 프로그램이 시작되지 않음. MBAgent가 후니아오 계정 정보를 읽을 수 없음.
해결:
- MBAgent 닫기
- 후니아오 브라우저 시작 및 로그인
- MBAgent 재시작
Q1.3: 시작 후 한국어가 표시되지 않음
해결:
- Windows 설정 → 시간 및 언어 → 언어 → Windows 표시 언어 → 한국어
- PC 재시작
Q1.4: 설치 시 "새 버전이 이미 설치되어 있습니다"가 표시됨
해결:
- 제어판 → 프로그램 및 기능 → 구버전 후니아오 제거
C:\Program Files\Mbbrowser삭제- 새 버전 재설치
2. 후니아오 브라우저 연결
Q2.1: MBAgent에 "후니아오 CDP 대기 중"이 표시됨
가능한 원인:
- 후니아오 브라우저가 시작되지 않음
- ControlV2 포트 점유
- 방화벽 차단
해결:
- 후니아오 브라우저 시작
- 후니아오 → 설정 → ControlV2가 활성화되어 있는지 확인
- 방화벽 / 안티바이러스 소프트웨어 닫기
Q2.2: AI가 후니아오 브라우저를 조작할 수 없음
분리 절차:
- "설정 → 공식 서비스 탐지" 진입
- **"후니아오 클라이언트 ControlV2"**의 "탐지 시작" 클릭
- 구체적인 실패 단계 확인
Q2.3: AI의 후니아오 조작이 항상 실패함
가능한 원인:
- 후니아오 계정 크레딧 소진
- 후니아오 환경 손상
- 네트워크 문제
해결:
- 후니아오 계정 AI 크레딧 확인
- 후니아오 브라우저 내에서 해당 환경 수동 테스트
- 후니아오 고객 지원에 연락
Q2.4: 원격의 후니아오 브라우저를 제어할 수 있나?
❌ 불가능. 자세한 내용은 후니아오 브라우저 컨트롤 연동을 참조.
3. 모델 및 Provider
Q3.1: 모델 목록이 비어 있음
원인: 후니아오 계정이 AI 모델 크레딧을 개통하지 않음.
해결:
- 후니아오 콘솔 접속
- "AI 모델" → 크레딧 개통
- MBAgent로 돌아와 모델 목록 새로 고침
Q3.2: Provider 전환 후 목록이 변하지 않음
분리:
- 해당 Provider가 API Key를 설정했는지 확인
- 연결 테스트 성공 여부 확인
- MBAgent 재시작
Q3.3: 자체 Provider에 연결할 수 없음
분리:
- API Key 및 Base URL이 올바른지 확인
- 네트워크 연결성 테스트 (ping / curl)
- MBAgent 로그 확인 (
%LOCALAPPDATA%\mbagent\logs\)
Q3.4: 모델 응답이 매우 느림
가능한 원인:
- 네트워크 문제
- 모델 과부하
- 컨텍스트가 너무 김
해결:
- 더 빠른 모델로 전환
- 대화 기록 압축 (
/compact) - 네트워크 확인
4. 작업 및 예약
Q4.1: 예약 작업이 예상대로 트리거되지 않음
분리:
- cron 식 확인
- MBAgent가 시작되어 있는지 확인 (Daemon 미설치)
- 작업 기록 확인
- 시스템 시각 확인
Q4.2: PC 절전 모드 시 작업이 실행되지 않음
해결:
- MBAgent Daemon 설치
- PC가 절전되지 않도록 설정
- 깨우기 타이머 설정
Q4.3: 작업이 항상 실패함
분리:
- 단독 실행하여 오류 확인
- 후니아오 브라우저 온라인 상태 확인
- 작업 설명을 간소화하여 단계별로 분리
- 후니아오 고객 지원에 연락
Q4.4: 예약 작업의 Token 소비가 너무 많음
해결:
- 저가 모델 사용
- "사고 과정 표시" 끄기
- 실행 빈도 줄이기
- 프롬프트 최적화
5. 파일 및 첨부 파일
Q5.1: 대용량 파일 업로드가 실패함
제한:
- 단일 파일은 50MB 미만 권장
- 초대용량 파일 (> 100MB)은 AI 도구에 경로 읽기를 맡김
해결:
- 파일 압축 (zip)
- Read 도구로 AI가 직접 읽도록
- 분할 업로드
Q5.2: AI가 이미지를 볼 수 없음
가능한 원인:
- 현재 모델이 멀티모달 미지원
- 이미지가 너무 큼
- 이미지 포맷 미지원
해결:
- 멀티모달 지원 모델로 전환 (gpt-5, claude-sonnet-4)
- 이미지 압축
- JPG / PNG로 변환
Q5.3: AI가 수정한 파일이 저장되지 않음
분리:
- "거부"를 잘못 클릭하지 않았는지 확인
- 작업 디렉터리에 쓰기 권한이 있는지 확인
- AI 메모리 뱅크에 잘못된 경로가 기록되어 있지 않은지 확인
6. 권한 및 보안
Q6.1: AI의 잘못된 조작을 취소하려면?
절차:
- 즉시
Esc로 AI 중지 - 조작 로그 확인
- AI의 잘못된 조작을 수동으로 취소
Q6.2: AI가 파일을 삭제했다, 복원 방법은?
상황 1: 파일이 샌드박스 내 (작업 디렉터리)
- "백업"을 활성화했다면 백업에서 복원
- 그렇지 않으면 전문 복원 도구 필요
상황 2: 파일이 샌드박스 외 (시스템 디렉터리)
- ⚠️ 이러한 조작은 기본으로 차단되어야 함
- 발생한 경우 즉시 후니아오 고객 지원에 연락
예방:
- AI가 중요 파일을 조작하기 전에 백업
- Ask 모드 사용 (팝업 확인)
Q6.3: API Key는 안전한가?
✅ 안전:
- MBAgent는 API Key를 업로드하지 않음
- Key는 Windows 자격증명 관리자에만 저장
- MBAgent 제거 시 자격증명도 함께 정리
⚠️ 권장:
- API Key를 주기적으로 회전
- 메모리 뱅크 또는 세션에 평문 Key를 붙여넣지 말 것
7. AI 메모리 뱅크
Q7.1: AI가 이전 발언을 "기억하지 못하는" 것처럼 보임
분리:
- AI 메모리 뱅크에 해당 메모리가 존재하는지 확인
- AI에게 다시 기억시키고 확인
- 작업 디렉터리가 변경되지 않았는지 확인
Q7.2: AI가 잘못된 메모리를 사용함
해결:
- 해당 메모리 편집
- 수정 또는 삭제
Q7.3: 메모리 뱅크를 백업하려면?
- 디렉터리
%LOCALAPPDATA%\mbagent\memory\찾기 - 폴더 전체 복사
- 안전한 위치에 저장
8. 인터페이스 및 표시
Q8.1: 인터페이스가 끊김
가능한 원인:
- 시스템 리소스 부족
- 세션 / KMS / MCP 로드 과다
- 테마 렌더링 문제
해결:
- 불필요한 탭 닫기
- 세션 수 줄이기
- 테마 전환 (다크 < 라이트)
- MBAgent 재시작
Q8.2: 글꼴 표시 이상
해결:
- 시스템 글꼴이 완전한지 확인
- MBAgent 설정에서 글꼴 전환
Q8.3: 탭 바가 보이지 않음
해결:
- 설정 → 인터페이스 및 네비게이션 → 표시 탭 → 모두 체크
- MBAgent 재시작
9. 성능 최적화
Q9.1: MBAgent의 메모리 점유가 높음
정상 범위:
- 유휴 시: 200-500MB
- 복잡 작업: 1-2GB
- 고병렬: 2-4GB
최적화:
- 불필요한 세션 닫기
- 병렬 작업 수 줄이기
- 불필요한 MCP 서비스 제거
Q9.2: AI 응답이 느림
가능한 원인:
- 모델 서버 지연
- 네트워크 문제
- 컨텍스트가 너무 김
최적화:
- 더 빠른 모델로 전환
- 기록 압축
- 네트워크 확인
10. 업데이트 및 업그레이드
Q10.1: MBAgent를 업데이트하려면?
MBAgent는 후니아오 브라우저와 함께 업데이트됩니다:
- 후니아오 브라우저 시작 시 새 버전 자동 탐지
- 업데이트 프롬프트 팝업
- "즉시 업데이트" 클릭
- 업데이트 후 재시작
Q10.2: 업데이트 후 데이터가 손실되었나?
발생하지 않음:
- AI 메모리 뱅크, 세션, KMS는 모두 유지
- 설정 파일만 리셋될 수 있음
데이터가 손실된 경우:
- 백업 디렉터리 확인
- 백업에서 복원
- 후니아오 고객 지원에 연락
Q10.3: 구버전으로 롤백할 수 있나?
가능하지만 다음 필요:
- 현재 데이터 백업
- 현재 버전 제거
- 구버전 설치
- 데이터 복원
⚠️ 주의: 구버전은 새 기능에 대응하지 않을 수 있음.
11. 오류 코드
BROWSER_AUTO_UNAVAILABLE
의미: 브라우저 자동화 능력 사용 불가. 원인: Playwright MCP browser가 시작되지 않음. 해결:
- Node.js 및 npx 설치
- MBAgent에 Playwright 자동 설치
- MBAgent 재시작
CONTROL_V2_DISCOVERING
의미: 후니아오 클라이언트 인스턴스 발견 중. 원인: 막 시작했거나 스캔 중. 해결: 수 초 기다린 후 재시도.
CONTROL_V2_HANDSHAKE_SPEC_MISMATCH
의미: MBAgent와 후니아오 클라이언트가 사용하는 ControlV2 규약 버전이 다름. 해결:
- 후니아오 브라우저를 최신 버전으로 업데이트
- MBAgent를 최신 버전으로 업데이트
TOOL_ENABLE_PREREQUISITE_MISSING
의미: 도구의 전제 조건이 충족되지 않음. 해결:
- 대응하는 Skill이 활성화되어 있는지 확인
- 후니아오 계정 인증 레벨 확인
후니아오 RAG 지식베이스 현재 사용 불가
의미: 후니아오 공식 RAG 지식베이스 서비스 이상. 해결:
- 후니아오 계정이 유효한지 확인
- 네트워크 확인
- 후니아오 고객 지원에 연락
후니아오 클라이언트 ControlV2 현재 사용 불가
의미: 후니아오 브라우저 ControlV2 프로토콜 이상. 해결:
- 후니아오 브라우저 재시작
- MBAgent 재시작
- 후니아오 브라우저 → 설정 → ControlV2 확인
12. 도움말 획득
공식 채널
- 공식 문서: https://help.mbbrowser.com/mbagent
- 후니아오 콘솔: https://www.mbbrowser.com/console
- 고객 WeChat: 후니아오 공식 사이트 참조
- 고객 이메일: support@mbbrowser.com
자체 분리
- MBAgent 로그 확인:
%LOCALAPPDATA%\mbagent\logs\ - 후니아오 브라우저 로그 확인
- **"설정 → 공식 서비스 탐지"**에서 서비스 상태 확인
문제 피드백
고객 지원에 연락할 때 다음을 제공해주세요:
- MBAgent 버전 번호
- 후니아오 브라우저 버전 번호
- Windows 버전
- 완전한 오류 메시지
- 조작 절차
- 필요 시 로그 파일 제공