Vòng đời Gateway trên macOS

Ứng dụng macOS quản lý Gateway thông qua launchd theo mặc định và không spawn Gateway như một child process. Đầu tiên nó sẽ thử kết nối với Gateway đang chạy sẵn trên port đã cấu hình; nếu không kết nối được, nó sẽ bật service launchd thông qua CLI openclaw bên ngoài (không có embedded runtime). Cách này giúp các bạn có auto-start khi đăng nhập và tự động restart khi bị crash.

Chế độ child-process (Gateway được spawn trực tiếp bởi app) hiện không được sử dụng. Nếu các bạn cần kết nối chặt chẽ hơn với UI, hãy chạy Gateway thủ công trong terminal.

Hành vi mặc định (launchd)

  • App cài đặt một LaunchAgent cho từng user với label bot.molt.gateway (hoặc bot.molt.<profile> khi dùng --profile/OPENCLAW_PROFILE; vẫn hỗ trợ legacy com.openclaw.*).
  • Khi bật chế độ Local, app sẽ đảm bảo LaunchAgent được load và khởi động Gateway nếu cần.
  • Log được ghi vào đường dẫn launchd gateway log (xem trong Debug Settings).

Các lệnh thường dùng:

launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway

Thay label thành bot.molt.<profile> khi chạy một profile có tên.

Unsigned dev builds

scripts/restart-mac.sh --no-sign dùng cho các build local nhanh khi các bạn không có signing keys. Để tránh launchd trỏ đến unsigned relay binary, nó sẽ:

  • Ghi file ~/.openclaw/disable-launchagent.

Các lần chạy signed của scripts/restart-mac.sh sẽ xóa override này nếu marker tồn tại. Để reset thủ công:

rm ~/.openclaw/disable-launchagent

Chế độ Attach-only

Để bắt ứng dụng macOS không bao giờ cài đặt hoặc quản lý launchd, khởi chạy nó với --attach-only (hoặc --no-launchd). Cái này sẽ tạo file ~/.openclaw/disable-launchagent, khiến app chỉ kết nối với Gateway đang chạy sẵn. Các bạn có thể bật/tắt hành vi này trong Debug Settings.

Chế độ Remote

Chế độ Remote không bao giờ khởi động Gateway local. App sẽ dùng SSH tunnel đến remote host và kết nối qua tunnel đó.

Tại sao mình ưu tiên launchd

  • Tự động khởi động khi đăng nhập.
  • Có sẵn cơ chế restart/KeepAlive.
  • Log và giám sát dễ dự đoán.

Nếu cần chế độ child-process thực sự trong tương lai, nó nên được document như một chế độ riêng biệt, chỉ dành cho dev.