본문으로 건너뛰기
KeuralDocs
데스크톱·내 장비

Keural Duo

내 컴퓨터에서 동작하는 상주형 에이전트의 설치, 대화, 루틴, 텔레그램, 컴퓨터 사용, Mate & Morph입니다.

Duo는 데스크톱 앱이 이 컴퓨터(또는 연결한 DGX Spark)에 설치하는 상주형 에이전트입니다. 격리된 샌드박스에서 동작하고, 사이드바의 Duo나 텔레그램으로 대화하며, 등록한 루틴을 실행합니다. NVIDIA NemoClaw·OpenClaw 기반입니다.

Duo는 데스크톱 앱 전용입니다.

설치

설정 → Duo → 실행 환경에서 모델을 고르고, 실행할 위치 줄의 설치를 누릅니다. 모델을 고르지 않았거나 디스크가 부족하면 설치 버튼이 비활성화됩니다.

실행 위치와 요구사항

실행 위치요구사항
이 기기 (macOS)Apple 실리콘, 메모리 16GB 이상. 컨테이너 런타임은 앱이 직접 설치하므로 Docker Desktop·Homebrew·관리자 비밀번호가 필요 없습니다.
이 기기 (Windows)WSL 2. 처음 한 번 Windows 준비를 누르면 필요한 구성 요소를 설치합니다. PC 재시작이나 관리자 권한 허용을 요청할 수 있습니다. 가상화가 꺼져 있으면 BIOS에서 켭니다.
원격 기기 (DGX Spark)Spark를 연결하고 모델을 먼저 실행합니다. Spark 방화벽이 켜져 있으면 Spark 계정 비밀번호를 한 번 입력해 포트 두 개를 엽니다(비밀번호는 저장되지 않습니다).

디스크는 20GB 이상 필요하며 40GB 이상을 권장합니다. 부족하면 설치 버튼이 잠기고 "{need} GB 필요 · {free} GB 남음"이 표시됩니다.

모델

선택설명
이 기기 모델받아 둔 로컬 모델 중 실행 중인 모델을 씁니다. "{모델} · 채팅과 같은 모델"로 표시됩니다.
DGX Spark연결한 Spark가 실행 중인 모델입니다.
클라우드요금제에 포함된 Duo 모델입니다. 로그인해야 표시됩니다.
게이트웨이설정 → 모델 → 게이트웨이에서 연결한 서버의 모델을 씁니다. 그 서버의 주소와 API 키가 필요합니다.

설치 후에도 모델 줄에서 모델을 바꿉니다. 같은 종류 안에서는 "전환"으로 바로 바뀌고, 로컬·클라우드·게이트웨이 사이에서 종류가 바뀌면 다시 설치합니다. 다시 설치해도 루틴은 유지됩니다. 실행 위치를 옮기려면 삭제한 뒤 다른 위치에 설치합니다.

설치 단계

이 기기 확인 → 컨테이너 런타임 준비 → NemoClaw 설치 → 모델 시작(클라우드·게이트웨이는 모델 사용 권한 준비) → 샌드박스 만들기 → Duo 설정 → 동작 확인 순서로 진행되며, 현재 단계는 버튼과 진행 카드에 표시됩니다. "조금 오래 걸리고 있습니다. 앱을 열어 두세요."가 표시되어도 앱을 닫지 않습니다.

설치가 멈추면 설치가 안 될 때에서 화면 문구로 원인을 확인합니다.

다른 계정·워크스페이스의 Duo

Duo는 기기당 하나이며, 설치한 계정과 워크스페이스에 속합니다. 다른 계정으로 로그인하거나 다른 워크스페이스로 바꾸면 설정의 Duo는 "설치 안 됨"으로 표시되고, 사이드바 Duo와 Mate & Morph는 숨겨집니다. 이 상태에서 설치를 누르면 기존 Duo와 대화·루틴이 삭제된다는 확인창이 표시되고, 새로 설치를 누르면 기존 Duo를 지우고 새로 만듭니다. 원래 계정·워크스페이스로 돌아오면 기존 Duo가 다시 표시됩니다.

