Програма для macOS

Застосунок macOS — це супутник у рядку меню для OpenClaw. Він керує дозволами, керує/під’єднується до Gateway локально (launchd або вручну) і надає macOS можливості агенту як Node.

# Що він робить

• Показує нативні сповіщення та стан у рядку меню.
• Керує запитами TCC (Сповіщення, Accessibility, Запис екрана, Мікрофон, Розпізнавання мовлення, Automation/AppleScript).
• Запускає або під’єднується до Gateway (локального чи віддаленого).
• Надає інструменти лише для macOS (Canvas, Camera, Screen Recording, system.run).
• Запускає локальну службу хоста Node у віддаленому режимі (launchd) і зупиняє її в локальному режимі.
• За бажанням розміщує PeekabooBridge для автоматизації UI.
• Встановлює глобальний CLI (openclaw) на запит через npm, pnpm або bun (застосунок віддає перевагу npm, потім pnpm, потім bun; Node залишається рекомендованим середовищем виконання Gateway).

# Локальний і віддалений режим

• Локальний (за замовчуванням): застосунок під’єднується до запущеного локального Gateway, якщо він є; інакше вмикає службу launchd через openclaw gateway install.
• Віддалений: застосунок під’єднується до Gateway через SSH/Tailscale і ніколи не запускає локальний процес. Застосунок запускає локальну службу хоста Node, щоб віддалений Gateway міг досягти цього Mac. Застосунок не запускає Gateway як дочірній процес. Виявлення Gateway тепер віддає перевагу іменам Tailscale MagicDNS замість сирих IP-адрес tailnet, тому застосунок Mac надійніше відновлюється, коли IP-адреси tailnet змінюються.

# Керування launchd

Застосунок керує LaunchAgent для кожного користувача з міткою ai.openclaw.gateway (або ai.openclaw.<profile> під час використання --profile/OPENCLAW_PROFILE; застарілі com.openclaw.* усе ще вивантажуються).

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

Замініть мітку на ai.openclaw.<profile> під час запуску іменованого профілю.

Якщо LaunchAgent не встановлено, увімкніть його із застосунку або виконайте openclaw gateway install.

# Можливості Node (mac)

Застосунок macOS представляє себе як Node. Поширені команди:

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Camera: camera.snap, camera.clip
• Screen: screen.snapshot, screen.record
• System: system.run, system.notify

Node повідомляє карту permissions, щоб агенти могли визначати, що дозволено.

Служба Node + IPC застосунку:

• Коли безголова служба хоста Node працює (віддалений режим), вона під’єднується до Gateway WS як Node.
• system.run виконується в застосунку macOS (контекст UI/TCC) через локальний Unix-сокет; запити + вивід залишаються в застосунку.

Діаграма (SCI):

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

# Дозволи виконання (system.run)

system.run керується дозволами виконання в застосунку macOS (Settings → Exec approvals). Безпека + запит + список дозволеного зберігаються локально на Mac у:

~/.openclaw/exec-approvals.json

Приклад:

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

Нотатки:

