let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: recommend WSL2 for Windows installs

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-07 01:21:36 +01:00
parent 62112d9978
commit 0116184b1c
13 changed files with 123 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@@ -22,7 +22,7 @@ If you want a personal, single-user assistant that feels local, fast, and always
[Website](https://clawdbot.com) · [Docs](https://docs.clawd.bot) · Getting Started: [https://docs.clawd.bot/getting-started](https://docs.clawd.bot/getting-started) · Updating: [https://docs.clawd.bot/updating](https://docs.clawd.bot/updating) · Showcase: [https://docs.clawd.bot/showcase](https://docs.clawd.bot/showcase) · FAQ: [https://docs.clawd.bot/faq](https://docs.clawd.bot/faq) · Wizard: [https://docs.clawd.bot/wizard](https://docs.clawd.bot/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawd.bot/docker](https://docs.clawd.bot/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**.
Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
Works with npm, pnpm, or bun.
New install? Start here: https://docs.clawd.bot/getting-started
@@ -369,7 +369,7 @@ Use these when you’re past the onboarding flow and want the deeper reference.
- [Wire external triggers via the webhook surface.](https://docs.clawd.bot/webhook)
- [Set up Gmail Pub/Sub triggers.](https://docs.clawd.bot/gmail-pubsub)
- [Learn the macOS menu bar companion details.](https://docs.clawd.bot/mac/menu-bar)
- [Platform guides: Windows](https://docs.clawd.bot/windows), [Linux](https://docs.clawd.bot/linux), [macOS](https://docs.clawd.bot/macos), [iOS](https://docs.clawd.bot/ios), [Android](https://docs.clawd.bot/android)
- [Platform guides: Windows (WSL2)](https://docs.clawd.bot/windows), [Linux](https://docs.clawd.bot/linux), [macOS](https://docs.clawd.bot/macos), [iOS](https://docs.clawd.bot/ios), [Android](https://docs.clawd.bot/android)
- [Debug common failures with the troubleshooting guide.](https://docs.clawd.bot/troubleshooting)
- [Review security guidance before exposing anything.](https://docs.clawd.bot/security)
@@ -416,7 +416,7 @@ Use these when you’re past the onboarding flow and want the deeper reference.
- [macOS voice wake](https://docs.clawd.bot/mac/voicewake)
- [iOS node](https://docs.clawd.bot/ios)
- [Android node](https://docs.clawd.bot/android)
- [Windows app](https://docs.clawd.bot/windows)
- [Windows (WSL2)](https://docs.clawd.bot/windows)
- [Linux app](https://docs.clawd.bot/linux)
## Email hooks (Gmail)

4
docs/gateway/doctor.md
View File

@@ -14,7 +14,7 @@ read_when:
- Detects deprecated config keys and offers to migrate them.
- Migrates legacy `~/.clawdis/clawdis.json` when no Clawdbot config exists.
- Checks sandbox Docker images when sandboxing is enabled (offers to build or switch to legacy names).
- Detects legacy Clawdis services (launchd/systemd/schtasks) and offers to migrate them.
- Detects legacy Clawdis services (launchd/systemd; legacy schtasks for native Windows) and offers to migrate them.
- On Linux, checks if systemd user lingering is enabled and can enable it (required to keep the Gateway alive after logout).
- Migrates legacy on-disk state layouts (sessions, agentDir, provider auth dirs) into the current per-agent/per-account structure.
@@ -63,6 +63,6 @@ cat ~/.clawdbot/clawdbot.json
```
## Legacy service migrations
Doctor checks for older Clawdis gateway services (launchd/systemd/schtasks).
Doctor checks for older Clawdis gateway services (launchd/systemd/schtasks). WSL2 installs use systemd.
If found, it offers to remove them and install the Clawdbot service using the current gateway port.
Remote mode skips the install step, and Nix mode only reports what it finds.

10
docs/gateway/index.md
View File

@@ -184,7 +184,7 @@ Enable lingering (required so the user service survives logout/idle):
```
sudo loginctl enable-linger youruser
```
Onboarding runs this on Linux (may prompt for sudo; writes `/var/lib/systemd/linger`).
Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`).
Then enable the service:
```
systemctl --user enable --now clawdbot-gateway.service
@@ -199,9 +199,9 @@ sudo systemctl daemon-reload
sudo systemctl enable --now clawdbot-gateway.service
```
## Supervision (Windows scheduled task)
- Onboarding installs a Scheduled Task named `Clawdbot Gateway` (runs on user logon).
- Requires a logged-in user session; for headless setups use a system service or a task configured to run without a logged-in user (not shipped).
## Windows (WSL2)
Windows installs should use **WSL2** and follow the Linux systemd section above.
## Operational checks
- Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
@@ -219,7 +219,7 @@ sudo systemctl enable --now clawdbot-gateway.service
- `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
- `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
- `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd/schtasks).
- `clawdbot gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
- Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
## Migration guidance

2
docs/index.md
View File

@@ -177,7 +177,7 @@ Example:
- [macOS app](https://docs.clawd.bot/platforms/macos)
- [iOS app](https://docs.clawd.bot/platforms/ios)
- [Android app](https://docs.clawd.bot/platforms/android)
- [Windows app](https://docs.clawd.bot/platforms/windows)
- [Windows (WSL2)](https://docs.clawd.bot/platforms/windows)
- [Linux app](https://docs.clawd.bot/platforms/linux)
- Ops and safety:
- [Sessions](https://docs.clawd.bot/concepts/session)

6
docs/install/updating.md
View File

@@ -12,7 +12,7 @@ Clawdbot is moving fast (pre “1.0”). Treat updates like shipping infra: upda
## Before you update
- Know how you installed: **npm** (global) vs **from source** (git clone).
- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd/Scheduled Task).
- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).
- Snapshot your tailoring:
- Config: `~/.clawdbot/clawdbot.json`
- Credentials: `~/.clawdbot/credentials/`
@@ -68,7 +68,7 @@ Typical things it does:
- Migrate deprecated config keys / legacy config file locations.
- Audit DM policies and warn on risky “open” settings.
- Check Gateway health and can offer to restart.
- Detect and migrate older gateway services (launchd/systemd/schtasks) to current Clawdbot services.
- Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current Clawdbot services.
- On Linux, ensure systemd user lingering (so the Gateway survives logout).
Details: [Doctor](/doctor)
@@ -86,7 +86,7 @@ clawdbot gateway --port 18789
If you’re supervised:
- macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`
- Linux systemd user service: `systemctl --user restart clawdbot-gateway.service`
- Windows: restart the `Clawdbot Gateway` Scheduled Task (Task Scheduler)
- Windows (WSL2): `systemctl --user restart clawdbot-gateway.service`
Runbook + exact service labels: [Gateway runbook](/gateway)

70
docs/platforms/windows.md
View File

@@ -1,11 +1,73 @@
---
summary: "Windows app status + contribution call"
summary: "Windows (WSL2) setup + companion app status"
read_when:
- Installing Clawdbot on Windows
- Looking for Windows companion app status
- Planning platform coverage or contributions
---
# Windows App
# Windows (WSL2)
Clawdbot core is fully supported on Windows. The core is written in TypeScript, so it runs anywhere Node runs.
Clawdbot runs on Windows **via WSL2** (Ubuntu recommended). WSL2 is **strongly
recommended**; native Windows installs are untested and more problematic. Use
WSL2 and follow the Linux flow inside it.
We do not have a Windows companion app yet. It is planned, and we would love contributions to make it happen.
## How to install this correctly
Start here (official WSL2 guide): https://learn.microsoft.com/windows/wsl/install
### 1) Install WSL2 + Ubuntu
Open PowerShell (Admin):
```powershell
wsl --install
# Or pick a distro explicitly:
wsl --list --online
wsl --install -d Ubuntu-24.04
```
Reboot if Windows asks.
### 2) Enable systemd (required for daemon install)
In your WSL terminal:
```bash
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
```
Then from PowerShell:
```powershell
wsl --shutdown
```
Re-open Ubuntu, then verify:
```bash
systemctl --user status
```
### 3) Install Clawdbot (inside WSL)
Follow the Linux Getting Started flow inside WSL:
```bash
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:install
pnpm ui:build
pnpm build
pnpm clawdbot onboard
```
Full guide: [Getting Started](/getting-started)
## Windows companion app
We do not have a Windows companion app yet. It is planned, and we would love
contributions to make it happen.

2
docs/start/clawd.md
View File

@@ -212,6 +212,6 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
- macOS menu bar companion: [Clawdbot macOS app](/macos)
- iOS node app: [iOS app](/ios)
- Android node app: [Android app](/android)
- Windows status: [Windows app](/windows)
- Windows status: [Windows (WSL2)](/windows)
- Linux status: [Linux app](/linux)
- Security: [Security](/security)

21
docs/start/faq.md
View File

@@ -28,11 +28,11 @@ Your **workspace** (AGENTS.md, memory files, skills) is separate — configured
### What platforms does Clawdbot run on?
**macOS and Linux** are the primary targets. Anywhere Node.js 22+ runs should work in theory.
**macOS and Linux** are the primary targets. On Windows, use **WSL2** (Ubuntu recommended).
- **macOS** — Fully supported, most tested
- **Linux** — Works great, common for VPS/server deployments
- **Windows** — Should work but largely untested! You're in pioneer territory 🤠
- **Windows (WSL2)** — WSL2 is strongly recommended; native Windows installs are untested and more problematic
Some features are platform-specific:
- **iMessage** — macOS only (uses `imsg` CLI)
@@ -52,6 +52,18 @@ The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. For
clawdbot gateway
```
### How do I install on Windows?
Use **WSL2** (Ubuntu recommended) and follow the Linux flow inside WSL. Quick start:
```powershell
wsl --install
```
Then open Ubuntu and run the normal Getting Started steps.
Full guide: [Windows (WSL2)](/windows)
### How do I install on Linux without Homebrew?
Build CLIs from source! Example for `gogcli`:
@@ -494,9 +506,10 @@ Onboarding attempts to enable lingering; if it’s still off, run:
sudo loginctl enable-linger $USER
```
**macOS/Windows**
**macOS/WSL2**
Gateway daemons run in the user session by default. Keep the user logged in.
Gateway daemons run in the user session by default. Keep the user logged in
(WSL2 services stop when the WSL VM shuts down).
Headless/system services are not configured out of the box.
### Processes keep restarting after I kill them

3
docs/start/getting-started.md
View File

@@ -26,6 +26,7 @@ If you want the deeper reference pages, jump to: [Wizard](/wizard), [Setup](/set
- Git
macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested and more problematic. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/windows).
## 1) Check out from source
@@ -63,7 +64,7 @@ What you’ll choose:
- **Local vs Remote** gateway
- **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now
- **Providers**: WhatsApp QR login, bot tokens, etc.
- **Daemon**: optional background install (launchd/systemd/Task Scheduler)
- **Daemon**: optional background install (launchd/systemd; WSL2 uses systemd)
- **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
Wizard doc: [Wizard](/wizard)

2
docs/start/hubs.md
View File

@@ -131,7 +131,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
- [macOS Peekaboo plan](https://docs.clawd.bot/platforms/mac/peekaboo)
- [iOS node](https://docs.clawd.bot/platforms/ios)
- [Android node](https://docs.clawd.bot/platforms/android)
- [Windows app](https://docs.clawd.bot/platforms/windows)
- [Windows (WSL2)](https://docs.clawd.bot/platforms/windows)
- [Linux app](https://docs.clawd.bot/platforms/linux)
- [Web surfaces](https://docs.clawd.bot/web)

8
docs/start/onboarding.md
View File

@@ -187,3 +187,11 @@ chmod 600 ~/.clawdbot/credentials/oauth.json
| `accessToken` | `access` |
| `refreshToken` | `refresh` |
| `expiresAt` | `expires` |
## Workspace backup (recommended)
We suggest creating a **private GitHub repository** to back up the agent
workspace. The agent is really good at keeping a git repo in shape, and GitHub
is the perfect place for it. Keep it **private**.
Setup steps: https://docs.clawd.bot/concepts/agent-workspace

11
docs/start/wizard.md
View File

@@ -7,7 +7,8 @@ read_when:
# Onboarding Wizard (CLI)
The onboarding wizard is the **recommended** way to set up Clawdbot on any OS.
The onboarding wizard is the **recommended** way to set up Clawdbot on macOS,
Linux, or Windows (via WSL2; strongly recommended).
It configures a local Gateway or a remote Gateway connection, plus providers, skills,
and workspace defaults in one guided flow.
@@ -30,7 +31,7 @@ clawdbot configure
- Workspace location + bootstrap files
- Gateway settings (port/bind/auth/tailscale)
- Providers (WhatsApp, Telegram, Discord, Signal)
- Daemon install (LaunchAgent / systemd user unit / Scheduled Task)
- Daemon install (LaunchAgent / systemd user unit)
- Health check
- Skills (recommended)
@@ -77,11 +78,9 @@ It does **not** install or change anything on the remote host.
6) **Daemon install**
- macOS: LaunchAgent
- Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
- Linux: systemd user unit
- Linux (and Windows via WSL2): systemd user unit
- Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
- May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
- Windows: Scheduled Task
- Runs on user logon; headless/system services are not configured by default.
- **Runtime selection:** Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp).
7) **Health check**
@@ -144,7 +143,7 @@ The wizard can install `signal-cli` from GitHub releases:
Notes:
- JVM builds require **Java 21**.
- Native builds are used when available.
- Windows auto‑install is not supported yet (manual install required).
- Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.
## What the wizard writes

9
src/commands/onboard.ts
View File

@@ -10,6 +10,15 @@ export async function onboardCommand(
runtime: RuntimeEnv = defaultRuntime,
) {
assertSupportedRuntime(runtime);
if (process.platform === "win32") {
runtime.log(
[
"Windows detected.",
"WSL2 is strongly recommended; native Windows is untested and more problematic.",
"Guide: https://docs.clawd.bot/windows",
].join("\n"),
);
}
if (opts.nonInteractive) {
await runNonInteractiveOnboarding(opts, runtime);