​

Công cụ Phiên

​

Tên Công Cụ

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

​

Mô Hình Khóa

• Bucket chat trực tiếp chính luôn là khóa literal "main" (được phân giải thành khóa chính của tác tử hiện tại).
• Chat nhóm dùng agent:<agentId>:<channel>:group:<id> hoặc agent:<agentId>:<channel>:channel:<id> (truyền đầy đủ khóa).
• Cron jobs dùng cron:<job.id>.
• Hooks dùng hook:<uuid> trừ khi được đặt rõ ràng.
• Phiên node dùng node-<nodeId> trừ khi được đặt rõ ràng.

41. global và unknown là các giá trị được dành riêng và không bao giờ được liệt kê. 42. Nếu session.scope = "global", chúng tôi ánh xạ nó thành main cho tất cả công cụ để người gọi không bao giờ thấy global.

​

sessions_list

• kinds?: string[] bộ lọc: một trong các "main" | "group" | "cron" | "hook" | "node" | "other"
• limit?: number số hàng tối đa (mặc định: theo mặc định của server, kẹp ví dụ 200)
• activeMinutes?: number chỉ các phiên được cập nhật trong vòng N phút
• messageLimit?: number 0 = không có tin nhắn (mặc định 0); >0 = bao gồm N tin nhắn cuối

• messageLimit > 0 lấy chat.history cho mỗi phiên và bao gồm N tin nhắn cuối.
• Kết quả công cụ được lọc khỏi đầu ra danh sách; dùng sessions_history cho tin nhắn công cụ.
• Khi chạy trong một phiên tác tử sandboxed, các công cụ phiên mặc định chỉ có khả năng hiển thị các phiên được spawn (xem bên dưới).

• key: khóa phiên (string)
• kind: main | group | cron | hook | node | other
• channel: whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown
• displayName (nhãn hiển thị nhóm nếu có)
• updatedAt (ms)
• sessionId
• model, contextTokens, totalTokens
• thinkingLevel, verboseLevel, systemSent, abortedLastRun
• sendPolicy (ghi đè phiên nếu được đặt)
• lastChannel, lastTo
• deliveryContext ({ channel, to, accountId } đã được chuẩn hóa khi có)
• transcriptPath (đường dẫn best-effort suy ra từ thư mục lưu trữ + sessionId)
• messages? (chỉ khi messageLimit > 0)

​

sessions_history

• sessionKey (bắt buộc; chấp nhận khóa phiên hoặc sessionId từ sessions_list)
• limit?: number số tin nhắn tối đa (server sẽ kẹp)
• includeTools?: boolean (mặc định false)

• includeTools=false lọc các tin nhắn role: "toolResult".
• Trả về mảng tin nhắn theo định dạng transcript thô.
• Khi cung cấp sessionId, OpenClaw sẽ phân giải nó thành khóa phiên tương ứng (lỗi nếu thiếu id).

​

sessions_send

• sessionKey (bắt buộc; chấp nhận khóa phiên hoặc sessionId từ sessions_list)
• message (bắt buộc)
• timeoutSeconds?: number (mặc định >0; 0 = fire-and-forget)

• timeoutSeconds = 0: xếp hàng và trả về { runId, status: "accepted" }.
• timeoutSeconds > 0: chờ tối đa N giây để hoàn tất, sau đó trả về { runId, status: "ok", reply }.
• 43. Nếu chờ bị hết thời gian: { runId, status: "timeout", error }. 44. Lần chạy vẫn tiếp tục; hãy gọi sessions_history sau.
• Nếu tiến trình thất bại: { runId, status: "error", error }.
• Các lần chạy thông báo (announce) sau khi lần chạy chính hoàn tất và là best-effort; status: "ok" không đảm bảo thông báo đã được gửi.
• Chờ thông qua agent.wait của gateway (phía server) để việc reconnect không làm rơi quá trình chờ.
• Ngữ cảnh tin nhắn tác tử‑tác tử được chèn cho lần chạy chính.
• Sau khi lần chạy chính hoàn tất, OpenClaw chạy vòng lặp reply-back:
• Khi vòng lặp kết thúc, OpenClaw chạy bước announce tác tử‑tác tử (chỉ tác tử đích):
  • Trả lời chính xác ANNOUNCE_SKIP để giữ im lặng.
  • Bất kỳ phản hồi nào khác sẽ được gửi tới kênh đích.
  • Bước announce bao gồm yêu cầu ban đầu + phản hồi vòng 1 + phản hồi ping‑pong mới nhất.
