Openclaw Hub

OpenClaw Hub

[](https://github.com/openclaw-community/openclaw-hub/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org) [](https://github.com/openclaw-community/openclaw-hub/releases)

> AI-specific ESB middleware for multi-LLM orchestration with MCP integration

Save 90% on AI costs by intelligently routing requests to the best provider for each task.

🔗 Links

• Repository: https://github.com/openclaw-community/openclaw-hub
• Latest Release: https://github.com/openclaw-community/openclaw-hub/releases
• Documentation: See [docs/](docs) folder
• Contributing: See [CONTRIBUTING.md](CONTRIBUTING.md)
• Security: See [SECURITY.md](SECURITY.md)

---

⚡ One-Line Install

curl -fsSL https://raw.githubusercontent.com/openclaw-community/openclaw-hub/main/scripts/install.sh | bash

Works on macOS (Apple Silicon & Intel) and Linux (Ubuntu 22.04/24.04+). Requires Python 3.12+ and git.

The installer handles everything: clones the repo, creates a venv, installs dependencies, sets up a managed service (launchd on macOS / systemd on Linux), and opens the dashboard in your browser. Running it again on an existing installation performs a clean update.

> Windows: Use WSL2. See [docs/INSTALLATION.md](docs/INSTALLATION.md).

---

Features

• ✅ Multi-Provider Support: OpenAI, Anthropic, Ollama (local), OpenRouter, LM Studio, custom
• ✅ Automatic Routing: Intelligent model-based provider selection
• ✅ Self-Healing: Auto-retry with exponential backoff, provider fallback routing, background health probes
• ✅ Push Notifications: Real-time alerts for consecutive errors, latency spikes, and budget thresholds — dashboard banners, webhooks, and macOS/Linux desktop notifications
• ✅ Cost Tracking: Real-time cost calculation, per-connection budgets with enforcement
• ✅ OpenAI-Compatible API: Drop-in replacement for OpenAI SDK
• ✅ Database Logging: SQLite storage for all requests and alerts
• ✅ YAML Workflow Orchestration: Human-readable multi-step pipelines
• ✅ MCP Tool Integration: External tool support (web search, files, APIs)
• ✅ Web Dashboard: Built-in monitoring UI — usage charts with historical navigation, connection management, cost tracking, alert banners
• ✅ Connection Management: Add, edit, and monitor 12+ service types (LLMs, media APIs, git platforms, gateways)
• ✅ Budget Enforcement: Per-connection daily/weekly/monthly limits; requests blocked at limit, override supported
• ✅ Encrypted Credentials: Fernet-encrypted API keys and tokens at rest

---

📖 Documentation

OpenClaw Hub is fully self-documenting!

For Humans

• Dashboard: http://127.0.0.1:8080/dashboard
• Interactive API Explorer: http://127.0.0.1:8080/docs (Swagger UI)
• API Reference: http://127.0.0.1:8080/redoc
• OpenAPI Spec: http://127.0.0.1:8080/openapi.json

For AI Agents

• Usage Instructions: GET /v1/usage — Returns how to use the Hub
• Capability Discovery:
• GET /v1/models — List available LLM models
• GET /v1/workflows — List available workflows
• GET /v1/github/capabilities — GitHub integration details
• GET /v1/social/capabilities — Instagram/social media details
• GET /v1/videos/capabilities — Video generation details

---

Quick Start

Already installed?

Check before running any install commands:

# macOS — is Hub already a launchd service?
launchctl list | grep com.openclaw.hub

# Linux — is Hub already a systemd service?
systemctl --user status openclaw-hub

# Either platform — is it simply running?
curl http://127.0.0.1:8080/health

If Hub is running as a service, manage it with launchctl (macOS) or systemctl (Linux) — not pkill. Killing the process directly causes the service manager to immediately respawn it.

Fresh install (recommended)

curl -fsSL https://raw.githubusercontent.com/openclaw-community/openclaw-hub/main/scripts/install.sh | bash

The installer:

1. Checks for Python 3.12+ and git (exits with clear instructions if missing)
2. Clones to ~/.openclaw-hub/ (overridable via OPENCLAW_HUB_HOME=...)
3. Creates a venv and installs dependencies
4. Bootstraps .env with a generated secret key
5. Detects local Ollama automatically
6. Installs and starts a managed service
7. Health-checks Hub, then opens the dashboard in your browser

Update

Running the installer again on an existing installation switches to update mode — pulls latest code, updates deps, restarts the service, and preserves your .env.

Manual / Development install

> ⚠️ Only use this if you have not run the unified installer. If you have, Hub is already managed by a service — use launchctl/systemctl to control it.

git clone https://github.com/openclaw-community/openclaw-hub.git
cd openclaw-hub

python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Edit .env with your API keys (optional — Ollama works without keys)

uvicorn aigateway.main:app --host 127.0.0.1 --port 8080 --reload

Uninstall

~/.openclaw-hub/scripts/uninstall.sh

Stops the service, backs up your .env and database to ~/.openclaw-hub.backup/, then removes the installation.

---

Service Management

Hub runs as a managed background service. Always use the service manager — never kill the process directly.

| | macOS (launchd) | Linux (systemd) | |---|---|---| | Stop | launchctl unload ~/Library/LaunchAgents/com.openclaw.hub.plist | systemctl --user stop openclaw-hub | | Start | launchctl load ~/Library/LaunchAgents/com.openclaw.hub.plist | systemctl --user start openclaw-hub | | Status | launchctl list \| grep com.openclaw.hub | systemctl --user status openclaw-hub | | Logs | tail -f ~/.openclaw-hub/hub.log | journalctl --user -u openclaw-hub -f |

---

API Examples

Health Check:

curl http://127.0.0.1:8080/health

Chat Completion (Ollama — free, local):

curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen2.5:32b-instruct", "messages": [{"role": "user", "content": "Say hello"}]}'

Chat Completion (GPT-4o-mini — requires OpenAI API key):

curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Explain quantum computing"}]}'

Chat Completion (Claude — requires Anthropic API key):

curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet", "messages": [{"role": "user", "content": "Write a haiku about AI"}]}'

List active alerts:

curl http://127.0.0.1:8080/api/alerts/active

Dismiss an alert:

curl -X POST http://127.0.0.1:8080/api/alerts//dismiss

---

Dashboard

Access at http://127.0.0.1:8080/dashboard

| Section | What's here | |---|---| | Overview | Real-time stats, token usage charts (daily/weekly/monthly with historical navigation), request distribution, connection health, active alert banners | | Connections | Manage 12+ service types; import from .env; per-connection budget limits with progress bars | | Activity | Every LLM and API call logged with model, provider, tokens, cost, latency, status | | Costs | Per-model cost config, budget enforcement, spend history |

Alert banners appear on every page and dismiss without a page reload. They auto-clear when the underlying condition resolves.

---

Self-Healing & Alerts

Hub automatically recovers from transient provider failures:

• Retry with backoff: failed requests retried up to 3× (1s → 5s → 15s, configurable)
• Fallback routing: if primary provider exhausts retries, request is routed to a fallback (e.g. openai → ollama)
• Health probes: degraded providers are probed every 30s; marked healthy after 3 consecutive successes
• Push notifications: background monitor checks every 60s for consecutive errors, latency spikes, and budget thresholds; alerts dispatched to dashboard, webhook, and desktop

Configure in .env:

# Retry
RETRY_ENABLED=true
RETRY_MAX_ATTEMPTS=3
FALLBACK_RULES=openai:ollama,anthropic:ollama

# Alerts
ALERT_ENABLED=true
ALERT_WEBHOOK_URL=https://your-endpoint.example.com/alerts
ALERT_DESKTOP_NOTIFY=true
ALERT_CONSECUTIVE_ERROR_THRESHOLD=3
ALERT_BUDGET_THRESHOLD_PERCENT=90

---

Architecture

openclaw-hub/
├── scripts/
│   ├── install.sh                # One-line installer (macOS + Linux)
│   ├── install-macos.sh          # macOS redirect stub → install.sh
│   ├── install-linux.sh          # Linux redirect stub → install.sh
│   └── uninstall.sh              # Uninstaller with data backup
├── examples/
│   ├── summarize.yaml            # Example: text summarisation workflow
│   ├── smart-analysis.yaml       # Example: adaptive complexity routing
│   └── web-research.yaml         # Example: web fetch + LLM analysis
├── aigateway/
│   ├── api/                      # FastAPI routers
│   │   ├── completions.py        # /v1/chat/completions (retry + fallback)
│   │   ├── alerts.py             # /api/alerts/* (Issue #29)
│   │   └── dashboard.py          # /api/dashboard/* (18 endpoints)
│   ├── monitoring/               # Push notification subsystem (Issue #29)
│   │   ├── alert_manager.py      # Deduplication, auto-resolve, dispatch
│   │   ├── health_monitor.py     # Background check loop
│   │   └── channels/             # webhook.py, desktop.py
│   ├── providers/                # LLM provider implementations
│   │   ├── manager.py            # Routing + fallback
│   │   ├── health.py             # Provider health tracker (Issue #26)
│   │   ├── ollama.py
│   │   ├── openai.py
│   │   └── anthropic.py
│   ├── dashboard/
│   │   ├── data.py               # Async data access layer
│   │   └── crypto.py             # Fernet encrypt/decrypt/mask
│   ├── storage/
│   │   ├── database.py           # SQLAlchemy async setup + migrations
│   │   └── models.py             # Request, Connection, Alert, CostConfig models
│   ├── orchestration/            # YAML workflow engine
│   ├── mcp/                      # MCP integration
│   ├── static/index.html         # Dashboard UI (single-file, no build tools)
│   ├── config.py                 # Settings (pydantic-settings, .env)
│   └── main.py                   # App entry point, startup/shutdown lifecycle
└── .env.example                  # Configuration reference

---

Provider Routing

Requests are routed automatically by model name:

| Model pattern | Provider | |---|---| | gpt-4*, gpt-3.5*, gpt-4o* | OpenAI | | claude* | Anthropic | | Anything else | Ollama (local) |

Fallback rules are configurable via FALLBACK_RULES in .env.

---

Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and the PR process.

License

Apache License 2.0 — see [LICENSE](LICENSE) for details.

Support

• Issues: GitHub Issues
• Documentation: See [docs/](docs) folder
• Security: Report vulnerabilities via [SECURITY.md](SECURITY.md)

Project Status

Version: 1.2.0 Status: Production-ready Maintainer: OpenClaw Community

See [CHANGELOG.md](CHANGELOG.md) for version history.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: openclaw-community
• Source: openclaw-community/openclaw-hub
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.