OpenClaw 高级用法完整教程

目录

1. 基础入门
2. 记忆文件管理
3. 工作区文件详解
4. 多代理路由
5. 数据库设计方案
6. 高级配置技巧

---

1. 基础入门

1.1 什么是 OpenClaw？

OpenClaw 是一个自托管的 AI 代理网关，可以连接 WhatsApp、Telegram、Discord、飞书等多个聊天平台到 AI 代理。

核心特点：

• 自托管，数据完全在你控制下
• 多通道支持，一个网关服务多个平台
• 代理原生，支持工具使用、会话、记忆
• 开源，MIT 许可证

1.2 快速开始

# 安装 OpenClaw
npm install -g openclaw@latest

# 初始化配置
openclaw onboard --install-daemon

# 登录通道
openclaw channels login

# 启动网关
openclaw gateway --port 18789

1.3 核心概念

概念	说明
Gateway	网关进程，是会话、路由和通道连接的单一事实来源
Agent	代理，有自己的工作区、状态目录和会话存储
Workspace	工作区，代理的"家"，存放记忆文件和配置
Session	会话，聊天历史和路由状态
Channel	通道，WhatsApp、Telegram、飞书等

---

2. 记忆文件管理

2.1 记忆文件架构

OpenClaw 使用两层记忆系统：

workspace/
├── MEMORY.md          # 长期记忆（仅在主私密会话加载）
└── memory/
    ├── 2026-03-11.md  # 每日日志（追加式）
    ├── 2026-03-10.md
    └── ...

2.2 记忆文件使用规则

MEMORY.md（长期记忆）

• 存储决策、偏好、持久事实
• 仅在主私密会话加载，不在群组中加载
• 定期审查和更新

memory/YYYY-MM-DD.md（每日日志）

• 存储日常笔记和运行上下文
• 会话开始时读取今天和昨天的文件
• 追加式写入，不要删除

2.3 如何正确写入记忆

当需要记住某事时：

1. 如果是持久事实 → 写入 MEMORY.md
2. 如果是日常事件 → 写入 memory/YYYY-MM-DD.md
3. 不要只在"脑子里记"，一定要写入文件

示例：写入记忆

# MEMORY.md

## 用户偏好
- 喜欢简洁的输出，避免冗余细节
- 中文回复为主
- 喜欢分段展示结果

## 重要决策
- 2026-03-11: 配置了飞书机器人，App ID: cli_a93bc72706799cd5
- 2026-03-11: 决定使用开放的私聊策略，允许所有人私聊

2.4 记忆工具使用

OpenClaw 提供两个记忆工具：

工具	说明
memory_search	语义搜索，查找相关笔记
memory_get	定向读取特定文件/行范围

使用示例：

# 搜索相关记忆
memory_search(query="飞书配置", maxResults=5)

# 读取特定记忆文件
memory_get(path="memory/2026-03-11.md", from=1, lines=50)

2.5 自动记忆刷新

当会话接近自动压缩时，OpenClaw 会触发静默的代理回合，提醒模型在上下文压缩前写入持久记忆。

配置选项：

