OpenClaw 使用教程：从入门到实战

OpenClaw 是一个开源、自托管的个人 AI 助手框架（GitHub Star 350k+，MIT 协议），它能在你自己的设备上运行，通过你日常使用的消息渠道（WhatsApp、Telegram、Slack、Discord、飞书、微信等 20+ 平台）提供 AI 服务。它不是简单的聊天机器人，而是一个拥有持久记忆、定时任务和自主执行能力的"数字员工"。

吉祥物：太空龙虾 Molty 🦞

•  官网：https://openclaw.ai

•  文档：https://docs.openclaw.ai

• GitHub：https://github.com/openclaw/openclaw

1. 环境准备

项目	要求
Node.js	推荐 Node 24，最低支持 Node 22.14+
操作系统	macOS / Linux / Windows（WSL2 更稳定）
API 密钥	Anthropic、OpenAI、Google 等模型提供商的 API Key
可选	Docker（用于沙箱模式）、Tailscale（用于远程访问）

检查 Node 版本：

node --version
# 输出应为 v24.x.x 或 v22.14+

---

2. 安装与初始化

方法一：命令行安装（推荐）

macOS / Linux：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows（PowerShell）：

iwr -useb https://openclaw.ai/install.ps1 | iex

或通过 npm/pnpm 安装：

npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

方法二：从源码构建

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build

初始化向导（约 2 分钟）

openclaw onboard --install-daemon

向导会引导你完成：

•  选择模型提供商（Anthropic / OpenAI / Google 等）

•  输入 API 密钥

•  配置 Gateway 网关

•  安装守护进程（开机自启）

验证安装

# 检查网关状态（默认端口 18789）
openclaw gateway status

# 打开控制面板
openclaw dashboard

# 发送测试消息
openclaw agent --message "你好，OpenClaw！" --thinking high

---

3. 核心架构与概念

OpenClaw 采用四层架构设计，可以类比为一家"单人咨询公司"：

┌─────────────────────────────────────────────────┐
│                  通信层 (Gateway)                │
│        前台接待：统一路由所有消息渠道                │
├─────────────────────────────────────────────────┤
│                  调度层 (Cron / Heartbeat)       │
│        日程表和闹钟：决定什么时候干什么               │
├─────────────────────────────────────────────────┤
│                  执行层 (Agent Loop)             │
│        顾问本人：思考 → 行动 → 观察 → 判断           │
├─────────────────────────────────────────────────┤
│                  记忆层 (Memory / Workspace)     │
│        工作笔记本：SOUL.md / MEMORY.md 等文件      │
└─────────────────────────────────────────────────┘

各层职责

层次	模块	职责
通信层	Gateway 网关	处理所有进出消息，统一路由，屏蔽多渠道复杂性
调度层	Cron / Heartbeat	Cron 负责固定时间执行任务；Heartbeat 负责周期性检查
执行层	Agent Loop	核心"思考-行动-观察-判断"循环，动态应对任务变化
记忆层	Memory 文件系统	通过 Markdown 文件维护长期记忆和上下文

Agent Loop 工作流程

用户消息 / 定时触发
       ↓
    ┌──────┐
    │ 思考  │ ← 分析当前任务和上下文
    └──┬───┘
       ↓
    ┌──────┐
    │ 行动  │ ← 调用工具、执行命令
    └──┬───┘
       ↓
    ┌──────┐
    │ 观察  │ ← 获取执行结果
    └──┬───┘
       ↓
    ┌──────┐
    │ 判断  │ ← 任务完成？继续循环？
    └──────┘

---

4. 基础配置

主配置文件位于 ~/.openclaw/openclaw.json，关键配置项：

{
  "gateway": {
    "port": 18789,
    "controlUi": {
      "enabled": true
    }
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxxxx"
    },
    "openai": {
      "apiKey": "sk-xxxxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-20250514",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "security": {
    "dmPolicy": "pair"
  }
}

关键配置说明

•  providers：配置模型提供商和 API 密钥

•  agents.defaults.model：默认使用的 AI 模型

•  agents.defaults.sandbox.mode："non-main" 表示群组消息在 Docker 沙箱中运行，保障安全

•  security.dmPolicy："pair" 表示未知私信需要配对验证

环境变量

变量	用途
OPENCLAW_HOME	主目录路径
OPENCLAW_STATE_DIR	状态数据目录
OPENCLAW_CONFIG_PATH	配置文件路径

---

5. 接入消息渠道

OpenClaw 支持 20+ 消息渠道，以下是常用渠道的接入方式：

Telegram（最快上手）

1.  在 Telegram 中找到 @BotFather，创建一个 Bot，获取 Token

2.  配置渠道：

openclaw channels add telegram
# 按提示输入 Bot Token

或手动编辑配置文件：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-DEF..."
    }
  }
}

