OpenClaw 极简教程 - 从入门到精通

第一章：认识 OpenClaw 🤖

1.1 什么是 OpenClaw？

OpenClaw（曾用名 Clawdbot、Moltbot）是一款开源免费的个人 AI 智能体（Personal AI Agent），能够在你的个人设备（Mac、Windows、Linux）上本地运行，通过聊天软件（如 Telegram、WhatsApp、飞书、钉钉等）接收指令并直接操作电脑完成任务。

🎯 核心定位：运行在你自己设备上的"自主 AI 执行代理"。
ChatGPT 是"你问它答"，被动响应；而 OpenClaw 是"你吩咐它做"，主动落地。

1.2 核心特性

本地部署：所有数据本地存储，隐私零泄露
系统级执行：拥有与人类用户同等级别的系统权限
全渠道交互：支持 Telegram、WhatsApp、Discord、飞书、钉钉等 10+ 聊天平台
持久化记忆：记住用户偏好和上下文，实现跨会话持久记忆
自我进化：用户可教授技能，OpenClaw 能内化为永久技能
技能扩展：支持丰富的技能插件（ClawHub 市场 103+ 验证模块）

1.3 典型应用场景

场景	传统方式	OpenClaw 方式
文件整理	手动分类、重命名、移动	一句话指令自动完成
代码调试	手动运行、查看错误、修复	自动执行测试并修复
邮件管理	逐个查看、回复、归档	自动摘要、分类、回复
日程同步	手动添加到多个平台	一次指令多平台同步

1.4 系统架构

┌─────────────────────────────────────────┐
│           消息渠道 (Channels)            │
│  Telegram/WhatsApp/Discord/飞书/钉钉...  │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│      Gateway 网关 (控制平面)             │
│         ws://127.0.0.1:18789            │
└──────────────────┬──────────────────────┘
                   │
        ┌──────────┼──────────┐
        ▼          ▼          ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│  Agent   │ │   CLI    │ │  Web UI  │
│ (AI 核心) │ │ (命令行)  │ │ (仪表盘)  │
└──────────┘ └──────────┘ └──────────┘
            

第二章：安装前准备 📋

2.1 硬件配置要求

配置项	最低要求	推荐配置	说明
CPU	4 核 64 位处理器	6 核及以上	支持 Intel i5/AMD Ryzen 5 及更高
内存	8GB	16GB	本地运行大模型需 16GB+，仅基础调度 8GB 可满足
存储	10GB 可用空间	20GB+	存储依赖、模型文件及操作日志
网络	稳定互联网连接	100Mbps+	下载依赖、调用 AI 模型 API

2.2 软件环境要求

组件	版本要求	获取路径
Node.js	≥22.0.0	Node.js 官网
Git	任意稳定版	Git 官网
Docker（可选）	≥20.10.0	Docker 官网
pnpm（推荐）	最新版	`npm install -g pnpm`

2.3 操作系统支持

Windows：Windows 10 2004+ / Windows 11（64 位）
- 需启用 WSL2 + Linux 子系统（如 Ubuntu 22.04）
- 需要管理员 PowerShell 权限
macOS：macOS 12+（Intel/Apple Silicon）
- 原生支持，无需额外配置
- 需要 sudo 权限
Linux：Debian/Ubuntu 20.04+
- 兼容性最佳，推荐优先使用
- 需要 sudo 权限

2.4 关键凭证准备

💡 以下凭证至少准备其一：

AI 模型 API Key（必选）

国际模型：Claude、GPT-4（需科学上网）
国产模型：智谱 GLM-4.5、阿里云百炼、MiniMax（国内可直接访问）

聊天平台 Token（推荐）

Telegram Bot Token（新手推荐，最稳定）
WhatsApp / Discord / Slack Token（进阶用户）
飞书 / 钉钉（国内用户）

第三章：快速安装部署 🚀

3.1 方式一：npm 一键安装（推荐新手）

# 1. 安装 Node.js 22+（如未安装）
nvm install 22
nvm use 22

# 2. 全局安装 OpenClaw
npm install -g openclaw

# 或使用 pnpm（推荐）
pnpm add -g openclaw

# 3. 初始化配置
openclaw onboard --install-daemon

# 4. 启动网关服务
openclaw gateway start

# 5. 验证安装
openclaw doctor
            

3.2 方式二：官方脚本安装（Mac/Linux）

# 执行官方一键安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 运行配置向导
openclaw onboard --install-daemon

# 按向导提示完成：
# - 选择启动模式（推荐 QuickStart）
# - 输入 AI 模型 API Key
# - 选择聊天渠道并输入 Token
            

