如何构建类似 OpenClaw 的个人 AI 代理

OpenClaw 的实际构成

OpenClaw 是一个自行托管的个人 AI 代理。您可以在自己的服务器上运行它，将其连接到日常使用的聊天应用；它可以执行 shell 命令、控制浏览器、读写文件，并根据您发送的消息执行操作。它采用 MIT 许可证，以本地优先为设计原则。截至 2026 年中，它在 GitHub 上获得了超过 380,000 个 star，是该平台上 star 数量最多的项目之一。抛开各种讨论不谈，它实际上由一组规模不大的组件以合理方式组合而成。本文将逐一介绍这些组件，帮助您了解这类工具的构建方式，以及其中容易出问题的部分。

先说明一个会影响下文所有设计选择的警告。2026 年 3 月，OpenClaw 维护者发布了大量安全公告：仅 3 月 13 日就有 22 个，3 月 16 日又有 5 个；国家漏洞数据库记录了该月发布的 199 个 OpenClaw CVE。3 月 13 日发布的公告中包括 2 个严重级别为 9.9（满分 10 分）的严重漏洞。其中一个是权限提升漏洞（CVE-2026-32922），持有配对权限的设备可以利用它签发完整的管理员令牌。该项目要求由您作为运维人员负责加固。能够执行任意命令的代理，其安全性取决于运行它的主机，以及您为它设置的限制。阅读下文时请牢记这一点。

网关守护进程：保持单进程并设为私有

系统的中心是一个持续运行的进程，通常称为 gateway。它是控制平面，负责接收消息、决定执行的操作、运行工具并返回响应。其他组件都连接到它。

关于 gateway，最重要的是确认它监听的位置。在常规主机安装中，OpenClaw 将其绑定到环回地址 127.0.0.1，因此除非您主动将其暴露出去，否则互联网无法访问它。容器镜像是例外：OpenClaw 自己的安全文档指出，容器镜像默认使用对外暴露的绑定。因此，如果运行容器，请启用身份验证，不要将其端口发布到互联网。无论采用哪种方式，都应将其保持为私有服务。这个进程负责执行命令，因此暴露 gateway 会让任何找到它的人获得进入服务器的远程立足点。需要从笔记本电脑访问时，应通过 VPN 或 SSH 隧道访问，而不是打开端口。无法访问的端口就无法被攻击。

渠道连接器：接收消息并返回回复

只有能通过您已经在使用的应用与个人代理交互时，个人代理才有实际用途。渠道连接器负责实现这一点。每个连接器对应一个平台，例如 Telegram、WhatsApp、Slack 或 Discord，并使用该平台的 bot API 或 Webhook。

所有连接器的工作方式基本相同。连接器先在平台上注册一个 bot，然后接收您发送的消息。它可以轮询平台，也可以接收平台推送的 Webhook。接着，连接器将消息交给网关，并通过同一个 API 将网关的回复发送回去。连接器只是一个薄的转换层。它将“收到一条 Telegram 消息”转换为“这是提供给代理的文本”，再将代理的回复转换回平台消息。自行构建连接器，主要就是阅读某个平台的 bot 文档，并将该平台的消息格式映射到网关的格式。

大脑与工具循环

网关内部包含使其成为智能体而非聊天机器人的部分。这是一个循环。

消息到达后，网关会将消息以及模型可以使用的工具列表发送给语言模型。模型读取消息并作出决定：直接回答，还是调用工具。如果模型调用工具，网关就运行该工具，获取结果，再将结果发送回模型。模型查看结果后再次作出决定。这个过程会一直重复，直到模型没有其他操作需要执行，并生成最终回复。

这个循环就是智能体的核心概念。无论智能体运行在聊天应用中还是终端中，使用的都是同一个循环。若要了解如何以标准方式将工具接入这个循环，请阅读下一篇 通过 Model Context Protocol 连接工具；若要了解模型这一侧，请阅读 在自己的硬件上运行模型本身，其中介绍了另一半内容。

工具集是核心，也是风险所在

工具让 OpenClaw 变得强大。一个工具可以运行 shell 命令，一个工具可以驱动浏览器，另一个工具可以读写文件。让上面的循环访问这些工具后，它几乎可以执行您在键盘上能执行的所有操作。这种能力就是整个产品的核心，也构成了全部风险。

能够执行任意命令、并根据聊天应用中传入的指令操作的代理，具有很大的攻击面。恶意指令、隐藏在浏览器工具访问的网页中的提示注入攻击，或类似 2026 年 3 月漏洞的缺陷，都可能把“读取我的日历”变成“删除我的文件”。因此，这些限制不是可选功能。使用专用的非特权用户运行代理，并禁止使用 sudo，避免遭到入侵后进一步提权。对危险工具设置审批步骤，让代理在执行破坏性操作前先请求批准。对工具执行进行沙箱隔离，限制失控命令的影响范围。隔离模型的 API 密钥，避免密钥泄露后攻击者接管您的账户。还要考虑同一台服务器上的其他机密，因为 Vaultwarden 真正的薄弱点是管理员令牌和备份文件，而不是加密机制；拥有 shell 访问权限的代理可以接触这两者。

在开放任何可以运行 shell 命令的功能之前，应有条理地完成基础检查。先在这里为您的服务器生成一份检查清单，然后从上到下执行：