이전에 설치된 Duo가 남아 있으면 정리한 뒤 설치합니다. 정리에 실패하면 "기존 Duo를 지우지 못했습니다. 다시 설치하세요."가 표시됩니다.

설치가 안 될 때

설치가 멈추면 설정 → Duo에 오류 문구가 표시됩니다. 문구 뒤 괄호 안의 코드도 확인합니다. 원인을 해결한 뒤 설치를 다시 누릅니다.

화면 문구원인해결
저장 공간이 부족해 설치를 멈췄습니다. 여유 공간을 {need} GB 이상 확보한 뒤 다시 설치하세요홈 폴더가 있는 디스크에 20GB가 없습니다.파일을 정리해 20GB 이상(권장 40GB) 비웁니다.
설치를 준비하지 못했습니다. 인터넷 연결을 확인하세요설치 파일을 받지 못했습니다. 회사 방화벽·프록시가 원인인 경우가 많습니다.인터넷 연결을 확인합니다. 회사망이면 내려받는 곳의 주소 허용을 IT 담당자에게 요청합니다.
기존 Duo를 지우지 못했습니다. 다시 설치하세요.이 기기에 남은 이전 Duo를 정리하지 못했습니다.앱을 완전히 종료했다가 다시 열고 설치를 누릅니다. 계속되면 macOS 탭의 같은 문구를 확인합니다.
다른 계정 또는 다른 워크스페이스의 Duo가 있습니다.이 기기의 Duo가 다른 계정·워크스페이스에 속합니다.새로 설치를 누르면 그 Duo를 지우고 설치합니다. 기존 Duo를 계속 쓰려면 원래 계정·워크스페이스로 전환합니다.
이 플랜에서는 클라우드 모델로 Duo를 쓸 수 없습니다.지금 워크스페이스의 요금제에 클라우드 Duo가 없습니다.모델을 이 기기 모델·DGX Spark·게이트웨이로 바꾸거나 요금제를 확인합니다.
로그인하면 클라우드 모델을 쓸 수 있습니다.로그아웃 상태입니다.로그인하고 다시 설치합니다.
모델이 실행 중이 아닙니다. 모델을 시작한 뒤 다시 적용하세요.이 기기 모델이 꺼져 있습니다.설정 → 모델에서 모델을 실행한 뒤 설치합니다.
조금 오래 걸리고 있습니다. 앱을 열어 두세요.첫 설치는 내려받을 파일이 많습니다.앱을 닫지 않고 기다립니다. 노트북은 잠자기 모드에 들어가지 않게 합니다.

해결되지 않으면 설정 → 지원으로 문의합니다. 화면 문구, 괄호 안 코드, 기기 종류(macOS·Windows·Spark)를 함께 적습니다.

설정 → Duo 화면

구역내용
상태"{위치}에서 실행 중" · 멈춤 · 시작 중 · 설치 안 됨 · 서버 없음(Spark 연결이 빠진 경우)
실행 환경모델 선택, 이 기기 / 원격 기기 줄의 설치·시작·멈추기·삭제, 샌드박스 ID와 NemoClaw 버전
채팅 앱텔레그램 연결
연결GitHub, 웹 검색
컴퓨터 사용권한, 읽을 수 있는 폴더, 행동 전 규칙, 항상 허용한 앱, Mate & Morph
대화 기억컨텍스트 사용량, 대화 압축, 새 대화
새 기능 (Windows)Windows 컴퓨터 연결, 공유 폴더, 앱 접근 확인, 최근 작업

설치·모델 전환·채팅 앱 적용·삭제 중에는 다른 구역이 잠깁니다. 컴퓨터 사용을 켜거나 규칙을 넓힐 때는 운영체제 확인창이 표시됩니다.

대화

사이드바의 Duo를 누릅니다(코드 모드에서는 표시되지 않습니다). 연결이 끊긴 동안 보낸 메시지는 "{n}개 전송 대기 중"으로 표시되고, 연결되면 전달됩니다. /new를 보내면 새 대화를 시작할지 묻습니다.

상단의 Duo 정보를 켜면 옆 패널에 다음 카드가 표시됩니다.

