第一章：入门指南
约 1545 字大约 5 分钟
OpenClaw 是一款开源的多平台个人 AI 助手，支持 WhatsApp、Telegram、Discord、iMessage 等聊天平台。它不只是聊天机器人——它能真正执行操作：运行命令、管理文件、发送邮件、控制日历。
官网：https://openclaw.ai | 文档：https://docs.openclaw.ai | GitHub：https://github.com/openclaw/openclaw
1.1 什么是 OpenClaw
OpenClaw 是一个为 Pi 智能体（Pi agents） 提供消息网关的框架。你可以通过已有的聊天应用（WhatsApp、Telegram、Discord 等）与 AI 助手交互，助手在你的本地机器上运行，拥有真正的执行能力。
核心定位
| 特性 | 说明 |
|---|---|
| 多平台接入 | WhatsApp、Telegram、Discord、iMessage、Slack、Signal 等 |
| 本地运行 | 助手运行在你自己的电脑上，数据不上传第三方 |
| 真实执行 | 能运行 shell 命令、读写文件、操作浏览器 |
| 开源可扩展 | MIT 协议，支持自定义技能（Skills）和插件 |
| 24/7 主动 | 支持定时心跳任务，主动完成后台工作 |
典型使用场景
- 通过 Telegram 让 AI 帮你整理收件箱、发邮件、查日历
- 让助手在后台运行代码、提交 PR、监控服务器
- 构建一个 24/7 在线的个人 AI 助理，随时通过手机控制
- 多设备协作：Mac 做主机，手机做控制端
1.2 安装 OpenClaw
系统要求
- 推荐运行时：Node.js（不推荐 Bun，WhatsApp/Telegram 有已知问题）
- macOS：完整支持，含菜单栏伴侣应用
- Linux：完整支持 Gateway（建议无头服务器）
- Windows：通过 WSL2 支持 Gateway；原生 Windows 应用正在开发中
- iOS / Android：节点应用（Node app），可作为远程控制端
安装方式
方式一：通过 npm 安装（推荐）
npm install -g openclaw方式二：macOS 伴侣应用
从 GitHub Releases 下载 .dmg 安装包，安装后菜单栏会出现 OpenClaw 图标。
方式三：从源码构建
git clone https://github.com/openclaw/openclaw
cd openclaw
npm install
npm run build验证安装
openclaw --version
openclaw doctor # 诊断配置和环境1.3 首次设置（快速上手 5 分钟）
第一步：初始化工作区
openclaw setup这会创建默认工作区 ~/.openclaw/workspace/，并生成以下初始文件：
| 文件 | 用途 |
|---|---|
AGENTS.md | 智能体指令和行为规则 |
SOUL.md | 助手人格与风格设定 |
TOOLS.md | 工具使用指南 |
IDENTITY.md | 助手身份描述 |
USER.md | 关于你的背景信息 |
HEARTBEAT.md | 定时心跳任务指令 |
提示：建议把这个目录设为私有 Git 仓库，用于备份记忆文件。
第二步：配置渠道（以 Telegram 为例，最简单）
# 创建配置文件
mkdir -p ~/.openclaw在 ~/.openclaw/openclaw.json 中写入：
{
"agent": {
"model": "anthropic/claude-opus-4-6",
"workspace": "~/.openclaw/workspace"
},
"channels": {
"telegram": {
"token": "YOUR_TELEGRAM_BOT_TOKEN",
"allowFrom": ["your_telegram_user_id"]
}
}
}第三步：启动网关
openclaw gateway --port 18789第四步：打开控制台
openclaw dashboard浏览器会自动打开 Web 控制界面（http://127.0.0.1:18789）。
1.4 配置 Telegram Bot（最快入门路径）
Telegram 是最简单的接入方式，无需扫码配对。
获取 Bot Token
- 在 Telegram 中打开 @BotFather（确认用户名完全一致）
- 发送
/newbot命令，按提示操作 - 记录生成的 Token（格式：
123456789:ABCdef...）
最小配置
{
"channels": {
"telegram": {
"token": "YOUR_BOT_TOKEN",
"dmPolicy": "allowlist",
"allowFrom": ["your_telegram_numeric_id"]
}
}
}安全提示：
allowFrom填写你的 Telegram 数字 ID（不是用户名）。可以向 @userinfobot 发消息获取你的 ID。
启动并测试
openclaw gateway --port 18789在 Telegram 中向你的 Bot 发消息，等待回复即成功。
1.5 配置 WhatsApp（双手机方案）
WhatsApp 需要扫码配对，强烈建议使用第二个手机号（SIM 卡、eSIM 或预付费号码），原因如下：
- 若用个人 WhatsApp，你收到的每条消息都会触发 AI 响应
- 专用号码可以严格控制谁能与助手交互
配对步骤
# 第一步：触发 QR 码（用助手手机扫码）
openclaw channels login
# 第二步：启动网关
openclaw gateway --port 18789安全配置
{
"channels": {
"whatsapp": {
"allowFrom": ["+15555550123"],
"groups": {
"*": { "requireMention": true }
}
}
}
}重要：
allowFrom必须配置，否则任何人都能触发你的 AI 助手。
1.6 个人助手完整配置示例
以下是一个生产可用的助手配置：
{
"logging": { "level": "info" },
"agent": {
"model": "anthropic/claude-opus-4-6",
"workspace": "~/.openclaw/workspace",
"thinkingDefault": "high",
"timeoutSeconds": 1800,
"heartbeat": { "every": "30m" }
},
"channels": {
"whatsapp": {
"allowFrom": ["+15555550123"],
"groups": {
"*": { "requireMention": true }
}
}
},
"routing": {
"groupChat": {
"mentionPatterns": ["@openclaw", "openclaw"]
}
},
"session": {
"scope": "per-sender",
"resetTriggers": ["/new", "/reset"],
"reset": {
"mode": "daily",
"atHour": 4,
"idleMinutes": 10080
}
}
}配置说明
| 字段 | 含义 |
|---|---|
model | 使用的 AI 模型，支持 Claude、GPT-4、Gemini 等 |
thinkingDefault | 思考深度，"high" = 最深度思考 |
timeoutSeconds | 单次响应最大等待时间（秒） |
heartbeat.every | 心跳间隔，"0m" 禁用，"30m" 每30分钟 |
session.scope | 会话范围，per-sender = 每个发消息者独立会话 |
1.7 会话管理
常用会话命令
在聊天中直接发送以下命令控制会话：
| 命令 | 功能 |
|---|---|
/new 或 /reset | 开始新会话，清除当前上下文 |
/compact | 压缩会话上下文，释放 Token 空间 |
会话文件位置
~/.openclaw/agents/<agentId>/sessions/
├── <SessionId>.jsonl # 会话记录
└── sessions.json # 会话元数据（Token 用量等）1.8 心跳任务（主动模式）
心跳让 OpenClaw 定期主动执行任务，无需等待你发消息。
工作原理
- 按配置间隔（默认30分钟）触发一次 AI 运行
- AI 读取
HEARTBEAT.md中的指令 - 若回复
HEARTBEAT_OK，表示无需操作，不会发送通知 - 否则执行任务并向配置的渠道发送结果
HEARTBEAT.md 示例
# 心跳任务
每次心跳时：
1. 检查是否有未处理的重要邮件
2. 查看今天的日历事项
3. 如果有紧急事项，通过 WhatsApp 通知我
4. 如果一切正常，回复 HEARTBEAT_OK注意：心跳会消耗 API 额度，间隔不要设置太短。初次使用建议先禁用：
"heartbeat": { "every": "0m" }
1.9 状态检查与日志
openclaw status # 本地状态（凭证、会话、队列事件）
openclaw status --all # 完整诊断信息
openclaw status --deep # 包含 Gateway 健康探测
openclaw health --json # Gateway 健康快照（JSON 格式）
openclaw doctor # 审计并修复配置问题日志位置
/tmp/openclaw/openclaw-YYYY-MM-DD.log