2.1.1 从“提示工程”到“系统工程”OpenClaw 将 AI 助手视为一个基础设施问题而不仅仅是提示工程问题。它不会依赖让 LLM“记住上下文”或通过复杂提示词来维持安全与稳定。相反OpenClaw 在模型之外构建了一套结构化的执行环境包括完整的会话管理机制独立的长期与短期记忆系统工具沙箱与权限控制消息路由与多渠道编排LLM 提供智能OpenClaw 提供操作系统。模型负责“思考”OpenClaw 负责“执行”。2.1.2 数据与控制权始终掌握在您手中您可以完全掌控助手运行在什么位置消息如何路由可使用哪些工具会话如何隔离模型 API 请求仍然会发送至AnthropicOpenAI或您自部署的模型服务但以下内容全部保留在您的基础设施中对话历史工具执行记录会话状态编排逻辑与系统控制流智能可以在云端控制权必须在本地。2.2 架构介绍2.2.1 OpenClawAI 代理操作系统OpenClaw 并非对 AI 模型 API 的简单封装。它是一个AI 代理操作系统Agent OS。OpenClaw 将 AI 视为一个系统工程问题而不是提示工程问题。它关注的是会话生命周期管理记忆与上下文持久化工具沙箱与权限控制访问控制与身份隔离任务编排与执行流管理AI 模型提供智能OpenClaw 提供执行环境。模型负责推理与生成OpenClaw 负责状态、控制与执行。2.2.2 中心辐射式架构OpenClaw 采用中心辐射式架构以一个统一网关作为系统核心控制平面。该网关连接WhatsAppiMessageSlackmacOS 本地应用Web UICLI所有用户输入统一进入网关再由网关路由至代理运行时。2.2.3 核心组件说明1️⃣ 网关网关是一个 WebSocket 服务器负责接入各类消息平台与控制接口统一认证与访问控制消息路由与会话隔离将输入分发到对应的代理运行时实例它是整个系统的控制平面。2️⃣ 代理运行时代理运行时负责完整的 AI 执行循环Agent Loop从会话历史与记忆系统中组装上下文调用模型 API解析工具调用指令执行系统能力例如浏览器自动化、文件操作、Canvas、计划任务等持久化更新后的状态模型是推理引擎运行时是执行引擎。关键优势接口层与运行时解耦OpenClaw 的核心设计优势在于将“接口层”消息来源与“助手运行时”智能与执行所在层彻底分离。这意味着您可以通过任何消息应用访问同一个持久助手对话状态集中管理工具权限统一控制多渠道共享记忆与执行能力所有核心状态保留在您的硬件之上AI 不再被困在某个聊天窗口中而是成为一个跨接口、跨场景的长期运行系统。插件化扩展架构OpenClaw 的核心设计原则之一是扩展能力而不侵入核心。系统通过插件机制进行功能扩展无需修改核心代码即可增加新能力。这使 OpenClaw 在保持稳定内核的同时具备高度可演进性。插件主要通过以下四种方式扩展系统1️⃣ 频道插件Channel Extensions用于接入新的消息平台例如Microsoft TeamsMatrixMattermost通过频道插件可以将 OpenClaw 的代理能力无缝扩展至新的通信环境而无需调整运行时逻辑。2️⃣ 内存插件Memory Extensions用于替换或增强默认存储后端。支持向量数据库语义检索知识图谱系统替代默认的 SQLite 存储方案这允许开发者根据场景需求选择不同的持久化与检索策略从轻量本地存储到分布式知识系统。3️⃣ 工具插件Tool Extensions用于扩展代理可调用的系统能力。除内置的Bash 执行浏览器自动化文件系统操作之外可以通过工具插件注入自定义能力例如数据库访问企业内部 APIDevOps 控制业务系统集成代理的能力边界由插件决定。4️⃣ 提供商插件Provider Extensions用于接入新的模型提供方或自托管模型。支持自定义 LLM API 适配层私有模型部署多模型策略切换模型智能可以来自任何地方OpenClaw 只负责统一调度与编排。插件加载机制插件系统位于extensions/目录采用**基于发现discovery-based**的加载模型。核心加载流程插件加载器src/plugins/loader.ts扫描工作区包检查package.json中是否存在openclaw.extensions字段根据声明的 schema 进行配置验证验证通过后执行热加载hot load这种机制带来几个关键优势无需硬编码注册支持模块化分发支持运行时动态扩展插件与核心完全解耦3.核心组件1️⃣ 通道适配器Channel Adapters每个消息平台都由一个专属适配器负责接入。部分适配器为内置模块例如src/telegram/、src/discord/、src/slack/、src/imessage/等其他平台则可通过频道插件扩展接入。所有适配器实现统一接口并对入站与出站消息进行规范化处理。因此OpenClaw 的核心运行时无需关心平台之间的 API 差异。尽管不同平台的协议、数据结构与身份验证方式差异巨大每个适配器都遵循同一个抽象接口并承担四项核心职责一、身份验证Authentication不同平台采用不同的认证机制WhatsApp使用 Baileys 库进行二维码配对凭据存储于~/.openclaw/credentials。Telegram通过TELEGRAM_BOT_TOKEN环境变量提供机器人令牌。Discord通过DISCORD_BOT_TOKEN环境变量完成认证。iMessage依赖 macOS 原生集成并需要正确签名的“信息”应用。适配器封装了各平台的认证流程使运行时无需处理平台差异。二、入站消息解析Inbound Normalization不同平台的消息结构差异显著。入站解析层负责提取纯文本内容处理媒体附件图像、音频、视频、文档解析表情与特殊符号维护回复链与对话上下文解析完成后消息会被转换为统一的内部格式。这意味着 OpenClaw 的核心逻辑无需关心消息来源——它只接收标准化事件。三、访问控制Access Control通道层是安全控制的第一道防线。支持多层访问策略1️⃣ 允许列表Allow List例如{ channels: { whatsapp: { enabled: true, allowFrom: [1234567890], groups: { *: { requireMention: true } } } } }仅允许指定号码或用户名与机器人交互。2️⃣ 私信策略Direct Message Policypaired默认——首次交互需审批open—— 接受所有私信不推荐disabled—— 拒绝所有私信3️⃣ 群组策略Group Policy强制 提及才响应群组级允许列表群组访问隔离通过在通道层实现访问控制可以防止未经授权的输入进入代理运行时。四、出站消息格式化Outbound Formatting每个平台都有自己的限制与规则Markdown 方言差异消息长度限制媒体上传 API 不同输入指示器与在线状态管理适配器负责自动拆分超长消息渲染平台兼容的 Markdown上传媒体文件并生成引用管理“正在输入”状态运行时只输出逻辑响应适配器负责平台兼容性。2️⃣ 控制接口Control InterfacesOpenClaw 提供多种与网关交互的方式覆盖不同的使用场景与操作习惯Web 用户界面命令行界面CLImacOS 桌面应用移动节点iOS / Android这些接口本质上都是网关的客户端只是形态不同。 Web 用户界面Web UI 基于Lit Web Components构建并由网关直接提供服务。默认访问地址http://127.0.0.1:18789/无需额外 Web 服务器网关自身承担全部服务职责。控制面板包含聊天界面配置管理会话检查节点管理健康监控Web UI 本质上是控制平面的可视化界面。 命令行界面CLICLI 基于 Commander.js 构建从openclaw.mjs启动核心逻辑位于src/cli/program.ts。常见命令示例openclaw gateway # 启动网关 openclaw agent # 直接调用代理 openclaw channels login # 登录 WhatsApp 或 Signal openclaw message send # 发送消息 openclaw doctor # 运行健康诊断 openclaw onboard # 引导式初始化CLI 适用于自动化脚本、服务器部署与高级用户操作。 macOS 应用macOS 客户端位于apps/macos/使用 Swift 编写。主要能力菜单栏常驻网关生命周期管理启动 / 停止 / 重启语音唤醒与一键对话覆盖层嵌入 WebChat通过 SSH 控制远程网关它本质上是一个本地控制中枢。 移动节点Mobile NodesiOS 与 Android 客户端通过 WebSocket 连接网关并在握手中声明{ role: node }它们不仅是聊天终端更是可调用的设备能力节点。移动节点可暴露摄像头访问屏幕录制地理位置本地 Canvas 渲染网关可通过node.invoke协议方法调用这些能力使手机成为代理工具链的扩展。3️⃣ 网关系统控制平面Gateway Control Plane网关实现于src/gateway/server.ts运行于 Node.js 22基于wsWebSocket 库构建。默认绑定127.0.0.1:18789仅使用回环地址以保证安全。网关不仅是路由器更是整个系统的唯一真实数据源Single Source of Truth。连接拓扑以下组件全部连接至网关WhatsAppBaileysTelegramgrammYDiscorddiscord.jsCLIWeb UI移动节点所有交互都通过 WebSocket 进行。4.系统提示词架构 工作区配置体系Workspace Configuration SystemOpenClaw 通过文件化配置定义代理行为而非硬编码逻辑。代理的能力、风格与约束均可在工作区内调整。一、静态配置文件Static Layer这些文件构成代理的基础行为框架。1️⃣AGENTS.md核心代理指令必选这是默认捆绑的核心配置文件。定义内容包括代理可执行的操作范围全局约束条件安全边界适用于所有会话的不可协商规则它是系统级行为基线Operational Baseline。2️⃣SOUL.md个性与语气可选定义代理的表达方式而非能力边界。包含语气风格回答结构表达习惯互动节奏⚠️ 不涉及工具行为或安全策略。它只影响“如何说”不影响“能做什么”。3️⃣TOOLS.md工具使用约定可选记录用户在本地环境中的工具使用说明。例如哪些目录可读写运行 bash 时的约定企业 API 使用规范这不是工具注册表。工具定义由 OpenClaw 自动生成并注入。 动态上下文Per-Turn Context Assembly在每一轮对话中运行时都会动态组装上下文而不是静态拼接全部信息。包括会话历史当前会话的最新对话记录从持久化 JSON 文件加载保证连续性与上下文记忆技能文件skills/skill/SKILL.md技能是结构化的操作指南。每个技能包含任务目标操作步骤工具调用规范约束条件可以理解为“标准操作流程SOP”。技能是完成特定任务的能力模块而非提示片段。记忆检索Memory Retrieval运行时通过语义搜索找到与当前问题相似的历史对话提取相关背景避免注入冗余信息只保留高相关度内容以防提示膨胀。 工具定义层Auto-Generated Tool Layer工具定义由系统自动生成并注入模型。分为两类内置工具位于src/agents/pi-tools.tssrc/agents/openclaw-tools.ts包括Bash 执行浏览器自动化文件操作Canvas核心系统能力插件工具通过扩展系统注册api.registerTool(toolName, toolDefinition)允许开发者添加自定义能力例如企业 API数据库访问DevOps 控制外部系统集成基础系统层Runtime Base Layer运行时还会注入Pi Agent Core 指令集来自代理运行时库mariozechner/pi-agent-core提供工具调用协议执行规则响应格式约束最终系统提示的构成最终发送给模型的上下文由以下元素组合而成AGENTS.md行为基线SOUL.md风格控制TOOLS.md使用约定动态技能注入会话历史记忆检索结果自动生成的工具定义Pi Agent Core 指令这种可组合式上下文构建模型意味着您可以通过编辑工作区文件改变代理行为而无需修改源代码。与此同时运行时仍然严格执行权限检查沙箱隔离工具执行控制行为可配置执行不可绕过。互动与协调机制1️⃣ Canvas 与 Agent-to-UIA2UICanvas 是一个由代理驱动的可视化工作空间。它以独立服务器进程运行默认监听端口18793为什么独立运行Canvas 与主网关分离出于两个核心考虑1️⃣故障隔离如果 Canvas 崩溃网关与消息通道仍可继续运行。2️⃣安全边界分离Canvas 是代理“可写”的界面层。将其与控制平面分离可以防止 UI 渲染逻辑影响系统核心状态。换句话说网关 控制平面Canvas 可视化呈现层代理 执行与决策层三者职责明确、相互解耦。工作流程Execution FlowCanvas 与代理之间通过 A2UIAgent-to-UI协议协作。整体流程如下① 代理生成界面内容代理调用 Canvas 更新方法并生成包含 UI 内容的 HTML。HTML 中可以嵌入 A2UI 属性用于声明可交互行为。② Canvas 服务器解析内容Canvas 服务端接收 HTML解析其中嵌入的 A2UI 指令建立交互映射A2UI 本质上是一个桥接层让代理能够声明式地定义 UI 行为而无需直接控制前端逻辑。③ WebSocket 推送更新Canvas 通过 WebSocket将更新后的内容推送至已连接的浏览器客户端实现实时同步系统采用事件驱动模型而非轮询刷新。④ 浏览器渲染交互界面客户端渲染 HTML绑定 A2UI 事件将用户交互事件回传至服务器代理从而可以观察用户操作更新界面执行后续逻辑Canvas A2UI 的设计解决了一个关键问题如何让代理安全地生成可交互界面而不是仅输出文本。优势包括UI 与控制平面隔离可恢复的界面状态实时同步事件驱动交互明确的安全边界代理负责“生成界面逻辑”Canvas 负责“安全渲染与同步”。A2UIAgent-to-UI是一种声明式交互框架使代理能够通过生成带有特定语义属性的 HTML 来构建可交互界面。代理无需编写或控制 JavaScript 代码。它只需输出结构化的 HTML并在元素上标注 A2UI 属性即可声明可点击行为表单提交状态更新事件回传这些特殊属性会被 Canvas 运行时解析并自动绑定对应的前端交互逻辑。换句话说代理负责声明“界面是什么、行为是什么”A2UI 负责实现“交互如何发生”。这使代理能够安全地创建动态 UI而不直接操控客户端脚本环境。div a2ui-componenttask-list button a2ui-actioncomplete a2ui-param-id123 Mark Complete /button /div当用户点击按钮时交互流程如下1️⃣客户端触发事件用户在界面上的点击行为会被客户端捕获并通过 WebSocket 发送一个操作事件到 Canvas 服务器。2️⃣服务器转发为工具调用Canvas 服务器接收到该事件后将其转换为标准化的工具调用并转发给代理运行时。3️⃣代理更新内部状态代理处理该操作。例如它可能在内部状态中将任务123标记为“已完成”更新会话数据或触发后续逻辑。4️⃣代理调用 Canvas 更新状态更新完成后代理调用 Canvas Update 方法生成新的界面内容。5️⃣实时推送与自动刷新Canvas 服务器将更新后的内容通过 WebSocket 推送至客户端客户端自动重新渲染界面无需页面刷新。整个流程是事件驱动且双向流式的用户操作 → 事件上报 → 代理决策 → 状态更新 → UI 重渲染多平台支持Canvas 是跨平台的统一界面层不依赖特定终端。macOS 应用使用原生 WebKit 视图渲染iOS 应用封装在 SwiftUI 组件中Android 应用通过 WebView 显示Web 浏览器可直接在独立标签页中访问所有平台共享同一套 Canvas 协议与更新机制。2️⃣ 语音唤醒与通话模式 语音唤醒Always-On Wake Word语音唤醒功能支持macOSiOSAndroid系统提供始终开启的唤醒词检测。只需说出“嘿 OpenClaw”助手即可被激活并立即进入监听状态。除了唤醒词外您也可以使用键盘快捷键进行“按键通话”Push-to-Talk适用于需要更高隐私或更精确控制的场景。 音频处理流程语音交互采用流式处理模型1️⃣ 本地设备采集音频2️⃣ 音频流发送至 ElevenLabs 进行实时转录3️⃣ 代理运行时处理文本请求4️⃣ 通过 ElevenLabs 的文本转语音TTS生成语音响应5️⃣ 响应实时播放整个过程是双向流式的减少等待时间提升对话自然度。☎️ 通话模式Conversation Mode通话模式在语音唤醒基础上扩展为连续对话体验。特点包括免提对话Hands-Free持续监听上下文中断检测Bar-Interrupt实时语音反馈当助手正在讲话时您可以随时插话系统会检测语音中断并立即停止播放转而处理新的输入。这使交互更接近人与人之间的自然对话。3️⃣ 多代理路由Multi-Agent Routing多代理路由机制允许您将不同的通道、私信或群组定向到彼此完全隔离的代理实例。每个代理实例可以独立拥有专属工作区Workspace独立模型配置不同的行为规则与权限策略独立的记忆与会话历史单独的工具集合与沙箱策略 典型应用场景个人助手与团队助手分离不同群组使用不同语气或能力测试环境与生产环境隔离不同客户或部门独立运行例如私人 WhatsApp 使用轻量模型公司 Slack 群组使用企业策略与更严格权限开发测试群使用实验模型设想这样一个场景你的Discord 服务器机器人需要呈现出类似 Claude Sonnet 那样亲切、乐于助人、偏社区管理员风格的形象在 OpenClaw 中这种差异化需求无需额外开发逻辑只需通过多代理路由与独立工作区配置即可自然实现。你可以为不同渠道绑定不同的代理实例并分别定义使用的模型行为规则AGENTS.md语气风格SOUL.md工具集合与权限策略会话与记忆隔离方式这种方式的核心优势在于不同场景拥有不同智能体而不是让一个智能体扮演所有角色。结果是Discord 保持轻松、社区化风格两者互不干扰配置清晰可控这正是多代理路由的设计初衷在同一基础设施之上实现多角色、多策略、多模型的自然分层。{ agents: { mapping: { group:discord:123456: { workspace: ~/.openclaw/workspaces/discord-bot, model: anthropic/claude-sonnet-4-5, systemPromptOverrides: { SOUL.md: You are a helpful Discord moderator... } }, dm:telegram:*: { workspace: ~/.openclaw/workspaces/support-agent, model: openai/gpt-4o, sandbox: { mode: always } } } } }这种路由机制不仅仅是“多实例部署”而是为复杂场景提供结构化隔离能力。它支持一系列强大的应用模式场景化角色分层您可以为每个社区创建独立的角色实例并针对该社区的文化、语气与使用习惯进行优化。例如技术社区 → 更专业、偏工程表达游戏社区 → 更轻松、互动性更强企业内部 → 更正式、流程导向每个角色拥有自己的行为规则与上下文记忆而不会互相污染。工具与权限分级不同上下文可以配置不同的工具访问权限。例如Discord 社区机器人 → 允许浏览器自动化与公开信息抓取客服私信代理 → 禁止浏览器访问仅允许内部知识库查询内部运维代理 → 允许执行受控的命令行工具工具能力不再是“全局开关”而是上下文级策略。安全隔离与沙箱控制针对不受信任的用户或开放群组可以启用更严格的沙箱策略限制文件系统访问强制 Docker 隔离缩减可调用工具范围即使存在提示注入尝试或恶意输入影响范围也会被限制在当前隔离上下文中不会波及其他代理实例。这是一种结构性风险控制而非单纯依赖提示词防御。行为灰度测试您可以在某个上下文中测试新的客服策略或模型版本而不会影响其他已经稳定运行的代理。例如在测试群验证新的语气策略在单个客户环境中试验新工具链部署实验模型而不干扰生产环境多代理路由天然支持灰度发布与分层迭代。4️⃣ 会话工具Agent-to-Agent Communication会话工具为代理之间提供了一套结构化的通信机制使不同会话中的代理能够相互协调与协作。这意味着代理不再是孤立的聊天实例而是可以互相沟通的智能体网络。当需要多个代理协同处理复杂任务、分工执行步骤或共享上下文信息时会话工具尤其有价值——无需在不同聊天窗口之间手动复制粘贴信息。核心能力1️⃣sessions_list— 发现活跃会话用于查询当前活跃的会话实例。代理可以查看哪些代理在线识别可协作的目标实例判断任务是否应转交给特定上下文这为动态调度与分工奠定基础。2️⃣sessions_send— 跨会话发送消息允许一个代理向另一个会话发送结构化消息。支持“静默委派”模式例如announceStep: ANNOUNCE_SKIP在该模式下任务会被转发原始会话用户不会收到通知协作过程对用户透明适用于后台任务协调或内部代理协商。3️⃣sessions_history— 获取其他会话记录允许代理查询另一个会话的历史交互。典型用途在协作前获取背景信息了解其他代理已完成的步骤基于跨会话上下文做出决策该能力使代理具备“组织级记忆”而非仅限于单会话视角。4️⃣sessions_spawn— 创建新会话以编程方式生成新的会话实例用于任务委派子流程拆分长任务异步执行建立临时工作线程这使代理能够动态扩展其执行结构。5️⃣ 定时操作Cron Jobs与外部触发器WebhooksOpenClaw 支持两种自动化机制⏱ 定时触发Time-Based Automation 事件触发Event-Based Automation它们共同构成代理的“主动执行能力”。定时操作Cron Jobs定时任务允许您在指定时间自动触发代理执行操作。例如每天上午 9 点生成一份工作摘要每周一推送项目进度每晚自动备份与报告分析结果您只需通过配置定义调度规则代理将在指定时间自动运行并将结果发送至目标会话例如主会话或指定频道。示例场景每日 09:00→ 触发代理→ 生成摘要→ 推送至主会话无需保持聊天窗口开启也无需手动触发。外部触发器WebhooksWebhook 提供了一个外部系统触发代理行为的入口。当外部系统向指定端点发送事件时网关会将该事件转换为代理可处理的上下文输入。典型应用包括邮件到达触发自动处理CI/CD 任务完成后生成报告表单提交后创建任务支付成功后执行通知例如邮件系统如 Gmail可以在收到新邮件时向 Webhook 端点发送通知从而触发代理执行分类、摘要或自动回复。自动化模型两种机制分别代表Cron → 时间驱动Webhook → 事件驱动它们都通过配置完成无需编写额外代码。这意味着无需自定义脚本无需修改核心逻辑无需额外服务编排代理可以自动执行重复任务也可以实时响应外部系统事件。