The Gateway connection is made from the browser, not from the machine running next dev.
ws://localhost:18789 (or ws://127.0.0.1:18789) means “connect to a gateway on the same device as the browser”.
- If you open Studio on your phone, localhost and 127.0.0.1 are your phone, not your laptop/server.
Studio persists the Gateway URL/token under ~/.openclaw/openclaw-studio/settings.json. Once set in the UI, this will be used on future runs and will override the default NEXT_PUBLIC_GATEWAY_URL.
If Studio is served over https://, the Gateway URL must be wss://... (browsers block ws:// from https:// pages).

Requirements

Quick start

If you don't already have OpenClaw installed:

npm install -g openclaw@latest
openclaw onboard --install-daemon

Start a gateway (foreground):

openclaw gateway run --bind loopback --port 18789 --verbose

Helpful checks:

openclaw gateway probe
openclaw config get gateway.auth.token

Most people keep the gateway bound to loopback and use Tailscale Serve on the gateway host.

On the gateway host:

openclaw config set gateway.tailscale.mode serve
openclaw config set gateway.auth.mode token

Restart your gateway. Then:

tailscale serve status

Take the HTTPS URL from tailscale serve status and convert it to a WebSocket URL for Studio:

https://gateway-host.your-tailnet.ts.net -> wss://gateway-host.your-tailnet.ts.net

npx -y openclaw-studio@latest
cd openclaw-studio
npm run dev

Token: openclaw config get gateway.auth.token
Gateway URL: wss://gateway-host.your-tailnet.ts.net (tailnet via tailscale serve)
Gateway URL: ws://localhost:18789 (local gateway)
Gateway URL: ws://your-host:18789 (direct remote port, no tailscale serve)

Notes:

If Studio is served over https://, the gateway URL must be wss://... (browsers block ws:// from https:// pages).
If you browse Studio from another device (phone/tablet), do not use ws://localhost:18789 unless the gateway is running on that device. Use a reachable host (LAN IP/DNS), wss://... via Tailscale Serve, or an SSH tunnel.

If you prefer SSH tunneling to a remote host:

ssh -L 18789:127.0.0.1:18789 user@your-host

Then connect Studio to ws://localhost:18789.

git clone https://github.com/grp06/openclaw-studio.git
cd openclaw-studio
npm install
npm run dev

Paths and key settings:

OpenClaw config: ~/.openclaw/openclaw.json (or OPENCLAW_CONFIG_PATH / OPENCLAW_STATE_DIR)
Studio settings: ~/.openclaw/openclaw-studio/settings.json
Default gateway URL: ws://localhost:18789 (override via Studio Settings or NEXT_PUBLIC_GATEWAY_URL)

Open an agent and go to Settings -> Cron jobs.
If no jobs exist, use the empty-state Create button.
If jobs already exist, use the header Create button.
The modal is agent-scoped and walks through template selection, task text, schedule, and review.
Submitting creates the job via gateway cron.add and refreshes that same agent's cron list.

Click New Agent in the fleet sidebar.
Pick a Preset bundle (for example Research Analyst, PR Engineer, Autonomous Engineer, Growth Operator, Coordinator, or Blank).
Each preset card shows capability chips and risk level (Exec, Internet, File tools, Sandbox, Heartbeat, plus caveats when relevant).
Optionally override the Control level (Conservative, Balanced, or Autopilot).
Add optional customization (agent name, first task, notes, and advanced control toggles).
Review the behavior summary, then create.
Studio compiles this setup into per-agent artifacts only:
- per-agent sandbox/tool overrides in agents.list[]
- per-agent exec approval policy in exec-approvals.json
- core agent files (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, HEARTBEAT.md, MEMORY.md)
- additive tool policy (tools.alsoAllow) so preset selections do not remove base profile tools
If setup fails after agents.create, Studio keeps the created agent, stores a pending setup in tab-scoped session storage keyed by gateway URL, and shows Retry setup / Discard pending setup in chat.
Auto-retry is deduplicated across reconnect and restart flows, so one pending setup is applied at most once at a time per agent.
Studio does not modify global defaults during creation.

When a run requires exec approval, chat shows an Exec approval required card with:
- command preview
- host and cwd
- expiration timestamp
Resolve directly in chat with:
- Allow once
- Always allow
- Deny
The fleet row displays Needs approval while approvals are pending for that agent.
Expired approvals are pruned automatically, so stale cards and stale Needs approval badges clear without a manual resolve event.

Missing config: Run openclaw onboard or set OPENCLAW_CONFIG_PATH
Gateway unreachable: Confirm the gateway is running and NEXT_PUBLIC_GATEWAY_URL matches
Auth errors: Studio currently prompts for a token. Check gateway.auth.mode is token and gateway.auth.token is set in openclaw.json (or run openclaw config get gateway.auth.token).
Secure-context connect errors (for example INVALID_REQUEST ... control ui requires HTTPS or localhost (secure context)): use ws://localhost:18789 for local gateways instead of ws://127.0.0.1:18789, or use wss://... when connecting over HTTPS.
UI loads but no agents show up (common when browsing from a phone):
- Check the Gateway URL shown in Studio. If it is ws://localhost:18789, that will only work when browsing Studio on the same machine running the gateway (or via an SSH tunnel).
- If you set a Gateway URL once, it is persisted in ~/.openclaw/openclaw-studio/settings.json. Update it in the UI (or delete/reset the file) if you moved hosts.
Still stuck: Run npx -y openclaw-studio@latest doctor --check (and --fix --force-settings to safely rewrite Studio settings).

See ARCHITECTURE.md for details on modules and data flow.