NanoClaw

Docker 应用程序 from BitCryptic's 2nd Repository

概述

NanoClaw is a lightweight, secure personal AI agent that runs on your own server.
It connects to Telegram and/or Matrix (E2EE) and runs every agent session
inside an isolated Docker container — so the AI only sees what you explicitly give it access to.

Built as a minimal alternative to OpenClaw/Clawdbot, NanoClaw has ~15 source files
you can actually read and understand. No complex config files — customise by
telling Claude Code what you want changed.

Features:

Telegram and Matrix (E2EE) support
Per-group isolated agent containers
Scheduled tasks (morning briefings, weekly reviews, etc.)
Web search and fetch
Agent Swarms (teams of specialised agents)
Memory via per-group CLAUDE.md files

Requirements:

Anthropic API key (console.anthropic.com)
Telegram bot token from @BotFather (for Telegram channel)
Matrix homeserver account, e.g. self-hosted Synapse (for Matrix channel)
Docker socket access (required for agent container isolation)

Messaging Channels:
At least one of Telegram or Matrix must be configured. Both can run simultaneously.

Telegram: Set TELEGRAM_BOT_TOKEN from @BotFather. After starting the container,
send /chatid to your bot and run the registration command — see the project README.

Matrix (E2EE): Set MATRIX_HOMESERVER_URL, MATRIX_BOT_USER_ID, and MATRIX_ACCESS_TOKEN.
MATRIX_BOT_PASSWORD is only needed once to bootstrap cross-signing keys and can
be removed after first successful start.

Optional Integrations:

Tailscale — join your tailnet for secure private access
Home Assistant — smart home control and automation
Vikunja — task and project management
Ollama / LiteLLM — local model inference
Paperclip — AI agent orchestration
UnraidClaw — manage your Unraid servers directly from chat

Project: https://github.com/qwibitai/nanoclaw
Unraid template: https://github.com/bitcryptic-gw/Unraid-nanoclaw
Support: https://forums.Unraid.net/topic/197773-support-nanoclaw-lightweight-secure-ai-agent-for-Unraid/

运行时参数

网络: bridge
外壳: sh
特权: false

模板配置

Docker SocketPathrw

Required. Gives NanoClaw access to the host Docker daemon so it can spin up isolated agent containers for each conversation.

目标: /var/run/docker.sock
默认值: /var/run/docker.sock

AppDataPathrw

Persistent data: SQLite database, sessions, IPC, env copy.

目标: /app/data
默认值: /mnt/cache/appdata/nanoclaw/data

StorePathrw

Persistent store: registered groups, messages, scheduled tasks.

目标: /app/store
默认值: /mnt/cache/appdata/nanoclaw/store

GroupsPathrw

Per-group CLAUDE.md memory files and agent runner source.

目标: /app/groups
默认值: /mnt/cache/appdata/nanoclaw/groups

LogsPathrw

NanoClaw service logs.

目标: /app/logs
默认值: /mnt/cache/appdata/nanoclaw/logs

HOST_PROJECT_ROOTVariable

Required. Host path to the NanoClaw appdata directory. Must match the host-side path of the AppData volume mount so agent containers can resolve volume paths correctly.

默认值: /mnt/cache/appdata/nanoclaw

TELEGRAM_BOT_TOKENVariable

Optional. Telegram bot token from @BotFather. Only required if using Telegram as a messaging channel — Matrix is the recommended primary channel.

Matrix Homeserver URLVariable

URL of your Matrix homeserver, e.g. https://matrix.yourdomain.com. Required for Matrix channel support.

目标: MATRIX_HOMESERVER_URL

Matrix Bot User IDVariable

Full Matrix user ID for the bot account, e.g. @Andy:yourdomain.com. Required for Matrix channel support.

目标: MATRIX_BOT_USER_ID

Matrix Access TokenVariable

Matrix access token for the bot account. Obtain via the Matrix login API or your client. Required for Matrix channel support.

目标: MATRIX_ACCESS_TOKEN

Matrix Bot PasswordVariable

k2 Matrix account password — used once to bootstrap cross-signing keys. Can be removed after first successful bootstrap.

目标: MATRIX_BOT_PASSWORD

ANTHROPIC_API_KEYVariable

Anthropic API key from console.anthropic.com. Use this OR CLAUDE_CODE_OAUTH_TOKEN.

CLAUDE_CODE_OAUTH_TOKENVariable

Claude Pro/Max subscription OAuth token. Use this OR ANTHROPIC_API_KEY. Obtain by running 'claude setup-token' with Claude Code installed.

OneCLI URLVariable

Optional. URL of your OneCLI gateway instance. OneCLI is the upstream default credential provider for agent containers. Leave blank if using the native credential proxy skill instead (self-hosted alternative).

目标: ONECLI_URL

OneCLI API KeyVariable

Optional. API key for your OneCLI gateway. Required only if ONECLI_URL is set. Leave blank if using the native credential proxy skill.

目标: ONECLI_API_KEY

NANOCLAW_TRIGGERVariable

Trigger word the assistant responds to. Default is @Andy. The assistant name is automatically derived from this — e.g. @Andy makes the assistant named Andy.

默认值: @Andy

NANOCLAW_REQUIRE_TRIGGERVariable

