OpenClaw Studio

OpenClaw Studio is a Next.js dashboard for managing OpenClaw agents via the OpenClaw Gateway (WebSocket).

How Studio Connects (Read This If You Use A Phone / Remote Host)

There are two separate connections involved:

1. Your browser -> Studio (HTTP) at http://<studio-host>:3000
2. Your browser -> OpenClaw Gateway (WebSocket) at the configured Gateway URL

Important consequences:

• 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

• Node.js 18+ (LTS recommended)
• OpenClaw Gateway running (local or remote)
• Tailscale (optional, recommended for tailnet access)

Quick start

Start the gateway (required)

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

Tailnet access via Tailscale Serve (recommended)

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

Install + run Studio (recommended)

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

Open http://localhost:3000 and set:

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

SSH tunneling (alternative)

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.

Install (manual)

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

Configuration

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)

Cron jobs in Agent Settings

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

Agent creation workflow

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

Exec approvals in chat

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

Troubleshooting

• 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).

Architecture

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