Setup

Lưu ý: Nếu bạn đang thiết lập lần đầu, hãy bắt đầu với Bắt đầu. Chi tiết trình hướng dẫn: Trình hướng dẫn Onboarding.

Cập nhật lần cuối: 2026-01-01

TL;DR

Tùy chỉnh nằm ngoài repo: ~/.openclaw/workspace (workspace) + ~/.openclaw/openclaw.json (cấu hình).
Workflow ổn định: cài ứng dụng macOS; để nó chạy Gateway đi kèm.
Workflow bleeding edge: tự chạy Gateway qua pnpm gateway:watch, rồi để ứng dụng macOS kết nối ở chế độ Local.

Yêu cầu (từ source)

Node >=22
pnpm
Docker (tùy chọn; chỉ cho thiết lập container/e2e — xem Docker)

Chiến lược tùy chỉnh (để cập nhật không đau)

Nếu bạn muốn “100% tùy chỉnh cho mình” và dễ cập nhật, giữ tùy chỉnh trong:

Cấu hình: ~/.openclaw/openclaw.json (JSON/JSON5)
Workspace: ~/.openclaw/workspace (skills, prompt, bộ nhớ; biến thành git repo private)

Bootstrap một lần:

openclaw setup

Từ trong repo này, dùng lối vào CLI cục bộ:

openclaw setup

Nếu chưa có cài đặt toàn cục, chạy qua pnpm openclaw setup.

Chạy Gateway từ repo này

Sau pnpm build, bạn có thể chạy CLI đã đóng gói trực tiếp:

node openclaw.mjs gateway --port 18789 --verbose

Workflow ổn định (ứng dụng macOS trước)

Cài và khởi chạy OpenClaw.app (thanh menu).
Hoàn thành checklist onboarding/quyền hạn (prompt TCC).
Đảm bảo Gateway đang ở Local và đang chạy (ứng dụng quản lý nó).
Liên kết giao diện (ví dụ: WhatsApp):

openclaw channels login

Kiểm tra nhanh:

openclaw health

Nếu onboarding không có trong bản build của bạn:

Chạy openclaw setup, rồi openclaw channels login, rồi khởi động Gateway thủ công (openclaw gateway).

Workflow bleeding edge (Gateway trong terminal)

Mục tiêu: làm việc trên TypeScript Gateway, hot reload, giữ UI ứng dụng macOS kết nối.

0) (Tùy chọn) Cũng chạy ứng dụng macOS từ source

Nếu bạn muốn ứng dụng macOS cũng ở bleeding edge:

./scripts/restart-mac.sh

1) Khởi động dev Gateway

pnpm install
pnpm gateway:watch

gateway:watch chạy gateway ở chế độ watch và reload khi TypeScript thay đổi.

2) Trỏ ứng dụng macOS đến Gateway đang chạy

Trong OpenClaw.app:

Connection Mode: Local Ứng dụng sẽ kết nối đến gateway đang chạy trên port đã cấu hình.

3) Xác minh

Trạng thái Gateway trong ứng dụng nên hiển thị “Using existing gateway …”
Hoặc qua CLI:

openclaw health

Lỗi thường gặp

Sai port: Gateway WS mặc định ws://127.0.0.1:18789; giữ ứng dụng và CLI cùng port.
Dữ liệu trạng thái nằm ở đâu:
- Thông tin đăng nhập: ~/.openclaw/credentials/
- Session: ~/.openclaw/agents/<agentId>/sessions/
- Log: /tmp/openclaw/

Bản đồ lưu trữ thông tin đăng nhập

Dùng khi debug xác thực hoặc quyết định backup gì:

WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram bot token: cấu hình/env hoặc channels.telegram.tokenFile (chỉ file thường; symlink bị từ chối)
Discord bot token: cấu hình/env hoặc SecretRef (provider env/file/exec)
Slack token: cấu hình/env (channels.slack.*)
Allowlist ghép nối:
- ~/.openclaw/credentials/<channel>-allowFrom.json (tài khoản mặc định)
- ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (tài khoản không mặc định)
Profile xác thực model: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Payload secret từ file (tùy chọn): ~/.openclaw/secrets.json
Import OAuth legacy: ~/.openclaw/credentials/oauth.json Chi tiết: Bảo mật.

Cập nhật (không phá thiết lập)

Coi ~/.openclaw/workspace và ~/.openclaw/ là “đồ của bạn”; đừng đặt prompt/cấu hình cá nhân vào repo openclaw.
Cập nhật source: git pull + pnpm install (khi lockfile thay đổi) + tiếp tục dùng pnpm gateway:watch.

Linux (systemd user service)

Cài đặt Linux dùng systemd user service. Mặc định, systemd dừng user service khi đăng xuất/rảnh, điều này giết Gateway. Onboarding cố gắng bật lingering cho bạn (có thể yêu cầu sudo). Nếu vẫn tắt:

sudo loginctl enable-linger $USER

Với server luôn bật hoặc đa người dùng, cân nhắc dùng system service thay vì user service (không cần lingering). Xem Runbook Gateway cho ghi chú systemd.

Tài liệu liên quan

Runbook Gateway (flag, giám sát, port)
Cấu hình Gateway (schema cấu hình + ví dụ)
Discord và Telegram (tag trả lời + cài đặt replyToMode)
Thiết lập trợ lý OpenClaw
Ứng dụng macOS (vòng đời gateway)