카드내용
지금 하는 일쉬는 중 또는 진행 중인 작업과 경과 시간, 쓴 도구
Duo 설정이 바뀌었습니다샌드박스 설정이 마지막 확인 때와 달라졌을 때 표시됩니다. 바뀐 영역(채팅 앱과 대화할 수 있는 사람 · 도구와 권한 · 연결된 서비스 · 모델 연결 · 기타)을 보여 줍니다. 직접 바꾼 것이면 변경 수락을 누릅니다.
샌드박스준비됨/오류, 모델 응답 정상/응답 없음, GPU(CUDA) 사용 여부, 용량
모델모델 이름, 위치(이 기기 · DGX Spark · 클라우드), 컨텍스트 사용량
루틴아래 루틴 참고
연결 · Telegram연결 요약. 누르면 설정으로 이동합니다.
작업 파일Duo가 샌드박스 작업 폴더에 만든 파일

백그라운드 작업 버튼을 누르면 Duo가 실행 중인 하위 에이전트 목록을 봅니다.

대화 기억

설정 → Duo → 대화 기억에서 "사용 중인 맥락"을 토큰 수와 비율로 확인합니다. 압축으로 대화를 줄이거나 새로 시작으로 새 대화를 엽니다. 기존 대화는 보관됩니다. Duo가 작업 중이면 작업이 끝난 뒤에 할 수 있습니다. "대화가 모델이 처리하기엔 너무 길어져 Duo가 답하지 못했습니다"가 표시되면 압축하거나 새로 시작합니다.

루틴

Duo에게 "매일 아침 9시에 …해 줘"처럼 말하면 이 루틴을 만들까요? 카드(작업 · 일정 · 실행 위치)가 표시됩니다. 루틴 만들기를 누르면 등록됩니다. 수정·삭제할 때도 같은 카드로 확인합니다.

항목내용
주기한 번(최대 365일 뒤까지) · 매일 · 평일 · 매주 · N분마다(5~1,440분)
실행 위치Keural 앱의 Duo 대화, 또는 Telegram으로 전달
개수활성 10개, 전체 50개
만료기본 7일, 최대 30일. 지나면 "만료됨"
놓침앱이 꺼져 있어 예정 시각보다 10분 넘게 늦으면 실행하지 않고 "놓침"으로 남깁니다
실패연속 3회 실패하면 "실패로 일시중지됨"

Duo 정보 패널의 루틴 카드에서 켜고 끄며, 더 보기에서 지금 실행·삭제합니다. 행마다 다음 실행 시각과 상태(전송됨 · 놓침 · 실패 · 일시중지됨 · 만료됨)가 표시됩니다. 루틴 결과는 Duo 대화나 텔레그램으로 전달되고 데스크톱 알림도 표시됩니다(지금 실행은 알림 없음). 루틴은 앱이 열려 있을 때 실행됩니다.

채팅 앱 (텔레그램)

설정 → Duo → 채팅 앱 → Telegram → 연결하기에서 안내를 따릅니다.

  1. 텔레그램의 @BotFather를 열고 /newbot을 보낸 뒤 봇의 이름과 사용자 이름을 정합니다.
  2. BotFather가 준 봇 토큰을 붙여 넣고 확인을 누릅니다. 토큰이 유출되면 누구나 봇을 조종할 수 있으므로 공개하지 않습니다.
  3. 휴대폰으로 QR을 찍어 봇을 열고 시작을 누릅니다. 응답이 없으면 화면의 코드를 봇에 보냅니다.
  4. "{이름} 님만 개인 메시지로 대화할 수 있습니다"가 표시되면 추가, 적용을 차례로 누릅니다.

적용하면 Duo가 다시 시작됩니다(대화와 파일은 유지). 이후 휴대폰에서 보낸 메시지는 Duo 대화에 "Telegram에서 보냄"으로 표시됩니다. 연결한 한 명만 개인 메시지로 대화할 수 있습니다. 해제하려면 연결 끊기를 누르고 적용합니다. 텔레그램을 연결하면 루틴 승인도 텔레그램으로 받습니다.

봇 토큰 하나는 한 계정의 한 기기(Duo)에서만 쓸 수 있습니다. 다른 기기에 연결하려면 기존 기기에서 연결을 해제한 뒤 토큰을 다시 등록합니다.

