Medium:OpenClaw Architecture — Simply Explained
- 原始链接:https://medium.com/@nimritakoul01/openclaw-architecture-simply-explained-fca2e9f15f27
- 来源章节:13. 第三方文章、解读与媒体报道
- 来源小节:无
- 抓取方式:jina:https://r.jina.ai/http://medium.com/@nimritakoul01/openclaw-architecture-simply-explained-fca2e9f15f27
- 抓取时间:2026-04-05 13:47:10
- 状态:ok
中文内容
阅读时间 12 分钟
2026 年 3 月 4 日
按 Enter 或单击以查看全尺寸图像

您的 OpenClaw AI 助手 是一款智能 AI 助手,它通过消息应用程序(WhatsApp、Telegram、Discord、SMS)聆听您的命令,并且可以为您 7*24 小时监控、计划、自动化和执行任务。
OpenClaw(又名 Clawdbot、Moltbot)是一个用 TypeScript 编写的开源框架(中间件进程或网关),可将电源编码代理连接到您的消息传递应用程序。它在您自己的硬件上运行(自托管)并且是开源的(MIT 许可证)。它可以通过专门的技能和插件进行扩展。 OpenClaw 框架可让您构建并运行您的个人 AI 助理/代理,您可以使用任何聊天应用程序与之进行通信。它的工作原理如下:您在 WhatsApp 中向您的 OpenClaw 代理发送一条消息,要求其搜索并预订飞往巴哈马的廉价但舒适的航班。代理首先使用 LLM 来推理和规划执行所请求的任务所需的操作序列。然后,它使用编码代理生成代码来执行所涉及的每个任务(步骤),执行它们,最后在 WhatsApp 上向您发送“任务已完成”消息。
OpenClaw 网关进程是会话、路由和所有消息通道连接的单一事实来源。

