clawwork-ai / clawwork-ai/ClawWork
Support connecting to remote OpenClaw servers (not just localhost)
- Dominant language
- TypeScript
- Stars
- 532
- Forks
- 75
- Avg merge
- 5h 31m
- Merged PRs (30d)
- 1
Description
## Problem
ClawWork currently defaults to connecting to a local OpenClaw Gateway at `ws://127.0.0.1:18789`. While the Settings page allows changing the Gateway URL after initial setup, there are several gaps that make connecting to a remote OpenClaw server inconvenient or unclear:
1. **Setup wizard only asks for workspace path** — the initial Setup screen does not include a Gateway URL field, so first-time users connecting to a remote server must complete setup first, then go to Settings to change the URL.
2. **No documentation** — there is no guide explaining how to configure ClawWork for a remote OpenClaw server, including considerations like network requirements, authentication tokens, and WebSocket URL format.
3. **No WSS (TLS) guidance** — for remote deployments, `wss://` should be used instead of `ws://`. There's no guidance or validation around this.
## Proposed Changes
### 1. Setup Wizard: Add Gateway URL Configuration
Add an optional "Advanced" or "Connection" section to the Setup wizard (`layouts/Setup/index.tsx`) that lets users configure:
- **Gateway URL** (default: `ws://127.0.0.1:18789`)
- **Bootstrap Token**
This way, users connecting to a remote server can configure everything during initial setup.
### 2. Documentation
Create a doc (e.g., `docs/remote-connection.md` or a section in README) covering:
- **Prerequisites**: What the remote OpenClaw server needs (Gateway port accessible, firewall rules)
- **URL format**: `ws://:` for local/dev, `wss://:` for production with TLS
- **Authentication**: How to obtain and configure the bootstrap token
- **Network considerations**: Latency, VPN, reverse proxy setups (e.g., nginx/Caddy with WebSocket upgrade)
- **Artifact file transfer limitation**: The current MVP assumes co-located deployment — artifact files are transferred via local filesystem paths. This will NOT work for remote servers. This limitation should be clearly documented.
- **Configuration methods**: Setup wizard, Settings page, or config file (`clawwork-config.json`)
### 3. Validation & UX Improvements (nice-to-have)
- Add a "Test Connection" button in both Setup and Settings
- Show connection status indicator (connected / disconnected / connecting) more prominently
- Warn users if they use `ws://` with a non-localhost host (suggest `wss://`)
## Current Code References
- Default URL fallback: `packages/desktop/src/main/ws/index.ts` — `cfg?.gatewayUrl ?? 'ws://127.0.0.1:${GATEWAY_WS_PORT}'`
- Settings UI: `packages/desktop/src/renderer/layouts/Settings/index.tsx` — already has Gateway URL + Token fields
- Setup wizard: `packages/desktop/src/renderer/layouts/Setup/index.tsx` — only has workspace path
- Config persistence: `packages/desktop/src/main/workspace/config.ts` — `gatewayUrl` field exists in `AppConfig`
- Reconnect on config change: `packages/desktop/src/main/ipc/settings-handlers.ts` — calls `gateway.updateConfig()`
## Acceptance Criteria
- [ ] Setup wizard allows configuring Gateway URL and token (with sensible defaults)
- [ ] Documentation exists for connecting to a remote OpenClaw server
- [ ] Artifact file transfer limitation for remote servers is clearly documented
Contributor guide
Assessment
This issue has not been assessed yet.