Hướng dẫn sử dụng Bản OpenClaw

Tài liệu dành cho Workmate AI — Bản OpenClaw. Phiên bản ứng dụng: 2026.3.30 · Tiếng Việt · ← Quay về trang chủ

Lưu ý: Hướng dẫn này chỉ áp dụng cho Workmate AI bản OpenClaw. Bản OpenCode đang trong quá trình phát triển, tài liệu sẽ phát hành cùng bản chính thức.

Chương 1Giới thiệu

Workmate AI là ứng dụng desktop (Electron) dùng để điều khiển và tương tác với các AI agent trên nền tảng OpenClaw. Hiểu đơn giản: Workmate AI là giao diện đồ họa cho OpenClaw — quản lý agent, chat, tự động hóa, kết nối kênh nhắn tin, tất cả từ một cửa sổ duy nhất.

📌 Về nguồn gốc: Fork từ Neurons-ai/CrawBot, bổ sung thêm các tính năng cá nhân: RAG, LocalLLM, QuickSearch, WorkflowBuilder. Những tính năng này không có trong bản upstream gốc.

Workmate AI làm được gì

💬

Chat AI real-time

Streaming, extended thinking, file attachment

🤖

Quản lý nhiều Agent

Tạo, cấu hình, gán kênh cho từng agent

📡

Kênh nhắn tin

WhatsApp, Telegram, Zalo, Discord, Slack…

🧩

Skills Plugin

Mở rộng từ ClawHub marketplace

⚡

Tự động hóa

Workflows, Cron, Webhooks, Triggers

📚

RAG

Hỏi đáp theo nội dung tài liệu thực tế

🦙

LocalLLM

Chạy AI local qua Ollama, offline

🌐

Browser tích hợp

Web automation, cookie, CDP, OAuth

Chương 2Kiến trúc hệ thống

Workmate AI hoạt động theo mô hình 3 tầng: Renderer (UI) → Main Process (điều phối) → OpenClaw Gateway (AI engine).

┌─────────────────────────────────────────────────────────┐ │ Workmate AI Desktop App │ │ │ │ Renderer (React 19 + Zustand) Main Process (Node) │ │ src/pages/ src/stores/ ←IPC→ electron/main/ │ │ ipc-handlers.ts │ │ │ │ │ │ └──────────┬───────────┘ │ │ │ WebSocket JSON-RPC │ │ ▼ │ │ OpenClaw Gateway (:18789) │ │ AI Engine · Agent Runner · Skills │ └─────────────────────────────────────────────────────────┘

Các thành phần chính

Thành phần	Vị trí	Vai trò
Renderer	`src/`	Giao diện React, state Zustand
Main Process	`electron/main/`	Window, tray, IPC handlers, updater
Gateway Manager	`electron/gateway/`	Khởi động OpenClaw, WebSocket, OAuth patcher
Utils	`electron/utils/`	Config, paths, provider registry, UV/Python
OpenClaw	Child process	AI engine thực sự — chạy agent, tools, skills

💡 Ports: Dev :5173 (Vite) · Gateway :18789 · Production :23333

Chương 3Cài đặt lần đầu

Khi khởi động lần đầu, Workmate AI tự mở Setup Wizard.

Kiểm tra môi trường

Wizard tự check Node.js, Python, UV, build tools. Thiếu gì có nút cài tự động.

Chọn AI Provider

Nhập API key (Anthropic, OpenAI…) hoặc skip, cấu hình sau trong Settings.

Kết nối kênh nhắn tin

Tùy chọn — có thể bỏ qua và thêm sau trong Channels.

Cài Skills mặc định

Nên đồng ý để có các tool cơ bản ngay từ đầu.

Hoàn thành

Chuyển đến Dashboard.

Chương 4Dashboard

Trang chủ — hiển thị trạng thái tổng quan và lối tắt đến các tính năng chính.

Thẻ thông tin	Ý nghĩa
Gateway Status	Running / Stopped / Error + uptime
Channels	Số kênh nhắn tin đang kết nối
Skills	Số skills đang kích hoạt

💡 Dev Console: Bật Dev Mode (Settings → Developer) → Dashboard hiển thị nút mở OpenClaw web UI để debug Gateway trực tiếp.

Chương 5Chat với Agent

Tính năng cốt lõi — tương tác với AI agent theo thời gian thực, xem quá trình suy nghĩ và thực thi tool.

Bố cục giao diện

Khu vực	Chức năng
Chat Toolbar	Chọn session, model, toggle thinking, nút abort, token counter
Message List	Lịch sử chat — streaming, markdown, thinking blocks, tool cards
Chat Input	Soạn tin nhắn, đính kèm file/ảnh
File Tree	Browser workspace của agent (ẩn/hiện được)
Browser Panel	Trình duyệt tích hợp cho web automation (toggle)

