Cẩm nang Quản trị 11 Menu trong GoClaw

Các menu trong tài liệu này xoay quanh vòng đời dữ liệu của agent:

1.1 Khái niệm cơ bản: 2 loại Agent

Khi tạo agent, bạn phải chọn 1 trong 2 loại — và không đổi được sau này. Đây là quyết định nền tảng nhất.

1.2 Trang Danh sách Agent

Khi click vào menu Agent ở thanh bên trái, bạn vào trang này — nơi quản lý tất cả agent đã tạo. Đây là điểm bắt đầu của mọi thao tác.

Có gì trên trang này?

Mỗi thẻ Agent hiển thị gì?

Trên mỗi card agent, bạn thấy đầy đủ những thông tin sau (xem lại ảnh giao diện thật):

1.3 Tạo Agent mới — Đi từng ô một

Khi bấm + Tạo agent, một cửa sổ pop-up mở ra. Hãy đi qua từng ô theo thứ tự:

Khối 1: Định danh agent

Khối 2: Bộ não agent (Provider & Model)

Khối 3: Mô tả agent của bạn

Đây là khối quan trọng nhất vì nó quyết định "tính cách" của agent. Có 2 phần:

Khối 4: Tự tiến hóa

Khối 5: Chế độ System Prompt — Chọn 1 trong 4

Đây là "độ dày" của hướng dẫn ban đầu mà agent đọc trước khi trả lời mỗi tin nhắn. Càng dày càng thông minh nhưng tốn tiền hơn.

Sau khi điền xong, bấm Tạo ở góc dưới bên phải. Agent sẽ xuất hiện trên trang danh sách.

1.4 Trang chi tiết Agent — Bố cục chung

Khi click vào 1 agent từ danh sách, bạn vào trang chi tiết. Trên cùng là thanh đầu trang:

5 tab chính bên dưới

1.5 Tab Agent — Phần "Chế độ System Prompt"

Đây là phần đầu tiên bạn thấy khi mở tab Agent. Hiển thị 4 thẻ tương ứng 4 chế độ — bấm vào thẻ nào để chọn chế độ đó. Mỗi thẻ kèm danh sách "khối" sẽ được nhúng vào prompt:

1.6 Tab Agent — Phần "Cá tính Agent"

Đây là nơi tinh chỉnh "danh tính" của agent. Bao gồm:

1.7 Tab Agent — "Mô hình & Ngân sách"

Phần này quyết định agent dùng "bộ não" gì và được tiêu bao nhiêu tiền mỗi tháng.

1.8 Cấu hình Heartbeat (Nhịp tim) — Nút trái tim

Heartbeat là tính năng cho agent chủ động gửi tin nhắn định kỳ — không phụ thuộc user nhắn trước. Như cú "check-in" hàng ngày của agent với bạn.

Mở: Bấm nút Tắt (hoặc Bật) ở thanh đầu trang chi tiết agent — biểu tượng trái tim đỏ. Dialog "Cấu hình Heartbeat" mở ra.

Khối "Kích hoạt"

Khối "MODEL"

Mô tả: "Ghi đè provider/model cho heartbeat. Để trống để dùng mặc định của agent."

Khối "GỬI KẾT QUẢ"

Khối "LỊCH HOẠT ĐỘNG"

Ghi chú phía dưới: "Để trống để chạy 24/7."

Cài đặt nâng cao (collapsible)

Mở rộng để tinh chỉnh sâu hơn — retry, suppress on OK, v.v. (đa số người mới có thể bỏ qua).

DANH SÁCH KIỂM TRA (HEARTBEAT.MD)

"Hướng dẫn được đưa vào mỗi lần chạy heartbeat. Hỗ trợ markdown."

Đây là checklist agent đọc mỗi lần check-in — bạn viết những điều agent cần kiểm tra/báo cáo. Ví dụ:

# Danh sách kiểm tra Heartbeat
- Tổng hợp 3 đơn hàng mới nhất
- Kiểm tra inbox có khách chờ trả lời không
- Báo cáo nếu có lỗi trong 1 giờ qua

Buttons cuối cùng

• Chạy thử: Test heartbeat ngay lập tức để xem kết quả trước khi enable.
• Hủy: Đóng dialog, bỏ thay đổi.
• Lưu: Lưu cấu hình.

1.9 Dialog "Nâng cao" — Nút bánh răng ⚙️

Bấm nút bánh răng ở thanh đầu trang để mở dialog Nâng cao. Đây là nơi tập trung mọi cấu hình "kỹ thuật" — chia thành nhiều khối:

Khối "Workspace"

Khối "Memory & Knowledge Graph"

"Kiểm soát cô lập memory và knowledge graph giữa các người dùng".

Khối "Chia sẻ Workspace"

"Kiểm soát cách cô lập file workspace giữa các người dùng".

Bên dưới là phần Thư mục Workspace — cụ thể chọn user nào được phép truy cập (nếu bật chia sẻ).

Khối "Subagents (Agent con)"

Cho phép agent này spawn (tạo ra) các agent con để làm song song nhiều việc.

Khối "Tool Policy" (Chính sách công cụ)

• Profile: chọn gói preset — full (đầy đủ), coding (lập trình), messaging (chat), minimal (tối thiểu).
• Allow / Deny / Also Allow: 3 danh sách để bật, cấm, hoặc bổ sung tool ngoài profile.
• Tool Call Prefix: Tiền tố xóa khi LLM gọi tool — chỉ cần khi dùng MCP có prefix.

Khối "Sandbox" (Docker)

Cấu hình môi trường cô lập để agent chạy code (như Python, Bash) an toàn.

Khối "Thinking / Reasoning"

Bật suy luận mở rộng (extended thinking) cho task phức tạp.

• Reasoning Mode: inherit (theo provider default) / custom
• Thinking Level: off / low / medium / high
• Reasoning Effort (expert): off đến xhigh
• Fallback Behavior: downgrade / provider_default / off

Khuyên: Để inherit trừ khi làm task toán/code phức tạp. Thinking tốn token rất đắt.

Khối "Memory" (Bộ nhớ agent)

Mẹo: Agent "quên" → hạ Min Score về 0.25. Agent "nhớ rác" → nâng lên 0.5.

Khối "Compaction" + "Context Pruning"

Khi nào động vào? Mặc định ổn. Nếu agent hay "lú" cuối cuộc trò chuyện dài → giảm Max History Share xuống 0.75.

Bấm Lưu cấu hình ở đáy dialog để áp dụng.

1.10 Tab Agent — Phần "Skills" và "Pinned Skills"

• Skills List: danh sách kỹ năng đã cấp cho agent. Mỗi skill là 1 file SKILL.md hướng dẫn agent làm 1 loại task chuyên biệt (xem Menu Skill).
• Pinned Skills (Skill được ghim): tối đa 10 skill được nhúng thẳng vào system prompt — agent không cần gọi skill_search để tìm. Phù hợp với skill thường xuyên dùng.

1.11 Tab Agent — Phần "Orchestration" (Phối hợp)

Phần này chỉ hiển thị, không sửa được. Nó tóm tắt quan hệ agent với agent khác:

• Mode: spawn (đứng riêng), delegate (có Agent Link gửi việc cho agent khác), team (thành viên Team).
• Delegate Targets: danh sách agent có thể gửi việc tới.
• Team: tên team đang tham gia.

Cấu hình thật ở menu Agent Link & Team.

1.12 Tab Agent — Phần "ChatGPT OAuth Routing"

Chỉ hiện khi provider là chatgpt_oauth với nhiều tài khoản ChatGPT Plus.

• Strategy: primary_first (ưu tiên tài khoản chính) / round_robin (xoay vòng) / priority_order (theo thứ tự định sẵn).
• Extra Providers: thêm tài khoản phụ vào pool routing để tránh rate limit.

1.13 Tab Agent — Phần "Self-Evolution" (chỉ Predefined)

• Self-Evolution (false): Bật metrics → suggestion → auto-adapt.
• Skill Learning (false): Tự khám phá skill mới.
• Skill Nudge Interval (15%): Tần suất gợi ý skill mới cho agent.
• Evolution Metrics / Suggestions: Thu thập metric, đề xuất cải tiến.

1.14 Tab "Tệp" — Files

Quản lý các file ngữ cảnh nền của agent — đây là "ký ức gốc" mà agent luôn đọc:

• SOUL.md — Linh hồn, tính cách cốt lõi
• IDENTITY.md — Danh tính, vai trò
• USER.md — Thông tin về user (per-user, chỉ Predefined)
• HEARTBEAT.md — Checklist heartbeat (xem mục 1.8)
• ...và các file khác bạn upload thêm

• Regenerate Bootstrap Files (chỉ Predefined): Tái tạo SOUL/IDENTITY/USER khi đổi preset hoặc sửa lỗi cấu trúc.
• System Prompt Preview: Xem prompt thật ở 4 chế độ (giống nút System Prompt ở header).

1.15 Tab "Phân quyền" — Permissions

Cấp quyền cho user nào được sửa cấu hình agent ở từng phần:

• Config Type: file_writer (sửa file), heartbeat, cron, context_files, hoặc * (tất cả)
• User ID: ai được cấp
• Scope: phạm vi (agent, group:*, group:<id>)
• Permission: allow hoặc deny

Khuyên: tối thiểu quyền. * chỉ cho admin tuyệt đối tin cậy. Luôn kèm Scope cụ thể, không để global.

1.16 Tab "Evolution" (chỉ Predefined)

