M
Openclaw
DocumentationGitHubDiscord
Browse docs

Docs / start / setup

Setup

Setup

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)

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

Tailoring strategy (so updates don’t hurt)

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

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):
text
openclaw channels login
  1. Sanity check:
text
openclaw health
  • Run openclaw setup, then openclaw channels login, then start the Gateway manually (openclaw gateway).

Bleeding edge workflow (Gateway in a terminal)

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

text
./scripts/restart-mac.sh

1) Start the dev Gateway

text
pnpm install
pnpm gateway:watch

2) Point the macOS app at your running Gateway

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

Credential storage map

  • WhatsApp: ~/.openclaw/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: ~/.openclaw/credentials/<channel>-allowFrom.json
  • Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Legacy OAuth import: ~/.openclaw/credentials/oauth.json More detail: Security.

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)

text
sudo loginctl enable-linger $USER

Related docs