Xây dựng trợ lý cá nhân với OpenClaw

OpenClaw là một Gateway kết nối WhatsApp + Telegram + Discord + iMessage cho các Pi agent. Plugin bổ sung hỗ trợ Mattermost. Hướng dẫn này sẽ giúp các bạn thiết lập “trợ lý cá nhân”: một số WhatsApp riêng hoạt động như agent luôn sẵn sàng của bạn.

⚠️ An toàn trước tiên

Khi chạy agent, các bạn đang cho phép nó:

  • chạy các lệnh trên máy của bạn (tùy thuộc vào cấu hình Pi tool)
  • đọc/ghi file trong workspace của bạn
  • gửi tin nhắn ra ngoài qua WhatsApp/Telegram/Discord/Mattermost (plugin)

Hãy bắt đầu thận trọng:

  • Luôn thiết lập channels.whatsapp.allowFrom (đừng bao giờ để mở cho cả thế giới trên Mac cá nhân của bạn).
  • Dùng một số WhatsApp riêng cho trợ lý.
  • Heartbeat mặc định chạy mỗi 30 phút. Tắt nó đi cho đến khi bạn tin tưởng hệ thống bằng cách đặt agents.defaults.heartbeat.every: "0m".

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

  • Node 22+
  • OpenClaw có sẵn trong PATH (khuyên dùng: cài global)
  • Một số điện thoại thứ hai (SIM/eSIM/trả trước) cho trợ lý
npm install -g openclaw@latest
# hoặc: pnpm add -g openclaw@latest

Cài từ source (development):

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # tự động cài UI deps lần đầu chạy
pnpm build
pnpm link --global

Thiết lập hai điện thoại (khuyên dùng)

Các bạn nên làm như này:

Điện thoại của bạn (cá nhân)    Điện thoại thứ hai (trợ lý)
┌─────────────────┐           ┌─────────────────┐
│  WhatsApp của   │  ──────▶  │  WhatsApp trợ   │
│  bạn            │  tin nhắn │  lý             │
│  +1-555-YOU     │           │  +1-555-ASSIST  │
└─────────────────┘           └────────┬────────┘
                                       │ liên kết qua QR
                                       ▼
                              ┌─────────────────┐
                              │  Mac của bạn    │
                              │  (openclaw)     │
                              │    Pi agent     │
                              └─────────────────┘

Nếu bạn liên kết WhatsApp cá nhân với OpenClaw, mọi tin nhắn gửi đến bạn sẽ trở thành “đầu vào của agent”. Đó hiếm khi là điều bạn muốn.

Bắt đầu nhanh trong 5 phút

  1. Ghép nối WhatsApp Web (hiển thị mã QR; quét bằng điện thoại trợ lý):
openclaw channels login
  1. Khởi động Gateway (để nó chạy):
openclaw gateway --port 18789
  1. Đặt config tối thiểu vào ~/.openclaw/openclaw.json:
{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Giờ gửi tin nhắn đến số trợ lý từ điện thoại đã được cho phép.

Khi quá trình onboarding hoàn tất, hệ thống sẽ tự động mở dashboard với gateway token của bạn và in ra link có token. Để mở lại sau này: openclaw dashboard.

Tạo workspace cho agent (AGENTS)

OpenClaw đọc các hướng dẫn hoạt động và “bộ nhớ” từ thư mục workspace của nó.

Mặc định, OpenClaw dùng ~/.openclaw/workspace làm workspace cho agent, và sẽ tự động tạo nó (cùng với các file khởi đầu AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md) khi setup/chạy agent lần đầu. BOOTSTRAP.md chỉ được tạo khi workspace hoàn toàn mới (nó sẽ không xuất hiện lại sau khi bạn xóa).

Mẹo: coi thư mục này như “bộ nhớ” của OpenClaw và biến nó thành một git repo (tốt nhất là private) để các file AGENTS.md + memory được backup. Nếu đã cài git, workspace mới sẽ được tự động khởi tạo.

openclaw setup

Cấu trúc workspace đầy đủ + hướng dẫn backup: Agent workspace Quy trình làm việc với memory: Memory

Tùy chọn: chọn workspace khác bằng agents.defaults.workspace (hỗ trợ ~).

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

Nếu bạn đã có sẵn các file workspace từ một repo, bạn có thể tắt hoàn toàn việc tạo bootstrap file:

{
  agent: {
    skipBootstrap: true,
  },
}

Config biến nó thành “một trợ lý”

OpenClaw mặc định đã có thiết lập tốt cho trợ lý, nhưng thường bạn sẽ muốn điều chỉnh:

  • persona/hướng dẫn trong SOUL.md
  • cài đặt thinking mặc định (nếu muốn)
  • heartbeat (khi đã tin tưởng hệ thống)

Ví dụ:

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-5",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // Bắt đầu với 0; bật sau.
    heartbeat: { every: "0m" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080,
    },
  },
}

Session và memory

  • File session: ~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
  • Metadata session (token usage, last route, v.v.): ~/.openclaw/agents/<agentId>/sessions/sessions.json (cũ: ~/.openclaw/sessions/sessions.json)
  • /new hoặc /reset bắt đầu một session mới cho cuộc trò chuyện đó (có thể config qua resetTriggers). Nếu gửi một mình, agent sẽ trả lời một lời chào ngắn để xác nhận đã reset.
  • /compact [instructions] nén context của session và báo cáo budget context còn lại.

Heartbeat (chế độ chủ động)

Mặc định, OpenClaw chạy heartbeat mỗi 30 phút với prompt: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. Đặt agents.defaults.heartbeat.every: "0m" để tắt.

  • Nếu HEARTBEAT.md tồn tại nhưng thực tế trống (chỉ có dòng trống và markdown header như # Heading), OpenClaw sẽ bỏ qua heartbeat run để tiết kiệm API call.
  • Nếu file không tồn tại, heartbeat vẫn chạy và model sẽ quyết định làm gì.
  • Nếu agent trả lời HEARTBEAT_OK (có thể có thêm text ngắn; xem agents.defaults.heartbeat.ackMaxChars), OpenClaw sẽ không gửi tin nhắn ra ngoài cho heartbeat đó.
  • Heartbeat chạy full agent turn — khoảng thời gian ngắn hơn sẽ tốn nhiều token hơn.
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

Media vào và ra

File đính kèm đầu vào (ảnh/audio/docs) có thể được truyền vào lệnh của bạn qua template:

  • {{MediaPath}} (đường dẫn file tạm local)
  • {{MediaUrl}} (pseudo-URL)
  • {{Transcript}} (nếu bật audio transcription)

File đính kèm đầu ra từ agent: thêm MEDIA:<path-or-url> trên một dòng riêng (không có khoảng trắng). Ví dụ:

Đây là screenshot.
MEDIA:https://example.com/screenshot.png

OpenClaw sẽ trích xuất chúng và gửi dưới dạng media cùng với text.

Checklist vận hành

openclaw status          # trạng thái local (creds, sessions, queued events)
openclaw status --all    # chẩn đoán đầy đủ (read-only, có thể paste)
openclaw status --deep   # thêm gateway health probe (Telegram + Discord)
openclaw health --json   # snapshot gateway health (WS)

Log nằm trong /tmp/openclaw/ (mặc định: openclaw-YYYY-MM-DD.log).

Bước tiếp theo