🦞 OpenClaw 运行原理与能力范围
自托管 AI 代理网关 · 从消息到智能的完整链路
一、OpenClaw 是什么？
一句话概括
OpenClaw 是一个自托管网关（Gateway），把你的聊天 App（Telegram、WhatsApp、Discord、iMessage 等）连接到 AI 代理。你在任何设备上发一条消息，AI 就能回复并替你执行操作。
🏠
自托管
运行在你自己的机器上，数据不经过第三方服务器，完全掌控。
🔌
多通道
一个 Gateway 进程同时服务 Telegram、WhatsApp、Discord、iMessage 等多个渠道。
🤖
代理原生
内置工具调用、会话管理、记忆系统、多代理路由，不只是聊天转发。
二、架构总览
关键要点
Gateway 是唯一的中心进程。所有消息渠道、客户端、移动节点都通过 WebSocket 连接到它。Gateway 负责路由消息、管理会话、调用 AI 模型、执行工具。
三、一条消息的生命周期
详细流程
1 消息通过渠道 SDK（如 grammY）到达 Gateway
2 Gateway 根据发送者/群组匹配到对应的 Session
3 组装上下文：系统提示词 + 工作区文件 + 历史消息 + 记忆
4 调用 AI 模型（如 Claude Opus 4），流式返回响应
5 如果模型需要工具（读文件、搜索、执行命令），Gateway 执行后将结果反馈模型
6 最终文本回复通过原渠道发送回来
四、会话管理
OpenClaw 用 Session 隔离不同对话的上下文，避免信息泄漏。
会话路由规则
私聊 默认合并到 main 会话（单用户连续对话）
群聊 每个群独立会话 group:<id>
Cron 定时任务独立会话 cron:<job.id>
子代理 生成隔离会话，完成后汇报
多用户安全
如果多人可以私聊你的 Bot，必须设置 dmScope: "per-channel-peer"，否则所有人共享同一个会话上下文——A 的隐私会被 B 看到。
五、核心能力矩阵
📂
文件操作
读、写、编辑任意文件。在工作区内自由操作代码和文档。
⌨️
命令执行
运行 shell 命令、管理后台进程、支持 PTY 交互式终端。
🌍
网络搜索
Brave Search、Tavily、网页抓取，获取实时信息。
🖥
浏览器控制
打开网页、截图、点击、输入，完成浏览器自动化任务。
🧠
记忆系统
MEMORY.md 长期记忆 + memory/*.md 每日笔记，跨会话持久化。
👥
多代理
生成子代理执行复杂任务，支持 Codex、Claude Code 等编码代理。
📱
移动节点
iOS/Android 配对后可远程拍照、录屏、获取定位、操作通知。
🎨
Canvas 画布
在移动端/浏览器渲染 HTML 页面，展示可视化内容。
⏰
自动化
Cron 定时任务、Heartbeat 心跳、Webhook 回调，无人值守运行。
🔊
语音
TTS 文字转语音、语音消息转录、语音通话（实验性）。
🔐
安全控制
allowFrom 白名单、Gateway Token、设备配对审批、工具策略。
🔌
技能扩展
从 ClawdHub 安装技能，或在 workspace/skills 自定义技能。
六、工作区文件体系
工作区是 AI 代理的「家」，所有配置和记忆都在这里。
~/.openclaw/workspace/
├── AGENTS.md ← 行为指南：怎么做事
├── SOUL.md ← 人格：语言、风格、边界
├── USER.md ← 主人信息：名字、偏好
├── IDENTITY.md ← 自我身份：名字、emoji
├── TOOLS.md ← 工具备忘：设备名、SSH 等
├── MEMORY.md ← 长期记忆（精炼）
├── HEARTBEAT.md ← 心跳任务清单
├── memory/ ← 每日笔记 YYYY-MM-DD.md
├── skills/ ← 自定义技能
└── docs/ ← 文档
~/.openclaw/
├── openclaw.json ← 核心配置文件
└── agents/main/sessions/ ← 会话记录 (JSONL)
七、关键概念速查
🔄 Compaction（压缩）
会话过长时，Gateway 自动压缩旧的上下文，保留摘要。压缩前会触发「记忆刷新」，提醒 AI 把重要信息写入文件。
📡 Streaming（流式输出）
AI 回复边生成边发送，不用等全部完成。长回复会自动分块（chunking），适配各平台消息长度限制。
🛡 Tool Policy（工具策略）
配置哪些工具可用、哪些需要人工审批。比如可以让 AI 自由读文件，但执行 rm 前必须确认。
🔀 Multi-Agent Routing（多代理路由）
一个 Gateway 可以运行多个代理，每个有独立的工作区和会话。通过路由规则把消息分发到对应代理。
💓 Heartbeat vs Cron
Heartbeat：周期性轮询，适合批量检查（邮件+日历+天气）。Cron：精确定时任务，独立会话执行。
八、你的当前配置
🖥 硬件
Mac mini M4, macOS 26.2
九、深入学习
- 官方文档：docs.openclaw.ai
- 架构详解：docs.openclaw.ai/concepts/architecture
- 会话管理：docs.openclaw.ai/concepts/session
- 配置参考：docs.openclaw.ai/gateway/configuration-reference
- 安全指南：docs.openclaw.ai/gateway/security
- 技能市场：clawhub.com
- 源代码：github.com/openclaw/openclaw
- 社区：discord.com/invite/clawd