场景AI 助手的边界问题把 OpenClaw 当作个人 AI 助手使用一段时间后会遇到几个让单进程模型力不从心的场景远程执行你想让 AI 帮你在家里的 Linux 服务器上跑一段脚本但 OpenClaw Gateway 运行在 Mac 上——AI 怎么触达那台服务器的 Shell手机上的交互 UI你想在手机上看到 AI 生成的实时仪表盘并且能点击按钮触发下一步操作——AI 怎么向移动端 WebView 推送 UIWebView 里的点击又怎么反馈给 AI并行任务你让 AI 帮你整理 1000 封邮件——用一个 Agent 串行处理太慢了能不能派出多个 AI 同时干这三个场景分别对应 OpenClaw 的三个核心扩展机制Node Host节点主机、Canvas A2UI、子 AgentSub-agent。一、Node Host让 AI 触达远程机器问题Gateway 和执行目标不在同一台机器Gateway 负责对话管理和 Agent 执行但system.run执行 Shell 命令这类工具需要在目标机器上运行——可能是远程服务器、NAS、Raspberry Pi或者同一台 Mac 上受限环境的另一个进程。Node是解决这个问题的抽象一个独立进程连接到 Gateway响应执行请求。Node 通过标准的GatewayClientWebSocket注册自己// src/node-host/runner.tsconstclientnewGatewayClient({url:wss://${gatewayHost}:${gatewayPort},instanceId:nodeId,// 节点唯一标识如机器 hostnameclientName:node-host,role:node,// 区别于 agent、cli 角色caps:[system,browser],// 声明此节点支持的能力commands:NODE_SYSTEM_RUN_COMMANDS,// 支持的命令列表onEvent:(evt){if(evt.event!node.invoke.request)return;constpayloadcoerceNodeInvokePayload(evt.payload);voidhandleInvoke(payload,client,skillBins);// 处理执行请求},});client.start();数据流Agent 调用 system.run 工具 → Gateway 路由到目标 nodeId 的 WebSocket 连接 → 发送 node.invoke.request 事件 → Node 执行命令 (spawn子进程) → node.invoke.result 返回结果 → Gateway 把结果交给 Agent执行安全三级权限模型Node 不是无限制的 Shell 执行器。exec-approvals.ts实现了一个三级安全模型typeExecSecuritydeny|allowlist|full;deny拒绝所有命令执行allowlist默认只允许exec-approvals.json白名单中的命令full允许所有命令高信任环境下使用白名单文件用哈希防止竞态修改——读取和更新都需要传入baseHash若文件已被其他进程改动返回INVALID_REQUEST: exec approvals changed; reload and retry。这防止了 TOCTOU 攻击。还有一个特殊路径在 macOS 上preferMacAppExecHost为 true 时执行请求会优先通过 macOS 应用的 Exec HostUnix socket而不是直接spawn。这是因为 macOS 沙盒限制了某些路径的访问权限通过应用层代理绕过这个限制。Node 的输出上限命令的输出被硬性截断constOUTPUT_CAP200_000;// 累计输出上限字节constOUTPUT_EVENT_TAIL20_000;// 单次事件的输出尾部字节超出上限的内容被丢弃结果中truncated: true。这保证了大量输出如日志文件不会撑爆 Agent 的上下文窗口。二、Canvas在手机上渲染 AI 生成的 UI问题AI 的回复只能是文字吗AI 擅长生成代码能不能生成 HTML 仪表盘、然后在用户手机上直接显示并支持交互Canvas是 Gateway 内置的一个轻量 HTTP 服务器挂载在/__openclaw__/canvas专门伺服 AI 生成的 HTML/JS/CSS 文件// 目录结构~/.openclaw/canvas/index.html ←AI生成后写到这里 app.js style.cssGateway 启动时createCanvasHostHandler会在~/.openclaw/canvas/创建默认的index.html如果不存在用chokidar监听目录变化文件变化时通过 WebSocket/__openclaw__/ws推送reload给所有已连接的客户端被注入的实时重载脚本// 每个 HTML 页面末尾都会自动注入constwsnewWebSocket(wss://host/__openclaw__/ws);ws.onmessage(ev){if(String(ev.data||)reload)location.reload();};这意味着AI 重写index.html→ chokidar 检测到文件变化 → WebSocket 广播reload→ 用户手机上的 WebView 自动刷新。文件系统边界文件服务有安全约束。resolveFileWithinRoot用open(fd)realpath验证每个请求的文件路径都在 Canvas 根目录内——这与上一篇 Plugin SDK 里的openBoundaryFileSync是同一类防护都是防止路径遍历攻击。三、A2UIWebView 与 Agent 的双向通信问题Canvas 页面里的按钮点击怎么回传给 AgentCanvas 里的 HTML 页面可以显示数据但它本身没有办法与 OpenClaw 通信——它是运行在 iOS/Android WebView 里的孤立页面。A2UIAgent-to-UI解决了这个方向问题提供一套跨平台的 JavaScript 桥接 API让 WebView 里的代码可以触发 OpenClaw Agent 的动作。A2UI 包src/canvas-host/a2ui/通过/__openclaw__/a2ui/伺服并在每个 Canvas 页面的 HTML 里自动注入一段引导脚本// 被注入到每个 Canvas HTML 页面的桥接脚本简化functionpostToNode(payload){constrawtypeofpayloadstring?payload:JSON.stringify(payload);// iOS 桥接constiosHandlerglobalThis.webkit?.messageHandlers?.openclawCanvasA2UIAction;if(iosHandler?.postMessage){iosHandler.postMessage(raw);returntrue;}// Android 桥接constandroidHandlerglobalThis.openclawCanvasA2UIAction;if(androidHandler?.postMessage){androidHandler.postMessage(raw);returntrue;}returnfalse;}// 给 Canvas 页面的公开 APIglobalThis.openclawSendUserAction(userAction){constiduserAction.id||crypto.randomUUID();returnpostToNode({userAction:{...userAction,id}});};Canvas 页面里的代码可以这样触发动作// 用户点击了执行备份按钮window.openclawSendUserAction({name:run_backup,surfaceId:main,sourceComponentId:backup.button,context:{target:nas-01,compress:true}});这条消息经由Canvas JS → native MessageHandleriOS/Android → OpenClaw Node Host 的 node.event → Gateway → 对应的 Agent 会话作为用户输入 → Agent 决定下一步行动动作结果回传Agent 处理完动作后可以通过window.dispatchEvent(new CustomEvent(openclaw:a2ui-action-status, { detail: { id, ok, error } }))通知 Canvas 页面操作已完成。这构成了一个完整的请求-响应循环。四、ACP标准化的 Agent 互操作协议问题外部工具如何调用 OpenClawagentclientprotocol/sdk是 Agent Client Protocol 的实现OpenClaw 通过它暴露一个标准接口让任何兼容 ACP 的工具都能与 OpenClaw 的 Agent 会话交互。// src/acp/server.tsexportasyncfunctionserveAcpGateway(opts:AcpServerOptions):Promisevoid{// 监听本地端口将 ACP 请求翻译成 Gateway 操作constagentnewAcpGatewayAgent(gateway);// 每个 ACP 会话映射到一个 OpenClaw 会话sessionKey}ACP 会话有两种模式exportconstACP_SPAWN_MODES[run,session]asconst;// run → 一次性任务完成后关闭会话// session → 持久会话完成后保留后续请求继续使用同一上下文这让 CI/CD 系统、IDE 插件、或其他 AI 工具可以把 OpenClaw 当作一个可编程的 AI 后端调用而不需要理解 OpenClaw 内部的协议细节。五、子 Agent并行任务分解问题串行处理大任务太慢一个复杂任务整理 1000 封邮件分析 50 个代码文件用单个 Agent 串行处理太慢。子 Agent 机制让 Agent 可以派生spawn独立的子 Agent 并行执行子任务。// Agent 使用 sessions.spawn 工具派生子 AgentexportasyncfunctionspawnSubagentDirect(params:SpawnSubagentParams,ctx:SpawnSubagentContext,):PromiseSpawnSubagentResultSpawnSubagentParams的核心字段typeSpawnSubagentParams{task:string;// 子任务描述注入为子 Agent 的第一条消息label?:string;// 可读标签用于状态显示agentId?:string;// 指定使用哪个 agent 配置model?:string;// 子 Agent 的模型可以与父 Agent 不同thinking?:string;// 子 Agent 的思考等级runTimeoutSeconds?:number;// 超时控制thread?:boolean;// 是否绑定到聊天线程结果直接发到聊天mode?:run|session;// 一次性 vs 持久会话cleanup?:delete|keep;// 完成后是否清理会话};子 Agent 的生命周期父 Agent 调用 sessions.spawn ↓ spawnSubagentDirect() → 创建新 SessionKey格式agentId:session-xxxxxxxx → 在 AGENT_LANE_SUBAGENT 通道里排队 → 注册到 SubagentRegistry追踪运行状态 ↓ 子 Agent 在独立 Lane 里执行与父 Agent 并行 ↓ 完成后subagent-announce 把结果发回给父 Agent → 作为父 Agent 会话里的一条用户消息 → 父 Agent 继续处理不要轮询注意事项子 Agent 完成后会主动宣告announce结果而不是等父 Agent 来查询。父 Agent 在派生子任务后应该继续其他工作而不是在循环里等待子任务完成。子任务的结果会自动以用户消息的形式重新注入父 Agent 的上下文。// 子 Agent 结果宣告文案src/agents/subagent-spawn.ts export const SUBAGENT_SPAWN_ACCEPTED_NOTE auto-announces on completion, do not poll/sleep. The response will be sent back as an user message.;深度限制为了防止无限递归子 Agent 再派生子 Agent 再派生……系统维护一个深度计数器subagent-depth.ts并且有默认上限// src/config/agent-limits.tsexportconstDEFAULT_SUBAGENT_MAX_SPAWN_DEPTH3;超过这个深度的派生请求会被拒绝返回forbidden状态。子 Agent 绑定线程thread: true参数让子 Agent 的结果直接投递到当前聊天线程而不是等父 Agent 转发父 Agent在 Telegram 对话里 → 派生子 Agentthread: true → 子 Agent 完成后结果直接发送到 Telegram 对话 → 用户在 Telegram 里直接看到子任务的输出这个功能依赖subagent_spawning生命周期钩子——只有实现了该钩子的通道插件能绑定线程的聊天平台才能使用。小结三个边界突破机制机制突破的边界核心数据流Node Host执行边界——让 AI 触达远程机器Gateway → WebSocket → Node →spawn→ 结果返回Canvas A2UIUI 边界——让 AI 的输出变成交互式 UIAI 写文件 → chokidar → WebSocket → WebView 重载用户点击 → native bridge → node.event → Agent子 Agent并发边界——让 AI 并行分解任务父 Agent spawn → 子 Agent 独立执行 → 完成后 announce 回注入父会话三者共同扩展了个人 AI 助手的能力边界不只是对话而是可编程的执行引擎 交互式 UI 宿主 多 Agent 协作系统。下一篇也是系列的最后一篇我们将进入 OpenClaw 的安全模型与沙盒——系统性梳理 Gateway 认证、工具策略、沙盒隔离、API Key 保护、以及整个系统的信任边界设计。