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.

• 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.
• Agent Chat: Chat with any agent session right from the sidebar. Sends queue durably and survive page reloads. Safe retries reconcile the original message ID against durable submission evidence; uncertain sends stay visible for review, and an explicit “Send again” creates a new ID. Stop reports honestly, interruptions show up inline in the transcript, and the connection reconnects on its own with keepalives on both the browser and gateway sockets.
• Team Access (beta): Share one AlphaClaw with named teammates. Each person signs in with their own email and password, OpenClaw attributes messages per person, and a who's-online roster shows presence. Admins invite members with expiring single-use links, assign roles, and disable or remove accounts; members can chat and view status while updates, secrets, terminals, agents, and team management stay admin-only. Requires the OpenClaw 2026.8.1-beta line.
• Gateway Manager: Spawns, monitors, restarts, and proxies the OpenClaw gateway as a managed child process. Restart is one click from the gateway card in every state once setup is done (only while AlphaClaw itself is still booting is it withheld), and restarts stream live progress with honest outcomes — measured downtime on success, actual error evidence on failure, and a plain-language reason when a safety gate refuses to relaunch.
• Watchdog: Crash detection, crash-loop recovery, auto-repair (openclaw doctor --fix), memory-leak detection that can warn hours before the gateway hits its limit (with strictly opt-in pre-OOM auto-restart), Telegram/Discord/Slack/WhatsApp notifications, and a live interactive terminal for monitoring gateway output directly from the browser.
• Resource Autotune: Sizes resource-dependent settings to the container's real capacity (default ON) — gateway heap, agent concurrency, request body limits, SQLite caches, and an advisory backup budget — with a persisted detected → derived → applied ledger, live resize detection, and OOM classification. Opt out per deployment from the Watchdog tab or with the ALPHACLAW_AUTOTUNE_DISABLED=1 kill-switch.
• Channel Orchestration: Telegram, Discord, Slack, ClickClack, and Buzz 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. ClickClack sets up from a single pasted setup code or URL; Buzz installs through a resumable plugin wizard (both need the OpenClaw beta line for their guided flows).
• 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. Start, Stop, renewal and disconnect share one account operation: the latest intent wins, Stop records disabled intent immediately, and unfinished remote cancellation remains visible with Retry after reload. Failed disconnect keeps the account disabled so cleanup can be retried.
• 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 rules as a single merged hooks/bootstrap/AGENTS.md injected into your agent's system prompt on every message — enforcing safe practices, commit discipline, and change summaries out of the box on every supported OpenClaw version (existing installs migrate automatically, and the General tab shows whether the rules are actually reaching the agent — a compact status badge, escalating to an actionable card naming the affected file, the true cause, and the fix when hardening is dropped, truncated, or blocked, with a one-click jump into the Doctor's context meter).
• 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.
• Agent Administration: Optional (off by default) mode that lets the OpenClaw agent drive the same dashboard API the web UI uses through an alphaclaw admin CLI, with tiered guardrails, confirm codes for dangerous operations, a rotatable bearer token, and full Watchdog audit logging.
• Codex OAuth: Built-in PKCE flow for OpenAI Codex CLI model access.

• 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.

AlphaClaw simply wraps OpenClaw, it's not a dependency. Remove AlphaClaw and your agent keeps running. Nothing proprietary, nothing to migrate.

Render sponsors AlphaClaw. Use code RENDER-ALPHACLAW to redeem $50 in Render credits. The deployment is maintained in Render's official AlphaClaw template repository.

Render sizing: one AlphaClaw container runs the admin server, the OpenClaw gateway (a second Node.js runtime), up to five gog Google Workspace daemons, an hourly git-sync cron, and periodic npm/pnpm installs during updates. We recommend at least 2 GB RAM / 1 CPU (Render standard or larger). The starter tier (512 MB / 0.5 CPU) can OOM under normal operation and makes every update slower.

Per-process heap budgets: if you cap the Node heap, set it on the admin process only (e.g. node --max-old-space-size=768 bin/alphaclaw.js start in your start command) rather than via a blanket NODE_OPTIONS env var — children would inherit it. AlphaClaw strips memory flags from the gateway's environment so the two processes keep separate budgets (and logs what it stripped). With resource autotune (default ON) the gateway's heap is sized automatically from the container's real memory limit, and GET /api/autotune reports a recommended admin-process cap for your box (omitted on very small containers, where the honest recommendation is a bigger box). To pin the gateway's heap by hand instead, set ALPHACLAW_GATEWAY_MAX_OLD_SPACE_SIZE=<MB> (e.g. 8192) — it applies to the long-running gateway daemon only, never to short-lived openclaw CLI calls, and wins over autotune's derived value (the autotune ledger marks that row operator-set). With autotune off and no cap, Node sizes the gateway heap from host RAM (~40% — nearly 50 GB on a 123 GB box).

