OpenClaw 自托管 Agent 网关

导语

你是否想过，把飞书、钉钉、微信这些日常聊天软件，变成一个能帮你处理任务、管理日程、执行自动化操作的AI助手入口？OpenClaw 正是为此而生的自托管开源网关。这篇教程将带你深入理解 OpenClaw 的核心架构、工作机制、记忆设计和安全策略，帮你快速上手搭建属于自己的「个人AI助手集群」——让聊天软件成为你与LLM Agent交互的桥梁，所有逻辑和数据都运行在你自己的机器上。

1. OpenClaw 是什么：从「聊天软件」到「AI Agent 入口」

OpenClaw 是一个自托管、开源的个人 AI 助手网关，核心目标是将各种聊天软件（飞书/钉钉/企微/Discord/Slack/Telegram/WhatsApp 等）统一接入到一个本地运行的 LLM Agent 中。你只需在自己的机器或服务器上启动一个「Gateway 进程」，就能实现以下功能：

• 多渠道统一接入：所有聊天软件的消息都会通过 Gateway 转发到 LLM Agent 处理
• 统一管理中心：通过 Web 控制台集中管理会话、路由规则、技能配置、定时任务和权限
• 自托管安全可控：所有逻辑和数据都在本地运行，无需依赖第三方服务器

简单说，OpenClaw 让你把日常聊天软件变成了「AI 助手的入口」，而 LLM Agent 则是「能执行任务的大脑」，Gateway 作为「桥梁」负责消息的路由和转发。

深入理解：与 Claude Code 的定位差异

你可能会问：「Claude Code 不就是终端里的编程 Agent 吗？OpenClaw 和它有什么区别？」

• Claude Code：定位是「开发者的终端编程助手」，专注于在命令行中与 LLM 交互，处理代码生成、调试等开发任务。
• OpenClaw：定位是「个人助手网关」，核心是将聊天软件作为「交互入口」，让非技术用户也能通过日常沟通工具（如微信、Discord）触发 LLM 执行任务，比如自动发消息、查天气、管理日程等。

但两者底层设计高度相似：都收敛到「13-Harness 六层架构」（包括循环、工具调用、记忆管理、权限控制等核心组件），本质上都是为了实现「通用智能体」的标准化框架。

2. 三层架构：Channel / Brain / Body 的「关注点分离」设计

OpenClaw 采用「关注点分离」原则，将系统拆分为三个核心层次，每个层次负责独立职责，避免相互干扰：

整体架构概览

各层详细解析

2.1 Gateway 层（Channel 层）：只做「消息桥梁」

• 职责：负责不同渠道（如微信、Discord）的协议归一化，路由消息到正确的 Agent，管理会话和权限。
• 关键特性：从不直接调用 LLM 模型，只做「协议转换」和「消息转发」。例如：Telegram 消息通过 grammY 库接收，Discord 消息通过 discord.js 处理，最终统一转发给 Brain 层。
• 设计优势：渠道接入与模型解耦——新增一个聊天软件（如 iMessage）时，只需开发对应的适配器，无需修改 Brain 层代码；更换 LLM 模型（如从 GPT-4 换 Claude）时，也只需调整 Brain 层配置。

2.2 Agent Runtime 层（Brain 层）：LLM 推理的「指挥官」

• 职责：接收 Gateway 转发的消息，解析指令、定义人格（如「严谨型」「幽默型」）、调用 LLM 生成回答，并协调工具调用。
• 关键特性：模型无关性——无论你用 Claude、GPT 还是本地 Ollama，都能通过配置无缝切换；支持「人格定制」（通过 prompt 模板定义语气和角色）。
• 设计优势：将「推理逻辑」与「模型选择」分离，让系统更灵活。例如，你可以同时运行「GPT 处理日常对话」和「Claude 处理代码任务」，通过路由规则分配不同会话到不同模型。

2.3 Tools 层（Body 层）：「动手能力」的执行者

• 职责：提供工具调用接口，如浏览器操作（查天气）、文件读写（处理文档）、消息发送（自动回复）等，将「对话」转化为「实际动作」。
• 关键特性：支持「技能扩展」——你可以自定义 Python 脚本作为工具（如调用天气 API、爬取网页），让 Agent 具备「做实事」的能力。
• 设计优势：让 LLM 不仅能「思考」，还能「动手」。例如，当你问「帮我订明天 9 点的咖啡」，Agent 会调用「日历工具」检查日程，再调用「外卖 API」下单，并将结果反馈给你。

