Neura Market Logo

Advanced Setup and Development Workflows for OpenClaw

Choose between stable or bleeding-edge setup methods for OpenClaw. Covers configuration placement, prerequisites for source builds, and strategies to keep customizations intact during updates.

Read this when

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

Note

First-time setup? Begin with the Getting Started guide. For CLI onboarding steps, refer to Onboarding (CLI).

TL;DR

Choose a setup method depending on your preferred update frequency and whether you host the Gateway yourself:

  • Customization stays outside the repo: place your config and workspace in ~/.openclaw/openclaw.json and ~/.openclaw/workspace/ so repo updates never affect them.
  • Stable method (best for most users): install the macOS application and let it manage the bundled Gateway.
  • Bleeding edge method (development): run the Gateway yourself through pnpm gateway:watch, then connect the macOS app in Local mode.

Prereqs (from source)

  • Node 24.15 or newer is recommended (Node 22 LTS, currently 22.22.3+, remains supported)
  • pnpm is needed for source checkouts. During development, OpenClaw loads bundled plugins from the extensions/* pnpm workspace packages, so root npm install does not set up the full source tree.
  • Docker is optional and only required for containerized setup or end-to-end testing. See Docker.

Tailoring strategy (so updates do not hurt)

For a fully personalized setup that stays easy to update, store your customizations in:

  • Config: ~/.openclaw/openclaw.json (uses JSON or JSON5-like format)
  • Workspace: ~/.openclaw/workspace (contains skills, prompts, memories; consider making it a private git repository)

Initialize the config and workspace folders once without launching the full onboarding wizard:

openclaw setup --baseline

Haven't installed globally? Run directly from this repository:

pnpm openclaw setup --baseline

Running plain openclaw setup (without --baseline) is the same as openclaw onboard and triggers the complete interactive wizard.

Run the Gateway from this repo

After running pnpm build, you can invoke the packaged CLI directly:

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

Stable workflow (macOS app first)

  1. Install and start OpenClaw.app (it lives in the menu bar).
  2. Go through the onboarding and permissions checklist (respond to TCC prompts).
  3. Confirm the Gateway is set to Local and active (the app handles this).
  4. Connect surfaces, for example WhatsApp:
openclaw channels login
  1. Verify everything works:
openclaw health

If your build lacks onboarding:

  • Execute openclaw setup, then openclaw channels login, and finally start the Gateway manually with openclaw gateway.

Bleeding edge workflow (Gateway in a terminal)

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

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

To also run the macOS app on the bleeding edge:

./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 inside a named tmux session (openclaw-gateway-watch-main) and automatically 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. Before taking over the configured or default port, the watcher stops the active profile's installed Gateway service, which prevents the service supervisor from replacing the source process. The service remains installed; run pnpm openclaw gateway start when you finish watching. The tmux pane stays available even after a startup failure so another terminal or agent can attach or capture its logs. The watcher reloads on changes to relevant source files, config, and bundled-plugin metadata. If the watched Gateway exits during startup, gateway:watch runs openclaw doctor --fix --non-interactive once and retries; set OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 to disable 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:

  • Set Connection Mode to Local The app will connect to the running gateway on the configured port.

3) Verify

  • The in-app Gateway status should show "Using existing gateway …"
  • Or check via the CLI:
openclaw health

Common footguns

  • Port mismatch: The Gateway WebSocket defaults to ws://127.0.0.1:18789; ensure the app and CLI use the same port.
  • State storage locations:
    • Channel and provider state: ~/.openclaw/credentials/
    • Model authentication profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Sessions and transcripts: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
    • Legacy or archived session artifacts: ~/.openclaw/agents/<agentId>/sessions/
    • Logs: /tmp/openclaw/

Credential storage map

Refer to this when debugging authentication or deciding what to back up.

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram bot token: set via config/env or channels.telegram.tokenFile (only regular files allowed; symlinks are not accepted)
  • Discord bot token: provided through config/env or a SecretRef (env, file, or exec providers)
  • Slack tokens: supplied in config/env (channels.slack.*)
  • Pairing allowlists:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (primary account)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (secondary accounts)
  • Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Optional file-backed secrets payload: ~/.openclaw/secrets.json
  • Legacy OAuth import: ~/.openclaw/credentials/oauth.json Further details can be found at Security.

Updating (without wrecking your setup)

  • Leave ~/.openclaw/workspace and ~/.openclaw/ as "your stuff"; avoid placing personal prompts or configuration inside the openclaw repository.
  • To update the source: run git pull and pnpm install, then continue using pnpm gateway:watch.

Linux (systemd user service)

On Linux, a systemd user service is used. By default, systemd stops user services when you log out or the session is idle, which terminates the Gateway. The onboarding process tries to enable lingering for you (you may be asked for sudo). If lingering remains disabled, execute:

sudo loginctl enable-linger $USER

For servers that run continuously or have multiple users, a system service is recommended instead of a user service (no lingering required). Check the Gateway runbook for systemd details.