文档中心
全面的 OpenClaw 开发和使用文档 (v0.8.0)
核心概念
🌐 网关 (Gateway)
OpenClaw 的核心长驻进程，管理所有聊天渠道连接、智能体调度、会话管理和服务。 统一对外提供 WebSocket API 和 HTTP 服务，默认运行在 127.0.0.1:18789。
🤖 智能体 (Agent)
运行时的AI实例，基于pi-mono runtime，拥有工具调用、记忆、会话管理能力。 支持多智能体隔离，不同工作区和用户拥有独立的智能体实例。
💬 会话 (Session)
用户与智能体之间的交互上下文，包含历史消息、状态信息和上下文数据。 单聊会话默认合并到主会话，群聊会话自动隔离。
🛠️ 技能 (Skill)
智能体的能力单元，通过SKILL.md文件定义，包含触发条件、操作指南和工具调用逻辑。 无需代码即可扩展智能体能力，支持热加载。
🔌 插件 (Plugin)
扩展核心功能的Node.js模块，可以新增聊天渠道、工具、模型支持等。 支持动态加载/卸载，无需重启网关。
📱 节点 (Node)
连接到网关的设备（macOS/iOS/Android/服务器），提供设备能力（摄像头、屏幕录制、定位、短信等）。 通过WebSocket安全连接，支持设备权限管理。
🧠 记忆 (Memory)
智能体的信息存储系统，分为短期记忆（会话上下文）、长期记忆（MEMORY.md/每日笔记） 和向量记忆（语义检索），支持持久化存储和跨会话继承。
工作区结构
~/.openclaw/ (工作区根目录) ├── openclaw.json # 核心配置文件 ├── workspace/ # 智能体工作区 │ ├── AGENTS.md # 智能体运行规则 │ ├── SOUL.md # 智能体人格设定 │ ├── IDENTITY.md # 智能体身份信息 │ ├── USER.md # 用户信息配置 │ ├── MEMORY.md # 长期记忆存储 │ ├── TOOLS.md # 工具配置说明 │ ├── HEARTBEAT.md # 心跳任务配置 │ ├── memory/ # 每日笔记目录 (YYYY-MM-DD.md) │ ├── skills/ # 自定义技能目录 │ └── plugins/ # 自定义插件目录 ├── logs/ # 日志文件目录 ├── state/ # 运行时状态存储 └── extensions/ # 扩展安装目录
工作区是智能体的唯一工作目录，所有文件操作、工具执行都在此目录下进行。 使用 openclaw setup 命令可以快速初始化工作区结构和默认配置文件。
技能开发快速指南
什么是技能？
技能是扩展智能体能力的最小单元，通过简单的Markdown文件即可定义，无需编写复杂代码。 每个技能包含触发条件、操作指南和可选的工具调用逻辑，支持热加载，修改后立即生效。
5分钟创建第一个技能
1. 创建技能目录
mkdir -p ~/.openclaw/workspace/skills/weather-query2. 编写 SKILL.md
---
name: weather_query
description: 查询全球城市天气信息
triggers: ["天气", "气温", "降水", "weather"]
---
# 天气查询技能
当用户询问天气相关问题时：
1. 首先提取城市名称和时间范围
2. 使用 web_search 工具查询最新天气数据
3. 整理成清晰的格式回复，包含温度、降水概率、风力等信息
4. 极端天气情况给出出行建议3. 加载技能
向智能体发送"刷新技能"指令，或重启网关，新技能会自动加载。
# 测试技能\nopenclaw agent --message "北京今天天气怎么样？"技能开发最佳实践
- • 明确触发条件：在frontmatter中定义清晰的触发关键词，避免误触发
- • 简洁指令：用清晰的步骤描述技能逻辑，避免冗余说明
- • 安全优先：涉及命令执行的技能要做好输入校验，防止注入攻击
- • 可测试：提供测试用例，确保技能行为符合预期
- • 共享贡献：优秀的技能可以提交到 ClawHub 社区分享
插件开发入门
提示： 插件用于扩展核心功能，需要Node.js开发能力。如果只是扩展智能体能力，优先使用技能系统。
插件结构
my-plugin/ ├── package.json # 插件元信息和依赖 ├── index.ts # 插件入口文件 ├── README.md # 插件说明文档 └── manifest.json # 插件清单（能力声明）
插件可以扩展多种能力：新增聊天渠道、新增工具、扩展模型支持、添加Web路由等。
开发步骤
1. 初始化插件项目
openclaw plugin create my-plugin2. 实现插件逻辑
// index.ts
import { Plugin } from '@openclaw/types';
export default {
name: 'my-plugin',
version: '1.0.0',
async activate(context) {
// 注册新工具
context.registerTool('my-tool', {
description: '自定义工具',
handler: async (params) => {
return { result: 'Hello from plugin!' };
}
});
}
} as Plugin;3. 安装插件
openclaw plugin install ./my-pluginAPI 参考
WebSocket API
网关默认在 127.0.0.1:18789 提供WebSocket API，支持双向通信。
连接示例
const ws = new WebSocket('ws://127.0.0.1:18789/ws');核心接口
| 方法 | 描述 |
|---|---|
agent.run | 运行智能体任务 |
message.send | 发送消息到指定渠道 |
gateway.status | 获取网关运行状态 |
skills.list | 列出已安装的技能 |