Resource autotune runbook: the Watchdog tab's Autotune card (and GET /api/autotune) shows what was detected on this container, what was derived, and what's applied — each row says whether a gateway restart or an AlphaClaw restart (redeploy from your host dashboard) finishes applying it. Pin a single setting with an override (alphaclaw admin PUT /api/autotune/settings --data '{"overrides":{"gatewayHeapMb":2048}}'; null clears a key), re-probe after a platform resize with POST /api/autotune/reapply, turn it off with the card toggle, or — even mid-crash-loop — set ALPHACLAW_AUTOTUNE_DISABLED=1 in your platform's environment settings. Disabling restores the built-in (pre-autotune) defaults — a gateway restart (and, for body limits and database caches, an AlphaClaw restart) finishes the revert.

Health checks: point your platform health check at /health (always 200 while the admin server can serve — a wedged gateway is healed by the watchdog, not container restarts). Operators who want strict gateway readiness gating can point it at /health/ready instead (503 while the gateway is down; be aware this restarts the container during gateway recovery, and a fresh, not-yet-onboarded instance also reports 503 — only switch to /health/ready after onboarding completes or the container will restart-loop before you can finish setup). Ops signal: if eventLoop.p99Ms in /api/watchdog/resources stays above 500ms, check recent gateway restarts and workspace size.

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.

npm install @chrysb/alphaclaw
npx alphaclaw start

Or with Docker:

FROM node:24-slim
RUN apt-get update && apt-get install -y --no-install-recommends git curl procps cron tini tmux ca-certificates && rm -rf /var/lib/apt/lists/*
# Optional but recommended: the local Claude Code rescue session needs tmux
# (above) and the claude CLI. Keep this pin in step with the reference
# Dockerfile; without this layer the launcher reports not_installed and
# falls back to the cloud routine.
RUN npm install -g @anthropic-ai/claude-code@2.1.251
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
# Fail the build, not the first boot, if the floating base tag resolved to a
# Node below AlphaClaw's floor (>=24.16 since v0.9.80, the OpenClaw 2026.9.3 pin).
RUN node -e "require('@chrysb/alphaclaw/lib/node-runtime').assertSupportedNodeVersion()"
ENV PATH="/app/node_modules/.bin:$PATH"
ENV ALPHACLAW_ROOT_DIR=/data
EXPOSE 3000
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["alphaclaw", "start"]

The reference Dockerfile is this recipe with two additions: it installs AlphaClaw from an npm pack tarball of the checkout (so npm run test:container can build and boot the local tree) instead of from a package.json pin, and it bakes in the toolchain for the local rescue session — tmux plus a pinned @anthropic-ai/claude-code. Everything else — tini as PID 1, ALPHACLAW_ROOT_DIR=/data, port 3000, alphaclaw start — is identical, and the container E2E runs against an image built from it (docker required).

The Monitoring section of the sidebar has an Open Claude Code item. Out of the box it opens claude.ai/code in a new tab. Configure it and one click starts a Claude Code session and lands you directly in it — a local rescue session on the box itself once you've done its one-time login (see below), or a fresh cloud session via a claude.ai routine.

Routine setup (one time, on your claude.ai account — requires a Pro/Max/Team/Enterprise plan):

1. Create a routine at claude.ai/code/routines. Keep its prompt minimal — something like "Await instructions." — because every fire runs the routine's saved prompt as an autonomous session (shell access, no approval prompts) that consumes your claude.ai subscription usage.
2. Edit the routine → Add another trigger → API → Generate token, then copy the fire URL and the token (shown once).
3. Paste them into Envars as CLAUDE_CODE_ROUTINE_URL (the full URL or just the trig_… id) and CLAUDE_CODE_ROUTINE_TOKEN. Changes apply immediately — no restart.

Behavior and guardrails:

• The first fire asks for a one-time confirmation; after that it's one click. Cmd/ctrl-click always opens plain claude.ai/code without firing (the escape hatch).
• A small accent dot on the sidebar item shows when the launcher is armed to fire rather than just link out.
• The server enforces the confirmation, a single-flight guard, and a short cooldown (longer after a timeout: the fire API has no idempotency key, so a timed-out fire may still have created a billed session — check claude.ai/code before retrying).
• The launcher never sends the token to the browser (status checks are presence-only), the token is excluded from the OpenClaw gateway's child environment, and the fire endpoint is denied to the agent-admin actor. Like every secret in ~/.alphaclaw/.env, admins can view it in the Envars editor, and a same-host process that can read that file can read it too — environment inheritance itself was closed in v0.9.63 (lib/server/gateway-env-policy.js allowlists what reaches the gateway child and denies every CLAUDE_CODE_ROUTINE_* / CLAUDE_CODE_LOCAL_* key by prefix; see CHANGELOG), so the remaining exposure is same-uid disk access to that file, not the child environment.
• Routines belong to one claude.ai account: in multi-admin installs, every admin's click fires (and bills) the token owner's account, and the session URL only opens for someone logged into that account.
• CLAUDE_CODE_ROUTINE_TOKEN is not the same as ANTHROPIC_TOKEN (the claude setup-token), despite the shared sk-ant-oat01- prefix — it is a per-routine trigger credential from the claude.ai UI.

The launcher's local path opens a Claude Code instance running on the box itself: a claude remote-control session hosted in detached tmux, reached through its Remote Control URL. Once its login is done, the button prefers this path (the routine stays as the fallback), so you can debug AlphaClaw/OpenClaw from claude.ai/code — or your phone — with hands on the actual machine, even while OpenClaw is down.

• One-time login. The Watchdog page's rescue-session card walks you through claude auth login in the browser (claude.ai subscription OAuth — Remote Control refuses API keys). Credentials live in <root>/claude-code-local/home/, deliberately outside backups: after restoring a backup, run the login again.
• Revocable link. The card, QR code, launcher, and notifications hand out an AlphaClaw-owned capability link — <your-alphaclaw>/rescue/<token> — that redirects to the live session. Links AlphaClaw distributed stop working on Stop; each new session start mints a new one (Start on an already-running session returns the existing link — stop first to rotate). An AlphaClaw restart with a still-live session keeps the same link. Honest boundaries: the guarantee does not cover fallback notifications sent with no public base URL configured (those carry the raw claude.ai URL — set ALPHACLAW_SETUP_URL), the underlying claude.ai URL disclosed to someone who already followed the redirect remains valid on Anthropic's side (claude.ai-account-gated), and a reverse proxy in front of AlphaClaw may access-log capability paths (inherent to capability URLs — revocation is the mitigation). The link needs the AlphaClaw server up; the card's tmux … attach hint is the out-of-band fallback. Upgrading from a release before v0.9.66: links distributed before the upgrade are raw claude.ai URLs — stop + start the rescue session once to cut over to revocable links.
• Survives AlphaClaw restarts. The tmux session outlives the AlphaClaw process; the card shows the rescue link (with a QR code for your phone), a copyable tmux … attach hint for shell access, one-click Stop, and a sanitized terminal tail when a spawn fails. Optionally warm a session at boot, or automatically when the watchdog opens an incident — the incident notification carries the link when the session is already running. Each use of the link is recorded as a watchdog operation event (IP + user agent); after an unexpected pane death the link dies on the next liveness poll, and a click also triggers a check — that click may still receive the stale redirect to the already-dead session, subsequent clicks 404 (explicit Stop revokes immediately; tmux hosting only — script-hosted sessions detect death instantly on process exit). Both GET and HEAD redirect (HEAD skips the liveness check); a malformed link gets a plain 400. Behind a reverse proxy, set ALPHACLAW_SETUP_URL so links and QR codes are built from the validated public origin instead of request headers (origins/subdomains only — path-prefixed proxy deployments like https://host/alphaclaw are not supported for rescue links).
• Permissions. Sessions default to acceptEdits; bypassPermissions is opt-in and only ever applies to sessions you start by clicking through the mode-named confirmation — unattended spawns (autostart, incidents) always clamp to acceptEdits. Note the session can read box content, including untrusted logs (a prompt-injection surface), and transmits selected content to Anthropic as part of operating Claude Code.
• Settings. Five CLAUDE_CODE_LOCAL_* keys on the Envars page — enable/kill switch, autostart, permission mode, working directory, incident auto-spawn — all hot-reloaded, no restart. Disabling never kills a live session; stop it from the Watchdog card.

<root> below is ALPHACLAW_ROOT_DIR (/data in the container, ~/.alphaclaw otherwise).

Post-rollback cleanup: after rolling the feature back (env kill switch or code revert), a live tmux session deliberately survives — clean it up with tmux -S <root>/claude-code-local/tmux.sock kill-server. The credentials dir is harmless to leave; the card's Logout removes it beforehand if wanted.

The Upgrade page pins your OpenClaw to a release channel and lets you switch, upgrade, or downgrade between specific builds — entirely from the browser.

How it works:

• Explicit updates only. Nothing installs on its own. Pick a version (last 5 stable, last 5 beta, or recent main commits), review its release notes, click once. Every restart deterministically re-loads the version you chose — offline, from a persisted copy on your data volume.

• npm ls reporting the openclaw dependency as "invalid" is expected while a channel pick is active. package.json keeps the exact stable pin (it is the safety fallback every recovery path boots from), while the applied build is overlaid onto node_modules/openclaw at startup — so npm's checker sees a version that doesn't match the declared spec. The boot log prints running <version> (<channel> channel) over declared pin <pin> — expected…, and the channel status APIs expose pinDiverged/appliedVersion so tooling can tell this expected state from real drift (foreign tampering is separately detected and reverted).

• Backed up before every switch. Every apply pauses the gateway for a consistent backup — since v0.9.77 (issue #79) the pause is no longer scoped to downgrades and cross-channel switches — and, with the gateway stopped and confirmed, AlphaClaw's own offline copy runs FIRST: SQLite's online backup of every state database, workspace debris (node_modules, *.heapsnapshot, *.tmp, logs/**/*.gz) excluded, written as a per-run timestamped openclaw-backup-<ts>-<opId8>.alphaclaw.tar.gz under <root>/backups/openclaw/ (the last 3 archives plus protected migration archives are retained). The upstream openclaw backup create --verify only backfills a failed copy — still paused when AlphaClaw's pre-pause diagnosis predicts it fits, retrying when OpenClaw's own migration lease contends for the database, otherwise against the relaunched gateway; a copy refused because another process held a state database hands over to that live rung instead of failing the run. While the gateway is paused AlphaClaw also holds its own state-database readers and writers quiet (writes answer 409 backup_in_progress while the backup pause is active). An archive from either producer counts as verified only after its manifest is read and shown to cover this box's databases. Downgrades, dev builds, prerelease targets and cross-channel switches require a verified backup; a same-channel stable upgrade also stops without one when the target migrates the database. Eligible availability failures can offer a separate human confirmation for an already prepared, verified target, including channel changes. The confirmation is single-use, expires after ten minutes and binds the signed-in session, failed run, source/target builds and database facts. A bare confirmNoBackup: true cannot bypass the gate; ownership conflicts, disk limits, corrupt state, incompatible targets and holds remain blockers. A new or moving dev build still requires a backup before preparation. See Backup: continue without a backup (consent). If the fresh backup still fails on a hard gate, the Upgrade page can offer a verified backup from the last 24 hours — proceeding on it is an explicit, human-only consent bound to that archive's digest, and the run record says state written since it is not included. The Upgrade tab's Backups card lists every archive (producer, age, size, provenance), links to the restore runbook in docs/upgrade-troubleshooting.md, and since v0.9.81 offers Back up now — the same ladder as a standalone run (gateway paused for the copy, then relaunched; nothing installed), recorded in the update history and summarized as "Last manual backup" — so a backup can be proven to work before the next update; a failed update's card offers "Retry backup" and then "Retry update".