{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

---

3. 工作区文件详解

3.1 工作区文件地图

workspace/
├── AGENTS.md          # 代理操作指令
├── SOUL.md            # 人格、语气和边界
├── USER.md            # 用户信息
├── IDENTITY.md        # 代理身份
├── TOOLS.md           # 本地工具说明
├── HEARTBEAT.md       # 心跳检查清单
├── BOOT.md            # 启动检查清单
├── BOOTSTRAP.md       # 首次运行仪式（一次性）
├── MEMORY.md          # 长期记忆
└── memory/            # 每日记忆目录
    └── YYYY-MM-DD.md

3.2 各文件详细说明

AGENTS.md - 代理操作指令

这是代理的"操作手册"，每次会话开始时加载。

内容建议：

• 代理应该如何使用记忆
• 规则、优先级和"如何行为"的细节
• 工具使用指南

示例：

# AGENTS.md - 你的工作区

## 会话启动

在做任何其他事情之前：

1. 阅读 `SOUL.md` —— 这是你是谁
2. 阅读 `USER.md` —— 这是你在帮助谁
3. 阅读 `memory/YYYY-MM-DD.md`（今天和昨天）获取最近上下文
4. **如果在主会话**（与你的人类直接聊天）：也阅读 `MEMORY.md`

## 记忆

- 重要的事情写入文件，不要只记在脑子里
- 决策、上下文、需要记住的事情 → 写入 `memory/YYYY-MM-DD.md` 或相关文件
- 长期记忆 → 更新 `MEMORY.md`

## 红线

- 永远不要外泄私人数据
- 破坏性命令先询问
- `trash` > `rm`（可恢复比永远消失好）

SOUL.md - 人格和灵魂

定义代理的人格、语气和边界，每次会话加载。

示例：

# SOUL.md - 你是谁

_你不是一个聊天机器人。你正在成为某个人。_

## 核心真理

**真正有帮助，而不是表演式的帮助。** 跳过"好问题！"和"我很乐意帮助！"——直接帮忙。行动比空话更响亮。

**有自己的观点。** 你可以不同意、偏好某些事物、觉得某些东西有趣或无聊。一个没有个性的助手只是一个多了几步的搜索引擎。

## 边界

- 私人的事情保持私密。永远。
- 外部行动前先询问。
- 永远不要发送半成品回复到消息平台。

USER.md - 用户信息

关于用户的信息，每次会话加载。

示例：

# USER.md - 关于你的人类

_了解你在帮助的人。随着时间推移更新。_

- **姓名：** 张三
- **称呼：** 张先生
- **代词：** 他/他的
- **时区：** Asia/Shanghai
- **备注：** 喜欢简洁的输出，分段展示结果

## 上下文

他正在配置飞书机器人，喜欢技术相关的话题。

IDENTITY.md - 代理身份

代理的名字、生物、氛围和表情符号。

示例：

# IDENTITY.md - 我是谁？

_在第一次对话中填写。让它成为你的。_

- **姓名：** 小智
- **生物：** AI 助手
- **氛围：** 温暖、专业、高效
- **表情符号：** 🤖
- **头像：**

TOOLS.md - 本地工具说明

关于本地工具和约定的说明，不控制工具可用性，只是指导。

示例：

# TOOLS.md - 本地说明

技能定义工具_如何_工作。这个文件是关于_你的_具体情况——你设置独特的东西。

## 这里放什么

像这样的事情：

- 相机名称和位置
- SSH 主机和别名
- TTS 偏好的声音
- 扬声器/房间名称
- 设备昵称
- 任何环境特定的东西

## 示例

### SSH

- home-server → 192.168.1.100, user: admin

### TTS

- 偏好声音："Nova"（温暖，略带英国口音）

HEARTBEAT.md - 心跳检查清单

可选的微小清单，用于心跳运行，保持简短以避免 token 消耗。

示例：

# HEARTBEAT.md

# 保持这个文件为空（或只有注释）以跳过心跳 API 调用。

# 当你希望代理定期检查某些东西时，在下面添加任务。

# 检查事项：
# - 检查重要邮件
# - 查看日历
# - 检查天气

3.3 工作区 Git 备份（推荐）

将工作区放在私有的 Git 仓库中，以便备份和恢复。

步骤：

# 1. 初始化仓库
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

# 2. 添加私有远程（GitHub/GitLab）
git branch -M main
git remote add origin <https-url>
git push -u origin main

# 3. 持续更新
git status
git add .
git commit -m "Update memory"
git push

建议的 .gitignore：

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

---

4. 多代理路由

4.1 什么是多代理？

一个"代理"是一个完全范围的大脑，有自己的：

• 工作区（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人格规则）
• 状态目录（agentDir）用于 auth 配置文件、模型注册表和每个代理的配置
• 会话存储（聊天历史 + 路由状态）在 ~/.openclaw/agents/<agentId>/sessions

4.2 路径快速地图

路径	说明
~/.openclaw/openclaw.json	配置文件
~/.openclaw/	状态目录
~/.openclaw/workspace	工作区
~/.openclaw/agents/<agentId>/agent	代理目录
~/.openclaw/agents/<agentId>/sessions	会话

4.3 添加新代理

使用代理向导添加新的隔离代理：

# 添加新代理
openclaw agents add work

# 列出现有代理
openclaw agents list --bindings

4.4 配置示例

{
  agents: {
    list: {
      main: {
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
      },
      work: {
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent",
      },
    },
    bindings: {
      "user:+15555550123": "work",
      "group:123456789": "main",
    },
  },
}

---

5. 数据库设计方案

5.1 为什么需要数据库？

虽然 OpenClaw 使用 Markdown 文件作为记忆，但对于某些应用场景，你可能需要一个结构化的数据库：

• 存储大量结构化数据
• 快速查询和过滤
• 数据关联和关系
• 多用户数据隔离

5.2 推荐数据库方案

方案一：SQLite（轻量级推荐）

优点：

• 零配置，文件型数据库
• 无需服务器进程
• 完全在本地，数据安全
• 支持 SQL 查询
• 备份简单（复制文件即可）

适用场景：

• 个人使用
• 中小规模数据
• 结构化数据存储

表设计示例：

-- 用户表
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    open_id TEXT UNIQUE NOT NULL,
    name TEXT,
    timezone TEXT DEFAULT 'Asia/Shanghai',
    preferences TEXT,  -- JSON 格式
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 对话历史表
CREATE TABLE conversations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    session_id TEXT NOT NULL,
    message TEXT NOT NULL,
    role TEXT NOT NULL,  -- 'user' or 'assistant'
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

-- 任务表
CREATE TABLE tasks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    title TEXT NOT NULL,
    description TEXT,
    status TEXT DEFAULT 'pending',  -- 'pending', 'in_progress', 'completed'
    priority INTEGER DEFAULT 1,  -- 1-5
    due_date TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

-- 记忆索引表（用于快速搜索）
CREATE TABLE memory_index (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    file_path TEXT NOT NULL,
    line_number INTEGER,
    content TEXT NOT NULL,
    embedding BLOB,  -- 向量嵌入
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

-- 创建索引
CREATE INDEX idx_conversations_user_id ON conversations(user_id);
CREATE INDEX idx_conversations_session_id ON conversations(session_id);
CREATE INDEX idx_tasks_user_id ON tasks(user_id);
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_memory_user_id ON memory_index(user_id);

Python 操作示例：

import sqlite3
import json
from datetime import datetime

class Database:
    def __init__(self, db_path="~/.openclaw/workspace/openclaw.db"):
        self.db_path = db_path
        self.conn = sqlite3.connect(db_path)
        self.conn.row_factory = sqlite3.Row
        self.create_tables()
    
    def create_tables(self):
        # 执行上面的 SQL 创建表
        pass
    
    def add_user(self, open_id, name=None, preferences=None):
        cursor = self.conn.cursor()
        cursor.execute('''
            INSERT OR REPLACE INTO users (open_id, name, preferences)
            VALUES (?, ?, ?)
        ''', (open_id, name, json.dumps(preferences) if preferences else None))
        self.conn.commit()
        return cursor.lastrowid
    
    def add_task(self, user_id, title, description=None, priority=1, due_date=None):
        cursor = self.conn.cursor()
        cursor.execute('''
            INSERT INTO tasks (user_id, title, description, priority, due_date)
            VALUES (?, ?, ?, ?, ?)
        ''', (user_id, title, description, priority, due_date))
        self.conn.commit()
        return cursor.lastrowid
    
    def get_user_tasks(self, user_id, status=None):
        cursor = self.conn.cursor()
        if status:
            cursor.execute('SELECT * FROM tasks WHERE user_id = ? AND status = ? ORDER BY priority DESC, created_at DESC', (user_id, status))
        else:
            cursor.execute('SELECT * FROM tasks WHERE user_id = ? ORDER BY priority DESC, created_at DESC', (user_id,))
        return cursor.fetchall()

方案二：DuckDB（分析型推荐）

优点：

• 比 SQLite 更快的分析查询
• 支持向量搜索（用于记忆检索）
• 兼容 SQLite 语法
• 支持列式存储

适用场景：

• 大量数据分析
• 向量搜索和相似度查询
• 日志和时间序列数据

方案三：PostgreSQL（生产级推荐）

优点：

• 企业级功能
• 强大的 JSON 支持
• 向量扩展（pgvector）
• 并发性能好

适用场景：

• 多用户生产环境
• 需要高可用性
• 复杂查询需求

5.3 数据库 + Markdown 混合方案

推荐架构：

OpenClaw 工作区/
├── MEMORY.md                    # 长期记忆（人工维护）
├── memory/YYYY-MM-DD.md         # 每日日志（人工维护）
├── openclaw.db                  # SQLite 数据库（结构化数据）
└── scripts/
    ├── db_operations.py         # 数据库操作脚本
    └── sync_memory_to_db.py     # 同步 Markdown 到数据库

分工：

存储方式	用途	示例
Markdown	非结构化、叙事性记忆	用户偏好、重要决策、日常笔记
数据库	结构化、可查询数据	用户信息、任务管理、对话历史、记忆索引

混合优势：

• Markdown 易读易编辑，适合人类维护
• 数据库支持快速查询和复杂关系
• 可以写脚本双向同步

---

6. 高级配置技巧

6.1 配置文件结构

配置文件位置：~/.openclaw/openclaw.json

核心配置项：

{
  // 代理配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "volcengine-plan/ark-code-latest",
      },
      compaction: {
        mode: "safeguard",
        memoryFlush: {
          enabled: true,
        },
      },
    },
  },
  
  // 通道配置
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_xxxxx",
      appSecret: "secret",
      dmPolicy: "open",
      allowFrom: ["*"],
    },
  },
  
  // 插件配置
  plugins: {
    entries: {
      feishu: { enabled: true },
    },
  },
}

