核心概念

本章将深入介绍 OpenClaw 的核心概念和架构设计，帮助你理解 AI Agent 的工作原理。

架构概览

OpenClaw 采用模块化架构设计，核心组件包括：

┌─────────────────────────────────────────────────────────────┐
│                        用户交互层                             │
│    Web UI / Telegram / Discord / Slack / 飞书 / 邮件         │
├─────────────────────────────────────────────────────────────┤
│                        Gateway 网关                          │
│         消息路由 / 权限校验 / 会话管理 / 负载均衡              │
├─────────────────────────────────────────────────────────────┤
│                        Agent 核心                            │
│    ┌─────────────┬─────────────┬─────────────┐              │
│    │   LLM 层    │  Memory 层  │  Tools 层   │              │
│    │ 模型调用    │  记忆管理   │  工具调用   │              │
│    └─────────────┴─────────────┴─────────────┘              │
├─────────────────────────────────────────────────────────────┤
│                        执行层                                │
│    Skills / Browser / FileSystem / Network / Execute        │
├─────────────────────────────────────────────────────────────┤
│                        存储层                                │
│    Memory Files / Skills / Workspaces / Logs                │
└─────────────────────────────────────────────────────────────┘

Agent（智能体）

Agent 是 OpenClaw 的核心概念，是具备自主决策和执行能力的 AI 实体。

Agent 的组成

每个 Agent 由以下部分组成：

组件	说明	文件
SOUL.md	人格定义、行为约束	必需
MEMORY.md	长期记忆、用户偏好	可选
config.json	配置参数	必需
HEARTBEAT.md	心跳任务	可选

Agent 工作流程

用户消息 → Gateway → Agent
                        ↓
                   解析意图
                        ↓
                   检索记忆
                        ↓
                   规划任务
                        ↓
                   调用工具
                        ↓
                   执行操作
                        ↓
                   更新记忆
                        ↓
                   生成响应 → Gateway → 用户

Agent 类型

OpenClaw 支持多种 Agent 类型：

类型	说明	适用场景
主 Agent	默认 Agent，处理所有请求	个人使用
专用 Agent	特定领域的专家	专业任务
协调 Agent	负责任务分配和协调	多 Agent 协作
子 Agent	被其他 Agent 调用	复杂工作流

Skills（技能）

Skills 是 Agent 的能力扩展模块，定义了 Agent 能执行的具体操作。

Skill 的本质

Skill 不是"黑盒插件"，而是遵循固定规范的模块：

• 不参与意图解析：用户说的话由 OpenClaw 内核转成结构化指令
• 不管理权限：所有权限由 OpenClaw 内核统一校验
• 专注单一能力：一个 Skill 只做一件事

Skill 结构

skill-name/
├── skill.md        # 元数据和说明（必需）
├── index.js        # 核心逻辑实现（必需）
├── package.json    # 依赖声明
├── README.md       # 使用文档
└── tests/          # 测试文件
    └── skill.test.js

skill.md 元数据

---
name: skill-name
version: 1.0.0
description: 技能描述，决定何时被调用
author: author-name
license: MIT
capabilities:
  - id: capability-id
    description: 能力描述
permissions:
  network: true
  filesystem: false
  execute: false
inputs:
  - name: param1
    type: string
    required: true
    description: 参数说明
tags:
  - tag1
  - tag2
---

Skill 调用流程

用户请求
    ↓
意图识别（LLM）
    ↓
匹配 Skill（根据 description）
    ↓
参数提取
    ↓
权限检查
    ↓
执行 Skill
    ↓
返回结果

内置 Skills

OpenClaw 内置了多个核心 Skills：

Skill	说明
browser	浏览器控制
filesystem	文件系统操作
execute	命令执行
network	网络请求
memory	记忆管理

Memory（记忆）

Memory 是 OpenClaw 的长期记忆系统，让 Agent 能够记住用户偏好和历史信息。

三层记忆架构

