万字解析 OpenClaw 源码架构-代理系统（一）

代理开发与调试

项目结构

OpenClaw是一个多平台、多通道的个人AI助手系统，核心由"网关控制平面 + 代理运行时 + 工具与技能体系 + 会话与工作空间"构成。下图给出高层结构示意（概念映射）：

graph TB subgraph "客户端" UI["Web 控制台/桌面应用"] 节点["移动/桌面节点"] end subgraph "网关控制平面" WS["WebSocket 控制面"] 配置["配置与路由"] 会话["会话存储与维护"] 日志["日志与审计"] end subgraph "代理运行时" 运行时["嵌入式代理运行时
pi-mono 衍生"] 提示["系统提示工程"] 工具["内置工具集"] 技能["技能加载与过滤"] end 客户端 --> WS WS --> 运行时 运行时 --> 工具 运行时 --> 技能 运行时 --> 会话 运行时 --> 日志 配置 --> WS 会话 --> WS 日志 --> WS

核心组件

• 代理运行时与会话循环：负责消息输入、上下文组装、模型推理、工具执行、流式输出与持久化。
• 工作空间与引导文件：作为代理唯一工作目录，注入AGENTS/SOUL/TOOLS等引导文件，支持Git备份与迁移。
• 系统提示工程：构建紧凑、可配置的系统提示，按模式注入工具列表、安全提醒、技能清单、时间信息等。
• 子代理与会话工具：支持后台并行任务、线程绑定、深度限制、并发控制与结果回传。
• 调试与开发工具：Watch模式、原始流日志、运行时调试覆盖、开发配置隔离。
• 技能体系：多级加载优先级、环境/二进制/配置门禁、安装器与热更新、令牌开销估算。

架构总览

下图展示一次典型代理循环的端到端流程，包括入口、队列与并发、提示装配、事件流与收尾：

sequenceDiagram participant 客户端 as "客户端/CLI" participant 网关 as "网关 RPC/CLI" participant 会话 as "会话管理器" participant 运行时 as "嵌入式代理运行时" participant 模型 as "模型提供方" participant 工具 as "工具执行器" 客户端->>网关 : 发送消息/命令 网关->>会话 : 解析会话键/准备工作空间 会话-->>网关 : 返回会话状态 网关->>运行时 : 启动代理循环序列化/排队 运行时->>运行时 : 组装系统提示含引导文件/技能 运行时->>模型 : 推理请求流式/分块 模型-->>运行时 : 流式响应思考/文本/工具调用 运行时->>工具 : 执行工具调用 工具-->>运行时 : 工具结果 运行时-->>网关 : 事件流生命周期/助手/工具 网关-->>客户端 : 实时流式回复 运行时->>会话 : 写入转录/统计 运行时-->>网关 : 生命周期结束/错误

详细组件分析

代理测试辅助工具

• Watch模式与开发配置隔离：通过全局--dev与网关--dev组合，实现状态隔离与默认引导，便于快速迭代与复现问题。
• 原始流日志：开启原始助手流与pi-mono原始块日志，用于观察推理泄漏与分块细节。
• 运行时调试覆盖：/debug命令在内存中临时覆盖配置，无需修改磁盘配置即可切换参数。

flowchart TD Start(["开始"]) --> DevProfile["设置 OPENCLAW_PROFILE=dev"] DevProfile --> DevGateway["启动网关 --dev自动写入最小配置/种子工作空间"] DevGateway --> Watch["pnpm gateway:watch热重载"] Watch --> EnableRaw["启用原始流日志CLI 或环境变量"] EnableRaw --> Inspect["观察原始流/分块"] Inspect --> DebugOverride["/debug 切换运行时覆盖"] DebugOverride --> End(["结束"])

工作空间管理与压缩机制

• 默认位置与布局：工作空间为代理唯一工作目录，推荐使用openclaw setup初始化，包含AGENTS/SOUL/TOOLS/BOOTSTRAP/IDENTITY/USER等引导文件。
• Git备份策略：建议将工作空间放入私有Git仓库，仅提交引导文件与每日记忆文件，避免提交凭据与会话历史。
• 压缩与修剪：系统提示注入的引导文件会进行截断与标记，防止上下文膨胀；会话修剪在LLM调用前清理旧工具结果，减少上下文占用。
• 大文件与令牌成本：MEMORY.md等大文件需谨慎，建议定期归档或使用memory_search/memory_get按需读取。

flowchart TD Init["初始化工作空间openclaw setup"] --> Seed["种子引导文件AGENTS/SOUL/TOOLS/IDENTITY/USER/BOOTSTRAP"] Seed --> Inject["每轮注入系统提示引导文件截断/标记"] Inject --> Trim["会话修剪调用前清理旧工具结果"] Trim --> Backup["Git备份私有仓库，仅提交必要文件"] Backup --> Compress["长期记忆归档按需检索"]

系统提示工程

• 结构化组成：工具列表、安全提醒、可用技能清单、自更新指引、工作空间路径、文档位置、注入的引导文件、沙箱信息、当前日期时间、回复标签、心跳、运行时信息、推理可见性。
• 模式控制：full/minimal/none三种模式，子代理使用minimal以缩小上下文。
• 引导文件注入：AGENTS/SOUL/TOOLS/IDENTITY/USER/HEARTBEAT/MEMORY等，支持截断与警告标记，总量与单文件上限可配置。
• 时间处理：仅包含时区信息以稳定提示缓存；需要实时时间时使用会话状态。

flowchart TD Build["构建系统提示"] --> Base["基础结构工具/安全/技能/工作空间/文档"] Base --> Inject["注入引导文件截断/标记"] Inject --> Sandbox["沙箱信息启用时"] Sandbox --> Time["当前日期时间时区"] Time --> Mode["提示模式full/minimal/none"] Mode --> Output["输出到模型"]

子代理注册与生命周期管理

• 角色与目标：并行研究/长任务/慢速工具，保持隔离（会话分离+可选沙箱），硬限制工具面，支持可配置嵌套深度。
• 启动方式：/subagents spawn（一次性）与sessions_spawn（可线程绑定/持久会话），支持模型/思考级别覆盖、超时、清理策略。
• 线程绑定：Discord等适配器支持线程绑定，配合/focus、/unfocus、/agents、/session idle/max-age等命令。
• 并发与深度：默认最大深度1，可提升至2形成编排者-工作者模式；全局并发与每会话子代上限可配置；停止主会话会级联停止子代。
• 结果回传：子代理完成时在请求者会话中发布摘要/统计，支持ANNOUNCE_SKIP静默。

sequenceDiagram participant 主会话 as "主会话" participant 子代理 as "子代理" participant 请求者 as "请求者聊天" 主会话->>子代理 : sessions_spawn可线程绑定/模式 子代理-->>主会话 : 返回 runId/childSessionKey 子代理->>子代理 : 执行任务受限工具集 子代理-->>主会话 : 完成结果/统计 主会话->>请求者 : 发布摘要/统计可线程保留

代理开发环境搭建与调试工具

• 开发配置隔离：OPENCLAW_PROFILE=dev隔离状态，网关--dev自动写入最小配置与工作空间种子文件。
• Watch模式：监听源码变更并重启，支持传递额外参数；适合快速迭代。
• 原始流日志：记录未过滤的助手流与pi-mono原始块，便于定位推理泄漏与分块行为。
• 运行时调试覆盖：/debug set/unset/reset在内存中临时覆盖配置项，无需重启。

代理配置验证、错误处理与日志记录

• 配置验证：通过openclaw doctor检查DM策略、通道配置、工作空间状态等；会话维护策略（清理/旋转/磁盘预算）可通过openclaw sessions cleanup预览与强制执行。
• 错误处理：代理循环在生命周期事件缺失时回退；工具结果大小与图像负载会被清洗；重复确认与NO_REPLY抑制逻辑避免冗余输出。
• 日志记录：原始流日志可写入指定路径；注意敏感信息脱敏与本地留存时限。

代理开发最佳实践与质量保证

• 工作空间治理：仅在工作空间内存放引导文件与每日记忆；凭据与会话历史放在~/.openclaw；使用私有Git备份。
• 提示工程：保持AGENTS/SOUL/TOOLS简洁；MEMORY.md避免过度增长；合理设置bootstrapMaxChars与bootstrapTotalMaxChars。
• 子代理使用：为重型任务选择更便宜模型；限制嵌套深度；控制并发与每会话子代数量；明确ANNOUNCE_SKIP语义。
• 技能管理：遵循门禁要求（二进制/环境/配置）；在沙箱中运行不受信任技能；利用skills watcher热更新；关注技能列表令牌开销。
• 调试与回归：使用--dev与watch模式；开启原始流日志；/debug覆盖关键开关；定期清理会话存储。

依赖关系分析

• 组件耦合
  • 网关控制平面与代理运行时：通过RPC与事件流交互，会话管理器与日志模块贯穿始终。
  • 代理运行时与系统提示工程：提示装配依赖工作空间引导文件与技能快照。
  • 子代理与会话工具：依赖sessions_*系列工具与线程绑定适配器。
• 外部依赖
  • 模型提供方：OpenAI兼容流式接口；原始块日志仅在使用pi-mono的openai-completions提供方时产生。
  • 渠道适配器：Discord等支持线程绑定与特定配置键。

graph LR 网关["网关控制平面"] --> 运行时["代理运行时"] 运行时 --> 提示["系统提示工程"] 运行时 --> 工具["工具集"] 运行时 --> 会话["会话存储"] 运行时 --> 日志["日志"] 运行时 --> 技能["技能加载"] 子代理["子代理"] --> 会话 子代理 --> 工具 会话 --> 日志

性能考量

• 上下文与令牌
  • 引导文件截断与总量上限控制；技能列表注入字符开销可估算；MEMORY.md按需检索降低上下文占用。
• 会话修剪与维护
  • 调用前修剪旧工具结果；维护策略包括时间窗口、条目上限、轮换与磁盘预算；生产环境建议强制模式并设定合理阈值。
• 子代理与并发
  • 限制最大嵌套深度与全局并发；为重型任务选择低价格模型；及时归档子代理会话。
• 原始流日志
  • 仅在调试阶段启用，注意文件体积与敏感信息脱敏。

代理引擎架构

代理引擎架构

OpenClaw 的代理引擎围绕"网关（Gateway）---路由（Routing）---会话（Sessions）---配置（Config）---代理（Agents）"五大维度组织，形成可插拔、可扩展、可治理的代理执行环境。核心模块职责如下：

• 网关：接收节点事件与外部请求，解析会话与交付目标，触发代理命令与回执。
• 路由：将消息映射到具体代理、账号与会话键，支持别名与回退策略。
• 会话：维护会话状态、最近通道与收件人，支撑按会话复用投递目标。
• 配置：集中式配置合并、默认值与运行时替换，提供代理与工具策略。
• 代理：代理生命周期事件、绑定与配置变更、ACPI/Acp 策略与运行边界。

graph TB GW["网关
server-node-events.ts"] --> RT["路由
resolve-route.ts"] GW --> SESS["会话
sessions.ts"] GW --> CFG["配置
merge-config.ts / defaults.ts"] RT --> BIND["绑定
bindings.ts"] RT --> SK["会话键
session-key.ts"] RT --> ACCT["账号标识
account-id.ts"] GW --> EVT["事件钩子
internal-hooks.test.ts"] GW --> BOOT["引导脚本钩子
boot-md/HOOK.md"] AG["代理
agents.*"] --> GW ACP["ACPI/Acp 策略
policy.ts"] --> GW EXT["扩展运行时
acpx/runtime.ts"] --> AG

核心组件

• 代理路径管理与绑定
  • 绑定列表与路由绑定解析，支持移除绑定、冲突检测与缺失项识别。
  • 代理配置应用与裁剪，支持按代理 ID 更新名称、工作区、代理目录与模型等字段。
• 作用域隔离与引导文件系统
  • 通过会话键与账号标识进行作用域隔离；在网关启动时按代理作用域执行引导脚本（如 BOOT.md）。
• 生命周期管理与状态转换
  • 子代理生命周期结束结果枚举与结局解析，支持重置、删除、超时、被杀等状态。
• 事件处理与消息路由
  • 节点事件驱动代理请求，自动复用会话最近通道与收件人，必要时发出回执；当路由不可达时禁用投递而非全局降级。
• 配置系统与默认参数
  • 合并配置、默认值注入、环境变量替换、路径规范化与会话缓存策略。
• 扩展与运行时边界
  • ACP 策略控制代理允许列表；ACPX 运行时根据 MCP 服务器构建代理命令，支持代理命令覆盖与缓存。

架构总览

下图展示从节点事件到代理执行的关键流程：事件进入网关后，解析会话与路由，决定是否投递与回执；路由解析失败时仅禁用本次投递，避免全局降级；配置与策略参与运行边界控制；扩展运行时可对代理命令进行覆盖与代理。

sequenceDiagram participant Node as "节点" participant GW as "网关(server-node-events)" participant RT as "路由(resolve-route)" participant SESS as "会话(sessions)" participant AG as "代理(agents)" participant ACP as "策略(policy)" participant EXT as "扩展(acpx)" Node->>GW : "agent.request 事件" GW->>SESS : "读取会话最近通道/收件人" GW->>RT : "解析代理路由(通道/账号/会话键)" RT-->>GW : "返回路由(可能为空)" alt 路由可用 GW->>AG : "执行代理命令(可带投递参数)" AG-->>GW : "返回结果" opt 需要回执 GW->>Node : "发送回执" end else 路由不可用 GW->>GW : "记录告警并禁用本次投递" end GW->>ACP : "检查代理策略/允许列表" ACP-->>GW : "允许/拒绝" GW->>EXT : "构建/覆盖代理命令(含MCP)" EXT-->>GW : "返回最终命令"

详细组件分析

组件一：代理路径管理与绑定

• 绑定管理
  • 支持列出现有路由绑定、区分非路由绑定、批量移除绑定，并检测缺失与冲突。
• 代理配置应用
  • 按代理 ID 应用名称、工作区、代理目录与模型等字段，若不存在则追加默认代理条目。
• 代理配置裁剪
  • 移除指定代理条目，并统计移除的绑定与允许项数量，保证配置整洁。

flowchart TD Start(["开始"]) --> List["列出现有绑定"] List --> Diff["区分路由/非路由绑定"] Diff --> Remove["计算待移除索引"] Remove --> Detect["检测缺失与冲突"] Detect --> ApplyCfg["应用代理配置(名称/工作区/目录/模型)"] ApplyCfg --> Prune["裁剪代理配置(移除条目)"] Prune --> End(["结束"])

组件二：作用域隔离与引导文件系统

• 作用域隔离
  • 使用会话键与账号标识进行作用域隔离，确保不同账号与会话不会互相干扰。
• 引导文件系统
  • 在网关启动时，按代理作用域执行引导脚本（例如 BOOT.md），确保每个作用域具备一致的初始化行为。

flowchart TD Boot(["网关启动"]) --> Scope["解析代理作用域(会话键/账号)"] Scope --> Exists{"引导文件存在?"} Exists -- 是 --> Run["执行引导脚本(如 BOOT.md)"] Exists -- 否 --> Skip["跳过引导"] Run --> Done(["完成"]) Skip --> Done

组件三：生命周期管理与状态转换

• 结果枚举
  • 定义子代理生命周期结束的多种结局（正常、错误、超时、被杀、重置、删除）。
• 结局解析
  • 将会话重置原因映射为重置或删除结局，便于上层统一处理。

flowchart TD S(["会话结束"]) --> Check{"是否会话重置?"} Check -- 是 --> Reset["映射为重置结局"] Check -- 否 --> Delete["映射为删除结局"] Reset --> E(["结束"]) Delete --> E

组件四：事件处理与消息路由

• 节点事件驱动
  • 网关接收节点事件，解析会话与投递目标；当请求投递但缺少通道/收件人时，尝试复用会话最近通道与收件人。
• 回执机制
  • 当需要回执且具备投递目标时，发送回执；否则记录告警并跳过。
• 路由不可达策略
  • 路由不可达时仅禁用本次投递，不进行全局降级，避免影响其他会话。

sequenceDiagram participant C as "客户端/节点" participant G as "网关" participant R as "路由" participant S as "会话" participant A as "代理" C->>G : "agent.request(可选 deliver/channel/to)" G->>S : "读取最近通道/收件人" G->>R : "解析路由" alt 路由可用 G->>A : "执行代理(携带投递参数)" opt 需要回执 G-->>C : "发送回执" end else 路由不可用 G-->>G : "记录告警并禁用本次投递" end

组件五：配置系统与默认参数

• 配置合并
  • 将用户配置与内置默认配置合并，确保关键字段不缺失。
• 默认值注入
  • 提供默认代理、模型、端口等默认值，保证最小可用配置。
• 环境变量替换
  • 在运行时对配置中的占位符进行环境变量替换，支持动态注入。
• 路径与会话
  • 规范化路径、缓存会话数据，减少重复 IO。

flowchart TD Load(["加载用户配置"]) --> Merge["合并内置默认配置"] Merge --> Env["环境变量替换"] Env --> Normalize["路径规范化"] Normalize --> Cache["会话缓存"] Cache --> Apply(["应用到运行时"])

组件六：扩展与运行时边界（ACPX/Acp）

• ACP 策略
  • 基于允许列表控制代理是否允许执行，未配置允许列表时默认放行。
• ACPX 运行时
  • 解析代理命令覆盖，构建包含 MCP 服务器信息的代理命令，支持缓存以提升性能。
• 命令构建
  • 将目标命令与 MCP 服务器序列化为 base64url 负载，拼接为可执行命令行。

flowchart TD Policy["策略检查(允许列表)"] --> Allowed{"允许?"} Allowed -- 否 --> Deny["返回策略错误"] Allowed -- 是 --> Resolve["解析代理命令覆盖"] Resolve --> Build["构建MCP代理命令(负载)"] Build --> Cache["写入命令缓存"] Cache --> Exec["执行代理命令"]

依赖关系分析

• 组件耦合
  • 网关高度依赖路由与会话模块；路由依赖绑定、会话键与账号标识；配置模块贯穿所有组件。
• 外部集成
  • ACP 策略与扩展运行时（ACPX）提供安全边界与代理命令覆盖能力。
• 潜在循环依赖
  • 路由与会话之间为单向依赖（路由使用会话键/账号），未见循环依赖迹象。

graph LR GW["网关"] --> RT["路由"] GW --> SESS["会话"] RT --> BIND["绑定"] RT --> SK["会话键"] RT --> ACCT["账号"] GW --> CFG["配置"] GW --> ACP["策略"] GW --> EXT["扩展运行时"]

性能考虑

• 命令缓存
  • ACPX 运行时对代理命令进行缓存，避免重复构建与 IO 开销。
• 会话复用
  • 投递目标缺失时优先复用会话最近通道与收件人，减少路由解析成本。
• 路由不可达短路
  • 路由不可达时立即禁用本次投递并记录告警，避免无效尝试。
• 配置合并与环境变量替换
  • 在启动阶段完成合并与替换，运行时直接使用已解析配置，降低运行时开销。

工具系统与执行

工具系统与执行

工具系统主要由以下层次构成：

• 工具注册与导出：统一入口导出 exec 与 process 工具，并暴露类型与默认值。
• 执行引擎：负责命令解析、环境注入、主机选择、安全策略、批准流程、输出聚合与超时控制。
• 进程管理：对后台会话进行生命周期管理、日志切片、轮询、输入写入、键序列发送、粘贴、终止与清理。
• 变异与显示：识别工具变异行为、构建指纹以去重与防环、生成用户可读的工具显示摘要。
• 循环检测：基于历史记录与模式匹配的环路检测与全局断路器，保障稳定性。
• 缓存与 TTL：文件统计快照、缓存 TTL 计算与持久化时间戳，提升性能与一致性。
• 权限与安全：安全二进制白名单、主机与安全级别、批准策略与节点主机隔离。
• 显示层：移动端工具显示配置与渲染，结合模板系统展示可用工具列表。

graph TB subgraph "工具注册与导出" BT["bash-tools.ts"] end subgraph "执行引擎" BE["bash-tools.exec.ts"] NSR["node-host/invoke-system-run.ts"] end subgraph "进程管理" BP["bash-tools.process.ts"] end subgraph "变异与显示" TM["tool-mutation.ts"] TD["ToolDisplay.kt"] HTML["export-html/template.js"] end subgraph "循环检测" TLD["tool-loop-detection.ts"] DIAG["logging/diagnostic.ts"] end subgraph "缓存与TTL" CU["config/cache-utils.ts"] CTTLS["pi-embedded-runner/cache-ttl.ts"] end subgraph "权限与安全" DOCTOR["commands/doctor-config-flow.ts"] SAFE_BIN_TESTS["doctor-config-flow.safe-bins.test.ts"] end BT --> BE BT --> BP BE --> NSR BE --> DIAG BE --> TLD BP --> DIAG TM --> TD TM --> HTML TLD --> DIAG CU --> CTTLS DOCTOR --> BE SAFE_BIN_TESTS --> DOCTOR

核心组件

• 工具注册与导出
  • 统一导出 exec 与 process 工具工厂函数与类型，便于上层按需装配。
  • 提供默认参数与环境变量注入能力，支持沙箱与主机模式切换。
• 执行引擎
  • 解析命令、工作目录、环境变量、PTY、超时、背景执行窗口等参数。
  • 基于主机（沙箱/网关/节点）与安全级别（deny/allowlist/full）执行策略。
  • 安全二进制白名单与预检，防止脚本中误用 shell 变量语法。
  • 支持批准策略与通知，以及失败/完成后的结果封装。
• 进程管理
  • 列表、轮询、日志切片、写入标准输入、发送键序列、粘贴文本、终止与清理。
  • 轮询等待时间限制、重试建议记录与诊断状态联动。
• 变异与显示
  • 识别写入、编辑、应用补丁、消息发送、定时任务等变异动作。
  • 构建稳定指纹用于重复检测与去重；移动端与 HTML 模板渲染工具摘要。
• 循环检测
  • 基于工具调用历史与模式匹配，检测通用重复、已知轮询无进展、Ping-Pong 交替与全局断路器。
  • 发生阻断时发出诊断事件并记录关键信息。
• 缓存与 TTL
  • 文件统计快照与缓存 TTL 解析；会话管理器中追加/读取缓存 TTL 时间戳。
• 权限与安全
  • 安全二进制可信目录与配置收集，提示不在可信目录的警告。
  • 节点主机运行策略评估，结合批准与白名单判定。

架构总览

下图展示了工具从注册到执行、再到进程管理与循环检测的整体交互：

sequenceDiagram participant Caller as "调用方" participant Reg as "工具注册(bash-tools.ts)" participant Exec as "执行引擎(bash-tools.exec.ts)" participant Gate as "网关/节点(node-host)" participant Proc as "进程管理(bash-tools.process.ts)" participant Loop as "循环检测(tool-loop-detection.ts)" participant Diag as "诊断(logging/diagnostic.ts)" Caller->>Reg : 创建 exec/process 工具实例 Caller->>Exec : 调用 exec(toolCallId, args, signal, onUpdate) Exec->>Gate : 依据主机/安全策略执行命令 Gate-->>Exec : 返回会话ID/状态或挂起 Exec-->>Caller : 返回运行中/完成结果 Caller->>Proc : 调用 process(action, sessionId,...) Proc->>Diag : 记录轮询/日志/状态 Exec->>Loop : 上报调用历史与结果 Loop-->>Exec : 若检测到环路则阻断或告警

详细组件分析

工具注册与导出（bash-tools.ts）

• 导出 exec 与 process 工具工厂函数与类型，统一入口便于上层按需装配。
• 提供默认参数（如背景执行窗口、超时、PATH 前缀、通知开关等），并支持按会话键解析代理 ID。

执行引擎（bash-tools.exec.ts）

• 参数归一化与校验：命令必填、工作目录解析、环境变量合并与验证、PTY、超时、主机与安全级别、批准策略。
• 主机与安全策略：
  • 主机选择：sandbox/gateway/node，默认 sandbox；仅在允许时接受请求主机。
  • 安全级别：deny/allowlist/full，结合请求与配置取最小安全级别。
  • 批准策略：ask/on-miss/off，结合批准系统与 gate 控制。
• 安全二进制与预检：
  • 解析安全二进制白名单与可信目录，未配置的条目会记录警告。
  • 预检脚本文件，避免 shell 变量语法泄漏到 Python/Node。
• 输出与超时：
  • 最大输出限制、挂起最大输出、聚合输出、超时控制、PTY 支持。
• 结果封装：
  • 运行中返回会话 ID 与 PID；完成后返回退出码、耗时、聚合输出等。

flowchart TD Start(["进入 exec.execute"]) --> Validate["校验命令/参数"] Validate --> HostSel["主机选择与安全级别归一化"] HostSel --> EnvMerge["合并并验证环境变量"] EnvMerge --> Precheck["安全二进制与脚本预检"] Precheck --> Run["启动进程/网关/节点执行"] Run --> Yield{"是否需要挂起?"} Yield --> |是| YieldRes["返回运行中结果"] Yield --> |否| Done["返回完成结果"] Run --> |异常| Fail["抛出错误"]

进程管理（bash-tools.process.ts）

• 动作集合：list、poll、log、write、send-keys、submit、paste、kill、clear、remove。
• 会话生命周期：运行中与已完成两类列表，支持按作用域过滤。
• 日志切片：默认尾部展示固定行数，支持 offset/limit 分页。
• 轮询与重试：设置最大轮询等待时间，记录重试建议并在退出时重置。
• 终止策略：优先通过进程监管器取消，否则回退到进程树终止。

flowchart TD PStart(["进入 process.execute"]) --> Action{"action 类型"} Action --> |list| List["列出运行中/已完成会话"] Action --> |poll| Poll["轮询指定会话，聚合输出"] Action --> |log| Log["按窗口切片输出日志"] Action --> |write/send-keys/submit/paste| Stdin["写入标准输入"] Action --> |kill/clear/remove| Terminate["终止或移除会话"] Poll --> Retry["记录/重置重试建议"] Log --> Slice["切片与统计"] Stdin --> Running["返回运行中结果"] Terminate --> Done["返回完成/失败结果"]

变异处理与显示（tool-mutation.ts 与 ToolDisplay.kt）

• 变异识别：
  • 工具名集合与只读动作集合，结合 action 判断是否为变异操作。
  • 特定工具（如 process、message、session_status）有专门规则。
  • 构建稳定指纹：优先使用稳定参数键（如 path、to、jobId、model 等），否则回退到 meta 文本。
• 显示摘要：
  • 移动端根据工具名与 action 生成标题、标签、细节行与表情符号。
  • HTML 模板渲染工具列表，区分必填/可选参数。

flowchart TD MStart(["构建变异状态"]) --> IsMutating{"是否为变异动作?"} IsMutating --> |否| NoFP["返回 undefined 指纹"] IsMutating --> |是| FP["提取稳定参数键/回退 meta"] FP --> State["返回 mutatingAction 与 actionFingerprint"]

循环检测与状态管理（tool-loop-detection.ts 与 diagnostic.ts）

• 检测器：
  • 通用重复、已知轮询无进展、Ping-Pong 交替、全局断路器。
  • 使用稳定哈希（工具名 + 参数 JSON 规范化）进行模式匹配。
• 阈值与级别：
  • 警告阈值、严重阈值、全局断路器阈值，自动保证顺序关系。
• 诊断事件：
  • 记录工具环路事件，包含级别、动作（warn/block）、探测器、计数、消息与配对工具名。

flowchart TD LStart(["上报一次工具调用"]) --> History["更新历史与配对状态"] History --> Detect["检测重复/无进展/Ping-Pong/全局断路器"] Detect --> |未触发| OK["继续执行"] Detect --> |警告| Warn["记录警告事件"] Detect --> |严重| Block["阻断并记录关键事件"]

结果缓存与性能优化（cache-utils.ts 与 cache-ttl.ts）

• 缓存 TTL：
  • 从环境变量解析 TTL，支持非负整数与默认回退。
  • 判断缓存是否启用（TTL > 0）。
• 文件统计快照：
  • 获取文件 mtime 与 size，用于缓存命中判断。
• 会话缓存 TTL：
  • 在会话管理器中追加/读取缓存 TTL 时间戳，忽略持久化失败。

执行策略、权限控制与安全隔离

• 执行默认值解析：
  • 从会话、代理与全局配置解析 host、security、ask、node 等默认值。
• 安全二进制与可信目录：
  • 收集 tools.exec 与代理级配置，提示不在可信目录的条目。
  • 单元测试覆盖安全二进制不在可信目录的提示场景。
• 节点主机运行策略：
  • 评估系统运行策略阶段，结合批准、安全级别、白名单与可信目录，决定允许/拒绝与提示。

工具开发指南与自定义工具创建

• 工具命名与权限：
  • 工具名规范化与长度/格式校验，用于权限分类。
• 工具目录与显示：
  • 工具目录分组模型与工具条目模型，支持插件来源与可选字段。
  • HTML 模板渲染工具列表，展示名称、描述与参数要求。
• 自定义工具集成测试：
  • 测试用例覆盖工具别名、不暴露特定提供程序工具、按子代理会话过滤等场景。

依赖关系分析

graph LR BT["bash-tools.ts"] --> BE["bash-tools.exec.ts"] BT --> BP["bash-tools.process.ts"] BE --> DIAG["logging/diagnostic.ts"] BE --> TLD["tool-loop-detection.ts"] BP --> DIAG TM["tool-mutation.ts"] --> TD["ToolDisplay.kt"] TM --> HTML["export-html/template.js"] DOCTOR["doctor-config-flow.ts"] --> BE DOCTOR --> SAFE_BIN_TESTS["safe-bins.test.ts"] NSR["node-host/invoke-system-run.ts"] --> BE CU["config/cache-utils.ts"] --> CTTLS["pi-embedded-runner/cache-ttl.ts"]

性能考量

• 输出与日志
  • 设置最大输出与挂起最大输出，避免内存膨胀；日志切片默认尾部展示固定行数，支持分页。
• 轮询与重试
  • 限制最大轮询等待时间；根据新输出动态调整重试建议，减少无效轮询。
• 缓存
  • 使用文件统计快照与缓存 TTL，降低重复读取成本；在会话管理器中记录缓存 TTL 时间戳。
• 背景执行
  • 合理设置背景执行窗口与超时，避免长时间占用资源；对挂起会话采用独立生命周期管理。
• 安全预检
  • 在执行前进行脚本文件预检，避免在环路中浪费令牌与资源。

会话管理系统

会话管理系统

会话管理相关代码主要位于以下模块：

• 会话存储与缓存：store.ts、store-cache.ts、store-maintenance.ts、store-migrations.ts、disk-budget.ts
• 会话路径与命名：paths.ts
• 转录修复与完整性：session-transcript-repair.ts
• 文件系统工具：session-utils.fs.ts
• 并发写锁：session-write-lock.ts
• 配置与类型：types.base.ts、cache-utils.ts

graph TB subgraph "会话存储层" A["store.ts
加载/保存/更新会话"] B["store-cache.ts
对象与序列化缓存"] C["store-maintenance.ts
修剪/封顶/轮转"] D["store-migrations.ts
迁移适配"] E["disk-budget.ts
磁盘预算清理"] end subgraph "路径与命名" F["paths.ts
会话目录/文件解析"] end subgraph "转录与修复" G["session-transcript-repair.ts
工具调用/结果配对修复"] end subgraph "文件系统工具" H["session-utils.fs.ts
预览/归档/清理"] end subgraph "并发与锁" I["session-write-lock.ts
进程级写锁"] end subgraph "配置与类型" J["types.base.ts
维护配置/重置策略"] K["cache-utils.ts
缓存TTL/统计快照"] end A --> B A --> C A --> D A --> E A --> F A --> H A --> I A --> J A --> K G --> A

核心组件

• 会话存储与持久化：负责从磁盘加载、合并更新、规范化字段、应用维护策略（修剪、封顶、轮转）、原子写入与缓存同步。
• 会话缓存：支持对象缓存与序列化缓存，带TTL与文件元信息校验，避免脏读。
• 维护策略：按时间阈值修剪过期条目、按数量封顶、按大小轮转sessions.json，并支持磁盘预算清理。
• 路径与命名：统一解析会话目录、默认存储路径、转录文件名规则（含话题主题）。
• 转录修复：严格修复工具调用与结果配对、去重、合成缺失结果、输入清洗与敏感信息脱敏。
• 并发控制：基于锁文件的进程级写锁，支持超时、过期回收、看门狗释放。
• 工具结果守卫：确保严格配对与完整性，避免API拒绝请求。
• 历史记录维护：支持归档与清理，保留最近N份备份，按原因与时间戳归档。

架构总览

会话管理采用"存储+缓存+维护+并发"的分层设计：

• 存储层：以JSON对象记录会话条目，条目内含运行时模型、通道上下文、派生元数据等。
• 缓存层：在内存中缓存对象与序列化字符串，结合文件mtime与size进行一致性校验。
• 维护层：在保存前执行修剪、封顶、轮转与磁盘预算清理，保证空间可控。
• 并发层：通过写锁保障同一会话文件的串行写入，避免竞态与损坏。
• 工具修复层：在读取或修复阶段对转录进行严格校验与修复，确保对外接口兼容性。

sequenceDiagram participant Caller as "调用方" participant Store as "会话存储(store.ts)" participant Cache as "缓存(store-cache.ts)" participant Maint as "维护(store-maintenance.ts)" participant Disk as "磁盘(fs)" participant Lock as "写锁(session-write-lock.ts)" Caller->>Store : 更新/保存会话 Store->>Cache : 读取缓存(TTL/元信息) alt 命中缓存 Cache-->>Store : 返回缓存对象 else 未命中 Store->>Disk : 读取sessions.json Store->>Store : 应用迁移/规范化 Store->>Cache : 写入缓存 end Store->>Maint : 执行修剪/封顶/轮转/磁盘预算 Maint-->>Store : 返回维护报告 Store->>Lock : 获取写锁 Lock-->>Store : 可写入 Store->>Disk : 原子写入sessions.json Store->>Cache : 更新缓存 Store-->>Caller : 完成

详细组件分析

会话存储与缓存

• 加载流程：优先读取缓存（带TTL与mtime/size校验），否则从磁盘读取并应用迁移与规范化，再写入缓存。
• 保存流程：规范化后执行维护策略（修剪、封顶、轮转、磁盘预算），随后原子写入，最后更新缓存。
• 锁队列：内部维护Promise链式队列，确保并发写入串行化，避免竞态。

flowchart TD Start(["开始"]) --> LoadCache["读取缓存(TTL/元信息)"] LoadCache --> Hit{"命中?"} Hit --> |是| ReturnCache["返回缓存对象"] Hit --> |否| ReadDisk["读取磁盘sessions.json"] ReadDisk --> ApplyMig["应用迁移/规范化"] ApplyMig --> WriteCache["写入缓存"] WriteCache --> Maintain["执行维护(修剪/封顶/轮转/磁盘预算)"] Maintain --> AtomicWrite["原子写入sessions.json"] AtomicWrite --> UpdateCache["更新缓存"] UpdateCache --> End(["结束"]) ReturnCache --> End

会话维护策略（修剪/封顶/轮转/磁盘预算）

• 修剪：按updatedAt超过阈值删除条目。
• 封顶：按最近活跃排序，保留最多N条。
• 轮转：当sessions.json超过阈值大小时重命名为.bak.，并清理旧备份。
• 磁盘预算：按高水位清理最老条目，支持警告模式与强制模式。

flowchart TD MStart(["维护入口"]) --> Mode{"模式(enforce/warn)"} Mode --> |warn| WarnCheck["计算警告(活动会话是否会被移除)"] WarnCheck --> ReportWarn["生成维护报告(仅统计)"] Mode --> |enforce| Prune["修剪过期条目"] Prune --> Cap["封顶到最大数量"] Cap --> Archive["归档被删除会话转录"] Archive --> Rotate["检查并轮转sessions.json"] Rotate --> Budget["执行磁盘预算清理"] Budget --> ReportEnforce["生成维护报告(统计+清理结果)"] ReportWarn --> MEnd(["结束"]) ReportEnforce --> MEnd

会话路径与文件命名

• 默认存储路径：agents//sessions/sessions.json
• 转录文件命名：sessionId.jsonl 或 sessionId-topic-.jsonl
• 路径解析：支持相对/绝对路径、跨代理根兼容、安全限制与回退策略

flowchart TD PStart(["解析会话文件路径"]) --> Opt{"传入storePath/agentId/sessionFile?"} Opt --> |有storePath| FromStore["从storePath推导sessionsDir"] Opt --> |无storePath| FromAgent["从agentId推导agents//sessions"] FromStore --> Join["拼接默认sessions.json"] FromAgent --> Join Join --> Validate["路径合法性/安全性校验"] Validate --> NameTranscript["根据sessionId/话题生成转录文件名"] NameTranscript --> PEnd(["输出最终路径"])

会话转录修复与工具结果保护

• 工具调用输入修复：过滤无效/不匹配块，标准化名称，对敏感工具参数进行脱敏。
• 工具结果配对修复：严格要求assistant工具调用后紧随对应toolResult，移动/插入/去重/丢弃孤儿结果。
• 合成缺失结果：为每个工具调用ID生成合成错误结果，避免API拒绝。
• 结果细节剥离：可选剥离toolResult中的details字段，降低冗余。

flowchart TD RStart(["读取转录"]) --> Sanitize["清洗工具调用输入"] Sanitize --> Pair["严格配对工具调用与结果"] Pair --> Move["移动结果到正确位置"] Move --> Insert["为缺失ID插入合成错误结果"] Insert --> Dedup["去重重复结果"] Dedup --> Strip["可选剥离toolResult详情"] Strip --> REnd(["输出修复后的转录"])

并发访问控制与写锁

• 进程级写锁：基于锁文件与PID/starttime检测，支持超时、过期回收、看门狗自动释放。
• 可重入：同进程多次获取计数累加，释放时递减至零才真正释放。
• 清理策略：注册信号处理器与退出钩子，异常终止时清理残留锁。

sequenceDiagram participant W as "写入者" participant L as "写锁(session-write-lock.ts)" participant FS as "文件系统" W->>L : 请求acquire(timeout,stale,maxHold) L->>FS : 创建/读取锁文件(.lock) alt 锁可用 FS-->>L : 成功 L-->>W : 返回release函数 W->>L : 执行写入 W->>L : 调用release() L->>FS : 关闭句柄并删除锁文件 else 锁被占用 L->>L : 检查是否过期/自锁孤儿 alt 可回收 L->>FS : 删除旧锁 L->>FS : 重试获取 else 不可回收 L->>L : 等待/重试 end end

会话工具结果守卫与状态持久化

• 守卫策略：严格配对与合成缺失结果，确保对外接口（如Anthropic）不会因历史错配而拒绝。
• 持久化：原子写入，失败重试，Windows平台增强容错；写后更新缓存与序列化缓存。
• 兼容性：迁移适配旧字段（provider→channel、room→groupChannel），保持向前兼容。

依赖关系分析

• store.ts依赖：
  • 写锁：确保并发安全
  • 维护模块：修剪、封顶、轮转、磁盘预算
  • 缓存模块：对象与序列化缓存
  • 路径模块：解析存储与转录路径
  • 归档工具：删除/重命名转录文件
• 维护模块依赖：
  • 配置解析：从openclaw.json读取维护策略
  • 字节解析：解析大小与持续时间
• 转录修复依赖：
  • 工具调用ID提取与结果ID提取
• 文件系统工具依赖：
  • 路径解析与转录候选集
  • 时间戳格式化/解析

graph LR Store["store.ts"] --> Lock["session-write-lock.ts"] Store --> Maint["store-maintenance.ts"] Store --> Cache["store-cache.ts"] Store --> Paths["paths.ts"] Store --> Utils["session-utils.fs.ts"] Maint --> Types["types.base.ts"] Maint --> Parse["parse-bytes/parse-duration"] Repair["session-transcript-repair.ts"] --> Store Utils --> Paths

性能考量

• 缓存策略：启用对象与序列化缓存，结合TTL与文件元信息校验，显著降低重复解析成本。
• IO优化：Windows平台读写退避与重试，避免短暂空文件导致失败；维护阶段批量处理，减少频繁IO。
• 内存控制：缓存容量上限与LRU淘汰，避免无限增长；序列化缓存减少深拷贝。
• 并发吞吐：Promise链式队列串行化写入，避免锁竞争；看门狗定时释放长时间占用的锁。