Cài đặt OpenClaw trên macOS — Hướng dẫn toàn tập

Dành cho: Mac mini / MacBook chạy macOS 13+
Kết quả: Bot Zalo AI chạy 24/7, truy cập từ xa qua domain riêng, tự khởi động khi máy restart

Tổng quan kiến trúc

Người dùng Zalo
      ↓ nhắn tin
Zalo Bot API
      ↓ polling (bot tự lấy tin)
OpenClaw Gateway (Mac mini)
      ↓
Gemini / Claude / GPT (AI model)
      ↓ phản hồi
Zalo Bot API → người dùng

Dashboard (bạn quản lý)
      ↓ truy cập qua browser
Cloudflare Tunnel → yourdomain.com → OpenClaw

Yêu cầu:

• macOS 13 trở lên (Intel hoặc Apple Silicon)
• Tài khoản Cloudflare (miễn phí)
• Tên miền đã trỏ về Cloudflare
• Tài khoản Zalo Bot Platform

Phần 1 — Cài đặt OpenClaw

1.1 Cài pnpm (nếu chưa có)

curl -fsSL https://get.pnpm.io/install.sh | sh -
source ~/.zshrc

Kiểm tra:

pnpm --version

1.2 Cài OpenClaw

pnpm add -g openclaw@latest

Kiểm tra:

openclaw --version

1.3 Khởi tạo cấu hình

openclaw onboard

Wizard sẽ hỏi:

• AI model: Chọn Google Gemini → nhập API key (lấy từ aistudio.google.com)
• Workspace: Giữ mặc định ~/.openclaw/workspace
• Gateway mode: Local

Lấy Google API key miễn phí: Vào aistudio.google.com → Get API Key → Copy

Phần 2 — Thiết lập Cloudflare Tunnel

Cloudflare Tunnel cho phép expose OpenClaw ra internet không cần IP tĩnh, không cần mở port router.

2.1 Tạo tunnel trên Cloudflare Dashboard

1. Vào one.dash.cloudflare.com
2. Chọn Networks → Tunnels → Create a tunnel
3. Đặt tên tunnel (VD: my-openclaw)
4. Chọn Docker hoặc macOS để lấy token

2.2 Cài cloudflared bằng Docker (khuyến nghị)

Tạo file docker-compose.yml:

version: "3"
services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token <TUNNEL_TOKEN>
    network_mode: host

Thay <TUNNEL_TOKEN> bằng token lấy từ bước 2.1

Chạy:

docker compose up -d

2.3 Cài cloudflared native (không dùng Docker)

brew install cloudflared
cloudflared tunnel login
cloudflared tunnel create my-openclaw
cloudflared tunnel route dns my-openclaw claw.yourdomain.com

Tạo file ~/.cloudflared/config.yml:

tunnel: <TUNNEL_ID>
credentials-file: ~/.cloudflared/<TUNNEL_ID>.json

ingress:
  - hostname: claw.yourdomain.com
    service: http://localhost:18789
  - service: http_status:404

Chạy:

cloudflared tunnel run my-openclaw

2.4 Cấu hình route trên Cloudflare Dashboard

1. Vào tunnel vừa tạo → Public Hostname
2. Thêm route:

• Subdomain: claw
• Domain: yourdomain.com
• Service: http://localhost:18789

Phần 3 — Cấu hình OpenClaw

3.1 Cấu hình gateway

# Cho phép kết nối từ mạng LAN (cần thiết cho Cloudflare Tunnel)
openclaw config set gateway.bind lan

# Trust Cloudflare proxy
openclaw config set gateway.trustedProxies '["127.0.0.1"]'

# Cho phép truy cập từ domain của bạn
openclaw config set gateway.controlUi.allowedOrigins '["https://claw.yourdomain.com"]'

# Đặt password truy cập dashboard
openclaw config set gateway.auth.password "mat-khau-cua-ban"

3.2 Lấy tokenized URL để truy cập lần đầu

openclaw dashboard --no-open

Copy URL dạng http://127.0.0.1:18789/#token=... → đổi thành https://claw.yourdomain.com/#token=...

Dùng URL này để mở dashboard lần đầu, sau đó bookmark lại.

Phần 4 — Thiết lập Zalo Bot

4.1 Tạo Bot trên Zalo Platform

1. Vào bot.zaloplatforms.com
2. Đăng nhập bằng tài khoản Zalo
3. Tạo bot mới → đặt tên
4. Copy Bot Token (dạng 123456789:abc-xyz-token)

4.2 Cấu hình Zalo channel trong OpenClaw

openclaw configure

Chọn:

• Channels → Zalo (Bot API)
• Nhập Bot Token
• Use webhook mode: No (dùng polling — ổn định hơn)
• DM Policy: Open (cho phép mọi người nhắn tin)

4.3 Test bot

Mở Zalo → tìm bot theo tên → nhắn "xin chào"

Bot sẽ phản hồi trong vòng 1-3 giây.

Phần 5 — Auto-start khi máy restart

5.1 Cài LaunchAgent

openclaw gateway install

5.2 Start gateway

openclaw gateway start

5.3 Kiểm tra trạng thái

openclaw gateway status
openclaw status

Từ giờ gateway sẽ tự chạy mỗi khi máy khởi động, không cần thao tác thủ công.

Các lệnh quản lý:

Phần 6 — Truy cập Dashboard từ xa

6.1 Truy cập lần đầu

Dùng tokenized URL:

https://claw.yourdomain.com/#token=<gateway-token>

Lấy token:

openclaw dashboard --no-open

6.2 Truy cập thường xuyên

Sau khi vào bằng tokenized URL lần đầu, browser sẽ được approve tự động. Từ lần sau chỉ cần vào https://claw.yourdomain.com và nhập password.

6.3 Chia sẻ với người khác

Share tokenized URL cho người tin tưởng — họ có thể vào thẳng không cần password.

Để revoke: đổi gateway token:

openclaw config set gateway.auth.token "$(openssl rand -hex 32)"

Phần 7 — Troubleshoot thường gặp

Gateway không start

openclaw gateway status
openclaw doctor --fix

Zalo không nhận/gửi tin

openclaw status
openclaw logs --follow

Kiểm tra channel Zalo:

openclaw channels list

Cloudflare 502 Bad Gateway

Kiểm tra gateway có bind đúng không:

openclaw config get gateway.bind
# Phải là: lan

Kiểm tra port:

lsof -i :18789

Dashboard yêu cầu pairing liên tục

Dùng tokenized URL thay vì vào trực tiếp domain, hoặc:

openclaw config set gateway.trustedProxies '["127.0.0.1"]'
openclaw config set gateway.controlUi.allowedOrigins '["https://claw.yourdomain.com"]'
openclaw gateway stop && openclaw gateway start

Tóm tắt các lệnh quan trọng

# Cài đặt
pnpm add -g openclaw@latest
openclaw onboard

# Cấu hình
openclaw config set gateway.bind lan
openclaw config set gateway.trustedProxies '["127.0.0.1"]'
openclaw config set gateway.controlUi.allowedOrigins '["https://claw.yourdomain.com"]'
openclaw config set gateway.auth.password "password"

# Zalo
openclaw configure  # chọn Channels → Zalo

# Auto-start
openclaw gateway install
openclaw gateway start

# Kiểm tra
openclaw status
openclaw logs --follow

Bài viết tiếp theo: [Cài đặt OpenClaw trên Linux VPS]