Extended Thinking

Bật toggle Extended Thinking trên toolbar → agent hiển thị block "suy nghĩ" trước khi trả lời. Click vào block để mở rộng / thu gọn.

📌 Chỉ khả dụng với Claude 3.5 Sonnet trở lên.

Tool Execution

Agent gọi tool → Workmate AI hiển thị tool call card: tên tool · input · output · trạng thái (running / done / error).

Tools Auto-Approve: Settings → Chat → bật để agent tự chạy tool không cần xác nhận. Tắt để kiểm soát từng bước.

Token Counter

Toolbar hiển thị số token thực tế (input / output / cache) theo thời gian thực — theo dõi chi phí API.

Dừng Agent

Abort Stream — dừng response đang stream, agent vẫn chạy ngầm
Stop Agent — dừng hoàn toàn agent run hiện tại

Chương 6Quản lý Agents

Agent là "nhân vật AI" do bạn định nghĩa — system prompt riêng, model riêng, workspace riêng, gán được vào kênh nhắn tin.

Tạo Agent mới

New Agent

Góc trên phải trang Agents.

Cấu hình cơ bản

Chọn emoji icon, tên, mô tả ngắn.

Viết System Prompt

Định nghĩa vai trò, phong cách, nhiệm vụ cụ thể.

Chọn model mặc định

Model dùng khi không override trong Chat.

Cài đặt nâng cao	Mô tả
Workspace Path	Thư mục file agent có quyền đọc/ghi
Channel Binding	Gán agent làm "người trả lời" cho kênh nhắn tin cụ thể

Chương 7Kênh nhắn tin (Channels)

Kết nối Workmate AI với nền tảng chat bên ngoài. Agent tự trả lời khi có tin nhắn đến.

💚

QR pairing, multi-account

✈️

Bot token, webhook

🔵

Zalo

QR pairing

🎮

Discord

Bot token

💜

Slack

OAuth, workspace

📧

Email

SMTP/IMAP

Thêm kênh mới

Add Channel

Chọn platform từ dropdown.

Nhập credentials

Mỗi platform có trường riêng: Bot Token, API Key, Webhook URL…

Save

Gateway tự restart để áp dụng cấu hình mới.

Gán Agent

Chọn agent sẽ trả lời tin nhắn từ kênh này.

QR Code Pairing (WhatsApp, Zalo)

Click Request QR Code
Mở app điện thoại → quét mã
Kênh chuyển sang Connected

⚠️ QR code hết hạn sau ~60 giây. Nếu hết hạn, nhấn Request lại.

Session DM Scope

Giá trị	Ý nghĩa
`main`	Tất cả dùng chung một session
`per-peer`	Mỗi người dùng một session riêng
`per-channel-peer`	Mỗi người + kênh = một session
`per-account-channel-peer`	Chi tiết nhất: account + kênh + người

Chương 8Skills & Marketplace

Plugin mở rộng khả năng agent — tìm kiếm web, xử lý file, tích hợp API bên thứ ba. Quản lý qua ClawHub Marketplace.

Cài skill

Tab Marketplace

Gõ từ khóa tìm kiếm.

Xem chi tiết

Mô tả, phiên bản, yêu cầu API key.

Install

Chờ progress → skill xuất hiện tab Installed.

Cấu hình skill: Tab Installed → click skill → nhập API key, env variables → Save.

💡 Skills cần API key của service đó (vd: Brave Search key), không phải AI provider key.

Chương 9Workflows

Chuỗi tác vụ tự động hóa qua giao diện kéo thả (ReactFlow) — nối nhiều bước thành một quy trình hoàn chỉnh.

Node	Chức năng
Input	Điểm bắt đầu — nhận dữ liệu đầu vào
LLM	Gọi AI model để xử lý, phân tích, tạo nội dung
Output	Điểm kết thúc — xuất kết quả

Run — chạy thủ công ngay lập tức
Instances — xem lịch sử chạy, trạng thái, log
Enable/Disable — bật/tắt workflow
Cancel — dừng instance đang chạy

Chương 10Cron — Lịch hẹn tự động

Lên lịch để agent tự động thực thi tác vụ theo định kỳ.

New Job

Trang Cron → tạo mới.

Chọn lịch

Preset hoặc cron expression tùy chỉnh.

Nhập tác vụ

Prompt agent thực thi. Chọn AI model dùng cho job.

Save và Enable

Toggle bật → job tự chạy.

Cron Expression tham khảo

* * * * *      # Mỗi phút
0 * * * *      # Mỗi giờ
0 9 * * *      # Mỗi ngày lúc 9:00 sáng
0 9 * * 1      # Mỗi thứ Hai lúc 9:00
0 9 1 * *      # Ngày đầu tháng lúc 9:00

