diff --git a/README.md b/README.md index fe2ebe45a..80a0fbca2 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@

-🐈 **nanobot** is an **ultra-lightweight** personal AI assistant inspired by [Clawdbot](https://github.com/openclaw/openclaw) +🐈 **nanobot** is an **ultra-lightweight** personal AI assistant inspired by [Clawdbot](https://github.com/openclaw/openclaw) ⚡️ Delivers core agent functionality in just **~4,000** lines of code — **99% smaller** than Clawdbot's 430k+ lines. @@ -104,6 +104,7 @@ nanobot onboard **2. Configure** (`~/.nanobot/config.json`) For OpenRouter - recommended for global users: + ```json { "providers": { @@ -166,19 +167,21 @@ nanobot agent -m "Hello from my local LLM!" ## 💬 Chat Apps -Talk to your nanobot through Telegram, Discord, WhatsApp, Feishu or Matrix(Element) — anytime, anywhere. +Talk to your nanobot through Telegram, Discord, WhatsApp, Feishu, DingTalk, or Matrix (Element) — anytime, anywhere. -| Channel | Setup | -|---------|-------| -| **Telegram** | Easy (just a token) | -| **Discord** | Easy (bot token + intents) | -| **WhatsApp** | Medium (scan QR) | -| **Feishu** | Medium (app credentials) | +| Channel | Setup | +| -------------------- | ---------------------------------- | +| **Telegram** | Easy (just a token) | +| **Discord** | Easy (bot token + intents) | +| **WhatsApp** | Medium (scan QR) | +| **Feishu** | Medium (app credentials) | +| **Matrix (Element)** | Medium (homeserver + access token) |
Telegram (Recommended) **1. Create a bot** + - Open Telegram, search `@BotFather` - Send `/newbot`, follow prompts - Copy the token @@ -211,15 +214,18 @@ nanobot gateway Discord **1. Create a bot** + - Go to https://discord.com/developers/applications - Create an application → Bot → Add Bot - Copy the bot token **2. Enable intents** + - In the Bot settings, enable **MESSAGE CONTENT INTENT** - (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data **3. Get your User ID** + - Discord Settings → Advanced → enable **Developer Mode** - Right-click your avatar → **Copy User ID** @@ -238,6 +244,7 @@ nanobot gateway ``` **5. Invite the bot** + - OAuth2 → URL Generator - Scopes: `bot` - Bot Permissions: `Send Messages`, `Read Message History` @@ -251,6 +258,67 @@ nanobot gateway
+
+Matrix (Element) + +Uses Matrix sync via `matrix-nio` (including inbound media support). + +**1. Create/choose a Matrix account** + +- Create or reuse a Matrix account on your homeserver (for example `matrix.org`). +- Confirm you can log in with Element. + +**2. Get credentials** + +- You need: + - `userId` (example: `@nanobot:matrix.org`) + - `accessToken` + - `deviceId` (recommended so sync tokens can be restored across restarts) +- You can obtain these from your homeserver login API (`/_matrix/client/v3/login`) or from your client's advanced session settings. + +**3. Configure** + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "homeserver": "https://matrix.org", + "userId": "@nanobot:matrix.org", + "accessToken": "syt_xxx", + "deviceId": "NANOBOT01", + "allowFrom": [], + "groupPolicy": "open", + "groupAllowFrom": [], + "allowRoomMentions": false, + "maxInboundMediaBytes": 20971520 + } + } +} +``` + +> `allowFrom`: Empty allows all senders; set user IDs to restrict access. +> `groupPolicy`: `open`, `mention`, or `allowlist`. +> `groupAllowFrom`: Room allowlist used when `groupPolicy` is `allowlist`. +> `allowRoomMentions`: If `true`, accepts `@room` (`m.mentions.room`) in mention mode. +> `maxInboundMediaBytes`: Max inbound attachment size in bytes (default `20MB`). + +> [!NOTE] +> Matrix E2EE implications: +> +> - Keep a persistent `matrix-store` and stable `deviceId`; otherwise encrypted session state can be lost after restart. +> - In newly joined encrypted rooms, initial messages may fail until Olm/Megolm sessions are established. +> - The bot currently sends with `ignore_unverified_devices=true` (more compatible, less strict than verified-only sending). +> - Changing `accessToken`/`deviceId` effectively creates a new device and may require session re-establishment. + +**4. Run** + +```bash +nanobot gateway +``` + +
+
WhatsApp @@ -294,6 +362,7 @@ nanobot gateway Uses **WebSocket** long connection — no public IP required. **1. Create a Feishu bot** + - Visit [Feishu Open Platform](https://open.feishu.cn/app) - Create a new app → Enable **Bot** capability - **Permissions**: Add `im:message` (send messages) @@ -339,6 +408,7 @@ nanobot gateway Uses **Stream Mode** — no public IP required. **1. Create a DingTalk bot** + - Visit [DingTalk Open Platform](https://open-dev.dingtalk.com/) - Create a new app -> Add **Robot** capability - **Configuration**: @@ -379,22 +449,23 @@ Config file: `~/.nanobot/config.json` ### Providers > [!TIP] +> > - **Groq** provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed. > - **Zhipu Coding Plan**: If you're on Zhipu's coding plan, set `"apiBase": "https://open.bigmodel.cn/api/coding/paas/v4"` in your zhipu provider config. -| Provider | Purpose | Get API Key | -|----------|---------|-------------| -| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | -| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | -| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | -| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | -| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | -| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | -| `aihubmix` | LLM (API gateway, access to all models) | [aihubmix.com](https://aihubmix.com) | -| `dashscope` | LLM (Qwen) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | -| `moonshot` | LLM (Moonshot/Kimi) | [platform.moonshot.cn](https://platform.moonshot.cn) | -| `zhipu` | LLM (Zhipu GLM) | [open.bigmodel.cn](https://open.bigmodel.cn) | -| `vllm` | LLM (local, any OpenAI-compatible server) | — | +| Provider | Purpose | Get API Key | +| ------------ | ----------------------------------------- | -------------------------------------------------------------------- | +| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | +| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | +| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | +| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | +| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | +| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | +| `aihubmix` | LLM (API gateway, access to all models) | [aihubmix.com](https://aihubmix.com) | +| `dashscope` | LLM (Qwen) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `moonshot` | LLM (Moonshot/Kimi) | [platform.moonshot.cn](https://platform.moonshot.cn) | +| `zhipu` | LLM (Zhipu GLM) | [open.bigmodel.cn](https://open.bigmodel.cn) | +| `vllm` | LLM (local, any OpenAI-compatible server) | — |
Adding a New Provider (Developer Guide) @@ -427,42 +498,40 @@ That's it! Environment variables, model prefixing, config matching, and `nanobot **Common `ProviderSpec` options:** -| Field | Description | Example | -|-------|-------------|---------| -| `litellm_prefix` | Auto-prefix model names for LiteLLM | `"dashscope"` → `dashscope/qwen-max` | -| `skip_prefixes` | Don't prefix if model already starts with these | `("dashscope/", "openrouter/")` | -| `env_extras` | Additional env vars to set | `(("ZHIPUAI_API_KEY", "{api_key}"),)` | -| `model_overrides` | Per-model parameter overrides | `(("kimi-k2.5", {"temperature": 1.0}),)` | -| `is_gateway` | Can route any model (like OpenRouter) | `True` | -| `detect_by_key_prefix` | Detect gateway by API key prefix | `"sk-or-"` | -| `detect_by_base_keyword` | Detect gateway by API base URL | `"openrouter"` | -| `strip_model_prefix` | Strip existing prefix before re-prefixing | `True` (for AiHubMix) | +| Field | Description | Example | +| ------------------------ | ----------------------------------------------- | ---------------------------------------- | +| `litellm_prefix` | Auto-prefix model names for LiteLLM | `"dashscope"` → `dashscope/qwen-max` | +| `skip_prefixes` | Don't prefix if model already starts with these | `("dashscope/", "openrouter/")` | +| `env_extras` | Additional env vars to set | `(("ZHIPUAI_API_KEY", "{api_key}"),)` | +| `model_overrides` | Per-model parameter overrides | `(("kimi-k2.5", {"temperature": 1.0}),)` | +| `is_gateway` | Can route any model (like OpenRouter) | `True` | +| `detect_by_key_prefix` | Detect gateway by API key prefix | `"sk-or-"` | +| `detect_by_base_keyword` | Detect gateway by API base URL | `"openrouter"` | +| `strip_model_prefix` | Strip existing prefix before re-prefixing | `True` (for AiHubMix) |
- ### Security > [!TIP] > For production deployments, set `"restrictToWorkspace": true` in your config to sandbox the agent. -| Option | Default | Description | -|--------|---------|-------------| -| `tools.restrictToWorkspace` | `false` | When `true`, restricts **all** agent tools (shell, file read/write/edit, list) to the workspace directory. Prevents path traversal and out-of-scope access. | -| `channels.*.allowFrom` | `[]` (allow all) | Whitelist of user IDs. Empty = allow everyone; non-empty = only listed users can interact. | - +| Option | Default | Description | +| --------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tools.restrictToWorkspace` | `false` | When `true`, restricts **all** agent tools (shell, file read/write/edit, list) to the workspace directory. Prevents path traversal and out-of-scope access. | +| `channels.*.allowFrom` | `[]` (allow all) | Whitelist of user IDs. Empty = allow everyone; non-empty = only listed users can interact. | ## CLI Reference -| Command | Description | -|---------|-------------| -| `nanobot onboard` | Initialize config & workspace | -| `nanobot agent -m "..."` | Chat with the agent | -| `nanobot agent` | Interactive chat mode | -| `nanobot gateway` | Start the gateway | -| `nanobot status` | Show status | -| `nanobot channels login` | Link WhatsApp (scan QR) | -| `nanobot channels status` | Show channel status | +| Command | Description | +| ------------------------- | ----------------------------- | +| `nanobot onboard` | Initialize config & workspace | +| `nanobot agent -m "..."` | Chat with the agent | +| `nanobot agent` | Interactive chat mode | +| `nanobot gateway` | Start the gateway | +| `nanobot status` | Show status | +| `nanobot channels login` | Link WhatsApp (scan QR) | +| `nanobot channels status` | Show channel status |
Scheduled Tasks (Cron) @@ -547,7 +616,6 @@ PRs welcome! The codebase is intentionally small and readable. 🤗 - ## ⭐ Star History
@@ -565,7 +633,6 @@ PRs welcome! The codebase is intentionally small and readable. 🤗 Views

-

nanobot is for educational, research, and technical exchange purposes only