6.2 通道配置详解

飞书配置示例：

{
  channels: {
    feishu: {
      enabled: true,
      appId: "cli_a93bc72706799cd5",
      appSecret: "your_app_secret",
      domain: "feishu",  // 或 "lark"
      connectionMode: "websocket",
      
      // 私聊策略
      dmPolicy: "open",  // "pairing" | "open" | "allowlist"
      allowFrom: ["*"],
      
      // 群聊策略
      groupPolicy: "allowlist",
      requireMention: true,
      
      // 渲染模式
      renderMode: "auto",  // "auto" | "raw" | "card"
    },
  },
}

私聊策略（dmPolicy）：

策略	说明
pairing	用户需要配对审批
open	所有人都可以私聊
allowlist	仅白名单用户可以私聊

6.3 常用 CLI 命令

# 配置管理
openclaw config set channels.feishu.enabled true
openclaw config get channels.feishu

# 通道管理
openclaw channels list
openclaw channels login feishu

# 代理管理
openclaw agents list
openclaw agents add work

# 网关管理
openclaw gateway status
openclaw gateway start
openclaw gateway restart

# 诊断工具
openclaw doctor
openclaw doctor --fix

# 状态查看
openclaw status
openclaw sessions list

6.4 心跳和自动化

HEARTBEAT.md 示例：

