Neura Market Logo

Advanced Setup and Development Workflows for OpenClaw

This page covers advanced setup methods for OpenClaw, including stable and bleeding edge paths, prerequisites, and tailoring strategies to keep customizations safe during updates.

Read this when

  • Setting up a new machine
  • You want "latest + greatest" without breaking your personal setup

Note

New to this? Begin with Getting Started. For onboarding specifics, refer to Onboarding (CLI).

TL;DR

Choose a setup method based on your update frequency and whether you prefer to manage the Gateway yourself:

  • Customization outside the repo: store your config and workspace in ~/.openclaw/openclaw.json and ~/.openclaw/workspace/ so repo changes leave them untouched.
  • Stable path (best for most users): install the macOS app, which runs the bundled Gateway.
  • Bleeding edge path (developers): run the Gateway yourself using pnpm gateway:watch, then have the macOS app connect in Local mode.

Prereqs (from source)

  • Node 24.15+ is recommended (Node 22 LTS, currently 22.22.3+, remains supported)
  • Source checkouts need pnpm. In dev mode, OpenClaw pulls bundled plugins from the extensions/* pnpm workspace packages, so root npm install does not build the entire source tree.
  • Docker (optional; only for containerized setup/e2e, see Docker)

Tailoring strategy (so updates do not hurt)

For "100% tailored to me" plus simple updates, keep your customizations in:

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

Initialize the config/workspace folders once, skipping the full onboarding wizard:

openclaw setup --baseline

No global install yet? Run it from this repo instead:

pnpm openclaw setup --baseline

(Bare openclaw setup, without --baseline, acts as an alias for openclaw onboard and launches the full interactive wizard.)

Run the Gateway from this repo

Once pnpm build is done, the packaged CLI runs directly:

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

Stable workflow (macOS app first)

  1. Install and launch OpenClaw.app (menu bar).
  2. Work through the onboarding/permissions checklist (TCC prompts).
  3. Confirm the Gateway is set to Local and active (the app handles it).
  4. Connect surfaces (e.g., WhatsApp):
openclaw channels login
  1. Verify everything:
openclaw health

If your build lacks onboarding:

  • Execute openclaw setup, then openclaw channels login, then launch the Gateway manually (openclaw gateway).

Bleeding edge workflow (Gateway in a terminal)

Aim: develop the TypeScript Gateway with hot reload while keeping the macOS app UI attached.

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

Want the macOS app on the bleeding edge too:

./scripts/restart-mac.sh

1) Start the dev Gateway

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

gateway:watch launches or restarts the Gateway watch process in a named tmux session (openclaw-gateway-watch-main) and auto-attaches from interactive terminals. Non-interactive shells stay detached and output tmux attach -t openclaw-gateway-watch-main; use OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch to keep an interactive run detached, or pnpm gateway:watch:raw for foreground watch mode. The watcher halts the active profile's installed Gateway service before taking over its configured/default port, so the service supervisor cannot replace the source process. The service remains installed; run pnpm openclaw gateway start once you finish watching. The tmux pane persists after a startup failure so another terminal or agent can attach or capture its logs. The watcher refreshes on relevant source, config, and bundled-plugin metadata changes. If the watched Gateway exits during startup, gateway:watch executes openclaw doctor --fix --non-interactive once and retries; set OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 to turn off that dev-only repair pass. pnpm gateway:watch does not rebuild dist/control-ui, so rerun pnpm ui:build after ui/ changes or use pnpm ui:dev while developing the Control UI.

2) Point the macOS app at your running Gateway

Inside OpenClaw.app:

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

3) Verify

  • In-app Gateway status should show "Using existing gateway …"
  • Or via CLI:
openclaw health

Common footguns

  • Wrong port: Gateway WS defaults to ws://127.0.0.1:18789; keep app and CLI on the same port.
  • State locations:
    • Channel/provider state: ~/.openclaw/credentials/
    • Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Sessions and transcripts: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
    • Legacy/archive session artifacts: ~/.openclaw/agents/<agentId>/sessions/
    • Logs: /tmp/openclaw/

Credential storage map

Use this when debugging auth or planning backups.

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram bot token: provided via config/env or channels.telegram.tokenFile (only regular files are accepted, symlinks are not)
  • Discord bot token: supplied through config/env or SecretRef (env/file/exec/store providers)
  • Slack tokens: from config/env (channels.slack.*)
  • Pairing allowlists:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (applies to the default account)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (used for 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 Further details can be found in Security.

Updating (without wrecking your setup)

  • Treat ~/.openclaw/workspace and ~/.openclaw/ as your personal data; avoid placing private prompts or configuration inside the openclaw repository.
  • To refresh the source: run git pull + pnpm install, then continue relying on pnpm gateway:watch.

Linux (systemd user service)

On Linux, installation relies on a systemd user service. By default, systemd terminates user services upon logout or idle, which stops the Gateway. The onboarding process attempts to activate lingering automatically, which may request sudo access. If lingering remains disabled, execute:

sudo loginctl enable-linger $USER

For servers that need to run continuously or serve multiple users, a system service is a better fit than a user service, as it does not require lingering. Refer to the Gateway runbook for systemd specifics.

913 words · updated Aug 17, 2026