앱 작업 승인은 텔레그램에서 시작한 대화라도 Keural 앱 창에서만 합니다.

연결

설정 → Duo → 연결에서 설정합니다.

서비스방법
GitHub개인 액세스 토큰을 붙여 넣고 확인하거나, GitHub CLI로 계속으로 이 컴퓨터의 gh 로그인을 씁니다. CLI가 없으면 설치 링크가, 로그인하지 않았으면 로그인 창이 열립니다. 연결하거나 바꾸면 Duo가 다시 시작됩니다.
웹 검색설정 → 일반 → 웹 검색에서 고른 방식(빠른 검색 · Keural 검색 · 내 검색 서비스의 Tavily·Brave·SearXNG)을 그대로 씁니다. 컴퓨터 사용이 켜져 있어야 합니다.

컴퓨터 사용

설정 → Duo → 컴퓨터 사용 → Duo가 이 컴퓨터를 사용하도록 허용을 켜면 Duo가 이 컴퓨터의 앱을 쓰고, 지정한 폴더를 읽고, 루틴을 만들 수 있습니다. 켜면 Duo가 1분 정도 다시 시작됩니다.

항목내용
macOS 권한손쉬운 사용(클릭·입력)과 화면 기록(화면 보기). 허용하지 않았으면 시스템 설정 열기를 누릅니다.
Duo가 읽을 수 있는 폴더폴더 추가로 지정한 폴더만 읽습니다. 홈 폴더 전체, 시스템 폴더는 추가할 수 없습니다.
Duo가 행동하기 전매번 묻기(기본) · 묻지 않고 실행 · 내가 직접 하기. 묻지 않고 실행으로 바꿀 때 한 번 더 확인합니다.
항상 허용한 앱승인 창에서 항상 허용한 앱 목록. ×를 눌러 제거합니다.

묻지 않고 실행이나 항상 허용이어도 보내기·삭제·덮어쓰기·결제·제출·로그인·게시·취소 같은 민감한 단계와 Enter·Backspace·⌘Q 같은 키는 항상 먼저 묻습니다.

Duo가 승인을 기다리면 입력창 위에 "Duo가 승인을 기다리고 있습니다"가 표시됩니다. 확인을 눌러 승인 창을 열고 거부 · 한 번 허용 · 항상 허용 중에서 고릅니다. 승인은 이 창에서만 할 수 있습니다.

Duo는 검색 결과의 링크만 승인 없이 엽니다. Duo가 직접 입력하거나 바꾼 주소는 승인 창에 주소 전체를 보여 주고 묻습니다.

Mate & Morph

Duo의 데스크톱 캐릭터입니다. 설정 → Duo → 컴퓨터 사용 → Mate & Morph → 바탕화면에 표시를 켜고 캐릭터(Mate · Morph · 둘 다)와 크기(작게 · 보통 · 크게)를 고릅니다.

  • Duo가 실행 중이고 대화가 준비됐을 때 표시됩니다. 다른 계정·워크스페이스로 바꾸거나 요금제에서 Duo를 쓸 수 없으면 숨겨집니다.
  • 캐릭터를 한 번 누르면 입력칸이 열리고, 두 번 빠르게 누르면 앱이 열립니다. 캐릭터 옆에 상태(대기 중 · 작업 중 · 완료 · 막힘 · 입력 필요 · 승인을 기다리고 있어요)와 마지막 답변 실패 사유가 표시됩니다.
  • 우클릭 메뉴: 숨기기 · 읽음으로 표시 · Duo 열기 · Duo 설정. 메뉴 막대(트레이) 메뉴에도 Mate & Morph 보이기/숨기기가 있습니다.

Windows

Windows의 Duo는 WSL 배포판에서 동작하며, 대화·루틴·텔레그램·승인·Mate & Morph·컴퓨터 사용을 macOS와 같이 지원합니다. 일부 앱과 비밀번호 칸·UAC·터미널 같은 보안 창은 Duo가 조작하지 않고 사용자에게 넘깁니다.

