{"id":46564976,"url":"https://github.com/chrysb/alphaclaw","last_synced_at":"2026-04-23T07:01:55.504Z","repository":{"id":341474504,"uuid":"1166321809","full_name":"chrysb/alphaclaw","owner":"chrysb","description":"The ultimate setup harness for OpenClaw. Deploy in minutes. Stay running for months. No CLI required.","archived":false,"fork":false,"pushed_at":"2026-04-13T22:32:28.000Z","size":3286,"stargazers_count":1127,"open_issues_count":13,"forks_count":136,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-04-14T00:37:00.571Z","etag":null,"topics":["ai-agent","gateway","nodejs","openclaw","setup-ui","watchdog"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrysb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"chrysb"}},"created_at":"2026-02-25T05:15:58.000Z","updated_at":"2026-04-13T22:32:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chrysb/alphaclaw","commit_stats":null,"previous_names":["chrysb/alphaclaw"],"tags_count":123,"template":false,"template_full_name":null,"purl":"pkg:github/chrysb/alphaclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrysb%2Falphaclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrysb%2Falphaclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrysb%2Falphaclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrysb%2Falphaclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrysb","download_url":"https://codeload.github.com/chrysb/alphaclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrysb%2Falphaclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32169657,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","gateway","nodejs","openclaw","setup-ui","watchdog"],"created_at":"2026-03-07T07:00:20.439Z","updated_at":"2026-04-23T07:01:55.483Z","avatar_url":"https://github.com/chrysb.png","language":"JavaScript","funding_links":["https://github.com/sponsors/chrysb"],"categories":["Skills \u0026 Plugins"],"sub_categories":["Third-Party Platforms"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"771\" height=\"339\" alt=\"image\" src=\"https://github.com/user-attachments/assets/b96b45ab-52f2-4010-bfbe-c640e66b0f36\" /\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003eAlphaClaw\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe ultimate OpenClaw harness. Deploy in minutes. Stay running for months.\u003c/strong\u003e\u003cbr\u003e\n  \u003cstrong\u003eObservability. Reliability. Agent discipline. Zero SSH rescue missions.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/chrysb/alphaclaw/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/chrysb/alphaclaw/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@chrysb/alphaclaw\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@chrysb/alphaclaw\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eAlphaClaw wraps \u003ca href=\"https://github.com/openclaw/openclaw\"\u003eOpenClaw\u003c/a\u003e 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.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eFirst deploy to first message in under five minutes.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://railway.com/deploy/openclaw-fast-start?referralCode=jcFhp_\u0026utm_medium=integration\u0026utm_source=template\u0026utm_campaign=generic\"\u003e\u003cimg height=\"40\" src=\"https://railway.com/button.svg\" alt=\"Deploy on Railway\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://render.com/deploy?repo=https://github.com/chrysb/openclaw-render-template\"\u003e\u003cimg height=\"40\" src=\"https://render.com/images/deploy-to-render-button.svg\" alt=\"Deploy to Render\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://updates.alphaclaw.md/desktop/prod/alphaclaw-mac-latest.dmg\"\u003e\u003cimg height=\"40\" src=\"https://img.shields.io/badge/Download%20for%20macOS-000000?style=for-the-badge\u0026logo=apple\u0026logoColor=white\" alt=\"Download for macOS\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e **Platform:** AlphaClaw currently targets Docker/Linux deployments. macOS local development is not yet supported.\n\n## Features\n\n- **Setup UI:** Password-protected web dashboard for onboarding, configuration, and day-to-day management.\n- **Guided Onboarding:** Step-by-step setup wizard — model selection, provider credentials, GitHub repo, channel pairing.\n- **Multi-Agent Management:** Sidebar-driven agent navigation with create, rename, and delete flows. Per-agent overview cards, channel bindings, and URL-driven agent selection.\n- **Gateway Manager:** Spawns, monitors, restarts, and proxies the OpenClaw gateway as a managed child process.\n- **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.\n- **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.\n- **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.\n- **Cron Jobs:** Dedicated cron tab with job management, an interactive rolling calendar, run-history drilldowns, trend analytics, and per-run usage breakdowns.\n- **Nodes:** Guided local-node setup for VPS deployments with per-node browser attach checks, reconnect commands, and routing/pairing controls.\n- **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.\n- **File Explorer:** Browser-based workspace explorer with file visibility, inline edits, diff view, and Git-aware sync for quick fixes without SSH.\n- **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.\n- **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.\n- **Version Management:** In-place updates for both AlphaClaw and OpenClaw with in-app release notes, changelog review, and one-click apply.\n- **Codex OAuth:** Built-in PKCE flow for OpenAI Codex CLI model access.\n\n## Why AlphaClaw\n\n- **Zero to production in one deploy:** Railway/Render templates ship a complete stack — no manual gateway setup.\n- **Self-healing:** Watchdog detects crashes, enters repair mode, relaunches the gateway, and notifies you.\n- **Everything in the browser:** No SSH, no config files to hand-edit, no CLI required after first deploy.\n- **Stays out of the way:** AlphaClaw manages infrastructure; OpenClaw handles the AI.\n\n## No Lock-in. Eject Anytime.\n\nAlphaClaw simply wraps OpenClaw, it's not a dependency. Remove AlphaClaw and your agent keeps running. Nothing proprietary, nothing to migrate.\n\n## Quick Start\n\n### Deploy (recommended)\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/openclaw-fast-start?referralCode=jcFhp_\u0026utm_medium=integration\u0026utm_source=template\u0026utm_campaign=generic)\n[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/chrysb/openclaw-render-template)\n\nSet `SETUP_PASSWORD` at deploy time and visit your deployment URL. The welcome wizard handles the rest.\n\n\u003e **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.\n\n### Local / Docker\n\n```bash\nnpm install @chrysb/alphaclaw\nnpx alphaclaw start\n```\n\nOr with Docker:\n\n```dockerfile\nFROM node:22-slim\nRUN apt-get update \u0026\u0026 apt-get install -y git curl procps cron \u0026\u0026 rm -rf /var/lib/apt/lists/*\nWORKDIR /app\nCOPY package.json ./\nRUN npm install --omit=dev\nENV PATH=\"/app/node_modules/.bin:$PATH\"\nENV ALPHACLAW_ROOT_DIR=/data\nEXPOSE 3000\nCMD [\"alphaclaw\", \"start\"]\n```\n\n## Setup UI\n\n| Tab           | What it manages                                                                                                          |\n| ------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| **General**   | Gateway status, channel health, pending pairings, Google Workspace, repo sync schedule, OpenClaw dashboard               |\n| **Browse**    | File explorer for workspace visibility, inline edits, diff review, and Git-backed sync                                   |\n| **Usage**     | Token summaries, per-session and per-agent cost and token breakdown with source/agent dimension comparisons              |\n| **Cron**      | Cron job management, interactive rolling calendar, run-history drilldowns, trend analytics, and per-run usage breakdowns |\n| **Nodes**     | Guided local-node setup for VPS deployments, per-node browser attach, reconnect commands, and routing/pairing controls   |\n| **Watchdog**  | Health monitoring, crash-loop status, auto-repair toggle, notifications, event log, live log tail, interactive terminal  |\n| **Providers** | AI provider credentials (Anthropic, OpenAI, Gemini, Mistral, Voyage, Groq, Deepgram) and model selection                 |\n| **Envars**    | Environment variables — view, edit, add — with gateway restart prompts                                                   |\n| **Webhooks**  | Webhook endpoints, transform modules, request history, payload inspection, OAuth callbacks, Gmail watch delivery flows   |\n\n## CLI\n\n| Command                                                    | Description                                   |\n| ---------------------------------------------------------- | --------------------------------------------- |\n| `alphaclaw start`                                          | Start the server (Setup UI + gateway manager) |\n| `alphaclaw git-sync -m \"message\"`                          | Commit and push the OpenClaw workspace        |\n| `alphaclaw telegram topic add --thread \u003cid\u003e --name \u003ctext\u003e` | Register a Telegram topic mapping             |\n| `alphaclaw version`                                        | Print version                                 |\n| `alphaclaw help`                                           | Show help                                     |\n\n## Architecture\n\n```mermaid\ngraph TD\n    subgraph AlphaClaw\n        UI[\"Setup UI\u003cbr/\u003e\u003csmall\u003ePreact + htm + Wouter\u003c/small\u003e\"]\n        WD[\"Watchdog\u003cbr/\u003e\u003csmall\u003eCrash recovery · Notifications\u003c/small\u003e\"]\n        WH[\"Webhooks\u003cbr/\u003e\u003csmall\u003eTransforms · Request logging\u003c/small\u003e\"]\n        UI --\u003e API\n        WD --\u003e API\n        WH --\u003e API\n        API[\"Express Server\u003cbr/\u003e\u003csmall\u003eJSON APIs · Auth · Proxy\u003c/small\u003e\"]\n    end\n\n    API -- \"proxy\" --\u003e GW[\"OpenClaw Gateway\u003cbr/\u003e\u003csmall\u003eChild process · 127.0.0.1:18789\u003c/small\u003e\"]\n    GW --\u003e DATA[\"ALPHACLAW_ROOT_DIR\u003cbr/\u003e\u003csmall\u003e.openclaw/ · .env · logs · SQLite\u003c/small\u003e\"]\n```\n\n## Watchdog\n\nThe built-in watchdog monitors gateway health and recovers from failures automatically.\n\n| Capability               | Details                                                                |\n| ------------------------ | ---------------------------------------------------------------------- |\n| **Health checks**        | Periodic `openclaw health` with configurable interval                  |\n| **Crash detection**      | Listens for gateway exit events                                        |\n| **Crash-loop detection** | Threshold-based (default: 3 crashes in 300s)                           |\n| **Auto-repair**          | Runs `openclaw doctor --fix --yes`, relaunches gateway                 |\n| **Notifications**        | Telegram, Discord, and Slack alerts for crashes, repairs, and recovery |\n| **Event log**            | SQLite-backed incident history with API and UI access                  |\n\n## Environment Variables\n\n| Variable                          | Required | Description                                        |\n| --------------------------------- | -------- | -------------------------------------------------- |\n| `SETUP_PASSWORD`                  | Yes      | Password for the Setup UI                          |\n| `OPENCLAW_GATEWAY_TOKEN`          | Auto     | Gateway auth token (auto-generated if unset)       |\n| `GITHUB_TOKEN`                    | Yes      | GitHub PAT for workspace repo                      |\n| `GITHUB_WORKSPACE_REPO`           | Yes      | GitHub repo for workspace sync (e.g. `owner/repo`) |\n| `TELEGRAM_BOT_TOKEN`              | Optional | Telegram bot token                                 |\n| `DISCORD_BOT_TOKEN`               | Optional | Discord bot token                                  |\n| `SLACK_BOT_TOKEN`                 | Optional | Slack bot token (Socket Mode)                      |\n| `WATCHDOG_AUTO_REPAIR`            | Optional | Enable auto-repair on crash (`true`/`false`)       |\n| `WATCHDOG_NOTIFICATIONS_DISABLED` | Optional | Disable watchdog notifications (`true`/`false`)    |\n| `PORT`                            | Optional | Server port (default `3000`)                       |\n| `ALPHACLAW_ROOT_DIR`              | Optional | Data directory (default `/data`)                   |\n| `TRUST_PROXY_HOPS`                | Optional | Trust proxy hop count for correct client IP        |\n\n## Security Notes\n\nAlphaClaw is a convenience wrapper — it intentionally trades some of OpenClaw's default hardening for ease of setup. You should understand what's different:\n\n| Area                    | What AlphaClaw does                                                                                                                   | Trade-off                                                                                              |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |\n| **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.                            |\n| **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.                  |\n| **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.                                        |\n| **Query-string tokens** | Webhook URLs support `?token=\u003cWEBHOOK_TOKEN\u003e` 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. |\n| **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.  |\n\nIf you need OpenClaw's full security posture (manual pairing codes, no query-string tokens, no auto-approval), use OpenClaw directly without AlphaClaw.\n\n## Development\n\n```bash\nnpm install\nnpm run build:ui        # Generate Setup UI bundle, Tailwind CSS, and vendor CSS (required for local runs from a git checkout)\nnpm test                # Full suite (440 tests)\nnpm run test:watchdog   # Watchdog-focused suite (14 tests)\nnpm run test:watch      # Watch mode\nnpm run test:coverage   # Coverage report\n```\n\n**Requirements:** Node.js ≥ 22.14.0\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrysb%2Falphaclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrysb%2Falphaclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrysb%2Falphaclaw/lists"}