• Database compatibility check. Before an update applies, the target version's own binary verifies it can read snapshots of your state databases; incompatible updates are blocked before anything changes, and rollbacks that can't be verified say so honestly.

• Recovery when scratch trees overwhelm backups. Preflight measures the full state tree before stopping the gateway, reports top offenders and absolute symlinks, and blocks oversized selected copies without downtime. After broader paused attempts fail, updates and Back up now try a migration-only backup of protected databases, configuration, credentials, identity and agent authentication within the same pause. The UI states the omitted workspace and other content; this archive protects its originating migration and is not eligible for later complete-backup reuse. The migration record and archive remain pinned for seven days. The Backups card also edits workspace and state-root exclusions, while failed scans name their largest observed directories. See backup policy and recovery and selective restore.

• Settings migration at boot. After a version change, OpenClaw's own doctor migrates your settings once (keeping a per-version pre-migration backup); downgrades restore the exact settings saved for that version, and the Upgrade page shows the last migration result. The migration is fail-closed: it runs BEFORE the new build's gateway can start, and on failure AlphaClaw reverts to a preflight-proven older build when that is safe — otherwise it holds the gateway with one-click "Retry migration" / "Strip blamed keys and retry" actions (see docs/upgrade-troubleshooting.md).

• What's new, per channel. A curated card highlights each OpenClaw line's changes, with security-default flips called out separately — and those same security changes reappear in the apply confirmation before you commit to a cross-channel switch.

• Repair. A dev build that fails mid-update gets a one-click, streamed openclaw update repair, recorded under its own durable operation ID. Reloading resumes that exact operation; success completes in place without an AlphaClaw restart. Cancelled repair writers and configuration restoration finish before another gateway operation can take ownership.

• Auto-rollback. A freshly switched version gets a 24-hour stabilization window. If it crash-loops, exits with a config error, or stays degraded, AlphaClaw blocklists it, restarts, and boots the last known-good build — then tells you on Telegram/Discord/Slack what happened and why. "Mark as good now" ends the window early once you're satisfied.

• Dev builds are honest about cost. The first dev build compiles OpenClaw from source (20-35 minutes measured, 45-minute ceiling, ~5 GB on the data volume, 8 GB RAM recommended) with live build output streamed to the page. Your agent stays up until the final restart.

• Channel picks persist immediately, but install nothing. Switching the channel selector saves right away and just changes which catalog you browse; a mismatch banner points out when the running version isn't from the selected channel. Nothing installs until you press Apply.

• Every update run is auditable. Each apply gets a durable run record and a redacted, size-capped log that survive the restart (/api/openclaw/runs, /api/openclaw/runs/:id/log) — the Upgrade page shows exactly what happened even after a crash mid-update.