설정 → Duo → 새 기능(Windows 컴퓨터)에서 Duo 연결, 공유 폴더(Duo는 선택한 폴더만 읽음), 앱 접근, 최근 작업을 확인합니다. Windows에서는 소프트웨어 설치(정확한 패키지 ID로만)와 Wi‑Fi 연결(저장된 프로필)도 할 수 있으며, 보내기·삭제·덮어쓰기·설치·네트워크 변경은 항상 먼저 묻습니다.

삭제

설정 → Duo → 실행 환경에서 설치된 위치 줄의 삭제를 누르고 확인창에서 삭제를 누릅니다. 샌드박스, 대화 기록, 루틴, 작업 파일이 삭제됩니다. macOS에서는 Duo 전용 컨테이너 VM도 삭제됩니다. DGX Spark의 Duo는 Spark가 연결되어 있어야 삭제할 수 있습니다.

자주 보는 문구

문구뜻
Duo가 실행 중이 아닙니다설정 → Duo에서 시작을 누릅니다.
최신 데스크톱 앱이 필요합니다앱을 업데이트합니다.
모델이 실행 중이 아닙니다. 모델을 시작한 뒤 다시 적용하세요.로컬·Spark 모델이 꺼져 있습니다. 모델을 먼저 실행합니다.
모델 연결이 끊겼습니다. 로그인 상태를 확인하세요.클라우드 모델 Duo의 접근 권한이 끊겼습니다. 다시 로그인합니다.
이 워크스페이스의 플랜에서는 Duo를 쓸 수 없습니다.클라우드 모델 Duo를 쓸 수 없는 요금제입니다. 로컬 모델로 바꾸거나 요금제를 확인합니다.
다른 계정 또는 다른 워크스페이스의 Duo가 있습니다.설치하면 그 Duo가 삭제됩니다. 원래 계정·워크스페이스로 전환하면 그대로 쓸 수 있습니다.
기존 Duo를 지우지 못했습니다. 다시 설치하세요.이전에 설치된 Duo를 정리하지 못했습니다. 설치를 다시 누릅니다.

IT 담당자용 상세

요구사항

실행 위치기준
macOSApple 실리콘(arm64), 메모리 16GB 이상. Duo용 가상 머신(Colima, vz)에 CPU 4개·메모리 9GiB·디스크 40GiB(필요한 만큼만 차지)를 씁니다.
WindowsWSL 2(커널 5.15 이상), x64 또는 ARM64. 배포판 Ubuntu 24.04를 Keural-Duo 이름으로 설치하고, 그 안에서 rootless Podman을 씁니다. Docker Desktop은 필요 없습니다.
DGX SparkDocker가 동작하고, 남은 디스크 20GB·사용 가능한 메모리 8GB 이상
공통홈 폴더가 있는 디스크에 20GB 이상 여유(40GB 권장)

Windows에서는 설치할 때 %USERPROFILE%\.wslconfig의 [wsl2]에 networkingMode=nat을 씁니다. 미러드 네트워킹(mirrored)을 쓰는 PC는 설치되지 않습니다.

설치되는 위치

실행 위치경로
macOS 런타임~/.keural-runtime/ (Colima·Lima·Docker CLI, 로그)
macOS 자동 실행~/Library/LaunchAgents/kr.mkd.keural-duo-colima.plist, kr.mkd.keural-duo-gateway.plist, kr.mkd.keural-duo-sweeper.plist
NemoClaw CLI~/.local/bin/nemoclaw
WindowsWSL 배포판 Keural-Duo
앱 기록앱 데이터 폴더의 keural-duo@<서버>.json, keural-duo-routines@<서버>.json, keural-duo-rules@<서버>.json
로그~/.keural/logs/, ~/.keural-runtime/colima.log·gateway.log, 앱 데이터 폴더의 keural-duo-install.log

내려받는 곳

방화벽이나 프록시에서 다음 주소를 허용합니다. 내려받는 파일은 고정 버전이며 SHA-256으로 검증합니다.

주소받는 것
github.comColima v0.10.3, Lima v2.2.1, buildx v0.38.2(macOS), Podman 도구(Windows)
download.docker.comDocker CLI 29.9.3(macOS)
www.nvidia.comNemoClaw 설치 스크립트(v0.0.134)
ghcr.ioOpenClaw 샌드박스 이미지
api.telegram.org텔레그램 연결
Keural 서버(api.keural.ai 등)클라우드 모델, 로그인

