Skip to content
BranchesTags

Repository files navigation

nanoClaw

Easy install, 24/7. Lightweight secure AI assistant inspired by OpenClaw.

OpenClaw:  430,000 lines, complex setup, security concerns
nanoClaw:    ~7,500 lines, secure by default, 2-min setup

Features

  • Secure by default - file system sandbox, shell command filtering, prompt injection defense
  • Model-agnostic - Claude, GPT-5, DeepSeek (including v4-flash reasoning), Gemini via OpenRouter or direct API
  • Prompt caching - Anthropic cache_control on system and tools; works through OpenRouter too
  • Extended thinking - reasoning blocks for Claude 4+ and DeepSeek reasoning models, echoed back across tool turns
  • Live streaming - SSE streaming with Telegram edit_text coalescing; first token under a second
  • MCP support - plug in any Model Context Protocol server (filesystem, github, etc.); tools auto-register as mcp__<server>__<tool>
  • Multi-channel - Telegram and Discord; same agent, allow-list and rate-limit per channel
  • Env-var secrets - reference ${DEEPSEEK_API_KEY} in config; keys never in files
  • 2-minute setup - interactive wizard guides configuration
  • No open ports - channel polling, dashboard on localhost only
  • Persistent memory - remembers facts about you across conversations
  • Background tasks - spawn long-running research jobs
  • Scheduled jobs - cron-like recurring tasks
  • Web dashboard - monitor activity, manage settings

Quick Start

Installation

git clone https://github.com/ysz/nanoClaw
cd nanoclaw
pip install -e .

Setup

Run the interactive wizard:

nanoclaw init

The wizard will:

  1. Configure your LLM provider (OpenRouter recommended)
  2. Set up Telegram bot connection
  3. Optionally enable web search (Brave API)
  4. Run security checks

Usage

Start the agent:

nanoclaw serve

Then message your bot on Telegram!

CLI Chat (Testing)

# Interactive chat
nanoclaw chat

# One-shot message
nanoclaw chat -m "What's the weather in Tokyo?"

Other Commands

# Check status
nanoclaw status

# Run security audit
nanoclaw doctor

# Manage scheduled tasks
nanoclaw cron list
nanoclaw cron add --name "Morning news" --message "Summarize tech news" --every 86400
nanoclaw cron remove 1

Architecture

You (Telegram / Discord) --> [nanoClaw Server] --> LLM API (Anthropic / OpenRouter /
                                 |                          OpenAI / DeepSeek / local)
    +-----------+------+---------+---------+------------+
    |           |      |         |         |            |
  Agent      Memory  Tools   MCP clients  Security   Skills
  Loop      (SQLite)        (stdio procs) (6 layers) (~/.nanoclaw/skills)
    |
  Dashboard (localhost:18790)

Security Layers

  1. FileGuard - restricts file access to workspace only
  2. ShellSandbox - blocks dangerous commands, confirms destructive ones
  3. PromptGuard - detects and sanitizes prompt injection attempts
  4. SessionBudget - rate limiting and cost controls
  5. AuditLog - logs all agent actions
  6. SecurityDoctor - validates installation security

Configuration

Config is stored at ~/.nanoclaw/config.json. Any string value supports ${VAR} or ${VAR:default} interpolation from environment variables, so you never have to put secrets in the file.

{
  "providers": {
    "deepseek": {
      "apiKey": "${DEEPSEEK_API_KEY}",
      "defaultModel": "deepseek-v4-flash"
    }
  },
  "agents": {
    "defaults": {
      "model": "deepseek-v4-flash"
    }
  },
  "agent": {
    "streaming": true,
    "promptCaching": true,
    "extendedThinking": false,
    "thinkingBudget": 2000
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}",
      "allowFrom": ["YOUR_USER_ID"]
    },
    "discord": {
      "enabled": false,
      "token": "${DISCORD_BOT_TOKEN}",
      "allowFrom": ["YOUR_DISCORD_ID"]
    }
  },
  "tools": {
    "webSearch": {
      "apiKey": "${BRAVE_API_KEY}"
    }
  },
  "mcpServers": {
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/workspace"]
    }
  },
  "dashboard": {
    "enabled": true,
    "port": 18790
  }
}

Swap providers by placing a different key (openrouter, anthropic, openai, deepseek) under providers. DeepSeek is picked first if configured; OpenRouter next; then Anthropic; then OpenAI.

Built-in Tools

  • web_search - search the internet (Brave API)
  • web_fetch - fetch and read web pages
  • shell_exec - execute shell commands (sandboxed)
  • file_read/write/list - file operations in workspace
  • memory_save/search - persistent memory
  • spawn_task - background tasks

Built-in Skills

  • get_weather - weather lookup
  • github_repo_info - GitHub repository info
  • get_news - news search
  • summarize_url - URL summarization
  • get_time - time in different cities

MCP Servers

nanoClaw speaks the Model Context Protocol over stdio. Point the config at any MCP server and its tools become callable by the agent, registered as mcp__<server>__<tool>.

"mcpServers": {
  "fs": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/workspace"]
  },
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"}
  }
}

Install the server binary on the host (npm i -g @modelcontextprotocol/server-filesystem or similar) and restart nanoclaw serve. The log will print MCP servers started: ['fs', 'github'].

Security note: MCP servers run as child processes under the same user as nanoClaw. They bypass the shell sandbox and FileGuard. Only install servers you trust.

Discord

Telegram is enabled by default. Discord is optional:

pip install -e '.[discord]'

Create a bot in the Discord Developer Portal, enable the Message Content Intent, invite the bot to a server with bot scope plus Send Messages + Read Message History. Then:

"channels": {
  "discord": {
    "enabled": true,
    "token": "${DISCORD_BOT_TOKEN}",
    "allowFrom": ["YOUR_DISCORD_USER_ID"]
  }
}

The bot responds to DMs and @mentions only; it ignores regular channel traffic. Rate-limited at 10 messages/minute per user.

Custom Skills

Add Python files to ~/.nanoclaw/skills/:

from nanoclaw.tools.registry import tool

@tool(
    name="my_skill",
    description="Does something useful",
    parameters={"arg": {"type": "string", "description": "Argument"}}
)
async def my_skill(arg: str) -> str:
    return f"Result: {arg}"

Skills are auto-loaded on startup.

Docker

docker run -d \
  --name nanoclaw \
  --restart unless-stopped \
  -v ~/.nanoclaw/config.json:/app/config/config.json:ro \
  -v ~/.nanoclaw/workspace:/app/workspace \
  -v ~/.nanoclaw/data:/app/data \
  -p 127.0.0.1:18790:18790 \
  nanoclaw/nanoclaw:latest

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type check
mypy nanoclaw/

# Lint
ruff check nanoclaw/

Supported Providers

Provider Models Get API Key
OpenRouter All major models openrouter.ai/keys
DeepSeek deepseek-chat, deepseek-reasoner platform.deepseek.com
Anthropic Claude Sonnet/Opus/Haiku console.anthropic.com
OpenAI GPT-5 family platform.openai.com
Local Ollama, LM Studio -

Requirements

  • Python 3.11+
  • Telegram Bot Token (from @BotFather)
  • LLM API key (any provider above)
  • Optional: Brave Search API key

License

MIT

About

Easy install, Ultra-lightweight secure AI assistant. Inspired by OpenClaw. 🦀

Resources

Readme
MIT license
Activity

Stars

67 stars

Watchers

2 watching

Forks

18 forks
Report repository

Releases

Packages

Contributors

Languages