Setup & Configuration
Installation and configuration guide: Keep your OpenClaw personalized while staying updated.
Last updated: 2026-01-01
TL;DR
- **Keep personalization outside the repo:** `~/.openclaw/workspace` (workspace) + `~/.openclaw/openclaw.json` (config).
- **Stable Workflow:** Install macOS app and let it run its own Gateway.
- **Bleeding Edge Workflow:** Run Gateway yourself with `pnpm gateway:watch` and connect macOS app in Local mode.
Prerequisites (Running from Source)
Personalization Strategy (Update without pain)
If you want "100% customized for me" and easy updates, keep your custom content in:
- **Config:** `~/.openclaw/openclaw.json` (JSON/JSON5 style)
- **Workspace:** `~/.openclaw/workspace` (skills, prompts, memories; recommended as a private git repo)
First-time bootstrap:
openclaw setup
Within this repository, use the local CLI entry:
openclaw setup
If not globally installed, use `pnpm openclaw setup`.
Stable Workflow (macOS App Priority)
1. 1. Install and launch **OpenClaw.app** (menu bar).
2. 2. Complete Onboarding / Permissions (TCC authorization popups).
3. 3. Confirm Gateway is in **Native** mode and running (managed by app).
4. 4. Connect chat platforms (example: WhatsApp):
openclaw channels login
5. 5. Health check:
openclaw health
If your build doesn't have onboarding:
- Run `openclaw setup`, `openclaw channels login` in sequence, then start Gateway manually (`openclaw gateway`).
Bleeding Edge Workflow (Terminal Gateway)
Goal: Develop TypeScript Gateway with hot-reload while keeping macOS app UI connected to your Gateway.
0) (Optional) Run macOS App from Source
If you want to use the latest macOS app too:
./scripts/restart-mac.sh
1) Start Dev Gateway
pnpm install pnpm gateway:watch
`gateway:watch` runs gateway in watch mode, auto-reloading upon TypeScript changes.
2) Connect macOS App to Running Gateway
In **OpenClaw.app**:
- Connection Mode: Choose **Local**
The app will connect to the running gateway on the configured port.
3) Verify
- App's Gateway status should show **"Using existing gateway …"**
- Or use CLI:
openclaw health
Common Pitfalls
- **Port Mismatch:** Gateway WS defaults to `ws://127.0.0.1:18789`; app and CLI must use the same port.
- **Storage Locations:**
- Credentials: `~/.openclaw/credentials/`
- Sessions: `<code1>~/.openclaw/agents/<agentId>/sessions/</code1>`
- Logs: `/tmp/openclaw/`
Credential Storage Map
Refence for debugging auth or deciding back up content:
- **WhatsApp:** `<code1>~/.openclaw/credentials/whatsapp/<accountId>/creds.json</code1>`
- **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:** `<code1>~/.openclaw/credentials/<channel>-allowFrom.json</code1>`
- **Model Auth Profiles:** `<code1>~/.openclaw/agents/<agentId>/agent/auth-profiles.json</code1>`
- **Legacy OAuth Imports:** `~/.openclaw/credentials/oauth.json`
More details: See Security .
Updating (Without breaking your config)
- - Treat `~/.openclaw/workspace` and `~/.openclaw/` as "yours"; don't put personal prompts/config inside the `openclaw` repo.
- - Update source: `git pull` + `pnpm install` (when lockfile changes) + continue using `pnpm gateway:watch`.
Linux (systemd User Service)
Linux installs use systemd **user** services. By default, systemd kills user services upon logout/idle. Onboarding tries to enable lingering for you (may prompt for sudo). If not enabled, run:
sudo loginctl enable-linger $USER
For persistent or multi-user servers, consider **system** services instead of user services (no lingering required). See systemd notes in Gateway runbook .