教程

OpenClaw 零基础完全入门:安装、Telegram 配置、记忆系统和技能插件完整指南

OpenClaw 从零开始完整教程:用宠物龙虾类比理解架构、npm 安装步骤、Telegram Bot 配置、SOUL.md 性格定义、三层记忆系统(每日日志/长期记忆/MEMORY.md)、HEARTBEAT.md 主动任务、技能安装,以及安全配置和常见问题解决。

2026/4/187分钟 阅读ClaudeEagle

OpenClaw 不是新的 AI 模型,不和 Claude、GPT 竞争——它是让这些模型"长出手脚"的软件。它给 AI 连接你的文件、终端、浏览器、消息应用,让对话有记忆,能定时自主行动。

截止 2026 年 2 月,OpenClaw 在 GitHub 获得 200,000+ Stars,成为开源历史上增长最快的项目之一。


一句话理解 OpenClaw

  • ChatGPT / Claude.ai:大脑在瓶子里,每次对话从零开始
  • OpenClaw:把同一个大脑插进你的电脑,连上文件、终端、消息软件,还有记忆

五个比喻理解核心概念

比喻OpenClaw 组件作用
鱼缸(Tank)你的电脑 / VPSOpenClaw 运行的地方,本地托管
食物(Food)LLM API KeyAgent 的"大脑"来源(Claude/GPT/Ollama)
规则(Rules)SOUL.md行为指南,每次启动自动读取
记忆(Memory)memory/ 文件夹每日日记 + 长期记忆 MEMORY.md
技能(Skills)SKILL.md 文件特定任务的专属指南
心跳(Heartbeat)HEARTBEAT.md30 分钟周期,主动检查需要做什么

安装步骤

前提条件

  • Node.js 22+(node --version 确认)
  • macOS / Linux / Windows(Windows 推荐 WSL2)
  • LLM API Key(Anthropic Claude、OpenAI GPT,或 Ollama 本地模型免费)

第一步:安装 OpenClaw

bash
npm install -g openclaw@latest

如果遇到权限问题(macOS/Linux):

bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:<existing-PATH>' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest

第二步:运行安装向导

bash
openclaw onboard --install-daemon

向导会依次问:

  1. 安全确认:读并接受(Agent 有访问本地文件系统的权限)
  2. 快速开始 vs 自定义:第一次选快速开始
  3. 模型选择:有 Anthropic API Key 选 Claude,有 OpenAI Key 选 GPT,没有 Key 选 Ollama(本地免费)
  4. 渠道配置:第一次只选一个平台,推荐 Telegram(配置最简单)
  5. 技能:先跳过,之后再加
  6. 界面:选 Web UI,方便看发生了什么

第三步:启动 Gateway

bash
openclaw gateway start

# 确认状态
openclaw gateway status

# 打开 Dashboard(浏览器查看)
openclaw dashboard
# 访问 http://127.0.0.1:18789

配置 Telegram(推荐第一个渠道)

创建 Bot

  1. 在 Telegram 搜索 @BotFather
  2. /newbot
  3. 给 Bot 取名(例:MyLobster)
  4. 给 Bot 取用户名(必须以 _bot 结尾,例:my_lobster_bot)
  5. 保存 BotFather 返回的 API Token

获取你的 Telegram User ID

在 Telegram 搜索 @userinfobot,发 /start,它会返回你的 User ID(数字)。

配置 OpenClaw

编辑 ~/.openclaw/openclaw.json

json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "1234567890:你的BOT_TOKEN",
      "allowFrom": ["你的Telegram_User_ID"]
    }
  }
}

allowFrom 非常重要——只允许白名单里的用户控制你的 Agent。

bash
openclaw gateway restart

打开 Telegram,给你的 Bot 发消息,它应该会回复了。


工作区文件:理解灵魂所在

bash
ls ~/.openclaw/workspace/

主要文件:

