LunaeClaw

Production-minded multi-channel agent runtime

Language / 语言: English | 简体中文

LunaeClaw is built for operators who need an agent runtime they can actually deploy and maintain, not just demo.

Prerequisites: Python 3.11+, uv; Node.js 20+ only if enabling WhatsApp bridge.

git clone <your-repo-url>
cd LunaeClaw
uv sync --extra dev
uv run lunaeclaw onboard
uv run lunaeclaw gateway
# another shell
uv run lunaeclaw webui --host 0.0.0.0 --port 18791

# inside Ubuntu (WSL2)
sudo apt update
sudo apt install -y curl git python3 python3-venv python3-pip
curl -LsSf https://astral.sh/uv/install.sh | sh

git clone <your-repo-url>
cd LunaeClaw
uv sync --extra dev
uv run lunaeclaw onboard
uv run lunaeclaw gateway

git clone <your-repo-url>
cd LunaeClaw
mkdir -p ./.lunaeclaw-data
docker compose up -d --build lunaeclaw-gateway lunaeclaw-webui
docker compose logs -f --tail=200

Default ports:

• Gateway 18790
• WebUI 18791

Notes:

• ./.lunaeclaw-data is the default host bind-mount for runtime state (config.json, .env, runtime/, sessions, tokens). On servers this appears as <repo>/.lunaeclaw-data and is expected.
• To change host storage location, set LUNAECLAW_HOST_DATA_DIR=/abs/path before docker compose up.
• If no provider/model is configured yet, gateway stays in waiting_config (no restart storm). Configure API key/model in WebUI or config.json, then it will switch to running.

git clone <your-repo-url>
cd LunaeClaw
pip install -e .
lunaeclaw onboard
lunaeclaw gateway

~/.lunaeclaw/config.json

{
  "providers": {
    "endpoints": {
      "openai": {
        "type": "openai_compatible",
        "apiBase": "https://api.openai.com/v1",
        "apiKey": "${OPENAI_API_KEY}",
        "models": ["gpt-4o-mini", "gpt-4.1-mini"]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "openai/gpt-4o-mini",
      "temperature": 0.1
    }
  }
}

~/.lunaeclaw/.env

OPENAI_API_KEY=sk-xxx

Run a health check:

lunaeclaw doctor

Current CI is ubuntu-latest. Other environments are supported by dependency/runtime design and common operator usage; always run lunaeclaw doctor after setup.

LunaeClaw/
├── lunaeclaw/              # runtime source (app/core/capabilities/platform/services)
├── bridge/                 # WhatsApp Node.js bridge
├── tests/public/           # public regression tests
├── docs/public/            # publishable governance docs
├── scripts/                # quality/release helper scripts
├── docker-compose.yml      # local production-like deployment
├── Dockerfile              # runtime image build
└── pyproject.toml          # package metadata + dependencies

~/.lunaeclaw/
├── config.json
├── .env
├── env/
├── workspace/
├── mcp/
├── skills/
├── media/
├── exports/
└── bridge/                 # copied/compiled WhatsApp bridge runtime

# overall runtime status
lunaeclaw status

# config/runtime diagnostics
lunaeclaw doctor

# per-channel config status
lunaeclaw channels status

# WhatsApp bridge login flow
lunaeclaw channels login

Before exposing the runtime to real users:

• configure allowFrom on every enabled channel (empty list means open access)
• set file permissions: ~/.lunaeclaw as 700, config/env as 600
• run with a non-root user
• if WhatsApp is enabled, set channels.whatsapp.bridgeToken
• apply SECURITY.md

• Upstream foundation: HKUDS/nanobot
• Core libraries used heavily: litellm, pydantic, python-telegram-bot, websockets, @whiskeysockets/baileys

Thanks to upstream and ecosystem maintainers.

MIT. See LICENSE.