Giới thiệu

OpenClaw không chỉ đơn thuần là gửi một prompt lên LLM và nhận phản hồi. Có rất nhiều thứ đang xảy ra bên dưới. Bài viết này sẽ đi sâu vào kiến trúc thực sự của OpenClaw để bạn có thể xây dựng một mental model rõ ràng về cách hệ thống này được thiết kế.

Hai trụ cột cốt lõi

Ở cấp độ cao nhất, OpenClaw được xây dựng xung quanh hai layer chính:

  • Gateway — Layer giao tiếp và điều phối. Nó nhận input từ các nguồn khác nhau, quyết định agent nào sẽ xử lý, giải quyết session, và điều phối toàn bộ luồng.
  • Agent Runtime — Layer thực thi được cung cấp bởi Pi (built by Badlogic). Đây là nơi công việc thực sự diễn ra: model chạy, tools được thực thi, và tasks được hoàn thành từng bước một.

Khi bạn hiểu cách hai thứ này tương tác, phần còn lại của hệ thống trở nên dễ theo dõi hơn nhiều.

Luồng một message qua OpenClaw

1. Channel Plugin

Mọi tương tác với OpenClaw đều bắt đầu thông qua một channel plugin. Channel plugin kết nối OpenClaw với các nền tảng bên ngoài như Slack, WhatsApp, Discord, iMessage, v.v. Mỗi platform có plugin riêng, và trong mỗi plugin có các adapter chịu trách nhiệm xử lý các nhiệm vụ cụ thể như cấu hình tài khoản, chuẩn hóa message đầu vào thành định dạng chuẩn, và định dạng phản hồi đầu ra.

Khi message rời khỏi layer này, nó đã được chuyển đổi thành một định dạng chuẩn mà phần còn lại của hệ thống có thể xử lý.

2. Gateway — Routing và chọn Agent

Khi message đến Gateway, gateway đánh giá các routing binding (rules) để xác định agent nào sẽ xử lý nó. Mỗi agent hoạt động trong môi trường cô lập riêng của nó — workspace, state directory, và session store riêng. Sự tách biệt này quan trọng vì nó cho phép các agent khác nhau hoạt động độc lập trong khi vẫn được điều phối bởi cùng một hệ thống.

Gateway không chỉ quyết định nơi request sẽ đến, mà còn chịu trách nhiệm về cách thực thi được phối hợp. Nếu một message đến khi đã có một agent run đang hoạt động cho cùng session đó, nó sẽ không được xử lý ngay lập tức. Thay vào đó, nó được xếp hàng và xử lý khi run hiện tại hoàn thành — đảm bảo không có các lần thực thi chồng chéo và context luôn nhất quán.

3. Session Resolution — Giải quyết Session

OpenClaw duy trì session theo hai layer:

  • Session Store — Một metadata layer nhẹ được implement dưới dạng key-value map. Mỗi sessionKey ánh xạ đến một SessionEntry chứa các chi tiết như session ID hiện tại, updatedAt, và thông tin session-level khác.
  • Transcripts — Nơi lưu trữ lịch sử hội thoại thực sự. Đây là append-only log với mỗi entry được liên kết với các entry trước đó, tạo thành cấu trúc cây. Lịch sử này được dùng để tái tạo context mỗi khi có message mới.

Khi message mới đến, Gateway lấy sessionKey từ thông tin request. Quyết định tiếp tục session hiện tại hay tạo mới dựa trên timestamp updatedAt và các reset policy được cấu hình cho agent — có thể là daily reset, idle timeout, hoặc manual reset.

4. System Prompt Construction

Khi session được giải quyết, OpenClaw xây dựng system prompt. Đây là lúc nhiều thành phần được kết hợp thành một prompt duy nhất gửi đến model:

  • Tool list & descriptions — Định nghĩa tất cả built-in và custom tools cùng cách agent có thể sử dụng chúng.
  • Session history — Cung cấp context hội thoại để model có thể tiếp tục tương tác một cách mạch lạc.
  • Skills — Inject các khả năng hoặc hành vi có thể tái sử dụng (chỉ metadata được inject ở giai đoạn này).
  • Memory system — Đưa vào kiến thức đã lưu trữ hoặc các bài học từ các session trước. OpenClaw lưu memory dưới dạng file Markdown thuần trong workspace của agent — long-term memory trong memory.md, running context trong các file có timestamp.
  • Workspace files — Bao gồm các file cấu trúc như IDENTITY.md, USER.md, AGENTS.md, SOUL.md định nghĩa hành vi agent và context môi trường.
  • Time — Thêm context thời gian như UTC hiện tại và timezone của user.
  • User message — Input hiện tại từ user.