3.3 方式三：Windows PowerShell 安装

# 以管理员身份打开 PowerShell
# 执行一键安装命令
iwr -useb https://openclaw.ai/install.ps1 | iex

# 初始化验证
openclaw doctor
            

⚠️ Windows 用户注意：
如果遇到 PowerShell 脚本执行限制，先执行：
Set-ExecutionPolicy RemoteSigned -Scope CurrentSession

3.4 方式四：Docker 部署（跨平台通用）

# 1. 拉取镜像
docker pull openclaw/openclaw:latest

# 2. 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

# 3. 验证启动
docker ps
docker logs openclaw
            

Docker Compose 配置（推荐）

version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/root/.openclaw
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN}
    restart: unless-stopped
            

3.5 验证安装成功

访问本地仪表盘：http://127.0.0.1:18789
出现 OpenClaw 管理界面即为成功
执行 openclaw doctor 检查环境依赖

第四章：配置与对接 ⚙️

4.1 配置文件位置

主配置文件：~/.openclaw/openclaw.json
工作空间：~/.openclaw/workspace
凭证存储：~/.openclaw/credentials

4.2 最小配置示例

{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  }
}
            

4.3 完整配置示例

{
  // 代理配置
  "agent": {
    "model": "anthropic/claude-opus-4-5",
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  
  // 网关配置
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "none"
    }
  },
  
  // 消息渠道配置
  "channels": {
    "telegram": {
      "botToken": "YOUR_BOT_TOKEN"
    },
    "discord": {
      "token": "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}
            

4.4 对接 Telegram（新手推荐）

步骤 1：获取 Telegram Bot Token

打开 Telegram，搜索 @BotFather
发送 /newbot 命令
按提示输入机器人名称和用户名（需以 bot 结尾）
收到 API 密钥（格式：123456:ABC-DEF1234ghIkl），复制保存

步骤 2：配置对接

# 方法一：通过环境变量
export TELEGRAM_BOT_TOKEN="your_bot_token"

# 方法二：通过配置文件
# 编辑 ~/.openclaw/openclaw.json，添加：
"channels": {
  "telegram": {
    "botToken": "YOUR_BOT_TOKEN"
  }
}

# 方法三：通过命令行
openclaw channels login telegram
            

步骤 3：验证对接

Telegram 搜索创建的机器人
发送 /start 命令
收到欢迎语后，发送测试指令（如"列出当前目录文件"）
机器人返回执行结果即对接成功

4.5 对接 Discord

# 1. 访问 Discord Developer Portal 创建应用
# 2. 启用 Bot 并获取 Token
# 3. 配置权限：Send Messages, Read Messages, Embed Links
# 4. 添加到配置文件：
"channels": {
  "discord": {
    "token": "YOUR_DISCORD_BOT_TOKEN",
    "dm": {
      "policy": "pairing"
    }
  }
}
            

4.6 对接飞书/钉钉（国内用户）

# 飞书开放平台配置步骤：
# 1. 创建应用并启用机器人功能
# 2. 开通必要权限
# 3. 【关键】进入"版本管理与发布"创建并启用新版本
# 4. 获取 App ID 和 App Secret
# 5. 在 OpenClaw 配置界面填入
# 6. 首次发消息时，根据提示完成配对：
openclaw pairing approve feishu <你的配对码>
            

4.7 配置 AI 模型

使用国产模型（以智谱 GLM-4.5 为例）

{
  "agent": {
    "defaults": {
      "model": {
        "primary": "glm/glm-4-plus"
      }
    }
  },
  "models": {
    "providers": {
      "glm": {
        "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "你的智谱 API Key",
        "api": "openai-completions"
      }
    }
  }
}
            

第五章：核心功能使用 🎯

5.1 基础操作流程

✅ 标准流程：
1. 通过聊天软件发送指令 → 2. OpenClaw 接收并解析 →
3. 执行本地任务 → 4. 返回结果反馈

5.2 常用指令示例

功能类型	指令示例	说明
文件管理	"整理下载文件夹，按类型分类 PDF、图片、文档"	自动分类文件并创建子文件夹
代码执行	"运行当前目录下的 test.py 脚本，返回结果"	需配置终端权限
日程同步	"将明天 14:00 的会议添加到系统日历，同步至 Notion"	需安装 Notion 插件
文本处理	"将当前目录的会议录音转成文字纪要"	需对接语音识别 API
系统监控	"监控服务器 CPU 使用率，超过 80% 提醒我"	主动告警功能
网页调研	"搜索最新的 AI 编程工具，整理成表格"	浏览器自动化功能

5.3 聊天命令

在支持的消息渠道中可使用以下内置命令：

命令	描述	权限
`/status`	显示会话状态（模型 + token，成本）	所有用户
`/new` 或 `/reset`	重置会话	所有用户
`/compact`	压缩会话上下文（摘要）	所有用户
`/think off\|minimal\|low\|medium\|high\|xhigh`	设置思考级别	所有用户
`/verbose on\|off`	开关详细输出	所有用户
`/restart`	重启网关	群组中仅所有者

5.4 工作空间与技能

工作空间结构

~/.openclaw/workspace/
├── AGENTS.md          # 代理配置
├── SOUL.md            # AI 人格
├── TOOLS.md           # 工具定义
├── skills/            # 技能目录
│   ├── skill1/
│   │   └── SKILL.md
│   └── skill2/
│       └── SKILL.md
└── ...
            

ClawHub 技能市场

ClawHub 是 OpenClaw 的技能注册表，汇集超过 103 个经社区验证的技能模块。访问：https://clawhub.com

# 安装技能插件
openclaw skills install <skill-name>

# 列出已安装技能
openclaw skills list

# 启用/禁用技能
openclaw skills enable <skill-name>
openclaw skills disable <skill-name>
            

5.5 浏览器自动化

# 启用浏览器控制
{
  "browser": {
    "enabled": true,
    "color": "#FF4500"
  }
}

# 示例指令：
# "打开 GitHub，搜索 trending 项目，整理前 10 个到表格"
# "访问知乎，收集 AI 相关热门问题，生成摘要"
            

第六章：进阶配置 🔧

6.1 安全配置

DM（直接消息）安全策略

# 配对模式（推荐）- 未知发送者需配对码
{
  "security": {
    "dmPolicy": "pairing"
  }
}

# 开放模式 - 仅在完全信任环境启用
{
  "security": {
    "dmPolicy": "open"
  }
}
            

配对管理命令

# 批准配对
openclaw pairing approve <code>

# 列出配对
openclaw pairing list

# 移除配对
openclaw pairing remove <user-id>
            

6.2 沙箱模式

为非主会话启用 Docker 沙箱，增强安全性：

{
  "agent": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}
            

默认沙箱权限

允许：bash, process, read, write, edit, sessions_*
拒绝：browser, canvas, nodes, cron, discord, gateway

6.3 远程访问配置

Tailscale 访问（推荐）

{
  "gateway": {
    "tailscale": {
      "mode": "serve"
    }
  }
}
            

SSH 隧道访问

# 创建 SSH 隧道
ssh -L 18789:localhost:18789 user@remote-server

# 然后在本地访问
openclaw gateway connect ws://localhost:18789
            

6.4 伴侣应用

macOS 应用（OpenClaw.app）

菜单栏网关控制和健康监控
Voice Wake + 按下说话覆盖层
WebChat + 调试工具
SSH 远程网关控制

iOS / Android 节点

通过 Bridge 配对为节点
语音触发转发 + Canvas 表面
暴露 Canvas、Camera 和屏幕捕获命令

6.5 开发渠道切换

# 切换到稳定版
openclaw update --channel stable

# 切换到测试版
openclaw update --channel beta

# 切换到开发版
openclaw update --channel dev
            

第七章：故障排除 🔍

7.1 安装失败

报错现象	原因	解决方案
容器启动失败，提示依赖缺失	Docker 版本过低	升级 Docker 至 20.10+，执行 `docker-compose down -v` 清除缓存后重试
Node.js 版本不兼容	低于 22.0.0	执行 `nvm install 22 && nvm use 22`
源码克隆失败	网络限制	直接访问 GitHub 下载压缩包，或配置代理
PowerShell 脚本执行限制	Windows 安全策略	执行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentSession`

7.2 功能异常

问题	原因	解决方案
Telegram 机器人无响应	API 密钥错误或网络无法访问	核对密钥，国内用户配置代理，在配置中添加 `PROXY_URL`
无法读写本地文件	权限不足	Docker 部署：映射本地目录并开放权限 `chmod 777`
运行卡顿	硬件算力不足	关闭本地大模型，改用云端模型；或降低模型参数
飞书机器人权限错误	权限未发布新版本	进入"版本管理与发布"创建并启用新版本

7.3 常用诊断命令

# 检查环境依赖
openclaw doctor

# 查看网关状态
openclaw gateway status

# 查看实时日志
openclaw gateway logs --follow

# 检查端口占用
netstat -an | grep 18789

# 显示当前配置
openclaw config show

# 验证配置
openclaw config validate

# 重新登录渠道
openclaw channels login <channel>
            

7.4 macOS 权限问题

如果遇到权限错误，请检查以下 macOS 权限：

系统偏好设置 > 安全性与隐私 > 隐私
确保已授予：
- ✅ 屏幕录制
- ✅ 辅助功能
- ✅ 完全磁盘访问权限

7.5 插件路径冲突

# 如果日志出现 "duplicate plugin id detected" 警告
# 删除 C 盘残留，确保指向最新源码：
Remove-Item -Recurse -Force "$HOME\.openclaw\extensions\feishu"
            

第八章：安全与最佳实践 🛡️

8.1 安全风险提示

⚠️ 重要警告：
OpenClaw 拥有系统级权限，禁止在主力电脑运行！
建议使用闲置设备或云服务器部署。

8.2 安全最佳实践

使用沙箱模式：为非主会话启用 Docker 沙箱
启用配对模式：DM 消息默认使用配对验证
限制允许列表：在配置中明确指定允许的用户/群组
定期更新：保持 OpenClaw 为最新版本
监控日志：定期检查 openclaw gateway logs
备份配置：定期备份 ~/.openclaw 目录

8.3 性能优化

避免中断

设置电脑"永不睡眠"
WSL2 用户执行 wsl --shutdown 避免后台耗电
使用 openclaw gateway background 后台运行

成本优化

轻度使用选择国产模型（如 GLM-4.5）
重度使用搭配 Claude Opus
合理设置 /think 级别

8.4 常用命令速查

# ===== 网关管理 =====
openclaw gateway start      # 启动网关
openclaw gateway stop       # 停止网关
openclaw gateway restart    # 重启网关
openclaw gateway status     # 查看状态
openclaw gateway logs       # 查看日志

# ===== 渠道管理 =====
openclaw channels login <channel>   # 登录渠道
openclaw channels list              # 列出渠道
openclaw channels logout <channel>  # 登出渠道

# ===== 配置管理 =====
openclaw config show        # 显示配置
openclaw config edit        # 编辑配置
openclaw config validate    # 验证配置

# ===== 技能管理 =====
openclaw skills install <name>   # 安装技能
openclaw skills list             # 列出技能
openclaw skills enable <name>    # 启用技能
            

8.5 学习资源

官方文档：https://docs.openclaw.ai
GitHub 仓库：https://github.com/openclaw/openclaw
技能市场：https://clawhub.com
Discord 社区：https://discord.com/invite/clawd
官方网站：https://openclaw.ai

📑 目录导航

第一章：认识 OpenClaw 🤖

1.1 什么是 OpenClaw？

1.2 核心特性

1.3 典型应用场景

1.4 系统架构

第二章：安装前准备 📋

2.1 硬件配置要求

2.2 软件环境要求

2.3 操作系统支持

2.4 关键凭证准备

AI 模型 API Key（必选）

聊天平台 Token（推荐）

第三章：快速安装部署 🚀

3.1 方式一：npm 一键安装（推荐新手）

3.2 方式二：官方脚本安装（Mac/Linux）

3.3 方式三：Windows PowerShell 安装

3.4 方式四：Docker 部署（跨平台通用）

Docker Compose 配置（推荐）

3.5 验证安装成功

第四章：配置与对接 ⚙️

4.1 配置文件位置

4.2 最小配置示例

4.3 完整配置示例

4.4 对接 Telegram（新手推荐）

步骤 1：获取 Telegram Bot Token

步骤 2：配置对接

步骤 3：验证对接

4.5 对接 Discord

4.6 对接飞书/钉钉（国内用户）

4.7 配置 AI 模型

使用国产模型（以智谱 GLM-4.5 为例）

第五章：核心功能使用 🎯

5.1 基础操作流程

5.2 常用指令示例

5.3 聊天命令

5.4 工作空间与技能

工作空间结构

ClawHub 技能市场

5.5 浏览器自动化

第六章：进阶配置 🔧

6.1 安全配置

DM（直接消息）安全策略

配对管理命令

6.2 沙箱模式

默认沙箱权限

6.3 远程访问配置

Tailscale 访问（推荐）

SSH 隧道访问

6.4 伴侣应用

macOS 应用（OpenClaw.app）

iOS / Android 节点

6.5 开发渠道切换

第七章：故障排除 🔍

7.1 安装失败

7.2 功能异常

7.3 常用诊断命令

7.4 macOS 权限问题

7.5 插件路径冲突

第八章：安全与最佳实践 🛡️

8.1 安全风险提示

8.2 安全最佳实践

8.3 性能优化

避免中断

成本优化

8.4 常用命令速查

8.5 学习资源