• Khi vòng lặp kết thúc, OpenClaw chạy bước announce tác tử‑tác tử (chỉ tác tử đích):
  • Trả lời chính xác ANNOUNCE_SKIP để giữ im lặng.
  • Bất kỳ phản hồi nào khác sẽ được gửi tới kênh đích.
  • Bước announce bao gồm yêu cầu ban đầu + phản hồi vòng 1 + phản hồi ping‑pong mới nhất.

​

Trường Channel

• Với nhóm, channel là kênh được ghi trên mục phiên.
• Với chat trực tiếp, channel ánh xạ từ lastChannel.
• Với cron/hook/node, channel là internal.
• Nếu thiếu, channel là unknown.

​

Bảo Mật / Chính Sách Gửi

{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "match": { "channel": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
      "default": "allow"
    }
  }
}

• sendPolicy: "allow" | "deny" (không đặt = kế thừa cấu hình)
• Có thể đặt qua sessions.patch hoặc /send on|off|inherit chỉ cho owner (tin nhắn độc lập).

• chat.send / agent (gateway)
• logic phân phối auto-reply

​

sessions_spawn

• task (bắt buộc)
• label? (tùy chọn; dùng cho logs/UI)
• agentId? (tùy chọn; spawn dưới một agent id khác nếu được phép)
• model? (tùy chọn; ghi đè mô hình sub-agent; giá trị không hợp lệ sẽ lỗi)
• runTimeoutSeconds? (mặc định 0; khi đặt, hủy lần chạy sub-agent sau N giây)
• cleanup? (delete|keep, mặc định keep)

• 45. agents.list[].subagents.allowAgents: danh sách id agent được phép qua agentId (["*"] để cho phép bất kỳ). 46. Mặc định: chỉ agent yêu cầu.

• Dùng agents_list để khám phá các agent id nào được phép cho sessions_spawn.

• Bắt đầu một phiên agent:<agentId>:subagent:<uuid> mới với deliver: false.
• Sub-agent mặc định có đầy đủ bộ công cụ trừ các công cụ phiên (có thể cấu hình qua tools.subagents.tools).
• Sub-agent không được phép gọi sessions_spawn (không spawn sub-agent → sub-agent).
• Luôn không chặn: trả về { status: "accepted", runId, childSessionKey } ngay lập tức.
• Sau khi hoàn tất, OpenClaw chạy bước announce sub-agent và đăng kết quả lên kênh chat của người yêu cầu.
• Trả lời chính xác ANNOUNCE_SKIP trong bước announce để giữ im lặng.
• Phản hồi announce được chuẩn hóa thành Status/Result/Notes; Status đến từ kết quả runtime (không phải văn bản của mô hình).
• Các phiên sub-agent được tự động lưu trữ sau agents.defaults.subagents.archiveAfterMinutes (mặc định: 60).
• Phản hồi announce bao gồm một dòng thống kê (thời gian chạy, tokens, sessionKey/sessionId, đường dẫn transcript và chi phí tùy chọn).

​

Khả Năng Hiển Thị Phiên Sandbox

{
  agents: {
    defaults: {
      sandbox: {
        // default: "spawned"
        sessionToolsVisibility: "spawned", // or "all"
      },
    },
  },
}