clawwork-ai / clawwork-ai/ClawWork

Support connecting to remote OpenClaw servers (not just localhost)

Open
#98 3 comments 0 reactions 1 assignee Claimed by @samzong View on GitHub
area/gateway
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.