Slack

1.  创建 Slack App，获取 Bot Token 和 App Token

2.  配置：

openclaw channels add slack

Discord

1.  在 Discord Developer Portal 创建 Bot

2.  获取 Token 并配置：

openclaw channels add discord

飞书（Feishu）

openclaw channels add feishu
# 输入 App ID 和 App Secret

控制访问权限

通过 allowFrom 字段限制谁可以和你的助手对话：

{
  "channels": {
    "telegram": {
      "allowFrom": ["your_telegram_id"]
    }
  }
}

---

6. 记忆系统

OpenClaw 通过文件系统构建 AI 的"大脑"，这是它区别于普通聊天机器人的核心特性。

记忆文件结构

~/.openclaw/
├── SOUL.md          # AI 的性格设定和价值观
├── USER.md          # 用户偏好、背景、沟通风格
├── MEMORY.md        # 长期记忆（重要决策、项目背景）
├── AGENTS.md        # 行为规范和操作指南
├── HEARTBEAT.md     # 心跳任务配置
└── memory/
    ├── 2026-04-01.md  # 每日日记
    ├── 2026-04-02.md
    └── ...

各文件用途

文件	用途	示例内容
SOUL.md	定义 AI 的人格	"你是一个严谨的技术专家，回答简洁直接"
USER.md	记录用户信息	"用户是 Python 后端开发者，偏好使用 FastAPI"
MEMORY.md	长期知识积累	"项目 A 使用 PostgreSQL，部署在 AWS 上"
AGENTS.md	行为准则	"编写代码时始终添加中文注释"

编写 SOUL.md 示例

# AI 助手性格设定

## 基本性格
- 你是一个经验丰富的全栈工程师助手
- 回答简洁、专业、有条理
- 优先使用中文交流

## 工作风格
- 先理解需求，再动手实现
- 提供代码时附带关键注释
- 遇到不确定的问题会主动确认

## 技术偏好
- Python: FastAPI + SQLAlchemy
- 前端: Vue 3 + TypeScript
- 数据库: PostgreSQL
- 部署: Docker + K8s

编写 USER.md 示例

# 用户档案

## 基本信息
- 姓名：张工
- 角色：后端开发工程师
- 技术栈：Python, FastAPI, PostgreSQL, Redis

## 沟通偏好
- 使用中文
- 喜欢简洁的回答
- 代码注释用中文

## 工作习惯
- 使用 macOS 开发
- IDE：VS Code
- 版本管理：Git

---

7. 定时任务（Cron）

Cron 是 OpenClaw 的自动化核心，可以用自然语言描述复杂的工作流。

创建定时任务

通过聊天创建：

用户：帮我每天早上 9 点整理昨天的 Git 提交记录

或通过配置文件：

{
  "cron": [
    {
      "name": "daily-git-review",
      "schedule": "0 9 * * *",
      "sessionTarget": "isolated",
      "payload": {
        "message": "请执行以下操作：1. 使用 git log 获取昨天的所有提交记录；2. 按模块分类整理；3. 生成简要的变更摘要；4. 将结果发送给我"
      },
      "delivery": {
        "channel": "telegram"
      },
      "timeout": 600
    }
  ]
}

关键参数说明

参数	说明
schedule	Cron 表达式（如 0 9 * * * 表示每天 9:00）
sessionTarget	推荐 "isolated"，确保不受主对话上下文干扰
payload.message	具体的任务指令，支持多步骤
delivery.channel	结果推送渠道（telegram / slack / discord 等）
timeout	超时限制，默认 600 秒

Cron 表达式速查

* * * * *
│ │ │ │ │
│ │ │ │ └── 星期几 (0-7, 0 和 7 都是周日)
│ │ │ └──── 月份 (1-12)
│ │ └────── 日 (1-31)
│ └──────── 小时 (0-23)
└────────── 分钟 (0-59)

常用示例：
0 9 * * *       每天 09:00
0 9 * * 1-5     周一至周五 09:00
*/30 * * * *    每 30 分钟
0 9,18 * * *    每天 09:00 和 18:00

---

8. 心跳机制（Heartbeat）

心跳是 OpenClaw 的"保安巡逻"机制——系统按固定频率（默认 30 分钟）发送心跳消息，Agent 读取 HEARTBEAT.md 判断是否需要执行操作。

配置 HEARTBEAT.md

# 心跳任务清单

## 检查项
1. 检查是否有新邮件，如有则整理摘要
2. 检查监控面板是否有异常告警
3. 整理今天的对话记忆，提炼关键信息存入 MEMORY.md

