sessions_spawn 完整参考

概述

sessions_spawn 是 OpenClaw 的核心编排工具，用于派生后台 Agent 运行（sub-agent）或外部 ACP harness 会话。调用后立即返回，非阻塞。

返回值：{ status: "accepted", runId, childSessionKey }

---

可用性与工具 Profile

sessions_spawn 属于 group:sessions，不同 profile 的包含情况：

Profile	是否包含 sessions_spawn
minimal	否
messaging	否（需手动添加）
coding	是
full	是

messaging profile 下手动启用：

{
  tools: {
    profile: "messaging",
    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],
  },
}

Channel/group、provider、sandbox、per-agent 策略可在 profile 阶段之后再移除该工具。用 /tools 确认当前会话的有效工具列表。

---

两种运行时模式

模式一：native sub-agent（默认）

{
  "task": "分析这份报告并总结关键发现",
  "runtime": "subagent"
}

• 会话 key：agent:<agentId>:subagent:<uuid>
• 任务通过子会话第一条可见消息 [Subagent Task] 传递
• 系统提示只携带运行时规则和路由上下文，不重复任务内容

模式二：ACP 外部 harness

{
  "task": "打开仓库并总结失败的测试",
  "runtime": "acp",
  "agentId": "codex"
}

• 会话 key：agent:<agentId>:acp:<uuid>
• 需要安装并启用 @openclaw/acpx 插件
• 支持的 harness：claude、codex、cursor、gemini、opencode、droid 等
• ACP 会话在宿主机运行，不受 OpenClaw sandbox 约束
• 沙箱会话中禁止发起 ACP spawn

---

完整参数表

通用参数

参数	类型	默认值	说明
task	string	必填	子 Agent 的任务描述
runtime	"subagent" | "acp"	"subagent"	运行时类型
agentId	string	—	目标 Agent ID（受 allowAgents 限制）
taskName	string	—	稳定编排句柄，格式 [a-z][a-z0-9_]{0,63}，用于后续 steer/kill 定位
label	string	—	人类可读标签
model	string	继承调用方	覆盖子 Agent 模型
thinking	string	继承调用方	覆盖 thinking 级别
runTimeoutSeconds	number	0（无超时）	超时后中止运行
thread	boolean	false	是否绑定 channel 线程
mode	"run" | "session"	"run"	"session" 需要 thread: true
cleanup	"delete" | "keep"	"keep"	"delete" 在 announce 后立即归档（仍保留 transcript）
context	"isolated" | "fork"	"isolated"	"fork" 将调用方 transcript 分支到子会话
sandbox	"inherit" | "require"	"inherit"	"require" 拒绝非沙箱目标

native sub-agent 专用参数

（无额外专用参数，以上通用参数均适用）

ACP 专用参数

参数	类型	说明
resumeSessionId	string	恢复已有 ACP 会话（目标需支持 session/load）
streamTo	"parent"	将 ACP 运行进度流式传给父会话
cwd	string	请求的运行时工作目录

注意：sessions_spawn 不接受投递参数（target、channel、to、threadId、replyTo、transport）。投递由子 Agent 自己用 message/sessions_send 完成。

---

上下文模式（context）

模式	适用场景	行为
isolated（默认）	新鲜研究、独立实现、可在 task 文本中说明的工作	创建干净子 transcript，token 消耗更低
fork	依赖当前对话、已有工具结果或调用方 transcript 中细微指令的工作	将调用方 transcript 分支到子会话后再启动

• 线程绑定 spawn 默认 fork
• 非线程 spawn 默认 isolated
• fork 要谨慎使用，不是写清楚 task prompt 的替代品

---

嵌套深度与工具策略

默认子 Agent 不能再派生子 Agent（maxSpawnDepth: 1）。

深度	Session key 格式	角色	能否派生	获得的 session 工具
0	agent:<id>:main	主 Agent	始终可以	全部
1（叶子，默认）	agent:<id>:subagent:<uuid>	叶子 sub-agent	否	无 session 工具
1（编排器，maxSpawnDepth>=2）	agent:<id>:subagent:<uuid>	编排器	是	sessions_spawn、subagents、sessions_list、sessions_history
2	agent:<id>:subagent:<uuid>:subagent:<uuid>	叶子工作 Agent	永不	无 session 工具

最大嵌套深度 5（maxSpawnDepth 范围 1–5），推荐 2。

---

工具策略与权限控制

全局 deny 示例（安全加固）

{
  tools: {
    deny: ["sessions_spawn", "sessions_send"],
  },
}

沙箱内工具策略

{
  tools: {
    sandbox: {
      tools: {
        allow: ["sessions_spawn", "sessions_list", "sessions_history", "sessions_send", "session_status"],
        deny: ["browser", "canvas", "nodes", "cron", "gateway"],
      },
    },
  },
}

sub-agent 工具策略覆盖

