AEGIS 대시보드에 오신 것을 환영합니다! 이 가이드는 기술에 익숙하지 않은 사용자도 시스템을 완벽하게 설정하고 활용할 수 있도록 돕습니다. 플러그인 샌드박싱 로직 및 향상된 터미널 인텐트 파싱이 포함된 v2.2 시스템에 기반하여 작성되었습니다.
AEGIS의 계정 인증은 보안을 위해 secrets.json 파일에서 관리됩니다.
config/secrets.json파일을 텍스트 에디터로 엽니다. (파일이 없다면secrets.example.json을 복사하여 이름을 변경합니다)"USER_CREDENTIALS"항목을 찾아 다음과 같이 아이디와 비밀번호를 설정합니다:"USER_CREDENTIALS": { "admin": "admin123", "my_id": "my_password" }
- 대시보드를 새로고침 한 뒤, 변경한 계정 정보로 로그인합니다.
대시보드 상단의 자물쇠 아이콘을 클릭하여 위젯을 고정하거나 자유롭게 배치할 수 있습니다.
- 🔓 잠금 해제: 위젯의 빈 영역을 드래그하여 위치를 옮기거나, 우측 하단 핸들을 통해 크기를 조절할 수 있습니다.
- 🔒 잠금: 모든 위젯이 고정됩니다. 클릭 실수를 방지하고 캐릭터와의 상호작용에 집중할 때 유용합니다.
- 팁: 버튼이나 입력창 등은 잠금 해제 상태에서도 정상적으로 작동합니다. (단, 일부 영역은 드래그를 위해 상호작용이 제한될 수 있습니다.)
날씨 플러그인이 비(RAINY), 눈(SNOWY), 폭풍우(STORM) 상태를 감지하면 화면 전체에 시각 효과가 자동으로 나타납니다.
- 이 기능은 아바타의 리액션과 연동되어 있으며, 대시보드의 분위기를 실시간으로 바꿔줍니다.
대시보드 어디서든 단축키 **Shift + ~**를 누르면 퀘이크 방식(Quake-style)의 터미널 오버레이 HUD가 나타나 직관적인 명령을 내릴 수 있습니다.
- 3단계 명령 체계 (3-Tier Command System):
/ (Systematic): AI를 거치지 않는 100% 확정적 명령. (예:/보고,/일정 추가 ...) 매칭 실패 시 AI 폴백 없이 종료됩니다./@ (Hybrid): 플러그인 데이터 지식과 AI의 지능을 결합합니다. (예:/@일정 내일 회의 있어?)/# 또는 # (Pure AI): 컨텍스트 없는 순수 AI 지식 및 구글 검색을 사용합니다. (예:/#테슬라 주가)
- 음소거 임시 적용: 명령어 끝에
--m또는--mute를 붙이면, 해당 응답에 한해 아바타가 말하지 않고 텍스트로만 브리핑합니다.
AEGIS는 완전히 묘듈화된 "Plugin-X" 아키텍처로 구동되며, 각각의 위젯은 고유한 설정 파일을 갖습니다.
위젯 세부 설정은 각 플러그인 폴더(plugins/[위젯이름]/config.json 등)에서 변경하실 수 있습니다. 처음 사용하시는 분들을 위해 튜토리얼 형식으로 나열해 두었으니, 순서대로 하나씩 따라해 보세요!
Gmail 연동을 위해서는 구글이 발급하는 credentials.json 인증 파일이 필요합니다.
- Google Cloud Console에 접속하여 새 프로젝트를 생성합니다.
- 좌측 네비게이션 또는 상단 검색창에서 "API 및 서비스" 메뉴에 진입한 뒤, Gmail API를 검색하여 "사용(Enable)" 버튼을 누릅니다.
- 다시 "API 및 서비스" -> "사용자 인증 정보" 탭으로 이동하여 **[+ 사용자 인증 정보 만들기]**를 클릭하고 OAuth 클라이언트 ID를 선택합니다. (애플리케이션 유형: 데스크톱 앱)
- 생성이 완료되면 다운로드 버튼(⬇️)을 눌러 json 파일을 내려받습니다.
- 다운로드 받은 파일 이름을
credentials.json으로 변경합니다. - 변경한 파일을 AEGIS의
config/폴더 안으로 이동시켜줍니다. (config/credentials.json)
이 위젯들은 앞서 다운받은 credentials.json 파일을 똑같이 재사용하므로, 추가 파일이 필요하지 않습니다.
- 앞서 접속했던 구글 클라우드 콘솔의 "API 및 서비스"에서 Google Calendar API 및 Google Tasks API도 검색하여 모두 "사용(Enable)" 상태로 만들어 둡니다.
- AEGIS 대시보드가 처음 실행되면, 터미널(콘솔) 화면이나 팝업을 통해 링크가 하나 뜹니다.
- 해당 링크를 브라우저에 복사해 들어가 본인 구글 계정으로 로그인하고 접근을 "허용" 합니다.
- 인증이 완료되면 내부에
token_personal.json토큰 파일이 자동 생성되며, 이후로는 매번 로그인 할 필요 없이 자동으로 일정/할 일을 가져옵니다. plugins/todo/config.json및plugins/calendar/config.json파일을 텍스트 에디터로 열면 화면에 표시할 최대 개수(max_tasks,max_events)를 입맛에 맞게 수정할 수 있습니다.
날씨 정보를 가져오기 위해서는 OpenWeather 사이트의 API 키가 필요합니다.
- OpenWeatherMap 웹사이트에 접속하여 회원가입 및 로그인을 합니다.
- 우측 상단의 본인 계정명 메뉴를 누르고 "My API keys" 탭에 들어갑니다.
- 발급된 영문+숫자 조합의 고유 키(Key) 텍스트를 복사합니다.
- AEGIS의
config/secrets.json파일을 메모장(에디터)으로 엽니다. (만약 없다면secrets.example.json을 복사하여 이름만 바꿉니다.) - 파일 내용 안의
"EXTERNAL_API_KEYS"항목 안에"OPENWEATHER_API_KEY"를 찾고, 그 옆에 방금 복사한 키 값을 따옴표 안에 붙여 넣습니다. plugins/weather/config.json파일을 열어"city"항목을 자신이 사는 지역의 영문 이름(예:"Seoul","Busan")으로 변경합니다.
별도의 회원가입이나 API 키가 필요 없으며, Yahoo Finance를 통해 최신 주가 정보를 바로 가져옵니다.
plugins/stock/config.json파일을 엽니다."tickers"항목 아랫부분에 본인이 모니터링할 증권 종목들을 입력합니다.- 미국 주식: 티커명 그대로 (예:
"MAIN": "MAIN","APPLE": "AAPL") - 한국 주식 (KOSPI/KOSDAQ): 종목번호 6자리 뒤에 .KS(코스피) 나 .KQ(코스닥)를 붙입니다. (예: 삼성전자 ->
"삼성전자": "005930.KS") - 지수: 코스피 지수는
"KOSPI": "^KS11"로 입력합니다.
- 미국 주식: 티커명 그대로 (예:
따로 연동할 것 없이 내 컴퓨터의 여유 자원을 보여줍니다.
plugins/system-stats/config.json설정 파일을 엽니다.- 기본적인 CPU와 메모리(RAM) 모니터링 외에
"disks"섹션에서 감시할 하드 드라이브 지정이 가능합니다.- (예: 윈도우 환경 ->
"C:\\", 맥/리눅스 환경 ->"/")
- (예: 윈도우 환경 ->
노션의 데이터를 읽고 요약하기 위해 노션 관리자 토큰과 문서 주소가 필요합니다.
- Notion Developers 연동 페이지에 접속해 **새 API 통합(New Integration)**을 만듭니다.
- 생성 완료 시 화면에 보이는 "프라이빗 API 통합 토큰(Internal Integration Secret)" 항목을 복사합니다.
- 앞서 날씨 때 사용했던 AEGIS의
config/secrets.json등에 환경 변수 형태로 해당 토큰을 추가하거나 시스템상NOTION_TOKEN으로 등록합니다. - 본인의 노션 웹/앱으로 진입하여 연동할 페이지 우측 상단의
...메뉴를 클릭하고 연결(Connect) 항목에서 방금 생성한 통합 이름을 검색해 추가해줍니다. - 해당 노션 페이지 URL 링크를 웹브라우저 주소창에서 보면 일련번호 문자열이 있습니다. (이를
Database ID라고 부릅니다.) - 해당 문자열을 복사한 뒤
plugins/notion/config.json내부의"workspaces"항목에서"id"옆에 붙여 넣습니다.
- Clock (시계):
plugins/clock/config.json파일을 열어 시간 형식(12h/24h제)과 타임존(Asia/Seoul)을 변경할 수 있습니다. - News (뉴스 브리핑):
plugins/news/config.json파일을 열어 모니터링 하고자 하는 언론사 또는 포털의 RSS 주소(URL)를 입력하면 해당 뉴스를 아바타가 요약해 줍니다.
MP3 파일을 대시보드의 특정 시스템 폴더로 옮길 필요 없이, 원래 음악이 있는 컴퓨터의 폴더를 연결할 수 있습니다.
plugins/mp3-player/config.json파일을 엽니다."media_directory"항목 안의 따옴표에 본인의 진짜 음악 폴더 절대경로를 적어줍니다.- 윈도우 예시:
"media_directory": "D:\\Music"(역슬래시는 두개씩 적어야 합니다) - 맥/리눅스 예시:
"media_directory": "/home/user/Music"
- 윈도우 예시:
- 만약 이 항목을 공백(
"")으로 두면, 플러그인은 기본 시스템 폴더인static/media/mp3/폴더를 참조하게 됩니다.
이 플러그인은 재생 정보 및 추천 음악을 가져오기 위해 브라우저 헤더 정보(쿠키)를 거울처럼 사용합니다.
- PC에서 구글 크롬 등의 브라우저를 열고 YouTube Music 웹페이지에 로그인합니다.
F12키(개발자 도구)를 누르고 상단의 Network (네트워크) 탭으로 들어갑니다.- YouTube Music 페이지를 새로고침(F5) 합니다. 네트워크 창에 주르룩 뜨는 항목 중 이름이
browse또는 다른 네트워크 요청 항목을 하나 클릭합니다. - 우측 상세 패널의
"Request Headers (요청 헤더)"영역 전체를 드래그하여 마우스 우클릭 -> 복사합니다. (쿠키 정보가 포함되어야 합니다) - AEGIS 프로젝트 최상위 폴더에 있는
headers_auth.txt파일을 만약 비어있다면 열어 방금 복사한 내용을 붙여 넣고 저장합니다.
시스템을 자동으로 통제하고 브리핑을 받는 중앙 스케줄러 기능입니다.
- 루틴 (Routine): 지정된 시간 혹은 특정 조건(데이터 임계치 달성) 시, 지정한 행동(로봇 발화, 알람 등)을 수행하는 규칙입니다.
- 게이트키퍼 (Gatekeeper/수문장): 요일과 시간대를 바탕으로 알람을 허용(Allow)하거나 금지(Deny)하는 전역 규칙입니다. (예: 새벽에는 아바타가 떠들지 못하도록 차단)
(이 기능은 보통 Gmail 위젯 내부 리액션으로 동작하지만, 루틴 매니저를 통해 특정 시간에 새로운 메일의 브리핑을 요구하도록 설정이 가능합니다)
- Trigger: 매 시간 정각 (
hourly) - Action: API Call (
/api/plugins/gmail/brief) - 메일 요약 브리핑.
- Trigger Type:
조건 감시 (Condition Watch) - 감시 대상:
📈 KOSPI 등락률 (%) — 실시간 종목 모니터링 - 조건 / 값:
<= / -2.0(KOSPI 2% 이상 하락 시) - TTS Text:
현재 KOSPI 지수가 {{value}}% 하락했습니다. 방어선 {{threshold}}%가 뚫렸습니다! - 설명: 주식 등락률 센서가 실시간으로 -2% 이하를 기록하면 아바타가 텍스트에 기반해 음성 브리핑을 실행합니다.
- Trigger Type:
시간 지정 - 시간:
08:00(월~금 체크박스 선택) - Action:
tactical_briefing(현재 날씨, 일정, 주요 뉴스를 통합하여 1명에게 브리핑)
게이트키퍼 설정 패널을 열어 알람을 받고 싶지 않은 시간을 Deny로 지정할 수 있습니다.
- 점심 시간 차단 예제:
- 요일: 월, 화, 수, 목, 금 선택
- 시간 범위:
12:00~13:00 - Action:
Deny항목을 선택하고 저장합니다. 참고: 루틴의 조건이 만족되더라도 현재 시각에 일치하는 Deny 규칙이 있다면 알람/발화는 무시됩니다.
AEGIS를 고급 활용하시는 스폰서들을 위한 추가 시각적 경험 설정입니다.
- 설정 방식: 왼쪽 사이드바나 타이틀 영역의 배경화면 위젯 설정(또는
plugins/wallpaper/config.json)을 엽니다. - 제공 모드:
- 단색 (Solid): 깔끔한 원톤 배경
- 이미지 고정 (Image): 1장의 고해상도 이미지를 사용
- 슬라이드 (Slideshow): 여러 장의 이미지를 순차적으로 렌더링
- 동영상 (Video): 움직이는 MP4 라이브 배경 (리소스 주의)
라이브 2D 애니메이션 모델을 추가하고 모션을 설정하는 관리 페이지입니다.
- 인터넷에서 다운받거나 직접 제작한 Live2D 폴더 전체(json 파일 및 텍스쳐 포함)를
test_models/경로 하위에 넣습니다. (예:test_models/ANIYA/) - 폴더 이름과 내부 핵심 json(.model3.json) 명칭이 동일한 것을 권장합니다.
기존 모델이 갖고 있는 표정이나 액션 모션 이름이 AEGIS 시스템과 다를 때 이를 연결(Mapping)해주는 작업입니다.
- 스튜디오 위젯 상단의 **[에일리어스 매니저 / Alias Manager]**를 엽니다.
- 현재 활성화된 모델의 물리적 모션 파일과 AEGIS 시스템 이벤트(
sad,joy,shock,briefing,idle)를alias.json에서 1:1로 매핑 및 저장합니다. (시스템이 비어있는alias.json을 자동 생성한 후 텍스트 필드를 띄워줍니다.) - 💡 커스텀 알리아스(Custom Alias): AEGIS는 기본적으로 제공되는
sad,joy외에도 사용자가 원하는 어떠한 이름의 알리아스든 무제한으로 지원합니다.- 스튜디오의 에일리어스 매니저 하단 [Custom Alias] 입력 칸에 원하는 이름(예:
superhappy,dance_slow,fire등)을 입력하고 Add 버튼을 누릅니다. - 이후
reactions.json규칙 설정 등에서 해당 알리아스 이름을 그대로 사용할 수 있습니다. (메인 코드를 전혀 수정할 필요가 없습니다)
- 스튜디오의 에일리어스 매니저 하단 [Custom Alias] 입력 칸에 원하는 이름(예:
설정한 알리아스가 실제로 잘 작동하는지 스튜디오 내에서 바로 버튼을 눌러 점검합니다.
- 이메일 도착(충격)시: 스튜디오 하단 테스트 패널에서
[shock]또는 이벤트 전송을 누르면 아바타가 놀라는 모션을 취합니다. - 날씨/주가 브리핑시:
[briefing]모션을 호출하여 아바타가 보고하는 동작을 하는지 관찰합니다.
수고하셨습니다! 이 설정을 마치셨다면, 여러분만의 쾌적하고 똑똑한 AEGIS 대시보드 구축이 완료되었습니다.
최종 업데이트: 2026-03-04 (v2.2.0)