Hướng dẫn cài đặt OpenClaw trên macOS tạo AI agent

Bạn muốn một AI agent chạy ngay trên máy Mac của mình, nhận lệnh qua khung chat quen thuộc chứ không phải web của dịch vụ nào khác? Tất cả bắt đầu từ việc cài OpenClaw. Bài này là hướng dẫn cài đặt OpenClaw trên macOS từ con số 0 tới lúc agent trả lời được, kèm đúng những chỗ người mới hay vướng trên máy Mac.

Cài đặt OpenClaw trên macOS gồm 4 việc: chuẩn bị Node.js và npm, cài OpenClaw bằng một lệnh npm, nối "đầu não" AI qua Codex, rồi mở giao diện điều khiển ở 127.0.0.1:18789. Làm xong 4 việc này là bạn đã có một AI agent sống trên máy Mac, sẵn sàng nối tiếp với Telegram hay Discord để ra lệnh từ điện thoại.

Key Takeaways

OpenClaw cài trên macOS qua npm, chỉ một lệnh, không cần biết code.
Cần sẵn Node.js 20 trở lên (cài nhanh bằng Homebrew) và app Terminal của macOS.
"Đầu não" của agent ở bài này là Codex, đăng nhập bằng tài khoản ChatGPT, không phải dán API key.
Cài được trên cả máy Mac chip Apple Silicon (M1, M2, M3...) lẫn Mac chip Intel.
Cài xong là nối tiếp được với Telegram hoặc Discord để điều khiển agent từ điện thoại lẫn máy tính.

OpenClaw là gì và cài trên macOS để làm gì

OpenClaw là một gateway tự host, làm cầu nối giữa model AI và máy tính của bạn. Thay vì chat trên web của từng dịch vụ, bạn giao việc cho một agent chạy ngay trên máy Mac, nó đọc được, ghi được và thao tác thật trên máy trong phạm vi bạn cấp quyền.

Khác với chatbot kiểu hỏi gì đáp nấy, một AI agent nhận một việc rồi tự đi làm nhiều bước: tự tra cứu, tự viết, tự chạy lệnh, tự gửi tin nhắn. Vì OpenClaw chạy trên máy của bạn nên bạn giữ quyền kiểm soát dữ liệu và công cụ, không đẩy hết lên dịch vụ của người khác.

Cài trên máy Mac cũng tiện: macOS có sẵn Terminal, cài Node.js bằng Homebrew rất nhanh, và máy Mac thường để mở lâu nên hợp để giữ agent sống.

Chuẩn bị trước khi cài đặt OpenClaw trên macOS

Chuẩn bị 4 thứ sau để không khựng giữa chừng.

Node.js 20 trở lên và npm - OpenClaw cài qua npm nên đây là bắt buộc.
Một tài khoản AI để OpenClaw mượn "đầu não" - bài này dùng Codex (đăng nhập bằng tài khoản ChatGPT đã có quyền dùng Codex).
App Terminal của macOS - mở bằng Spotlight (nhấn Cmd + dấu cách, gõ "Terminal") hoặc vào Applications rồi Utilities. Từ macOS Catalina trở đi, shell mặc định là zsh, bạn không cần chỉnh gì thêm.
Một chút quyền terminal - bạn chỉ gõ vài lệnh có sẵn, không cần biết code.

Mở Terminal và kiểm tra Node.js, npm trên máy Mac

Trong Terminal, gõ 2 lệnh node -v và npm -v. Có số phiên bản hiện ra là máy đã sẵn sàng.

node -v
npm -v

Chưa có Node.js thì cài nhanh bằng Homebrew

Nếu một trong hai lệnh báo "command not found" nghĩa là máy chưa có Node.js. Cách nhanh nhất trên macOS là dùng Homebrew, trình quản lý gói phổ biến cho máy Mac:

brew install node

Cài xong, Homebrew tự đặt node và npm vào đúng đường dẫn (/opt/homebrew/bin trên máy Apple Silicon, /usr/local/bin trên máy Intel). Gõ lại node -v để chắc ăn. Cách này còn giúp tránh lỗi quyền truy cập khi cài gói npm toàn cục mà mình nói ở phần lỗi thường gặp.

Bước 1 - Cài đặt OpenClaw trên macOS bằng một lệnh npm

Cài OpenClaw trên máy Mac chỉ bằng một lệnh npm toàn cục.

Vẫn trong Terminal, chạy lệnh dưới đây. Phần --allow-scripts=openclaw cho phép gói chạy script cài đặt của chính nó.

npm install -g openclaw@latest --allow-scripts=openclaw

