Học OpenClaw: hiểu gateway trước khi cài plugin

Hai năm cài lại gần chục lần, mình rút ra một điều: phần khó của trợ lý AI chạy trên máy không nằm ở lúc cài. Nó nằm ở tuần thứ hai, khi tin nhắn không tới, khi trợ lý trả lời chậm, khi thấy một tên lạ trong hộp thư đã gửi.

Vì sao không sửa cấu hình khi chưa hiểu gateway

Một tin nhắn đi từ Telegram xuống máy bạn qua bốn chặng. Kênh nhận, gateway chuyển phiên, mô hình trả lời, rồi kết quả quay ngược ra. Sửa cấu hình mà không biết tin nhắn đang kẹt ở chặng nào thì phần lớn thời gian là sửa mò.

Mình đã mất gần một buổi sáng đổi token Telegram ba lần, xoá bot, tạo lại, chỉ để mở nhật ký ra và thấy một dòng: kênh bị tắt trong cấu hình. Từ đó, mọi lần sự cố đều bắt đầu bằng ba câu: gateway có chạy không, log có gì, mô hình có trả lời được không.

Đường đi của một tin nhắn

Gõ "kiểm tra ổ đĩa" trên Telegram. Tin nhắn rời ứng dụng, tới máy chủ Telegram, rồi xuống bot. Bot chuyển vào gateway bằng một kết nối đang mở sẵn, không phải bot tự gọi vào máy bạn.

Gateway nhận, xác định phiên theo chat ID, gom ngữ cảnh, rồi gửi lên mô hình. Mô hình trả về lời đề nghị chạy một lệnh. Gateway xin phép theo chính sách, chạy lệnh, lấy kết quả, gửi lại mô hình, rồi mới trả câu trả lời về Telegram.

Bốn chặng, mỗi chặng có thể hỏng. Biết bốn chặng thì đoán chỗ hỏng nhanh hơn nhiều so với cài lại từ đầu.

Có, nhưng không phải mặc định. Công cụ đọc tệp phải bật, và thư mục phải nằm trong phạm vi cho phép. Đọc ngoài phạm vi thì bị chặn, không phải vì lỗi mà vì thiết kế.

Chỗ người mới hay vấp: đường dẫn tương đối. Agent chạy lệnh trong thư mục làm việc của nó, nên một đường dẫn kiểu "tài liệu/báo cáo.docx" có thể trỏ sang chỗ khác với chỗ bạn đang nghĩ. Dùng đường dẫn đầy đủ cho chắc.

Mô hình phụ: chỗ tiết kiệm không ai để ý

OpenClaw cho khai nhiều loại mô hình: mô hình chính, mô hình dự phòng, và mô hình phụ cho việc rẻ như đặt tên phiên, tóm tắt ngắn, hay đọc ảnh.

Mặc định thì nhiều người để mọi việc chạy một mô hình. Nhưng việc phụ chiếm số lượt gọi chứ không chiếm chất lượng. Tách ra một mô hình nhỏ cho phần đó là cách giảm tiền mà không giảm chất lượng trả lời.

Cẩn thận một chỗ: mô hình phụ yếu quá thì việc tóm tắt sai, và phiên sau đọc bản tóm tắt sai đó như sự thật.

Một buổi chiều cài trên máy thật

Máy chạy macOS 26.6.2, Node 26. Cài bằng gói npm toàn cục, mất khoảng bốn mươi phút, trong đó phần lớn là chờ tải.

Sai lầm đầu tiên là mở hai cửa sổ terminal, chạy lệnh khởi động ở cả hai. Bản thứ hai báo cổng đã bị chiếm. Mình tưởng mạng có vấn đề, loay hoay gần nửa tiếng mới thấy nguyên nhân. Từ đó, trước mọi lần khởi động, kiểm tiến trình trước.

Sai lầm thứ hai là đặt tên trợ lý trùng tên một agent. Nhìn không sao, nhưng khi có thêm hai agent phụ thì nhật ký ghi lẫn, đọc không ra tin nào của ai.

Kênh chat: chỗ dễ bỏ qua nhất

