Cài OpenClaw trên Mac: Hướng dẫn chi tiết từng bước (macOS 2026)

macOS là nền tảng phổ biến nhất để chạy OpenClaw — nhờ terminal Unix native, hệ sinh thái Homebrew mạnh, và hỗ trợ tốt cho Node.js. Bài viết này dành riêng cho người dùng Mac, hướng dẫn từng bước từ chuẩn bị máy đến cài companion app trên menu bar, bao gồm cả máy Intel lẫn Apple Silicon (M1/M2/M3/M4).

Chưa biết OpenClaw cài bằng cách nào? Bài Hướng dẫn cài đặt OpenClaw từ A-Z giới thiệu 4 phương pháp cài đặt. Bài viết bạn đang đọc tập trung vào phương pháp tối ưu nhất cho macOS.

---

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

Kiểm tra máy bạn đáp ứng các điều kiện sau. Nếu thiếu mục nào, phần tiếp theo sẽ hướng dẫn bạn cài.

Thành phần	Yêu cầu	Cách kiểm tra
macOS	Monterey (12) trở lên	Nhấn → About This Mac
Chip	Intel hoặc Apple Silicon (M1-M4)	Cùng màn About This Mac → mục Chip
RAM	Tối thiểu 2 GB, khuyến nghị 4 GB+	About This Mac → Memory
Ổ cứng	5 GB trống	Finder → phím tắt Cmd + Shift + . → xem ổ đĩa
Node.js	Version 24 (khuyến nghị) hoặc 22.16+	Mở Terminal → chạy node -v
Xcode CLT	Cần thiết (để build native modules)	Chạy xcode-select -p

Mở Terminal: Nhấn Cmd + Space → gõ “Terminal” → Enter. Terminal là ứng dụng dòng lệnh có sẵn trên mọi Mac — bạn sẽ dùng nó xuyên suốt bài viết này.

---

Bước 1: Cài Xcode Command Line Tools

Xcode CLT (Command Line Tools) cung cấp các công cụ biên dịch mà nhiều package Node.js cần để build. Đây là bước hay bị bỏ qua nhưng rất quan trọng — thiếu nó sẽ gặp lỗi node-gyp hoặc sharp build khi cài OpenClaw.

xcode-select --install

Một popup sẽ hiện ra hỏi bạn có muốn cài — nhấn Install và đợi 5-10 phút.

Cách biết thành công: Chạy lại xcode-select -p — nếu hiện đường dẫn /Library/Developer/CommandLineTools, bạn đã cài xong. Nếu trước đó lệnh đã hiện đường dẫn này, nghĩa là máy bạn đã có sẵn — bỏ qua bước này.

---

Bước 2: Cài Homebrew (nếu chưa có)

Homebrew là trình quản lý package phổ biến nhất trên macOS — nó giúp bạn cài Node.js, Git, và nhiều công cụ khác chỉ bằng một dòng lệnh. Kiểm tra trước:

brew --version

Nếu hiện số version → bạn đã có, bỏ qua bước này. Nếu báo command not found, cài bằng lệnh:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Lưu ý quan trọng cho Apple Silicon (M1/M2/M3/M4)

Trên chip Apple Silicon, Homebrew cài vào /opt/homebrew thay vì /usr/local (Intel). Sau khi cài xong, bạn bắt buộc phải thêm Homebrew vào PATH để Terminal nhận lệnh brew:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Cách biết thành công: Chạy brew --version lần nữa — hiện số version là OK.

Intel Mac: Bạn không cần bước thêm PATH ở trên. Homebrew trên Intel tự cài vào /usr/local/bin — đường dẫn này đã có sẵn trong PATH.

---

Bước 3: Cài Node.js 24

OpenClaw yêu cầu Node.js 24 (khuyến nghị) hoặc tối thiểu 22.16+. Có hai cách cài trên Mac:

Cách A: Dùng Homebrew (đơn giản nhất)

brew install node@24

Nếu Homebrew không link tự động (hay xảy ra khi bạn đã có version Node khác):

brew link --overwrite node@24

Cách biết thành công: node -v hiện v24.x.x.

Cách B: Dùng nvm (linh hoạt hơn)

nvm (Node Version Manager) cho phép bạn cài và chuyển đổi giữa nhiều version Node.js — hữu ích nếu bạn làm nhiều dự án cần version khác nhau.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

Đóng Terminal, mở lại (để nvm có hiệu lực), rồi:

