OpenClaw 深度拆解：从环境部署到架构构造的完整指南
本文基于 OpenClaw 官方文档和源码分析，系统拆解这个 375k+ Stars 的个人 AI Agent 框架。从环境准备到核心架构，再到思维导图可视化，带你一文看懂 OpenClaw 的构造逻辑。
一、OpenClaw 是什么？
OpenClaw 是一个个人 AI 助手框架，你可以在自己的设备上运行它。它通过你已经在用的通讯渠道（WhatsApp、Telegram、Slack、Discord、Signal、iMessage 等 20+ 渠道）与你交互，支持语音唤醒、实时画布渲染，以及多 Agent 隔离运行。
核心特点：
– 本地优先：Gateway 守护进程跑在你自己的机器上
– 多渠道 inbox：20+ 通讯渠道统一接入
– 多 Agent 路由：每个 Agent 独立工作区、独立人格、独立会话
– 语音交互：macOS/iOS 唤醒词 + Android 持续语音
– 实时画布：Agent 驱动的可视化工作区（A2UI）
– Skills 生态：ClawHub 技能市场，5400+ 技能
二、环境部署：从零开始
2.1 系统要求
| 组件 | 最低要求 | 推荐 |
|---|---|---|
| Node.js | 22.19+ | 24.x |
| OS | macOS / Linux / Windows (WSL2) | macOS / Linux |
| 内存 | 4GB | 8GB+ |
| 存储 | 2GB | 5GB+ |
2.2 安装步骤
# 全局安装
npm install -g openclaw@latest
# 或 pnpm add -g openclaw@latest
# 引导安装（推荐）
openclaw onboard --install-daemon
onboard 会引导你完成：
1. Gateway 配置
2. 工作区初始化
3. 渠道连接（Telegram/WhatsApp/Slack 等）
4. Skills 安装
2.3 目录结构
~/.openclaw/
├── openclaw.json # 主配置文件
├── credentials/ # 渠道/提供商状态 + OAuth 数据
├── agents/
│ └── <agentId>/
│ ├── agent/
│ │ └── auth-profiles.json # 模型认证配置
│ └── sessions/ # 会话记录 (JSONL)
├── skills/ # 托管技能
└── sandboxes/ # 沙盒工作区
~/.openclaw/workspace/ # 默认 Agent 工作区
├── AGENTS.md # 操作指令 + 记忆
├── SOUL.md # 人格、语气、边界
├── USER.md # 用户画像
├── IDENTITY.md # Agent 名称/氛围/表情
├── TOOLS.md # 本地工具约定
├── HEARTBEAT.md # 心跳检查清单
├── BOOTSTRAP.md # 首次运行仪式
├── memory/ # 每日记忆日志
│ └── YYYY-MM-DD.md
└── skills/ # 工作区专属技能
2.4 快速启动
# 守护进程模式（推荐）
openclaw onboard --install-daemon
openclaw gateway status
# 前台调试模式
openclaw gateway stop
openclaw gateway --port 18789 --verbose
# 发送测试消息
openclaw message send --target +1234567890 --message "Hello from OpenClaw"
# 与 Agent 对话
openclaw agent --message "Ship checklist" --thinking high
三、核心架构拆解
3.1 整体架构图
┌─────────────────────────────────────────────────────────────┐
│ 用户层 (Channels) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │WhatsApp │ │Telegram │ │ Discord │ │ Slack │ ... │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ └───────────┴───────────┴───────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ │ Gateway │ ← 单一控制平面 │
│ │ (Daemon) │ WebSocket 服务器 │
│ │:18789 │ │
│ └─────┬─────┘ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │
│ │ macOS │ │ iOS │ │ Android │ │
│ │ App │ │ Node │ │ Node │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Agent Runtime │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ ... │ │ │
│ │ │(工作区A)│ │(工作区B)│ │(工作区C)│ │ │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Skills │ │ Tools │ │ Sessions│ │ │
│ │ │ 加载器 │ │ 执行器 │ │ 管理器 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
3.2 Gateway（网关）
Gateway 是 OpenClaw 的核心控制平面，负责：
- 连接管理：维护所有渠道（WhatsApp/Telegram/Discord 等）的连接
- WebSocket 服务器：暴露 typed WS API，处理请求/响应/事件
- 协议验证：JSON Schema 校验入站帧
- 事件分发：
agent,chat,presence,health,heartbeat,cron
WebSocket 协议：
Transport: WebSocket, text frames with JSON
First frame: connect (必须)
Requests: {type:"req", id, method, params}
Responses: {type:"res", id, ok, payload|error}
Events: {type:"event", event, payload, seq?}
连接生命周期：
Client → Gateway: req:connect
Gateway → Client: res (ok) + event:presence + event:tick
Client → Gateway: req:agent
Gateway → Client: res:agent {runId, status:"accepted"}
Gateway → Client: event:agent (streaming)
Gateway → Client: res:agent final {runId, status, summary}
3.3 Agent Runtime（代理运行时）
OpenClaw 运行单个嵌入式 Agent 运行时，每个 Gateway 一个 Agent 进程，包含：
| 组件 | 说明 |
|---|---|
| Workspace | Agent 唯一工作目录（文件工具上下文） |
| Bootstrap 文件 | AGENTS.md/SOUL.md/USER.md/IDENTITY.md 等 |
| Skills | 从多个来源加载，按优先级覆盖 |
| Sessions | JSONL 格式存储在 ~/.openclaw/agents/<id>/sessions/ |
| Tools | 内置工具（read/exec/edit/write 等） |
Agent 循环（Agent Loop）：
┌─────────────────────────────────────────────────┐
│ Agent Loop 生命周期 │
├─────────────────────────────────────────────────┤
│ 1. Intake → 接收用户输入 │
│ ↓ │
│ 2. Context Assembly → 组装系统提示 + 上下文 │
│ ↓ │
│ 3. Model Inference → LLM 推理 │
│ ↓ │
│ 4. Tool Execution → 执行工具调用 │
│ ↓ │
│ 5. Streaming Replies → 流式回复 │
│ ↓ │
│ 6. Persistence → 持久化会话记录 │
└─────────────────────────────────────────────────┘
3.4 多 Agent 路由
OpenClaw 支持多 Agent 隔离运行，每个 Agent 拥有：
- 独立工作区：
~/.openclaw/agents/<agentId>/workspace - 独立认证：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json - 独立会话：
~/.openclaw/agents/<agentId>/sessions/ - 独立人格：各自的
SOUL.md+AGENTS.md
路由绑定（Bindings）：
{
agents: {
list: [
{ id: "work", workspace: "~/workspaces/work" },
{ id: "personal", workspace: "~/workspaces/personal" }
]
},
bindings: [
{ channel: "telegram", account: "work_bot", agent: "work" },
{ channel: "whatsapp", account: "+1234567890", agent: "personal" }
]
}
3.5 Skills 系统
Skills 是 OpenClaw 的核心扩展机制，采用 AgentSkills 兼容格式。
加载优先级（高→低）：
| 优先级 | 来源 | 路径 |
|---|---|---|
| 1 | 工作区 skills | <workspace>/skills |
| 2 | 项目 Agent skills | <workspace>/.agents/skills |
| 3 | 个人 Agent skills | ~/.agents/skills |
| 4 | 托管/本地 skills | ~/.openclaw/skills |
| 5 | 内置 skills | 随安装包分发 |
| 6 | 额外目录 | skills.load.extraDirs |
Skill 结构：
skills/
└── my-skill/
├── SKILL.md # YAML frontmatter + 使用说明
├── references/ # 参考文档
├── templates/ # 模板文件
├── scripts/ # 脚本工具
└── assets/ # 静态资源
3.6 安全模型
OpenClaw 的安全设计围绕默认不信任原则：
| 层级 | 机制 | 说明 |
|---|---|---|
| DM 配对 | dmPolicy="pairing" |
未知发送者收到配对码，需手动批准 |
| 沙箱隔离 | agents.defaults.sandbox.mode: "non-main" |
非 main 会话在 Docker 沙箱中运行 |
| 工具审批 | exec-approvals |
危险命令需用户确认 |
| 签名验证 | connect.challenge |
所有连接必须签名 nonce |
默认沙箱策略：
– ✅ 允许：bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn
– ❌ 拒绝：browser, canvas, nodes, cron, discord, gateway
四、核心组件详解
4.1 Bootstrap 文件系统
| 文件 | 作用 | 加载时机 |
|---|---|---|
AGENTS.md |
操作指令 + 记忆规则 | 每次会话 |
SOUL.md |
人格、语气、边界 | 每次会话 |
USER.md |
用户画像 + 称呼方式 | 每次会话 |
IDENTITY.md |
Agent 名称/氛围/表情 | 首次运行后 |
TOOLS.md |
本地工具使用约定 | 每次会话 |
HEARTBEAT.md |
心跳检查清单 | 心跳触发时 |
BOOTSTRAP.md |
首次运行仪式 | 仅新工作区 |
memory/YYYY-MM-DD.md |
每日记忆日志 | 按需检索 |
4.2 工具系统
内置工具：
– read / write / edit — 文件操作
– exec — 命令执行
– browser — 浏览器自动化
– canvas — 画布操作
– sessions_list / sessions_history / sessions_send — 会话管理
– cron — 定时任务
工具审批：
– 危险命令（如 rm -rf）触发审批流程
– 用户可通过配置调整审批阈值
4.3 会话管理
会话存储：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
会话特性：
– 会话 ID 由 OpenClaw 生成，稳定不变
– 支持会话压缩（compaction）避免 token 爆炸
– 支持会话队列（steer/followup/collect/interrupt）
– 会话写锁保护，防止并发冲突
4.4 模型配置
模型引用格式：provider/model
{
models: {
defaults: {
model: "openai/gpt-5.5"
},
providers: [
{ id: "openai", apiKey: "sk-...", baseUrl: "https://api.openai.com/v1" },
{ id: "anthropic", apiKey: "sk-ant-...", baseUrl: "https://api.anthropic.com" }
]
}
}
模型回退：当首选模型不可用时，自动回退到备用模型。
五、与同类框架对比
| 特性 | OpenClaw | Hermes | Claude Code | Codex CLI |
|---|---|---|---|---|
| 定位 | 个人 AI 助手 | 通用 Agent | 代码助手 | 代码助手 |
| 部署 | 本地 + 自托管 | 本地 + 自托管 | 云端 | 本地 |
| 渠道 | 20+ 通讯渠道 | Telegram/QQ/Discord | IDE 插件 | 终端 |
| 多 Agent | ✅ 原生支持 | ✅ 支持 | ❌ | ❌ |
| 语音 | ✅ 唤醒词+持续 | ❌ | ❌ | ❌ |
| 画布 | ✅ A2UI | ❌ | ❌ | ❌ |
| Skills | ✅ ClawHub | ✅ 技能系统 | ❌ | ✅ |
| 开源 | ✅ MIT | ✅ | ❌ | ❌ |
| Stars | 375k+ | 172k+ | N/A | N/A |
六、总结
OpenClaw 是一个面向个人用户的全功能 AI Agent 框架，其核心设计理念是：
- 本地优先：数据不离开你的设备
- 渠道统一：一个 Gateway 管理所有通讯渠道
- Agent 隔离：多 Agent 独立人格、独立会话
- 可扩展：Skills 生态支持无限扩展
- 安全默认：DM 配对 + 沙箱 + 工具审批
对于想要拥有私有化、可定制、多渠道 AI 助手的用户来说，OpenClaw 是目前最成熟的开源方案之一。
参考链接
本文基于 OpenClaw 官方文档和源码分析整理，如有更新请以官方文档为准。