{
  tools: {
    subagents: {
      tools: {
        deny: ["gateway", "cron"],
        // allow 设置后变为 allow-only（deny 仍优先）
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

tools.subagents.tools.allow 只能收窄已解析的工具集，不能添加被 tools.profile 移除的工具。

per-agent 允许 sessions_spawn

{
  agents: {
    list: [
      {
        id: "family",
        tools: {
          allow: ["read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

---

完整配置参考

agents.defaults.subagents

{
  agents: {
    defaults: {
      subagents: {
        delegationMode: "prefer",        // "suggest"（默认）或 "prefer"
        maxSpawnDepth: 2,                // 嵌套深度，默认 1，最大 5
        maxChildrenPerAgent: 5,          // 每个会话最大活跃子 Agent 数，默认 5，范围 1-20
        maxConcurrent: 8,                // 全局并发 lane 上限，默认 8
        runTimeoutSeconds: 900,          // sessions_spawn 省略时的默认超时（0=无超时）
        announceTimeoutMs: 120000,       // 每次 announce 投递超时（毫秒），默认 120000
        archiveAfterMinutes: 60,         // 自动归档时间，默认 60 分钟
        model: "anthropic/claude-haiku-4-5", // 子 Agent 默认模型（省略则继承调用方）
        thinking: "fast",                // 子 Agent 默认 thinking 级别
        allowAgents: ["*"],              // 允许 agentId 目标列表（默认仅同 agent）
        requireAgentId: false,           // 强制 sessions_spawn 必须指定 agentId
      },
    },
  },
}

tools.sessions_spawn（附件支持）

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false,              // 默认关闭，需手动开启
        maxTotalBytes: 5242880,      // 5 MB 总大小
        maxFiles: 50,
        maxFileBytes: 1048576,       // 1 MB 单文件
        retainOnSessionKeep: false,  // cleanup="keep" 时是否保留附件
      },
    },
  },
}

附件说明：

• 仅支持 runtime: "subagent"，ACP 不支持
• 文件写入子工作区 .openclaw/attachments/<uuid>/，附带 .manifest.json
• 附件内容自动从 transcript 持久化中脱敏
• 权限：目录 0700，文件 0600

tools.sessions（可见性）

{
  tools: {
    sessions: {
      visibility: "tree",  // self | tree（默认）| agent | all
    },
  },
}

级别	范围
self	仅当前会话
tree	当前会话 + 派生的子 Agent（默认）
agent	该 agent 的所有会话
all	所有会话（跨 agent 还需 tools.agentToAgent）

沙箱会话强制锁定为 tree。

---

线程绑定（thread: true）

目前仅 Discord 支持持久线程绑定 sub-agent 会话。

// Discord 线程绑定配置
{
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,           // 空闲自动解绑（0=禁用）
        maxAgeHours: 0,          // 硬上限（0=禁用）
        spawnSessions: true,     // 控制 sessions_spawn({ thread: true }) 是否自动创建/绑定线程
        defaultSpawnContext: "fork",  // 线程绑定 spawn 的默认 context
      },
    },
  },
}

线程绑定流程：

1. sessions_spawn 加 thread: true（可选 mode: "session"）
2. OpenClaw 在当前 channel 创建或绑定线程到该会话
3. 该线程中的后续消息路由到绑定会话
4. /session idle 查看/更新空闲自动解绑；/session max-age 控制硬上限
5. /unfocus 手动解绑

---

Announce 机制

子 Agent 完成后通过 announce 步骤回报结果：

字段	来源
Source	subagent 或 cron
Session ids	子会话 key/id
Status	从运行时结果派生（success/error/timeout/unknown），不从模型文本推断
Result content	最新可见 assistant 文本，否则为净化后的工具/工具结果文本
Follow-up	说明何时回复 vs 保持静默的指令

特殊行为：

• 子 Agent 回复精确字符串 ANNOUNCE_SKIP → 不发布任何内容
• 最新 assistant 文本为精确 NO_REPLY / no_reply → 抑制 announce 输出
• Stats 行：运行时长、token 用量、估算费用、sessionKey/sessionId/transcript 路径

---

安全注意事项

来自 gateway/security/index.md：

sessions_spawn — session 编排；远程派生 Agent 等同于 RCE（远程代码执行）

安全建议：

• 非必要不开放 sessions_spawn
• 限制 agents.defaults.subagents.allowAgents 为已知安全的目标 agent
• 需要保持沙箱的工作流，使用 sandbox: "require"
• 沙箱会话中 ACP spawn 被完全阻止

---

与相关工具的关系

工具	关系
sessions_yield	等待 sessions_spawn 完成的唯一正确方式，禁止用轮询替代
subagents	列出/引导/终止已派生的 sub-agent，作用域限于当前请求方
sessions_send	向已有会话发消息（不派生新会话）
sessions_list	列出会话（不派生）
/subagents spawn	slash 命令版本，一次性模式（mode: "run"）
/acp spawn	ACP 版本的 spawn，通过 chat 操作

---

后台任务追踪

每次 sessions_spawn 都会创建一条后台任务记录：

来源	运行时类型	任务创建时机	默认通知策略
Sub-agent 编排	subagent	通过 sessions_spawn 派生 sub-agent	done_only
ACP 后台运行	acp	派生子 ACP 会话	done_only

---

限制

• Announce 是尽力而为的，网关重启会丢失待处理的 announce
• 子 Agent 共享同一网关进程资源，maxConcurrent 是安全阀
• 始终非阻塞，立即返回
• 子 Agent 上下文只注入 AGENTS.md、TOOLS.md、SOUL.md、IDENTITY.md、USER.md（不含 MEMORY.md、HEARTBEAT.md、BOOTSTRAP.md）
• runTimeoutSeconds 只停止运行，不自动归档
• ACP spawn 不支持 sandbox: "require"
• 沙箱会话中禁止 ACP spawn

---

相关页面

• concepts/tool-subagents — Sub-agents 完整文档（嵌套、Announce、工具策略）
• concepts/tool-acp-agents — ACP agents（外部 harness：Claude Code/Cursor/Gemini CLI 等）
• session — 会话路由与生命周期
• queue — 命令队列与并发控制（subagent lane）
• multi-agent — 多 Agent 路由与 binding 规则
• concepts/tool-agent-send — Agent Send（CLI 触发 Agent 运行）