nvm install 24
nvm use 24

Cách biết thành công: node -v hiện v24.x.x và nvm current hiện v24.x.x.

Tip: Nếu bạn muốn Node 24 là mặc định mỗi khi mở Terminal mới: nvm alias default 24

---

Bước 4: Cài OpenClaw bằng script tự động

Đây là cách được khuyến nghị chính thức — script tự detect macOS, tải đúng bản, và chuẩn bị mọi thứ:

curl -fsSL https://openclaw.ai/install.sh | bash

Script thực hiện: kiểm tra môi trường → tải OpenClaw → cài global → báo kết quả.

Cách biết thành công: Chạy:

openclaw --version

Hiện số phiên bản (ví dụ v2026.4.8) là OK. Nếu báo command not found, đóng Terminal mở lại rồi thử lần nữa (Terminal cần reload PATH).

Cách khác: Nếu bạn thích dùng npm: npm install -g openclaw@latest. Cả hai cho kết quả như nhau.

---

Bước 5: Chạy Onboard Wizard + cài Daemon

Đây là bước quan trọng nhất trên macOS. Lệnh dưới đây khởi động wizard cài đặt tương tác — hướng dẫn bạn từng bước và tự động cài Gateway daemon (dịch vụ chạy nền):

openclaw onboard --install-daemon

Wizard hướng dẫn bạn qua 4 bước: cài daemon, chọn model AI + nhập API key, kết nối channel, cấu hình workspace. (Chi tiết từng bước đã được giải thích trong bài tổng quan cài đặt.)

Ở đây, hãy chú ý điểm khác biệt trên macOS:

Gateway daemon cài dưới dạng LaunchAgent — khác với Linux (systemd) hay Windows (Task Scheduler), macOS dùng LaunchAgent — dịch vụ nền do hệ điều hành quản lý. Nó tự khởi động khi bạn đăng nhập và chạy ngầm mà không cần mở Terminal. File config daemon nằm ở ~/Library/LaunchAgents/io.openclaw.gateway.plist.

Đây là cách chính thức và ổn định nhất trên macOS — hệ điều hành tự restart daemon nếu nó crash. Không cần dùng pm2 hay tmux.

Cấu hình lưu tại ~/.openclaw/openclaw.json — bạn có thể chỉnh sửa bằng bất kỳ text editor nào (VS Code, nano, vim). Chưa có API key? Xem Hướng dẫn cấu hình API Key.

Cách biết thành công: Sau khi wizard hoàn tất, chạy:

openclaw doctor

Lệnh này kiểm tra toàn bộ hệ thống: Gateway, model, channel, daemon status. Tất cả hiện OK hoặc checkmark xanh nghĩa là mọi thứ hoạt động.

---

Bước 6: Cài OpenClaw Menu Bar App (tùy chọn nhưng khuyến nghị)

OpenClaw có một companion app riêng cho macOS — chạy trên thanh menu bar (góc phải trên cùng màn hình). App này không bắt buộc nhưng rất hữu ích:

Chức năng chính:

• Theo dõi Gateway — icon trên menu bar cho biết Gateway đang chạy hay không, kèm thông tin health
• WebChat tích hợp — giao diện chat nhanh ngay từ menu bar, không cần mở Telegram/Discord
• Voice Wake — kích hoạt wake word (từ khóa đánh thức): nói từ khóa → OpenClaw bắt đầu nghe và xử lý yêu cầu giọng nói. Tính năng này chỉ có trên macOS và iOS
• Talk Mode overlay — hiện overlay giao diện đàm thoại liên tục, hỗ trợ ElevenLabs (giọng AI tự nhiên) với fallback sang System TTS của macOS
• Debug tools — xem log, kiểm tra trạng thái kết nối, restart Gateway trực tiếp

Cách cài: Tải từ trang release trên GitHub hoặc qua Homebrew Cask (nếu có). Sau khi cài, mở app → nó tự detect Gateway đang chạy và kết nối.

Lưu ý Apple Silicon: App cần được ký code (signed build) để các quyền hệ thống (microphone, screen recording, notification) hoạt động ổn định qua các lần update. Nếu macOS hỏi quyền truy cập — nhấn Allow.

---

Bước 7: Giao task đầu tiên và xác nhận

Mở kênh nhắn tin bạn đã kết nối (hoặc WebChat trên menu bar app) và thử:

“Tóm tắt 3 tin công nghệ nổi bật nhất hôm nay”

