Cài đặt

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

TL;DR

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

Yêu cầu (khi chạy từ source)

  • Node >=22
  • pnpm
  • Docker (tùy chọn; chỉ cần cho containerized setup/e2e — xem Docker)

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

Nếu các bạn muốn “tùy chỉnh 100%” và dễ cập nhật, hãy giữ các thay đổi trong:

  • Config: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
  • Workspace: ~/.openclaw/workspace (skills, prompts, memories; nên làm thành private git repo)

Bootstrap một lần:

openclaw setup

Từ trong repo này, dùng CLI entry local:

openclaw setup

Nếu chưa cài global, chạy qua pnpm openclaw setup.

Quy trình ổn định (dùng app macOS)

  1. Cài đặt + khởi chạy OpenClaw.app (menu bar).
  2. Hoàn thành checklist onboarding/permissions (TCC prompts).
  3. Đảm bảo Gateway ở chế độ Local và đang chạy (app sẽ quản lý).
  4. Liên kết surfaces (ví dụ: WhatsApp):
openclaw channels login
  1. Kiểm tra:
openclaw health

Nếu onboarding không có trong 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).

Quy trình bleeding edge (Gateway trong terminal)

Mục tiêu: làm việc với TypeScript Gateway, có hot reload, giữ UI app macOS kết nối.

0) (Tùy chọn) Chạy app macOS từ source luôn

Nếu các bạn cũng muốn app macOS ở 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 có thay đổi TypeScript.

2) Trỏ app macOS vào Gateway đang chạy

Trong OpenClaw.app:

  • Connection Mode: Local App sẽ kết nối với gateway đang chạy trên port đã cấu hình.

3) Xác minh

  • Trạng thái Gateway trong app sẽ hiện “Using existing gateway …”
  • Hoặc qua CLI:
openclaw health

Lỗi thường gặp

  • Sai port: Gateway WS mặc định là ws://127.0.0.1:18789; giữ app + CLI cùng port.
  • Dữ liệu nằm ở đâu:
    • Credentials: ~/.openclaw/credentials/
    • Sessions: ~/.openclaw/agents/<agentId>/sessions/
    • Logs: /tmp/openclaw/

Sơ đồ lưu trữ credentials

Dùng cái này khi debug auth hoặc quyết định backup gì:

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram bot token: config/env hoặc channels.telegram.tokenFile
  • Discord bot token: config/env (chưa hỗ trợ token file)
  • Slack tokens: config/env (channels.slack.*)
  • Pairing allowlists: ~/.openclaw/credentials/<channel>-allowFrom.json
  • Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Legacy OAuth import: ~/.openclaw/credentials/oauth.json Chi tiết hơn: Security.

Cập nhật (mà không làm hỏng cấu hình)

  • Giữ ~/.openclaw/workspace và ~/.openclaw/ là “đồ của bạn”; đừng để prompts/config 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)

Bản cài Linux dùng systemd user service. Mặc định, systemd dừng user services khi logout/idle, làm tắt Gateway. Onboarding sẽ cố enable lingering cho bạn (có thể hỏi sudo). Nếu vẫn tắt, chạy:

sudo loginctl enable-linger $USER

Với server always-on hoặc multi-user, nên dùng system service thay vì user service (không cần lingering). Xem Gateway runbook để biết thêm về systemd.

Tài liệu liên quan