Skip to main content

​
Setup

Last updated: 2026-01-01

​
TL;DR

  • Tailoring lives outside the repo: ~/clawd (workspace) + ~/.clawdbot/clawdbot.json (config).
  • Stable workflow: install the macOS app; let it run the bundled Gateway.
  • Bleeding edge workflow: run the Gateway yourself via pnpm gateway:watch, then point the macOS app at it using Debug Settings → Gateway → Attach only.

​
Prereqs (from source)

  • Node >=22
  • pnpm
  • Docker (optional; only for containerized setup/e2e — see docs/docker.md)

​
Tailoring strategy (so updates don’t hurt)

If you want “100% tailored to me” and easy updates, keep your customization in:
  • Config: ~/.clawdbot/clawdbot.json (JSON/JSON5-ish)
  • Workspace: ~/clawd (skills, prompts, memories; make it a private git repo)
Bootstrap once: 
clawdbot setup
From inside this repo, use the local CLI entry: 
pnpm clawdbot setup

​
Stable workflow (macOS app first)

  1. Install + launch Clawdbot.app (menu bar).
  2. Complete the onboarding/permissions checklist (TCC prompts).
  3. Ensure Gateway is Local and running (the app manages it).
  4. Link surfaces (example: WhatsApp):
clawdbot providers login
  1. Sanity check:
clawdbot health
If onboarding is not available in your build:
  • Run clawdbot setup, then clawdbot providers login, then start the Gateway manually (clawdbot gateway).

​
Bleeding edge workflow (Gateway in a terminal)

Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.

​
0) (Optional) Run the macOS app from source too

If you also want the macOS app on the bleeding edge: 
./scripts/restart-mac.sh

​
1) Start the dev Gateway

pnpm install
pnpm gateway:watch
gateway:watch runs the gateway in watch mode and reloads on TypeScript changes.

​
2) Point the macOS app at your running Gateway

In Clawdbot.app:
  • Connection Mode: Local
  • Settings → Debug Settings → Gateway → enable Attach only
This makes the app only connect to an already-running gateway and never spawn its own.

​
3) Verify

  • In-app Gateway status should read “Using existing gateway …”
  • Or via CLI:
pnpm clawdbot health

​
Common footguns

  • Attach only enabled, but nothing is running: app shows “Attach-only enabled; no gateway to attach”.
  • Wrong port: Gateway WS defaults to ws://127.0.0.1:18789; keep app + CLI on the same port.
  • Where state lives:
    • Credentials: ~/.clawdbot/credentials/
    • Sessions: ~/.clawdbot/agents/<agentId>/sessions/
    • Logs: /tmp/clawdbot/

​
Updating (without wrecking your setup)

  • Keep ~/clawd and ~/.clawdbot/ as “your stuff”; don’t put personal prompts/config into the clawdbot repo.
  • Updating source: git pull + pnpm install (when lockfile changed) + keep using pnpm gateway:watch.

​
Linux (systemd user service)

Linux installs use a systemd user service. By default, systemd stops user services on logout/idle, which kills the Gateway. Onboarding attempts to enable lingering for you (may prompt for sudo). If it’s still off, run: 
sudo loginctl enable-linger $USER
For always-on or multi-user servers, consider a system service instead of a user service (no lingering needed). See docs/gateway.md for the systemd notes.