Hiển thị bảng metrics tiến hóa và danh sách gợi ý cải tiến từ AI. Có nút Apply / Reject cho từng suggestion. Có Guardrails (hàng rào) ngăn thay đổi nguy hiểm.

1.17 Tab "Phiên bản người dùng" (chỉ Predefined)

Liệt kê các "instance" của agent với từng user — mỗi user có file USER.md và state riêng. Tiện cho việc xem agent đang làm việc với những ai và tình trạng riêng từng người.

1.18 Tóm tắt — Khi tạo agent xong, làm gì tiếp?

1. ✅ Vào trang chi tiết, bấm System Prompt (con mắt) → đọc kỹ prompt LLM thực sự thấy.
2. ✅ Vào phần Mô hình & Ngân sách → đặt Budget Monthly (đừng để vô hạn).
3. ✅ Cấp 1-2 Skills phù hợp + ghim 3 skill cốt lõi nhất.
4. ✅ Mở dialog Nâng cao → kiểm tra Sandbox, Workspace Sharing (nên tắt hết khi mới bắt đầu).
5. ✅ Test thử: vào menu Trò chuyện, chọn agent, gửi vài tin nhắn xem agent phản hồi đúng tính cách chưa.
6. ✅ Khi ok, link agent với Channel (Telegram, Slack...) ở menu Channel.
7. ✅ Sau 1 tuần dùng, xem Usage để theo dõi chi phí thực tế và điều chỉnh.

2.1 Hiểu nhanh: Team vs Agent Link

2.2 Vào menu — 2 tab ở thanh trên cùng

Khi click vào menu Agent Link & Team ở thanh bên trái, bạn vào trang có tiêu đề "Agent Team" kèm dòng phụ "Quản lý các agent team của bạn". Bên dưới là 2 tab:

TAB 1 — AGENT TEAM (Nhóm)

2.3 Trang danh sách Team — Có gì trên màn hình?

Tab Agent Team mở ra một thanh công cụ + lưới các Team. Lần lượt từ trái sang phải:

Mỗi thẻ Team hiển thị

Trên mỗi card team, bạn sẽ thấy:

2.4 Tạo Team mới — Đi từng ô một

Bấm + Tạo Team, dialog "Tạo Team" mở ra với 4 trường:

Bấm Tạo ở góc dưới (đang xám cho đến khi đủ điều kiện: có tên + có lead + ≥1 member). Khi tạo xong, toast hiện "Đã tạo nhóm".

2.5 Trang chi tiết Team — Bố cục Bảng Kanban

Click vào card team → vào trang chi tiết. Khác với Agent (có nhiều tab), Team mở thẳng vào Bảng Kanban với phần header ở trên cùng.

Header — Thanh đầu trang

Từ trái sang phải:

Bảng Kanban — Phần chính

Đây là chỗ team thực sự "làm việc". Có 3 phần:

Thanh công cụ phía trên Kanban:

Cột Kanban: Hiển thị tasks chia theo trạng thái (mặc định): Chờ xử lý → Đang chạy → Chờ duyệt → Đã hoàn thành. Mỗi task là một thẻ chứa: tiêu đề, badge trạng thái, người phụ trách, độ ưu tiên, ID task.

Trạng thái rỗng: "Không có task — Chat với agent của team để tạo task" — gợi ý người dùng tạo task qua chat thay vì tạo thủ công.

2.6 Dialog "Thành viên" — Quản lý người trong team

Mở từ nút Thành viên ở header. Title hiện "Thành viên (N)" với N là số members.

Có gì trong dialog?

3 vai trò (badge màu)

Xóa member: Hover lên dòng → hiện nút ở phải. Lead không có nút này.

2.7 Dialog "Cài đặt" — Trái tim của Team

Mở từ nút Cài đặt ở header. Đây là dialog dài nhất, chia thành nhiều khối. Title hiện: {Tên Team} + {badge status} + {badge v2 Super Team}.

Khối tổng quan (đầu dialog)

Card xám hiển thị nhanh: Mô tả, Trưởng nhóm, Số thành viên.

Khối "Thông báo" (Notifications)

Đây là 7 toggle quyết định team gửi notification khi nào. Click toggle để bật/tắt:

Sub-khối "Chế độ gửi" (notifyMode)

Hint: "Cách thông báo được gửi đến kênh chat." 2 lựa chọn radio:

Khối "Không gian làm việc" (Workspace Scope)

Card gradient xanh ngọc, có tiêu đề "Phạm vi workspace" + hint "Kiểm soát cách tổ chức tệp trong workspace của team."

Click chọn 1 trong 2 thẻ:

Khối "Yêu cầu thành viên" (Member Requests)

Khối "Escalation khi bị chặn" (Blocker Escalation)

Card gradient cam-đỏ, icon .

Khối "Nhắc nhở theo dõi" (Follow-up Reminders)

Card gradient amber-vàng, icon đồng hồ. Có 2 trường:

Khối "Kiểm soát truy cập người dùng" (Access Control — Users)

Khối "Hạn chế channel" (Access Control — Channels)

Nút Lưu

Cuối dialog, nút Lưu cài đặt (kèm icon ). Khi đang lưu hiện "Đang lưu...". Toast thành công: "Đã lưu".

2.8 Dialog "Không gian làm việc" — Workspace

Mở từ nút Không gian làm việc trên thanh công cụ Kanban. Đây là nơi xem các file dùng chung của team.

2.9 Dialog "Nhật ký hoạt động" — Audit Logs

Mở từ nút Nhật ký hoạt động trên header. Hiện timeline mọi sự kiện trong team, mỗi sự kiện có badge loại:

Trạng thái rỗng: "Chưa có sự kiện". Có nút Tải thêm để paginate.

2.10 Dialog "Tính năng Super Team" (v2)

Mở khi click vào badge gradient v2 Super Team ở header. Title: "Tính năng Super Team" + badge Beta.

Liệt kê 9 tính năng có sẵn ở phiên bản v2:

Note Beta cuối dialog: "Một số tính năng đang ở giai đoạn Beta.". Nút Đã hiểu để đóng.

TAB 2 — AGENT LINK (Liên kết)

2.11 Trang danh sách Agent Link

Bấm tab Agent Link ở thanh trên. Trang gồm:

Header

Bảng danh sách (6 cột)

Trạng thái rỗng: "Chưa có liên kết agent nào."

Xác nhận xóa: dialog title "Xóa liên kết", nội dung "Xóa liên kết agent này? Không thể hoàn tác.", nút Xóa đỏ.

2.12 Dialog Tạo / Sửa liên kết

Title đổi theo ngữ cảnh: "Tạo liên kết" hoặc "Sửa liên kết". Có 5 trường:

2 nút cuối: Hủy / Tạo (hoặc Lưu khi sửa). Nút Tạo/Lưu xám đến khi đủ điều kiện (source ≠ target và đủ trường bắt buộc).

2.13 Tóm tắt — Khi nào tạo Team, khi nào dùng Link?

2.14 Checklist hoàn chỉnh sau khi tạo Team

1. ✅ Tạo Team với Lead phù hợp + 3-7 members predefined
2. ✅ Vào Cài đặt → kiểm tra: Workspace = Cô lập; Notifications bật đúng các loại quan trọng (Giao + Thất bại + Hoàn thành + Tạo mới)
3. ✅ Nếu cần kiểm soát: thêm vào Người dùng được phép hoặc Channel được phép
4. ✅ Bật Blocker Escalation để task không bị treo
5. ✅ Đặt Follow-up Reminders: 60 phút / max 5
6. ✅ Xem Tính năng Super Team v2 để biết những gì mình đang có
7. ✅ Tạo task thử qua chat với Lead → quan sát task xuất hiện trên Kanban
8. ✅ Sau 1 tuần, mở Nhật ký hoạt động review xem có sự kiện bất thường không

3.1 Hiểu nhanh: Session là gì?

Session = lịch sử 1 cuộc hội thoại giữa 1 người dùng và 1 agent trên 1 kênh cụ thể. Mỗi session có:

• 1 mã định danh duy nhất (gọi là session key)
• Tất cả tin nhắn (cả của user và của agent)
• Thông tin: ai chat, kênh nào, agent nào, đã có bao nhiêu tin, dùng bao nhiêu token
• Có thể có 1 đoạn tóm tắt tự động (nếu hội thoại đã dài)

3.2 Trang danh sách Session — Có gì trên màn hình?

Khi click menu Session ở thanh bên trái, bạn vào trang có:

Trạng thái rỗng

• Nếu chưa có session nào: "Chưa có session nào — Các session sẽ xuất hiện ở đây khi bạn bắt đầu trò chuyện."
• Nếu search không tìm thấy: "Không tìm thấy session phù hợp — Thử từ khóa tìm kiếm khác."

3.3 Bảng 5 cột — Hiểu từng cột

Click vào dòng nào sẽ vào trang chi tiết của session đó.

3.4 Hiểu cột "Ngữ cảnh" — Thanh tiến trình màu

Đây là cột quan trọng nhất để biết agent có "đầu đầy chữ" chưa. Ví dụ một thanh trông như: ▓▓▓▓▓▓░░░░ 12K / 200K · 🔄 2

Cách tính phần trăm

Phần trăm đầy = tokens hiện tại / (context window × 0.75). Tức là khi đạt 75% của context window thì thanh đã 100% — vì 25% còn lại dành cho dự phòng (response của agent).

3 mức màu

