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 版本：

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 等文件      │
└─────────────────────────────────────────────────┘

各层职责

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" 表示未知私信需要配对验证

环境变量

5. 接入消息渠道

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

Telegram（最快上手）

1. 1. 在 Telegram 中找到 @BotFather，创建一个 Bot，获取 Token
2. 2. 配置渠道：

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

或手动编辑配置文件：

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

Slack

1. 1. 创建 Slack App，获取 Bot Token 和 App Token
2. 2. 配置：

openclaw channels add slack

Discord

1. 1. 在 Discord Developer Portal 创建 Bot
2. 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 助手性格设定

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

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

## 技术偏好
- 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
}
]
}

关键参数说明

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>

技能类型

常用内置技能

• • 浏览器控制：网页浏览、截图、表单填写
• • 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 # 配置渠道

聊天命令

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

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

📚 更多资源

• • 官方文档：https://docs.openclaw.ai
• • GitHub：https://github.com/openclaw/openclaw
• • ClawHub 技能市场：https://openclawbase.ai
• • 中文社区教程：https://openclaw.cc
• • 中文教程 101：https://www.openclaw101.club