Whether the assistant requires the trigger word to respond. Set to false to respond to all messages without needing the trigger.

默认值: true

Agent ModelVariable

Default model for agent containers. Per-group override via settings.json. Use model name with optional [1m] suffix for 1M context (Sonnet only). Examples: haiku, sonnet[1m], claude-opus-4-6

目标: NANOCLAW_AGENT_MODEL
默认值: haiku

Agent EffortVariable

Default reasoning effort for agent containers. Per-group override via settings.json. Valid values: low, medium, high, max.

目标: NANOCLAW_AGENT_EFFORT
默认值: medium

NANOCLAW_EXTRA_MOUNTSVariable

Additional volume mounts passed to agent containers. Format: hostpath:containerpath:ro,hostpath2:containerpath2:rw — e.g. /mnt/cache/logs:/central-logs:ro

NANOCLAW_DOCKER_NETWORKVariable

Docker network for agent containers. Leave blank for default bridge. Set to a custom network name (e.g. ai-local) to isolate agent containers. The NanoClaw container itself must also be on this network.

默认值: ai-local

UNRAIDCLAW_SERVERSVariable

UnraidClaw server config as JSON array. Example: [{"name":"unraid-syd","url":"https://unraid-syd:9876","apiKey":"YOUR_KEY"}]. Supports multiple servers.

Tailscale API Client IDVariable

OAuth client ID from login.tailscale.com/admin/settings/oauth. Used by the assistant to query the Tailscale API for device discovery, monitoring and ACL auditing.

目标: TS_API_CLIENT_ID

Tailscale API Client SecretVariable

OAuth client secret from login.tailscale.com/admin/settings/oauth. Keep this masked — treated as a credential.

目标: TS_API_CLIENT_SECRET

Tailscale TailnetVariable

Your Tailscale tailnet name. Found in the Tailscale admin console.

目标: TS_API_TAILNET
默认值: your-tailnet.ts.net

Home Assistant URLVariable

URL of your Home Assistant instance. Use http://YOUR-UNRAID-IP:8123 if HA is on the same Unraid server.

目标: HA_URL
默认值: http://homeassistant:8123

Home Assistant TokenVariable

Long-lived access token from Home Assistant. Create at Profile → Long-Lived Access Tokens in HA.

目标: HA_TOKEN

Vikunja URLVariable

URL of your Vikunja instance. Use http://vikunja:3456 if Vikunja is on the same Docker network as NanoClaw.

目标: VIKUNJA_URL
默认值: http://vikunja:3456

Vikunja API TokenVariable

Vikunja API token. Create at Settings → API Tokens in the Vikunja UI. Needs Projects (read), Tasks (read/write/update/delete), Task comments (read/write), Task assignees (read/write/delete), and User (read) permissions.

目标: VIKUNJA_TOKEN

Tailscale State DirectoryPathrw

Persistent Tailscale state directory. Prevents new node identity being created on each restart.

目标: /mnt/cache/appdata/nanoclaw/tailscale
默认值: /mnt/cache/appdata/nanoclaw/tailscale

Ollama URLVariable

URL of your Ollama instance. Use http://ollama:11434 if Ollama is on the same Docker network as NanoClaw.

目标: OLLAMA_URL
默认值: http://ollama:11434

LiteLLM URLVariable

Base URL for LiteLLM API. If set, enables the LiteLLM MCP skill for model discovery and Ollama sync.

目标: LITELLM_URL
默认值: http://litellm:4000

LiteLLM Master KeyVariable

Master key for LiteLLM model management API. Required for Ollama auto-sync into LiteLLM.

目标: LITELLM_MASTER_KEY

Paperclip URLVariable

URL of your Paperclip instance. Use http://paperclip:3100 if on the same Docker network.

目标: PAPERCLIP_URL
默认值: http://paperclip:3100

Paperclip Agent JWT SecretVariable

JWT secret from Paperclip for agent API auth. Found in Paperclip appdata at instances/default/.env

目标: PAPERCLIP_AGENT_JWT_SECRET

Paperclip Agent IDVariable

UUID of the NanoClaw agent in Paperclip. Found in Paperclip UI under Agents.

目标: PAPERCLIP_AGENT_ID

Paperclip Company IDVariable

UUID of your Paperclip company. Found in Paperclip UI under Company settings or the URL.

目标: PAPERCLIP_COMPANY_ID

Paperclip Webhook SecretVariable

Bearer token Paperclip uses to authenticate heartbeat calls to NanoClaw.

目标: PAPERCLIP_WEBHOOK_SECRET

Paperclip Group FolderVariable

NanoClaw group folder that receives Paperclip tasks, e.g. telegram_1234567890.

目标: PAPERCLIP_GROUP_FOLDER

Paperclip Webhook PortVariable

Port for the Paperclip webhook server. Default 3102.

目标: PAPERCLIP_WEBHOOK_PORT
默认值: 3102

Credential Proxy (host 3001)Porttcp

Internal credential proxy port used by agent containers to reach the Anthropic API. Only needs to be accessible on the local Docker bridge network. Change if port 3001 is already in use.

目标: 3001
默认值: 3001

Paperclip Webhook (port 3102)Porttcp

Paperclip webhook port for receiving heartbeats from Paperclip.