• The running build is checked against the recorded one. Every boot writes boot-report.json (what the bin phase saw, what the server phase found, a verdict[]) and stamps alphaclaw-version.json; a tree that is not the build the channel state recorded — a redeploy whose npm install rewrote node_modules/openclaw, an interrupted activation — is re-activated at boot before anything can run from the wrong binary, and no build launches against a state database it cannot read (PRAGMA user_version vs the build's declared schema; a refusal holds the gateway instead). At runtime the same lever is POST /api/openclaw/reconcile-installed (humans only; the Upgrade page shows "Re-activate recorded build" only while the tree is diverged); the watchdog's structural repair uses it on a corroborated version-family crash instead of relaunching the crashed binary. Kill switches: OPENCLAW_RUNTIME_RECONCILE, OPENCLAW_LAUNCH_COMPAT_GATE, OPENCLAW_CRASH_CAUSE_LADDER (env table).

• Notifications you can route. Upgrade and watchdog events go through a durable outbox (retried, re-delivered after restarts) and can be routed to specific admin chats with a preferred channel and fallbacks, instead of broadcasting to every paired conversation. Overseer notices expire sixty minutes after first handling, including through quiet periods, retries and restarts; expired notices retain their history without paging later. Other notices keep the existing 48-hour retry policy.

• Managed AlphaClaw deployments stay identifiable. An accepted or uncertain provider request remains visible across reloads, restarts and version changes. It blocks another submission until a human admin verifies the provider has finished or cancelled the deployment and resolves that exact attempt. See managed deployment recovery.

• Recovery explains its wait. Crash recovery survives temporary maintenance contention. Watchdog shows its age and blocker; repair cleanup that cannot confirm writer termination shows Repair cleanup needs attention and retains ownership. See pending recovery and cleanup.

• Gateway startup medic (on by default). If the gateway dies at startup with a fatal configuration error, AlphaClaw fixes it instead of staying down: it removes the config keys the gateway itself rejected (best-effort backup taken first), or runs OpenClaw's doctor --fix, then restarts — and for unfamiliar failures it asks the smartest frontier model you have an API key for (Anthropic, OpenAI, or Gemini; evidence is secret-redacted first) to diagnose and choose from a fixed menu of safe remedies. At most two attempts per incident, every action is announced, and you can turn it off on the Upgrade page.

• Optional AI overseer (off by default). If you have the Claude Code CLI installed and an Anthropic API key set, you can enable an advisory reviewer: after an update settles, it reads the run record, redacted log tail, and openclaw doctor output, and posts a verdict ("looks healthy — consider Mark as good" / "looks broken — consider Roll back"). It's recommend-only — the deterministic auto-rollback stays in charge — and when enabled, redacted upgrade logs and doctor output are sent to the Anthropic API.

• Beta extras appear when the beta ships them. On OpenClaw 2026.8.1-beta.1+ the UI gains a session Dashboards link (opens in a new tab already signed in — the authenticated /gateway/launch redirect primes the token server-side, so it never enters the page's JavaScript), a "Create verified SQLite backup" button on the Watchdog tab (snapshots the shared state database and every configured agent's database, and verifies each snapshot it created — a backup that can't be verified is reported as a failure, never a success), and a note about secret egress binding — all hidden (and their APIs closed) on older versions.

The stable pin in package.json remains the recovery floor: whatever happens, a container restart can always fall back to it.

Off by default. When you enable features.agentAdmin (Setup UI -> General tab, "Agent Administration" panel, or PUT /api/alphaclaw/config/features/agent-admin), the OpenClaw agent can administer the deployment on behalf of admin users. It works through an alphaclaw admin <METHOD> /api/path CLI that drives the same dashboard HTTP API the web UI uses, so the server owns all validation and side effects. With the flag off, nothing observable changes.

Enabling it regenerates an alphaclaw-admin skill into the agent's workspace (rebuilt at boot, effective on the agent's next session) and appends an "AlphaClaw Administration" pointer stanza to the merged hooks/bootstrap/AGENTS.md prompt-hardening file in every agent workspace (written when you enable the flag and re-rendered at every boot; it appears only once the skill is actually installed). Nothing is written to a TOOLS.md — OpenClaw 2026.8.1+ no longer accepts it as a bootstrap file, and any legacy AlphaClaw-owned hooks/bootstrap/TOOLS.md is removed on sync. Operations are tiered: safe reads run freely, write operations mutate immediately, restart operations apply but need a gateway restart, dangerous operations require a one-time confirm code delivered to a configured admin channel, and denied operations stay operator-only. Every agent mutation is written to the Watchdog event log, and admins are notified of restart-level and dangerous changes. A bearer token (mode 0600, kept in the managed state dir, never git-synced) authenticates the CLI; rotate it from the panel.

The CLI takes the request body inline or from stdin, plus optional flags for confirm codes, a compact summary, and JSON output:

# safe: reads run freely
alphaclaw admin GET /api/openclaw/runs --json

# write: applies immediately, body from stdin
echo '{"autoRepair":true}' | alphaclaw admin PUT /api/watchdog/settings --data-stdin

# dangerous: one-time confirm code, delivered to your admin channel
alphaclaw admin DELETE /api/agents/legacy-bot --confirm ABCD-EFGH

Honest framing (same convention as team mode). This is not a hard security boundary against the agent. Since v0.9.63 the gateway child no longer inherits AlphaClaw's secrets (SETUP_PASSWORD and the internal credentials are withheld by the allowlist in lib/server/gateway-env-policy.js), but the agent still runs as AlphaClaw's own uid with HOME under the data root, so an unsandboxed exec can read .env and the state dir from disk. Agent Administration exists to keep secrets out of chat transcripts, attribute actions for audit, enable revocation, and add tiered guardrails and structured errors.

The Team tab turns a single-password AlphaClaw into a multi-member workspace. It needs the OpenClaw 2026.8.1-beta line (the tab shows "switch to the beta channel to try it" on older builds).

How it works:

• Real member accounts. Each teammate signs in with their own email and password. OpenClaw sees who's who — messages are attributed per person, everyone gets their own profile, and the roster shows who's online.
• Trusted-proxy identity. With team access on, the gateway switches from shared-token to trusted-proxy auth: AlphaClaw injects the signed-in member's email on every gateway request (HTTP, WebSocket, and webhook paths) and strips client-supplied forwarding headers so identity can't be spoofed.
• Invites and roles. Admins invite members with expiring single-use links, set roles, and disable or remove accounts — sessions and gateway authority end together, and the last admin can never be demoted. Invite acceptance is transactional (a failed signup doesn't burn the link).
• Permission boundary. Members can chat and view status. Updates, secrets, terminals, agents, webhooks, and team management stay admin-only — enforced on every API route, WebSocket, and OAuth callback, with a role-aware nav that hides admin pages.
• Safe enable + rollback. The enable wizard explains the security boundary up front, applies the gateway change, restarts, and verifies the login handshake end to end. If the check fails, it attempts to restore the previous setup and verifies the restored login before reporting recovery. A gateway hold or expired lifecycle lease can defer the restart; the result distinguishes saved auth settings from verified gateway recovery. Optional lockdown turns off shared-password login once your own account works (a break-glass env var is included).
• Deferred member sync is explicit. Member changes can save while a gateway blocker prevents syncing the authentication roster. After clearing the blocker, an administrator must save the member settings again; restarting alone does not sync the roster.
• Off means off. Turning team access off fully ends member access: member sessions and logins stop, and existing shared-password sessions end the moment shared-password login is disabled.
• Fail closed on a broken config. If alphaclaw.json exists but cannot be parsed, sign-in answers 503 config_unreadable and every existing session (shared-password and member) is refused until the file is fixed or restored — a corrupt file never silently re-enables shared-password login. ALPHACLAW_ALLOW_LEGACY_LOGIN=1 on the server is the emergency hatch for shared-password access meanwhile.

Team endpoints live under /api/team (enable, disable, invites, members, presence); all mutations are admin-only.

graph TD
    subgraph AlphaClaw
        UI["Setup UI<br/><small>Preact + htm + Wouter</small>"]
        WD["Watchdog<br/><small>Crash recovery · Notifications</small>"]
        WH["Webhooks<br/><small>Transforms · Request logging</small>"]
        UI --> API
        WD --> API
        WH --> API
        API["Express Server<br/><small>JSON APIs · Auth · Proxy</small>"]
    end

    API -- "proxy" --> GW["OpenClaw Gateway<br/><small>Child process · 127.0.0.1:18789</small>"]
    GW --> DATA["ALPHACLAW_ROOT_DIR<br/><small>.openclaw/ · .env · logs · SQLite</small>"]

The built-in watchdog monitors gateway health and recovers from failures automatically.

Opt-in: ALPHACLAW_GATEWAY_PRELAUNCH_HOOK=/absolute/path/to/executable (deployment environment only — never honored from .env). When set, AlphaClaw runs the hook and waits for it to exit before every gateway launch — the boot start, manual/API restarts, watchdog relaunches and repairs — strictly before the plugin preflight or the gateway child import the OpenClaw bundle. Use case: containers whose image cannot bake in a change — restore a runtime patch to the installed OpenClaw, start a sidecar the gateway needs, re-apply a file the platform resets on redeploy.

Requirements (all enforced, any miss aborts the launch):

• Root-owned, out-of-tree, executable regular file. The path must be absolute and canonical (a symlink, or a path with a symlinked component, is refused before it is resolved); its realpath must lie outside the AlphaClaw root (ALPHACLAW_ROOT_DIR) and the OpenClaw state dir; it must be owned by uid 0, have an execute bit, and must not be group- or world-writable; symlinks are refused (O_NOFOLLOW). Why root and out-of-tree: the deployed agent runs as AlphaClaw's own uid and can write anywhere under the tree, so "owned by the AlphaClaw user" proves nothing — only a file the operator (or the image build) installed as root, outside the agent-writable tree, is a trustworthy pre-launch step. Install it in your Dockerfile (COPY --chown=0:0 --chmod=0755 hooks/pre-gateway-launch /opt/alphaclaw/hooks/) or as root on the host.
• Inode-pinned execution. AlphaClaw opens the file, inspects the open descriptor, and on Linux executes that exact inode by descriptor (/proc/<pid>/fd/<fd>), so a file swapped between the check and the exec never runs; elsewhere the path is re-checked against the inspected inode.
• Minimal environment. The hook receives only PATH, HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, and ALPHACLAW_ROOT_DIR — never the gateway's environment (no tokens, passwords, or API keys). PATH is a fixed system path (/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin, like sudo's secure_path), never AlphaClaw's own, so a #!/usr/bin/env … shebang cannot resolve to a planted interpreter.
• Budget: 120 s, enforced as a hard deadline: the hook runs in its own process group, and 5 s after the budget the whole group is killed, so a hook that traps signals or leaves a child holding its output still fails the launch closed instead of hanging it. Its stdout/stderr are logged to the AlphaClaw process log with token-, key- and signed-URL-shaped values redacted.

Failure semantics: a refused check (wrong owner/mode/location, symlink, missing) or a failed run (non-zero exit, timeout, cannot execute) is a named error (GatewayPrelaunchHookError, with a machine code such as not_root_owned, in_tree, symlink, nonzero_exit, timeout). The launch is aborted, fail-closed: a manual restart fails with that error before anything is stopped (the running gateway keeps serving), a boot or watchdog relaunch starts no gateway, and the outcome (ran / refused / failed) is reported to the watchdog. Unset the variable to turn the hook off; there is no in-tree fallback path.

Deployment-only settings: ALPHACLAW_ALLOW_LEGACY_LOGIN and every public-origin alias (ALPHACLAW_SETUP_URL, ALPHACLAW_BASE_URL, RENDER_EXTERNAL_URL, URL, RAILWAY_PUBLIC_DOMAIN, RAILWAY_STATIC_URL) must come from the hosting platform or service's environment, not AlphaClaw's editable .env. Envars rejects edits and onboarding imports skip these keys. Boot and reload ignore existing file values without replacing genuine deployment values. If a setting exists only in .env, AlphaClaw logs a migration notice once per key per process, without its value. Review and configure the intended value in the deployment environment, then restart AlphaClaw; old file values are never promoted automatically.

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.

When enabled, the proxy forwards requests to the loopback OpenClaw gateway. AlphaClaw requires Authorization: Bearer <OPENCLAW_GATEWAY_TOKEN> 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 a machine-derived limit: 20 MB on small containers, scaling with resource autotune to 32/48/64 MB on medium/large/xl tiers (overridable via openAiCompatBodyLimitMb, clamped to ~10% of container memory — parsing a large body can transiently need several times its size in heap). 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.<REMOTE_MCP_NAME> 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).