Telegram là kênh dễ nối nhất: tạo bot, dán token, nhắn thử. Xong trong vài phút, nên nhiều người dừng ở đó và cho rằng mọi kênh giống nhau.

Zalo thì khác hẳn. Zalo có ba kiểu kênh khác nhau, mỗi kiểu dùng cho một mục đích: tài khoản cá nhân, tài khoản chính thức cho doanh nghiệp, và kênh dành cho ứng dụng. Chọn sai kiểu thì nối được nhưng nhắn không tới, hoặc nhận được tin nhưng không trả lời được nhóm.

Slack cần quyền theo workspace và theo kênh, và quyền đó do người quản trị workspace cấp chứ không phải bạn. Đây là lý do nhiều người thử Slack thấy khó rồi bỏ, trong khi Telegram đã chạy từ lâu.

Cài đặt trên macOS và trên Windows

Trên macOS, cài bằng trình quản lý gói, rồi chạy lệnh thiết lập ban đầu. Bộ cài đặt hỏi vài thứ: tên trợ lý, kênh muốn nối, nhà cung cấp mô hình. Chọn nhanh thì mất chừng hai phút và có thể sửa lại sau.

Trên Windows có ba đường: ứng dụng riêng, PowerShell, hoặc WSL2. WSL2 gần với môi trường Linux nhất nên ít lỗi đường dẫn hơn, đổi lại việc truy cập tệp trong ổ C: chậm hơn một chút.

Sau khi cài, có bốn lệnh chỉ đọc để kiểm tình trạng: phiên bản, tình trạng gateway, danh sách kênh đã nối và danh sách agent. Bốn lệnh đó không sửa gì, chạy xong là biết mình đang ở đâu.

Cập nhật và gỡ cài

Cập nhật thì đơn giản, nhưng có một cái bẫy: bản cập nhật đôi khi đổi khoá cấu hình. Cấu hình cũ vẫn chạy nhưng một hai mục bị bỏ qua, và mục bị bỏ qua thường là mục mới thêm chứ chưa ai dùng, nên vài tuần sau mới phát hiện.

Gỡ cài thì cần xoá cả thư mục cấu hình. Nhiều người gỡ ứng dụng rồi cài lại, thấy mọi thứ vẫn như cũ, vì thư mục cấu hình còn nguyên. Hữu ích khi muốn giữ lại dữ liệu, phiền khi đang cố sửa một lỗi cấu hình.

Ba tầng quyền và lý do không mở hết

Dưới chế độ quyền của phiên còn có chính sách công cụ. Một công cụ bị chặn ở cấp chính sách thì phiên có ở mức cao nhất cũng không chạy được.

Thứ tự mình dùng cho mọi agent mới: chặn hết, mở từng công cụ một, chạy thử, đọc nhật ký. Mất nửa buổi, nhưng không có đêm nào phải dọn hậu quả.

Có một quyền không bao giờ mở sẵn: gửi tin ra ngoài. Trợ lý đọc cả thư mục, sửa mã, nhưng thư đến người lạ phải do mình bấm.

Xem trước năm trang: thấy gì, thiếu gì

Năm trang đầu cho thấy bảng so sánh ba cách dùng, bảng mục lục, và vài trang về cấu trúc thư mục.

Chúng đủ để trả lời hai câu: tài liệu có viết đúng trình độ mình không, và nó có đi vào phần mình cần không.

Chúng không đủ để đánh giá phần thực hành. Muốn biết phần cài trên Windows viết kỹ tới đâu thì phải mua, hoặc chờ ai đó viết bài chi tiết hơn. Đây là điểm yếu thật của việc chỉ xem trước năm trang.

Lấy tài liệu

PDF 171 trang, song ngữ Việt - Anh cạnh nhau, giá 128.000 đồng. Đặt mua theo kiểu chuyển khoản trong nước, không cần thẻ quốc tế. Sau khi xác nhận chuyển khoản, file được gửi trong 24 giờ.

Đọc 5 trang xem trước và đặt mua

Một lưu ý nhỏ: tài liệu viết cho bản 1.0 tháng 9/2026. OpenClaw cập nhật khá nhanh nên tên lệnh trong phụ lục có thể lệch một chút so với bản mới nhất, còn phần khái niệm thì vẫn đúng.

