nanobot

Discord ·
X ·
WeChat / Feishu

nanobot
🐈 nanobot은 Python으로 작성된 초경량 오픈소스 셀프 호스팅 개인 AI 에이전트 프레임워크입니다. 브라우저, 터미널 또는 채팅 앱에서 사용하여 파일을 다루고, 선호도를 기억하고, 작업을 예약할 수 있습니다. 지원되는 모델 제공자 또는 로컬 모델 서버를 연결하여 AI를 공급하세요.

여기서 시작하기

원하는 작업...
이동 위치

터미널/설정 배경 없이 nanobot 설치
기술 배경 없이 시작하기

빠르게 설치하고 첫 응답 받기
설치 및 빠른 시작

번들 브라우저 UI 열기
WebUI

Telegram, Discord, WeChat, Slack, Email, Mattermost, Linear 또는 다른 채널 연결
채팅 앱 가이드

제공자, 폴백 모델, Langfuse, MCP, 웹 도구 또는 보안 구성
문서 및 구성

브라우저 UI 개발
현재 소스 설치 후 WebUI 개발 및 기여

Python 또는 HTTP에서 통합
Python SDK 또는 Agent API

내부 구조 이해 또는 확장
아키텍처, 기여 및 제공자 확장

클라우드에 배포하거나 nanobot을 서비스로 계속 실행
배포

nanobot은 무엇을 할 수 있나요?
nanobot은 다음을 할 수 있습니다:

브라우저 WebUI 또는 터미널에서 실행
Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear 및 기타 채널에 연결
내장 파일 도구로 PDF, Word(.docx), Excel(.xlsx), PowerPoint(.pptx) 파일을 읽어 보고서 요약 등의 작업 수행
shell, 웹 검색/가져오기, MCP 통합, cron, 이미지 생성, 멀티 에이전트 위임 사용
Dream을 통해 세션 기록과 장기 기억 유지
장기 목표와 예약 자동화 실행
통합을 위한 Python SDK 및 OpenAI 호환 API 노출
장기 실행 로컬 또는 서버 측 에이전트 게이트웨이로 배포

💡 nanobot을 선택하는 이유

지속적인 워크플로: 저장된 대화, 장기 기억, 작업 결과를 이후 작업을 위해 유지합니다.
채팅 네이티브 접근: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, Mattermost, Linear.
모델 자유도: OpenAI 호환 API, 로컬 LLM, 이미지 생성, 검색, 폴백.
작은 코어: MCP, 메모리, 배포, 자동화가 내장된 읽기 쉬운 내부 구조.
스택 소유: 거대한 플랫폼 없이 검사, 커스터마이즈, 셀프 호스팅, 확장.

📦 설치
Python 3.11 이상과 지원되는 모델 제공자 또는 로컬 모델 서버에 대한 접근이 필요합니다. 모델 요금 또는 로컬 하드웨어 요구 사항은 선택한 서비스에 따라 다릅니다. nanobot은 모델 계정을 제공하지 않습니다.

일상 사용에는 안정 릴리스를, 개발 및 최신 기능에는 현재 소스를 선택하세요. 이 README는 현재 소스를 설명하며, 게시된 문서는 릴리스된 버전을 다룹니다.

터미널이나 모델 자격 증명이 처음이신가요? 기술 배경 없이 시작하기를 따르세요. 기존 인스턴스를 업데이트하시나요? 설치 방법에 따른 업데이트 및 복구, 백업 단계, 재시작 확인을 따르세요.

트랙
설치 방법
업데이트 방법
실행되는 것

안정
installer, uv 또는 pip
관리형 installer: WebUI 업데이트; 기타 설치: 원래 패키지 도구
하나의 릴리스된 Python/WebUI/TUI 버전

현재 소스
편집 가능한 Git 체크아웃
git pull --ff-only + 편집 가능한 의존성 동기화
해당 체크아웃의 Python, WebUI, TUI

안정 릴리스: 자동 설정 (권장)

installer가 격리된 Python 환경을 선택하고 설정을 열어줍니다. 아래 두 명령은 서로 다른 운영 체제에 대한 동일한 설치 방법입니다. 시스템에 맞는 명령만 실행하세요.

macOS / Linux
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

Windows PowerShell
irm https: // raw.githubusercontent.com / HKUDS / nanobot / main / scripts / install.ps1 | iex

Installer 세부 정보, 미리보기, 스크립트 검토
기본 명령은 안정 PyPI 릴리스를 설치하거나 업그레이드합니다. 새 설치는 ~/.nanobot/venv 아래의 전용 환경을 사용합니다. 새 로컬 데스크톱에서는 모델 설정을 위해 WebUI를 엽니다. 해당 게이트웨이는 브라우저나 터미널이 닫힌 후에도 계속 실행됩니다. 중지하려면 출력된 게이트웨이 중지 명령을 사용하세요. SSH, 헤드리스, 기존 구성 및 이전 릴리스 설치는 터미널 설정을 사용합니다.