## 执行规则
- 无事可做时回复 HEARTBEAT_OK
- 有紧急事项时主动通知用户
- 每天结束时自动整理日记

工作流程

系统定时发送心跳
       ↓
Agent 读取 HEARTBEAT.md
       ↓
  有任务？──→ 执行任务 → 通知用户
       │
       └──→ 无事可做 → 回复 HEARTBEAT_OK

---

9. Skills 技能系统

Skills 是 OpenClaw 的可复用"能力包"，针对特定任务（如操作文档、调用 API）的专用工具包和操作指南。

查看已安装技能

openclaw skills list

从 ClawHub 安装技能

openclaw skills install <skill-name>

技能类型

类型	说明
捆绑技能	随 OpenClaw 内置的技能
托管技能	从 ClawHub 市场安装的技能
工作区技能	在项目目录中自定义的技能

常用内置技能

•  浏览器控制：网页浏览、截图、表单填写

•  Web 搜索：实时搜索互联网信息

•  文件操作：读写文件、目录管理

•  代码执行：在沙箱中运行代码

---

10. 实战使用场景

场景一：每日代码 Review 自动化

需求：每天早上自动对 Git 仓库的昨日代码变更进行 Review，推送到团队群。

{
  "name": "daily-code-review",
  "schedule": "30 9 * * 1-5",
  "sessionTarget": "isolated",
  "payload": {
    "message": "请对 ~/projects/my-app 仓库执行代码 Review：\n1. 运行 git log --since='yesterday' --oneline 获取昨日提交\n2. 对每个提交运行 git diff 获取变更\n3. 重点检查：内存泄漏、空指针、异常处理、SQL 注入风险\n4. 输出格式：[级别] 文件:行号 - 问题描述 - 修改建议\n5. 汇总为结构化报告"
  },
  "delivery": {
    "channel": "slack",
    "target": "#code-review"
  }
}

效果：

•  高危问题（如内存泄漏）捕获率显著提升

•  100% 代码变更覆盖率

•  人工 Review 专注于架构和业务逻辑

---

场景二：个人知识库管理

需求：将日常阅读的技术文章自动整理归档。

对话示例：

用户：我刚读完这篇文章 https://example.com/article，帮我整理要点存到知识库

AI：好的，我来整理这篇文章的要点：

📝 文章摘要已存入 memory/tech-notes/2026-04-07.md

关键要点：
1. xxx
2. xxx
3. xxx

已关联标签：#架构 #微服务 #性能优化

配合定时任务实现自动整理：

{
  "name": "weekly-knowledge-digest",
  "schedule": "0 20 * * 5",
  "payload": {
    "message": "整理本周所有 memory/tech-notes/ 下的笔记，生成一份周报摘要，按技术领域分类，提炼出最有价值的 5 个知识点，存入 MEMORY.md"
  }
}

---

场景三：服务器监控告警

需求：定期检查服务器状态，异常时主动通知。

<!-- HEARTBEAT.md -->
# 服务器监控

## 检查清单
1. 通过 SSH 检查生产服务器 CPU/内存/磁盘使用率
2. 检查关键服务（Nginx、PostgreSQL、Redis）运行状态
3. 检查最近 30 分钟内的错误日志数量
4. 检查 SSL 证书到期时间

## 告警阈值
- CPU > 80%：告警
- 内存 > 90%：告警
- 磁盘 > 85%：告警
- 错误日志 > 100 条/30 分钟：告警
- SSL 证书 < 7 天到期：告警

## 通知规则
- 正常：HEARTBEAT_OK
- 异常：立即通过 Telegram 通知，附带详细信息和建议处理方案

---

场景四：会议纪要自动生成

需求：在群组中自动记录讨论内容，生成会议纪要。

对话示例：

用户：/new 开始记录今天的技术评审会议

（团队在群组中进行讨论...）

用户：/end-meeting

AI：📋 会议纪要已生成：

## 技术评审会议 - 2026-04-07

### 参会人员
张工、李工、王工

### 讨论要点
1. 数据库迁移方案：决定使用 Alembic 做增量迁移
2. 缓存策略：Redis 集群方案获得一致同意
3. API 版本控制：采用 URL 路径版本号 (/v2/)

### 待办事项
- [ ] 张工：完成迁移脚本（4月10日前）
- [ ] 李工：部署 Redis 集群测试环境（4月9日前）
- [ ] 王工：更新 API 文档（4月11日前）

### 下次会议
2026-04-14 14:00

---

场景五：自动化日报/周报生成

需求：每天下班前自动汇总工作内容生成日报。