Chi phí một tháng thật

Một agent chạy hằng ngày, mỗi ngày vài chục lượt gọi mô hình, đa số là câu ngắn. Với một mô hình cỡ trung bình, hoá đơn có thể rơi vào khoảng vài trăm nghìn đồng một tháng.

Nhưng chi phí tăng vọt ở đúng một chỗ: tự động hoá. Một tác vụ hẹn giờ chạy mỗi nửa giờ, mỗi lần đọc cả chục tệp, sẽ nhanh chóng vượt toàn bộ phần hỏi đáp.

Cách giảm: cho tác vụ chạy ít hơn, hoặc cho nó một mô hình nhỏ chuyên làm việc rẻ. Phần quyết định vẫn để mô hình lớn, nhưng phần quét dữ liệu thì không cần.

Trước khi cho người khác dùng

Danh sách kiểm của mình có sáu dòng, viết sau một lần suýt để trợ lý trả lời khách bằng thông tin nội bộ.

Một: chỉ cho đúng người đã biết ID của họ. Hai: tắt quyền chạy lệnh ở mọi phiên có người ngoài. Ba: chặn đọc những thư mục có hồ sơ riêng.

Bốn: kiểm nội dung nạp từ ngoài, vì trang web hay email có thể chứa câu lệnh đánh lừa. Năm: khoá bí mật không nằm trong tệp cấu hình. Sáu: ghi lại ai đã nhắn trong tuần đầu, rồi đọc lại.

Sáu dòng, mất nửa buổi. Đắt hơn nhiều nếu bỏ qua.

Điều tài liệu không giấu

Phần lớn tài liệu hướng dẫn phần mềm hay kể chuyện thành công. Cuốn này có một chỗ nói thẳng: cài đặt trên máy Mac chip Apple không có bản chạy thẳng, phải đi qua môi trường khác. Ai dùng Mac mà không muốn cài thêm thì nên biết trước khi mua.

Chỗ thứ hai: bộ cài kèm công cụ nặng, ổ đĩa dưới 128 gigabyte trống thì nên dọn trước.

Chỗ thứ ba: nếu chỉ cần hỏi đáp, mua cuốn sách này là lãng phí. Chính cuốn sách nói vậy ở chương đầu.

Công cụ và kỹ năng: hai chữ hay bị lẫn

Công cụ là thứ phần mềm cấp sẵn: đọc tệp, chạy lệnh, tìm trên web, gửi tin nhắn. Kỹ năng là tệp hướng dẫn nằm trong thư mục, mô tả cách làm một việc cụ thể.

Khác biệt nghe nhỏ nhưng dùng hằng ngày thì rõ. Bật thêm công cụ là trao quyền. Thêm một kỹ năng là dạy cách làm, không trao quyền nào thêm.

Nhiều người muốn trợ lý biết việc riêng của mình, cách gọn nhất là viết một kỹ năng, chứ không phải dán hướng dẫn dài vào câu hỏi mỗi lần.

Plugin và ClawHub

ClawHub là chợ công khai của dự án, có cả kỹ năng lẫn phần mở rộng. Cài từ đó nhanh, nhưng có bước không nên bỏ: kiểm tra phiên bản phần mở rộng tương thích với bản OpenClaw đang chạy.

Lệnh cài đặt có in ra cảnh báo khi lệch phiên bản, đôi khi ở cuối, dễ bị cuộn qua. Một phần mở rộng viết cho bản cũ vẫn cài được, vẫn chạy, nhưng lỗi chỉ lộ ra khi dùng tới chức năng bị đổi.

Trước khi công bố một kỹ năng lên chợ, cần thêm tên và phiên bản vào tệp khai báo. Thiếu thì công bố bị từ chối, thông báo lỗi không nói rõ là thiếu trường nào.

Vận hành hằng ngày

Gateway nên chạy dưới dạng dịch vụ nền, có bật cùng máy. Cài một lần rồi quên là cách ổn nhất. Chạy tay mỗi lần mở máy thì lần nào quên cũng mất cả buổi sáng đoán xem vì sao tin nhắn không tới.

