macOS app

The macOS app is the menu‑bar companion for OpenClaw. It owns permissions, manages/attaches to the Gateway locally (launchd or manual), and exposes macOS capabilities to the agent as a node.

What it does

• Shows native notifications and status in the menu bar.
• Owns TCC prompts (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript).
• Runs or connects to the Gateway (local or remote).
• Exposes macOS‑only tools (Canvas, Camera, Screen Recording,
  text

  Copy

  system.run
  ).
• Starts the local node host service in remote mode (launchd), and stops it in local mode.
• Optionally hosts PeekabooBridge for UI automation.
• Installs the global CLI (
  text

  Copy

  openclaw
  ) on request via npm, pnpm, or bun (the app prefers npm, then pnpm, then bun; Node remains the recommended Gateway runtime).

Local vs remote mode

• Local (default): the app attaches to a running local Gateway if present; otherwise it enables the launchd service via
  text

  Copy

  openclaw gateway install
  .
• Remote: the app connects to a Gateway over SSH/Tailscale and never starts a local process. The app starts the local node host service so the remote Gateway can reach this Mac. The app does not spawn the Gateway as a child process. Gateway discovery now prefers Tailscale MagicDNS names over raw tailnet IPs, so the Mac app recovers more reliably when tailnet IPs change.

Launchd control

The app manages a per‑user LaunchAgent labeled

(or when using /; legacy still unloads).

bash
Copy
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

Replace the label with

when running a named profile.

If the LaunchAgent isn’t installed, enable it from the app or run

.

Node capabilities (mac)

The macOS app presents itself as a node. Common commands:

• Canvas:
  text

  Copy

  canvas.present
  ,
  text

  Copy

  canvas.navigate
  ,
  text

  Copy

  canvas.eval
  ,
  text

  Copy

  canvas.snapshot
  ,
  text

  Copy

  canvas.a2ui.*
• Camera:
  text

  Copy

  camera.snap
  ,
  text

  Copy

  camera.clip
• Screen:
  text

  Copy

  screen.snapshot
  ,
  text

  Copy

  screen.record
• System:
  text

  Copy

  system.run
  ,
  text

  Copy

  system.notify

The node reports a

map so agents can decide what’s allowed.

Node service + app IPC:

• When the headless node host service is running (remote mode), it connects to the Gateway WS as a node.
• text

  Copy

  system.run
  executes in the macOS app (UI/TCC context) over a local Unix socket; prompts + output stay in-app.

Diagram (SCI):

text
Copy
Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

Exec approvals (system.run)

is controlled by Exec approvals in the macOS app (Settings → Exec approvals). Security + ask + allowlist are stored locally on the Mac in:

text
Copy
~/.openclaw/exec-approvals.json

Example:

json
Copy
{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

Notes:

• text

  Copy

  allowlist
  entries are glob patterns for resolved binary paths, or bare command names for PATH-invoked commands.
• Raw shell command text that contains shell control or expansion syntax (
  text

  Copy

  &&
  ,
  text

  Copy

  ||
  ,
  text

  Copy

  ;
  ,
  text

  Copy

  |
  ,
  text

  Copy

  `
  ,
  text

  Copy

  $
  ,
  text

  Copy

  <
  ,
  text

  Copy

  >
  ,
  text

  Copy

  (
  ,
  text

  Copy

  )
  ) is treated as an allowlist miss and requires explicit approval (or allowlisting the shell binary).
• Choosing “Always Allow” in the prompt adds that command to the allowlist.
• text

  Copy

  system.run
  environment overrides are filtered (drops
  text

  Copy

  PATH
  ,
  text

  Copy

  DYLD_*
  ,
  text

  Copy

  LD_*
  ,
  text

  Copy

  NODE_OPTIONS
  ,
  text

  Copy

  PYTHON*
  ,
  text

  Copy

  PERL*
  ,
  text

  Copy

  RUBYOPT
  ,
  text

  Copy

  SHELLOPTS
  ,
  text

  Copy

  PS4
  ) and then merged with the app’s environment.
• For shell wrappers (
  text

  Copy

  bash|sh|zsh ... -c/-lc
  ), request-scoped environment overrides are reduced to a small explicit allowlist (
  text

  Copy

  TERM
  ,
  text

  Copy

  LANG
  ,
  text

  Copy

  LC_*
  ,
  text

  Copy

  COLORTERM
  ,
  text

  Copy

  NO_COLOR
  ,
  text

  Copy

  FORCE_COLOR
  ).
• For allow-always decisions in allowlist mode, known dispatch wrappers (
  text

  Copy

  env
  ,
  text

  Copy

  nice
  ,
  text

  Copy

  nohup
  ,
  text

  Copy

  stdbuf
  ,
  text

  Copy

  timeout
  ) persist inner executable paths instead of wrapper paths. If unwrapping is not safe, no allowlist entry is persisted automatically.

Deep links

The app registers the

URL scheme for local actions.

text

Copy

openclaw://agent

Triggers a Gateway

request.

bash
Copy
open 'openclaw://agent?message=Hello%20from%20deep%20link'

Query parameters:

• text

  Copy

  message
  (required)
• text

  Copy

  sessionKey
  (optional)
• text

  Copy

  thinking
  (optional)
• text

  Copy

  deliver
  /
  text

  Copy

  to
  /
  text

  Copy

  channel
  (optional)
• text

  Copy

  timeoutSeconds
  (optional)
• text

  Copy

  key
  (optional unattended mode key)

Safety:

• Without
  text

  Copy

  key
  , the app prompts for confirmation.
• Without
  text

  Copy

  key
  , the app enforces a short message limit for the confirmation prompt and ignores
  text

  Copy

  deliver
  /
  text

  Copy

  to
  /
  text

  Copy

  channel
  .
• With a valid
  text

  Copy

  key
  , the run is unattended (intended for personal automations).

Onboarding flow (typical)

1. Install and launch OpenClaw.app.
2. Complete the permissions checklist (TCC prompts).
3. Ensure Local mode is active and the Gateway is running.
4. Install the CLI if you want terminal access.

State dir placement (macOS)

Avoid putting your OpenClaw state dir in iCloud or other cloud-synced folders. Sync-backed paths can add latency and occasionally cause file-lock/sync races for sessions and credentials.

Prefer a local non-synced state path such as:

bash
Copy
OPENCLAW_STATE_DIR=~/.openclaw

If

detects state under:

• text

  Copy

  ~/Library/Mobile Documents/com~apple~CloudDocs/...
• text

  Copy

  ~/Library/CloudStorage/...

it will warn and recommend moving back to a local path.

Build & dev workflow (native)

• text

  Copy

  cd apps/macos && swift build
• text

  Copy

  swift run OpenClaw
  (or Xcode)
• Package app:
  text

  Copy

  scripts/package-mac-app.sh

Debug gateway connectivity (macOS CLI)

Use the debug CLI to exercise the same Gateway WebSocket handshake and discovery logic that the macOS app uses, without launching the app.

bash
Copy
cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

Connect options:

• text

  Copy

  --url <ws://host:port>
  : override config
• text

  Copy

  --mode <local|remote>
  : resolve from config (default: config or local)
• text

  Copy

  --probe
  : force a fresh health probe
• text

  Copy

  --timeout <ms>
  : request timeout (default:
  text

  Copy

  15000
  )
• text

  Copy

  --json
  : structured output for diffing

Discovery options:

• text

  Copy

  --include-local
  : include gateways that would be filtered as “local”
• text

  Copy

  --timeout <ms>
  : overall discovery window (default:
  text

  Copy

  2000
  )
• text

  Copy

  --json
  : structured output for diffing

Remote connection plumbing (SSH tunnels)

When the macOS app runs in Remote mode, it opens an SSH tunnel so local UI components can talk to a remote Gateway as if it were on localhost.

Control tunnel (Gateway WebSocket port)

• Purpose: health checks, status, Web Chat, config, and other control-plane calls.
• Local port: the Gateway port (default
  text

  Copy

  18789
  ), always stable.
• Remote port: the same Gateway port on the remote host.
• Behavior: no random local port; the app reuses an existing healthy tunnel or restarts it if needed.
• SSH shape:
  text

  Copy

  ssh -N -L <local>:127.0.0.1:<remote>
  with BatchMode + ExitOnForwardFailure + keepalive options.
• IP reporting: the SSH tunnel uses loopback, so the gateway will see the node IP as
  text

  Copy

  127.0.0.1
  . Use Direct (ws/wss) transport if you want the real client IP to appear (see macOS remote access).

For setup steps, see macOS remote access. For protocol details, see Gateway protocol.

Related docs

• Gateway runbook
• Gateway (macOS)
• macOS permissions
• Canvas