openclaw-dashboard-swiftbar

中文

A SwiftBar plugin that opens a remote OpenClaw dashboard through a local SSH tunnel and auto-fetches the dashboard token.

OpenClaw operators often need one small thing on macOS: click once in the menu bar and land in the remote dashboard without manually starting a tunnel, checking the port, or copying a token. This plugin is built for that workflow.

Why This Exists

Existing menu bar plugins usually stop at generic SSH access or simple tunnel toggling. This project is narrower and more practical for OpenClaw:

• it forwards the dashboard port
• it fetches the token from the remote host
• it opens the local dashboard URL directly
• it avoids the common non-interactive SSH PATH failure on Homebrew-based macOS hosts

If you run OpenClaw on another Mac mini, VPS, or homelab box and want the dashboard one click away, this is the intended use case.

Highlights

• One-click OpenClaw dashboard access from the macOS menu bar
• Auto-start and stop for the SSH local port forward
• Automatic token fetch before opening the dashboard
• Local port conflict detection with process name and PID in the menu
• SSH startup errors surfaced directly in SwiftBar instead of a generic failure message
• Fix for the common non-interactive SSH PATH problem on macOS/Homebrew installs
• Self-contained menu bar icon with no external image file dependency

Screenshot

What It Does

• Shows tunnel status in the macOS menu bar via SwiftBar.
• Starts and stops an SSH local port forward.
• Opens the OpenClaw dashboard through the local tunnel.
• Fetches the dashboard token from the remote host before opening the UI.
• Uses a remote login shell so openclaw, node, and Homebrew paths resolve correctly.

Requirements

• macOS
• SwiftBar
• SSH access to the remote machine
• openclaw installed on the remote machine
• A login shell on the remote machine that loads the correct PATH

Recommended Network Setup

The recommended setup for this plugin is to keep your local Mac and remote OpenClaw host connected through Tailscale, then establish SSH over that private network.

The typical access path is:

SwiftBar -> SSH over Tailscale -> local port forward -> remote 127.0.0.1:18789 -> OpenClaw Dashboard

In practice this means:

• OPENCLAW_HOST will often be the remote host's Tailscale IP or a hostname that resolves to it
• the plugin depends on SSH reachability before it can establish the tunnel
• Tailscale is recommended because it keeps the Gateway private while making remote SSH access straightforward

Quick checks:

tailscale status
tailscale ping <remote-tailscale-ip>
ssh <user>@<remote-tailscale-ip>

Repository Layout

plugin/openclaw-tunnel.3s.sh
examples/openclaw-tunnel.env.example
scripts/install.sh

Install

cd ~/Workspace/openclaw-dashboard-swiftbar
./scripts/install.sh

The installer will:

• symlink the plugin into ~/.swiftbar/openclaw-tunnel.3s.sh
• create ~/.config/openclaw-tunnel-swiftbar.env if it does not exist

SwiftBar Plugin Folder

SwiftBar does not require a single hard-coded plugin directory. On first launch, it asks you to choose a Plugin Folder, and then tries to import every file inside that folder as a plugin.

For this project, the installer uses:

~/.swiftbar

That is a common local choice, but it is not the only valid location. If your SwiftBar instance uses a different plugin folder, set SWIFTBAR_PLUGIN_DIR before running the installer:

SWIFTBAR_PLUGIN_DIR="/path/to/your/swiftbar-plugins" ./scripts/install.sh

Important behavior from SwiftBar:

• nested folders are traversed, including symlinks
• hidden folders are ignored
• non-plugin files inside the plugin folder may still be imported unless excluded

Because of that, this project avoids runtime image files inside ~/.swiftbar and keeps the menu bar icon embedded in the plugin itself.

Configure

Edit ~/.config/openclaw-tunnel-swiftbar.env:

OPENCLAW_HOST="user@your-remote-host"
OPENCLAW_LOCAL_PORT="18789"
OPENCLAW_REMOTE_HOST="127.0.0.1"
OPENCLAW_REMOTE_PORT="18789"

Optional settings:

• OPENCLAW_REMOTE_SHELL
• OPENCLAW_NOTIFY_TITLE

Default behavior:

• local port 18789
• remote host 127.0.0.1
• remote port 18789
• remote shell zsh -lic

Menu states:

• Running
• Stopped
• Local Port Busy
• Not configured

Positioning

This project sits between two existing categories:

• more focused than generic SSH tunnel menu bar plugins
• much lighter than full OpenClaw desktop companion apps

The goal is not to replace a full GUI manager. The goal is to make remote dashboard access frictionless.

Relationship To OpenClaw Remote Access

This plugin follows OpenClaw's recommended remote access model: keep the Gateway bound to loopback and reach it through an SSH tunnel instead of exposing it directly on the network.

In practice, this plugin does three things:

• forwards the remote Gateway port to local 127.0.0.1
• asks the remote host for the dashboard URL and token
• opens the local forwarded dashboard URL in the browser

That makes it a lightweight operator tool for dashboard access, not a full replacement for OpenClaw's broader remote workflow.

Compared with the official options:

• lighter than the macOS app's full "Remote over SSH" experience
• more dashboard-focused than generic SSH tunnel setups
• less complete than configuring persistent remote access for CLI and app usage

This project is a good fit when your main goal is simple, one-click access to a remote Dashboard running on another Mac, VPS, or homelab machine.

It is a weaker fit if you want a full remote client workflow including broader health checks, chat, or richer remote session management.

Why Token Fetching Fails In SSH

The common failure mode is not OpenClaw itself. It is usually the remote non-interactive SSH environment:

• ssh host 'openclaw dashboard --no-open' often runs with a minimal PATH
• Homebrew binaries such as openclaw may live in /opt/homebrew/bin
• openclaw may depend on node, which also fails if the login shell is not loaded

This plugin avoids that by running the token fetch through a remote login shell, defaulting to:

zsh -lic "openclaw dashboard --no-open"

Troubleshooting

If the menu action opens the dashboard without logging in:

• verify openclaw dashboard --no-open works on the remote host
• verify the remote login shell loads Homebrew and node
• verify OPENCLAW_HOST points to the correct machine

If the tunnel shows as stopped unexpectedly:

• make sure SSH key-based login works without prompts
• confirm the local port is free
• confirm the remote dashboard is listening on the configured host and port

If SwiftBar shows Local Port Busy:

• the plugin found another process already listening on the local dashboard port
• the menu will show the listener process name and PID when available
• stop the conflicting process or change OPENCLAW_LOCAL_PORT if the conflict is intentional

If SwiftBar shows SSH Error: ...:

• the SSH command itself failed before the tunnel could come up
• the menu now keeps the last startup error, such as timeout, auth failure, or host unreachable
• verify the remote machine is reachable and that ssh OPENCLAW_HOST succeeds outside SwiftBar

If Tailscale shows the remote node as online but SSH still times out:

• the remote machine may be idle, asleep, or only partially reachable
• the connection may have degraded to relay-only or otherwise unstable connectivity
• verify the remote host responds to tailscale ping and that sshd is healthy

If SwiftBar shows a warning icon:

• keep non-plugin assets outside ~/.swiftbar
• use Refresh All or restart SwiftBar after replacing a plugin

Development

Local validation:

zsh -n plugin/openclaw-tunnel.3s.sh
zsh -n scripts/install.sh
plugin/openclaw-tunnel.3s.sh

License

MIT