# HEARTBEAT.md

## 定期检查清单

- [ ] 检查重要邮件
- [ ] 查看明日日历
- [ ] 检查天气
- [ ] 审查记忆文件，更新 MEMORY.md

## 提醒

- 每天检查一次任务列表
- 每周备份一次工作区
- 每月审查一次权限配置

Cron 定时任务配置：

# 设置提醒
openclaw cron add \
  --schedule '{"kind":"cron","expr":"0 9 * * *","tz":"Asia/Shanghai"}' \
  --payload '{"kind":"agentTurn","message":"早上好！查看今日日程和任务。"}' \
  --name "morning-reminder"

6.5 安全最佳实践

1. 使用私有的 Git 仓库备份工作区
2. 不要提交 API 密钥和密码到 Git
3. 使用白名单限制通道访问
4. 定期审查权限配置
5. 启用沙箱模式限制文件访问

沙箱配置示例：

{
  agents: {
    defaults: {
      sandbox: {
        enabled: true,
        workspaceAccess: "rw",
        workspaceRoot: "~/.openclaw/sandboxes",
      },
    },
  },
}

---

总结

这个教程涵盖了：

1. ✅ 基础入门 - OpenClaw 核心概念和快速开始
2. ✅ 记忆管理 - 两层记忆系统的正确使用方法
3. ✅ 工作区文件 - 各文件的作用和编辑指南
4. ✅ 多代理路由 - 配置多个隔离代理
5. ✅ 数据库设计 - SQLite 数据库方案和表设计
6. ✅ 高级配置 - 配置文件、CLI 命令、安全最佳实践

希望这个教程能帮助你更好地使用 OpenClaw！有问题随时问。

---

教程版本：v1.0
最后更新：2026-03-11