💡 Trigger Now: Chạy job ngay lập tức không cần chờ lịch — hữu ích khi test.

Chương 11RAG — Tri thức từ tài liệu Personal Feature

RAG (Retrieval-Augmented Generation) cho phép agent tham chiếu nội dung từ tài liệu bạn cung cấp — PDF, TXT, Markdown — thay vì chỉ dùng kiến thức training.

Tài liệu (PDF / TXT / MD) │ ▼ Embedding (vector hóa nội dung) Vector Database (local) │ ▼ Agent query: "tìm đoạn liên quan" Relevant chunks → thêm vào context của AI │ ▼ AI trả lời dựa trên nội dung thực tế của tài liệu

Index tài liệu

Vào trang RAG

Upload file

Hỗ trợ .pdf, .txt, .md. Kéo thả hoặc click chọn.

Chờ indexing

Xong → file xuất hiện với timestamp.

💡 Index tài liệu kỹ thuật, hướng dẫn, dữ liệu nội bộ. Agent trả lời dựa trên nội dung thực, không phải đoán.

Chương 12LocalLLM — Chạy AI offline qua Ollama Personal Feature

Tích hợp Ollama — chạy AI model trên máy, không cần API key, không phí cloud, hoàn toàn private.

📌 Yêu cầu: Cài Ollama trên máy trước (ollama.com). Workmate AI tự detect.

Thao tác	Cách làm
Xem models đã cài	Trang LocalLLM → danh sách tự load
Tải model mới	Nhập tên (vd: `llama3.2`) → Pull → chờ progress
Xóa model	Click Delete bên cạnh model

Dùng trong Chat: Settings → Providers → thêm Ollama provider → model local xuất hiện trong dropdown chọn model.

💡 Gợi ý model theo RAM:
8GB → llama3.2:3b, phi3:mini
16GB → llama3.2:8b, mistral:7b
32GB+ → llama3.1:70b-q4, qwen2.5:32b

Chương 13Trình duyệt tích hợp

Browser built-in (Chromium) cho phép agent thực hiện web automation — điều hướng, điền form, chụp ảnh, xuất PDF, quản lý cookies.

Tính năng	Mô tả
Multi-tab	Nhiều tab, mỗi tab có thể thuộc session khác nhau
Navigation	Back, Forward, Reload, nhập URL
Print to PDF	Xuất trang web thành PDF
Cookie Management	Import / Export / Clear cookies
CDP	Chrome DevTools Protocol cho automation nâng cao
Detach	Tách panel thành cửa sổ riêng

Web Authentication

Settings → Web Auth → Thêm provider (Google, GitHub…) → Login → browser mở trang đăng nhập → token lưu lại cho agent dùng.

Chương 14Quick Search Personal Feature

Popup nhỏ gửi câu hỏi đến agent ngay lập tức mà không cần mở full app.

Kích hoạt bằng phím tắt (cấu hình ở cấp hệ điều hành)
Popup xuất hiện giữa màn hình
Gõ câu hỏi → Enter
Workmate AI điều hướng về Chat và gửi tin nhắn
Esc để đóng

Chương 15Webhooks & HTTP Server

Nhận webhook từ service bên ngoài (GitHub, Stripe, Zapier…) và trigger agent phản hồi tự động.

New Webhook

Đặt tên và path cho endpoint.

Copy URL

Dán vào service bên ngoài.

Gán làm Trigger

Kết nối với Workflow hoặc Cron job.

Tab Logs trong mỗi webhook — xem tất cả request đã nhận, payload, thời gian, response code.

Chương 16AI Providers

🟠

Anthropic

Claude 3.5 Sonnet, Opus, Haiku

🟢

OpenAI

GPT-4o, GPT-4 Turbo, o1

🦙

Ollama

Local models, offline

⚙️

Custom

Bất kỳ API tương thích OpenAI

Settings → Providers → Add

Chọn loại provider

Nhập API Key → Validate

Kiểm tra key có hoạt động không.

Set as Default

Provider dùng khi không chỉ định cụ thể.

📌 OAuth (Anthropic): Có thể đăng nhập qua tài khoản Claude.ai thay vì API key riêng.

Chương 17Cài đặt ứng dụng

General

Cài đặt	Mô tả
Theme	Light / Dark / System
Language	EN / 中文 / 日本語 / Tiếng Việt
Launch at Startup	Tự khởi động cùng hệ điều hành
Start Minimized	Khởi động thu vào system tray

Gateway

Cài đặt	Mô tả
Auto-start	Tự khởi động OpenClaw Gateway khi mở app
Port	WebSocket port (mặc định 18789)

Chat & Automation