Số bên dưới thanh

Vd 12K / 200K · 🔄 2 nghĩa là:

• 12K — token hiện tại trong session
• 200K — context window tối đa của model agent đang dùng
• 🔄 2 — đã nén lịch sử 2 lần. Hover vào sẽ thấy tooltip "Đã nén N lần". Số này càng cao = session đã rất dài, đã nén nhiều lần.

3.5 Hiểu mã Session Key

Session key là chuỗi mã trông phức tạp nhưng có quy luật rõ ràng:

agent:<tên-agent>:<phần-scope>

Ví dụ thực tế và ý nghĩa:

3.6 Trang chi tiết Session — Bố cục

Click vào dòng session nào → vào trang chi tiết. Layout chia 3 phần (trên xuống):

Phần 1 — Header (đầu trang)

Bên trái:

Bên phải — 2 nút action:

Phần 2 — Tóm tắt (Summary, nếu có)

Block nền xám nhạt nằm dưới header, có:

• Chữ "Tóm tắt: " đậm
• Đoạn tóm tắt nội dung session (do agent tự tạo khi consolidation chạy)
• Nếu nội dung dài (>3 dòng) sẽ bị cắt + có nút "Xem thêm" / "Thu gọn"

Khi nào có tóm tắt? Khi session đã đủ dài và worker Episodic đã consolidate (xem Menu Bộ nhớ). Session ngắn thì chưa có.

Phần 3 — Danh sách tin nhắn

Vùng cuộn ở giữa, hiển thị tất cả tin nhắn theo thứ tự thời gian. 2 loại tin chính:

Trạng thái rỗng: nếu chưa có tin nào → hiển thị "Không có tin nhắn trong session này" ở giữa.

Lưu ý kỹ thuật: Tin nhắn role tool bị ẩn (vì đã được nhúng vào assistant message kèm theo). Tin assistant chỉ hiện khi có content/tool_calls/thinking.

3.7 Dialog "Đặt lại phiên" — Reset

Bấm nút Đặt lại ở góc phải header → hiện dialog xác nhận:

Sau khi đặt lại: messages list trống, session key vẫn còn, agent vẫn nhớ tên session, kênh vẫn pair. User có thể tiếp tục chat từ đầu mà không cần thiết lập lại.

Toast khi xong: "Đã đặt lại session". Nếu lỗi: "Không thể đặt lại session".

3.8 Dialog "Xóa session" — Delete

Bấm nút Xóa (màu đỏ) → dialog xác nhận:

Sau khi xóa: Session biến mất khỏi danh sách. Khi user chat lại, nếu là kênh ngoài (Telegram/Slack...) phải pair lại hoặc nhắn theo chính sách của channel (open/allowlist) → tạo session MỚI hoàn toàn (key mới, lịch sử trắng).

Toast khi xong: "Đã xóa session". Nếu lỗi: "Không thể xóa session".

3.9 Khi nào dùng "Đặt lại" vs "Xóa"?

3.10 Tự động cập nhật (Auto-refresh)

Khi bạn đang xem chi tiết 1 session và agent vừa hoàn thành 1 turn (vd: user vừa chat → agent reply xong), trang sẽ tự refresh trong 2 giây để hiện tin nhắn mới — bạn không cần F5.

Cụ thể: hệ thống lắng nghe các sự kiện WebSocket: run.completed, run.failed, run.cancelled. Khi sự kiện đến cho đúng agent của session đang xem → debounced 2s → reload messages.

3.11 Những trường ẩn — Metadata thêm

Mỗi session có metadata kỹ thuật (không hiển thị trực tiếp nhưng có trong API):

{
  key, messageCount, created, updated, label, channel, userID,
  metadata: {
    display_name,    // tên hiển thị user (vd: "Nguyễn Văn A")
    username,        // username (vd: @nguyenvana)
    chat_title,      // tên nhóm chat (vd: "Marketing Team")
    peer_kind        // "direct" hoặc "group"
  },
  model, provider,
  inputTokens, outputTokens,
  agentName,
  estimatedTokens, contextWindow,
  compactionCount    // số lần đã nén lịch sử
}

Bạn không cần nhớ — hệ thống tự xử. Chỉ cần biết những trường này tồn tại nếu cần debug qua API.

3.12 Tóm tắt — Quy trình quản trị Session

1. 📋 Theo dõi định kỳ: Vào menu Session 1 lần/tuần để biết có bao nhiêu session active, kênh nào nhiều nhất.
2. 🔍 Kiểm tra cột "Ngữ cảnh": Nếu nhiều session có thanh đỏ hoặc 🔄 cao → cấu hình lại agent (tăng context window, giảm history_limit).
3. 🏷️ Đặt label cho session quan trọng (Phỏng vấn, Họp với khách VIP) — dễ tìm sau.
4. 🧹 Reset session khi user chuyển chủ đề — tránh ngữ cảnh cũ làm "lú" agent.
5. 🗑️ Xóa session test sau khi xong — giữ DB sạch.
6. 👀 Xem chi tiết session bị lỗi: Nếu user phàn nàn agent trả lời sai, vào session đó, đọc messages + xem SystemMessageBlock có thông báo lỗi gì không.
7. 📊 Đối chiếu với menu Usage: Số tokens in/out ở session detail dùng để hiểu cost từng cuộc trò chuyện.

4.1 Hiểu nhanh: Channel là gì?

Mỗi Channel Instance = 1 cấu hình cụ thể cho 1 nền tảng giao tiếp. Mỗi instance có:

• Tên duy nhất (slug, vd: my-telegram-bot)
• Loại (telegram / discord / slack / zalo_oa / zalo_personal / whatsapp / facebook / pancake)
• Credentials (token, API key... được mã hóa AES-256-GCM phía server)
• Cấu hình (chính sách DM/Group, giới hạn media, streaming...)
• Trạng thái (đang chạy, đã tắt, lỗi xác thực...)
• Agent gán kèm — agent nào sẽ trả lời tin nhắn từ channel này

4.2 Trang danh sách Channel — Có gì trên màn hình?

Click menu Channel → trang có tiêu đề "Channel" + dòng phụ "Quản lý các phiên bản channel". Bao gồm:

Trạng thái rỗng:

• Chưa có: "Không có channel nào — Thêm phiên bản channel đầu tiên để bắt đầu."
• Search không khớp: "Không tìm thấy channel phù hợp — Thử từ khóa tìm kiếm khác."

4.3 Trạng thái channel — 7 mức + biểu tượng

Cột Trạng thái hiển thị 1 trong 7 badge — sắp xếp theo độ ưu tiên cần xử lý:

Nếu có {{N}} lỗi liên tiếp, hiển thị thêm dòng "Mở chi tiết channel để xem chẩn đoán mới nhất". Mỗi loại lỗi có gắn nhãn:

• Xác thực — credential sai
• Cấu hình — config sai
• Mạng — không kết nối được
• Cần chú ý — lỗi không xác định

4.4 Bảng 6 cột — Hiểu từng cột

4.5 Tạo channel mới — Wizard nhiều bước

Bấm + Thêm channel, dialog "Tạo phiên bản channel" mở ra. Một số channel (Zalo Personal, WhatsApp) cần wizard nhiều bước, còn lại chỉ 1 bước.

Bước 1 — Thông tin chung (luôn có)

Cuối: Hủy / Tạo. Khi đang lưu hiện "Đang lưu...". Toast khi xong: "Đã tạo channel".

Bước 2 — Xác thực (chỉ Zalo Personal & WhatsApp)

Sau khi tạo, dialog hiện QR code để quét bằng điện thoại:

4.6 Credentials theo loại channel

Mỗi loại channel có bộ credentials riêng. Tất cả đều mã hóa AES-256-GCM phía server. Khi sửa, để trống nghĩa là giữ giá trị cũ — hệ thống không bao giờ trả credential cũ về UI.

4.7 Chính sách DM & Group — 4 mức an toàn

Đây là cấu hình quan trọng nhất để chống spam và lạm dụng. Áp dụng cho hầu hết channel:

4.8 Cấu hình theo loại channel — Bảng tổng hợp

Mỗi loại channel có bộ field config riêng. Tất cả có chung: dm_policy, group_policy, require_mention, history_limit, allow_from, block_reply. Khác biệt nổi bật từng loại:

4.9 Trang chi tiết Channel — 5 Tab

Click vào dòng channel → vào trang chi tiết. Có 5 tab ngang:

Bên cạnh tabs còn có nút "Nâng cao" mở dialog cài đặt nâng cao (Network, Limits, Streaming, Behavior, Access Control).

4.10 Tab "Chung"

Hiển thị thông tin định danh — đa phần read-only. Các trường có thể sửa:

Nút Lưu thay đổi cuối tab. Toast: "Đã lưu".

4.11 Tab "Cấu hình"

Hiển thị toàn bộ field config theo loại channel — render thành form thân thiện (không phải JSON thô). Field hiện theo điều kiện showWhen: ví dụ Feishu chọn Webhook mode mới hiện webhook_port + webhook_path.

Nút Lưu cấu hình. Khi save: "Đang lưu...". Toast: "Đã lưu".

4.12 Tab "Thông tin xác thực"

Hint: "Để trống các trường để giữ giá trị hiện tại. Thông tin xác thực được mã hóa phía máy chủ và không bao giờ trả về trong phản hồi API."

Mỗi field type "password" (mask hiển thị). Khi cập nhật:

• Trường nào điền giá trị mới → save vào DB
• Trường nào để trống → giữ nguyên giá trị cũ
• Không có cách nào "xem lại" credential cũ

Nút Cập nhật thông tin xác thực. Toast: "Đã lưu". Lỗi: "Lưu thất bại".

4.13 Tab "Nhóm" — Override per-group/per-topic (Telegram)

Tiêu đề: "Ghi đè nhóm & chủ đề". Hint: "Ghi đè mặc định channel theo cuộc trò chuyện nhóm hoặc chủ đề diễn đàn. Dùng \"*\" làm ID nhóm cho mặc định ký tự đại diện."

Cách dùng

1. Nhập ID nhóm (vd: -100123456 hoặc * wildcard) → bấm Thêm nhóm
2. Bên dưới có "Nhóm đã biết" — list các group bot đã tham gia, click để add nhanh
3. Mỗi nhóm có thể chứa nhiều chủ đề (topic) — nhập ID topic + bấm Thêm chủ đề

Field override (tristate: Inherit / Có / Không)

Use case: Bot ở nhiều nhóm, mỗi nhóm có rules riêng — vd nhóm VIP open + có skill đặc biệt; nhóm spam disabled.

4.14 Tab "Quản lý" — Managers

Mô tả: "Quản lý người dùng có quyền quản lý trong cuộc trò chuyện nhóm."

Hiển thị

• Nhóm: Liệt kê các group có managers. Mỗi group có "{N} quản lý viên".
• Trống: "Không có nhóm quản lý — Dùng biểu mẫu bên dưới để thêm quản lý viên vào nhóm."
• Bảng managers: ID người dùng / Tên / Tên đăng nhập

Form thêm manager mới

Tiêu đề: "Thêm quản lý viên vào nhóm mới". Hint: "Thêm quản lý viên vào nhóm chưa xuất hiện trong danh sách trên."

Lỗi: "ID nhóm và ID người dùng là bắt buộc". Nút Thêm quản lý viên.

4.15 Dialog "Nâng cao" — Advanced

Tiêu đề: "Cài đặt nâng cao". Banner: "Xem chẩn đoán mới nhất của channel này trước khi thay đổi cài đặt."

Chia 6 khối collapsible:

4.16 Dòng thời gian sự cố — Diagnostics

Khi channel có vấn đề, tab chính có khối "Dòng thời gian" hiển thị:

Trạng thái rỗng: "Chưa có lần kiểm tra channel nào gần đây."

Banner cảnh báo đặc biệt:

• "Cần xác thực": "Channel đã được bật nhưng cần đăng nhập trước khi có thể kết nối." → Nút "Kết nối lại phiên channel"
• "Thiếu thông tin xác thực": "Channel đã được bật nhưng thiếu thông tin xác thực bắt buộc." → Nút "Điền thông tin xác thực bắt buộc"

4.17 Checklist setup channel chuẩn production

1. ✅ Tạo channel với Khóa rõ ràng (vd support-bot-prod)
2. ✅ Điền credentials đầy đủ → kiểm tra trạng thái chuyển Đang chạy
3. ✅ Đặt DM Policy = pairing và Group Policy = pairing
4. ✅ Set webhook_secret nếu là channel webhook-based (Facebook/Pancake/Zalo OA)
5. ✅ Chat thử từ user thật → kiểm tra agent trả lời đúng
6. ✅ Vào tab Quản lý thêm admin nếu cần (Telegram group)
7. ✅ Vào tab Nhóm override nếu có nhóm cần xử lý đặc biệt
8. ✅ 1 tuần sau: Kiểm tra Diagnostics — nếu Failure Streak >5 → rotate token
9. ✅ 90 ngày sau: Rotate credential định kỳ
10. ✅ Tách bot dev và bot prod (token khác nhau, instance khác nhau)

5.1 Hiểu nhanh: Skill là gì?

Skill = 1 thư mục chứa file SKILL.md và (tuỳ chọn) các file kèm theo. SKILL.md có 2 phần:

• YAML frontmatter (bắt buộc): khai báo name, description, license
• Nội dung Markdown: hướng dẫn chi tiết, code mẫu, công thức xử lý task

---
name: pdf
description: Use this skill whenever the user wants to do anything with PDF files
license: Proprietary
---

# Hướng dẫn xử lý PDF
[nội dung dài...]

Khi agent cần làm việc nào đó (vd "trích văn bản từ PDF"), agent sẽ tìm trong danh sách skill được cấp → đọc SKILL.md phù hợp → làm theo.

5.2 Trang danh sách Skill — Có gì trên màn hình?

Click menu Skill → trang có tiêu đề "Skill" + dòng phụ "Quản lý skill và khả năng của agent". Bao gồm:

Header — 3 nút action

2 Tab — Hệ thống vs Tùy chỉnh

Mỗi tab có badge số lượng cạnh tên: vd "Hệ thống (12)", "Tùy chỉnh (3)".

Search + Empty

• Ô search: "Tìm kiếm skill..." — lọc theo name + description
• Trạng thái rỗng: "Chưa có skill — Chưa có skill nào được đăng ký."
• Search không khớp: "Không tìm thấy skill phù hợp — Thử từ khóa tìm kiếm khác."

5.3 Bảng danh sách — Cột thay đổi theo tab

Tab "Hệ thống"

Tab "Tùy chỉnh"

Có thêm 2 cột:

Cột Thao tác có thêm: Edit + Delete.

5.4 Tenant Override — Đa tenant

Khi bạn vào dưới góc nhìn 1 tenant cụ thể (không phải master), mỗi skill có thêm phần override per-tenant:

Use case: Tenant A bật web_search dùng provider Exa, tenant B muốn tắt → override tenant B.

5.5 Panel "Missing Dependencies"

Nếu có skill thiếu dependency (Python package, npm package), panel cảnh báo hiện ở đầu trang:

Cảnh báo Runtime thiếu

Nếu container không có Python/Node:

5.6 Dialog "Tải lên Skill" — Upload ZIP

Bấm Tải lên ở tab Tùy chỉnh. Title: "Tải lên Skill". Description: "Tải lên tệp ZIP chứa SKILL.md với YAML frontmatter (name, description, slug)."

Khu vực drop file

Khung lớn ở giữa: "Nhấp hoặc kéo thả tệp .zip". Khi kéo file vào: "Thả tệp .zip vào đây". Chỉ chấp nhận .zip: "Chỉ chấp nhận tệp .zip".

Validation lúc upload

Mỗi file ZIP đi qua các kiểm tra:

Multi-skill ZIP

1 ZIP có thể chứa nhiều skill (mỗi sub-folder = 1 skill). Hệ thống detect và hiện: "Phát hiện {{N}} kỹ năng". Mỗi skill có badge:

• Mới — skill chưa có
• Không đổi — đã có và content giống hệt → hệ thống skip: "Nội dung không đổi — đã bỏ qua"
• Slug trùng với kỹ năng hệ thống — bị từ chối

Trạng thái upload

• Đang validate: "Đang xác thực..." với badge "{{X}} / {{Y}} hợp lệ"
• Đang upload: "Đang tải lên...". Nút: "Tải lên ({{N}})"
• Hoàn thành: "{{X}} / {{Y}} đã tải lên thành công". Nút Xong
• Lỗi: "Tải lên thất bại"
• Mỗi file có nút Xóa tệp để loại trước khi upload

5.7 Dialog "Chỉnh sửa skill" — Edit metadata

Bấm icon ở dòng skill custom. Title: "Chỉnh sửa skill".

Cuối: Hủy / Lưu. Đang lưu: "Đang lưu...". Toast: "Đã cập nhật skill".

5.8 Dialog "Chi tiết skill" — Xem nội dung + files + versions

Click vào tên skill → mở dialog chi tiết. Title: "Chi tiết skill". Có:

5.9 Toggle Bật/Tắt + Xóa

Toggle bật/tắt

Mỗi skill có Switch ở cột Thao tác. Tooltip:

• "Bật skill" khi đang tắt
• "Tắt skill" khi đang bật
• "Đã tắt" hiển thị badge khi disabled

Xóa skill (chỉ Custom)

Icon . Confirm dialog:

• Title: "Xóa skill"
• Mô tả: "Bạn có chắc chắn muốn xóa \"{{name}}\"? Hành động này không thể hoàn tác."
• Nút: Xóa (đỏ)

Toast: "Đã xóa skill".

5.10 Best practices khi quản trị Skill

1. 📝 Description rõ ràng: Bắt đầu bằng "Use this skill whenever..." — đây là input chính cho BM25 search. Mô tả tốt giúp agent tìm đúng skill.
2. 🎯 1 skill / 1 năng lực: Chia nhỏ thay vì gộp. Vd: pdf-extract, pdf-merge tốt hơn 1 cái pdf-everything.
3. 📦 Upload ZIP nhỏ: 1 skill / 1 ZIP để debug dễ. Multi-skill chỉ khi đã ổn.
4. 🔒 Visibility mặc định "Internal": Chỉ Public với skill đã kiểm định kỹ — tránh agent dùng nhầm.
5. 🏷️ Gắn Tags theo domain (marketing, coding, finance) — admin tìm nhanh.
6. ⚙️ Cài deps trước khi enable: Vào Missing Dependencies panel → install hết → bật skill.
7. 🔄 Rescan Deps định kỳ: Sau khi upgrade GoClaw hoặc cài thêm package.
8. 🏢 Tenant override khi cần: Tenant nhạy cảm (banking, health) → tắt skill rủi ro cao.
9. 📚 Theo dõi version: Mỗi lần sửa SKILL.md tăng version (v1 → v2). Detail dialog cho phép xem version cũ.

