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.
Render sponsors AlphaClaw. Redeem $50 in Render credits with code RENDER-ALPHACLAW.
> **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:** Render/Railway 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 on Render (recommended)
[](https://render.com/templates/alphaclaw)
Render sponsors AlphaClaw. Use code **`RENDER-ALPHACLAW`** to redeem **$50 in Render credits**. The deployment is maintained in Render's [official AlphaClaw template repository](https://github.com/render-examples/openclaw-render-template).
### Other deployment options
[](https://railway.com/deploy/openclaw-fast-start?referralCode=jcFhp_&utm_medium=integration&utm_source=template&utm_campaign=generic)
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 tini && 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
ENTRYPOINT ["/usr/bin/tini", "--"]
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`) |
| `ALPHACLAW_SKIP_SYSTEM_CRON_INSTALL` | Optional | Skip writes to `/etc/cron.d` while keeping cron config (`true`/`false`); the managed hourly script still exits when sync is disabled |
| `ALPHACLAW_GIT_SHIM_PATH` | Optional | Install the managed git auth shim at this path and prepend its directory to runtime `PATH` (default `/usr/local/bin/git`) |
| `ALPHACLAW_GIT_ASKPASS_PATH` | Optional | Install the git askpass helper at this path (default `$TMPDIR/alphaclaw-git-askpass.sh`) |
| `TRUST_PROXY_HOPS` | Optional | Trust proxy hop count for correct client IP |
| `REMOTE_MCP_URL` | Optional | Upstream remote MCP server URL. When set together with `REMOTE_MCP_API_TOKEN`, AlphaClaw writes a managed `mcp.servers.` entry to `openclaw.json` on every gateway start. |
| `REMOTE_MCP_API_TOKEN` | Optional | Bearer token for the remote MCP server. Persisted in `openclaw.json` as the `${REMOTE_MCP_API_TOKEN}` reference, never as plaintext. |
| `REMOTE_MCP_NAME` | Optional | Key under `mcp.servers.`. Defaults to `remote`. Set it to label the entry (e.g. `sure`, `notion`). |
| `REMOTE_MCP_PROXY_URL` | Optional | When set, OpenClaw connects here instead of `REMOTE_MCP_URL`. Intended for a same-host scanning proxy (e.g. `pipelock mcp proxy --listen --upstream `). Implementation is proxy-agnostic. |
## OpenAI-compatible `/v1` proxy
AlphaClaw can expose an OpenAI-compatible API surface on the same public port as the Setup UI. It is disabled by default. Enable it from the Setup UI under General -> Features -> API; the setting is persisted in `alphaclaw.json` in the OpenClaw repo so workspace sync can commit the change.
| Path | Method | Notes |
| ------------------------------- | ------- | ------------------------------------------------------------------ |
| `/v1/chat/completions` | POST | Streams when `stream: true`. Use `model: "openclaw/default"` or `openclaw/`. |
| `/v1/responses` | POST | OpenClaw's `/v1/responses` surface (enabled together with chat completions). |
| `/v1/embeddings` | POST | Routes to OpenClaw's embeddings endpoint. |
| `/v1/models`, `/v1/models/` | GET | Lists OpenClaw agent targets. |
When enabled, the proxy forwards requests to the loopback OpenClaw gateway. AlphaClaw requires `Authorization: Bearer ` and rejects requests when the gateway token is missing or does not match before forwarding to OpenClaw. Failed bearer-token attempts are rate-limited before proxying. The setup-UI cookie is stripped before forwarding, hop-by-hop response headers are not passed through, and `/v1` JSON request bodies are accepted up to 50 MB. When disabled or missing from `alphaclaw.json`, `/v1` requests return 404.
**Security boundary (important).** OpenClaw treats `/v1/chat/completions` as a full operator-access surface. A caller with a valid `OPENCLAW_GATEWAY_TOKEN` can run any tool the configured agent profile allows. Treat this token like an owner credential:
- Use this surface only for trusted server-to-server callers (for example, a self-hosted app that needs OpenClaw as its external assistant).
- Do not hand the gateway token to end-user clients.
- If your front door is public (Render, Fly, fly-style PaaS), make sure `SETUP_PASSWORD` is strong and that the gateway token is held by exactly one trusted backend.
When `REMOTE_MCP_URL` + `REMOTE_MCP_API_TOKEN` are set, AlphaClaw also registers an `mcp.servers.` block (default key `remote`) in `openclaw.json` so the agent can call back into that remote MCP server. Set `REMOTE_MCP_PROXY_URL` to route those callbacks through a same-host scanning proxy (for example a Pipelock MCP reverse proxy running in the same container).
## 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.22.3 on Node 22, ≥ 24.15.0 on Node 24, or ≥ 25.9.0
## Official Website
[alphaclaw.md](https://alphaclaw.md) is the official AlphaClaw website.
## License
MIT