FAQ

설치, 운영, 보안, 트러블슈팅에 관한 자주 묻는 질문과 해결 방법을 정리했습니다.

일반

AllvIa는 어떤 서비스인가요?

AllvIa는 사용자 행동 기반 자동화 에이전트입니다. OS 수준에서 컴퓨터 사용 패턴을 분석하여 반복 작업을 자동으로 감지하고, AI가 최적의 자동화를 추천 및 실행합니다. Rust 네이티브 바이너리로 구현되어 높은 안정성과 처리 성능을 제공합니다.

지원 운영체제는 무엇인가요?

macOS 12+ (Monterey 이상)이 필수/권장 환경입니다. Windows는 scripts/run_core.ps1 경로로 실행할 수 있으며, Linux는 Rust 네이티브 빌드가 가능합니다.

자연어로 컴퓨터를 조작할 수 있나요?

네. surf 명령어로 "날씨 검색해", "Notes에 메모 만들어" 같은 자연어 지시를 입력하면, intent_router가 의도를 분석하고, plan_builder가 실행 계획을 생성하며, visual_driver와 browser_automation이 OS를 직접 제어합니다. 여러 앱을 연결하는 복잡한 멀티앱 시나리오도 지원합니다.

오프라인 환경에서도 사용할 수 있나요?

데이터 수집(routine, status)과 애플리케이션 제어(control, exec)는 오프라인에서 동작합니다. 단, LLM 기반 분석(recommend)과 워크플로우 생성(build_workflow)에는 OpenAI API 연결이 필요합니다. 완전한 오프라인 모드는 향후 로드맵에 포함되어 있습니다.

무료로 사용할 수 있나요?

AllvIa 코어 에이전트는 오픈소스로 무료 이용이 가능합니다. 추가 운영 기능은 플랜별 제공 범위가 다릅니다. Pricing 페이지에서 상세 요금 정보를 확인하실 수 있습니다.

설치 및 설정

OpenAI API Key가 반드시 필요한가요?

예. LLM 기반 행동 패턴 분석(analyzer.rs)과 자연어 워크플로우 생성(build_workflow)에 OpenAI API를 사용합니다. .env 파일에 OPENAI_API_KEY를 설정해야 합니다. GPT-3.5 및 GPT-4 모델을 모두 지원합니다.

macOS에서 Accessibility 권한은 왜 필요한가요?

OS 센서가 앱 전환, 활성 윈도우, 시스템 이벤트를 수집하기 위해 macOS의 Accessibility API를 사용합니다. 시스템 환경설정 → 개인정보 보호 및 보안 → 손쉬운 사용에서 터미널 앱에 권한을 부여하십시오.

n8n 없이도 사용할 수 있나요?

예. n8n은 선택적 워크플로우 오케스트레이션 레이어입니다. 코어 에이전트의 핵심 기능(routine, recommend, exec, control)은 n8n 없이 독립적으로 동작합니다. n8n은 복잡한 멀티스텝 워크플로우를 시각적으로 관리할 필요가 있을 때 추가하십시오.

빌드에 실패하는 경우

다음 사항을 순서대로 확인하십시오:

• Rust 버전이 1.70 이상인지 확인: rustup update && rustc --version
• Xcode Command Line Tools 설치 여부(macOS): xcode-select --install
• Visual Studio C++ Build Tools 설치 여부(Windows)
• 네트워크 연결 상태 확인 — Cargo 의존성 다운로드에 인터넷 연결이 필요합니다

보안 및 데이터

보안은 어떻게 처리되나요?

AllvIa는 Zero Trust 원칙을 적용하는 5계층 보안 모델을 적용합니다:

• PolicyEngine (policy.rs): Safe / Caution / Critical 3단계로 행동을 분류합니다
• CommandClassifier (security.rs): 셸 명령의 위험도를 자동 분석하여 차단합니다
• ToolPolicy (tool_policy.rs): 환경변수 기반 도구별 Allow/Denylist를 관리합니다
• PrivacyGuard (privacy.rs): 이메일, 카드번호 등 PII를 DB 저장 전 자동 마스킹합니다
• API Auth (api_server.rs): STEER_API_KEY 기반 미들웨어 인증을 적용합니다
• Write Lock: 기본 잠금 상태로, 시간 제한 자동 재잠금으로 실수를 방지합니다
• Kill Switch: Esc 연타 시 프로세스 즉시 종료

수집된 데이터는 어디에 저장되나요?

모든 데이터는 로컬 SQLite 데이터베이스(steer.db)에 저장됩니다. 외부 서버로 데이터가 전송되지 않습니다. LLM 분석 시에만 패턴 요약 데이터가 OpenAI API로 전송되며, 원시 이벤트 데이터는 전송되지 않습니다.

데이터 보관 주기

Rust Collector는 다음과 같은 데이터 라이프사이클을 관리합니다 (config.yaml 기준):

• 원시 이벤트: 7일 보관 후 자동 삭제 (raw_events_days: 7)
• 세션 데이터: 30일 보관 (sessions_days: 30)
• 루틴 후보: 90일 보관 (routine_candidates_days: 90)
• DB 최대 크기: 500MB (max_db_mb: 500)

성능 및 확장

플랜별 운영 한도 가이드

로컬 Core API 자체는 고정 Rate Limit 미들웨어를 강제하지 않으며, 운영 한도는 배포 환경/플랜 정책에 따라 적용됩니다.

에이전트가 시스템 리소스에 영향을 주나요?

AllvIa는 Rust 네이티브 바이너리로, 일반적으로 CPU 1% 미만, 메모리 50MB 이하를 사용합니다. Collector의 데이터 수집은 비동기로 동작하며 백그라운드에서 실행됩니다.

팀 단위로 배포할 수 있나요?

예. 다음 방식으로 팀 규모 배포가 가능합니다:

• Tauri 데스크톱 앱: .app / .exe로 번들하여 팀원에게 배포
• n8n 워크플로우 공유: 팀 전체가 동일한 자동화 워크플로우를 사용
• Self-Healing Guardian: steer-guardian.sh가 프로세스 크래시 시 자동 재시작을 보장

트러블슈팅

자동화가 실행되지 않습니다

다음을 순서대로 확인하십시오:

1. status 명령어로 에이전트가 정상 동작 중인지 확인
2. 트리거 설정이 올바른지 확인 (Webhook URL, 스케줄 등)
3. 커넥터 인증이 만료되지 않았는지 확인
4. Write Lock 상태 확인 — 필요 시 unlock 실행
5. 실행 이력에서 에러 메시지 확인: GET /api/agent/task-runs?status=failed

처리 속도가 느린 경우

다음 최적화를 시도하십시오:

• 배치 모드 활성화: 대량 데이터 처리 시 배치 분석으로 전환
• Release 빌드 확인: cargo build --release로 최적화된 바이너리를 사용하고 있는지 확인
• DB 최적화: steer.db 파일이 크다면 VACUUM 쿼리 실행
• Collector 간격 조정: STEER_COLLECTOR_INTERVAL 환경변수로 수집 빈도 변경

Webhook 전송이 실패하는 경우

실패한 Webhook은 지수 백오프(exponential backoff) 방식으로 최대 5회 재시도됩니다. 5회 실패 후에도 전송되지 않으면:

• 대상 URL의 접근 가능 여부 확인
• HTTPS 인증서 유효성 확인
• 방화벽에서 AllvIa 서비스의 IP가 허용되어 있는지 확인
• 응답 시간이 30초 이내인지 확인 (타임아웃 기준)

해결되지 않는 문제가 있으시면 GitHub Issues에서 이슈를 등록하거나 기술팀에 직접 문의하실 수 있습니다.