6.1 Hiểu nhanh: Công cụ tích hợp là gì?

"Công cụ tích hợp" (Built-in Tools) là bộ tool đóng gói sẵn trong GoClaw — không cần cài thêm. Khi agent cần làm việc gì đó cụ thể (đọc file, search web, tạo ảnh), nó gọi tool tương ứng.

Khác với Skill (sách hướng dẫn) và MCP (kết nối bên ngoài), built-in tools là khả năng cốt lõi đi kèm sản phẩm.

6.2 Trang danh sách Công cụ tích hợp — Có gì trên màn hình?

Click menu Công cụ tích hợp → trang có tiêu đề "Công cụ tích hợp" + dòng phụ "Quản lý các công cụ tích hợp sẵn. Bật/tắt hoặc cấu hình cài đặt toàn cục."

Banner cảnh báo (nếu có): "{{N}} công cụ cần cấu hình provider để agent sử dụng đầy đủ năng lực."

Trạng thái rỗng:

• Chưa khởi tạo: "Không có công cụ tích hợp — Chưa có công cụ tích hợp nào được khởi tạo."
• Search không khớp: "Không tìm thấy công cụ phù hợp — Thử từ khóa tìm kiếm khác."

6.3 Danh mục — 14 nhóm tool

Tool được nhóm theo category, hiển thị theo thứ tự cố định:

Knowledge Graph: knowledge_graph_search nằm trong nhóm Bộ nhớ.

6.4 Mỗi dòng tool hiển thị gì?

Trong mỗi nhóm category, mỗi tool là 1 row chứa:

6.5 Dialog "Cài đặt" — Mỗi tool có form khác nhau

Click Cài đặt → dialog title "Cài đặt — {{name}}". Tùy tool, hiển thị 1 trong các form:

1️⃣ Web Search Provider Chain

Title: "Chuỗi nhà cung cấp tìm kiếm web". Description: "Kéo để sắp xếp lại nhà cung cấp tìm kiếm. Nhà cung cấp đầu tiên được bật với API key hợp lệ sẽ được thử trước."

4 provider có sẵn (kéo-thả thứ tự):

Mỗi provider có:

• Số kết quả tối đa (max_results) — mặc định 5
• API Key — input password. Nếu đã có: hiện "✓ Đã có key" + nút "Thay đổi". Placeholder: "Nhập API key" hoặc "Nhập key mới để thay thế"
• Badge "Dự phòng luôn bật" với DuckDuckGo (luôn enabled)

2️⃣ Web Fetch Extractor Chain

Title: "Web Fetch — Chuỗi bộ trích xuất". Description: "Danh sách bộ trích xuất nội dung theo thứ tự. Mỗi URL được thử từ trên xuống cho đến khi một bộ trả về nội dung chất lượng."

3️⃣ Text-to-Speech (TTS) Mở rộng v3.10.0

Title: "Chuyển văn bản thành giọng nói". Description: "Cấu hình provider TTS và cài đặt tự động".

Trạng thái

Badge ở đầu: "Đã cấu hình" / "Đã tắt" / "Chưa cấu hình provider TTS". Khi đã chạy: "Provider chính: {{provider}}, Tự động: {{auto}}".

Cài đặt chung

Cài đặt theo Provider — 5 form khác nhau

OpenAI: API Key, API Base URL, Model, Giọng nói, Tốc độ (0.25-4.0), Định dạng đầu ra (mp3/opus/aac/flac/wav/pcm), Hướng dẫn (chỉ với gpt-4o-mini-tts).

ElevenLabs: API Key, Base URL, Voice ID, Model ID. Voice settings: Độ ổn định (0=biến đổi, 1=ổn định), Độ tương đồng (0=sáng tạo, 1=giống gốc), Phóng đại phong cách, Tăng cường giọng, Tốc độ (0.7-1.2). Nâng cao: Chuẩn hoá văn bản (auto/on/off), Seed (tái tạo kết quả), Độ trễ streaming (0-4), Mã ngôn ngữ ISO 639-1.

Edge (Miễn phí): Hint "Edge TTS miễn phí, không cần API key. Cài đặt: pip install edge-tts". Params: Tốc độ nói (-50% đến +100%), Cao độ (-50Hz đến +50Hz), Âm lượng (-50% đến +100%).

MiniMax: API Key, Group ID * (bắt buộc, placeholder "Bắt buộc cho MiniMax"), API Base, Model, Voice ID. Params: Tốc độ (0.5-2.0), Âm lượng (0.01-10.0), Cao độ (-12 đến +12 nửa cung), Cảm xúc, Chuẩn hoá văn bản. Audio: format (mp3/pcm/flac/wav), sampleRate, bitrate (chỉ MP3), kênh (mono/stereo).

Google Gemini (Mới v3.10.0): API Key, API Base URL, Giọng đọc, Mô hình. Tính năng đặc biệt:

• Nhiều người nói — hỗ trợ tối đa 2 người nói (multi-speaker mode). Thêm/xóa speaker với tên + giọng riêng.
• Thẻ âm thanh — chèn thẻ biểu cảm như [laughs] trực tiếp vào văn bản. Có panel tìm thẻ với 4 nhóm: Cảm xúc, Nhịp độ, Hiệu ứng, Chất lượng giọng.
• Badge "Xem trước" — nghe trước voice character (style).

Voice Picker chung (PortalVoicePicker — mới v3.10.0)

Dùng cho mọi provider. Chức năng:

• Làm mới — load lại danh sách voice từ provider
• Nghe thử / Dừng — preview voice tại chỗ. Lỗi: "Không nghe thử được — đang làm mới"
• Nhập voice_id thủ công nếu provider có voice không trong list
• Trạng thái: "Đang tải giọng đọc…", "Chưa có giọng đọc", "Lưu API key trước để tải giọng đọc", "Vui lòng cấu hình provider TTS trước"

Test Connection + Playground

• Kiểm tra kết nối: "Đang kiểm tra…" → "Kết nối thành công" hoặc "Kết nối thất bại"
• Thử nghiệm (Playground) — Textarea "Nhập văn bản để nghe thử…", nút Phát / Dừng. Trạng thái: "Đang tổng hợp…". Lỗi: "Phát âm thất bại". Nếu chưa chọn provider: "Chọn provider ở trên để bật phát thử."

Per-Agent Override (mới v3.10.0)

Mỗi agent có thể có TTS riêng — vào trang chi tiết agent, khối "Ghi đè giọng đọc cho agent này":

• Bật toggle để override
• Hint "Kế thừa: {{provider}} · {{voice}} · {{model}}" — biết đang inherit từ đâu
• Tinh chỉnh params (tốc độ, cảm xúc, style...) khác với cấu hình toàn cục

Use case: Agent CSKH dùng giọng nữ ấm; Agent công bố tin tức dùng giọng nam trang trọng. Override chỉ chỗ cần — không phải tạo provider mới.

Trạng thái rỗng

Nếu chưa cấu hình: "Chưa cấu hình TTS — Cấu hình provider TTS để bật giọng đọc cho agent.". Nút Cấu hình TTS. Nếu user không phải owner: "Liên hệ chủ workspace để cấu hình TTS."

Cài đặt nâng cao

Mỗi provider có khu Advanced thu gọn. Badge: "{{N}} cài đặt nâng cao".

4️⃣ Knowledge Graph Settings

Title: "Cài đặt đồ thị tri thức". Description: "Cấu hình trích xuất thực thể từ lần ghi bộ nhớ. Yêu cầu provider/mô hình hỗ trợ đầu ra JSON có cấu trúc."

5️⃣ Media Provider Chain (cho create_image, create_audio, create_video, read_*)

Title: "{{tên tool}} — Chuỗi provider". Description: "Cấu hình và sắp xếp các provider dự phòng. Kéo để sắp xếp lại — provider đầu tiên được thử trước."

6️⃣ JSON Settings (fallback cho tool không có form chuyên biệt)

Title: "Cài đặt: {{name}}". Description: "Chỉnh sửa cài đặt công cụ dưới dạng JSON. Thay đổi có hiệu lực ngay sau khi lưu."

• Textarea JSON với syntax highlighting
• Nút Định dạng JSON để format đẹp
• Validate: "Cú pháp JSON không hợp lệ" hoặc "JSON không hợp lệ"

Mọi dialog: nút Hủy / Lưu. Đang lưu: "Đang lưu...". Toast: "Đã lưu cài đặt". Lỗi: "Không thể lưu cài đặt".

Nếu tool không có cấu hình: "Không có cài đặt có thể cấu hình cho công cụ này."

6.6 Tenant Override

Khi truy cập dưới góc nhìn tenant (không phải master), mỗi tool có thêm:

6.7 Best practices khi quản trị Built-in Tools