Chờ khoảng nửa phút là xong. Trong log bạn có thể thấy vài dòng npm warn install-scripts báo chặn mấy gói phụ như esbuild, koffi, protobufjs. Đây là cảnh báo bình thường, OpenClaw vẫn chạy tốt. Chỉ khi gặp lỗi liên quan bạn mới cần mở chúng theo đúng lệnh npm gợi ý ngay trong log.

Bước 2 - Chạy lệnh onboard và chọn chế độ Quick start

Cài xong, gõ lệnh khởi tạo:

openclaw onboard

OpenClaw hiện màn thiết lập kèm một dòng cảnh báo bảo mật quan trọng: agent này có quyền truy cập thật vào máy Mac của bạn. Ở câu "How would you like to start?", chọn Quick start (recommended) rồi Enter.

Đây là lúc hiểu rõ mình đang dựng cái gì: một trợ lý có thể đọc, ghi và thao tác trên máy bạn qua khung chat. Tiện, nhưng cũng là lý do các bước cấp quyền phía sau cần làm cẩn thận.

Bước 3 - Chọn tạo một agent duy nhất cho lần đầu dùng

Ở câu "What would you like to create?", chọn One agent (một agent duy nhất). Lựa chọn còn lại là dựng cả một đội agent, hợp với nhu cầu phức tạp hơn và chưa cần cho lần đầu cài đặt.

Bước 4 - Nối OpenClaw với "đầu não" AI qua Codex của OpenAI

OpenClaw không tự nghĩ, nó mượn một model AI làm đầu não. Ở đây là Codex của OpenAI.

OpenClaw quét máy và thấy sẵn Codex, nó tự cài Codex plugin.

Giải thích nhanh vì sao lại là Codex. OpenClaw chạy agent thông qua Codex Harness của OpenAI. "Harness" ở đây là bộ khung điều phối: nó không chỉ gọi model trả lời chữ, mà cho model đọc lệnh, gọi công cụ và thao tác trên máy theo từng bước. Nói gọn, model là bộ não, còn harness là tay chân và quy trình làm việc. Vì đi qua Codex nên bạn đăng nhập bằng tài khoản ChatGPT/Codex, không phải dán API key.

OpenClaw mở một tab Chrome để bạn đăng nhập tài khoản OpenAI.

Trang web sẽ xin một mã thiết bị 9 ký tự. Mã này in ngay trong Terminal (ví dụ BEI1-4FJMK), bạn chép sang trình duyệt. Mã hết hạn sau 15 phút và không được chia sẻ cho ai.

Bước 5 - Xác nhận Inference ready và mở giao diện OpenClaw trên macOS

Sau khi đăng nhập, OpenClaw chạy một bài kiểm tra kết nối. Màn hình báo Inference ready cùng dòng Inference verified là bộ não đã thông.

Để ý dòng về Gateway: nếu nó báo "service installation skipped", bạn cần tự chạy openclaw gateway run để bật cầu nối. Gateway là tiến trình giữ cho mọi thứ sống, có nó agent mới nhận và trả tin được.

openclaw gateway run

Khi xong, trình duyệt tự mở giao diện OpenClaw ở địa chỉ 127.0.0.1:18789. Đây là bảng điều khiển chính, nơi bạn xem trạng thái, chỉnh cài đặt và nối thêm kênh chat. Tới đây, phần cài đặt OpenClaw trên macOS coi như xong.

Giữ OpenClaw chạy nền trên máy Mac

Agent chỉ sống khi Gateway của OpenClaw còn chạy. Nếu bạn đóng cửa sổ Terminal đang chạy gateway, hoặc máy Mac vào chế độ ngủ (sleep), agent sẽ im.

Vài cách giữ cho nó sống trên máy Mac:

Để nguyên cửa sổ Terminal đang chạy openclaw gateway run, đừng đóng.
Chặn máy ngủ khi cần agent trực bằng lệnh caffeinate có sẵn của macOS. Mở một cửa sổ Terminal khác và chạy caffeinate -s, máy sẽ không tự ngủ chừng nào lệnh còn chạy.
Muốn chạy 24/7 thật sự thì nên đặt OpenClaw trên một máy luôn mở, ví dụ một máy chủ nhỏ (VPS) hoặc một chiếc Mac mini để ở nhà, thay vì máy làm việc hằng ngày.

Nối OpenClaw với Telegram hoặc Discord để ra lệnh từ điện thoại

