AlphaClaw

Step 1 · Day zero

Deploy with two secrets, wizard the rest

The deploy form asks for almost nothing — a setup password and a GitHub token. The blog frames this as a decision: "The Render deploy form does not become a dumping ground for every secret your agent might need." Everything else happens in a browser wizard afterward. If you already had an agent, the import path clones your old workspace repo, scans it, and — the best part — hunts for plaintext secrets in the config: 34 known config paths, 27 vendor key prefixes (sk-ant-, ghp_, xoxb-…), and a name heuristic. Found secrets are shown for review, moved into .env, and the config file is rewritten to hold ${ENV_REF} references instead. The server re-validates every approved secret against its own scan by fingerprint — the browser can rename a variable but cannot inject a value the scanner never saw.

• import-scanner.js watches — classifies the clone: config, env files, skills, cron jobs, webhooks, credentials, managed conflicts.
• secret-detector.js watches — three-channel secret hunt; masks values as abcd****wxyz for review.
• import-applier.js touches — applies the import; scrubs the same secret everywhere it appears, longest value first.
• onboarding/workspace.js touches — seeds the workspace and the bootstrap prompt files.

Step 2 · Boot

Spawn the agent, stamp its discipline

Every boot, AlphaClaw spawns openclaw gateway run as a child on loopback port 18789, handing it the entire environment plus a redirected HOME — and one crucial flag: OPENCLAW_NO_RESPAWN=1, so the agent cannot restart itself (see decision R3). Before the spawn it re-stamps the discipline files — AGENTS.md and a templated TOOLS.md — into every agent workspace's hooks/bootstrap/ directory, and rewrites the managed MCP entry in openclaw.json, scrubbing any plaintext token back to a ${REMOTE_MCP_API_TOKEN} reference. Readiness detection is charmingly fragile: it greps the child's stdout for the string "listening on".

• gateway.js touches — spawn, env injection, config rewriting, readiness grep, plugin preflight.
• openclaw-runtime-env.js touches — adds the compile cache and the OPENCLAW_NO_RESPAWN=1 flag.
• startup.js touches — the onboarded boot sequence: re-sync prompts, reload env, sync channels, start gateway, start watchdog.
• core-prompts/TOOLS.md touches — the stamped instructions, templated with the live dashboard URL and connected Google accounts.

Step 3 · The front door

Four doors, four different locks

Everything shares one public port, but the doors differ wildly in lock quality. The dashboard and setup APIs need the password-derived session cookie, with a persistent two-tier lockout behind it. The /v1 API needs the gateway token, compared timing-safe, with its own throttle. Webhooks get no AlphaClaw auth at all — the request is normalized (a ?token= query parameter is promoted into a bearer header, then deleted from the URL) and relayed for OpenClaw to judge. Gmail push is the weakest door: a plain string compare on a query token, and Google's signed identity token is never verified.

• routes/auth.js watches — session HMAC is keyed by the setup password itself: rotate the password, log everyone out.
• login-throttle.js watches — per-IP and global lockout state in SQLite; survives restarts.
• routes/proxy.js watches — the /v1 boundary; strips cookies both directions ("a stray Set-Cookie crossing the AlphaClaw boundary would be a real leak").
• webhook-middleware.js watches — normalizes, logs (with key-based redaction), relays byte-for-byte.
• gmail-push.js watches — the weak door: query-token compare, no JWT verification, no throttle.

Step 4 · Serve

A message arrives; the agent works; git gets a receipt

Normal operation barely involves AlphaClaw: Telegram talks to the gateway, the agent does its work in the workspace under /data/.openclaw. AlphaClaw's influence is the stamped discipline: the agent must commit workspace changes and end its reply with a "Changes committed" summary linking the commit hash. To make that possible without handing the agent a token, AlphaClaw installs a git shim at /usr/local/bin/git that injects GITHUB_TOKEN credentials — but only when the working directory is inside the workspace repo. The agent can also reach back into its own harness: create webhooks, call the setup APIs, run the CLI.

• lib/scripts/git touches — the shim: resolves the real git, computes the effective cwd (including -C), injects credentials only inside the workspace repo.
• git-askpass touches — answers x-access-token / $GITHUB_TOKEN.
• core-prompts/AGENTS.md touches — "No YOLO system changes", plan-before-build, commit discipline.
• routes/browse/ touches — the human's parallel hands: browser file editor with per-file git restore.

Step 5 · Watch

Ledgers for tokens, health, and incidents

Observation runs on five separate SQLite ledgers under /data/db/ — usage, watchdog events, doctor runs, webhook requests, auth throttle. The clever bit is how usage gets in: AlphaClaw installs a plugin inside OpenClaw that records every model call's token counts into the shared database; AlphaClaw then prices them with its hardcoded table and renders the Usage and Cron tabs. Health is polled every 120 seconds; a live browser terminal (a real shell on the box) covers whatever the dashboards don't.

