ClawHand

ClawHand is a persistent AI assistant built on the V1 openhands-sdk with A-MEM long-term memory, LiteLLM Proxy for model routing, and a Discord gateway. It learns and evolves through every conversation, maintaining memory across sessions while operating securely within configurable boundaries.

Prerequisites

• Python 3.12+
• LiteLLM Proxy — for routing LLM requests to any provider (OpenAI, Anthropic, Ollama, etc.)
• Discord bot token — for the Discord gateway channel
• ChromaDB — installed automatically as a dependency for vector storage

Installation

# Clone the repository
git clone <repo-url>
cd clawhand

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

Configuration

1. Copy the example configuration:

cp clawhand/config/clawhand.example.yaml clawhand.yaml

2. Edit clawhand.yaml and fill in your values:

llm:
  model: "litellm_proxy/gpt-4o"
  base_url: "http://localhost:4000"
  api_key_env: "LITELLM_PROXY_KEY"    # Name of the env var holding your key

memory:
  llm_model: "litellm_proxy/gpt-4o-mini"
  chromadb_path: "./data/chromadb"

gateway:
  discord:
    enabled: true
    token_env: "DISCORD_BOT_TOKEN"     # Name of the env var holding your token
    allowed_users: []                  # Empty = allow all; add user IDs to restrict

3. Set the required environment variables:

export LITELLM_PROXY_KEY="your-litellm-api-key"
export DISCORD_BOT_TOKEN="your-discord-bot-token"

LiteLLM Proxy Setup

ClawHand routes all LLM requests through a LiteLLM Proxy instance. Start it before running ClawHand:

pip install litellm[proxy]
litellm --config config/litellm_config.yaml --port 4000

Refer to the LiteLLM documentation for proxy configuration details.