웹 검색·GitHub 연결을 쓰면 api.tavily.com, api.search.brave.com, api.github.com, api.githubcopilot.com도 허용합니다.

네트워크와 포트

위치포트쓰임
macOS127.0.0.1:8080OpenShell 게이트웨이
macOS·Windows127.0.0.1:8766이 기기 모델 서버(Windows는 WSL 안의 중계). 겹치면 8768
DGX Spark18080~18099 중 빈 포트Spark 전용 게이트웨이
DGX Spark18081샌드박스에서 Spark 모델(8000)로 가는 중계
DGX Spark22앱의 SSH 접속

Spark에 ufw 방화벽이 켜져 있으면 설치 중에 게이트웨이·중계 포트 두 개를 엽니다. 이때 Spark 계정 비밀번호를 한 번 입력합니다.

샌드박스는 인터넷에 직접 접속하지 않습니다. 웹 검색과 페이지 읽기는 앱이 처리하고, GitHub은 읽기 전용으로 연결됩니다.

모델 주소

모델샌드박스가 부르는 주소
이 기기 모델http://localhost:<포트>/v1. 기본 모델 qwen3-8-27b, 컨텍스트 262,144
DGX Spark 모델Spark 중계를 거쳐 Spark의 127.0.0.1:8000/v1
클라우드 모델Keural 서버의 /core/v1/bot/v1. Duo마다 발급한 토큰을 씁니다.
게이트웨이설정 → 모델 → 게이트웨이에서 연결한 서버의 주소

게이트웨이 주소는 https면 어디든, http면 사설 IP나 사내 이름(.local·.lan·.internal·.intranet·.home.arpa, 점 없는 이름)만 받습니다. localhost와 user:pass@가 들어간 주소는 받지 않습니다.

텔레그램

  • 봇 토큰은 BotFather의 /newbot으로 받습니다. 형식은 숫자:영숫자 입니다.
  • 연결 코드가 만들어지면 10분 안에 휴대폰에서 봇을 열고, 5분 안에 첫 메시지를 보냅니다. 첫 메시지를 보낸 계정이 허용됩니다.
  • 그룹 대화에는 답하지 않습니다.

루틴

항목값
확인 주기30초마다 실행할 루틴을 찾습니다.
놓침예정 시각보다 10분 넘게 늦으면 실행하지 않고 놓침으로 남깁니다.
일시중지3번 연속 실패하면 멈춥니다.
반복 간격5~1,440분
한 번 실행365일 뒤까지
만료기본 7일, 최대 30일
개수켜 둔 루틴 10개, 전체 50개
시간대루틴을 만든 컴퓨터의 시간대

폴더 추가 규칙

다음 폴더는 추가할 수 없습니다.

구분폴더
공통디스크 루트, 홈 폴더 자체와 그 위
홈 아래.ssh, .aws, .gnupg, .kube, .docker, .config, Library, .Trash, AppData
macOS/System, /Library, /usr, /bin, /sbin, /etc, /var, /private, /dev, /Volumes, /Applications, /opt, /cores
WindowsWindows, Program Files, Program Files (x86), ProgramData

컴퓨터 사용 권한

OS필요한 권한
macOS시스템 설정 → 개인정보 보호 및 보안의 손쉬운 사용, 화면 기록
Windows별도 권한 없이 Windows UI 자동화를 씁니다.

전송·삭제·결제·구매·제출·로그인·송금·게시·취소 같은 버튼과 Enter·Delete·창 닫기·앱 종료 같은 키는 민감한 단계로 보고 매번 확인합니다.

삭제할 때 지우는 것

삭제를 누르면 샌드박스, Duo 대화 기록, 루틴, 텔레그램·GitHub·검색 연결, 클라우드 모델 토큰이 삭제됩니다. 이 기기에 다른 Duo가 없으면 macOS에서는 ~/.keural-runtime/과 자동 실행 항목도 삭제됩니다. Mate & Morph 설정과 Spark 접속 기록은 남습니다.

이 페이지의 내용