The Clawdbot macOS companion app provides menu bar integration, permission management, and native macOS capabilities for your AI assistant.

Clawdbot macOS Companion Overview

The Clawdbot macOS app is the menu-bar companion for Clawdbot. 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, system.run)
Manages the local node host service
Installs the global CLI (clawdbot) via npm/pnpm on request

Local vs Remote Mode

Mode	Description
Local (default)	App attaches to running local Gateway; enables launchd service if needed
Remote	App connects to Gateway over SSH/Tailscale; starts local node host service

The app does not spawn the Gateway as a child process.

Launchd Control

The app manages a per-user LaunchAgent labeled bot.molt.gateway (or bot.molt.<profile> when using --profile).

# Restart the gateway
launchctl kickstart -k gui/$UID/bot.molt.gateway

# Stop the gateway
launchctl bootout gui/$UID/bot.molt.gateway

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

clawdbot gateway install

Node Capabilities (macOS)

The macOS app presents itself as a node with these capabilities:

Category	Commands
Canvas	`canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`
Camera	`camera.snap`, `camera.clip`
Screen	`screen.record`
System	`system.run`, `system.notify`

The node reports a permissions map so agents can decide what's allowed.

Exec Approvals (system.run)

system.run is controlled by Exec approvals in the macOS app (Settings → Exec approvals).

Configuration stored in:

~/.clawdbot/exec-approvals.json

Example configuration:

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

Notes:

Allowlist entries are glob patterns for resolved binary paths
Choosing "Always Allow" in the prompt adds that command to the allowlist

Deep Links

The app registers the clawdbot:// URL scheme for local actions.

clawdbot://agent

Triggers a Gateway agent request:

open 'clawdbot://agent?message=Hello%20from%20deep%20link'

Query parameters:

Parameter	Description
`message`	Required - the message to send
`sessionKey`	Optional - session identifier
`thinking`	Optional - enable thinking mode
`deliver` / `to` / `channel`	Optional - delivery target
`timeoutSeconds`	Optional - request timeout
`key`	Optional - unattended mode key

Safety: Without key, the app prompts for confirmation.

Onboarding Flow

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

Build & Dev Workflow

cd apps/macos && swift build
swift run Clawdbot  # or use Xcode

# Package app
scripts/package-mac-app.sh

Debug Gateway Connectivity

Use the debug CLI to test Gateway WebSocket handshake:

cd apps/macos
swift run clawdbot-mac connect --json
swift run clawdbot-mac discover --timeout 3000 --json

Connect options:

Option	Description
`--url <ws://host:port>`	Override config
`--mode <local\|remote>`	Resolve from config
`--probe`	Force fresh health probe
`--timeout <ms>`	Request timeout (default: 15000)
`--json`	Structured output

Remote Connection (SSH Tunnels)

For remote Gateway access:

# Control tunnel (Gateway WebSocket port)
ssh -N -L 18789:127.0.0.1:18789 user@host

Next Steps

Clawdbot Linux - Linux setup
Clawdbot Windows - Windows WSL2 setup
Clawdbot Gateway - Gateway configuration

Clawdbot macOS App