05bcb565f2
Golden paths now explicitly call out that TCC privacy permissions cannot be fully declarative on unmanaged Macs.
69 lines
2.1 KiB
Markdown
69 lines
2.1 KiB
Markdown
# Golden Paths
|
||
|
||
nix-openclaw is opinionated: **there should be one obvious way to deploy**.
|
||
|
||
A **Golden Path** is a supported topology + defaults + docs that:
|
||
|
||
- is secure by default
|
||
- is reproducible (pinned inputs)
|
||
- avoids manual state drift
|
||
- has a clear boundary between **Nix-managed config** and **runtime state**
|
||
|
||
If your setup doesn’t match a Golden Path, it may still work — but you’re on your own.
|
||
|
||
## GP1: Single Mac (laptop or Mac mini)
|
||
|
||
**Who it’s for:** simplest “it just works” install; macOS-only capabilities available locally.
|
||
|
||
- Gateway: macOS (launchd)
|
||
- OpenClaw.app: same machine
|
||
- Networking: localhost (default)
|
||
|
||
## GP2: VPS Gateway + Mac Node (recommended for reliability)
|
||
|
||
**Who it’s for:** always-on Gateway (Telegram/Discord/etc) with macOS-only capabilities bridged from your Mac.
|
||
|
||
- Gateway: Linux VPS (systemd user service)
|
||
- Node: OpenClaw.app on macOS (connects over WebSocket)
|
||
- Networking: **Tailscale tailnet** (private), no public exposure
|
||
|
||
Key idea: the Gateway routes tool calls to the node when `host=node` is selected.
|
||
|
||
### Why Tailscale?
|
||
|
||
- private-by-default connectivity
|
||
- MagicDNS stable hostnames (no IP chasing)
|
||
- easy to lock down with ACLs
|
||
|
||
### Nix mode on macOS app
|
||
|
||
OpenClaw.app supports **Nix mode** (`OPENCLAW_NIX_MODE=1` or `defaults write ai.openclaw.mac openclaw.nixMode -bool true`).
|
||
|
||
In Nix mode the app disables auto-mutation flows and treats config as read-only.
|
||
If something is missing for a fully declarative deployment, it’s a bug — fix it upstream.
|
||
|
||
## GP3: Laptop-only dev
|
||
|
||
**Who it’s for:** local experimentation.
|
||
|
||
- Gateway: macOS/Linux laptop
|
||
- Node: optional
|
||
- Expect downtime / sleep / network changes
|
||
|
||
## macOS permissions (TCC)
|
||
|
||
On unmanaged Macs, privacy permissions (Screen Recording, Accessibility, etc.) are not fully declarative.
|
||
You can check required permissions in `openclaw nodes status/describe` and then approve them once.
|
||
|
||
## Runtime state vs pinned config
|
||
|
||
Pinned / Nix-managed:
|
||
- `openclaw.json` (gateway config)
|
||
- documents (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, etc.)
|
||
- workspace path selection
|
||
|
||
Runtime:
|
||
- sessions, caches
|
||
- pairing state (devices/nodes)
|
||
- exec approvals
|