HKUDS/nanobot — 優良食堂詳しい解説

01 / 概要

何をするものか一文で言うと

ひとことでWebUI・ターミナル・チャットアプリで動作する軽量なセルフホスト型 AI エージェントフレームワーク

nanobotは、Pythonで書かれた超軽量・自己ホスト型のパーソナルAIエージェントフレームワークです。WebUIやターミナル、Discord・Telegram・Slackなどのチャットアプリ上で動作し、ツール・長期記憶・MCP連携・マルチエージェント委任・スケジュール自動化・OpenAI互換APIを小さなコアにまとめています。ファイル構成からは、個人用途でも複数チャンネル運用でも同じエージェントを使い回せる設計だとわかります。

02 / 構造

どう動くのか中核のしくみ

読み方動きの流れを図と一緒にほどきました。

中核はnanobot/agent/loop.pyのAgentLoopです。各チャットチャンネル(discord・dingtalk・emailなど)はmanifest.pyとruntime.pyの組で実装され、受信メッセージはnanobot/bus配下のメッセージバスに載ります。AgentLoopはバスからメッセージを取り出し、nanobot/agent/tools配下のfilesystem・shell・web・mcp・cron・image_generationなどのツールを呼び分けて応答を作ります。生成した返信は同じバス経由で元のチャンネルやWebUIに配信されます。APIサーバー(nanobot/api/server.py)はOpenAI互換の/v1/chat/completionsを提供し、単一の永続セッションにリクエストをルーティングします。Docker配布ではwebuiをビルドしてPython仮想環境に同梱し、entrypoint.shがroot権限でデータディレクトリの所有権を整えたあと、非rootユーザーnanobotに権限を落として起動します。docker-compose.ymlはgateway・api・cliの3サービスをcap_drop ALLで動かし、必要な権限だけcap_addで戻す構成です。

03 / 体験

入れるとこんな体験になりますギット飯が実際にたどった順序

所要ギット飯が実際に導入・実行しながらたどった順序です。

STEP 01
macOSやLinuxならinstall.shを、Windowsならinstall.ps1をcurlまたはirmで実行し、nanobotコマンドを導入します。
STEP 02
公開パッケージ版を初回起動すると、チェックサム付きのバージョン一致TUIアーカイブが自動で取得されます。
STEP 03
CLIで1回分のやり取りを試すと、設定済みのLLMプロバイダーからテキストが返ってくることを確認できます。
STEP 04
ブラウザでWebUIを開くと、DiscordやDingTalkなどのチャンネル設定画面でトークンや許可リストを入力できます。
STEP 05
docker-compose upでgateway・api・cliを起動すると、entrypoint.shがデータディレクトリの権限を調整したあと非rootユーザーで常駐します。
STEP 06
チャンネルを有効化すると、起動時にそのチャンネル専用の依存パッケージが追加インストールされます。

04 / 成果物

何が手に入るのか導入後に手元に残るもの

実行すると、ローカルまたはサーバー上で常駐するパーソナルAIエージェントが手に入ります。WebUI・CLI・OpenAI互換API・チャットアプリの中から好みの入口を選び、同じエージェントに話しかけられます。ファイル操作やシェル実行、Web検索、MCPツール、cronによる自動化を状況に応じて呼び出してくれます。セッション履歴と長期記憶(Dream)により、会話をまたいだ文脈保持も期待できます。

05 / 注意

ここは先に知っておいてください先に知っておくとよいこと

正直なところ誰にでも合うとは言いにくいところです。

公開パッケージ版は初回起動時にネットワーク経由でTUIアーカイブを取得するため、完全オフライン環境では別途準備が必要です。

ソースからのインストールにはGitとBun、Python3.11以上が前提で、環境構築の手間が増えます。

Dockerコンテナは起動直後こそroot権限で動き、entrypoint.shがchown後に非rootへ落とす設計のため、権限周りの挙動を理解してから使うのが安全です。

有効化したチャンネルごとにmanifest定義の依存パッケージが起動時に追加インストールされるため、チャンネルを増やすほど起動時間が延びます。

06 / 結論

ギット飯の結論食べてみる価値のある一膳か

ギット飯の最終判断優良食堂

個人用のAIエージェントを、特定チャットアプリやクラウドサービスに縛られず自前運用したい人に向いています。DiscordやTelegランなど複数チャンネルを1つのエージェントで束ねたい場合や、cronによる長時間タスクの自動化、OpenAI互換APIとしての社内利用を考える開発者にも合います。README・Dockerfile・compose・エージェントループやツール群のソース構成が一貫しており、チャンネル実装がmanifestとruntimeとwebuiの型で揃っている点から、設計は実装に沿っていると判断できます。ただし応答品質や各チャンネルの安定性は利用するLLMプロバイダーや接続先チャットアプリの仕様に左右されるため、そこは自分の用途で確かめる必要があります。