An enabled OpenClaw A2A channel is reachable on AlphaClaw's public port. You do not need to publish the loopback gateway port or enable the OpenAI-compatible API feature.

Only these exact paths and methods are forwarded for A2A. A setup cookie or OPENCLAW_GATEWAY_TOKEN is not a substitute for a peer credential. AlphaClaw passes the peer's Authorization header and body bytes unchanged, strips setup cookies and client-supplied identity/forwarding headers, and never injects browser/operator identity into these requests. The proxy's 50 MiB streamed-body cap still applies; OpenClaw 2026.9.5 enforces a stricter 1 MiB A2A request limit.

Configure the channel in openclaw.json, with a separate high-entropy token for each peer:

{
  "channels": {
    "a2a": {
      "enabled": true,
      "advertisedUrl": "https://your-alphaclaw.example.com",
      "exposeAgents": ["main"],
      "peers": { "trusted-peer": { "token": "${A2A_PEER_TOKEN}" } }
    }
  }
}

Set A2A_PEER_TOKEN in the gateway environment and restart the gateway. Set advertisedUrl to the externally reachable HTTPS origin of AlphaClaw, without /openclaw or /a2a/v1; the card appends /a2a/v1. AlphaClaw does not fill or overwrite this operator setting, including from ALPHACLAW_SETUP_URL. If omitted, OpenClaw derives the origin from the proxied request and can advertise its internal loopback address instead. Verify the card's supportedInterfaces[].url from the peer's network before connecting.