Dùng nhiều máy thì nên có một bản sao lưu thư mục cấu hình. Không phải vì sợ mất máy, mà vì đổi máy dễ hơn nhiều khi có sẵn bản sao.

Xử lý sự cố: sáu mươi giây đầu

Khi có gì đó không chạy, thứ tự kiểm tra nên cố định. Ba bước đầu mất chưa tới một phút nhưng bắt được phần lớn sự cố.

Bước một: gateway có đang chạy không. Bước hai: nhật ký có dòng lỗi nào trong mười phút gần nhất không. Bước ba: mô hình phía sau có trả lời được không, bằng cách hỏi thẳng câu ngắn.

Nếu ba bước đều ổn mà vẫn không nhận tin, thì lỗi nằm ở kênh: token hết hạn, quyền bot bị thu, hoặc nhóm chat không còn thành viên bot. Ba nguyên nhân này hay bị nhầm thành lỗi hệ thống.

Bảng chọn mô hình theo việc

Việc chọn mô hình không phải chuyện "mô hình nào mạnh nhất". Là chuyện cân giữa tốc độ, tiền và khả năng suy luận.

Dòng cuối là chỗ dễ hỏng nhất. Mô hình phụ tóm tắt sai một lần, phiên sau đọc bản tóm tắt sai đó như sự thật, rồi trả lời sai tiếp. Kiểm lại bản tóm tắt trước khi cho nó vào ngữ cảnh.

Đọc nhật ký mỗi ngày

Mình có thói quen mở nhật ký gateway khoảng năm phút mỗi sáng, trước khi hỏi gì.

Phần lớn dòng là thông tin bình thường. Nhưng có ba chuỗi nên biết: lỗi xác thực của mô hình, lỗi kênh bị tắt, và dòng chuyển sang mô hình dự phòng.

Chuỗi thứ hai từng làm mình mất buổi sáng. Tin nhắn không tới, mình đổi token, xoá bot, tạo lại, vẫn vậy. Nhật ký ghi một dòng ngắn: kênh bị vô hiệu trong cấu hình.

Chuỗi thứ ba giải thích vì sao trợ lý chậm bất thường: mô hình chính lỗi hạn mức, hệ thống chạy mô hình dự phòng. Không đọc log thì tưởng máy yếu, rồi đòi nâng cấu hình.

Máy Mac mới thường chỉ có một ổ, dung lượng dùng chung với hệ điều hành. Cài bộ công cụ nặng lên đó thì dễ đầy, và khi đầy thì gateway ghi log thất bại rồi dừng lặng lẽ.

Cách kiểm: xem dung lượng trống trước khi cài, và để dư ít nhất bằng hai lần dung lượng bộ cài. Nghe thừa, nhưng bản cập nhật cần chỗ tạm để giải nén.

Một mẹo nhỏ: chuyển thư mục log sang ổ ngoài nếu có. Log là thứ lớn dần mà không ai dọn.

Tự động hoá: chỗ dễ ham

OpenClaw có nhiều cơ chế để trợ lý tự làm việc: tác vụ hẹn giờ, nhịp tim chạy nền, tác vụ nền, móc sự kiện, và webhook.

Ham nhất là tác vụ hẹn giờ. Hẹn vài việc một ngày là ổn. Hẹn hai chục việc, mỗi việc gọi mô hình vài lượt, thì hoá đơn tăng mà kết quả phần lớn là rác: trợ lý đi quét những thứ không ai đọc.

Cách mình dùng: mỗi tác vụ hẹn giờ phải có một câu trả lời cho "nếu không có gì mới thì nó làm gì". Nếu câu đó là "không làm gì" thì tác vụ không đáng tồn tại.

Một buổi chiều với nhật ký

Nhật ký gateway là nơi ít người mở nhất và cũng là nơi trả lời nhiều câu hỏi nhất.

Một lần, tin nhắn trên Telegram không tới. Thử đổi token, xoá bot, tạo lại, vẫn không. Mở log ra thì thấy dòng ghi rõ: kênh bị tắt trong cấu hình. Không phải token. Không phải mạng.