非特权用户部分将在 以非特权用户运行服务 中详细介绍；真实项目的完整安全配置流程请参阅 在 VPS 上安全运行 OpenClaw。

以普通文件保存记忆

大多数人会认为代理的记忆存储在数据库中。但 OpenClaw 不是这样。它将记忆作为磁盘上的普通 Markdown 文件保存，这种设计值得借鉴。这些文件是真实数据源；默认记忆引擎会在文件旁边维护 SQLite 搜索索引，并且可以根据文件重新构建该索引。

文件很简单。不需要迁移 schema，不需要持续运行额外服务，也不需要学习查询语言。文件内容可以直接检查：您可以打开目录，准确查看代理对您的认知；可以编辑文件更正错误记录，也可以删除某条记忆。文件还便于迁移，因为将代理迁移到新服务器只需复制一个目录。对于单用户个人代理，一个文本文件目录就足够了，也能让整个系统更易于理解和维护。

技能：以可移植方式添加功能

除内置工具外，OpenClaw 还使用可移植的技能格式，让社区无需修改核心代码即可扩展其功能。技能是一个包含指令，有时还包含代码的自包含软件包，用于教会代理执行新任务。任务需要某项技能时，代理会加载该技能。Web 搜索通常是人们首先添加的技能，而将 该技能指向您自己的 SearXNG 实例，既能避免查询经过商业搜索 API，也能清楚展示技能的信任边界，因为它返回的所有内容都是陌生人编写的文本。

这种格式的价值在于，功能可以共享。有人为特定工作编写技能并发布，其他人将其添加即可。这种便利也有风险，因为技能是代理会毫不犹豫地运行的陌生人代码。因此，在加载任何您未编写的技能前，最好先通过 您自行托管的安全扫描器进行检查。如果您要构建自己的代理，尽早定义一种小型且清晰的扩展格式，可以避免日后将每项功能都硬编码到核心中。

自行选择模型

OpenClaw 与模型无关。它不附带自己的语言模型，而是连接到您选择的模型。该模型可以通过托管 API 提供，也可以由您自行运行。

这种分离会影响成本、隐私和控制能力。托管 API 无需管理硬件即可提供能力最强的模型，但需要按 token 付费，并且您的提示词会离开服务器。使用 Ollama 等工具提供服务的自托管模型，可将所有消息保留在您自己的设备上，成本仅包括硬件和电力；代价是只能运行更小或更慢的模型。许多用户会混合使用这两种方式。如果您希望让 agent 完全保持私密，在 VPS 上自托管模型可以弥补最后的隐私缺口，Hermes Agent也是一个值得比较的其他自托管 agent。

构建一个吗？

这些组件都可以自行构建。它们并不复杂：一个守护进程、几个聊天连接器、一个模型与工具循环、一组 Markdown 文件，以及一种插件格式。理解这些内容确实有用，因为这能消除您对所用各种代理的神秘感，并明确风险究竟存在于哪里。

但对大多数人来说，诚实的答案是运行成熟的实现并对其进行加固，而不是重新发明一遍。OpenClaw 已经解决了连接器、循环和技能格式问题，也接受过实际的安全审查。您更应该把精力放在真正需要由您正确完成的部分，也就是在自己的服务器上完成配置和加固。如果您确实想先通过实践学习，那么分阶段逐步学习这些概念比直接阅读代理源代码更有效，因为每个阶段都会让您实际构建出一个成果。构建一个小型代理用于学习。运行并锁定成熟实现用于实际使用。

通用基础内容请参阅在 VPS 上构建自己的 AI 代理；使用 Claude 构建代理则使用特定模型作为核心，展示了相同的思路。

FAQ

构建类似 OpenClaw 的代理难吗？

各个组件本身并不难。gateway 进程、聊天连接器、模型与工具循环，以及文件目录，分别实现都比较直接。真正困难的是确保安全。代理会根据聊天消息执行 shell 命令，这构成了严重的安全风险；正确配置沙箱、权限和非特权用户，比将这些功能连接起来更费工夫。

OpenClaw 为什么使用 Markdown 文件保存记忆，而不是使用数据库？

因为对于单用户个人代理，文件已经足够，而且简单得多。不需要运行数据库服务，记忆内容易于阅读和手动修正，将代理迁移到另一台服务器也只需复制一个目录。数据库适合更大规模的场景，但不适合这里的需求。

个人 AI 代理最危险的部分是什么？

是允许代理执行操作的工具：执行 shell 命令、控制浏览器和写入文件。这些功能既是构建代理的原因，也是代理可能造成损害的原因。OpenClaw 在 2026 年 3 月发布的安全公告浪潮，是谨慎对待工具层的最直接依据：3 月 13 日至 16 日期间共发布了 27 个公告，其中包括 2 个评级为 9.9 的严重漏洞。应使用非特权用户运行，限制破坏性操作，并将执行过程放入沙箱。

构建这类代理需要自己的语言模型吗？

不需要。OpenClaw 这类代理与模型无关，因此您可以连接自行选择的模型。对于能力最强的模型，可以使用托管 API；如果需要完全隐私，也可以运行自己的模型。使用 Ollama 自行托管模型，可以让所有消息都保留在自己的服务器上，但代价是运行规模较小的模型。