Nếu bot trả lời nội dung hợp lý — bạn đã cài đặt OpenClaw trên Mac thành công.

Test thêm tính năng macOS-specific:

• Voice: Nói wake word (mặc định: “Hey Claw”) → đợi âm xác nhận → nói yêu cầu. Nếu microphone chưa được cấp quyền, macOS sẽ hỏi — nhấn Allow.
• Notification: Yêu cầu OpenClaw gửi thông báo: “Nhắc tôi uống nước sau 30 phút” → notification macOS sẽ hiện khi đến giờ.
• Trạng thái menu bar: Nhìn icon OpenClaw trên menu bar — xanh = Gateway đang chạy, xám = đã dừng.

---

Xử lý lỗi thường gặp trên macOS

openclaw: command not found sau khi cài

Terminal chưa nhận PATH mới. Fix:

source ~/.zshrc

Hoặc đóng Terminal, mở lại. Nếu vẫn lỗi, kiểm tra PATH:

echo $PATH | tr ':' '\n' | grep -i openclaw

Lỗi node-gyp rebuild hoặc sharp khi cài

Thiếu Xcode CLT. Fix:

xcode-select --install

Đợi cài xong rồi chạy lại lệnh cài OpenClaw.

macOS Gatekeeper chặn script

Nếu macOS hiện cảnh báo “cannot be opened because the developer cannot be verified”:

# Cấp quyền thực thi
chmod +x install.sh

# Hoặc gỡ quarantine attribute
xattr -d com.apple.quarantine install.sh

Port 18789 bị chiếm (Gateway không khởi động)

Tìm và tắt process đang dùng port:

lsof -i :18789
# Ghi lại PID (cột thứ 2), rồi:
kill <PID>

Sau đó khởi động lại Gateway:

openclaw gateway start

Daemon không tự khởi động sau reboot

Kiểm tra LaunchAgent đã load:

launchctl list | grep openclaw

Nếu không thấy kết quả, load lại:

launchctl load ~/Library/LaunchAgents/io.openclaw.gateway.plist

Gặp lỗi khác? Xem danh sách đầy đủ 15+ lỗi và cách fix tại Lỗi thường gặp khi cài OpenClaw.

---

Cập nhật và gỡ cài đặt trên macOS

Cập nhật lên phiên bản mới

openclaw update

Hoặc chọn kênh: openclaw update --channel stable (ổn định), beta (tính năng mới), dev (bản phát triển). Daemon tự restart sau khi update.

Gỡ cài đặt OpenClaw

Nếu muốn xóa hoàn toàn:

# Dừng daemon
launchctl unload ~/Library/LaunchAgents/io.openclaw.gateway.plist

# Gỡ OpenClaw
npm uninstall -g openclaw

# Xóa dữ liệu cấu hình (tùy chọn — chỉ xóa nếu bạn không cần backup)
rm -rf ~/.openclaw

---

Thay thế: Dùng TryOpenClaw.io nếu không muốn tự cài

Nếu bạn không muốn cài đặt gì trên Mac, hoặc muốn OpenClaw chạy 24/7 kể cả khi tắt máy, TryOpenClaw.io là giải pháp cloud — instance riêng, backup hàng ngày, uptime 99.9%, bắt đầu từ 99K VND/tháng.

So sánh chi tiết: OpenClaw tự cài đặt vs TryOpenClaw Cloud — nên chọn gì?

---

Tổng kết

Cài OpenClaw trên Mac gồm 7 bước (hoặc 5 nếu bạn đã có Xcode CLT và Homebrew):

1. Cài Xcode Command Line Tools
2. Cài Homebrew (lưu ý PATH cho Apple Silicon)
3. Cài Node.js 24 (qua Homebrew hoặc nvm)
4. Chạy script cài OpenClaw
5. Chạy openclaw onboard --install-daemon (bước quan trọng nhất)
6. Cài menu bar companion app (tùy chọn)
7. Test task đầu tiên + voice

Thời gian ước tính: 10-15 phút nếu đã quen Terminal, 20-30 phút nếu cần cài Homebrew và Node.js từ đầu.

---

Bước tiếp theo: Cấu hình API Key OpenClaw — từ Claude đến GPT để tối ưu hóa model cho workflow của bạn.

Hoặc: Đăng ký TryOpenClaw.io — bỏ qua toàn bộ cài đặt, dùng ngay trong 2 phút.

---