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

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. 在 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 助手性格设定 ## 基本性格 - 你是一个经验丰富的全栈工程师助手 - 回答简洁、专业、有条理 - 优先使用中文交流 ## 工作风格 - 先理解需求，再动手实现 - 提供代码时附带关键注释 - 遇到不确定的问题会主动确认 ## 技术偏好 - 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