Clawlet

Ultra-lightweight and efficient personal AI assistant

Clawlet is a lightweight personal AI agent with hybrid semantic memory search — a single static binary with no runtime and no CGO.
Bundled SQLite + sqlite-vec. Drop it on any machine and memory search just works.

This project is inspired by OpenClaw and nanobot.

Install

Download from GitHub Releases.

macOS (Apple Silicon):

curl -L https://github.com/mosaxiv/clawlet/releases/latest/download/clawlet_Darwin_arm64.tar.gz | tar xz
mv clawlet ~/.local/bin/

Quick Start

# Initialize
clawlet onboard \
  --openrouter-api-key "sk-or-..." \
  --model "openrouter/anthropic/claude-sonnet-4.5"

# Check effective configuration
clawlet status

# Chat
clawlet agent -m "What is 2+2?"

Configuration (~/.clawlet/config.json)

Config file: ~/.clawlet/config.json

Supported providers

clawlet currently supports these LLM providers:

• OpenAI (openai/<model>, API key: env.OPENAI_API_KEY)
• OpenAI Codex (OAuth) (openai-codex/<model>, no API key; login: clawlet provider login openai-codex)
• OpenRouter (openrouter/<provider>/<model>, API key: env.OPENROUTER_API_KEY)
• Anthropic (anthropic/<model>, API key: env.ANTHROPIC_API_KEY)
• Gemini (gemini/<model>, API key: env.GEMINI_API_KEY or env.GOOGLE_API_KEY)
• Local (Ollama / vLLM / OpenAI-compatible local endpoint) (ollama/<model> or local/<model>, default base URL: http://localhost:11434/v1, API key optional)

Minimal config (OpenRouter):

{
  "env": { "OPENROUTER_API_KEY": "sk-or-..." },
  "agents": { "defaults": { "model": "openrouter/anthropic/claude-sonnet-4-5" } }
}

Agent generation defaults are configurable:

{
  "agents": {
    "defaults": {
      "model": "openrouter/anthropic/claude-sonnet-4-5",
      "maxTokens": 8192,
      "temperature": 0.7
    }
  }
}

Minimal config (Local via Ollama):

{
  "agents": { "defaults": { "model": "ollama/qwen2.5:14b" } }
}

Minimal config (Local via vLLM using the same ollama/ route):

{
  "agents": { "defaults": { "model": "ollama/meta-llama/Llama-3.1-8B-Instruct" } },
  "llm": { "baseURL": "http://localhost:8000/v1" }
}

OpenAI Codex (OAuth):

# one-time login
clawlet provider login openai-codex

# headless environment (SSH / container)
clawlet provider login openai-codex --device-code

{
  "agents": { "defaults": { "model": "openai-codex/gpt-5.1-codex" } }
}

Option: Memory search setup

To enable semantic memory search, add memorySearch to the agent defaults:

{
  "env": {
    "OPENAI_API_KEY": "sk-..."
  },
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "openai",
        "model": "text-embedding-3-small"
      }
    }
  }
}

Local embedding (Ollama / OpenAI-compatible local endpoint):

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "openai",
        "model": "nomic-embed-text",
        "remote": {
          "baseURL": "http://localhost:11434/v1"
        }
      }
    }
  }
}

When enabled:

• The agent gains memory_search and memory_get tools for retrieving past context.
• clawlet indexes MEMORY.md, memory.md, and memory/**/*.md for retrieval.
• The index DB is created at {workspace}/.memory/index.sqlite.

When disabled (default):

• memorySearch.enabled defaults to false; the search tools are not exposed to the model.
• Memory files (memory/MEMORY.md, memory/YYYY-MM-DD.md) are still injected into context as usual.
• Normal chat behavior is otherwise unchanged.

Security

Secure Defaults

• tools.restrictToWorkspace defaults to true (tools can only access files inside the workspace directory)
• gateway.listen defaults to 127.0.0.1:18790
• gateway.allowPublicBind defaults to false

Security Checklist

Tools

Multimodal input (audio/image/attachments)

Inbound channel messages can include attachments. clawlet can:

• send images to vision-capable models,
• transcribe audio using the configured provider,
• and inline text-like file attachments into the user context.

Configure under tools.media (the values below are the current default values):

{
  "tools": {
    "media": {
      "enabled": true,
      "audioEnabled": true,
      "imageEnabled": true,
      "attachmentEnabled": true,
      "maxAttachments": 4,
      "maxFileBytes": 20971520,
      "maxInlineImageBytes": 5242880,
      "maxTextChars": 12000,
      "downloadTimeoutSec": 20
    }
  }
}

Chat Apps

Chat app integrations are configured under channels (examples below).

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABCDEF...",
      "allowFrom": ["123456789"]
    }
  }
}

clawlet gateway

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["15551234567"]
    }
  }
}

# one-time login (required before gateway)
clawlet channels login --channel whatsapp

# normal runtime
clawlet gateway

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

clawlet gateway

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "groupPolicy": "mention",
      "allowFrom": ["U012345"]
    }
  }
}

clawlet gateway

CLI Reference

clawlet cron add formats

--message is required, and exactly one of --every, --cron, or --at must be set.

# Every N seconds
clawlet cron add --message "summarize my inbox" --every 3600

# Cron expression (5-field)
clawlet cron add --message "daily standup notes" --cron "0 9 * * 1-5"

# Run once at a specific time (RFC3339)
clawlet cron add --message "remind me" --at "2026-02-10T09:00:00Z"

# Deliver to a chat (requires both --channel and --to)
clawlet cron add --message "ping" --every 600 --channel slack --to U012345

🐳 Docker

Using Pre-built Images

Pre-built images are available on GitHub Container Registry:

# docker-compose.yml
services:
  clawlet:
    image: ghcr.io/mosaxiv/clawlet:latest
    volumes:
      - ~/.clawlet:/root/.clawlet
    command: gateway
    restart: unless-stopped

docker compose up -d

Building Locally

# Build the image
docker build -t clawlet .

# Initialize config (first time only)
docker run -v ~/.clawlet:/root/.clawlet --rm clawlet onboard

# Edit config on host to add API keys
vim ~/.clawlet/config.json

# Run the gateway
docker run -v ~/.clawlet:/root/.clawlet clawlet gateway

# Or run a single command
docker run -v ~/.clawlet:/root/.clawlet --rm clawlet agent -m "Hello"
docker run -v ~/.clawlet:/root/.clawlet --rm clawlet status