Skip to content
OpenClaw Docs

Setup

Setup

Section titled “Setup”

TL;DR

Section titled “TL;DR”
  • Tailoring lives outside the repo: ~/.openclaw/workspace (workspace) + ~/.openclaw/openclaw.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)

Section titled “Prereqs (from source)”
  • Node 24 recommended (Node 22 LTS, currently 22.14+, still supported)
  • pnpm
  • Docker (optional; only for containerized setup/e2e — see Docker)

Tailoring strategy (so updates do not hurt)

Section titled “Tailoring strategy (so updates do not hurt)”

If you want “100% tailored to me” and easy updates, keep your customization in:

  • Config: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
  • Workspace: ~/.openclaw/workspace (skills, prompts, memories; make it a private git repo)

Bootstrap once:

Terminal window
openclaw setup

From inside this repo, use the local CLI entry:

Terminal window
openclaw setup

If you don’t have a global install yet, run it via pnpm openclaw setup.

Run the Gateway from this repo

Section titled “Run the Gateway from this repo”

After pnpm build, you can run the packaged CLI directly:

Terminal window
node openclaw.mjs gateway --port 18789 --verbose

Stable workflow (macOS app first)

Section titled “Stable workflow (macOS app first)”
  1. Install + launch OpenClaw.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):
Terminal window
openclaw channels login
  1. Sanity check:
Terminal window
openclaw health

If onboarding is not available in your build:

  • Run openclaw setup, then openclaw channels login, then start the Gateway manually (openclaw gateway).

Bleeding edge workflow (Gateway in a terminal)

Section titled “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

Section titled “0) (Optional) Run the macOS app from source too”

If you also want the macOS app on the bleeding edge:

Terminal window
./scripts/restart-mac.sh

1) Start the dev Gateway

Section titled “1) Start the dev Gateway”
Terminal window
pnpm install
pnpm gateway:watch

gateway:watch runs the gateway in watch mode and reloads on relevant source, config, and bundled-plugin metadata changes.

2) Point the macOS app at your running Gateway

Section titled “2) Point the macOS app at your running Gateway”

In OpenClaw.app:

  • Connection Mode: Local The app will attach to the running gateway on the configured port.

3) Verify

Section titled “3) Verify”
  • In-app Gateway status should read “Using existing gateway …”
  • Or via CLI:
Terminal window
openclaw health

Common footguns

Section titled “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: ~/.openclaw/credentials/
    • Sessions: ~/.openclaw/agents/<agentId>/sessions/
    • Logs: /tmp/openclaw/

Credential storage map

Section titled “Credential storage map”

Use this when debugging auth or deciding what to back up:

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram bot token: config/env or channels.telegram.tokenFile (regular file only; symlinks rejected)
  • Discord bot token: config/env or SecretRef (env/file/exec providers)
  • Slack tokens: config/env (channels.slack.*)
  • Pairing allowlists:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (default account)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (non-default accounts)
  • Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • File-backed secrets payload (optional): ~/.openclaw/secrets.json
  • Legacy OAuth import: ~/.openclaw/credentials/oauth.json More detail: Security.

Updating (without wrecking your setup)

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

Linux (systemd user service)

Section titled “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:

Terminal window
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 for the systemd notes.

Section titled “Related docs”