Spaces:
Configuration error
Configuration error
File size: 4,402 Bytes
3a65265 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 | ---
summary: "Setup guide: keep your Moltbot setup tailored while staying up-to-date"
read_when:
- Setting up a new machine
- You want “latest + greatest” without breaking your personal setup
---
# Setup
Last updated: 2026-01-01
## TL;DR
- **Tailoring lives outside the repo:** `~/clawd` (workspace) + `~/.clawdbot/moltbot.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 let the macOS app attach in Local mode.
## Prereqs (from source)
- Node `>=22`
- `pnpm`
- Docker (optional; only for containerized setup/e2e — see [Docker](/install/docker))
## Tailoring strategy (so updates don’t hurt)
If you want “100% tailored to me” *and* easy updates, keep your customization in:
- **Config:** `~/.clawdbot/moltbot.json` (JSON/JSON5-ish)
- **Workspace:** `~/clawd` (skills, prompts, memories; make it a private git repo)
Bootstrap once:
```bash
moltbot setup
```
From inside this repo, use the local CLI entry:
```bash
moltbot setup
```
If you don’t have a global install yet, run it via `pnpm moltbot setup`.
## Stable workflow (macOS app first)
1) Install + launch **Moltbot.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):
```bash
moltbot channels login
```
5) Sanity check:
```bash
moltbot health
```
If onboarding is not available in your build:
- Run `moltbot setup`, then `moltbot channels login`, then start the Gateway manually (`moltbot 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:
```bash
./scripts/restart-mac.sh
```
### 1) Start the dev Gateway
```bash
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 **Moltbot.app**:
- Connection Mode: **Local**
The app will attach to the running gateway on the configured port.
### 3) Verify
- In-app Gateway status should read **“Using existing gateway …”**
- Or via CLI:
```bash
moltbot health
```
### Common footguns
- **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/moltbot/`
## Credential storage map
Use this when debugging auth or deciding what to back up:
- **WhatsApp**: `~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`
- **Telegram bot token**: config/env or `channels.telegram.tokenFile`
- **Discord bot token**: config/env (token file not yet supported)
- **Slack tokens**: config/env (`channels.slack.*`)
- **Pairing allowlists**: `~/.clawdbot/credentials/<channel>-allowFrom.json`
- **Model auth profiles**: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
- **Legacy OAuth import**: `~/.clawdbot/credentials/oauth.json`
More detail: [Security](/gateway/security#credential-storage-map).
## Updating (without wrecking your setup)
- Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `moltbot` 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:
```bash
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 [Gateway runbook](/gateway) for the systemd notes.
## Related docs
- [Gateway runbook](/gateway) (flags, supervision, ports)
- [Gateway configuration](/gateway/configuration) (config schema + examples)
- [Discord](/channels/discord) and [Telegram](/channels/telegram) (reply tags + replyToMode settings)
- [Moltbot assistant setup](/start/clawd)
- [macOS app](/platforms/macos) (gateway lifecycle)
|