OpenClaw 使用教程从入门到实战OpenClaw是一个开源、自托管的个人 AI 助手框架GitHub Star 350kMIT 协议它能在你自己的设备上运行通过你日常使用的消息渠道WhatsApp、Telegram、Slack、Discord、飞书、微信等 20 平台提供 AI 服务。它不是简单的聊天机器人而是一个拥有持久记忆、定时任务和自主执行能力的数字员工。吉祥物太空龙虾 Molty 官网https://openclaw.ai文档https://docs.openclaw.aiGitHubhttps://github.com/openclaw/openclaw1. 环境准备项目要求Node.js推荐 Node 24最低支持 Node 22.14操作系统macOS / Linux / WindowsWSL2 更稳定API 密钥Anthropic、OpenAI、Google 等模型提供商的 API Key可选Docker用于沙箱模式、Tailscale用于远程访问检查 Node 版本node --version # 输出应为 v24.x.x 或 v22.142. 安装与初始化方法一命令行安装推荐macOS / Linuxcurl -fsSL https://openclaw.ai/install.sh | bashWindowsPowerShelliwr -useb https://openclaw.ai/install.ps1 | iex或通过 npm/pnpm 安装npm install -g openclawlatest # 或 pnpm add -g openclawlatest方法二从源码构建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 high3. 核心架构与概念OpenClaw 采用四层架构设计可以类比为一家单人咨询公司┌─────────────────────────────────────────────────┐ │ 通信层 (Gateway) │ │ 前台接待统一路由所有消息渠道 │ ├─────────────────────────────────────────────────┤ │ 调度层 (Cron / Heartbeat) │ │ 日程表和闹钟决定什么时候干什么 │ ├─────────────────────────────────────────────────┤ │ 执行层 (Agent Loop) │ │ 顾问本人思考 → 行动 → 观察 → 判断 │ ├─────────────────────────────────────────────────┤ │ 记忆层 (Memory / Workspace) │ │ 工作笔记本SOUL.md / MEMORY.md 等文件 │ └─────────────────────────────────────────────────┘各层职责层次模块职责通信层Gateway 网关处理所有进出消息统一路由屏蔽多渠道复杂性调度层Cron / HeartbeatCron 负责固定时间执行任务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.modenon-main表示群组消息在 Docker 沙箱中运行保障安全security.dmPolicypair表示未知私信需要配对验证环境变量变量用途OPENCLAW_HOME主目录路径OPENCLAW_STATE_DIR状态数据目录OPENCLAW_CONFIG_PATH配置文件路径5. 接入消息渠道OpenClaw 支持20 消息渠道以下是常用渠道的接入方式Telegram最快上手在 Telegram 中找到BotFather创建一个 Bot获取 Token配置渠道openclaw channels add telegram # 按提示输入 Bot Token或手动编辑配置文件{ channels: { telegram: { enabled: true, botToken: 123456:ABC-DEF... } } }Slack创建 Slack App获取 Bot Token 和 App Token配置openclaw channels add slackDiscord在 Discord Developer Portal 创建 Bot获取 Token 并配置openclaw channels add discord飞书Feishuopenclaw 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 后端开发者偏好使用 FastAPIMEMORY.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 开发 - IDEVS Code - 版本管理Git7. 定时任务CronCron 是 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 } ] }关键参数说明参数说明scheduleCron 表达式如0 9 * * *表示每天 9:00sessionTarget推荐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:008. 心跳机制Heartbeat心跳是 OpenClaw 的保安巡逻机制——系统按固定频率默认 30 分钟发送心跳消息Agent 读取HEARTBEAT.md判断是否需要执行操作。配置 HEARTBEAT.md# 心跳任务清单 ## 检查项 1. 检查是否有新邮件如有则整理摘要 2. 检查监控面板是否有异常告警 3. 整理今天的对话记忆提炼关键信息存入 MEMORY.md ## 执行规则 - 无事可做时回复 HEARTBEAT_OK - 有紧急事项时主动通知用户 - 每天结束时自动整理日记工作流程系统定时发送心跳 ↓ Agent 读取 HEARTBEAT.md ↓ 有任务──→ 执行任务 → 通知用户 │ └──→ 无事可做 → 回复 HEARTBEAT_OK9. 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 --sinceyesterday --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