3.0 KiB
3.0 KiB
summary, read_when
| summary | read_when | ||
|---|---|---|---|
| Clawdbot macOS companion app (menu bar + gateway broker) |
|
Clawdbot macOS Companion (menu bar + gateway broker)
The macOS app is the menu‑bar companion for Clawdbot. It owns permissions, manages the Gateway locally, 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). - Optionally hosts PeekabooBridge for UI automation.
- Installs a helper CLI (
clawdbot) into/usr/local/binand/opt/homebrew/binon request.
Local vs remote mode
- Local (default): the app ensures a local Gateway is running via launchd.
- Remote: the app connects to a Gateway over SSH/Tailscale and never starts a local process.
- Attach‑only (debug): the app connects to an already‑running local Gateway and never spawns its own.
Launchd control
The app manages a per‑user LaunchAgent labeled com.clawdbot.gateway.
launchctl kickstart -k gui/$UID/com.clawdbot.gateway
launchctl bootout gui/$UID/com.clawdbot.gateway
If the LaunchAgent isn’t installed, enable it from the app or run
clawdbot daemon install.
Node capabilities (mac)
The macOS app presents itself as a node. Common commands:
- Canvas:
canvas.present,canvas.navigate,canvas.eval,canvas.snapshot,canvas.a2ui.* - 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.
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:
message(required)sessionKey(optional)thinking(optional)deliver/to/provider(optional)timeoutSeconds(optional)key(optional unattended mode key)
Safety:
- Without
key, the app prompts for confirmation. - With a valid
key, the run is unattended (intended for personal automations).
Onboarding flow (typical)
- Install and launch Clawdbot.app.
- Complete the permissions checklist (TCC prompts).
- Ensure Local mode is active and the Gateway is running.
- Install the CLI helper if you want terminal access.
Build & dev workflow (native)
cd apps/macos && swift buildswift run Clawdbot(or Xcode)- Package app + CLI:
scripts/package-mac-app.sh- Switch bundled gateway runtime with
BUNDLED_RUNTIME=node|bun(default: node).
- Switch bundled gateway runtime with