Một lần khác, trợ lý trả lời chậm bất thường. Log cho thấy mô hình chính trả lỗi hạn mức, hệ thống chuyển sang mô hình dự phòng chậm hơn. Nếu không đọc log, sẽ tưởng máy yếu.

Đọc log là kỹ năng, không phải sở thích. Ai bỏ qua bước đó sẽ mất nhiều lần hơn số lần tiết kiệm được.

Bốn lối vào, một bộ nhớ

Trực tiếp trong terminal là lối vào nhanh nhất khi đang sửa cấu hình: mở ra, hỏi, thấy kết quả ngay.

Bảng điều khiển web hợp khi cần xem nhiều phiên cùng lúc, hoặc đọc lại lịch sử dài.

Kênh chat hợp khi đang đi đường. Nhưng nhớ: cùng một bộ nhớ nghĩa là câu hỏi vụng về trên chat cũng nằm trong ngữ cảnh phiên làm việc.

Học OpenClaw có khó không. Cài thì không khó. Hiểu vì sao nó không trả lời mới khó, và phần lớn cuốn sách dành cho chỗ đó.

Có cần biết lập trình không. Không. Nhưng phải đọc được lỗi và chịu mở nhật ký ra xem. Ai thấy log là sợ thì mua về cũng khó dùng.

Máy bao nhiêu là đủ. Đủ để chạy vỏ thì máy nào cũng được. Đủ để chạy mô hình nội bộ thì cần bộ nhớ lớn và thời gian chờ dài. Hai chuyện khác nhau, đừng gộp.

Bản tiếng Anh có cần không. Có, khi gặp tên lệnh. Bản dịch giải thích ý, bản gốc cho biết phải gõ chính xác chữ gì.

Có cập nhật miễn phí không. Không. Bản 1.0 viết theo tháng 9/2026. Nếu phần mềm đổi cấu trúc lệnh, cuốn sách không tự sửa theo.

Ai nên mua

Người đã có việc lặp lại hằng ngày mà không muốn tự làm: đọc hộp thư, tóm tắt tài liệu, quét một thư mục mã nguồn. Nếu chưa có việc đó, mua về cũng chỉ để đọc cho biết.

Người đang dùng dịch vụ AI qua mạng và cần nó chạm vào tệp trong máy. Đây là nhóm hợp nhất.

Người đang chuẩn bị cho cả phòng dùng chung một trợ lý. Phần bảo mật và ranh giới tin cậy đáng đọc trước, chứ không phải sau khi đã nối kênh cho cả phòng.

Khi nào nên gỡ và cài lại

Cài lại sửa nhanh, nhưng chỉ đúng khi lỗi nằm ở cấu hình hoặc ở bộ cài. Khoá API hết hạn thì cài lại mười lần vẫn thế.

Dấu hiệu nên cài lại: gateway không khởi động dù cấu hình đã về mặc định, hoặc bản cập nhật làm hỏng thư viện. Dấu hiệu không nên: một kênh lỗi, một agent bị từ chối quyền, hay mô hình trả lời sai giọng. Ba thứ đó sửa ở cấu hình, cài lại chỉ mất dữ liệu phiên.

Trước khi cho người khác dùng, sao lưu cẩn thận

Thư mục cấu hình chứa cả lịch sử hội thoại. Sao lưu nguyên thư mục có nghĩa là sao lưu cả những câu bạn đã hỏi, kể cả câu hỏi về hồ sơ riêng của khách.

Cách mình làm: sao lưu định kỳ, nhưng để bản sao trong ổ mã hoá. Nếu phải gửi cho ai xem lỗi cấu hình, mở riêng đúng tệp cần xem, không gửi cả thư mục.

Đặt mua

PDF 171 trang, song ngữ Việt - Anh, giá 128.000 đồng. Năm trang xem trước có trên trang sản phẩm, đủ để biết phần cài đặt viết tới đâu.

Thanh toán bằng chuyển khoản trong nước, nhận file trong 24 giờ sau khi xác nhận. Không có bản giấy, không có bản in theo yêu cầu.

Đọc 5 trang xem trước và đặt mua