1. 🔧 Chỉ bật tool agent thực sự cần: Tool "đắt" (browser, exec, subagent spawn) → tắt cho agent client-facing.
2. 🔑 Cấu hình API key cho Web Search: Production nên có Exa hoặc Tavily (chất lượng cao). DuckDuckGo dự phòng miễn phí.
3. 🎤 TTS auto mode "Tắt" mặc định — chỉ bật Có thẻ hoặc Luôn luôn khi nghiệp vụ cần audio.
4. 🖼️ Media tool cần provider chain: Bật xong phải vào Settings cấu hình ít nhất 1 provider — banner cam sẽ nhắc.
5. 🧠 KG auto-extract: Bật nếu agent xử lý nhiều thực thể (CRM, support). Min confidence 0.7-0.8.
6. 🛒 Nhanh.vn: Cấu hình app_id + business_id + access_token ở settings nhanh_* tool.
7. 🏢 Tenant nhạy cảm tắt tool rủi ro: Banking, health → tắt exec, browser.
8. ⚠️ Chú ý "Cấu hình qua trang Config": Một số tool phải sửa ở menu Config — không sửa được ở đây.
9. 🔍 Xem banner cảnh báo: Nếu có tool media bật mà chưa cấu hình → vào quick-config trên banner cam.

7.1 Hiểu nhanh: MCP là gì?

MCP (Model Context Protocol) = chuẩn mở do Anthropic giới thiệu để LLM kết nối với tool/dữ liệu bên ngoài. Mỗi MCP Server expose một bộ tool — agent gọi tool đó như tool thường.

Khác với Built-in Tools (đóng gói sẵn) và Skill (hướng dẫn), MCP là plugin từ bên ngoài — bạn cài thêm khi cần.

7.2 Trang danh sách MCP Servers — Có gì trên màn hình?

Click menu MCP → trang có tiêu đề "MCP Servers" + dòng phụ "Quản lý kết nối máy chủ Model Context Protocol".

Trạng thái rỗng:

• Chưa có: "Không có MCP server — Thêm MCP server đầu tiên để bắt đầu."
• Search không khớp: "Không tìm thấy máy chủ phù hợp — Thử từ khóa tìm kiếm khác."

7.3 Thêm MCP Server — 2 lựa chọn

Bấm + Thêm máy chủ, dropdown hiện 2 cách tạo:

7.4 Bảng 7 cột — Hiểu từng cột

7.5 Form tạo MCP Server tùy chỉnh — Đi từng ô

Title: "Thêm MCP Server" (hoặc "Chỉnh sửa MCP Server" khi sửa).

Khối 1 — Định danh

Khối 2 — Giao thức (Transport) *

Dropdown 3 lựa chọn — quyết định các trường bên dưới:

Lỗi validate: "Lệnh là bắt buộc cho giao thức stdio" hoặc "URL là bắt buộc cho giao thức SSE/HTTP".

Khối 3 — Stdio: Lệnh + Tham số (chỉ khi transport=stdio)

Khối 4 — HTTP/SSE: URL + Headers (chỉ khi transport=SSE/HTTP)

Khối 5 — Biến môi trường (mọi transport)

Khối 6 — Cấu hình nâng cao

Test Connection trước khi save

Có nút Kiểm tra kết nối. Khi bấm:

• Đang test: "Đang kiểm tra..."
• Thành công: "Tìm thấy {{N}} công cụ"
• Lỗi: "Kết nối thất bại"

Khuyên: Luôn test trước khi save — để chắc connection đúng và biết MCP expose những tool gì.

Cuối: Hủy / Tạo (hoặc Cập nhật). Đang lưu: "Đang lưu...". Toast: "Đã tạo MCP server".

7.6 Dialog "Xem công cụ" — Tools

Bấm Xem công cụ ở cột Thao tác. Title: "Công cụ — {{name}}". Sub-title: "tiền tố: {{prefix}}".

7.7 Dialog "Quản lý quyền" — Grants

Bấm Quản lý quyền. Title: "Quyền agent - {{name}}". Mặc định: "Tất cả công cụ được phép" cho mọi agent. Bạn có thể tạo grant chi tiết để hạn chế.

Khu vực "Quyền hiện tại"

Liệt kê các grant đã có: agent + tool allow list + tool deny list. Mỗi grant có nút Edit/Delete.

Form "Thêm quyền agent"

Nút Cấp quyền (hoặc Cập nhật). Toast: lỗi "Cấp quyền thất bại" / "Thu hồi quyền thất bại".

7.8 Dialog "Thông tin xác thực" — User Credentials

Khi MCP server bật "Yêu cầu Credentials riêng", mỗi user phải tự cấu hình. Bấm credentials button ở row → mở dialog.

2 ngữ cảnh hiển thị

3 loại credential

Buttons: Lưu / Xóa (1 user) / Xóa tất cả (mọi user) / Hủy.

Toast: "Đã lưu thông tin xác thực", "Đã xóa thông tin xác thực". Lỗi: "Lưu credentials thất bại", "Xóa credentials thất bại".

Hint quan trọng cho bot user: "Người dùng chat (Telegram, Discord...) cần được gộp vào tenant user qua trang Contacts trước khi có thể thiết lập credentials riêng."

7.9 Reconnect & Delete

Reconnect

Nút Kết nối lại ở cột Thao tác. Force reset connection nếu MCP bị lag/lỗi. Toast: "Đã reset kết nối MCP server". Lỗi: "Không thể kết nối lại MCP server".

Delete

Confirm dialog:

• Title: "Xóa MCP Server"
• Mô tả: "Bạn có chắc muốn xóa \"{{name}}\"? Tất cả quyền liên quan cũng sẽ bị xóa."
• Nút: Xóa (đỏ)

Toast: "Đã xóa MCP server".

7.10 Best practices khi quản trị MCP

1. 🧪 Test connection trước khi save: Tránh tạo server "ma" không kết nối được.
2. 🏷️ Đặt tool prefix rõ ràng: github_, notion_, jira_ — tránh trùng tool name giữa các MCP.
3. ⏱️ Timeout hợp lý: Mặc định 60s đủ cho hầu hết MCP. Tăng nếu MCP fetch dữ liệu lớn (vd Notion full database).
4. 🔐 Yêu cầu Credentials riêng: Bật cho MCP có quyền cá nhân (GitHub OAuth, Slack user token). Tắt cho MCP system-wide (read-only API).
5. 🛡️ Grants chi tiết: Agent client-facing → deny tool nguy hiểm (delete, write, payment). Agent dev → allow all.
6. 🔄 Reconnect khi MCP lag: Nếu thấy tool calls timeout liên tục → bấm Kết nối lại.
7. 📋 Xem tool sau khi tạo: Bấm Xem công cụ để biết MCP expose những tool nào, giúp viết description agent chính xác.
8. 🔧 Stdio cho local, HTTP/SSE cho remote: Stdio đơn giản nhưng phải cài server local. HTTP linh hoạt nhưng cần endpoint public/private.
9. 🧹 Xóa MCP không dùng: Mỗi MCP active = 1 connection + tool registration → tốn resource.

8.1 Hiểu nhanh: Tác vụ định kỳ là gì?

Mỗi Cron Job = 1 "lịch hẹn" để agent tự thực thi 1 việc cụ thể. Job có:

• Lịch chạy — cron / mỗi N giây / một lần
• Tin nhắn cho agent — "việc cần làm" gửi cho agent xử lý
• Agent được giao việc (hoặc agent mặc định)
• Trạng thái bật/tắt
• Tùy chọn nâng cao: gửi kết quả qua kênh nào, múi giờ, tự xóa sau khi chạy...

8.2 Trang danh sách Tác vụ định kỳ — Có gì trên màn hình?

Click menu Tác vụ định kỳ → trang có tiêu đề "Tác vụ định kỳ" + dòng phụ "Lên lịch các tác vụ agent định kỳ".

Trạng thái rỗng:

• Chưa có: "Không có tác vụ định kỳ — Tạo tác vụ định kỳ để lên lịch các tác vụ agent định kỳ."
• Search không khớp: "Không tìm thấy tác vụ — Thử từ khóa khác."

8.3 Bảng 6 cột — Hiểu từng cột

8.4 Tạo Tác vụ định kỳ — Đi từng ô

Bấm + Tác vụ mới. Title: "Tạo tác vụ định kỳ".

Cuối: Hủy / Tạo. Đang tạo: "Đang tạo...". Toast: "Đã tạo tác vụ định kỳ".

8.5 Loại lịch — 3 lựa chọn

Cú pháp Cron — 5 trường

┌────── phút (0-59)
│ ┌──── giờ (0-23)
│ │ ┌── ngày tháng (1-31)
│ │ │ ┌── tháng (1-12)
│ │ │ │ ┌── thứ (0-6, 0=Chủ nhật)
* * * * *

Ví dụ thực tế:

8.6 Trang chi tiết Cron Job — 2 tab

Click vào dòng job → vào trang chi tiết. Có 2 tab:

Header trang chi tiết — 3 nút action

• Chạy ngay — kích hoạt job ngay lập tức (không đợi lịch). Đang chạy: "Đang chạy...". Toast: "Đã kích hoạt tác vụ định kỳ".
• Bật/Tắt — toggle nhanh
• Xóa — xóa vĩnh viễn (confirm dialog)

8.7 Tab "Tổng quan" — Các khối cấu hình

Khối "Lịch" + "Tin nhắn"

Hiển thị lịch hiện tại + tin nhắn nội dung. Bấm Sửa để chỉnh. Có nút Xem trước nếu muốn render trước.

Trạng thái rỗng: "Chưa có tin nhắn".

Khối "Agent & Trạng thái"

• Agent đang gán
• Trạng thái: "đã bật" / "đã tắt" / "đang chạy..."

Khối "Thông tin" (read-only)

Khối "Tải trọng" (Payload)

Nếu job có payload kèm theo (advanced): hiển thị JSON. Trống: "(trống)".

Khối "Giao nhận" (Delivery)