Discovery exposes the instance description and exposed agent IDs without login. Use exposeAgents to limit disclosure and HTTPS on untrusted networks. Peer tasks retain the routed agent's tool permissions; approve peers accordingly. See the bundled OpenClaw docs/channels/a2a.md for JSON-RPC examples and peer configuration.

For long tasks, use SendMessage with params.configuration.returnImmediately: true and poll GetTask, or size ALPHACLAW_PROXY_TIMEOUT_MS for the gateway's blocking reply wait. The proxy defaults to a 30-second wait for response headers; a proxy timeout does not cancel the upstream task.

The real pinned-gateway regression runs with OPENCLAW_LIVE_E2E=1 npm test -- tests/live/proxy-a2a.e2e.test.js --no-file-parallelism. It exercises the full AlphaClaw HTTP proxy and real A2A auth/task lifecycle with a local deterministic model endpoint, without external model credentials.

AlphaClaw is a convenience wrapper — it intentionally trades some of OpenClaw's default hardening for ease of setup. You should understand what's different:

If you need OpenClaw's full security posture (manual pairing codes, no query-string tokens, no auto-approval), use OpenClaw directly without AlphaClaw.

Release history lives in CHANGELOG.md; contributor setup and test tiers are in CONTRIBUTING.md; open work is tracked in TODOS.md; design documents (Agent Administration, chat reliability, gateway state model, the OpenClaw context contract, Telegram topics discovery, the AlphaClaw offline-copy backup format, and reliability ownership) live in docs/designs/; the operator runbook for upgrade failure states (held gateways, backup contention and the offline copy, restoring a backup, consented backup reuse, incumbent gateways, a gateway that is up but not ready, state-directory ownership conflicts, expired repair leases, the prelaunch hook, rollback fencing) is docs/upgrade-troubleshooting.md; architecture notes and conventions for coding agents are in AGENTS.md.

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 (hermetic — no network)
npm run test:watchdog   # Watchdog-focused suite
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