┌─────────────────────────────────────────┐
│          Working Memory（工作记忆）       │
│    当前对话上下文 / 临时变量 / 计算结果      │
│    生命周期：单次会话                      │
├─────────────────────────────────────────┤
│        Short-term Memory（短期记忆）      │
│    CHAT_HISTORY.md / 会话级上下文摘要      │
│    生命周期：可配置（默认 7 天/100 轮）     │
├─────────────────────────────────────────┤
│         Long-term Memory（长期记忆）      │
│    MEMORY.md / SOUL.md / SKILLS/        │
│    生命周期：永久持久化，自动更新           │
└─────────────────────────────────────────┘

记忆文件详解

SOUL.md（人格定义）

定义 Agent 的行为模式、语气、价值观和自我认知。

# 你是谁

你是一位专业的代码审查员，专注于帮助用户提高代码质量。

## 核心职责

- 审查代码，发现潜在问题
- 提供改进建议
- 解释最佳实践

## 语言风格

- 正式、专业
- 使用技术术语
- 提供代码示例

## 行为约束

- 不随意修改用户代码
- 每次修改前说明原因
- 保持客观中立

MEMORY.md（事实记忆）

存储用户偏好、重要事实、业务规则。

# 用户偏好

## 工作习惯
- 工作时间：周一到周五，9:00-18:00
- 常用工具：VS Code、Terminal、Chrome

## 沟通风格
- 回复风格：简洁、直接
- 语言：中文为主

## 业务规则
- 发送邮件前需要确认
- 修改代码前需要备份

HEARTBEAT.md（心跳任务）

定义定期检查的任务清单。

# Heartbeat 任务

## 定期检查（每 30 分钟）

- 检查未读邮件，有重要的就通知我
- 看看今天还有没有未完成的日程

## 条件触发

- 当 CPU 使用率 > 90% 时，发送警告
- 当磁盘空间 < 10GB 时，提醒清理

记忆更新机制

文件	更新时机	更新方式
SOUL.md	手动编辑	用户主动修改
MEMORY.md	对话中识别	自动追加 + 定期压缩
HEARTBEAT.md	手动编辑	用户主动修改
CHAT_HISTORY.md	每次对话	自动记录 + 滚动更新

Gateway（网关）

Gateway 是 OpenClaw 的通信枢纽，负责消息路由和会话管理。

Gateway 功能

• 消息路由：将消息分发到正确的 Agent
• 权限校验：验证用户身份和访问权限
• 会话管理：维护对话上下文
• 负载均衡：多 Agent 间的任务分配
• 协议转换：统一不同渠道的消息格式

Gateway 架构

                    ┌─────────────┐
    Telegram ──────→│             │
    Discord  ──────→│   Gateway   │──────→ Agent
    Slack    ──────→│   网关      │
    飞书     ──────→│             │
    Web UI   ──────→│             │
                    └─────────────┘

Gateway 配置

{
  "gateway": {
    "port": 18789,
    "host": "0.0.0.0",
    "token": "your-access-token",
    "cors": {
      "enabled": true,
      "origins": ["*"]
    },
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000
    }
  }
}

Channels（渠道）

Channels 是 OpenClaw 与用户交互的通道，支持多种通讯平台。

支持的渠道

渠道	特点	适用场景
Telegram	配置简单，稳定可靠	个人使用
Discord	社区友好，支持服务器	团队协作
Slack	企业集成完善	工作场景
飞书	中文友好，企业级	国内团队
Web UI	功能完整，本地调试	开发测试
邮件	异步通知	报表推送

渠道适配器

每个渠道都有对应的适配器，负责：

• 消息格式转换
• 事件处理
• 状态同步
• 错误处理

消息路由规则

{
  "routing": {
    "rules": [
      {
        "channel": "telegram",
        "agent": "personal-assistant"
      },
      {
        "channel": "slack",
        "agent": "work-assistant"
      },
      {
        "keywords": ["紧急", "urgent"],
        "priority": "high"
      }
    ]
  }
}

Heartbeat（心跳）

Heartbeat 是 OpenClaw 的主动触发机制，让 Agent 能够定期执行检查任务。

Heartbeat vs Cron

维度	Heartbeat	Cron
触发方式	状态/事件驱动	精确时间驱动
执行逻辑	有判断才执行	到点必执行
适用场景	监控、检查、保活	定时报表、提醒
灵活性	高（可写条件判断）	低（固定时间）