您的 OpenClaw AI 助手可以根据您要求的任务学习新技能。它甚至可以在您请求它做某事之前主动采取行动。例如,它可以扫描您的消息并通知您即将举行的会议。当然,您可以决定您的助手所遵循的规则以及它所具有的访问权限。如果您告诉 OpenClaw 助手连接到您的电子邮件,它会自行学习如何连接到您的电子邮件客户端,您无需为其配置任何步骤。
这使得OpenClaw助手功能极其强大。它几乎成为虚拟世界中的数字孪生。它会随着时间的推移不断改进自己,从经验中学习,并且由于其编码技能,它会适应您的需求、偏好和角色。
充分利用OpenClaw AI助手:
- 您的 OpenClaw 助理是学徒、团队成员,而您是经理。当然,您可以向其分配完整的任务、项目,解释您的偏好,设定界限,经常给他们反馈,并作为一个团队来完成任务。期待迭代式的问题解决。
- 用它来自动化重复、无聊的事情。
但是OpenClaw助手仍然容易产生幻觉,并且及时注射,他们会根据你提供的上下文进行引导。当你作为合作者与它交谈时,它们的效果最好。
安全第一
如果您在主工作站上安装 OpenClaw,则您正在运行网络公开的自主代理运行时,可以访问您的本地文件、凭据和 API。它可以为您浏览网页、执行在线和本地操作。这将您的攻击面扩展到多个风险类别。
- 如果 OpenClaw 使用您的用户权限运行,它将继承对您的 SSH 密钥、云凭证、浏览器会话 cookie、本地文件、Git 存储库的访问权限。这会使您的计算机遭受任何提示级危害或插件利用。
您可以通过以低权限操作系统用户(而不是管理员或 root 用户)身份运行 OpenClaw、使用严格的文件系统 ACL、使用虚拟机、docker 容器隔离它或在辅助计算机(主计算机除外)上运行它来缓解这一问题。
- 提示注入和恶意操作执行——攻击者可能会向您的聊天应用程序发送有害消息,代理可能会将其解释为合法指令并执行本地命令或 API 调用,从而造成损失或损害。这是一个跨渠道的提示注入向量。
- 为了缓解这种情况,在所有敏感操作(例如写入文件、shell 执行、API 突变、禁用自动执行模型以及为代理可用的工具添加基于规则的白名单)之前都需要明确的人工批准。
- 您的人工智能助手默认开启配对模式。这意味着,当有人向其发送消息时,发件人会收到一个一次性代码,您可以决定是否让他们进入。这是一个安全的设置。不要将模式更改为“打开”,否则您的人工智能助手将执行消息发送者告诉它的任何操作。
- 仅将受信任的消息传递应用程序 (Telegram) 连接到您的 AI 助手。您可以将 OpenClaw 添加到群聊中,但将其配置为“需要提及”,这样只有当有人直接标记它时它才会响应。否则,它会将群聊中的每条消息视为您的指令。
- 更喜欢能够更好地识别即时注射并阻止它们的人工智能模型。
- 插件供应链风险——通过插件,您的代理可以执行第三方代码、安装未经审查的依赖项并存在远程更新风险。
- 这可以通过仅安装受信任的插件、固定依赖版本、在启用和禁用自动更新之前检查插件源来缓解。
- 为您的人工智能助手提供来自可信技能注册表的有限数量的技能。沙箱你的人工智能助手。从为您的助手提供最少的工具开始,然后根据需要添加更多工具。在具有有限访问权限的 Docker 容器或虚拟机中运行助手。
4.您的 API 和消息传递应用程序、电子邮件的凭据均存储在本地。如果攻击者获得对这些服务的持久访问权限,它们都会受到损害。
- 为了缓解这种情况,请将机密存储在操作系统钥匙串、加密保管库、具有严格权限的 .env 文件中,定期轮换密钥,使用范围内的 API 令牌(最低权限)。
- OpenClaw 公开了您的 Web 仪表板、REST API、Webhoks,并且您绑定到 0.0.0.0,不受防火墙限制。
- 除非外部需要,否则您可以通过绑定到本地主机来缓解这种情况,使用带有 TLS 和身份验证的反向代理,使用防火墙限制入站流量,不要直接暴露到互联网。
- 如果您连接到外部LLM API,您的数据可能会发送到云模型,敏感文件可能会被序列化为提示。
- 您可以通过禁用自动文件读取、审核发送到 LLM 的内容、运行本地 LLM 来缓解此问题。更喜欢能够更好地识别即时注射并阻止它们的人工智能模型。
- 如果攻击者控制了您的 OpenClaw 代理,它就会成为您系统的可编程后门,可以安装软件包、修改文件以及访问内部网络资源。
建议不要在主机上运行OpenClaw,使用单独的笔记本电脑来运行它。如果您在主机上运行它,请在虚拟机环境中使用它。
安装
您需要 Node 22+ 才能安装和运行 OpenClaw。您还需要您的 LLM 模型或 Ollama 本地模型的 API 密钥。
- 安装 OpenClaw 使用 Windows (PowerShell) 使用 npm,需要 Node 22+。
iwr -useb https://openclaw.ai/install.ps1 | iwr -useb埃克斯
上述脚本处理节点检测、安装和加入。
OpenClaw 提供了三个安装程序脚本,由“openclaw.ai”提供。 install.sh 适用于 macOS/Linux/WSL,install-cli.sh 适用于 macOS、Linux、WSL,install.psl 适用于 Windows PowerShell。
您还可以使用 Docker 安装。
- 运行入门向导
openclaw 板载 --install-daemon 该向导配置身份验证、网关设置和可选通道。
- 检查网关
如果您安装了该服务,它应该已经在运行:
开爪网关状态 4. 验证安装
开爪医生
开爪状态
- 打开控制用户界面
开爪仪表板 如果控制 UI 加载,则您的网关即可使用。
基于 GitHub 存储库的 OpenClaw 架构
OpenClaw 存储库 是一个基于 TypeScript 的 monorepo,设计为自托管、多通道 AI 助手。它将各种消息传递平台与中央人工智能代理连接起来,可以通过专业技能和插件进行扩展。 OpenClaw 构建为中心辐射架构,其中网关为中心,消息传递平台、AI 模型和自定义技能为辐射。
高级架构层
按 Enter 或单击以查看全尺寸图像

