人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载本文围绕 OpenClaw 的会话工具集Session Tools展开系统讲解 Agent 如何通过sessions_list、sessions_history、sessions_send、sessions_spawn四个工具列出会话、获取历史、跨会话发消息以及派生隔离子代理会话。读完本文你将掌握会话键session key的编码规则、每个工具的完整参数与返回结构、跨 Agent 消息的 ping-pong 与 announce 流程以及通过sendPolicy、tools.sessions.visibility、沙箱会话可见性等机制实施的安全边界配置。一、设计目标与工具总览OpenClaw 会话工具的设计目标是提供一套小、难以误用small, hard-to-misuse的工具集让 Agent 能够完成三类基本操作列出会话sessions_list获取某个会话的历史记录sessions_history向另一个会话发送消息sessions_send派生一个隔离的子代理会话sessions_spawn四个工具的实现分别位于仓库源码 src/agents/tools/sessions-list-tool.ts、sessions-history-tool.ts、sessions-send-tool.ts 与 sessions-spawn-tool.ts它们都实现了统一的AnyAgentTool接口定义见 src/agents/tools/common.ts通过 TypeBox 声明参数 schema由 Agent 运行时统一调度。在深入各工具之前必须先理解 OpenClaw 的会话键模型——它是所有会话工具的寻址基础。二、会话键Session Key模型OpenClaw 使用字符串形式的会话键标识每一个会话规则如下会话类型会话键格式主直接聊天main字面量main解析为当前 Agent 的主键群聊agent:agentId:channel:group:id或agent:agentId:channel:channel:id需传完整键定时任务Croncron:job.id钩子Hookshook:uuid除非显式指定节点会话Nodenode-nodeId除非显式指定子代理会话agent:agentId:subagent:uuid由sessions_spawn创建两个保留值需要注意global与unknown是保留值永远不会出现在列表输出中。如果session.scope globalOpenClaw 会在所有会话工具中把它别名alias为main调用者永远不会看到global这个键。main的别名解析逻辑体现在 src/agents/tools/sessions-resolution.ts 的resolveMainSessionAlias它根据当前 Agent 的配置解析出mainKey与alias而会话类型的分类main/group/cron/hook/node/other由 src/agents/tools/sessions-helpers.ts 中的classifySessionKind实现键以cron:、hook:、node-/node:前缀开头的分别归为对应类型包含:group:或:channel:段落的归为group其余归为other。三、sessions_list列出会话sessions_list以行row数组的形式返回会话列表。参数参数类型说明kindsstring[]可选过滤条件取值main \| group \| cron \| hook \| node \| otherlimitnumber可选最大行数默认取服务端默认值代码中 clamp 上限为 200activeMinutesnumber可选仅返回 N 分钟内有更新的会话messageLimitnumber可选0 不包含消息默认0 附带最近 N 条消息行为细节当messageLimit 0时工具会对每个会话调用网关的chat.history拉取历史并截取最后 N 条消息。工具调用结果toolResult会被过滤掉不在列表输出中出现需要查看工具消息时请改用sessions_history。过滤逻辑在 sessions-helpers.ts 的stripToolMessages中实现所有role toolResult或role tool的消息都会被剔除。在沙箱化sandboxed的 Agent 会话中运行时会话工具默认只显示被本会话派生的子会话spawned-only visibility详见下文沙箱会话可见性一节。从源码看sessions-list-tool.ts并发拉取历史时使用最大 4 路并发maxConcurrent Math.min(4, ...)的工作池避免一次性打爆网关。返回行结构JSON每行row包含以下字段key会话键字符串kindmain | group | cron | hook | node | otherchannelwhatsapp | telegram | discord | signal | imessage | webchat | internal | unknowndisplayName群聊显示标签如有updatedAt最后更新时间毫秒时间戳sessionIdmodel、contextTokens、totalTokensthinkingLevel、verboseLevel、systemSent、abortedLastRunsendPolicy会话级发送策略覆盖如设置lastChannel、lastTodeliveryContext规范化后的{ channel, to, accountId }可用时transcriptPath由 store 目录 sessionId 推导的最佳路径messages?仅当messageLimit 0时存在从源码可以看到行结构中还包含origin、spawnedBy、label、parentSessionKey、status、startedAt、endedAt、runtimeMs、childSessions、fastMode、reasoningLevel、elevatedLevel、responseUsage、lastAccountId等附加字段完整类型见 sessions-helpers.ts 中的SessionListRow其中deliveryContext.threadId也会被保留对应测试用例见 sessions-list-tool.test.ts。transcriptPath的推导逻辑会读取网关返回的 store path支持{agentId}占位符与~开头的路径模板再通过resolveSessionFilePath拼接出真实记录文件路径见 sessions-list-tool.ts。四、sessions_history获取会话历史sessions_history用于获取单个会话的完整转录transcript。参数参数类型说明sessionKeystring必填接受会话键或sessions_list返回的sessionIdlimitnumber可选最大消息条数服务端 clampincludeToolsboolean可选默认false行为细节includeToolsfalse时role: toolResult的消息会被过滤复用stripToolMessages。返回消息数组格式为原始转录格式。当传入的是sessionId时OpenClaw 会解析它对应的会话键不存在的 ID 会报错。解析逻辑位于 sessions-resolution.ts包含looksLikeSessionId判断与resolveSessionReference解析流程。源码级安全细节脱敏与截断sessions-history-tool.ts 的实现值得注意它内置了防止敏感信息泄漏的机制敏感信息脱敏返回历史前会调用redactSensitiveText来自 src/logging/redact.ts清洗凭证、API Key、令牌等敏感内容注释中标注了 OC-07 安全项。文本截断单段文本超过 4000 字符SESSIONS_HISTORY_TEXT_MAX_CHARS时会被 UTF-16 安全截断并追加…(truncated)…标记。大字段剥离消息中的details、usage、cost等大体积嵌套字段会被删除thinking块的thinkingSignature加密签名会被移除图片块会删除data并保留omitted: true与字节数。字节硬上限整个返回值被 clamp 到 80 KiBSESSIONS_HISTORY_MAX_BYTES 80 * 1024以内超出时只保留最后一条消息若单条消息仍超限则用占位消息[sessions_history omitted: message too large]替代。返回结果中还带有一组元信息truncated是否发生任何截断、droppedMessages是否丢消息、contentTruncated、contentRedacted、bytes方便调用方感知数据完整性。五、sessions_send向另一会话发送消息sessions_send把一个消息注入到另一个会话中并等待或不等其完成。参数参数类型说明sessionKeystring必填接受会话键或sessions_list返回的sessionIdmessagestring必填要发送的消息timeoutSecondsnumber可选默认00表示 fire-and-forget即发即忘从源码看schema 还额外支持label会话标签最长长度由SESSION_LABEL_MAX_LENGTH约束与agentId组合用于通过标签而非键定位目标会话sessionKey与label二选一同时提供会报错。当用label定位且目标属于另一个 Agent 时会先经过tools.agentToAgent策略检查详见下文安全策略。行为细节timeoutSeconds 0入队后立即返回{ runId, status: accepted }后台继续运行。timeoutSeconds 0等待最多 N 秒返回{ runId, status: ok, reply }。等待超时返回{ runId, status: timeout, error }运行不会取消之后可用sessions_history查看结果。运行失败返回{ runId, status: error, error }。等待动作通过网关的agent.wait方法在服务端侧完成timeoutMs: timeoutMs 2000的网关调用超时因此客户端重连不会中断等待。主运行primary run会注入 Agent 间消息上下文Agent-to-agent message context:包含 requester/target 双方的 session 与 channel 行见 sessions-send-helpers.ts 的buildAgentToAgentMessageContext。跨会话消息持久化时带有message.provenance.kind inter_session同时记录sourceSessionKey、sourceChannel、sourceTool: sessions_send见 sessions-send-tool.ts转录阅读器因此可以区分路由的 Agent 指令与外部用户输入。发送时使用deliver: falsechannel: INTERNAL_MESSAGE_CHANNELlane: AGENT_LANE_NESTED即消息只进入目标会话处理不直接投递到外部聊天通道。每次调用会生成幂等键idempotencyKeyUUID避免重复提交产生重复运行。Reply-back Loop乒乓回复循环主运行完成后OpenClaw 会启动一个reply-back loop实现于 sessions-send-tool.a2a.ts 的runSessionsSendA2AFlow第 2 轮起在 requester 与 target 两个 Agent 之间交替回复。回复精确内容REPLY_SKIP即可终止乒乓判断函数isReplySkip做精确 trim 后匹配。最大轮数为session.agentToAgent.maxPingPongTurns取值范围 0–5默认 5。从 sessions-send-helpers.ts 的resolvePingPongTurns看配置值会被Math.max(0, Math.min(5, ...))钳制。乒乓每轮的提示词由buildAgentToAgentReplyContext生成包含当前角色requester/target、当前轮次与总轮数以及回复REPLY_SKIP停止乒乓的指示。Announce Step宣布步骤乒乓结束后OpenClaw 运行Agent 间 announce 步骤仅 target Agent 参与回复精确内容ANNOUNCE_SKIP保持沉默isAnnounceSkip精确匹配。任何其他回复都会被发送到目标会话所属的聊天通道。announce 提示词包含原始请求original request 第 1 轮回复 最新一轮乒乓回复。需要注意的是announce 投递是**尽力而为best-effort**的status: ok只代表主运行完成并不保证 announce 已送达。六、Channel 字段的推导规则sessions_list输出中的channel字段按以下规则推导实现在 sessions-helpers.ts 的deriveChannel群聊group使用会话条目上记录的channel。直接聊天direct chat由lastChannel映射而来。Cron / Hook / Node 会话固定为internal。缺失时为unknown。此外从deliveryContext可用时中提取的channel、to、accountId、threadId会优先于条目自身的lastChannel/lastTo使用当群键形如agent:agentId:channel:group:id时也能从键的第 2、3 段反推出channel。七、安全与发送策略Send Policy会话工具实施基于策略的发送阻断匹配维度是通道 / 聊天类型channel / chat type而非单个会话 ID。配置示例如下{ session: { sendPolicy: { rules: [ { match: { channel: discord, chatType: group }, action: deny } ], default: allow } } }SessionSendPolicyConfig的结构定义在 config/types.base.tsdefault是兜底动作rules是规则数组每条规则由matchchannel/chatType与action组成。运行时覆盖per-session entry 级别sendPolicy: allow | deny未设置 继承配置。可通过sessions.patch设置或由拥有者发送独立消息/send on|off|inherit切换。强制执行点Enforcement pointschat.send/agent网关侧auto-reply 投递逻辑从源码看跨 Agent 的发送还叠加了第二层控制——tools.agentToAgent{ tools: { agentToAgent: { // 默认 false开启后才允许跨 Agent 的会话访问 enabled: true, // Agent id 或模式的允许列表支持 * 通配 allow: [*] } } }其策略实现在 src/agents/tools/sessions-access.ts 的createAgentToAgentPolicy同 Agent 内部始终放行跨 Agent 时要求enabled true且 requester 与 target 的 id 都命中allow列表支持*与 glob 模式匹配如team-*。未开启时工具会返回明确的错误提示例如Agent-to-agent messaging is disabled. Set tools.agentToAgent.enabledtrue to allow cross-agent sends.。八、sessions_spawn派生隔离的子代理会话sessions_spawn在隔离会话中启动一个子代理sub-agent运行并在完成后把结果 announce 回请求方所在的聊天通道。参数参数类型说明taskstring必填交给子代理的任务描述labelstring可选用于日志 / UI 的标签agentIdstring可选在允许的前提下以另一个 Agent id 派生子代理modelstring可选覆盖子代理的模型非法值报错thinkingstring可选覆盖子代理运行的 thinking 级别runTimeoutSecondsnumber可选默认取agents.defaults.subagents.runTimeoutSeconds未设置则为0设置后 N 秒中止子代理运行threadboolean可选默认false请求通道/插件支持时的线程绑定路由moderun \| session可选默认runthreadtrue时默认sessionmodesession要求threadtruecleanupdelete \| keep可选默认keepsandboxinherit \| require可选默认inheritrequire在目标子运行时未沙箱化时拒绝派生attachments数组可选内联文件仅 subagent 运行时支持ACP 拒绝。每项{ name, content, encoding?: utf8 \| base64, mimeType? }文件物化到子工作区.openclaw/attachments/uuid/返回每文件的 sha256 收据attachAs{ mountPath? }可选为将来的 mount 实现预留的提示从 sessions-spawn-tool.ts 的源码看还有几个补充参数runtimesubagent | acp默认subagent。runtimeacp时支持resumeSessionId恢复既有会话如 Codex 会话 UUID与streamToparent把 ACP 输出流回父会话。cwd子代理工作目录。timeoutSeconds与runTimeoutSeconds等价的向后兼容别名。不支持的参数target、transport、channel、to、threadId、replyTo等会直接抛出ToolInputError提示改用sessions_send做通道投递。允许列表Allowlistagents.list[].subagents.allowAgents允许通过agentId派生的 Agent id 列表[*]允许任意。默认只允许请求方 Agent 自己。沙箱继承守卫如果请求方会话已沙箱化sessions_spawn会拒绝那些会以非沙箱方式运行的目标。发现允许的 Agent id使用agents_list工具。行为细节派生行为由 src/agents/subagent-spawn.ts 的spawnSubagentDirect实现它创建一个agent:agentId:subagent:uuid新会话并设置deliver: false结果不直接投递外部通道。子代理默认使用完整工具集减去会话工具可通过tools.subagents.tools配置。子代理不允许调用sessions_spawn禁止子代理→子代理的嵌套派生maxSpawnDepth默认 1。始终非阻塞立即返回{ status: accepted, runId, childSessionKey }。threadtrue时通道插件可把投递/路由绑定到线程目标Discord 支持受session.threadBindings.*与channels.discord.threadBindings.*控制。完成后运行子代理announce 步骤并把结果发布到请求方聊天通道若 assistant 最终回复为空子代理历史中最近一条toolResult会作为Result包含进 announce。announce 期间回复精确内容ANNOUNCE_SKIP保持沉默。announce 回复被规范化为Status/Result/Notes三段Status来自运行时结果而非模型文本。announce 回复附带统计行运行时长runtime、token 数、sessionKey/sessionId、转录路径transcript path以及可选的费用cost。子代理默认配置agents.defaults.subagents的相关默认值定义见 config/types.agent-defaults.tsarchiveAfterMinutes子代理会话自动归档时间默认 60分钟设为 0 可禁用。maxConcurrent子代理最大并发默认 1。maxSpawnDepthsessions_spawn链最大深度默认 1即不允许嵌套派生。maxChildrenPerAgent单个请求方会话可派生的最大子代理数默认 5。model/thinking子代理默认模型与 thinking 级别。runTimeoutSeconds子代理默认运行超时0 不超时。announceTimeoutMsannounce 投递的网关超时默认 90000 ms。九、沙箱会话可见性Sandbox Session Visibility会话工具可以通过**作用域限定scoping**来减少跨会话访问面。默认行为tools.sessions.visibility默认是tree当前会话 由当前会话派生的子代理会话。对于沙箱化会话agents.defaults.sandbox.sessionToolsVisibility可以**硬性钳制hard-clamp**可见性。配置示例{ tools: { sessions: { // self | tree | agent | all // 默认: tree visibility: tree, }, }, agents: { defaults: { sandbox: { // 默认: spawned sessionToolsVisibility: spawned, // 或 all }, }, }, }可见性语义取值含义self仅当前会话键tree当前会话 当前会话派生的会话默认agent当前 Agent id 名下的任意会话可能包含其他用户all任意会话跨 Agent 仍需tools.agentToAgent源码级实现可见性解析与强制逻辑集中在 src/agents/tools/sessions-access.tsresolveSessionToolsVisibility读取tools.sessions.visibility非法值回落为tree。resolveEffectiveSessionToolsVisibility处理沙箱钳制当会话沙箱化且sessionToolsVisibility spawned时即使把tools.sessions.visibility设为all也会被钳制为tree。这正是文档所述OpenClaw clamps visibility totree的实现依据。createSessionVisibilityGuard生成统一的访问检查器跨 Agent 访问要求visibility all且tools.agentToAgent放行self模式只放行当前会话tree模式通过listSpawnedSessionKeys收集子会话集合后校验。沙箱上下文解析resolveSandboxedSessionToolContext当请求方会话沙箱化且可见性为spawned时restrictToSpawned生效sessions_list的网关调用会带上spawnedBy: requesterKey过滤并排除global/unknown条目见 sessions-list-tool.ts。配置类型方面AgentSandboxConfig.sessionToolsVisibility定义于 config/types.agents-shared.ts取值仅spawned | alltools.sessions.visibility与tools.agentToAgent定义于 config/types.tools.ts。十、实战要点小结寻址直接聊天用main或sessions_list返回的键/ID群聊、Cron、Hook、Node 各有前缀约定global/unknown永远不可见。历史安全sessions_history自带凭据脱敏、4000 字符文本截断与 80 KiB 字节硬上限includeToolsfalse默认过滤工具结果。跨会话发送timeoutSeconds0即发即忘返回accepted等待模式返回ok/reply超时后运行继续用sessions_history补查用REPLY_SKIP/ANNOUNCE_SKIP精确文本控制乒乓与宣布行为。派生子代理sessions_spawn始终非阻塞返回accepted结果通过 announce 步骤回传子代理不再拥有会话工具也不能再嵌套派生默认 60 分钟后自动归档。权限分层sendPolicy按通道/聊天类型tools.agentToAgent跨 Agenttools.sessions.visibility会话工具作用域 沙箱sessionToolsVisibility硬钳制四层叠加构成完整防线。相关契约测试可参考 gateway/server.sessions-send.test.ts 与 src/agents/tools/sessions-list-tool.test.ts。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw 会话工具集Session Tools完全指南会话列表、历史回读、跨会话消息与子代理 SpawnOpenClaw 会话工具集Session Tools完全指南会话列表、历史回读、跨会话消息与子代理 Spawn 导读 OpenClaw 的 Agent人工智能AI Agent即时通讯后端本地部署语音Authelia Session 配置完全指南会话 Cookie、多域名与 Redis 会话存储Authelia Session 配置完全指南会话 Cookie、多域名与 Redis 会话存储 导读 Authelia 依赖会话 Cookie 来授权用户后端认证鉴权单点登录身份认证应用安全OpenClaw 会话管理Session Management权威指南会话键、DM 作用域、重置策略与持久化OpenClaw 会话管理Session Management权威指南会话键、DM 作用域、重置策略与持久化 会话Session是 OpenClaw人工智能AI Agent即时通讯后端本地部署语音上一篇OpenOnload API参考手册开发者必备的完整函数调用指南下一篇SWE-bench API接口全解析从实例创建到评估报告生成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考