Agent Loop (OpenClaw)

Agent loop là một lần chạy “thực sự” đầy đủ của Agent: nhận đầu vào → lắp ráp context → suy luận model → thực thi tool → streaming phản hồi → lưu trữ. Đây là luồng chính thức biến một message thành các hành động và phản hồi cuối cùng, đồng thời giữ cho trạng thái session nhất quán.

Trong OpenClaw, một loop là một lần chạy tuần tự duy nhất cho mỗi session, phát ra các sự kiện lifecycle và stream khi model suy nghĩ, gọi tool, và streaming output. Tài liệu này giải thích cách mà loop chính thức đó được kết nối từ đầu đến cuối.

Điểm vào (Entry points)

  • Gateway RPC: agent và agent.wait.
  • CLI: lệnh agent.

Cách hoạt động (tổng quan)

  1. agent RPC xác thực params, phân giải session (sessionKey/sessionId), lưu metadata của session, trả về { runId, acceptedAt } ngay lập tức.
  2. agentCommand chạy agent:
    • phân giải model + các giá trị mặc định thinking/verbose
    • load snapshot của skills
    • gọi runEmbeddedPiAgent (pi-agent-core runtime)
    • phát ra lifecycle end/error nếu embedded loop không phát ra
  3. runEmbeddedPiAgent:
    • tuần tự hóa các lần chạy qua hàng đợi per-session + global
    • phân giải model + auth profile và xây dựng pi session
    • subscribe vào các sự kiện pi và streaming assistant/tool deltas
    • áp dụng timeout → hủy bỏ lần chạy nếu vượt quá
    • trả về payloads + metadata về usage
  4. subscribeEmbeddedPiSession kết nối các sự kiện pi-agent-core với OpenClaw agent stream:
    • tool events => stream: "tool"
    • assistant deltas => stream: "assistant"
    • lifecycle events => stream: "lifecycle" (phase: "start" | "end" | "error")
  5. agent.wait sử dụng waitForAgentJob:
    • đợi lifecycle end/error cho runId
    • trả về { status: ok|error|timeout, startedAt, endedAt, error? }

Queueing + concurrency

  • Các lần chạy được tuần tự hóa theo session key (session lane) và tùy chọn qua một global lane.
  • Điều này ngăn chặn các race condition của tool/session và giữ lịch sử session nhất quán.
  • Các messaging channel có thể chọn queue modes (collect/steer/followup) để cung cấp cho hệ thống lane này. Xem Command Queue.

Chuẩn bị Session + workspace

  • Workspace được phân giải và tạo ra; các lần chạy sandboxed có thể chuyển hướng đến sandbox workspace root.
  • Skills được load (hoặc tái sử dụng từ snapshot) và inject vào env và prompt.
  • Các file bootstrap/context được phân giải và inject vào system prompt report.
  • Một session write lock được lấy; SessionManager được mở và chuẩn bị trước khi streaming.

Lắp ráp Prompt + system prompt

  • System prompt được xây dựng từ base prompt của OpenClaw, skills prompt, bootstrap context, và các override theo từng lần chạy.
  • Các giới hạn cụ thể của model và compaction reserve tokens được áp dụng.
  • Xem System prompt để biết model nhìn thấy gì.

Các điểm hook (nơi bạn có thể can thiệp)

OpenClaw có hai hệ thống hook:

  • Internal hooks (Gateway hooks): các script event-driven cho commands và lifecycle events.
  • Plugin hooks: các điểm mở rộng bên trong agent/tool lifecycle và gateway pipeline.

Internal hooks (Gateway hooks)

  • agent:bootstrap: chạy trong khi xây dựng các file bootstrap trước khi system prompt được hoàn thiện. Dùng cái này để thêm/xóa các file bootstrap context.
  • Command hooks: /new, /reset, /stop, và các command events khác (xem tài liệu Hooks).

Xem Hooks để biết cách setup và các ví dụ.

Plugin hooks (agent + gateway lifecycle)

Các hook này chạy bên trong agent loop hoặc gateway pipeline:

  • before_agent_start: inject context hoặc override system prompt trước khi lần chạy bắt đầu.
  • agent_end: kiểm tra danh sách message cuối cùng và metadata của lần chạy sau khi hoàn thành.
  • before_compaction / after_compaction: quan sát hoặc chú thích các chu kỳ compaction.
  • before_tool_call / after_tool_call: chặn params/results của tool.
  • tool_result_persist: transform đồng bộ các kết quả tool trước khi chúng được ghi vào session transcript.
  • message_received / message_sending / message_sent: các hook message đến + đi.
  • session_start / session_end: ranh giới lifecycle của session.
  • gateway_start / gateway_stop: các sự kiện lifecycle của gateway.

Xem Plugins để biết API của hook và chi tiết đăng ký.

Streaming + partial replies

  • Assistant deltas được streaming từ pi-agent-core và phát ra dưới dạng các sự kiện assistant.
  • Block streaming có thể phát ra partial replies trên text_end hoặc message_end.
  • Reasoning streaming có thể được phát ra dưới dạng một stream riêng biệt hoặc dưới dạng block replies.
  • Xem Streaming để biết về chunking và hành vi block reply.

Thực thi Tool + messaging tools

  • Các sự kiện tool start/update/end được phát ra trên tool stream.
  • Kết quả tool được làm sạch về kích thước và image payloads trước khi logging/emitting.
  • Các lần gửi messaging tool được theo dõi để ngăn chặn các xác nhận assistant trùng lặp.

Reply shaping + suppression

  • Payloads cuối cùng được lắp ráp từ:
    • assistant text (và reasoning tùy chọn)
    • inline tool summaries (khi verbose + được phép)
    • assistant error text khi model bị lỗi
  • NO_REPLY được coi là một silent token và được lọc ra khỏi các payloads đi.
  • Các messaging tool trùng lặp được xóa khỏi danh sách payload cuối cùng.
  • Nếu không còn payloads có thể render và một tool bị lỗi, một fallback tool error reply được phát ra (trừ khi một messaging tool đã gửi một phản hồi hiển thị cho người dùng).

Compaction + retries

  • Auto-compaction phát ra các sự kiện compaction stream và có thể kích hoạt một lần retry.
  • Khi retry, các buffer in-memory và tool summaries được reset để tránh output trùng lặp.
  • Xem Compaction để biết về compaction pipeline.

Event streams (hiện tại)

  • lifecycle: được phát ra bởi subscribeEmbeddedPiSession (và như một fallback bởi agentCommand)
  • assistant: streaming deltas từ pi-agent-core
  • tool: streaming tool events từ pi-agent-core

Xử lý Chat channel

  • Assistant deltas được buffer vào các message delta của chat.
  • Một final của chat được phát ra khi lifecycle end/error.

Timeouts

  • agent.wait mặc định: 30s (chỉ là wait). Param timeoutMs có thể override.
  • Agent runtime: agents.defaults.timeoutSeconds mặc định 600s; được áp dụng trong runEmbeddedPiAgent abort timer.

Các trường hợp có thể kết thúc sớm

  • Agent timeout (abort)
  • AbortSignal (cancel)
  • Gateway disconnect hoặc RPC timeout
  • agent.wait timeout (chỉ wait, không dừng agent)