这是系统的核心,包含助手的主要逻辑。它具有以下组件:
- 网关 (src/gateway/):充当中央“控制平面”。它管理与不同消息通道的连接,处理消息路由,并协调用户和人工智能代理之间的流程。
- Agents (src/agents/):包含AI逻辑和模型集成。这就是助理“思考”的地方,使用 LLM(例如 Anthropic、OpenAI 或 Ollama 的本地模型)来处理查询。
- Channels (src/channels/ & src/[platform]/):核心消息传递平台(如 WhatsApp、Telegram、Slack 和 Discord)的本机实现。
- 插件SDK(src/plugin-sdk/):提供第三方扩展和“技能”的框架,允许在不修改核心的情况下扩展助手的能力。
2.扩展
OpenClaw 使用高度模块化的方法进行集成。这些扩展允许网关与 Matrix、iMessage(通过 BlueBubbles)、Google Chat 和 Microsoft Teams 等其他服务进行通信。它们与核心解耦,以确保稳定性和易于更新。
将 Nimrita Koul 博士的故事放入您的收件箱
免费加入 Medium 以获取作者的最新动态。
记住我以便更快登录
3.原生应用程序
为了提供跨设备的无缝体验,存储库包含特定于平台的代码:
- 移动设备:Android 和 iOS 应用程序。
- 桌面:专用的 macOS 应用程序。
- 共享:共享/目录包含在这些本机包装器中使用的通用逻辑(例如,OpenClawKit)。
4.接口
OpenClaw 提供了多种与助手交互的方式:
- CLI (src/cli/):用于配置、管理(例如板载向导)和基本消息传递。
- TUI (src/tui/):丰富的终端用户界面,提供更具交互性的终端体验。
- Web UI (ui/):一个现代的基于网络的前端。
- Canvas (src/canvas-host/):一项独特的功能,允许助手直接在聊天中渲染交互式实时 UI 组件。
5.基础设施和工具
- Monorepo 管理:使用 pnpm 工作区来管理各个包之间的依赖关系
应用程序。
- Daemon (src/daemon/):将网关作为后台服务运行的逻辑(在 macOS 上启动,systemd
在 Linux 上)。
- 文档 (docs/):综合指南和 API 参考,通常通过 Mintlify 提供。
- 容器化:包括 Dockerfile 和 docker-compose.yml,用于通过 Docker 或 Podman 简化部署。
6。进阶内存系统
OpenClaw 的内存是一个复杂的混合系统,专为长期信息检索而设计:
- 嵌入管理:它支持各种嵌入提供程序(OpenAI、Gemini、Mistral、Voyage)并管理嵌入的批量处理,以有效地处理大量数据。
- RAG(检索增强生成):它使用矢量搜索(由 sqlite-vec 或 LanceDB 提供支持)与基于关键字的搜索(混合搜索)相结合来查找与 AI 最相关的上下文。
- 时间衰减:系统可以使用时间衰减算法将新信息优先于旧数据,确保助手保持最新状态。
- 查询扩展:它包括将用户的简短查询“扩展”为多个相关搜索词的逻辑,显着提高检索记忆的准确性。
代理层是“思考”发生的地方,有几个高级子系统:
- 身份验证配置文件和轮换:OpenClaw 可以在不同的 API 密钥和 OAuth 配置文件(例如 GitHub Copilot、Bedrock)之间轮换。如果一个提供商出现故障或达到速率限制,它可以自动故障转移到另一个提供商。
- 沙箱执行:一项关键的安全功能。启用后,工具(如 bash)在 Docker 容器 (src/agents/sandbox/) 内运行。该系统管理将特定工作区路径安装到容器中,以便 AI 可以在没有完全主机访问权限的情况下处理文件。
- 子代理编排:它可以生成“子代理”来处理复杂的多步骤任务。这些子代理拥有自己的隔离会话,并且可以向主代理报告。
- 工具策略:严格的管道 (tool-policy.ts) 根据安全配置确定给定会话允许使用哪些工具(例如,拒绝群聊中的“危险”工具)。
这使得助手能够超越纯文本回复:
- A2UI 服务器:网关托管 Canvas 的专用服务器。当人工智能使用“画布工具”时,它会向该服务器发送指令。
- 实时更新:可以在 macOS/iOS 应用程序或网络浏览器中查看画布。它提供了一个实时的交互式界面,人工智能可以在工作时更新该界面(例如,显示仪表板、游戏或代码预览)。
9.插件 SDK
SDK 旨在保持核心代码库干净,同时允许大规模可扩展性:
- 标准化助手:它提供内置实用程序,用于处理媒体、管理文件锁、执行 SSRF 安全网络请求以及管理临时文件。
- 跨平台一致性:通过使用 SDK,插件开发人员可以确保他们的工具在所有消息传递渠道(Slack、Discord、WhatsApp 等)上运行,而无需编写特定于渠道的逻辑。
OpenClaw 使用一组基于 Markdown 的“模板”来定义助手的行为:
- AGENTS.md:充当“系统提示符”或“角色”定义。它告诉人工智能它是谁(例如,“Molty,太空龙虾”)以及它的限制是什么。
- SOUL.md:通常用于定义更深层次的人格特质、语气和情绪反应。
- TOOLS.md:自动生成的文档,准确告诉 AI 哪些工具可用以及如何使用它们。
按 Enter 或单击以查看全尺寸图像

