Thiết lập môi trường Developer trên macOS

Hướng dẫn này sẽ giúp các bạn build và chạy ứng dụng OpenClaw macOS từ source code.

Yêu cầu trước khi bắt đầu

Trước khi build app, các bạn cần cài sẵn:

  1. Xcode 26.2+: Cần thiết để phát triển Swift.
  2. Node.js 22+ & pnpm: Cần thiết cho Gateway, CLI và các script đóng gói.

1. Cài đặt Dependencies

Cài đặt các dependencies cho toàn bộ project:

pnpm install

2. Build và đóng gói App

Để build app macOS và đóng gói thành dist/OpenClaw.app, chạy lệnh:

./scripts/package-mac-app.sh

Nếu các bạn không có Apple Developer ID certificate, script sẽ tự động dùng ad-hoc signing (-).

Để tìm hiểu về dev run modes, signing flags và cách xử lý lỗi Team ID, xem macOS app README: https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

Lưu ý: App được ký ad-hoc có thể kích hoạt cảnh báo bảo mật. Nếu app bị crash ngay lập tức với lỗi “Abort trap 6”, xem phần Troubleshooting nhé.

3. Cài đặt CLI

App macOS cần cài đặt openclaw CLI global để quản lý các tác vụ chạy nền.

Cách cài đặt (khuyên dùng):

  1. Mở app OpenClaw.
  2. Vào tab cài đặt General.
  3. Click “Install CLI”.

Hoặc cài đặt thủ công:

npm install -g openclaw@<version>

Troubleshooting

Build bị lỗi: Toolchain hoặc SDK không khớp

Build app macOS yêu cầu macOS SDK mới nhất và Swift 6.2 toolchain.

System dependencies (bắt buộc):

  • Phiên bản macOS mới nhất có trong Software Update (yêu cầu bởi Xcode 26.2 SDKs)
  • Xcode 26.2 (Swift 6.2 toolchain)

Kiểm tra:

xcodebuild -version
xcrun swift --version

Nếu phiên bản không khớp, cập nhật macOS/Xcode và chạy lại build.

App bị crash khi cấp quyền

Nếu app bị crash khi các bạn cho phép truy cập Speech Recognition hoặc Microphone, có thể do TCC cache bị lỗi hoặc chữ ký không khớp.

Cách khắc phục:

  1. Reset quyền TCC: 
    tccutil reset All bot.molt.mac.debug
  2. Nếu vẫn không được, thay đổi BUNDLE_ID tạm thời trong scripts/package-mac-app.sh để buộc macOS tạo “clean slate”.

Gateway hiển thị “Starting…” mãi không xong

Nếu trạng thái Gateway cứ ở “Starting…”, kiểm tra xem có process zombie nào đang giữ port không:

openclaw gateway status
openclaw gateway stop

# Nếu các bạn không dùng LaunchAgent (dev mode / chạy thủ công), tìm listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN

Nếu có process thủ công đang giữ port, dừng process đó (Ctrl+C). Nếu không được, kill PID mà các bạn tìm thấy ở trên.