对 OpenClaw Gateway 消息机制的个人理解

OpenClaw 上线以来间断地养过虾，除了一些基本类助理的功能表现优秀之外，经过探索它在RCA+Tools上也很值得期待，个人觉得目前它主要的阻碍是安全性，即工具执行中 “exec + allowedBinaries” 和权限管理中的 “allowedDirectories + 沙箱” 机制。当然核心也不可回避地要考虑到OpenClaw的运行角色（root or common-user）及 Openclow.json 的文件安全，以防止Prompt提示词注入类的工具提升权限，引发运维中不可避免的损失。

任何一个新的事物的发展都需要经历检验和挑战，但OpenClaw的确是开启了从 “对话式AI” 到 “行动式AI” 的范式跃迁。叠加其本身已经具备的策略配置约束智能体边界，让AI从执行上变的可控、透明、可审计，让"技术民主化"的远景 -- “飞入寻常百姓家”。但今天要讨论的不是这些，是我对OpenClaw消息机制的一点个人理解。

以上是依据个人理解画的一个OpenClaw消息流图，

引言：为什么需要理解完整会话流程？

在构建基于 OpenClaw 的 AI 应用时，开发者常常面临以下困惑：

用户消息如何从飞书/Web 渠道传递到智能体？

不同用户的会话如何隔离？上下文如何保持？

SOUL.md、USER.md 等配置文件何时加载？如何影响智能体行为？

工具调用（Skills/Exec/Memory）是如何触发和执行的？

理解完整的数据流转路径，不仅是调试问题的基础，更是优化性能、设计扩展功能的前提。

一、消息接入与标准化

1.1、用户在不同渠道（Web 聊天窗口、飞书机器人、Telegram、Discord）发送消息后，OpenClaw 的第一道关卡是 Gateway 接收层，gateway 接收到不同的消息后，将它们标准化为统一的 message 对象

# 支持的消息渠道channels:  - web: WebSocket/HTTP REST API  - feishu: 飞书开放平台 webhook  - telegram: Telegram Bot API  - discord: Discord Gateway  - whatsapp: WhatsApp Business API

二、Session Key 路由识别

消息标准化后，Gateway 面临一个关键问题：这条消息属于哪个会话？OpenClaw 通过 session Key 实现细粒度的会话隔离。

场景	消息特征	生成的 Session Key	说明
用户在 Web 直接提问	`channel=web, type=direct`	`agent:default:main`	所有 Web 直接聊天共享一个会话
飞书群@机器人	`channel=feishu, type=group, gid=123`	`agent:default:feishu:group:123`	每个群独立会话

会话隔离的意义

上下文隔离：群A的对话历史不会泄露到群B
配置隔离：不同会话可加载不同的 USER.md（用户偏好）
并发安全：避免多线程写入同一会话状态

如果是一个新的会话，则通过 bootstrap 加载系统默认的 SOUL.md、USER.md 等建立会话。

三、工作区和上下文Context加载

一旦确定了 sessionKey，Gateway 需要为这个会话加载上下文配置文件。这些文件位于**工作区（Workspace）**目录中。

~/.openclaw/workspaces/

├── SOUL.md # 智能体人格定义

├── USER.md # 用户档案与偏好

├── AGENTS.md # 操作指令与记忆

├── TOOLS.md # 工具使用说明

├── IDENTITY.md # 智能体身份标识

└── memory/ # 向量知识库索引

对于新创建的Session, 有 bootstrap 负责加载至上下文中

async def load_workspace_context(session_key: str, workspace_path: Path) -> dict:    """    加载工作区上下文文件    """    context_files = {        "SOUL": workspace_path / "SOUL.md",        "USER": workspace_path / "USER.md",        "AGENTS": workspace_path / "AGENTS.md",        "TOOLS": workspace_path / "TOOLS.md",        "IDENTITY": workspace_path / "IDENTITY.md"    }

四、系统提示词创建

加载完上下文文件后，Gateway 需要将它们组装成系统提示词（System Prompt），这是影响智能体行为的最关键因素，因为不同场景，Session 下加载的内容不一，这也是为什么OpenClaw吃token（新说法叫词元）太多的原因之一。

4.1、动态提示词生成：

这里举一个例子，动态提示词加载

# Identity - 来源于Identified.md

你是 OpenClaw 助手，由 OpenClaw 团队开发。

# Personality & Behavior - 来源于SOUL.md

你是一个专业的 DevOps 工程师助手，擅长 Kubernetes、CI/CD 流水线设计。

# User Profile - 来源于 USER.md

姓名：小学生

技术栈：Python, FastAPI, Kubernetes

最终合成的Prompt长度就是：SOUL.md → USER.md → AGENTS.md → TOOLS.md → 渠道规则 → 最终拼接成完整的 System Prompt。最终可能形成一个几百K Token的上下文，未开始正式工作，“token 已如流水东去也”。

五、Pi Agent 推理引擎

系统提示词构建完成后，Gateway 通过 createAgentSession() 直接实例化 Pi Agent（同进程，非 RPC）

5.1、推理拆解过程

用户消息: "帮我部署一个 FastAPI 服务到 Kubernetes"

↓

┌─────────────────────────────────────┐

│ 1. 理解意图 │

│ - 识别任务类型：代码生成 + 部署 │

│ - 提取关键信息：FastAPI, K8s │

└─────────────────────────────────────┘

↓

┌─────────────────────────────────────┐

│ 2. 检索上下文 │

│ - 查看 USER.md：用户技术栈确认 │

│ - 查看 SOUL.md：DevOps 专家角色 │

│ - 搜索记忆：是否有历史部署经验？ │

└─────────────────────────────────────┘

↓

┌─────────────────────────────────────┐

│ 3. 规划执行步骤 │

│ Step 1: 生成 FastAPI 代码框架 │

│ Step 2: 编写 Dockerfile │

│ Step 3: 生成 K8s Deployment YAML │

│ Step 4: 提供 kubectl 部署命令 │

└─────────────────────────────────────┘

↓

┌─────────────────────────────────────┐

│ 4. 工具调用决策 │

│ - 需要读取模板文件？→ 调用 exec │

│ - 需要搜索最佳实践？→ memory_search│

│ - 需要生成代码？→ 直接推理 │

└─────────────────────────────────────┘

↓

┌─────────────────────────────────────┐

│ 5. 生成响应 │

│ - 流式输出代码块 │

│ - 添加解释说明 │

│ - 提供下一步建议 │

└─────────────────────────────────────┘

六、工具调用与技能执行

Pi Agent 根据自己的推理思考，调用相应的工具或Skills, 缺乏什么样的Skill会去市场下载。

七、结果回流与响应

Pi Agent 的推理结果是流式输出的（token by token），Gateway 需要实时推送给用户

以下借助一个生成的图进行整个过程的说明

以上就是个人理解的一次完整的OpenClaw会话过程，OpenClaw 的强大，不在于单个组件，而在于这些组件如何无缝协作

参考文档：https://docs.openclaw.ai/

知识点扫盲：https://chat.qwen.ai/ - Qwen3.5 AI Model

注：一家之言仅供参考，如有问题还请各位朋友们交流讨论。