为什么「三层架构」重要？

通过「关注点分离」，系统变得更模块化、可维护。例如：
- 新增一个聊天渠道（如 iMessage）→ 只需开发 Gateway 层的适配器，无需修改 Brain/Body 层；
- 更换 LLM 模型 → 只需调整 Brain 层的模型配置，不影响 Gateway 和 Tools；
- 升级工具（如新增「邮件发送」工具）→ 只需在 Body 层注册新工具，无需改动其他部分。

3. 七阶段 Agentic 循环：消息从「进来」到「出去」的完整流程

当你在聊天软件中发送一条消息（如「明天天气如何」），OpenClaw 会按以下「七阶段循环」处理：

阶段 1：Normalize（归一化）

• 操作：将不同渠道的消息统一转换为标准化格式（如 {sender: "你", content: "明天天气如何", channel: "Telegram", timestamp: "2024-05-01 10:00"}）。
• 特殊处理：语音消息先通过「语音转文字」工具转为文本，再进入后续流程。

阶段 2：Route（路由）

• 操作：Gateway 将消息路由到「正确的 Agent 和会话」。例如：
• 确定性路由：消息来自「工作群」→ 路由到「工作助手 Agent」；来自「个人聊天」→ 路由到「个人助手 Agent」。
• 多智能体路由：根据消息内容（如「代码问题」），路由到「代码处理子 Agent」。
• 关键设计：会话按「Command Queue 串行处理」——同一会话的消息按顺序执行，避免并发导致的记忆状态错乱（如「先问天气，再查日程」不会因并发而冲突）。

阶段 3~4：组装上下文 + LLM 推理

• 组装上下文：Brain 层收集「当前会话历史」「记忆文件」「工具信息」，拼接成 LLM 的输入 prompt。
• LLM 推理：调用 LLM 生成回答，过程中会判断是否需要调用工具（如「需要查天气」→ 触发 ReAct 循环）。

阶段 5：ReAct 循环（工具调用）

• 操作：LLM 根据推理结果，决定是否调用工具。例如：
• 若需要查天气 → 调用「天气工具」，传入地点参数；
• 若需要发消息 → 调用「消息工具」，传入接收人、内容。
• 关键特性：ReAct 模式——Agent 会先「思考是否需要工具」，再「执行工具」，最后「判断是否继续」，形成闭环。

阶段 6：加载技能（Skills）

• 操作：根据工具调用结果，加载对应的「技能」（如「查天气」「发邮件」），执行具体动作。
• 示例：调用「天气工具」时，触发 weather.py 脚本，获取天气数据并返回给 LLM。

阶段 7：持久化记忆

• 操作：将本次对话的关键信息（如「明天天气：晴，25℃」）写入「记忆文件」（默认 MEMORY.md），供后续会话复用。
• 设计优势：记忆以「纯文本文件」形式存储，支持直接用文本编辑器查看、Git 备份、手动修改，避免「向量库黑盒」导致的记忆不可控问题。

4. 记忆设计：「文件优先」的透明化存储策略

OpenClaw 的记忆系统采用「文件优先，检索其次」的设计哲学，核心是让记忆可观测、可审计、可人工干预：

记忆存储方式

• 存储形式：所有记忆（对话历史、长期知识、技能配置）以 Markdown + YAML 文件 形式存储在 ~/.openclaw/workspace 目录下，典型文件包括：
• MEMORY.md：长期精选记忆（如「用户偏好：喜欢简洁回答」）；
• SESSION_xxxx.md：每个会话的对话历史；
• SKILLS.yaml：技能配置（如「天气工具」的 API 地址）。
• 优势：纯文本格式支持「直接编辑」「Git 版本控制」「grep 搜索」，避免向量数据库的「黑盒问题」（如无法查看 Agent 具体记住了什么）。

记忆访问策略

