Session Tools

Mục tiêu: Một bộ công cụ nhỏ gọn, khó dùng sai để Agent có thể liệt kê các session, lấy lịch sử và gửi tin nhắn sang session khác.

Tên các công cụ

sessions_list
sessions_history
sessions_send
sessions_spawn

Mô hình Key

Bucket chat trực tiếp chính luôn là key literal "main" (được resolve thành main key của agent hiện tại).
Chat nhóm dùng agent:<agentId>:<channel>:group:<id> hoặc agent:<agentId>:<channel>:channel:<id> (truyền full key).
Cron job dùng cron:<job.id>.
Hook dùng hook:<uuid> trừ khi được set rõ ràng.
Node session dùng node-<nodeId> trừ khi được set rõ ràng.

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

sessions_list

Liệt kê các session dưới dạng mảng các dòng.

Tham số:

kinds?: string[] bộ lọc: bất kỳ giá trị nào trong "main" | "group" | "cron" | "hook" | "node" | "other"
limit?: number số dòng tối đa (mặc định: giá trị mặc định của server, giới hạn ví dụ 200)
activeMinutes?: number chỉ lấy các session đượ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 cùng

Hành vi:

messageLimit > 0 sẽ fetch chat.history cho mỗi session và bao gồm N tin nhắn cuối cùng.
Kết quả công cụ được lọc ra khỏi output danh sách; dùng sessions_history để xem tin nhắn công cụ.
Khi chạy trong một Agent session sandboxed, các session tool mặc định chỉ hiển thị spawned-only visibility (xem bên dưới).

Cấu trúc dòng (JSON):

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

sessions_history

Lấy transcript cho một session.

Tham số:

sessionKey (bắt buộc; chấp nhận session key hoặc sessionId từ sessions_list)
limit?: number số tin nhắn tối đa (server giới hạn)
includeTools?: boolean (mặc định false)

Hành vi:

includeTools=false lọc các tin nhắn role: "toolResult".
Trả về mảng tin nhắn ở định dạng transcript thô.
Khi được cung cấp sessionId, OpenClaw sẽ resolve nó thành session key tương ứng (id thiếu sẽ báo lỗi).

sessions_send

Gửi tin nhắn vào một session khác.

Tham số:

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

Hành vi:

timeoutSeconds = 0: đưa vào hàng đợi và trả về { runId, status: "accepted" }.
timeoutSeconds > 0: đợi tối đa N giây để hoàn thành, sau đó trả về { runId, status: "ok", reply }.
Nếu đợi timeout: { runId, status: "timeout", error }. Run tiếp tục; gọi sessions_history sau.
Nếu run thất bại: { runId, status: "error", error }.
Announce delivery chạy sau khi primary run hoàn thành và là best-effort; status: "ok" không đảm bảo announce đã được gửi.
Đợi thông qua gateway agent.wait (server-side) nên reconnect không làm mất wait.
Context tin nhắn agent-to-agent được inject cho primary run.
Sau khi primary run hoàn thành, OpenClaw chạy một reply-back loop:
- Round 2+ xen kẽ giữa requester và target agent.
- Reply chính xác REPLY_SKIP để dừng ping-pong.
- Số turn tối đa là session.agentToAgent.maxPingPongTurns (0–5, mặc định 5).
Khi loop kết thúc, OpenClaw chạy agent-to-agent announce step (chỉ target agent):
- Reply chính xác ANNOUNCE_SKIP để im lặng.
- Bất kỳ reply nào khác sẽ được gửi đến target channel.
- Announce step bao gồm request gốc + reply round-1 + reply ping-pong mới nhất.

Trường Channel

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

Security / Send Policy

Chặn dựa trên policy theo channel/chat type (không phải theo session id).

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

Ghi đè runtime (theo session entry):

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

Điểm thực thi:

chat.send / agent (gateway)
logic auto-reply delivery

sessions_spawn

Spawn một sub-agent run trong một session riêng biệt và announce kết quả về requester chat channel.

Tham số:

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

Allowlist:

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

Discovery:

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

Hành vi:

Bắt đầu một session mới agent:<agentId>:subagent:<uuid> với deliver: false.
Sub-agent mặc định có full tool set trừ session tools (có thể config qua tools.subagents.tools).
Sub-agent không được phép gọi sessions_spawn (không có sub-agent → sub-agent spawning).
Luôn non-blocking: trả về { status: "accepted", runId, childSessionKey } ngay lập tức.
Sau khi hoàn thành, OpenClaw chạy sub-agent announce step và đăng kết quả lên requester chat channel.
Reply chính xác ANNOUNCE_SKIP trong announce step để im lặng.
Announce reply được chuẩn hóa thành Status/Result/Notes; Status đến từ runtime outcome (không phải model text).
Sub-agent session được tự động archive sau agents.defaults.subagents.archiveAfterMinutes (mặc định: 60).
Announce reply bao gồm dòng thống kê (runtime, token, sessionKey/sessionId, transcript path và cost tùy chọn).

Sandbox Session Visibility

Các session sandboxed có thể dùng session tool, nhưng mặc định chúng chỉ thấy các session mà chúng spawn qua sessions_spawn.

Config:

{
  agents: {
    defaults: {
      sandbox: {
        // default: "spawned"
        sessionToolsVisibility: "spawned", // hoặc "all"
      },
    },
  },
}