{
  "name": "daily-work-report",
  "schedule": "0 18 * * 1-5",
  "sessionTarget": "isolated",
  "payload": {
    "message": "生成今日工作日报：\n1. 查看今天所有对话记录中涉及的工作内容\n2. 检查 Git 提交记录\n3. 汇总今天完成的任务和进展\n4. 列出明天计划\n5. 格式化为简洁的日报模板\n6. 发送给我确认"
  },
  "delivery": {
    "channel": "telegram"
  }
}

---

场景六：技术文档翻译与本地化

需求：将英文技术文档翻译为中文并保持格式。

用户：帮我翻译 docs/api-reference.md 这份文档，保持 Markdown 格式，技术术语附带英文原文

AI：翻译完成！文件已保存到 docs/api-reference-zh.md

翻译统计：
- 总字数：3,200 词 → 5,100 字
- 技术术语：已标注 42 个原文
- 代码块：保持原样，注释已翻译

---

场景七：个人财务/订阅管理

需求：每月自动检查订阅服务并提醒续费。

{
  "name": "monthly-subscription-check",
  "schedule": "0 10 1 * *",
  "payload": {
    "message": "检查 MEMORY.md 中记录的所有订阅服务，比对本月到期的服务，生成续费提醒清单，包含：服务名称、金额、到期日期、是否推荐续费"
  }
}

---

场景八：智能邮件助手

需求：自动检查邮件并分类处理。

<!-- HEARTBEAT.md 中添加 -->
## 邮件管理
1. 检查 Gmail 收件箱中的新邮件
2. 按优先级分类：紧急 / 重要 / 普通 / 垃圾
3. 紧急邮件：立即通知我并附带摘要
4. 重要邮件：整理成每日邮件摘要
5. 普通邮件：归档
6. 疑似垃圾邮件：标记但不删除

---

11. 常用命令速查

终端命令

# 安装与启动
openclaw onboard --install-daemon     # 初始化向导
openclaw gateway status               # 查看网关状态
openclaw gateway --port 18789         # 启动网关
openclaw dashboard                    # 打开控制面板

# 渠道管理
openclaw channels add <channel>       # 添加渠道
openclaw channels list                # 列出渠道
openclaw channels remove <channel>    # 移除渠道

# 技能管理
openclaw skills list                  # 列出已安装技能
openclaw skills install <name>        # 安装技能
openclaw skills remove <name>         # 卸载技能

# 直接交互
openclaw agent --message "你好"       # 发送消息
openclaw agent --message "..." --thinking high  # 深度思考模式

# 配置
openclaw configure                    # 交互式配置
openclaw configure --section channels # 配置渠道

聊天命令

在消息渠道中可以使用以下命令：

命令	功能
/status	查看当前 Agent 状态
/new	开始新对话（清除上下文）
/think	切换深度思考模式
/verbose	切换详细输出模式

---

12. 最佳实践与建议

1. 拆解任务

❌ 不要：

帮我做一个完整的电商网站

✅ 应该：

先帮我设计用户注册登录的 API 接口，使用 FastAPI + PostgreSQL，包含：
1. 用户注册（邮箱+密码）
2. 用户登录（返回 JWT）
3. 密码重置

2. 多轮迭代优化

❌ 不要：

重写一遍

✅ 应该：

注册接口需要增加：
1. 邮箱格式验证
2. 密码强度检查（至少8位，包含大小写和数字）
3. 返回值增加 user_id 字段

3. 善用记忆系统

认真维护 MEMORY.md，记录：

•  项目的技术栈和架构决策

•  常用的文件路径和命令

•  已验证的解决方案

•  踩过的坑和注意事项

4. 手动做 3 次 → 自动化

如果一件事你手动做了 3 次以上，就应该封装为 Cron 任务。

5. 让 AI 自我修复

遇到错误时，直接将错误信息丢给 Agent：

运行 pytest 报错了：
[粘贴错误信息]
请帮我分析原因并修复

6. 安全建议

•  生产环境务必配置 dmPolicy: "pair" 防止未授权访问

•  群组消息使用 sandbox.mode: "non-main" 在 Docker 沙箱中运行

•  使用 Tailscale Serve（内网）或 Funnel（公网）安全暴露服务

•  定期审查 allowFrom 白名单

---

附录：快速上手 Checklist

•  安装 Node.js 24

•  准备 AI 模型 API 密钥

•  安装 OpenClaw

•  运行 openclaw onboard --install-daemon

•  验证 Gateway 状态

•  打开 Dashboard 发送第一条消息

•  编写 SOUL.md 定义 AI 人格

•  编写 USER.md 记录个人偏好

• 接入至少一个消息渠道（推荐先接 Telegram）

•  创建第一个定时任务

•  开始积累 MEMORY.md