Mô tả: "Chuyển kết quả công việc đến kênh hoặc người dùng". Cấu hình:

Khi đã cấu hình: hiển thị "Gửi: trực tiếp", "Channel: {{name}}", "Đến: {{name}}".

Khối "Vòng đời" (Lifecycle)

Mô tả: "Cài đặt vòng đời công việc".

Khối "Lên lịch" (Scheduling)

Mô tả: "Cấu hình múi giờ".

Nút "Nâng cao"

Mở dialog cấu hình thêm các tùy chọn ít dùng (retry policy, max attempts...).

8.8 Tab "Lịch sử chạy" — Run History

Hiển thị danh sách tất cả lần chạy của job.

Cũng có thể mở Lịch sử chạy nhanh từ trang danh sách bằng cách bấm icon ở cột Thao tác. Title dialog: "Lịch sử chạy: {{name}}".

8.9 Bật/Tắt + Xóa — Confirm dialogs

Bật job

• Title: "Bật tác vụ định kỳ"
• Mô tả: "Bật \"{{name}}\"? Tác vụ sẽ bắt đầu chạy theo lịch."
• Nút: Bật

Toast: "Đã bật tác vụ định kỳ".

Tắt job

• Title: "Tắt tác vụ định kỳ"
• Mô tả: "Tắt \"{{name}}\"? Tác vụ sẽ dừng chạy cho đến khi được bật lại."
• Nút: Tắt

Toast: "Đã tắt tác vụ định kỳ".

Xóa job

• Title: "Xóa tác vụ định kỳ"
• Mô tả: "Xóa \"{{name}}\"? Hành động này không thể hoàn tác."
• Nút: Xóa (đỏ)

Toast: "Đã xóa tác vụ định kỳ".

8.10 Best practices khi quản trị Cron

1. 🌍 LUÔN đặt múi giờ Asia/Ho_Chi_Minh nếu bạn ở Việt Nam — tránh sai 7 tiếng.
2. 🏷️ Tên job rõ ràng: sales-report-8am-vn, backup-hourly — sau 6 tháng vẫn hiểu.
3. 🔁 Job Một lần bật Tự động xóa: Tránh job "rác" tích tụ.
4. 📦 Job tần suất cao bật Không trạng thái: Health check 5p/lần → stateless để không phình runlog.
5. 📡 Cấu hình Delivery cho job báo cáo: Để kết quả tự gửi Telegram/Slack — không phải vào trang Sessions xem thủ công.
6. 🧪 Test cron tại crontab.guru: Verify expression đúng trước khi save.
7. 🔍 Theo dõi Lịch sử chạy: Job thất bại liên tục → vào xem lỗi gần nhất, fix ngay.
8. ⚠️ Đừng tạo nhiều job cùng giờ: 10 job cùng chạy 9:00 sáng → spike CPU + LLM rate limit.
9. 🔄 Tận dụng Chạy ngay để test: Đừng đợi đến giờ — bấm Chạy ngay để verify ngay khi tạo.
10. 🤖 Tin nhắn rõ ràng: Viết như chat với agent. Càng cụ thể càng đúng. Vd "Tổng hợp doanh thu từ Nhanh.vn ngày hôm qua. Format bảng. Gửi Telegram."

9.1 Hiểu nhanh: Bộ nhớ là gì?

"Bộ nhớ" (Memory) là kho tài liệu dài hạn mà agent có thể tìm kiếm bằng semantic search (hiểu ý) — không cần khớp chính xác từ khóa.

Mỗi tài liệu memory:

• Có đường dẫn (path) như file, vd: notes/q2-strategy.md
• Có nội dung dạng text/markdown
• Được chia thành chunks (đoạn nhỏ)
• Mỗi chunk được embedding (chuyển thành vector số học)
• Có scope (toàn cục / cá nhân)

9.2 Trang menu Bộ nhớ — Có gì trên màn hình?

Click menu Bộ nhớ → trang có tiêu đề "Bộ nhớ" + dòng phụ "Duyệt và quản lý tài liệu bộ nhớ, đoạn trích và nhúng của agent".

2 Tab top-level

Header — 4 nút action

Bộ lọc

Trạng thái rỗng:

• Lọc theo agent: "Không có tài liệu bộ nhớ — Agent này chưa có tài liệu bộ nhớ."
• Toàn cục: "Không tìm thấy tài liệu bộ nhớ trên bất kỳ agent nào."

9.3 Bảng Tài liệu — 6 cột

9.4 Hai phạm vi — Toàn cục vs Cá nhân

9.5 Dialog "Tạo tài liệu bộ nhớ" — Đi từng ô

Bấm + Tạo. Title: "Tạo tài liệu bộ nhớ".

Cuối: Hủy / Tạo. Đang tạo: "Đang tạo...". Toast: "Đã tạo tài liệu bộ nhớ".

9.6 Dialog "Tìm kiếm bộ nhớ" — Semantic Search

Bấm Tìm kiếm. Title: "Tìm kiếm bộ nhớ".

Bấm Tìm kiếm. Đang tìm: "Đang tìm kiếm...". Khu vực Kết quả:

• Mỗi kết quả: chunk text + score "tương đồng" (0-1) + "Đường dẫn:" document gốc
• Trống: "Không tìm thấy kết quả"
• Lỗi: "Tìm kiếm thất bại"

Cách dùng: Test xem agent có "nhớ" đúng thông tin không. Vd hỏi "Chính sách hoàn trả của công ty?" → xem có trả về đoạn từ document policy.

9.7 Dialog "Tài liệu bộ nhớ" — Xem chi tiết

Click vào dòng document → mở dialog xem chi tiết. Title: "Tài liệu bộ nhớ".

Phần thông tin

Phần "Nội dung"

Hiển thị toàn bộ markdown content. Có thể edit nếu có quyền.

Phần "Đoạn trích" (Chunks)

Hiển thị số đoạn: "Đoạn trích ({{count}})". Mỗi chunk:

• Tiêu đề "Đoạn {{index}}" — vd "Đoạn 1", "Đoạn 2"...
• Nội dung chunk
• Trạng thái: Đã nhúng hoặc Chưa nhúng

Trống: "Không có đoạn trích".

9.8 Xóa document

Confirm dialog:

• Title: "Xóa tài liệu bộ nhớ"
• Mô tả: "Bạn có chắc muốn xóa \"{{path}}\"? Tất cả đoạn trích và nhúng liên quan cũng sẽ bị xóa."
• Nút: Xóa (đỏ)

Toast: "Đã xóa tài liệu bộ nhớ".

9.9 Best practices khi quản trị Bộ nhớ

1. 📂 Đặt path có tổ chức: notes/strategy.md, products/laptop.md, customers/abc-corp.md — sau dễ tìm và xóa hàng loạt.
2. 🌐 Toàn cục cho thông tin chung: catalog sản phẩm, FAQ, policy. Cá nhân cho data per-user (ghi chú khách hàng).
3. 🔄 Luôn bật Tự động lập chỉ mục khi tạo. Document chưa indexed thì search không thấy.
4. 🧪 Test bằng dialog Tìm kiếm: Sau khi tạo doc → search vài câu hỏi liên quan → xem có trả về đúng không.
5. 📏 Doc ngắn-vừa thay vì dài: 1 doc = 1 chủ đề. Doc 10.000 từ về mọi thứ → embedding kém chính xác.
6. 🗑️ Xóa doc cũ/sai: Tránh agent "nhớ" thông tin lỗi thời (vd giá cũ, policy đã đổi).
7. 🔄 Re-index sau khi đổi embedding model: Bấm "Lập chỉ mục tất cả" để tính lại với model mới.
8. 👀 Định kỳ review chunks: Mở doc xem chunks có chia hợp lý không. Doc chia tệ → kết quả search tệ.
9. 🏷️ Dùng metadata trong path: v2/products/laptop.md để biết version, bỏ v1/ khi không dùng.
10. 🛡️ Bảo mật cá nhân: Đặt scope đúng — không để PII (số CMND, password) ở Toàn cục.

10.1 Hiểu nhanh: Vault là gì?

"Vault" (Kho Tri Thức) = kho tài liệu chia sẻ theo cá nhân/team/cross-team với:

• 7 loại document (Context, Memory, Note, Skill, Episodic, Media, Document)
• Wikilinks [[link]] giữa tài liệu — agent và user follow link như Notion
• Hybrid search = full-text + semantic (vector)
• Auto sync workspace folder → vault

10.2 Trang Vault — Có gì trên màn hình?

Click menu Vault → trang có tiêu đề "Kho Tri Thức" + dòng phụ "Kho tài liệu với wikilinks và tìm kiếm ngữ nghĩa".

Bộ lọc

• Agent: dropdown "Tất cả agent" hoặc agent cụ thể
• Loại: "Tất cả" hoặc 1 trong 7 loại doc (xem mục 10.5)

Trạng thái rỗng:

• Vault rỗng: "Không có tài liệu trong kho"
• Search không khớp: "Không có kết quả"
• Lỗi search: "Tìm kiếm thất bại"

10.3 Bảng tài liệu — 6 cột

10.4 3 Phạm vi (Scope)

10.5 7 Loại tài liệu (DocType)

10.6 Tạo / Sửa Tài Liệu

Bấm + Tạo mới. Form gồm:

Toast: "Đã tạo tài liệu". Lỗi: "Tạo tài liệu thất bại".

10.7 Dialog "Tải lên Kho Tri Thức" — Bulk upload