• Записи allowlist — це glob-шаблони для розв’язаних шляхів до бінарних файлів або голі назви команд для команд, викликаних через PATH.
• Сирий текст команди shell, що містить синтаксис керування shell або розгортання (&&, ||, ;, |, `, $, <, >, (, )), вважається промахом списку дозволеного й потребує явного схвалення (або додавання бінарного файлу shell до списку дозволеного).
• Вибір "Always Allow" у запиті додає цю команду до списку дозволеного.
• Перевизначення середовища system.run фільтруються (відкидаються PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4), а потім об’єднуються із середовищем застосунку.
• Для обгорток shell (bash|sh|zsh ... -c/-lc) перевизначення середовища в межах запиту скорочуються до невеликого явного списку дозволеного (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Для рішень «завжди дозволяти» в режимі списку дозволеного відомі обгортки диспетчеризації (env, nice, nohup, stdbuf, timeout) зберігають шляхи до внутрішніх виконуваних файлів замість шляхів до обгорток. Якщо розгортання небезпечне, запис у список дозволеного автоматично не зберігається.

# Глибокі посилання

Застосунок реєструє URL-схему openclaw:// для локальних дій.

# openclaw://agent

Запускає запит Gateway agent. OC_I18N_900004 Параметри запиту:

• message (обов’язковий)
• sessionKey (необов’язковий)
• thinking (необов’язковий)
• deliver / to / channel (необов’язковий)
• timeoutSeconds (необов’язковий)
• key (необов’язковий ключ автоматичного режиму)

Безпека:

• Без key застосунок запитує підтвердження.
• Без key застосунок застосовує коротке обмеження повідомлення для запиту підтвердження та ігнорує deliver / to / channel.
• З дійсним key запуск відбувається без участі користувача (призначено для особистих автоматизацій).

# Потік онбордингу (типовий)

1. Встановіть і запустіть OpenClaw.app.
2. Виконайте контрольний список дозволів (запити TCC).
3. Переконайтеся, що режим Локальний активний і Gateway працює.
4. Встановіть CLI, якщо потрібен доступ із термінала.

# Розміщення каталогу стану (macOS)

Уникайте розміщення каталогу стану OpenClaw в iCloud або інших хмарно синхронізованих папках. Шляхи, що підтримуються синхронізацією, можуть додавати затримку й іноді спричиняти перегони блокування файлів/синхронізації для сеансів і облікових даних.

Надавайте перевагу локальному несинхронізованому шляху стану, наприклад: OC_I18N_900005 Якщо openclaw doctor виявить стан у:

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

він попередить і порадить повернутися до локального шляху.

# Збірка та робочий процес розробки (нативний)

• cd apps/macos && swift build
• swift run OpenClaw (або Xcode)
• Пакування застосунку: scripts/package-mac-app.sh

# Налагодження підключення Gateway (macOS CLI)

Використовуйте налагоджувальний CLI, щоб виконати той самий WebSocket-рукостиск Gateway і логіку виявлення, які використовує застосунок macOS, без запуску застосунку. OC_I18N_900006 Параметри підключення:

• --url <ws://host:port>: перевизначити конфігурацію
• --mode <local|remote>: розв’язати з конфігурації (за замовчуванням: конфігурація або локальний)
• --probe: примусово виконати нову перевірку стану
• --timeout <ms>: таймаут запиту (за замовчуванням: 15000)
• --json: структурований вивід для порівняння

Параметри виявлення:

• --include-local: включити шлюзи, які були б відфільтровані як "local"
• --timeout <ms>: загальне вікно виявлення (за замовчуванням: 2000)
• --json: структурований вивід для порівняння

# Інфраструктура віддаленого підключення (SSH-тунелі)

Коли застосунок macOS працює у віддаленому режимі, він відкриває SSH-тунель, щоб локальні UI компоненти могли спілкуватися з віддаленим Gateway так, ніби він був на localhost.

# Керівний тунель (порт WebSocket Gateway)

• Призначення: перевірки стану, статус, Web Chat, конфігурація та інші виклики площини керування.
• Локальний порт: порт Gateway (за замовчуванням 18789), завжди стабільний.
• Віддалений порт: той самий порт Gateway на віддаленому хості.
• Поведінка: без випадкового локального порту; застосунок повторно використовує наявний справний тунель або перезапускає його за потреби.
• Форма SSH: ssh -N -L <local>:127.0.0.1:<remote> з BatchMode + ExitOnForwardFailure + параметрами keepalive.
• Звітування IP: SSH-тунель використовує loopback, тому Gateway бачитиме IP Node як 127.0.0.1. Використовуйте транспорт Direct (ws/wss), якщо хочете, щоб з’являвся реальний IP клієнта (див. віддалений доступ macOS).

Кроки налаштування див. у віддаленому доступі macOS. Подробиці протоколу див. у протоколі Gateway.

# Пов’язана документація

• Інструкція з експлуатації Gateway
• Gateway (macOS)
• Дозволи macOS
• Canvas