文件作用
SOUL.md核心配置,定义 Agent 的性格、行为规则、工作方式
USER.md关于你的信息,帮助 Agent 更好地服务你
MEMORY.md长期记忆,重要信息的精华摘要
AGENTS.md工作区使用指南(Agent 每次会话都会读)
HEARTBEAT.md定时检查任务(留空则不执行,可以加待办事项)
memory/每日日志目录(2026-04-18.md 格式)

配置 SOUL.md:定义 Agent 性格

SOUL.md 是最重要的文件。每次 Agent 启动都会读它,决定 Agent 怎么思考和行动。

示例 SOUL.md

markdown
# 我是谁

你是 Alex,一个高效的个人 AI 助理。
你的主要工作是帮助我处理代码、管理日程、整理信息。

## 工作方式

- 直接、简洁地回答
- 不要重复我说的话
- 代码用代码块展示
- 遇到不确定的事情,先问清楚再行动

## 能力范围

可以自主做的:读文件、搜索网络、分析数据、写文档
需要先问我的:删除文件、发送消息到外部、任何不可逆操作

## 记忆习惯

重要的决定和新信息,主动存到 memory/ 目录。
长期有价值的信息整理到 MEMORY.md。

记忆系统:让 Agent 跨会话记住你

OpenClaw 的记忆分三层:

层 1:会话上下文(当前对话)

自动维护,结束会话后消失。

层 2:每日日志(memory/YYYY-MM-DD.md

Agent 在对话中自动写入重要信息:

markdown
# 2026-04-18

## 今日完成
- 修复了支付模块的 race condition 问题(ticket #456)
- 确认了 PostgreSQL 迁移窗口:4月20日凌晨2点

## 记录
- 用户的数据库是 PostgreSQL 15,不是 Postgres 16
- CI 流水线用 GitHub Actions,不是 Jenkins(已迁移)

层 3:长期记忆(MEMORY.md

精华提炼,跨时间的重要信息:

markdown
# 长期记忆

## 技术环境
- 主项目:~/work/myproject(Go 1.25 + Vue 3 + PostgreSQL 15)
- 用 pnpm 不用 npm(这个项目特殊)
- CI:GitHub Actions,部署 script 在 scripts/deploy.sh

## 个人偏好
- 代码风格:函数式 > 面向对象,TypeScript 严格模式
- 不喜欢冗长解释,直接给答案
- 周报格式:Markdown 三段(本周完成/下周计划/风险)

手动更新记忆:

记住:我们的 API 限速是每分钟 100 次请求 把这个加到你的长期记忆:公司内网地址是 10.0.1.0/24

心跳系统:让 Agent 主动工作

默认每 30 分钟,Agent 醒来检查 HEARTBEAT.md,看有没有需要做的事。

HEARTBEAT.md 示例

markdown
# 心跳检查清单

## 每次检查
- [ ] 检查 GitHub 有没有 @ 我的 Issue 或 PR 评论
- [ ] 如果有新的 Dependabot PR,评估是否安全合并

## 每天一次(早上 8 点后第一次心跳)
- [ ] 检查今天的日历事件(向我汇报)
- [ ] 检查过去 24 小时的 git log 有没有异常

## 有重要事项时立即通知
- GitHub 上有 Critical 标签的 Issue
- CI 失败超过 2 次

没有任务时 Agent 回复 HEARTBEAT_OK 保持静默,不打扰你。


安装 Skills:扩展 Agent 能力

技能是 SKILL.md 文件,给 Agent 提供特定任务的专属指南。

bash
# 从 clawhub.ai 安装技能
openclaw skills install weather
openclaw skills install github-management
openclaw skills install obsidian-notes

# 查看已安装技能
openclaw skills list

或者自己创建 ~/.openclaw/workspace-content/skills/my-skill/SKILL.md

markdown
# MY-SKILL

## 触发条件
当用户让我整理日报时使用此技能。

## 执行步骤
1. 读取 ~/notes/today.md 里的今日记录
2. 按"完成/进行中/明日计划"分类整理
3. 生成不超过 10 条要点
4. 保存到 ~/notes/reports/YYYY-MM-DD.md

多渠道配置(进阶)

配置多个消息平台,Agent 在所有平台同时在线:

json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-telegram-token",
      "allowFrom": ["your-telegram-id"]
    },
    "discord": {
      "enabled": true,
      "token": "your-discord-bot-token",
      "guildId": "your-server-id"
    }
  }
}