기존 설치는 패키지 관리자, extras, 제약 조건을 유지합니다. 활성 일반 venv는 installer가 관리하는 환경이 아닌 명시적 대상으로 유지됩니다. installer는 시스템 전체 pip를 피하며, nanobot이 PATH에 없을 경우 재사용할 명령을 출력합니다.

환경을 변경하지 않고 계획을 미리 보려면 --dry-run을 전달하세요.

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run
& ([ scriptblock ]::Create((irm https: // raw.githubusercontent.com / HKUDS / nanobot / main / scripts / install.ps1))) -- dry - run
스크립트를 먼저 검토하려면 scripts/install.sh 또는 scripts/install.ps1을 여세요.

이미 uv 또는 pip를 사용 중이신가요? 안정 패키지를 직접 설치하세요
이미 자체 Python 환경을 관리하고 있다면 권장 installer 대신 이것을 사용하세요. 이 명령들은 동일한 안정 nanobot-ai 패키지를 설치하며 설정을 실행하지 않습니다.

uv: 격리된 CLI 설치

uv tool install nanobot-ai
pip: 먼저 가상 환경을 활성화하세요

python -m pip install nanobot-ai
그런 다음 브라우저 설정을 위해 nanobot webui를 실행하거나, 터미널 전용 설정을 위해 nanobot onboard --wizard를 실행하세요. Python SDK의 경우 애플리케이션이 import할 수 있도록 애플리케이션의 가상 환경에 nanobot-ai를 설치하세요. 별도의 uv tool 환경은 해당 위치에서 SDK를 import 가능하게 하지 않습니다.

pip가 externally-managed-environment를 보고하면 권장 installer, uv tool install nanobot-ai, pipx install nanobot-ai 또는 활성화된 가상 환경을 사용하세요. 동일한 방법으로 업그레이드하세요. uv는 uv tool upgrade nanobot-ai, pip는 python -m pip install -U nanobot-ai를 사용합니다.

현재 소스: 개발 체크아웃

Git과 Bun으로 현재 소스 설치
저장소를 클론하고 편집 가능 모드로 설치하세요. 소스 설치는 Git과 Bun이 필요합니다. Bun은 이전 릴리스 바이너리를 다운로드하는 대신 체크아웃에서 일치하는 TUI를 직접 실행합니다.

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m venv .venv
macOS/Linux에서는 source .venv/bin/activate로, Windows PowerShell에서는 .venv\Scripts\Activate.ps1로 활성화한 후 다음을 실행하세요:

python -m pip install -e .
그 후 일반 명령은 안정 설치와 동일합니다. nanobot은 이 체크아웃에서 TUI를 실행하며, nanobot webui는 오래된 프론트엔드 자산을 자동으로 재빌드합니다. 이전 인스턴스를 중지한 후 git pull --ff-only로 Python, TUI, WebUI 소스를 함께 업데이트하세요. Python 의존성이 변경되면 python -m pip install -e .를 다시 실행한 후 인스턴스를 재시작하세요. 기여자는 CONTRIBUTING.md도 읽어보세요.

지원 플랫폼, 번들 UI, 릴리스 트랙
게시된 패키지에는 WebUI가 포함되며, 지원되는 플랫폼 wheel에는 네이티브 TUI도 포함됩니다. 소스 배포 설치에서는 첫 사용 시 체크섬이 검증되고 버전이 일치하는 TUI 아카이브(라이선스, 고지, 해당 애플리케이션 소스, 소스 제공, 재링크 지침 포함)를 가져올 수 있습니다.

플랫폼 wheel에는 WebUI와 네이티브 터미널 UI가 모두 포함됩니다: macOS 13+ (Apple Silicon 및 Intel), glibc 2.17+ Linux (ARM64 및 x64), Windows x64. x64 런타임은 SSE4.2가 필요합니다. Pip이 일치하는 wheel을 선택하며, TUI를 열 때 별도의 GitHub 다운로드나 Bun 설치가 필요하지 않습니다. 지원되는 대상에서 소스 배포 설치를 하면 일치하는 체크섬 GitHub 릴리스 아카이브를 사용할 수 있습니다. 다른 플랫폼에서는 nanobot --classic 또는 WebUI를 사용하세요.

[!IMPORTANT]

최신 기능과 실험을 원한다면 소스에서 설치하세요.

가장 안정적인 일상 경험을 원한다면 PyPI 또는 uv로 설치하세요.

설치 방법을 하나 선택하세요:

트랙
설치 방법
업데이트 방법
실행되는 것

안정
installer, uv 또는 pip
동일한 설치 방법
하나의 릴리스된 Python/WebUI/TUI 버전

현재 소스
편집 가능한 Git 체크아웃
git pull --ff-only + 편집 가능한 의존성 동기화
해당 체크아웃의 Python, WebUI, TUI

설치 확인 또는 nanobot 명령 찾기
설치 확인:

nanobot --version
nanobot이 PATH에 없으면 installer가 출력한 명령을 재사용하거나 기존 설치의 Python 실행 파일을 -I -m nanobot으로 실행하세요. uv/pipx의 경우 원래 관리자로 해당 환경을 찾으세요. 기존 설치를 관리하기 위해 임시 도구 환경을 사용하지 마세요.

설치 후 빠른 시작으로 계속하세요. nanobot이 PATH에 없으면 installer가 출력한 정확한 명령을 사용하세요.

🚀 빠른 시작
브라우저에서 nanobot 열기

installer가 이미 WebUI를 열었다면 거기서 계속하세요. 그렇지 않으면 다음을 실행하세요:

nanobot webui
브라우저를 사용하는 동안 런처 터미널을 열어 두세요. 공유 로컬 게이트웨이를 시작하거나 참여하고 첫 실행 WebUI를 localhost에 바인딩합니다. 브라우저가 열리지 않으면 터미널에 출력된 전체 로그인 링크를 복사하세요(# 이후의 모든 내용 포함). 이 자격 증명은 비공개로 유지하세요. SSH 또는 헤드리스 호스트의 경우 아래의 원격 브라우저 또는 터미널 전용 지침을 사용하세요.

처음 세 단계

Settings → Models를 열고 자격 증명 또는 지원되는 로그인으로 제공자/모델 프리셋을 저장하세요. 전체 단계가 필요하면 모델 설정을 참조하세요.
새 토픽을 시작하고 Hello!를 보내 모델 연결을 확인하세요.
파일 작업을 시도하려면 notes.txt 사본을 연습 폴더에 넣고, 해당 폴더와 Restricted access를 선택한 후 다음과 같이 요청하세요: "Read notes.txt and write a short summary to summary.md." 해당 폴더의 summary.md를 열어 결과를 확인하세요. 첫 파일 작업을 참조하세요.

정상 응답은 제공자/모델과 브라우저 연결을 확인합니다. 파일 작업은 선택한 프로젝트와 해당 파일 권한을 별도로 확인합니다. 파일을 첨부하면 대화로 전송되며, 선택한 프로젝트 폴더를 변경하지는 않습니다.

그런 다음 같은 채팅에서 다음 목표를 설명하세요. 예: "I am already using the WebUI. Help me connect Telegram and allow only my account." 활성화된 nanobot-document 스킬은 설치와 함께 번들된 문서를 참조할 수 있습니다. 예시, 명시적 호출, 가용성은 nanobot으로 계속하기를 참조하세요.

SSH를 통해 원격 서버에서 WebUI 열기
서버에 nanobot을 설치한 후 서버 측 브라우저를 열지 않고 WebUI를 시작하세요:

nanobot webui --no-open
해당 서버 터미널을 계속 실행하세요. 자신의 컴퓨터의 두 번째 터미널에서 SSH를 통해 기본 WebUI 포트를 포워딩하세요:

ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 user@SERVER
user@SERVER를 SSH 로그인으로 바꾸고 터널을 열어 두세요. 로컬 브라우저에서 서버 런처가 출력한 전체 로그인 링크를 # 프래그먼트를 유지한 채로 여세요. 이 링크는 http://127.0.0.1:8765를 사용하며, 이제 터널을 통해 서버에 도달합니다. Settings → Models를 완료하고 Hello!를 보내세요. 로컬 포트 8765가 사용 중이면 터널에서 다른 로컬 포트를 사용하고 브라우저 링크의 포트만 변경하세요. 서버 리스너는 localhost에 유지하세요. Docker, 공개 엔드포인트 또는 서비스 관리에 대해서는 배포를 참조하세요.

터미널 전용 설정, 원샷 확인, TUI
모델이 아직 구성되지 않았다면 터미널 마법사를 사용하세요:

nanobot onboard --wizard
브라우저를 열지 않고 한 번의 응답을 확인하세요:

nanobot -m " Hello! "
대화형 작업의 경우 터미널 클라이언트를 여세요:

nanobot
네이티브 TUI는 실행 디렉터리를 프로젝트 워크스페이스로 사용하며 WebUI와 저장된 대화 및 로컬 게이트웨이를 공유합니다. 명시적 nanobot agent 형식은 호환성을 위해 계속 사용할 수 있습니다.

명령을 찾으려면 /를 입력하고, 대화를 전환하려면 /sessions, 앱, MCP 서버 또는 저장된 세션을 언급하려면 @를 입력하세요.
Ctrl+V 또는 Alt+V로 클립보드 이미지를 붙여넣고, $로 스킬 참조를 완성하세요.
파일 변경을 검사하려면 /diff, 세션 컨텍스트를 검사하려면 /context, 완료된 응답에서 새 세션으로 계속하려면 /branch를 사용하세요.
Enter를 눌러 전송하세요. nanobot이 작업하는 동안 Enter는 즉시 전송하고 Tab은 현재 응답 후 전송합니다. 줄바꿈을 추가하려면 Shift+Enter를 누르세요(수정된 Enter 키를 구분할 수 없는 터미널에서는 Ctrl+J가 작동합니다).
게이트웨이를 백그라운드 모드로 승격하려면 /detach를 사용하세요…