# Live e2e tiers (opt-in; hit the REAL npm registry / GitHub API and install
# real OpenClaw releases — catch upstream drift the hermetic suite can't):
npm run test:live       # catalog + real stable/beta package applies, a
                        # real-gateway memory-leak e2e against the newest beta,
                        # and the #54 backup suites (state-lock contention
                        # reproduction, real beta→stable downgrade, 12-cell
                        # restore drill, gateway-stop contract) against the real
                        # pin/stable/beta packages (network). Needs a supported
                        # Node FIRST on PATH (the
                        # real npm installs resolve `node` from PATH). Stages GBs
                        # under $TMPDIR: roots are swept per file; between
                        # interrupted runs `rm -rf /tmp/alphaclaw-live-*
                        # /tmp/openclaw-prepare-*` and check `df -h /` — the
                        # per-version install cache survives private TMPDIR
                        # cleanup (~/.cache/alphaclaw-openclaw-cache; override
                        # with ALPHACLAW_LIVE_OPENCLAW_CACHE). Cross-process
                        # ownership serializes verified atomic publication.
npm run test:live:dev   # dev-channel source build only (20-35 min, ~5 GB disk);
                        # does not re-run the catalog/apply tiers above
npm run test:container  # production-container journeys: stable→beta through
                        # Chromium, deterministic thread-ID collision, and
                        # immutable AlphaClaw v0.9.76→candidate on one volume.
                        # Proves recorded-overlay activation, gateway readiness,
                        # preserved config and pidfile convergence.
                        # Needs docker + network; CI allows 110 minutes.
npm run test:ui         # Browser UI smoke of the Upgrade page: real server +
                        # headless Chromium asserting the rendered DOM (opt-in;
                        # needs network for the version catalog; self-skips
                        # unless a browse CLI is present — set BROWSE_BIN)
npm run test:ui:reliability # Chromium recovery, deployment and Gmail journeys
                        # against local fixtures; needs build:ui and
                        # npx playwright install chromium. Reports/screenshots:
                        # .context/wave-browser/ (WAVE_BROWSER_ARTIFACTS overrides)
npm run test:ui:time    # Browser smoke of UI time formatting: real server +
                        # headless Chromium asserting rendered timestamps against
                        # expectations the browser itself computes with the same
                        # Intl presets, so it passes in any locale/timezone
                        # (opt-in; self-skips without a browse CLI — set BROWSE_BIN)
npm run test:ui:claude-code   # Browser smoke of the Open Claude Code launcher
                        # (opt-in; same real-server + Chromium harness)
npm run test:live:claude-code # Fires the REAL configured routine end-to-end —
                        # BILLS one claude.ai session; needs CLAUDE_CODE_ROUTINE_URL
                        # / CLAUDE_CODE_ROUTINE_TOKEN + CLAUDE_CODE_LIVE_FIRE=1

The live tiers also run in CI on a schedule (.github/workflows/live-e2e.yml): nightly for catalog + package applies, weekly (or manually via workflow_dispatch) for the dev source build. A live-tier failure usually means upstream OpenClaw changed something the channel feature depends on (dist-tags, prerelease naming, engines, updater JSON, dist layout) — not that this repo regressed.

Container journeys run in .github/workflows/container-e2e.yml. An enabled container tier fails if Docker is unavailable; a skipped invocation is not upgrade evidence. Cloud sandboxes may lack Docker, and a threaded cgroup topology can prevent memory-limited containers from starting. Verify an actual limited container and follow the tested setup in the cloud testing runbook. CI or a Docker Desktop/Colima host can also run these checks. The immutable two-image journey must pass before considering self-upgrade risk covered.

Requirements: Node.js ≥ 24.16.0 on Node 24, or ≥ 26.1.0 on Node 26 (OpenClaw 2026.9.3 dropped Node 22 and 25 — older runtimes truncate SQLite text)

CI (.github/workflows/ci.yml) runs the hermetic suite on Node 24 and Node 26. The main ruleset requires test (24) plus the container-e2e gate aggregator; test (26) is an early-warning lane (continue-on-error) whose failures are reported but do not block a merge until the ruleset lists it as required.

alphaclaw.md is the official AlphaClaw website.

MIT