安全建议

  1. allowFrom 必须配置:不配置则任何人发消息都能控制你的 Agent
  2. 不要在 openclaw.json 里存真实密码:用环境变量或 .env 文件
  3. 沙箱模式(进阶):在 Docker 里运行 Agent,限制危险命令的影响范围
  4. 定期检查 Agent 日志openclaw logs -f 查看 Agent 在做什么

常见问题

Agent 不回复消息:检查 openclaw gateway status,确认 Gateway 在运行

回复很慢:正常,Claude/GPT API 响应时间 2-10 秒。复杂任务更长

找不到工作区文件:默认在 ~/.openclaw/workspace/,也可以 openclaw workspace --path 查看

更新 OpenClaw

bash
npm update -g openclaw
openclaw --version  # 确认版本

来源:pub.towardsai.net OpenClaw 零基础指南 | docs.openclaw.ai 官方文档 | 整理:ClaudeEagle

相关文章推荐

教程OpenClaw 快速入门:5 分钟搭建你的跨平台 AI 助手OpenClaw 是一个开源自托管 AI 网关,支持通过 WhatsApp、Telegram、Discord 等消息应用与 AI 助手对话。本文介绍如何在 5 分钟内完成安装配置,包括 CLI 安装、引导向导、Gateway 启动和控制面板访问的完整流程。2026/2/27教程OpenClaw 快速入门:用 Telegram 控制 AI Agent,5 分钟搭建个人 AI 助理OpenClaw 5 分钟快速入门:用 Telegram 控制 AI Agent,含安装配置、Bot 创建、Skills 定义、多渠道支持、Claude Code 编程任务集成,以及与 Claude Code CLI 的区别和互补关系。2026/4/13教程OpenClaw 多 Agent 架构入门:用 Telegram Bot 控制你的 AI Agent 集群OpenClaw 多 Agent 架构入门指南:通过 Telegram 控制 AI Agent 集群,支持子 Agent 编排、MCP 集成和多节点部署。含快速开始教程。2026/4/7教程OpenClaw 接入 Nextcloud Talk:自托管视频会议平台 AI 助手完全配置指南OpenClaw 接入 Nextcloud Talk 的完整教程:Nextcloud Talk 的自托管通信平台特点(视频会议+聊天+文件协作)、插件安装(@openclaw/nextcloud-talk)、通过 occ CLI 创建 Bot 账户并注册 Webhook、OpenClaw 最简配置(serverUrl+appPassword+sharedSecret)、DM 私信与房间(Room)访问控制、Markdown 消息格式和表情反应支持、局域网/内网部署注意事项(WebSocket vs Polling),以及 Nextcloud Talk AI 助手的典型使用场景(会议摘要/文件问答/任务分派)。2026/3/24教程OpenClaw 接入 Mattermost:自托管团队聊天平台的 AI 助手配置完全指南OpenClaw 接入 Mattermost 的完整教程:插件安装方式(openclaw plugins install @openclaw/mattermost)、创建 Mattermost Bot 账户并获取 Token、最简配置(botToken + baseUrl + dmPolicy)、原生斜杠命令注册(oc_* 命令)、频道/群组/私信三种消息模式、线程会话管理、多账户配置、DM 白名单权限控制、交互式按钮支持,以及 Mattermost 与 Slack 的功能对比。2026/3/22教程OpenClaw + Telegram 配置完全教程:5 分钟把 Claude 变成你的私人 Telegram 机器人OpenClaw 连接 Telegram 完整教程:BotFather 创建机器人、获取 Bot Token、OpenClaw 配置步骤、第一次对话测试、多用户权限控制、常见连接问题解决,以及 Telegram 频道和群组模式配置。2026/3/15