Bấm Tải lên. Title: "Tải lên Kho Tri Thức".

Khối "Đích đến" — chọn nơi lưu

Khối "Dropzone"

"Kéo thả file vào đây hoặc nhấn để chọn". Hint: "Chỉ file văn bản (.md, .txt, .json, .yaml, .csv, ...)".

Sau khi chọn: hiển thị "File ({{count}})" + danh sách file. Bấm Tải lên hoặc Hủy.

Đang upload: "Đang tải lên...". Toast: "Đã tải lên {{N}} file". Lỗi: "Tải lên thất bại".

10.8 Dialog xem chi tiết tài liệu

Click vào dòng → mở chi tiết. Có các phần:

Khối "Siêu dữ liệu" (Metadata)

Title, Path, Type, Scope, Agent, Updated.

Khối "Liên kết đi" (Outlinks)

Các tài liệu mà doc này tham chiếu đến (dạng [[other-doc]]). Trống: "Không có liên kết".

Khối "Liên kết ngược" (Backlinks)

Các tài liệu khác tham chiếu đến doc này. Trống: "Không có liên kết".

Khối "Xem nội dung" (Content Preview)

Render markdown. Trạng thái đặc biệt:

• "Không tìm thấy tệp"
• "Không có nội dung"
• "Tệp nhị phân — không thể xem trước" (cho ảnh/video/audio)

Có nút Chỉnh sửa, Lưu / Hủy. Đang lưu: "Đang lưu...".

10.9 Tạo Liên Kết — Wikilinks

Bấm + Thêm Liên Kết trong dialog xem chi tiết. Form:

Toast: "Đã tạo liên kết". Lỗi: "Tạo liên kết thất bại".

Xóa link: "Đã xóa liên kết" hoặc lỗi "Xóa liên kết thất bại".

10.10 Quét lại workspace — Sync

Bấm icon Quét lại workspace ở header. Hệ thống quét folder workspace của agent → tự thêm doc mới + update doc đã đổi.

Trạng thái

Kết quả quét

• "{{N}} mới" — file mới thêm vào
• "{{N}} cập nhật" — file đã update
• "{{N}} đang xử lý lại"
• "{{N}} không đổi"
• "Quét bị cắt (đạt giới hạn)" — quá nhiều file
• "Không tìm thấy file mới"
• "Đang quét, vui lòng đợi" — đã có quét chạy
• "Quét thất bại"

10.11 Xóa

Confirm: "Xóa tài liệu này?". Nút Có / Không.

Toast: "Đã xóa tài liệu". Lỗi: "Xóa tài liệu thất bại".

10.12 Best practices khi quản trị Vault

1. 📁 Tổ chức path theo nghiệp vụ: brand/voice.md, products/specs/laptop.md, policies/refund.md — agent dễ tìm và filter.
2. 🏷️ Đặt đúng DocType: Note ≠ Skill ≠ Context — giúp filter và agent xử lý đúng cách.
3. 👥 Scope phù hợp: Chia sẻ cho info công ty, Nhóm cho team-specific, Cá nhân cho note riêng.
4. 🔗 Tận dụng Wikilinks: Link giữa các doc liên quan để agent follow context. Vd: "Strategy Q2" link tới "Marketing Plan".
5. ⬆️ Bulk upload thay vì tạo từng doc: Có 50 file md? Dùng dropzone upload 1 lần.
6. 🔄 Quét workspace định kỳ: Nếu agent edit file trong workspace, cần quét để Vault thấy update.
7. 🧪 Test bằng Search: Sau khi upload doc → search keyword/câu hỏi để verify hiển thị đúng.
8. 🛑 Dừng quét nếu phát hiện sai: Đang sync mà thấy nhiều file rác → dừng, fix folder rồi quét lại.
9. 🔍 Xem Backlinks để hiểu phụ thuộc: Doc có nhiều backlinks = "tài sản trung tâm", cẩn thận khi xóa/sửa.
10. 📂 Loại bỏ DocType Episodic khi quá nhiều: Episodic auto-gen có thể tích tụ nhanh — định kỳ filter và xóa cũ.

11.1 Hiểu nhanh: Knowledge Graph là gì?

Knowledge Graph (đồ thị tri thức) lưu 2 loại thông tin:

Agent có KG sẽ trả lời chính xác hơn câu hỏi như: "Khách hàng nào mua laptop và làm ở TechCorp?" — vì nó truy đồ thị thay vì search text mù.

11.2 Trang Knowledge Graph — Có gì trên màn hình?

Click menu Knowledge Graph (hoặc tab "Đồ thị tri thức" trong Menu Bộ nhớ). Title: "Knowledge Graph". Description: "Khám phá các thực thể và quan hệ được trích xuất từ bộ nhớ agent."

Bước 1 — Chọn agent

Trống ban đầu: "Chọn agent — Chọn agent để xem đồ thị tri thức.". Sau khi chọn → hiển thị KG của agent đó.

Header sau khi chọn agent

Trạng thái rỗng:

• Agent chưa có KG: "Không có thực thể — Chưa có thực thể đồ thị tri thức nào cho agent này."
• Search không khớp: "Không có thực thể nào khớp với tìm kiếm của bạn."

11.3 Bảng thực thể — 5 cột

Có thể có thêm cột Quan sát và Quan hệ hiển thị số liệu liên quan.

11.4 Dialog xem chi tiết Thực thể

Click vào tên thực thể → mở dialog. Hiển thị:

Phần "Quan hệ" + nút "Duyệt"

Hiển thị các quan hệ liên quan thực thể. Có nút Duyệt + dropdown "{{depth}} bước" (1, 2, 3 bước) để khám phá đồ thị sâu hơn.

Đang chạy: "Đang duyệt...". Trống: "Không tìm thấy quan hệ."

2 Tab "Bảng" / "Đồ thị"

Bảng Quan hệ — 4 cột

Khi traverse: hiển thị "Kết quả duyệt ({{count}})". Có nút Hiện tất cả để mở rộng kết quả.

Đồ thị view (graphView)

• Đang load: "Đang tải đồ thị..."
• Trống: "Không có thực thể nào để hiển thị"
• Stats: "{{N}} nút", "{{N}} cạnh"
• Selected: "Đã chọn: {{name}}"
• Khi quá nhiều entity: "Hiển thị {{limit}}/{{total}} thực thể" + Hint: "Đồ thị giới hạn {{limit}} thực thể để đảm bảo hiệu năng. Dùng chế độ bảng để xem tất cả {{total}} thực thể."

11.5 Dialog "Trích xuất thực thể từ văn bản"

Bấm Trích xuất. Title: "Trích xuất thực thể từ văn bản".

Cuối: Hủy / Trích xuất. Đang chạy: "Đang trích xuất...". Toast: "Trích xuất hoàn tất". Lỗi: "Trích xuất thất bại".

11.6 Dialog "Gộp trùng" — Dedup

Bấm Gộp trùng. Title: "Thực thể trùng lặp". Description: "Xem và gộp các thực thể có thể trùng lặp dựa trên độ tương đồng embedding."

Khu vực ứng viên

• Hiển thị "{{count}} ứng viên"
• Mỗi ứng viên: 2 entity giống nhau + score "tương đồng" (vd 0.92)
• Trống: "Không tìm thấy ứng viên trùng lặp."

Action mỗi cặp

Nút "Quét tất cả"

Force scan toàn bộ entity tìm cặp trùng. Đang chạy: "Đang quét...". Hoàn tất: "Quét hoàn tất.". Lỗi: "Quét thất bại."

11.7 Xóa thực thể

Confirm dialog:

• Title: "Xóa thực thể"
• Mô tả: "Xóa \"{{name}}\"? Tất cả quan hệ liên quan cũng sẽ bị xóa."
• Nút: Xóa (đỏ)

Toast: "Đã xóa thực thể". Lỗi: "Không thể xóa thực thể".

11.8 Best practices khi quản trị Knowledge Graph

1. 🤖 Bật auto-extract trong Built-in Tools KG settings: KG tự update khi agent ghi memory mới.
2. 🎯 Min confidence 0.7-0.8: Quá thấp (0.5) → KG nhiễu. Quá cao (0.95) → bỏ sót entity.
3. 🧪 Test trích xuất bằng dialog Trích xuất: Dán 1 đoạn text → xem entity/relation có chính xác không. Nếu sai → đổi model trích xuất.
4. 🔄 Gộp trùng định kỳ: Mở dialog Dedup mỗi tuần — KG nhiều dễ trùng (vd "Lan", "Lan Nguyen", "Nguyen Lan" cùng người).
5. 🔍 Dùng Đồ thị view để khám phá pattern bất ngờ. Bảng để search/filter.
6. 🌐 Traverse 1-2 bước là đủ: 3+ bước thường rộng quá, kết quả nhiễu.
7. 🗑️ Xóa entity sai: KG sai có thể gây agent trả lời sai. Kiểm tra confidence thấp + Source để verify.
8. 📊 Theo dõi stats: Số entity tăng đều = dấu hiệu hệ thống học. Tăng đột biến = có thể auto-extract nhiễu.
9. 🔗 External ID quan trọng: Khi trích xuất từ CRM, set external_id = customer ID → liên kết KG ↔ database thực.
10. 🛡️ Cẩn thận PII: KG lưu thông tin cá nhân (tên, email, phone). Xóa entity khi user yêu cầu (GDPR/Quy định bảo vệ dữ liệu).