• 分层控制：不是将所有记忆文件一次性塞进 LLM prompt（避免上下文窗口爆炸），而是通过 「检索式访问」 按需加载：
• memory_search("天气")：根据关键词搜索相关记忆片段；
• memory_get("用户偏好")：直接读取固定段落（如「用户喜欢简洁回答」）。
• 关键设计：通过「显式指定记忆范围」，让 LLM 只关注「当前任务需要的信息」，避免冗余内容干扰推理。

常见问题：记忆「选择性遗忘」怎么办？

现象：用户问「昨天天气如何」，Agent 回答「不记得了」——但实际天气数据已被记录。
原因：记忆写入决策不稳定（LLM 可能误判「是否值得写入」），或关键信息未显式写入 MEMORY.md。
解决方法：
1. 关键规则硬编码：将「用户历史偏好」「系统规则」等固定内容直接写进 MEMORY.md（如「用户偏好：只回复中文，不超过 20 字」）；
2. 复述校验：要求 LLM 在生成回答前，显式引用关键记忆内容（如「根据记忆，你喜欢简洁回答」），通过输出可观测性反向确认记忆是否被正确加载。

5. 自动化任务：Cron / Heartbeat / Webhook 三种触发方式

OpenClaw 支持三种自动化任务调度，满足「定时」「事件驱动」「外部触发」等场景：

5.1 Heartbeat 心跳（定期任务）

• 触发条件：默认每 30 分钟（Anthropic OAuth 下为 1 小时）检查 HEARTBEAT.md 文件。
• 作用：Agent 主动检查「待办任务清单」（如「每天 8 点提醒喝水」），有任务时触发消息到聊天渠道，无任务时回复「HEARTBEAT_OK」。
• 适用场景：周期性提醒（如日程、健康打卡）。

5.2 Cron 定时（计划任务）

• 触发条件：通过 Cron 表达式（如 0 9 * * * 表示每天 9 点）触发。
• 核心特性：
• 持久化：任务配置写入 CRON_JOBS.yaml，重启后仍生效；
• 隔离执行：支持「主会话任务」（直接在主对话中回复）和「独立会话任务」（开新会话执行，不污染主上下文）；
• 并发控制：通过 maxConcurrentRuns 限制同时运行的任务数，避免资源占用过高。
• 示例：每天 18:00 自动发送「今日总结」到微信工作群。

5.3 Webhook 事件（外部触发）

• 触发条件：接收外部系统的 HTTP 请求（如 Gmail 邮件、GitHub 事件）。
• 适用场景：外部事件驱动的自动化（如「收到新邮件」→ 触发「邮件处理」技能，自动回复或生成摘要）。
• 实现方式：在 Gateway 层暴露 Webhook 端点（如 http://localhost:18789/webhook），外部系统通过 POST 请求触发任务。

6. 安全设计：三道「权限闸」的纵深防御

OpenClaw 采用「入口闸 → 工具闸 → 执行闸」的三层权限控制，确保系统安全可控：

6.1 入口闸（鉴权与隔离）

• 默认策略：仅允许「本地连接」（ws://127.0.0.1:18789），防止外部直接访问；
• 非本地连接：需通过「配对码」（Pairing）授权——新设备接入时，Gateway 生成唯一 token，用户需在聊天软件中确认配对；
• 多用户隔离：每个用户/会话独立存储，避免数据交叉（如「工作 Agent」与「个人 Agent」的会话、记忆完全隔离）。

6.2 工具闸（白名单控制）

• 默认拒绝：所有工具默认不允许调用，仅通过「白名单」显式授权；
• 典型白名单：允许 bash/read/write（基础文件操作）、browser（安全网页访问）、sessions_*（会话管理）；
• 风险隔离：禁止 docker（宿主机操作）、canvas（前端注入）等高风险工具，防止恶意调用。

6.3 执行闸（Docker 沙箱隔离）

• 高风险操作（如调用本地脚本、执行外部程序）默认在 Docker 沙箱 中运行；
• 资源限制：沙箱内仅分配最小权限，禁止挂载宿主机根目录，防止容器逃逸；
• 安全原则：坚持「最小权限 + 显式允许」——任何工具调用必须在 Dockerfile 中预配置，否则无法执行。

安全注意事项

• 避免「默认允许」：若将工具闸改为「默认允许 + 黑名单」，一旦某个工具被误放，可能导致高危操作（如删除文件），因此必须坚持「默认拒绝」；
• 多 Agent 隔离：不同 Agent 的会话、记忆、权限物理隔离，但 OpenClaw 定位是「个人助手」，不支持多租户强隔离（多人共用需谨慎）。

