https://github.com/chrysb/alphaclaw
The ultimate setup harness for OpenClaw. Deploy in minutes. Stay running for months. No CLI required.
https://github.com/chrysb/alphaclaw
ai-agent gateway nodejs openclaw setup-ui watchdog
Last synced: about 2 months ago
JSON representation
The ultimate setup harness for OpenClaw. Deploy in minutes. Stay running for months. No CLI required.
- Host: GitHub
- URL: https://github.com/chrysb/alphaclaw
- Owner: chrysb
- License: mit
- Created: 2026-02-25T05:15:58.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-13T22:32:28.000Z (2 months ago)
- Last Synced: 2026-04-14T00:37:00.571Z (2 months ago)
- Topics: ai-agent, gateway, nodejs, openclaw, setup-ui, watchdog
- Language: JavaScript
- Size: 3.13 MB
- Stars: 1,127
- Watchers: 10
- Forks: 136
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
AlphaClaw
The ultimate OpenClaw harness. Deploy in minutes. Stay running for months.
Observability. Reliability. Agent discipline. Zero SSH rescue missions.
AlphaClaw wraps OpenClaw with a convenient setup wizard, self-healing watchdog, Git-backed rollback, and full browser-based observability. Ships with anti-drift prompt hardening to keep your agent disciplined, and simplifies integrations (e.g. Google Workspace, Google Pub/Sub, Telegram Topics, Slack, Discord) so you can manage multiple agents from one UI instead of config files.
First deploy to first message in under five minutes.
> **Platform:** AlphaClaw currently targets Docker/Linux deployments. macOS local development is not yet supported.
## Features
- **Setup UI:** Password-protected web dashboard for onboarding, configuration, and day-to-day management.
- **Guided Onboarding:** Step-by-step setup wizard — model selection, provider credentials, GitHub repo, channel pairing.
- **Multi-Agent Management:** Sidebar-driven agent navigation with create, rename, and delete flows. Per-agent overview cards, channel bindings, and URL-driven agent selection.
- **Gateway Manager:** Spawns, monitors, restarts, and proxies the OpenClaw gateway as a managed child process.
- **Watchdog:** Crash detection, crash-loop recovery, auto-repair (`openclaw doctor --fix`), Telegram/Discord/Slack notifications, and a live interactive terminal for monitoring gateway output directly from the browser.
- **Channel Orchestration:** Telegram, Discord, and Slack bot pairing with per-agent channel bindings, credential sync, and a guided wizard for splitting Telegram into multi-threaded topic groups as your usage grows.
- **Google Workspace:** OAuth integration for Gmail, Calendar, Drive, Docs, Sheets, Tasks, Contacts, and Meet, plus guided Gmail watch setup with Google Pub/Sub topic, subscription, and push endpoint handling.
- **Cron Jobs:** Dedicated cron tab with job management, an interactive rolling calendar, run-history drilldowns, trend analytics, and per-run usage breakdowns.
- **Nodes:** Guided local-node setup for VPS deployments with per-node browser attach checks, reconnect commands, and routing/pairing controls.
- **Webhooks:** Named webhook endpoints with per-hook transform modules, request logging, payload inspection, editable delivery destinations, and OAuth callback support for third-party auth flows.
- **File Explorer:** Browser-based workspace explorer with file visibility, inline edits, diff view, and Git-aware sync for quick fixes without SSH.
- **Prompt Hardening:** Ships anti-drift bootstrap prompts (`AGENTS.md`, `TOOLS.md`) injected into your agent's system prompt on every message — enforcing safe practices, commit discipline, and change summaries out of the box.
- **Git Sync:** Automatic hourly commits of your OpenClaw workspace to GitHub with configurable cron schedule. Combined with prompt hardening, every agent action is version-controlled and auditable.
- **Version Management:** In-place updates for both AlphaClaw and OpenClaw with in-app release notes, changelog review, and one-click apply.
- **Codex OAuth:** Built-in PKCE flow for OpenAI Codex CLI model access.
## Why AlphaClaw
- **Zero to production in one deploy:** Railway/Render templates ship a complete stack — no manual gateway setup.
- **Self-healing:** Watchdog detects crashes, enters repair mode, relaunches the gateway, and notifies you.
- **Everything in the browser:** No SSH, no config files to hand-edit, no CLI required after first deploy.
- **Stays out of the way:** AlphaClaw manages infrastructure; OpenClaw handles the AI.
## No Lock-in. Eject Anytime.
AlphaClaw simply wraps OpenClaw, it's not a dependency. Remove AlphaClaw and your agent keeps running. Nothing proprietary, nothing to migrate.
## Quick Start
### Deploy (recommended)
[](https://railway.com/deploy/openclaw-fast-start?referralCode=jcFhp_&utm_medium=integration&utm_source=template&utm_campaign=generic)
[](https://render.com/deploy?repo=https://github.com/chrysb/openclaw-render-template)
Set `SETUP_PASSWORD` at deploy time and visit your deployment URL. The welcome wizard handles the rest.
> **Railway users:** after deploying, upgrade to the **Hobby plan** and redeploy to ensure your service has at least **8 GB of RAM**. The Trial plan's memory limit can cause out-of-memory crashes during normal operation.
### Local / Docker
```bash
npm install @chrysb/alphaclaw
npx alphaclaw start
```
Or with Docker:
```dockerfile
FROM node:22-slim
RUN apt-get update && apt-get install -y git curl procps cron && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
ENV PATH="/app/node_modules/.bin:$PATH"
ENV ALPHACLAW_ROOT_DIR=/data
EXPOSE 3000
CMD ["alphaclaw", "start"]
```
## Setup UI
| Tab | What it manages |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **General** | Gateway status, channel health, pending pairings, Google Workspace, repo sync schedule, OpenClaw dashboard |
| **Browse** | File explorer for workspace visibility, inline edits, diff review, and Git-backed sync |
| **Usage** | Token summaries, per-session and per-agent cost and token breakdown with source/agent dimension comparisons |
| **Cron** | Cron job management, interactive rolling calendar, run-history drilldowns, trend analytics, and per-run usage breakdowns |
| **Nodes** | Guided local-node setup for VPS deployments, per-node browser attach, reconnect commands, and routing/pairing controls |
| **Watchdog** | Health monitoring, crash-loop status, auto-repair toggle, notifications, event log, live log tail, interactive terminal |
| **Providers** | AI provider credentials (Anthropic, OpenAI, Gemini, Mistral, Voyage, Groq, Deepgram) and model selection |
| **Envars** | Environment variables — view, edit, add — with gateway restart prompts |
| **Webhooks** | Webhook endpoints, transform modules, request history, payload inspection, OAuth callbacks, Gmail watch delivery flows |
## CLI
| Command | Description |
| ---------------------------------------------------------- | --------------------------------------------- |
| `alphaclaw start` | Start the server (Setup UI + gateway manager) |
| `alphaclaw git-sync -m "message"` | Commit and push the OpenClaw workspace |
| `alphaclaw telegram topic add --thread --name ` | Register a Telegram topic mapping |
| `alphaclaw version` | Print version |
| `alphaclaw help` | Show help |
## Architecture
```mermaid
graph TD
subgraph AlphaClaw
UI["Setup UI
Preact + htm + Wouter"]
WD["Watchdog
Crash recovery · Notifications"]
WH["Webhooks
Transforms · Request logging"]
UI --> API
WD --> API
WH --> API
API["Express Server
JSON APIs · Auth · Proxy"]
end
API -- "proxy" --> GW["OpenClaw Gateway
Child process · 127.0.0.1:18789"]
GW --> DATA["ALPHACLAW_ROOT_DIR
.openclaw/ · .env · logs · SQLite"]
```
## Watchdog
The built-in watchdog monitors gateway health and recovers from failures automatically.
| Capability | Details |
| ------------------------ | ---------------------------------------------------------------------- |
| **Health checks** | Periodic `openclaw health` with configurable interval |
| **Crash detection** | Listens for gateway exit events |
| **Crash-loop detection** | Threshold-based (default: 3 crashes in 300s) |
| **Auto-repair** | Runs `openclaw doctor --fix --yes`, relaunches gateway |
| **Notifications** | Telegram, Discord, and Slack alerts for crashes, repairs, and recovery |
| **Event log** | SQLite-backed incident history with API and UI access |
## Environment Variables
| Variable | Required | Description |
| --------------------------------- | -------- | -------------------------------------------------- |
| `SETUP_PASSWORD` | Yes | Password for the Setup UI |
| `OPENCLAW_GATEWAY_TOKEN` | Auto | Gateway auth token (auto-generated if unset) |
| `GITHUB_TOKEN` | Yes | GitHub PAT for workspace repo |
| `GITHUB_WORKSPACE_REPO` | Yes | GitHub repo for workspace sync (e.g. `owner/repo`) |
| `TELEGRAM_BOT_TOKEN` | Optional | Telegram bot token |
| `DISCORD_BOT_TOKEN` | Optional | Discord bot token |
| `SLACK_BOT_TOKEN` | Optional | Slack bot token (Socket Mode) |
| `WATCHDOG_AUTO_REPAIR` | Optional | Enable auto-repair on crash (`true`/`false`) |
| `WATCHDOG_NOTIFICATIONS_DISABLED` | Optional | Disable watchdog notifications (`true`/`false`) |
| `PORT` | Optional | Server port (default `3000`) |
| `ALPHACLAW_ROOT_DIR` | Optional | Data directory (default `/data`) |
| `TRUST_PROXY_HOPS` | Optional | Trust proxy hop count for correct client IP |
## Security Notes
AlphaClaw is a convenience wrapper — it intentionally trades some of OpenClaw's default hardening for ease of setup. You should understand what's different:
| Area | What AlphaClaw does | Trade-off |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Setup password** | All gateway access is gated behind a single `SETUP_PASSWORD`. Brute-force protection is built in (exponential backoff lockout). | Simpler than OpenClaw's pairing code flow, but the password must be strong. |
| **One-click pairing** | Channel pairings (Telegram/Discord/Slack) can be approved from the Setup UI instead of the CLI. | No terminal access required, but anyone with the setup password can approve pairings. |
| **Auto CLI approval** | The first CLI device pairing is auto-approved so you can connect without a second screen. Subsequent requests appear in the UI. | Removes the manual pairing step for the initial CLI connection. |
| **Query-string tokens** | Webhook URLs support `?token=` for providers that don't support `Authorization` headers. Warnings are shown in the UI. | Tokens may appear in server logs and referrer headers. Use header auth when your provider supports it. |
| **Gateway token** | `OPENCLAW_GATEWAY_TOKEN` is auto-generated and injected into the environment so the proxy can authenticate with the gateway. | The token lives in the `.env` file on the server — standard for managed deployments but worth noting. |
If you need OpenClaw's full security posture (manual pairing codes, no query-string tokens, no auto-approval), use OpenClaw directly without AlphaClaw.
## Development
```bash
npm install
npm run build:ui # Generate Setup UI bundle, Tailwind CSS, and vendor CSS (required for local runs from a git checkout)
npm test # Full suite (440 tests)
npm run test:watchdog # Watchdog-focused suite (14 tests)
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
```
**Requirements:** Node.js ≥ 22.14.0
## License
MIT