https://github.com/openclaw/openclaw/blob/main/AGENTS.md
重要的功能和技术特性:
- 独特的核心功能
- Live Canvas (A2UI):与传统的基于文本的机器人不同,OpenClaw 可以渲染“Live Canvas”,这是一个由 AI 控制的交互式视觉工作区。它使用名为 A2UI 的自定义框架将 UI 更新直接推送到您的聊天或配套应用程序。
- 语音和通话模式:OpenClaw 支持“始终在线”语音。它可以在 macOS、iOS 和 Android 上监听唤醒词并保持连续的语音对话,并与 ElevenLabs 等高质量 TTS 集成。
- **设备节点:**您可以将物理设备(macOS、iOS、Android)配对为“节点”。这允许中央网关触发特定于设备的操作,例如拍摄相机快照、记录屏幕或检索您的 GPS 位置。
2.安全与信任模型
- **“个人助理”**模型:OpenClaw 被设计为单用户系统。它假设任何有权访问网关的人都是值得信赖的操作员。它不是为用户敌对的多租户环境而设计的。
- 不可信输入处理:默认情况下,OpenClaw 将来自未知发件人的入站消息视为不可信。它使用 DM 配对策略,新用户必须通过配对代码手动批准,然后助理才会做出响应。
- 沙箱:为了安全起见,您可以为非主要会话(如群聊)启用 Docker 沙箱。这确保了 AI 执行(通过 bash)的任何代码都在隔离的容器中运行,而不是在主机上运行。
3.可扩展性和集成
- 技能平台:通过“技能”扩展能力。这些可以捆绑(内置)、管理(特定于工作空间)或通过社区技能注册表 ClawHub 发现。
- MCP 支持:OpenClaw 通过名为 mcporter 的桥接器支持模型上下文协议 (MCP),而不是复杂的内部实现。这可以保持核心精简,同时允许您使用任何 MCP 兼容工具。
- 多代理协调:sessions_* 工具允许不同的 AI 会话(代理)协调工作、获取彼此的历史记录以及在会话之间发送消息。
4.技术堆栈亮点
- 语言:完全用 TypeScript (ESM) 编写,具有较高的可破解性。
- 运行时:需要 Node.js 22+。虽然它在 Node 上运行,但它大量利用 Bun 来快速执行 TypeScript 和任务运行。
- 浏览器控制:包括用于网络抓取、拍摄快照和自动化浏览器任务的托管 Chromium 实例。
- Tailscale 集成:可以自动设置 Tailscale Serve 或 Funnel,以便通过您的私有 tailnet 安全地公开您的网关仪表板,而无需打开公共端口。
5.部署和运营
- CLI 向导:推荐的安装路径是 openclaw onboard 命令,它会指导您完成型号选择、通道配对和守护程序安装。
- Doctor Tool:内置的 openclaw doctor 命令有助于诊断配置问题、权限差距和迁移需求。
- Nix 支持:包括用于声明性环境管理和可重复安装的 Nix flake。
OpenClaw 优先考虑本地控制和跨平台功能,而不是云托管的多租户方法。
6。强大的开发工具
- Doctor Command:扫描您的安装是否存在常见问题,例如不正确的 Node.js 版本、缺少环境变量或不安全的配置。
- Vitest Suite:该项目拥有广泛的测试套件(单元、集成和E2E),覆盖率要求高(70%以上),确保即使是复杂的更改也能在所有平台上得到验证。
OpenClaw 不仅仅是法学硕士的包装;它也是法学硕士的包装。它是一个功能齐全的人工智能操作系统,以统一、高度可扩展的方式管理身份、内存、安全和多平台通信。 使用它但要安全。
## 参考:
