Initial commit: OpenClaw Skill Collection
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
This commit is contained in:
@@ -0,0 +1,29 @@
|
||||
# Gateway on macOS
|
||||
|
||||
## Overview
|
||||
|
||||
The OpenClaw macOS application has evolved to work with an external `openclaw` CLI installation rather than bundling its own runtime. The app manages Gateway operations through launchd services.
|
||||
|
||||
## Key Requirements
|
||||
|
||||
To use local mode, you must have Node 22+ on the Mac, then install `openclaw` globally via npm. The application provides an **Install CLI** button that automates this setup.
|
||||
|
||||
## LaunchAgent Configuration
|
||||
|
||||
The system uses launchd to maintain Gateway persistence:
|
||||
|
||||
- **Service Label**: `bot.molt.gateway` (or `bot.molt.<profile>` for custom profiles)
|
||||
- **Configuration Path**: `~/Library/LaunchAgents/bot.molt.gateway.plist`
|
||||
- **Manager**: The macOS app handles installation and updates in Local mode; the CLI also supports installation via `openclaw gateway install`
|
||||
|
||||
## Operational Behavior
|
||||
|
||||
App quit does **not** stop the gateway (launchd keeps it alive). If a Gateway instance already runs on your configured port, the application attaches to it instead of launching a new process. The "OpenClaw Active" toggle controls LaunchAgent activation.
|
||||
|
||||
## Logging and Diagnostics
|
||||
|
||||
Gateway output appears at `/tmp/openclaw/openclaw-gateway.log`. Version compatibility between the app and gateway CLI is verified automatically—mismatches require updating the global CLI installation.
|
||||
|
||||
## Verification Commands
|
||||
|
||||
Test your setup using provided smoke-check commands to validate Gateway functionality on port 18999.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Canvas
|
||||
|
||||
## Overview
|
||||
|
||||
The Canvas feature in OpenClaw is a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive UI surfaces embedded in the macOS app using `WKWebView`.
|
||||
|
||||
## Key Storage & Access
|
||||
|
||||
Canvas files are stored in `~/Library/Application Support/OpenClaw/canvas/<session>/` and served through a custom `openclaw-canvas://` URL scheme that prevents directory traversal attacks.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
The agent can control Canvas through several operations:
|
||||
|
||||
- Display or hide the panel
|
||||
- Navigate to local paths or external URLs
|
||||
- Execute JavaScript commands
|
||||
- Generate snapshot images
|
||||
|
||||
## A2UI Integration
|
||||
|
||||
The system supports A2UI v0.8 server-to-client messages including `surfaceUpdate`, `dataModelUpdate`, and `deleteSurface`. The newer `createSurface` (v0.9) remains unsupported.
|
||||
|
||||
## Agent Triggering
|
||||
|
||||
Canvas content can initiate new agent runs using deep links formatted as `openclaw://agent?message=<text>`, with confirmation prompts unless a valid key is supplied.
|
||||
|
||||
## Security Features
|
||||
|
||||
Canvas scheme blocks directory traversal; files must live under the session root. External URLs require explicit navigation permissions.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Gateway Lifecycle on macOS
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS application manages the Gateway through launchd rather than spawning it as a child process. It attempts to connect to an existing Gateway on the configured port; if unavailable, it enables the launchd service via the `openclaw` CLI.
|
||||
|
||||
## Default Behavior
|
||||
|
||||
The system installs a per-user LaunchAgent labeled `bot.molt.gateway` (or `bot.molt.<profile>` for named profiles). When Local mode is active, the app ensures this agent is loaded and starts the Gateway as needed. Log files are directed to the launchd gateway log path, accessible through Debug Settings.
|
||||
|
||||
Key management commands include:
|
||||
|
||||
```bash
|
||||
launchctl kickstart -k gui/$UID/bot.molt.gateway
|
||||
launchctl bootout gui/$UID/bot.molt.gateway
|
||||
```
|
||||
|
||||
## Development Builds
|
||||
|
||||
Unsigned development builds use `scripts/restart-mac.sh --no-sign` for rapid iteration. This prevents launchd from referencing an unsigned binary by creating `~/.openclaw/disable-launchagent`. Signed builds automatically clear this override.
|
||||
|
||||
## Connection Modes
|
||||
|
||||
**Attach-only mode** forces the app to skip launchd management entirely using the `--attach-only` flag, connecting only to already-running Gateways.
|
||||
|
||||
**Remote mode** bypasses local Gateway startup, instead establishing an SSH tunnel to a remote host.
|
||||
|
||||
## Design Rationale
|
||||
|
||||
The launchd approach provides:
|
||||
|
||||
- Automatic login startup
|
||||
- Built-in restart capabilities
|
||||
- Consistent logging and supervision patterns
|
||||
@@ -0,0 +1,75 @@
|
||||
# macOS Dev Setup
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The following tools are required:
|
||||
|
||||
1. **Xcode 26.2+**: Necessary for Swift development
|
||||
2. **Node.js 22+ & pnpm**: Required for the gateway, CLI, and packaging scripts
|
||||
|
||||
## 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## 2. Build and Package the App
|
||||
|
||||
To build the macOS app and package it into `dist/OpenClaw.app`, run:
|
||||
|
||||
```bash
|
||||
./scripts/package-mac-app.sh
|
||||
```
|
||||
|
||||
If you don't have an Apple Developer ID certificate, the script will automatically use ad-hoc signing instead.
|
||||
|
||||
For additional configuration options, see the apps/macos/README.md file in the repository.
|
||||
|
||||
> Ad-hoc signed apps may trigger security prompts. Immediate crashes with "Abort trap 6" are addressed in troubleshooting.
|
||||
|
||||
## 3. Install the CLI
|
||||
|
||||
The app requires a global `openclaw` CLI installation for background task management.
|
||||
|
||||
**To install:**
|
||||
|
||||
1. Open the OpenClaw app
|
||||
2. Navigate to the **General** settings tab
|
||||
3. Click **"Install CLI"**
|
||||
|
||||
Or manually install:
|
||||
|
||||
```bash
|
||||
npm install -g openclaw@<version>
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails: Toolchain or SDK Mismatch
|
||||
|
||||
Verify your toolchain versions:
|
||||
|
||||
```bash
|
||||
xcodebuild -version
|
||||
xcrun swift --version
|
||||
```
|
||||
|
||||
Update macOS and Xcode if versions don't align.
|
||||
|
||||
### App Crashes on Permission Grant
|
||||
|
||||
Reset TCC permissions:
|
||||
|
||||
```bash
|
||||
tccutil reset All bot.molt.mac.debug
|
||||
```
|
||||
|
||||
### Gateway "Starting..." Indefinitely
|
||||
|
||||
Check for zombie processes:
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw gateway stop
|
||||
lsof -nP -iTCP:18789 -sTCP:LISTEN
|
||||
```
|
||||
@@ -0,0 +1,42 @@
|
||||
# Health Checks on macOS
|
||||
|
||||
## Overview
|
||||
|
||||
This documentation explains monitoring linked channel health through the macOS menu bar application, including status indicators, settings, and diagnostic procedures.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Status Indicator
|
||||
|
||||
The menu bar displays a colored dot reflecting channel health:
|
||||
|
||||
- **Green**: linked + socket opened recently
|
||||
- **Orange**: connecting/retrying
|
||||
- **Red**: logged out or probe failed
|
||||
|
||||
A secondary line shows authentication age or failure details.
|
||||
|
||||
### Settings Interface
|
||||
|
||||
The Health card within Settings displays:
|
||||
|
||||
- Linked authentication age
|
||||
- Session storage information
|
||||
- Last check timestamp
|
||||
|
||||
Users can manually trigger checks and access logs through dedicated buttons.
|
||||
|
||||
### Diagnostic Process
|
||||
|
||||
The system executes `openclaw health --json` approximately every 60 seconds and on-demand. This probe loads creds and reports status without sending messages, maintaining separate caches for successful and failed snapshots.
|
||||
|
||||
## Alternative Approaches
|
||||
|
||||
For additional troubleshooting, reference the Gateway health section. Recommended CLI commands include:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw status --deep
|
||||
```
|
||||
|
||||
Review log files at `/tmp/openclaw/openclaw-*.log` for connection-related events.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Menu Bar Icon States
|
||||
|
||||
Author: steipete | Updated: 2025-12-06 | Scope: macOS app (`apps/macos`)
|
||||
|
||||
## Icon States
|
||||
|
||||
- **Idle:** Normal icon animation (blink, occasional wiggle).
|
||||
- **Paused:** Status item uses `appearsDisabled`; no motion.
|
||||
- **Voice trigger (big ears):** Voice wake detector calls `AppState.triggerVoiceEars(ttl: nil)` when the wake word is heard, keeping `earBoostActive=true` while the utterance is captured. Ears scale up (1.9x), get circular ear holes for readability, then drop via `stopVoiceEars()` after 1s of silence. Only fired from the in-app voice pipeline.
|
||||
- **Working (agent running):** `AppState.isWorking=true` drives a "tail/leg scurry" micro-motion: faster leg wiggle and slight offset while work is in-flight. Currently toggled around WebChat agent runs; add the same toggle around other long tasks when you wire them.
|
||||
|
||||
## Wiring Points
|
||||
|
||||
- **Voice wake:** Runtime/tester call `AppState.triggerVoiceEars(ttl: nil)` on trigger and `stopVoiceEars()` after 1s of silence to match the capture window.
|
||||
- **Agent activity:** Set `AppStateStore.shared.setWorking(true/false)` around work spans (already done in WebChat agent call). Keep spans short and reset in `defer` blocks to avoid stuck animations.
|
||||
|
||||
## Shapes & Sizes
|
||||
|
||||
- Base icon drawn in `CritterIconRenderer.makeIcon(blink:legWiggle:earWiggle:earScale:earHoles:)`.
|
||||
- Ear scale defaults to `1.0`; voice boost sets `earScale=1.9` and toggles `earHoles=true` without changing overall frame (18x18 pt template image rendered into a 36x36 px Retina backing store).
|
||||
- Scurry uses leg wiggle up to ~1.0 with a small horizontal jiggle; it's additive to any existing idle wiggle.
|
||||
|
||||
## Behavioral Notes
|
||||
|
||||
- No external CLI/broker toggle for ears/working; keep it internal to the app's own signals to avoid accidental flapping.
|
||||
- Keep TTLs short (<10s) so the icon returns to baseline quickly if a job hangs.
|
||||
@@ -0,0 +1,49 @@
|
||||
# macOS Logging
|
||||
|
||||
## Rolling Diagnostics File Log (Debug Pane)
|
||||
|
||||
OpenClaw routes macOS app logs through swift-log (unified logging by default) and can write a local, rotating file log to disk when you need a durable capture.
|
||||
|
||||
- **Verbosity**: Debug pane -> Logs -> App logging -> Verbosity
|
||||
- **Enable**: Debug pane -> Logs -> App logging -> "Write rolling diagnostics log (JSONL)"
|
||||
- **Location**: `~/Library/Logs/OpenClaw/diagnostics.jsonl` (rotates automatically; old files are suffixed with `.1`, `.2`, ...)
|
||||
- **Clear**: Debug pane -> Logs -> App logging -> "Clear"
|
||||
|
||||
### Notes
|
||||
|
||||
- This is **off by default**. Enable only while actively debugging.
|
||||
- Treat the file as sensitive; don't share it without review.
|
||||
|
||||
## Unified Logging Private Data on macOS
|
||||
|
||||
Unified logging redacts most payloads unless a subsystem opts into `privacy -off`. This is controlled by a plist in `/Library/Preferences/Logging/Subsystems/` keyed by the subsystem name. Only new log entries pick up the flag, so enable it before reproducing an issue.
|
||||
|
||||
## Enable for OpenClaw (`bot.molt`)
|
||||
|
||||
Write the plist to a temp file first, then install it atomically as root:
|
||||
|
||||
```bash
|
||||
cat <<'EOF' >/tmp/bot.molt.plist
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>DEFAULT-OPTIONS</key>
|
||||
<dict>
|
||||
<key>Enable-Private-Data</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
sudo install -m 644 -o root -g wheel /tmp/bot.molt.plist /Library/Preferences/Logging/Subsystems/bot.molt.plist
|
||||
```
|
||||
|
||||
- No reboot is required; logd notices the file quickly, but only new log lines will include private payloads.
|
||||
- View the richer output with the existing helper, e.g. `./scripts/clawlog.sh --category WebChat --last 5m`.
|
||||
|
||||
## Disable After Debugging
|
||||
|
||||
- Remove the override: `sudo rm /Library/Preferences/Logging/Subsystems/bot.molt.plist`
|
||||
- Optionally run `sudo log config --reload` to force logd to drop the override immediately.
|
||||
- Remember this surface can include phone numbers and message bodies; keep the plist in place only while you actively need the extra detail.
|
||||
@@ -0,0 +1,53 @@
|
||||
# Menu Bar Status Logic
|
||||
|
||||
## Overview
|
||||
|
||||
This page documents how OpenClaw displays agent work state through menu bar indicators and status messaging.
|
||||
|
||||
## Key Display Features
|
||||
|
||||
The system surfaces current agent activity via:
|
||||
|
||||
- Menu bar icon reflecting work state
|
||||
- Status row showing session and activity information
|
||||
- Health status (visible only when idle)
|
||||
- Device list from paired nodes
|
||||
- Usage metrics when available from providers
|
||||
|
||||
## Session Management
|
||||
|
||||
Sessions receive events containing a `runId` and `sessionKey`. The "main" session takes priority—when active, it immediately displays in the menu. If main is idle, the most recently active non-main session appears instead, preventing constant switching during transitions.
|
||||
|
||||
## Activity Indicators
|
||||
|
||||
Two activity types generate status updates:
|
||||
|
||||
**Jobs** represent high-level command execution with states: started, streaming, done, or error.
|
||||
|
||||
**Tools** show operational phases (start/result) with associated metadata and arguments.
|
||||
|
||||
## Visual States
|
||||
|
||||
The icon system includes four states:
|
||||
|
||||
- **Idle**: Normal display
|
||||
- **Working main**: Full badge animation
|
||||
- **Working other**: Muted badge
|
||||
- **Overridden**: Debug mode
|
||||
|
||||
Activity kinds map to glyphs:
|
||||
|
||||
| Kind | Glyph |
|
||||
|------|-------|
|
||||
| exec | terminal |
|
||||
| read | document |
|
||||
| write | pencil |
|
||||
| edit | notepad |
|
||||
| attach | paperclip |
|
||||
| others | wrench |
|
||||
|
||||
## Status Labels
|
||||
|
||||
Active work displays as: `<Session role> - <activity label>` (e.g., "Main - exec: pnpm test").
|
||||
|
||||
The system labels activities by extracting command first lines, shortened file paths, and inferred change types from diffs.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Peekaboo Bridge
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw.app can function as a **PeekabooBridge host**, enabling UI automation through the `peekaboo` CLI while leveraging existing macOS app permissions.
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
The system operates as a thin broker where:
|
||||
|
||||
- OpenClaw.app acts as the hosting service
|
||||
- The `peekaboo` command-line tool serves as the client interface
|
||||
- Visual overlays remain within Peekaboo.app rather than OpenClaw
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
To activate this feature, navigate to **Settings -> Enable Peekaboo Bridge** within the macOS application. Once enabled, OpenClaw initiates a local UNIX socket server; disabling it stops the host and causes `peekaboo` to revert to alternative available hosts.
|
||||
|
||||
## Host Discovery Sequence
|
||||
|
||||
Peekaboo clients attempt connection in this order:
|
||||
|
||||
1. Peekaboo.app (full user experience)
|
||||
2. Claude.app (if present)
|
||||
3. OpenClaw.app (broker alternative)
|
||||
|
||||
Check active hosts using:
|
||||
|
||||
```bash
|
||||
peekaboo bridge status --verbose
|
||||
```
|
||||
|
||||
Override socket path with:
|
||||
|
||||
```bash
|
||||
export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
|
||||
```
|
||||
|
||||
## Security Features
|
||||
|
||||
The bridge validates caller code signatures; an allowlist of TeamIDs is enforced. Request timeouts are approximately 10 seconds. Missing permissions trigger error messages rather than prompting system dialogs.
|
||||
|
||||
## Snapshot Management
|
||||
|
||||
Snapshots exist temporarily in memory with automatic expiration. Re-capture snapshots when extended retention is needed.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **Authorization errors**: Ensure proper code signing or enable `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` in debug mode
|
||||
- **No hosts detected**: Launch either Peekaboo.app or OpenClaw.app and verify permission grants
|
||||
@@ -0,0 +1,48 @@
|
||||
# macOS Permissions
|
||||
|
||||
## Overview
|
||||
|
||||
This documentation addresses macOS permission management through TCC (Transparency, Consent, and Control), explaining why permission grants can be unstable and how to resolve issues.
|
||||
|
||||
## Permission Stability Issues
|
||||
|
||||
TCC associates a permission grant with the app's code signature, bundle identifier, and on-disk path. Any changes to these elements cause macOS to treat the application as new, potentially removing previously granted permissions.
|
||||
|
||||
## Requirements for Reliable Permissions
|
||||
|
||||
- Applications must run from a consistent location
|
||||
- Bundle identifiers should remain unchanged
|
||||
- Apps must be properly signed (not ad-hoc signed)
|
||||
- Code signatures must be consistent across rebuilds using real Apple certificates
|
||||
|
||||
## Why Ad-Hoc Signing Fails
|
||||
|
||||
Ad-hoc signatures create new identities with each build, causing macOS to forget previous permission grants and potentially hiding permission prompts entirely.
|
||||
|
||||
## Troubleshooting Steps
|
||||
|
||||
The recovery process involves:
|
||||
|
||||
1. Quitting the app
|
||||
2. Removing it from System Settings privacy controls
|
||||
3. Relaunching it
|
||||
4. Re-granting permissions
|
||||
|
||||
### Using tccutil
|
||||
|
||||
Reset specific permission entries by bundle identifier:
|
||||
|
||||
```bash
|
||||
tccutil reset All bot.molt.mac.debug
|
||||
```
|
||||
|
||||
Or reset specific services:
|
||||
|
||||
```bash
|
||||
tccutil reset Accessibility bot.molt.mac.debug
|
||||
tccutil reset ScreenCapture bot.molt.mac.debug
|
||||
```
|
||||
|
||||
## Testing Recommendation
|
||||
|
||||
For permission testing, developers should use real certificates rather than ad-hoc signatures. Ad-hoc builds are acceptable for casual local testing where permissions aren't critical.
|
||||
@@ -0,0 +1,47 @@
|
||||
# macOS Release
|
||||
|
||||
## Overview
|
||||
|
||||
This page documents the process for releasing OpenClaw on macOS using Sparkle auto-updates. Release builds require Developer ID signing, packaging, and appcast publication.
|
||||
|
||||
## Key Requirements
|
||||
|
||||
The following prerequisites are required:
|
||||
|
||||
- A Developer ID Application certificate must be installed
|
||||
- The Sparkle private key path needs configuration via `SPARKLE_PRIVATE_KEY_FILE`
|
||||
- Notary credentials are required for Gatekeeper-safe distribution
|
||||
- `pnpm` dependencies must be installed
|
||||
- Sparkle tools are automatically fetched through SwiftPM
|
||||
|
||||
## Build Process
|
||||
|
||||
Developers should use specific scripts depending on their needs:
|
||||
|
||||
- `scripts/package-mac-app.sh` handles local and development packaging
|
||||
- `scripts/package-mac-dist.sh` creates release artifacts including zip files, disk images, and notarization
|
||||
|
||||
### Build Parameters
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `APP_BUILD` | Must be numeric + monotonic for Sparkle compare |
|
||||
| `APP_VERSION` | Semantic version string |
|
||||
| Architecture | Target CPU architecture specification |
|
||||
|
||||
## Appcast and Publishing
|
||||
|
||||
After building, generate appcast entries using:
|
||||
|
||||
```bash
|
||||
scripts/make_appcast.sh
|
||||
```
|
||||
|
||||
This creates formatted HTML release notes from the changelog.
|
||||
|
||||
### Final Steps
|
||||
|
||||
1. Upload assets to GitHub releases
|
||||
2. Verify that the appcast URL functions correctly
|
||||
3. Confirm package URLs are accessible
|
||||
4. Test the update flow end-to-end
|
||||
@@ -0,0 +1,53 @@
|
||||
# Remote Control
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw's remote control capabilities allow a macOS app to function as a controller for an OpenClaw gateway on another host via SSH.
|
||||
|
||||
## Key Operational Modes
|
||||
|
||||
The system supports three operational approaches:
|
||||
|
||||
1. **Local execution** on the macOS device
|
||||
2. **Remote over SSH** (default) with port forwarding
|
||||
3. **Remote direct** using WebSocket connections without SSH tunneling
|
||||
|
||||
## Transport Options
|
||||
|
||||
Two transport mechanisms are available:
|
||||
|
||||
- **SSH tunneling**: Masks the client as localhost
|
||||
- **Direct WebSocket**: Exposes the actual client IP
|
||||
|
||||
## Setup Requirements
|
||||
|
||||
### Remote Host Requirements
|
||||
|
||||
- Node.js, pnpm, and the OpenClaw CLI installed
|
||||
- Accessible on the system PATH
|
||||
- SSH should use key-based authentication
|
||||
- Tailscale IPs recommended for reliable off-network access
|
||||
|
||||
### macOS App Configuration
|
||||
|
||||
1. Select transport type
|
||||
2. Specify the SSH target
|
||||
3. Optionally provide gateway URLs and identity file paths
|
||||
4. Use "Test remote" feature to validate connectivity
|
||||
|
||||
## Web Chat Integration
|
||||
|
||||
Web Chat operates through the same SSH tunnel or direct gateway connection depending on the selected transport method.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Use loopback bindings with either SSH or Tailscale for secure connections
|
||||
- Implement token/password authentication when binding to non-loopback interfaces
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issues include:
|
||||
|
||||
- **Exit code 127**: PATH configuration problems
|
||||
- **SSH connectivity failures**: Check key authentication and host accessibility
|
||||
- **Port forwarding mismatches**: Verify WebSocket connection ports match configuration
|
||||
@@ -0,0 +1,35 @@
|
||||
# macOS Signing
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS signing process for OpenClaw is automated through build scripts that handle code signing, bundle identification, and metadata injection.
|
||||
|
||||
## Key Components
|
||||
|
||||
**Main Script**: `scripts/package-mac-app.sh` orchestrates the packaging and signing workflow, requiring Node 22+ for TypeScript and Control UI builds.
|
||||
|
||||
**Signing Identity**: The process reads the `SIGN_IDENTITY` environment variable. Developers can configure a persistent signing certificate by exporting this value in their shell configuration.
|
||||
|
||||
## Core Functionality
|
||||
|
||||
The packaging script performs several tasks:
|
||||
|
||||
1. Establishes a stable debug bundle identifier (`ai.openclaw.mac.debug`)
|
||||
2. Updates Info.plist with the bundle identifier
|
||||
3. Invokes `codesign-mac-app.sh` to sign binaries and the app bundle
|
||||
4. Implements timestamping for Developer ID signatures (configurable via `CODESIGN_TIMESTAMP`)
|
||||
5. Injects build metadata (`OpenClawBuildTimestamp` and `OpenClawGitCommit`)
|
||||
6. Validates Team ID consistency across all Mach-O files
|
||||
|
||||
## Signing Options
|
||||
|
||||
| Option | Configuration |
|
||||
|--------|---------------|
|
||||
| Auto-selection | Run script without environment variables |
|
||||
| Production certificates | `SIGN_IDENTITY="Developer ID Application: Name"` |
|
||||
| Ad-hoc signing | `ALLOW_ADHOC_SIGNING=1` or `SIGN_IDENTITY="-"` |
|
||||
| Offline builds | `CODESIGN_TIMESTAMP=off` |
|
||||
|
||||
## Important Caveat
|
||||
|
||||
Ad-hoc signatures automatically disable the Hardened Runtime to prevent framework loading failures. This approach compromises TCC permission persistence between rebuilds.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Skills (macOS)
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS application surfaces OpenClaw skills through a gateway rather than parsing them locally.
|
||||
|
||||
## Key Components
|
||||
|
||||
### Data Source
|
||||
|
||||
The system retrieves skill information via `skills.status` from the gateway, which provides all skills plus eligibility and missing requirements. Requirements come from the `metadata.openclaw.requires` field in skill markdown files.
|
||||
|
||||
### Installation Process
|
||||
|
||||
The `metadata.openclaw.install` property specifies available installation methods:
|
||||
|
||||
- brew
|
||||
- node
|
||||
- go
|
||||
- uv
|
||||
|
||||
When users initiate installation, the app invokes `skills.install` on the gateway host. The gateway prioritizes a single installer:
|
||||
|
||||
1. Prefers brew when available
|
||||
2. Otherwise uses the node package manager specified in `skills.install`
|
||||
3. Falls back to npm as the default
|
||||
|
||||
### Credential Management
|
||||
|
||||
API keys and environment variables are stored locally at `~/.openclaw/openclaw.json` under the `skills.entries.<skillKey>` path.
|
||||
|
||||
Configuration updates use the `skills.update` endpoint to modify:
|
||||
|
||||
- Enabled status
|
||||
- API keys
|
||||
- Environment settings
|
||||
|
||||
### Remote Configuration
|
||||
|
||||
Installation and configuration changes occur on the gateway host rather than the local machine, maintaining centralized management of skill deployment.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Voice Overlay
|
||||
|
||||
## Overview
|
||||
|
||||
This documentation describes the macOS voice overlay lifecycle, designed to manage interactions between wake-word detection and push-to-talk functionality.
|
||||
|
||||
## Key Design Principle
|
||||
|
||||
The system ensures predictable behavior when wake-word and push-to-talk overlap. If the overlay is already visible from wake-word and the user presses the hotkey, the hotkey session *adopts* the existing text instead of resetting it.
|
||||
|
||||
## Core Implementation (as of Dec 9, 2025)
|
||||
|
||||
The architecture uses three main components:
|
||||
|
||||
### 1. VoiceSessionCoordinator
|
||||
|
||||
Acts as a single-session owner managing token-based API calls:
|
||||
|
||||
- `beginWakeCapture`
|
||||
- `beginPushToTalk`
|
||||
- `endCapture`
|
||||
|
||||
### 2. VoiceSession
|
||||
|
||||
Model carrying session metadata including:
|
||||
|
||||
- Token
|
||||
- Source (wakeWord | pushToTalk)
|
||||
- Committed/volatile text
|
||||
- Chime flags
|
||||
- Timers (auto-send, idle)
|
||||
|
||||
### 3. VoiceSessionPublisher
|
||||
|
||||
SwiftUI integration that mirrors the active session into SwiftUI without direct singleton mutations.
|
||||
|
||||
## Behavior Details
|
||||
|
||||
- **Wake-word alone**: Auto-sends on silence
|
||||
- **Push-to-talk**: Sends immediately upon release, can wait up to 1.5s for a final transcript before falling back to the current text
|
||||
|
||||
## Debugging Support
|
||||
|
||||
Stream logs using:
|
||||
|
||||
```bash
|
||||
sudo log stream --predicate 'subsystem == "bot.molt" AND category CONTAINS "voicewake"'
|
||||
```
|
||||
|
||||
## Migration Path
|
||||
|
||||
Implementation follows five sequential steps:
|
||||
|
||||
1. Add core components
|
||||
2. Wire VoiceSessionCoordinator
|
||||
3. Integrate VoiceSession model
|
||||
4. Connect VoiceSessionPublisher to SwiftUI
|
||||
5. Integration testing for session adoption and cooldown behavior
|
||||
@@ -0,0 +1,54 @@
|
||||
# Voice Wake & Push-to-Talk
|
||||
|
||||
## Overview
|
||||
|
||||
The Voice Wake feature operates in two modes: wake-word (always-on with trigger detection) and push-to-talk (immediate capture via right Option key hold).
|
||||
|
||||
## Key Operating Modes
|
||||
|
||||
### Wake-word Mode
|
||||
|
||||
Functions as the default, with the speech recognizer continuously listening for specified trigger tokens. Upon detection, it:
|
||||
|
||||
1. Initiates capture
|
||||
2. Displays an overlay with partial transcription
|
||||
3. Automatically sends after detecting silence
|
||||
|
||||
### Push-to-talk Mode
|
||||
|
||||
Activates immediately when users hold the right Option key—no trigger word necessary. The overlay remains visible during the hold and processes the audio after release.
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### VoiceWakeRuntime
|
||||
|
||||
Manages the speech recognizer, requiring approximately 0.55 seconds of meaningful pause between trigger word and command.
|
||||
|
||||
### Silence Detection
|
||||
|
||||
- 2.0-second windows during active speech
|
||||
- 5.0-second windows if only the trigger was detected
|
||||
- Hard 120-second limit per session
|
||||
|
||||
### Overlay Implementation
|
||||
|
||||
Uses `VoiceWakeOverlayController` with committed and volatile text states. A critical improvement prevents the "sticky overlay" failure mode where manual dismissal could halt listening—the runtime no longer blocks on overlay visibility, and closing the overlay triggers automatic restart.
|
||||
|
||||
## User Configuration
|
||||
|
||||
Available settings include:
|
||||
|
||||
- Toggle Voice Wake on/off
|
||||
- Enable push-to-talk (Cmd+Fn hold, macOS 26+)
|
||||
- Language selection
|
||||
- Microphone selection with persistent preferences
|
||||
- Customizable audio cues (Glass sound by default, or any NSSound-compatible file)
|
||||
|
||||
## Message Routing
|
||||
|
||||
Transcripts forward to the active gateway using the app's configured local or remote mode, with replies delivered to the previously-used primary provider:
|
||||
|
||||
- WhatsApp
|
||||
- Telegram
|
||||
- Discord
|
||||
- WebChat
|
||||
@@ -0,0 +1,48 @@
|
||||
# WebChat
|
||||
|
||||
## Overview
|
||||
|
||||
The macOS menu bar application integrates WebChat as a native SwiftUI component, connecting to the Gateway with support for both local and remote operation modes.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Connection Modes
|
||||
|
||||
- **Local mode**: Links directly to the local Gateway WebSocket
|
||||
- **Remote mode**: Tunnels the Gateway control port through SSH
|
||||
|
||||
### Session Management
|
||||
|
||||
The app defaults to the main session for the selected agent (with a session switcher for other sessions). Onboarding operates through a separate dedicated session.
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Data Plane
|
||||
|
||||
The system uses Gateway WebSocket methods:
|
||||
|
||||
- `chat.history`
|
||||
- `chat.send`
|
||||
- `chat.abort`
|
||||
- `chat.inject`
|
||||
|
||||
Corresponding events for:
|
||||
|
||||
- Chat
|
||||
- Agent
|
||||
- Presence
|
||||
- Tick
|
||||
- Health monitoring
|
||||
|
||||
### Launch Options
|
||||
|
||||
Access through multiple methods:
|
||||
|
||||
- Lobster menu -> "Open Chat"
|
||||
- Testing launch: `dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat`
|
||||
- Logging via `./scripts/clawlog.sh` (subsystem `bot.molt`, WebChatSwiftUI category)
|
||||
|
||||
## Security & Constraints
|
||||
|
||||
- Remote mode restricts forwarding to the Gateway WebSocket control port only
|
||||
- The interface is optimized for chat sessions (not a full browser sandbox)
|
||||
@@ -0,0 +1,49 @@
|
||||
# macOS IPC
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw's macOS architecture uses a local Unix socket connecting a node host service to the macOS app for execution approvals and system commands. A debug CLI tool (`openclaw-mac`) supports discovery and connection checks.
|
||||
|
||||
## Key Architecture Components
|
||||
|
||||
### Primary Goal
|
||||
|
||||
Maintain a single GUI app instance that handles all TCC-related operations while minimizing the automation surface area.
|
||||
|
||||
### System Layers
|
||||
|
||||
The system operates through three main layers:
|
||||
|
||||
#### 1. Gateway + Node Transport
|
||||
|
||||
The application runs the Gateway locally and connects as a node, executing agent actions via `node.invoke` for commands like `system.run` and `system.notify`.
|
||||
|
||||
#### 2. IPC Layer
|
||||
|
||||
A headless node service connects to the Gateway WebSocket, forwarding `system.run` requests to the macOS app through a local Unix socket with security measures:
|
||||
|
||||
- Tokens
|
||||
- HMAC validation
|
||||
- TTL
|
||||
|
||||
#### 3. UI Automation
|
||||
|
||||
PeekabooBridge operates on a separate socket (`bridge.sock`), following a preference hierarchy:
|
||||
|
||||
1. Peekaboo.app
|
||||
2. Claude.app
|
||||
3. OpenClaw.app
|
||||
4. Local execution
|
||||
|
||||
## Security Considerations
|
||||
|
||||
Protection mechanisms include:
|
||||
|
||||
- Socket permissions set to `0600`
|
||||
- Peer UID verification checks
|
||||
- HMAC-based challenge/response protocols
|
||||
- Short time-to-live values on tokens
|
||||
- TeamID matching requirements for privileged operations
|
||||
- Signed bundle ID stability across rebuilds
|
||||
|
||||
Communication remains entirely local without exposed network sockets.
|
||||
Reference in New Issue
Block a user