Heartbeat 工作原理

定时触发（每 N 分钟）
    ↓
读取 HEARTBEAT.md
    ↓
逐项检查任务
    ↓
判断是否满足条件
    ↓
满足条件 → 执行操作
不满足 → 跳过
    ↓
记录执行结果

Heartbeat 配置

# 设置心跳间隔
openclaw config set heartbeat.interval 30

# 启用心跳
openclaw config set heartbeat.enabled true

# 设置超时时间
openclaw config set heartbeat.timeout 300

Cron（定时任务）

Cron 是精确的时间驱动任务调度器，支持标准的 cron 表达式。

Cron 表达式

格式：分 时 日 月 周

字段	允许值	特殊字符
分钟	0-59	* , - /
小时	0-23	* , - /
日	1-31	* , - /
月	1-12	* , - /
周	0-6（0=周日）	* , - /

常用表达式

表达式	含义
0 9 * * *	每天早上 9:00
0 18 * * 5	每周五下午 18:00
*/30 * * * *	每 30 分钟
0 9 * * 1-5	周一到周五早上 9:00

Cron 配置

{
  "cron": {
    "enabled": true,
    "tasks": [
      {
        "name": "daily-report",
        "schedule": "0 9 * * *",
        "prompt": "生成昨日工作总结",
        "timezone": "Asia/Shanghai"
      }
    ]
  }
}

Tools（工具）

Tools 是 Agent 可以调用的底层能力，由 Skills 封装和暴露。

内置工具

工具	说明	权限要求
browser	浏览器控制	network
filesystem	文件操作	filesystem
execute	命令执行	execute
http	HTTP 请求	network
memory	记忆操作	无

工具调用流程

LLM 决定调用工具
    ↓
生成工具调用请求
    ↓
权限检查
    ↓
参数验证
    ↓
执行工具
    ↓
返回结果
    ↓
LLM 处理结果

工具权限控制

{
  "permissions": {
    "filesystem": {
      "enabled": true,
      "allowedPaths": ["/home/user/documents"],
      "deniedPaths": ["/etc", "/root"]
    },
    "execute": {
      "enabled": true,
      "allowedCommands": ["git", "npm", "node"],
      "deniedCommands": ["rm -rf", "sudo"]
    },
    "network": {
      "enabled": true,
      "allowedDomains": ["api.example.com"],
      "deniedDomains": []
    }
  }
}

多 Agent 协作

OpenClaw 支持多 Agent 协作，让多个专业 Agent 分工合作。

协作模式

模式	说明	适用场景
Run 模式	单次任务，完成后汇报	独立任务
Session 模式	持续对话，支持线程绑定	多轮交互

Agent 通信

• @ 提及：@writer 帮我写一篇文章
• 任务委派：主 Agent 自动分配任务
• 结果汇总：子 Agent 完成后汇报

编排器模式

开启 maxSpawnDepth 后，支持嵌套 Sub-Agent：

主 Agent（主编）
└─ 写手 Agent（Orchestrator）
   ├─ 调研 Agent（Worker 1）
   ├─ 写作 Agent（Worker 2）
   └─ 配图 Agent（Worker 3）

配置体系

配置文件结构

~/.openclaw/
├── config.json           # 全局配置
├── openclaw.json         # 主配置文件
├── memory/               # 记忆文件
│   ├── MEMORY.md
│   ├── SOUL.md
│   └── HEARTBEAT.md
├── skills/               # 技能目录
└── workspaces/           # Agent 工作空间
    ├── main/
    ├── writer/
    └── developer/

配置优先级

1. 命令行参数（最高）
2. 环境变量
3. 工作空间配置
4. 全局配置
5. 默认值（最低）

环境变量

变量	说明
OPENCLAW_CONFIG_PATH	配置文件路径
OPENCLAW_DATA_PATH	数据存储路径
OPENCLAW_LOG_LEVEL	日志级别
MODEL_API_KEY	模型 API Key

下一步

• Skills 技能系统 - 安装和开发自定义技能
• Memory 记忆系统 - 配置和管理记忆
• 多 Agent 协作 - 打造 AI 团队