Bước này rất quan trọng vì hành vi của agent bị ảnh hưởng mạnh bởi cách prompt này được xây dựng.

5. Agent Runtime và Execution Loop

Khi system prompt được xây dựng, việc thực thi chuyển vào một Pi session trong Agent Runtime. Session này hoạt động như execution context cho task và có thể được tạo mới hoặc tái sử dụng tùy theo trạng thái session.

Pi agent core chạy một agent loop. Trong mỗi bước, model xử lý context hiện tại, quyết định hành động tiếp theo, và hoặc là tạo phản hồi hoặc kích hoạt tool call. Kết quả của hành động đó sau đó được append vào session context, và loop tiếp tục.

Trong quá trình này, agent có thể truy xuất thông tin liên quan từ memory để hướng dẫn quyết định, và ghi lại thông tin mới để kiến thức hữu ích tồn tại vượt qua session hiện tại. Đồng thời, runtime emit các structured event cho mỗi bước, cho phép system stream intermediate output và duy trì khả năng quan sát.

6. Sau khi thực thi

Khi phản hồi được tạo, control trả về Gateway. Cùng với phản hồi cuối cùng, Agent Runtime cũng tạo ra trạng thái session đã cập nhật — bao gồm session metadata và các transcript entry mới nhất (assistant response, tool calls, tool outputs).

Gateway persist thông tin này: session store được cập nhật với metadata mới nhất, và transcripts được append với các conversation event mới. Cuối cùng, phản hồi được truyền lại cho channel plugin, định dạng nó theo platform đích và gửi lại cho nguồn ban đầu.

Các cách kích hoạt event trong OpenClaw

Một trong những lý do OpenClaw cảm thấy responsive và luôn hoạt động là vì các agent không chỉ được kích hoạt bởi user message. Có nhiều cách hệ thống có thể khởi tạo việc thực thi:

  • Messaging channels — Input trực tiếp từ Slack, WhatsApp, Discord, v.v. được route qua channel plugin và xử lý ngay lập tức.
  • Heartbeat — Trigger định kỳ mà hệ thống invoke agent theo interval cố định (mặc định 30 phút) để kiểm tra trạng thái hiện tại và quyết định có cần hành động không.
  • Cron jobs — Trigger theo lịch, chạy vào các thời điểm cụ thể dựa trên schedule xác định trước.
  • Webhooks — Trigger từ hệ thống bên ngoài. Ví dụ: nhận payment event từ Stripe có thể kích hoạt một workflow bên trong OpenClaw.
  • Hooks — Trigger nội bộ được tạo ra trong hệ thống dựa trên thay đổi trạng thái. Ví dụ: khi task hoàn thành, một hook có thể trigger hành động khác như gửi notification.

Ngoài ra còn có các programmatic trigger như CLI operations, web interface actions, hoặc một agent gọi agent khác — cho phép tự động hóa sâu hơn và phối hợp giữa các phần khác nhau của hệ thống.

Tổng kết

OpenClaw là một ví dụ điển hình về cách thiết kế một hệ thống AI agent nghiêm túc — không phải chỉ là wrapper xung quanh một API call. Kiến trúc phân layer rõ ràng (Entry → Control → Execution), session persistence hai tầng, và đa dạng trigger mechanism giúp nó hoạt động như một hệ thống liên tục chạy, phản hồi, giám sát và tự hành động.

Nếu bạn đang xây dựng hệ thống agent tương tự, những pattern này là bài học đáng tham khảo: tách biệt communication layer khỏi execution layer, persist session theo cách có thể tái tạo context, và thiết kế hệ thống để có thể triggered từ nhiều nguồn khác nhau.