nanobot

ultra-lightweight personal AI agent · v0.1.5 · Python ≥3.11 · MIT

1 — 概要
What is nanobot

nanobot は HKUDS が開発する超軽量パーソナル AI エージェント。OpenClaw にインスパイアされ、フルスタック代替比で 99% 少ないコード行数 でコアエージェント機能を実現している。

99%
コード削減
20+
LLM プロバイダー
11+
チャンネル
MCP
対応
Ultra-Lightweight
安定した長時間稼働向けに設計された軽量実装。起動高速、リソース消費最小。
Research-Ready
読みやすく変更しやすいクリーンなコード。研究・拡張・学習に最適。
Easy-to-Use
nanobot onboard 一発でセットアップ完了。ウィザード付き対話型初期化も可能。
Multi-Instance
--config フラグで複数インスタンスを独立して運用。チャンネル別・テナント別の分離も容易。
2 — アーキテクチャ
システム構成

CLI / Gateway がエントリポイントとなり、Message Bus を介してチャンネルと Agent Loop が疎結合で接続されている。

%%{init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#f5e9cc', 'primaryTextColor': '#1a1a2e', 'primaryBorderColor': '#c9a74d', 'lineColor': '#8c7340', 'secondaryColor': '#e8eef5', 'tertiaryColor': '#f0f4f8', 'background': '#faf9f7', 'fontSize': '15px' }}}%% flowchart TD CLI["nanobot CLI\nonboard / agent / gateway"] CLI --> LOOP["Agent Loop\nloop.py · context.py"] CLI --> GW["Gateway\n:18790"] GW --> BUS["Message Bus"] BUS <--> CH["Channels\nTelegram · Discord · Slack\nFeishu · WhatsApp · Email\n+ 6 more"] BUS --> LOOP LOOP --> PROV["LLM Providers\nOpenRouter · Anthropic · OpenAI\n+ 20 more"] LOOP --> TOOLS["Built-in Tools\nweb · exec · file · mcp"] LOOP --> MEM["Memory / Session\nDream consolidation"] LOOP --> SKILLS["Skills\n(bundled + custom)"] CRON["Cron / Heartbeat"] --> BUS classDef box fill:#f5e9cc,stroke:#c9a74d,color:#3a2a0a classDef bus fill:#e3edf8,stroke:#7090c0,color:#1a3060 classDef prov fill:#e8f5ee,stroke:#60a080,color:#1a3020 class CLI,GW box class BUS,CH bus class PROV,TOOLS,MEM,SKILLS prov

モジュール構成

agent/
コア: loop.py（LLM↔ツール実行ループ）, context.py（プロンプト構築）, memory.py, skills.py, subagent.py
channels/
チャットチャンネル連携。プラグイン対応で独自チャンネルも追加可能
providers/
LLM プロバイダーレジストリ。2 ステップで新プロバイダーを追加できる
bus/
メッセージルーティング。チャンネルとエージェントを疎結合に接続
cron/ heartbeat/
スケジュールタスク・定期起動（HEARTBEAT.md による 30 分間隔 wake-up）
session/ config/
会話セッション管理と JSON 設定スキーマ（Pydantic）
3 — クイックスタート
2 分でエージェント起動
1

インストール — pip / uv / source から選択:

# PyPI（安定版）
pip install nanobot-ai

# uv（推奨 — 高速）
uv tool install nanobot-ai

# ソースから（最新機能）
git clone https://github.com/HKUDS/nanobot.git
cd nanobot && pip install -e .
2

初期化 — config と workspace を生成:

nanobot onboard
# または対話型ウィザード
nanobot onboard --wizard
3

設定 — ~/.nanobot/config.json を編集:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  }
}
4

チャット — CLI で即座に対話:

# 対話モード
nanobot agent

# 1 回だけ
nanobot agent -m "README を要約して"

# ゲートウェイ（チャンネル接続）
nanobot gateway
API キーについて: グローバルユーザーには openrouter（全モデルアクセス）が推奨。環境変数 ${VAR_NAME} 参照もサポートしており、シークレットを config.json に直書きしなくて済む。
CLI リファレンス
コマンド説明
nanobot onboard~/.nanobot/ に config と workspace を初期化
nanobot onboard --wizard対話型セットアップウィザード起動
nanobot agent -m "..."エージェントに 1 メッセージ送信
nanobot agent対話モード（/exit で終了）
nanobot gatewayゲートウェイ起動（チャンネル接続）
nanobot serveOpenAI 互換 API サーバー起動（ポート 8900）
nanobot status設定・プロバイダー状態を表示
nanobot provider login <name>OAuth プロバイダー認証（Copilot / Codex）
nanobot channels login <ch>チャンネル認証（WhatsApp QR scan 等）
4 — チャンネル連携
対応チャンネル一覧

すべてのチャンネルは channels.*.allowFrom でアクセス制御できる。空配列はデフォルトで全拒否（["*"] で全許可）。

