Setup

TL;DR

Pick a setup workflow based on how often you want updates and whether you want to run the Gateway yourself:

• Tailoring lives outside the repo: keep your config and workspace in
  text

  Copy

  ~/.openclaw/openclaw.json
  and
  text

  Copy

  ~/.openclaw/workspace/
  so repo updates don't touch them.
• Stable workflow (recommended for most): install the macOS app and let it run the bundled Gateway.
• Bleeding edge workflow (dev): run the Gateway yourself via
  text

  Copy

  pnpm gateway:watch
  , then let the macOS app attach in Local mode.

Prereqs (from source)

• Node 24 recommended (Node 22 LTS, currently
  text

  Copy

  22.14+
  , still supported)
• text

  Copy

  pnpm
  preferred (or Bun if you intentionally use the Bun workflow)
• Docker (optional; only for containerized setup/e2e — see Docker)

Tailoring strategy (so updates do not hurt)

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

• Config:
  text

  Copy

  ~/.openclaw/openclaw.json
  (JSON/JSON5-ish)
• Workspace:
  text

  Copy

  ~/.openclaw/workspace
  (skills, prompts, memories; make it a private git repo)

Bootstrap once:

bash
Copy
openclaw setup

From inside this repo, use the local CLI entry:

bash
Copy
openclaw setup

If you don’t have a global install yet, run it via

(or if you are using the Bun workflow).

Run the Gateway from this repo

After

, you can run the packaged CLI directly:

bash
Copy
node openclaw.mjs gateway --port 18789 --verbose

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):

bash
Copy
openclaw channels login

5. Sanity check:

bash
Copy
openclaw health

If onboarding is not available in your build:

• Run
  text

  Copy

  openclaw setup
  , then
  text

  Copy

  openclaw channels login
  , then start the Gateway manually (
  text

  Copy

  openclaw 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
Copy
./scripts/restart-mac.sh

1) Start the dev Gateway

bash
Copy
pnpm install
# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup
pnpm gateway:watch

starts or restarts the Gateway watch process in a named tmux session and auto-attaches from interactive terminals. Non-interactive shells stay detached and print ; use to keep an interactive run detached, or for foreground watch mode. The watcher reloads on relevant source, config, and bundled-plugin metadata changes. is the one-time local config/workspace initialization step for a fresh checkout. does not rebuild , so rerun after changes or use while developing the Control UI.

If you are intentionally using the Bun workflow, the equivalent commands are:

bash
Copy
bun install
# First run only (or after resetting local OpenClaw config/workspace)
bun run openclaw setup
bun run gateway:watch

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

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

bash
Copy
openclaw health

Common footguns

• Wrong port: Gateway WS defaults to
  text

  Copy

  ws://127.0.0.1:18789
  ; keep app + CLI on the same port.
• Where state lives:
  • Channel/provider state:
    text

    Copy

    ~/.openclaw/credentials/
  • Model auth profiles:
    text

    Copy

    ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Sessions:
    text

    Copy

    ~/.openclaw/agents/<agentId>/sessions/
  • Logs:
    text

    Copy

    /tmp/openclaw/

Credential storage map

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

• WhatsApp:
  text

  Copy

  ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Telegram bot token: config/env or
  text

  Copy

  channels.telegram.tokenFile
  (regular file only; symlinks rejected)
• Discord bot token: config/env or SecretRef (env/file/exec providers)
• Slack tokens: config/env (
  text

  Copy

  channels.slack.*
  )
• Pairing allowlists:
  • text

    Copy

    ~/.openclaw/credentials/<channel>-allowFrom.json
    (default account)
  • text

    Copy

    ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json
    (non-default accounts)
• Model auth profiles:
  text

  Copy

  ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• File-backed secrets payload (optional):
  text

  Copy

  ~/.openclaw/secrets.json
• Legacy OAuth import:
  text

  Copy

  ~/.openclaw/credentials/oauth.json
  More detail: Security.

Updating (without wrecking your setup)

• Keep
  text

  Copy

  ~/.openclaw/workspace
  and
  text

  Copy

  ~/.openclaw/
  as “your stuff”; don’t put personal prompts/config into the
  text

  Copy

  openclaw
  repo.
• Updating source:
  text

  Copy

  git pull
  + your chosen package-manager install step (
  text

  Copy

  pnpm install
  by default;
  text

  Copy

  bun install
  for Bun workflow) + keep using the matching
  text

  Copy

  gateway:watch
  command.

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
Copy
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.

Related docs

• Gateway runbook (flags, supervision, ports)
• Gateway configuration (config schema + examples)
• Discord and Telegram (reply tags + replyToMode settings)
• OpenClaw assistant setup
• macOS app (gateway lifecycle)