Cài đặt xong, agent đã sống trên máy Mac nhưng mới chat được trong giao diện web ở máy. Bước tiếp theo là gắn cho nó một "cửa chat" để bạn ra lệnh từ bất cứ đâu. Đây là phần mở rộng, làm hay không tuỳ bạn, và cả hai hướng đều đi tiếp từ đúng bản cài đặt vừa xong.

Muốn nhắn cho agent như nhắn cho bạn bè, từ điện thoại lẫn máy tính, xem cách kết nối OpenClaw với Telegram qua BotFather.
Muốn ra lệnh và duyệt bài ngay trong server quen thuộc, xem cách kết nối OpenClaw với Discord qua Developer Portal.

Khi đã quen, bạn còn giao cho agent tự động đăng bài Facebook và Instagram mỗi ngày, với một bước duyệt qua chat trước khi lên trang.

Lỗi thường gặp khi cài đặt OpenClaw trên macOS và cách xử lý

Vài chỗ hay vướng khi cài trên máy Mac lần đầu, xử lý nhanh như sau.

node: command not found hoặc npm: command not found - máy chưa có Node.js. Cài bằng brew install node như ở phần chuẩn bị, rồi mở lại Terminal.
npm install -g báo lỗi quyền EACCES - thường gặp khi Node.js nằm ở đường dẫn hệ thống. Cách gọn nhất trên macOS là cài Node.js bằng Homebrew (brew install node), vì khi đó thư mục gói toàn cục thuộc về bạn, không cần sudo.
openclaw: command not found sau khi cài xong - thư mục chứa lệnh toàn cục của npm chưa nằm trong PATH. Đóng rồi mở lại Terminal, hoặc kiểm tra npm đang đặt lệnh ở đâu bằng npm config get prefix. Cài Node.js qua Homebrew thường không gặp lỗi này.
Agent không trả lời - kiểm tra Gateway có đang chạy không. Nếu không, chạy openclaw gateway run rồi thử lại.
Gateway báo "service installation skipped" - đây không phải lỗi, chỉ cần tự chạy openclaw gateway run để bật cầu nối.

Câu hỏi thường gặp về cài đặt OpenClaw trên macOS

Cài đặt OpenClaw trên macOS có cần biết code không?
Không, bạn chỉ cần gõ vài lệnh có sẵn trong Terminal và làm theo từng bước. Toàn bộ quy trình là cài qua npm, chạy openclaw onboard, đăng nhập tài khoản AI rồi làm theo wizard. Không phải viết dòng code nào.

Cài OpenClaw trên máy Mac có mất phí không?
OpenClaw là mã nguồn mở và miễn phí, còn phần AI thì tính theo tài khoản model bạn dùng. Ở hướng dẫn này, chi phí nằm ở tài khoản ChatGPT/Codex. Bạn cần một gói hoặc lượng credit còn hiệu lực thì agent mới trả lời. Chi phí thực tế tuỳ mức độ dùng.

Máy Mac chip Apple Silicon (M1, M2, M3) và máy Intel đều cài được chứ?
Được cả hai. OpenClaw cài qua npm và chạy trên Node.js, mà Node.js hỗ trợ cả máy Mac chip Apple Silicon lẫn chip Intel. Chỉ cần máy có Node.js 20 trở lên là chạy được, không phân biệt dòng chip.

Cài OpenClaw trên macOS khác gì trên Windows hay Linux?
Các lệnh npm và quy trình onboard gần như giống nhau, chỉ khác ở cách mở terminal và cài Node.js. Trên macOS bạn dùng app Terminal và Homebrew cho nhanh. Phần cài OpenClaw, nối Codex và pairing thì giống hệt các hệ điều hành khác.

Để OpenClaw chạy trên máy Mac như vậy có an toàn không?
Tương đối an toàn nếu bạn giữ chế độ pairing, không lộ token và chỉ cấp quyền vừa đủ. Agent có quyền thật trên máy, nên rủi ro nằm ở việc người lạ chiếm quyền. Khi nối kênh chat, luôn để pairing hoặc allowlist, giữ kín token và chỉ duyệt đúng tài khoản của mình.

Kết luận: cài xong OpenClaw trên macOS rồi làm gì tiếp

Cài đặt OpenClaw trên macOS không khó: chuẩn bị Node.js, cài bằng một lệnh npm, nối "đầu não" Codex rồi mở giao diện ở 127.0.0.1:18789. Chìa khoá là nhớ giữ Gateway chạy và cấp quyền cẩn thận vì agent thao tác thật trên máy Mac.

Cài xong, bước tự nhiên tiếp theo là gắn cho agent một cửa chat: kết nối OpenClaw với Telegram hoặc kết nối OpenClaw với Discord, rồi giao cho nó những việc lặp lại mỗi ngày.