会话工具

Goal: small, hard-to-misuse tool set so agents can list sessions, fetch history, and send to another session.

- ''sessions_list''

- ''sessions_history''

- ''sessions_send''

- ''sessions_spawn''

- Main direct chat bucket is always the literal key ''"main"'' (resolved to the current agent's main key).

- 群组聊天是 ''agent:<agentId>:<channel>:group:<id>'' 或 ''agent:<agentId>:<channel>:channel:<id>'' 使用执行（完全那密钥渡执行）。

- Cron任务是 ''cron:<job.id>'' 使用执行。

- 钩子是明示的在设置未被限里 ''hook:<uuid>'' 使用执行。

- 节点会话是明示的在设置未被限里 ''node-<nodeId>'' 使用执行。

''global'' and ''unknown'' are reserved values and are never listed. If ''session.scope = "global"'', we alias it to ''main'' for all tools so callers never see ''global''.

会话行的数组作为列表执行。

参数：

- ''kinds?: string[]'' filter: any of ''"main" | "group" | "cron" | "hook" | "node" | "other"''

- ''limit?: number'' 最大行数（默认：服务器的默认、示示例：200）

- ''activeMinutes?: number'' only sessions updated within N minutes

- ''messageLimit?: number'' 0 = no messages (default 0); >0 = include last N messages

动作：

- ''messageLimit > 0'' fetches ''chat.history'' per session and includes the last N messages.

- Tool results are filtered out in list output; use ''sessions_history'' for tool messages.

- 沙盒代理会话在运行如果已被、会话工具默认生成仅的可见性变为（以下参照）。

行的形状（JSON）：

- ''key''：会话密钥（字符串）

- ''kind''：''main | group | cron | hook | node | other''

- ''channel''：''whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown''

- ''displayName'' (group display label if available)

- ''updatedAt'' (ms)

- ''sessionId''

- ''model''、''contextTokens''、''totalTokens''

- ''thinkingLevel''、''verboseLevel''、''systemSent''、''abortedLastRun''

- ''sendPolicy''（设置如果已被的会话覆盖）

- ''lastChannel''、''lastTo''

- deliveryContext (normalized '{ channel, to, accountId }' when available)

- ''transcriptPath''（存储目录 + sessionId 从派生已执行尽力而为路径）

- ''messages?''（''messageLimit > 0'' 的場合仅）

获取一个会话的记录。

参数：

- ''sessionKey'' (required; accepts session key or ''sessionId'' from ''sessions_list'')

- ''limit?: number'' 最大消息数（服务器限制）

- ''includeTools?: boolean''（默认false）

动作：

- ''includeTools=false'' filters ''role: "toolResult"'' messages.

- 生的记录形式在消息的数组返执行。

- When given a ''sessionId'', OpenClaw resolves it to the corresponding session key (missing ids error).

別的会话在消息发送执行。

参数：

- ''sessionKey'' (required; accepts session key or ''sessionId'' from ''sessions_list'')

- ''message''（必须）

- ''timeoutSeconds?: number'' (default >0; 0 = fire-and-forget)

动作：

- timeoutSeconds = 0: enqueue and return '{ runId, status: "accepted" }'.

- timeoutSeconds > 0: wait up to N seconds for completion, then return '{ runId, status: "ok", reply }'.

- 待機但超时如果执行了：'{ runId, status: "timeout", error }'。运行是継続执行。後在 sessions_history 呼必出请。

- 运行但失败如果执行了：'{ runId, status: "error", error }'。

- Announce delivery runs after the primary run completes and is best-effort; ''status: "ok"'' does not guarantee the announce was delivered.

- Waits via gateway ''agent.wait'' (server-side) so reconnects don't drop the wait.

- Agent-to-agent message context is injected for the primary run.

- 初期运行的完成後、OpenClaw是回复循环运行执行：

- Round 2+ alternates between requester and target agents.

- Reply exactly ''REPLY_SKIP'' to stop the ping-pong.

- Max turns is ''session.agentToAgent.maxPingPongTurns'' (0–5, default 5).

- 循环的结束後、OpenClaw是代理間通知步骤运行执行（目标代理仅）：

- 沈黙保次在是正確在 ''ANNOUNCE_SKIP'' 在回复请。

- 他的回复是全部目标渠道在发送被。

- Announce step includes the original request + round-1 reply + latest ping-pong reply.

- For groups, ''channel'' is the channel recorded on the session entry.

- For direct chats, ''channel'' maps from ''lastChannel''.

- For cron/hook/node, ''channel'' is ''internal''.

- If missing, ''channel'' is ''unknown''.

Policy-based blocking by channel/chat type (not per session id).

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

Runtime override (per session entry):

- ''sendPolicy: "allow" | "deny"''（未设置=设置継承）

- Settable via ''sessions.patch'' or owner-only ''/send on|off|inherit'' (standalone message).

运行积分钟：

- ''chat.send'' / ''agent''（网关）

- auto-reply delivery logic

Spawn a sub-agent run in an isolated session and announce the result back to the requester chat channel.

参数：

- ''task''（必须）

- ''label?''（选项；日志/UI用）

- ''agentId?''（选项；允许如果已被、別的代理ID在生成）

- ''model?''（选项；子代理模型覆盖；禁用那值错误）

- ''runTimeoutSeconds?''（默认0；设置如果已被、N秒後在子代理运行中止）

- ''cleanup?''（''delete|keep''、默认 ''keep''）

允许列表：

- ''agents.list[].subagents.allowAgents'': list of agent ids allowed via ''agentId'' (''["*"]'' to allow any). Default: only the requester agent.

发现：

- Use ''agents_list'' to discover which agent ids are allowed for ''sessions_spawn''.

动作：

- ''deliver: false'' 在新 ''deliver: false'' 会话开始执行。

- Sub-agents default to the full tool set ''minus session tools'' (configurable via ''tools.subagents.tools'').

- Sub-agents are not allowed to call ''sessions_spawn'' (no sub-agent → sub-agent spawning).

- Always non-blocking: returns '{ status: "accepted", runId, childSessionKey }' immediately.

- After completion, OpenClaw runs a sub-agent announce step and posts the result to the requester chat channel.

- 沈黙保次在是通知步骤在正確在 ''ANNOUNCE_SKIP'' 在回复请。

- 通知回复是 ''Status''/''Result''/''Notes'' 在被规范化。''Status'' 是运行时结果从获取被（模型文本不是）。

- 子代理会话是 ''agents.defaults.subagents.archiveAfterMinutes''（默认：60）後在自动的在被归档。

- Announce replies include a stats line (runtime, tokens, sessionKey/sessionId, transcript path, and optional cost).

沙盒会话可以使用会话工具，但默认情况下它们只能看到通过 ''sessions_spawn'' 生成的会话。

设置：

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