チャンネル接続方式必要なもの備考
Telegram 推奨 Polling / WebSocket @BotFather トークン ストリーミング対応、グループポリシー設定可
Discord WebSocket Bot トークン + Message Content Intent groupPolicy: "mention" でメンション時のみ応答
WhatsApp Node.js bridge Node.js ≥18 + QR スキャン アップグレード時は bridge の再ビルドが必要
WeChat (Weixin) HTTP long-poll pip install nanobot-ai[weixin] デスクトップクライアント不要
Feishu WebSocket long connection App ID + App Secret + CardKit 権限 公開 IP 不要、CardKit streaming 対応
DingTalk Stream Mode AppKey + AppSecret 公開 IP 不要
Slack Socket Mode Bot Token + App-Level Token groupPolicy: "mention" / "open" / "allowlist"
Matrix Matrix SDK pip install nanobot-ai[matrix] + homeserver URL E2EE 対応（推奨: password login）
Email IMAP / SMTP polling IMAP + SMTP 認証情報 添付ファイル受信・自動返信 on/off 可
QQ botpy SDK / WebSocket AppID + AppSecret プライベートメッセージのみ、サンドボックスでテスト
Wecom (企業微信) WebSocket long connection pip install nanobot-ai[wecom] AI ボット API モード
Mochat Socket.IO WebSocket Claw トークン（自動セットアップ可） nanobot に「Mochat に参加して」と送るだけで自動構成
チャンネルプラグイン: 独自チャンネルの追加は docs/CHANNEL_PLUGIN_GUIDE.md を参照。プラグイン形式で任意の通信チャンネルを接続できる。
5 — LLM プロバイダー
対応プロバイダー

プロバイダーは nanobot/providers/registry.py に ProviderSpec を 1 エントリ追加するだけで拡張できる。config.json に providers.<name> フィールドも追加する必要がある（2 ステップのみ）。

プロバイダー種別取得先
openrouter 推奨ゲートウェイ（全モデルアクセス）openrouter.ai
anthropicClaude ダイレクトconsole.anthropic.com
openaiGPT + Whisper 音声転写platform.openai.com
azure_openaiAzure OpenAIportal.azure.com
deepseekDeepSeek ダイレクトplatform.deepseek.com
groqLLM + Whisper 転写（デフォルト）console.groq.com
geminiGemini ダイレクトaistudio.google.com
volcengine / byteplusVolcEngine（国内 / 海外）volcengine.com / byteplus.com
minimaxMiniMax ダイレクトplatform.minimaxi.com
dashscopeQwen（Alibaba）dashscope.console.aliyun.com
moonshotMoonshot / Kimiplatform.moonshot.cn
zhipuZhipu GLMopen.bigmodel.cn
stepfunStep Fun / 阶跃星辰platform.stepfun.com
mimoXiaomi MiMoplatform.xiaomimimo.com
ollamaローカル LLM（API key 不要）ollama.ai
vllmローカル OpenAI 互換サーバー— (any vLLM endpoint)
ovmsIntel GPU / OpenVINO Model Serverdocs.openvino.ai
openai_codexCodex（OAuth、ChatGPT Plus 必須）nanobot provider login openai-codex
github_copilotGitHub Copilot（OAuth）nanobot provider login github-copilot
custom任意の OpenAI 互換エンドポイント—
siliconflow, mistral, aihubmix, qianfan各種サードパーティ各公式サイト参照
6 — 高度な機能
コア機能群
メモリシステム（Dream）

3 層メモリ: SOUL.md（エージェント人格）, USER.md（ユーザー情報）, memory/MEMORY.md（長期記憶）。memory/history.jsonl に追記式で要約履歴を保存。

Dream は定期実行（またはチャット内 /dream コマンド）でメモリを統合。/dream-restore <sha> で過去状態への復元も可能。

MCP（Model Context Protocol）

Stdio（npx / uvx 等）と HTTP（SSE）の両方に対応。Claude Desktop / Cursor の config 形式と互換。

{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y",
          "@modelcontextprotocol/server-filesystem",
          "/path"]
      }
    }
  }
}

enabledTools で登録ツールを絞り込み可能。

Python SDK

CLI なしでライブラリとして利用できる。セッションキーで会話を独立管理。

from nanobot import Nanobot

bot = Nanobot.from_config()
result = await bot.run(
    "README を要約して",
    session_key="user-alice"
)
print(result.content)

AgentHook でツール呼び出し前後のライフサイクルフックも追加できる。

OpenAI 互換 API

nanobot serve で 127.0.0.1:8900 にエンドポイントを公開。既存の OpenAI クライアントからそのまま利用できる。

  • GET /health
  • GET /v1/models
  • POST /v1/chat/completions

"session_id" で会話を分離（省略時は共有デフォルトセッション）。

Docker / Linux Service

公式 Docker イメージは非 root ユーザー（UID 1000）で動作。bubblewrap（bwrap）によるサンドボックスが事前インストール済み。

docker compose run --rm nanobot-cli onboard
vim ~/.nanobot/config.json
docker compose up -d nanobot-gateway

systemd ユーザーサービスとして登録すればログアウト後も常時稼働可能（loginctl enable-linger）。

セキュリティ・サンドボックス

本番運用向け推奨設定:

{
  "tools": {
    "restrictToWorkspace": true,
    "exec": { "sandbox": "bwrap" }
  }
}

bwrap で exec をサンドボックス化（Linux のみ）。channels.*.allowFrom は空配列で全拒否がデフォルト。

チャット内コマンド: /new（会話リセット）, /stop（タスク停止）, /restart（再起動）, /status（状態表示）, /dream（記憶統合即時実行）, /dream-restore（メモリ復元）, /help。すべての対応チャンネルと CLI モードで共通動作。