• usage-tracker/index.js watches — the informant plugin; WAL-mode SQLite writes.
• cost-utils.js watches — the hardcoded price table; unknown model → $0.00.
• cron-service.js watches — run history, trends, per-run usage for scheduled jobs.
• watchdog-terminal.js touches — a real shared shell in the browser; 15-minute idle kill.
• db/watchdog/ watches — incident ledger, 30-day retention, routine green checks filtered from view.

Step 6 · Hourly rhythm

The backup clock: commit the allowlist, drop the noise

A root cron entry fires hourly-git-sync.sh every hour. Before committing, it runs a noise filter: if the cron bookkeeping files changed only in runtime metadata (lastRun, timestamps, run counts), it restores them — "Runtime metadata only; restore cleanly so it doesn't create noise commits." Then alphaclaw git-sync stages everything the deny-by-default gitignore allows, commits as "AlphaClaw Agent", and pushes. The commit message is a timestamp; the history is the rollback story from decision C1.

• hourly-git-sync.sh touches — the clock's hand; re-written from the packaged copy on every boot if it drifted.
• onboarding/cron.js touches — installs the system cron entry at /etc/cron.d.
• bin/alphaclaw.js touches — git-sync command: rebase-pull, stage, commit, push; per-PID temp askpass.
• lib/setup/gitignore watches — the deny-by-default allowlist that defines "what survives".

Step 7 · Break & heal

The self-repair loop, with teeth and gaps

A crash relaunches the gateway immediately — no backoff. Three crashes inside 300 seconds is a crash loop: the watchdog stops restarting, opens an incident, and notifies. Only if auto-repair is enabled (it is off by default, despite the "self-healing" headline) does it run openclaw doctor --fix --yes, relaunch, and verify with a health check. Two states break the loop deliberately: exit code 78 latches restarts off until a human fixes the config, and OpenClaw's own "safe mode" breaker (channels suppressed, health still green) is merely observed and reported — resuming channels is a button, not an automatism.

The exploration surfaced real gaps between headline and code: the repair-attempt cap notifies "paused" but never actually pauses; the repair command inherits a 15-second timeout while the separate Doctor service grants itself 10 minutes; and the watchdog's repair (openclaw doctor, OpenClaw's deterministic CLI) is an entirely different system from AlphaClaw's Doctor tab (an LLM that audits the workspace and is forbidden to change anything).

• watchdog.js touches — the state machine, crash classification (stderr grep for "already listening" = not a crash), repair orchestration.
• watchdog-notify.js watches — 🐺-format notices to whatever channels are paired.
• doctor/service.js watches — the other doctor: LLM workspace audit, advisory-only, skipped entirely when a deterministic workspace fingerprint says nothing changed.
• doctor/bootstrap-context.js watches — deterministic budget model of prompt injection; warns before OpenClaw silently trims oversized files ("keep first 70%, last 20%, cut the middle").
• routes/watchdog.js touches — manual repair (force), resume-channels, settings.

Step 8 · Die & come back

The restore ladder: three rungs, honestly lossy

What returns after a failure depends on which layer died. A process restart loses nothing — the boot sequence re-stamps prompts and relaunches the gateway. A redeploy keeps everything because /data is a persistent volume. Volume loss drops you to the bottom rung: nothing is auto-cloned; you re-run onboarding, import from the workspace repo, and get back exactly the committed allowlist. Secrets must be re-entered, channels re-paired, and every ledger starts empty.

• openclaw-config-restore.js touches — the one automatic restore: fetches openclaw.json from the remote if it vanished locally while .git survived.
• onboarding/index.js touches — the import path: clone, scan, review, apply; re-inits git, deletes replaceable bootstrap paths.
• env.js touches — .env read/write/watch; the file that never rides the ladder.

Step 9 · Upgrade

Replacing organs while the patient runs

Both packages update by the same trick (decision R8): install into a temp directory, then cp -af over the live node_modules, avoiding the rename syscall that EBUSYs on Docker. Updating OpenClaw then restarts only the child gateway. Updating AlphaClaw itself must restart the container — so before exiting it writes a marker file to the persistent volume, and the next boot replays the install, because on ephemeral filesystems the freshly-copied files were themselves lost in the restart. A strategy detector picks the right story per platform (Render, Railway, Docker, managed, git-pinned) — and git-pinned installs get told to redeploy instead.

• alphaclaw-version.js touches — strategy detection, self-install, restart orchestration.
• openclaw-version.js touches — the child's update: copy trick + gateway restart, guarded by an in-progress flag.
• self-dependency.js watches — finds who installed AlphaClaw and how it's pinned; one boolean (git vs npm) gates the whole update UX.