Cài đặt	Mô tả
Tools Auto-Approve	Agent tự chạy tool không cần xác nhận
Session DM Scope	Cách phân chia session theo người dùng kênh
Built-in Browser	Bật/tắt trình duyệt tích hợp
Screenshot Max Side	Giới hạn kích thước screenshot (px)

Chương 18Patcher — Anthropic OAuth Bypass Advanced

Hệ thống intercept luồng giao tiếp giữa OpenClaw và Anthropic API, cho phép dùng Claude qua tài khoản Anthropic.com thay vì API key.

⚠️ Tính năng nội bộ nâng cao. Chỉ chỉnh sửa nếu hiểu rõ cơ chế — sai cấu hình có thể làm gián đoạn kết nối.

Workmate AI → OpenClaw → LLM Patcher Proxy → Anthropic API │ Intercept & rewrite: • HTTP headers (xóa fingerprint) • Tool names (bypass signature check) • System prompt content • Response stream

Category	Chức năng
`system`	Rewrite nội dung system prompt
`tool_name`	Đổi tên tool để bypass signature check
`tool_desc`	Rewrite mô tả tool
`response`	Xử lý response từ API
`header`	Xóa/thêm HTTP headers

Settings → Patcher → text editor: enable/disable từng rule, chỉnh sửa pattern (hỗ trợ Regex).

Chương 19Cập nhật ứng dụng

Cài đặt	Mô tả
Update Channel	stable / beta / dev
Auto Check	Tự kiểm tra khi mở app
Auto Download	Tự tải về khi có bản mới

Mặc định autoDownload: false — app hỏi trước khi download. Sau khi tải xong, bản mới cài khi tắt app (autoInstallOnAppQuit: true).

Chương 20Quy trình Release

Bump version trong package.json

Format: YYYY.M.D — vd: 2026.4.11

Tag và push

git tag v2026.4.11
git push origin main --tags

Chuyển repo sang Public trên GitHub

Settings → Danger Zone → Change visibility → Public. Làm trước khi Actions chạy xong.

Chờ GitHub Actions (~15-30 phút)

Build mac/win/linux song song → publish GitHub Releases tự động.

Chuyển repo về Private

Sau khi release published.

⚠️ Quan trọng: Nếu repo Private khi app check update, electron-updater không fetch được latest.yml → auto-update không hoạt động. Phải Public trong lúc app đang check.

Chương 21Merge Upstream

Định kỳ merge code mới từ Neurons-ai/CrawBot để nhận tính năng và bugfix.

git fetch upstream
git merge upstream/main --no-commit --no-ff
# Resolve conflicts, restore personal features
git commit
git push origin main

Files phải restore sau mỗi lần merge

Upstream xóa các tính năng cá nhân. Luôn restore sau khi merge:

File	Tính năng
`src/pages/Rag/index.tsx`	RAG
`src/pages/LocalLLM/index.tsx`	Ollama Local LLM
`src/pages/QuickSearch.tsx`	Quick Search popup
`src/pages/WorkflowBuilder/index.tsx`	Visual Workflow Builder
`electron/main/rag.ts`	RAG backend
`electron/main/quick-search.ts`	Quick Search window
`electron/utils/ollama.ts`	Ollama API client
Routes trong `src/App.tsx`	/rag, /localllm, /quick-search, /workflow
Handlers trong `ipc-handlers.ts`	rag:, ollama:, quick-search handlers

git checkout HEAD -- \
  src/pages/Rag/index.tsx \
  src/pages/LocalLLM/index.tsx \
  src/pages/QuickSearch.tsx \
  src/pages/WorkflowBuilder/index.tsx \
  electron/main/rag.ts \
  electron/main/quick-search.ts \
  electron/utils/ollama.ts \
  src/App.tsx

Chương 22Xử lý sự cố

Gateway không khởi động

Kiểm tra port 18789: lsof -i :18789 (Mac/Linux) hoặc netstat -ano | findstr 18789 (Windows)
Xem logs: Settings → Developer → View Logs
Dashboard → Stop → Start để restart thủ công

Agent không trả lời

Kiểm tra API key: Settings → Providers → Validate
Kiểm tra Gateway đang Running (Dashboard)
Thử model khác để loại trừ model-specific issue
Clear session và tạo mới

Kênh mất kết nối

WhatsApp / Zalo: QR hết hạn → Request QR mới
Telegram: Kiểm tra Bot Token còn active
Restart Gateway sau khi cập nhật credentials

Auto-update không hoạt động

Kiểm tra repo đang Public trên GitHub
Settings → Updates → Check Now (kiểm tra thủ công)
Xác nhận đúng Update Channel (stable/beta/dev)

Workmate AI · v2026.3.30 · Tài liệu nội bộ · Cập nhật 2026-04-11