OpenClaw 是一款专为 AI 代理打造的自托管网关，旨在打破聊天应用与智能助手之间的隔阂。它不仅仅是一个连接器，更是一个强大的中枢，能将 WhatsApp 、Telegram 、Discord 、iMessage 等主流通讯平台无缝接入像 Pi 这样具备编码能力的 AI 代理。 通过在自己的设备或服务器上运行 OpenClaw ，我们获得了一个完全属于自己的“AI 大脑中枢”。它不仅是一个多渠道的聚合器，更是一个代理原生的操作系统——专为处理复杂的工具调用、会话记忆管理和多代理路由而设计。这意味着，无论我们身在何处，通过哪个平台，都能随时唤起我们的私人 AI 助手，而无需担忧数据隐私或依赖不稳定的第三方托管服务。OpenClaw 让我们的 AI 助手真正驻留在自己的硬件上，听从我们的规则，为我们构建一个安全、统一且高度可扩展的智能交互网络。 虽然关于 OpenClaw 的部署文章已经随处可见，但是当你安装并实际使用时，如果你不了解 OpenClaw 设计架构的精妙之处，你很难真正知道 OpenClaw 能干什么、怎么干，以及它的边界和限制在哪里。本篇文章，我将深入 OpenClaw 的工作原理，让你全面了解这个系统。 工作原理 OpenClaw 的原理可以参考下图。
- 左侧输入：Chat apps + plugins -> Gateway
各聊天渠道（ Telegram/WhatsApp/Discord/Slack 等）通过 channel plugin 接入，统一成标准事件。 消息归一化：每条入站消息在 Gateway 内被归一化为：channel + account + 会话键(sessionKey) + 消息体。 插件能力：插件还能扩展工具、hooks 、额外 RPC 方法，它不仅仅是“多一个渠道”。
- 中枢：Gateway 做什么
核心职责：负责长驻连接、鉴权、会话状态、方法路由、事件广播。 统一管理：把“谁发来的、发到哪、当前会话上下文”统一管理，然后分发到 agent/chat/send 等。 协议一致：所有前端/客户端几乎都通过同一套 Gateway 协议交互，所以能力一致性很高。
- 右侧能力面：Gateway -> Pi agent / CLI / Web UI / macOS / iOS&Android nodes
Pi agent：推理执行核心（生成回复、调用工具、读写会话记忆）。 CLI：既可直接跑命令，也可作为 Gateway 的运维与调用入口。 Web Control UI / macOS app：本质是 Gateway 的可视化控制台（配置、状态、日志、会话）。 iOS/Android nodes：移动端节点，向 Gateway 注册、收发事件、执行被下发任务。
Chat apps + plugins 这块可以理解成：Gateway 左侧的“外部世界接入层”。 它主要做两件事：
Chat apps：真实消息来源/去向（ Telegram 、WhatsApp 、Discord 、iMessage 等）。 负责“把用户消息带进来、把回复发出去”。 Plugins：协议适配器 + 扩展能力。 把每个平台各自不同的 API/事件格式，转换成 Gateway 能统一处理的格式；也能附加新能力（新渠道、工具、hooks 、provider 、自定义命令等）。
所以这块的作用不是“处理 AI”，而是：把杂乱的外部渠道世界，整理成 Gateway 能懂的统一输入输出。 没有这层，Gateway 就没法稳定接那么多不同平台。 图里把 plugins 画在左边，是从“概念层”强调它在入口侧扩展渠道能力，但在“实现层”上，插件系统确实是 Gateway 启动时加载、注册到 Gateway 内部 的（不是独立外部服务）。所以它不只是“前置动作”，而是 Gateway 运行时的一部分：
启动时：发现并加载插件； 运行时：插件参与消息接入、路由、工具调用、RPC 扩展、渠道发送。
Gateway Gateway 就是 OpenClaw 的“大脑中枢 + 交通枢纽 + 安全门禁”。 它的定位不是某个聊天渠道，也不是单纯的 API 服务，而是把所有能力组织起来的核心层：
统一入口：Telegram 、WhatsApp 、Discord 、iMessage 、WebChat 、移动端 node 、CLI 、macOS/iOS/Android 客户端，最后都汇到 Gateway 。 统一协议：不管前端来自哪里，Gateway 都用同一套方法（ RPC/事件）处理，避免每个端自己发明一套逻辑。 统一会话：它维护 sessionKey、上下文、最后路由目标、线程信息，让“这次对话是谁、在哪、怎么回”始终可追踪。 统一路由：消息进来后决定交给谁（ agent 、chat handler 、工具、channel adapter ），回复再按来源和策略发回去。 统一安全：鉴权、角色、scope 、配对审批、节点命令白名单都在 Gateway 层收口，不让客户端直接越权。 统一扩展：插件（ channels/tools/hooks/providers/http/gateway methods ）都挂在 Gateway 生态上，扩展时不用改核心主干。 统一可观测：状态、日志、健康检查、事件广播都以 Gateway 为中心，Web 控制台和 CLI 看的是同一份事实。
Gateway 的价值是把“多端、多渠道、多能力”变成一个一致、可控、可扩展的系统。没有它，OpenClaw 就会退化成一堆彼此割裂的小工具。 统一安全
Gateway 在连接握手就做认证和角色判定（ operator / node ）并下发 scopes ，后续每个方法再次校验，避免越权调用。 方法级权限是白名单式的：读写、审批、配对、管理员能力分别受控，不是“连上就全能”。 节点（ iOS/Android/macOS node ）还有二次约束：配对审批 + 命令白名单 + 节点声明能力，三层都通过才执行。 会话层还有发送策略（ allow/deny ）控制，防止某些 session 被误发消息。
统一扩展
插件可注册多种能力：渠道、工具、hooks 、provider 、CLI 子命令、Gateway 方法、HTTP 路由。 Gateway 启动时统一发现并加载插件，注册到同一个 registry ，核心不需要为每个新渠道写 if-else 。 这让“加一个新渠道”变成“实现插件契约”，不是重构整个系统。 同时支持内置渠道和 extensions 目录下的外部插件，扩展边界清晰。
统一观测
Gateway 集中维护健康状态、在线节点、会话状态、事件流，并广播给 CLI/Web/macOS/mobile 。 日志、心跳、状态快照、运行事件（ agent/chat/node ）都从同一中枢输出，所以排障时事实源一致。 status/health/logs 看到的是同一套运行时，不会出现“CLI 说正常，Web 说异常”的多套口径问题。 对你这种多端场景最关键：任何端的问题都能回溯到 Gateway 这一条主链路。
用户身份（ Telegram/Discord/飞书里的“谁发的消息”）
每个渠道先用自己的原生 ID （ Telegram user id 、Discord user id 、飞书 open_id 等）接入。 OpenClaw 不会把它们直接当成同一个人，而是会先带上渠道命名空间（可理解为 telegram:123、discord:abc、feishu:xxx）。 然后路由层根据 channel + account + peer (chat/group/thread) 生成 sessionKey，决定这条消息落到哪个会话。
所以在 OpenClaw 视角，默认是：同一个“人类用户”在不同渠道，先被当成不同身份流量处理。 如何把同一个人的不同渠道身份认成同为一个人呢？ 会不会“合并”取决于配置策略，不是自动魔法识别。如果你配置了 identityLinks，可以把跨平台 ID 映射到同一 canonical identity，实现“跨渠道同人合并”。不配置的话，通常按渠道隔离或按会话策略合并，不会无脑认同一个人。 消息入站流程 消息的入站流程需要先了解 OpenClaw 里的 Agent 、Session 、Context 设计。
Agent：可以理解为一个可配置的人格/岗位。每一个 Agent 都可以单独配置一个自己的默认模型、可用工具列表、工作的目录，可以通过 Prompt 预设行为风格。在 OpenClaw 可以通过 CLI 命令创建一个 Agent 。当消息入站，OpenClaw 会根据配置的规则，给请求分配对应的 Agent 。我们可以把 Agent 当成 Java 中的 .class 文件。
Session：某个 Agent 的一个持续对话状态容器，可以理解为 Java 中通过 new 创建出来的实例。Session 是“和谁聊、在哪条线聊”的记忆边界。 不同 Session 默认隔离，互不共享历史；这就是多人同时使用同一个 OpenClaw 时不串话的关键。每一次用户的请求，OpenClaw 都会根据配置，分配或者绑定 Session 会话。
Context （上下文）：Context 是每次调用模型时“喂给 LLM 的输入包”，是临时拼出来的，不是长期对象。它通常由这些部分组成：系统设定 + 当前消息 + 从 Session 里抽取的历史片段 + 工具结果 + 运行时元信息。一次回答结束后，Context 会消失；但对话结果会写回 Session （持久化）。 LLMs （模型层）：在 OpenClaw 中的 LLM 是“无状态推理器”。OpenClaw 每次请求都会开启一个新的 LLM 实例然后拼接本次会话需要的 Context 。当一次会话结束以后，OpenClaw 会根据对话结果更新 Session ，同时关闭 LLM 的会话。LLM 端是无状态调用：对模型 API 来说每次请求都是新请求；不会天然记住上次。所谓“连续对话”是 OpenClaw 把历史重新带上去实现的。这一点跟 Codex 、OpenCode 、ClaudeCode 等有本质的区别。 技能 (Skills)：OpenClaw 支持全局共享 Skill 、每个 Agent 独享 Skill ； Session 侧更像是有一个 Skills 可见性快照（用于当次/该会话阶段运行一致性），不是给每个 Session 单独安装一份 Skill 。Skill 的来源按全局/Agent 管； Session 只管当下可见与调用状态。
消息入站的具体流程为：
入站先读 Session
按 sessionKey 找会话条目（ sessionId 、thinking/model override 、lastChannel/lastTo 等）。 如果不存在或触发 reset ，就新建 sessionId。
临时生成 Context
用当前消息 + 会话历史 + agent/system prompt + 渠道元数据 + 媒体/链接增强拼装本轮输入。 这个 Context 只在本轮推理内存在，不直接持久化。
模型执行后，写 Transcript
本轮 user/assistant/tool 事件追加到 sessionId 对应 JSONL （物理历史）。
写回 Session 元数据
更新 updatedAt、lastChannel/lastTo、deliveryContext、思考级别/模型覆盖、token 统计等。 这一步是“把本轮结果沉淀成下轮可用状态”。
路由规则
- Agent ID 的路由规则：具体哪个身份来处理当前的用户消息 可以按渠道、群/团队、账号、甚至具体会话目标去分流到不同 Agent 。可以把它看成“分单规则引擎”，输入一条消息后按优先级匹配：
peer 精确匹配（某个人/某个群/某个频道） parent peer（线程场景继承父会话） guild/server（如 Discord 服务器级） team/workspace（如 Slack 团队级） account（某渠道下的某账号） channel（ Telegram/Discord/Slack…整渠道） 最后回退到 default agent
配置维度（可控项）：
Agent 列表（哪些 Agent 存在，哪个是默认）
绑定规则（ match.* -> agentId ） 可按：channel 、accountId 、peer(kind+id)、guildId 、teamId
运行时可显式指定 Agent ，会覆盖默认路由；但会做一致性校验，防止乱绑。
- SessionKey 的路由规则（落哪条记忆线） 会话类型分三大类：
DM （私聊）
Group （群聊）
Channel （频道/公开通道）
DM （私聊）：重点是“私聊是否合并/拆分会话” → dmScope
Group （群聊）：重点是“群是否允许进入、是否必须 @ 、谁可触发” → groupPolicy / groupAllowFrom / groups.
Channel （公开频道）：重点是“频道级 allowlist 与提及规则、按频道绑定到哪个 Agent”（例如 Discord/Slack 常是 guild/channel 级配置 + bindings ）
我们展开讲一下私聊场景，DM 的关键是 dmScope 它是“私聊会话切分策略”。也就是：当不同人、不同渠道来私聊时，OpenClaw 要不要把他们放到同一条记忆线上。你可以把它理解成“秘书的档案柜分隔规则”。 四种常见策略：
main：所有私聊共用一个主会话 优点：连续性最强，像同一个人一直在聊。 风险：多人场景容易串上下文（ A 的内容被 B 继承）。
per-peer：按“人”分会话（跨渠道可合并同一人） 适合你能稳定识别“同一个人”的场景。 比 main 安全很多。
per-channel-peer：按“渠道 + 人”分会话 Telegram 的你和 Discord 的你是两条线。 多人系统里常用，隔离更稳。
per-account-channel-peer：按“账号 + 渠道 + 人”分会话 适合一个系统挂多账号（比如多个 Telegram bot 或多工作区）。 隔离最细，最不容易串。
额外维度：
identityLinks：把跨渠道“同一个人”映射到同一 canonical 身份（只在你配置时生效）。 thread/topic：在线程型渠道再细分子会话。 mainKey：主会话别名（默认 main ）。 session scope：有的部署会用全局/按发送者模式做更粗粒度控制。
先有 Agent ID ，再生成 SessionKey 。 它的输入维度是：AgentId + 会话类型 + 渠道/账号/对象 ID + 线程信息 + DM 切分策略。 根据你的配置，会生成对应的 SessionKey ，然后再绑定到具体的 Session 上面去。 AgentId + SessionKey 的组合意义：
agentId：谁处理（人格/策略）。 sessionKey：在哪条记忆线上处理（上下文边界）。
所以同一个人可以： 进同一个 Agent 但不同 Session （隔离）。 或进不同 Agent （不同角色）且各自独立 Session 。
整个会话的交互时序图如下。
Pi agent Pi agent 可以理解成 OpenClaw 的“推理执行内核”。 它不是渠道，也不是网关，而是负责“真正思考和产出”的那层。 核心作用：
接收任务：从 Gateway 拿到已经整理好的上下文（用户消息、会话历史、系统设定等）。 调用模型：用配置的 LLM 运行一次 Agent 回合。 做工具编排：需要时触发 tools/skills （查资料、发消息、执行动作等）。 生成结果：输出回复文本、工具结果、状态事件，再回交给 Gateway 分发。 维护回合状态：配合 Session 信息处理 thinking/model override 、中断、等待等流程。
Agent / Session / Context 是 OpenClaw 的整体架构概念（主要由 Gateway + 运行时共同管理）。 Pi agent 主要负责“执行推理回合”（吃 Context 、跑模型、调用工具、产出结果）。 消息出站的流程
产出回复结果 Pi agent 返回文本/工具结果/结构化输出给 Gateway 。
决定“发往哪里” 优先按本次消息的来源路由回去（原渠道、原会话目标）。 如果没有明确来源，再用 Session 里的最后路由信息兜底。
应用发送策略 检查会话发送策略、频道能力、权限约束（是否允许发、发到哪个目标）。
渠道适配与投递 Gateway 调对应 channel 插件，把统一回复格式转成 Telegram/Discord/WhatsApp 等各自 API 格式并发送。
写回会话状态 更新 Session 元数据（更新时间、lastChannel/lastTo 、usage 等）并追加 transcript 。
广播运行事件 把结果/状态同步给 Web 控制台、CLI 、macOS/iOS/Android 客户端。
Web 与 OpenClaw CLI Web 偏在线运营控制台（可视化 + 实时），CLI：偏全量运维与自动化入口（可脚本、可批处理、覆盖更全）。 Web （ Control UI ）能力
实时聊天：发送、流式回复、停止当前运行 会话管理：查看会话列表、改会话参数（如思考/verbose ） 渠道运营：看渠道状态、扫码登录、调渠道配置 节点管理：查看已配对节点、能力状态 定时任务：cron 的增删改查、手动触发、查看运行记录 技能管理：查看技能状态、启用/禁用、安装与更新 配置中心：可视化配置编辑（含 schema 表单 + raw JSON ） 日志与诊断：health/status/models 快照、实时日志 tail 更新入口：触发更新并查看重启报告
OpenClaw CLI 能力
安装与初始化：setup 、onboard 、configure 服务生命周期：gateway install/start/stop/restart/run 渠道与插件：channels add/login/status 、plugins install/enable/disable Agent 管理：agent 、agents list/add/delete 等 会话与消息：sessions 、message send/poll/react/broadcast 定时与自动化：cron add/edit/run/runs （脚本化最强） 安全与审批：security audit 、approvals 、devices 、pairing 节点与浏览器控制：nodes 、node 、browser 全套命令 系统运维：logs 、status 、health 、system 、models 、hooks 等
OpenClaw 定时任务 (Scheduler) Gateway 里跑着一个一直在线的定时器（ scheduler ），负责管理所有定时任务。这些定时任务都会被保存到磁盘上，所以就算服务重启，任务也不会丢失。到了设定的时间点，系统就会触发一次 Agent 的执行。执行完的结果可以选择：
只在内部记录下来 或者把结果发送到指定的聊天渠道
每个 cron 任务主要包含以下几个关键信息：
agentId：指定由哪个 Agent 来执行这个任务（不填就用默认的 Agent ） sessionTarget：决定这次执行是在「主会话」里跑，还是用一个独立的会话 payload：到了时间点后，到底要让 Agent 做什么（可以是 system event ，也可以是完整的 agent turn ） wakeMode：是立刻唤醒 Agent 处理，还是等到下一次心跳再处理 delivery：执行结果要不要往外发送？如果要发，发到哪个聊天渠道或目标
最核心的两种执行方式对比
用主会话（ sessionTarget = main ） 系统会往这个 Agent 的主对话里插入一条 system event 然后根据 wakeMode 设置，立即唤醒或等到下次心跳再让 Agent 响应 适合用来做「定时提醒」「日程事项」「重要通知」这类希望融入日常对话、保留上下文的任务
用独立会话（ sessionTarget = isolated ） 每次执行都会创建一个全新的、临时的会话（内部标记为 cron:<任务 ID>） 不会带入上一次运行的任何对话历史，避免上下文互相干扰 但会继承一些会话级别的配置（比如用哪个模型、思考深度等设置） 特别适合做「日报生成」「数据巡检」「批量处理」「后台统计」这种不需要跟用户主聊天混在一起的任务
iOS/Android nodes iOS/Android nodes 即“移动端节点”，把手机变成 OpenClaw 网络里的一个可控设备角色。 它的作用主要有三件事：
当执行端：PC 端的 Gateway 可以给手机下发“受限动作命令”（比如拍照、录屏、定位、发短信等，具体看白名单和权限）。 当交互端：手机自己也能主动跟 Gateway 说话（比如发 chat/agent 请求），不只是被动等命令。 当统一会话的一部分：手机、Web 、macOS 、CLI 都连到同一个 Gateway ，会话和状态能同步，形成一个多端协同的“同一个 OpenClaw”。
现在 iOS/Android node 就是 OpenClaw 的“移动端能力节点 + 控制入口”，让手机成为整个系统里的第一类成员，而不是外挂设备。 openclaw 与 tailscale Tailscale 是一个非常好用的现代虚拟组网 / Mesh VPN 工具，简单来说就是： 它能让你把分散在世界各地的设备（手机、电脑、NAS 、服务器、树莓派、云服务器等）像处在同一个局域网里一样互相访问，而且整个过程非常简单、安全、几乎零配置。 openclaw 里默认集成里 tailscale ，默认是关闭的状态。tailscale 模块本质上是 给 Gateway 做“安全远程入口” 。通过 tailscale 你可以在任何地方都能够访问你的 web 管理入口。 不过 openclaw 在中国大陆的网络环境下有点水土不服，你可以使用星空组网进行平替。 openclaw 的记忆架构 openclaw 牛的点在于永久性的记忆，它的记忆机制是让它感觉“像真人一样记住东西”的关键核心：不同于大多数 AI 靠短暂的上下文窗口硬撑，OpenClaw 把记忆彻底外化到磁盘上的纯 Markdown 文件里，文件本身就是真相来源，模型每次只加载需要的内容，就像人类翻笔记而不是把所有人生经历塞进大脑。 具体来说，它采用非常简洁的两层设计：短期/临时记忆靠每天一个追加式文件（通常在 memory/YYYY-MM-DD.md 里），记录当天的决策、运行日志和上下文，启动会话时自动把今天 + 昨天的内容加载进来，提供最近的连续感却不会把 token 撑爆；长期/精选记忆则集中在单个核心文件 MEMORY.md （也有人叫它“灵魂文件”），里面放用户偏好、重要结论、项目约定、不能忘的关键事实，只有在私密个人会话中才会加载（群聊或共享场景故意不读，保护隐私）。此外还有可选的会话记录（ sessions/ 目录下），完整对话历史可以被搜索或定期摘要归档。 为了“想起来”东西，OpenClaw 不依赖黑盒向量数据库，而是用混合检索（ BM25 关键词 + 向量相似度）在这些 Markdown 文件上建小索引，Agent 需要时自己调用工具去搜（比如“memory_search”），真正需要的内容才 page in 到上下文里。整个过程透明到极致：你随时用任意文本编辑器打开、修改、删除 AI 的“记忆”，没有隐藏状态；当上下文太长时，Agent 还能主动把关键点 flush 到 MEMORY.md 再压缩历史，避免遗忘重要信息。这种“磁盘是硬盘、上下文是缓存”的哲学，让 OpenClaw 在本地 Agent 里拥有了罕见的持久性和可控性——它不会每次重启就失忆，但也完全由你掌控，不会偷偷积累你不想留的东西。简单、开放、却意外强大，这就是很多人觉得它“像活的”原因。 openclaw 的自我进化 技能的存在，还可以让他自己完善自己的能力。比如你可以让它创建一个邮件收发的技能，你只需第一次详细告诉它你的 SMTP/IMAP 配置（服务器地址、端口、用户名、密码或 app-specific password 、加密方式等），并描述期望的行为（如“用我的 Gmail 发带附件的日报”“自动回复特定关键词的邮件”），OpenClaw 就会自己生成一个专属的“邮件收发技能”——它会写出 SKILL.md 文件（包含工具描述、调用参数、错误处理逻辑），并关联必要的 Python/Node 脚本或内置工具调用（如 smtplib 或 imaplib ）。一旦保存进 skills 目录，这个技能就永久可用。 这些自我进化的能力源于 OpenClaw 的核心插件系统和内存机制，允许 Agent 不只是执行指令，而是像活的实体一样，通过代码生成、测试和持久存储来扩展自身边界，最终从一个通用助手变成高度个性化的生产力伙伴。 要是学累了，就来打打游戏吧