7. 真实踩坑与解决方案：从实践中总结的经验

坑 1：记忆「选择性遗忘」

• 现象：用户问「上周三的会议内容」，Agent 回答「记不清了」。
• 原因：LLM 推理时「判断是否写入记忆」的逻辑不稳定（模型可能认为「不重要」而不写）。
• 解决：将「关键规则」（如「会议记录需写入 MEMORY.md」）直接硬编码到 MEMORY.md，要求 LLM 生成时「引用该规则」，通过「显式写入」避免遗忘。

坑 2：技能与运行环境强耦合

• 现象：Cron 定时任务触发时，报错「命令不存在」。
• 原因：Gateway 运行在 Docker 容器中，手动安装的技能依赖（如 python-weather-api）未写入 Dockerfile，容器重建后依赖丢失。
• 解决：所有技能依赖必须通过 Dockerfile 预安装，确保容器内环境一致。

坑 3：Cron 任务「不执行」

• 现象：配置了「每天 9 点发消息」，但未收到提醒。
• 原因：时区未设置为本地时区（如容器内默认 UTC 时区），或 Cron 表达式格式错误（如 0 9 * * * 应为「分钟 时 日 月 周」）。
• 解决：
• 在 Docker 启动时挂载本地时区：-v /etc/timezone:/etc/timezone:ro；
• 用 crontab -e 检查 Cron 配置是否正确。

坑 4：Docker 权限边界失控

• 现象：工具调用时，Agent 意外删除了宿主机文件。
• 原因：沙箱未正确限制权限，工具脚本被赋予「读写宿主机根目录」的权限。
• 解决：严格限制 Docker 沙箱挂载目录（仅挂载 workspace 目录），禁止 --privileged 模式。

8. 高频问题速答（FAQ）

Q：如何设计自己的「Agent 系统」？

A：参考 OpenClaw 三层架构：
- Channel 层：开发聊天渠道适配器（如微信接入）；
- Brain 层：定义 LLM 调用逻辑（支持 Claude/GPT）；
- Body 层：实现工具链（如邮件、天气工具）。
核心原则：状态外化到文件 + 权限分层 + 路由确定性。

Q：为什么不用向量库做记忆？

A：向量库是「黑盒」，无法直接查看记忆内容；文件记忆支持「人工编辑」「Git 备份」，且通过「检索式访问」避免上下文爆炸，更符合「个人助手」的透明化需求。

Q：与 Claude Code 的关系？

A：Claude Code 是「终端编程助手」，OpenClaw 是「聊天入口网关」，但两者底层都基于「13-Harness 六层架构」（循环、工具、记忆、权限等），核心设计思想一致。

Q：如何防止 Docker 沙箱逃逸？

A：坚持「最小权限」原则：
- 禁止挂载宿主机根目录（仅挂 workspace）；
- 不使用 --privileged 模式；
- 限制容器资源（CPU/内存），防止恶意占用；
- 网络白名单：仅允许访问必要 API（如天气工具的公开接口）。

小结

OpenClaw 自托管 Agent 网关通过「三层架构」「文件记忆」「权限隔离」和「自动化调度」，将日常聊天软件转化为「个人 AI 助手入口」。核心优势在于：
- 透明可控：记忆以文本文件存储，支持人工干预；
- 安全隔离：通过 Docker 沙箱和权限白名单，降低高危操作风险；
- 灵活扩展：渠道、模型、技能可独立升级，无需大规模重构。

无论是作为「个人生活助手」（查天气、管日程）还是「开发者工具」（代码生成、文档处理），OpenClaw 都能通过聊天软件入口，实现「即问即答」的智能交互。

核心要点：
1. 三层架构（Channel→Brain→Body）分离职责；
2. 文件记忆 + 检索式访问确保透明与可控；
3. 三道权限闸（入口/工具/执行）保障安全；
4. Cron/Heartbeat/Webhook 支持多场景自动化。

通过本文，你已掌握 OpenClaw 的核心设计与实践要点，可着手搭建自己的「个人 AI 助手网关」，将聊天软件变为高效的任务入口。