文章

2026-03-31

OpenClaw 安装与使用教程

OpenClaw 安装与使用教程：打造你的 AI 私人助手一篇从零开始搭建 OpenClaw 的完整指南，让你拥有一个能通过 WhatsApp、Telegram、Discord 等多平台对话的 AI 助手。目录一、...

OpenClaw 安装与使用教程：打造你的 AI 私人助手 #

一篇从零开始搭建 OpenClaw 的完整指南，让你拥有一个能通过 WhatsApp、Telegram、Discord 等多平台对话的 AI 助手。

目录 #

一、核心概念
二、安装 OpenClaw
三、配置 AI 模型
四、连接聊天平台
五、实战场景
六、常见问题
七、总结速记

一、核心概念 #

1.1 什么是 OpenClaw？ #

大白话解释：OpenClaw 就像一个"AI 大管家"，它可以：

连接各种聊天软件（WhatsApp、Telegram、Discord、Signal、飞书等）
让 AI（如 GPT、Claude、DeepSeek）在聊天软件里帮你干活
自动处理消息、执行任务、回复对话
像真人一样在群里互动

类比理解：

OpenClaw = 手机操作系统
Skills（技能）= APP 应用（如天气查询、新闻推送）
Provider（模型提供商）= 云服务账号（如 OpenAI、Anthropic）

1.2 为什么需要 OpenClaw？ #

解决了这些痛点：

问题	OpenClaw 的解决方案
AI 只能在网页上聊天	让 AI"进驻"你的聊天软件
想在不同平台用同一个 AI	统一管理，一套配置多平台生效
AI 不能主动提醒你	定时任务 + 心跳机制，AI 会主动找你
每次都要重复配置	配置一次，永久生效

1.3 OpenClaw 的核心名词 #

名词	白话解释	类比
Gateway	网关服务，负责连接各平台和 AI	手机通信基站
Agent	智能体，就是你的 AI 助手"本体"	你的私人秘书
Channel	聊天渠道（WhatsApp、Telegram 等）	不同的聊天软件
Model	AI 模型（GPT-4o、Claude、DeepSeek 等）	AI 的"大脑"
Provider	模型提供商（OpenAI、Anthropic 等）	AI 大脑的供应商
Skill	技能包（天气预报、新闻推送等）	手机 APP
Workspace	工作区，AI 存放文件和记忆的地方	AI 的办公桌

1.4 支持哪些 AI 模型？ #

OpenClaw 支持几乎所有主流 AI 模型：

提供商	支持的模型	特点
OpenAI	GPT-4o、GPT-4o-mini、GPT-4-turbo	多模态、速度快、API 稳定
Anthropic	Claude Opus、Claude Sonnet	写作强、推理强、安全可靠
DeepSeek	DeepSeek Chat、DeepSeek R1	中文友好、便宜、推理能力强
Google	Gemini Pro、Gemini Flash	多模态、免费额度多
Moonshot	Kimi K2	长文本、中文友好
本地模型	Ollama、LM Studio	完全本地、隐私安全

二、安装 OpenClaw #

2.1 系统要求 #

要求	说明
Node.js	版本 ≥ 22（必须）
操作系统	macOS、Linux、Windows（通过 WSL2）
包管理器	npm 或 pnpm

检查 Node.js 版本：

node -v  # 需要显示 v22.x.x 或更高

如果版本不够，去 Node.js 官网下载最新 LTS 版本。

2.2 快速安装（推荐） #

macOS / Linux：

# 一行命令安装
curl -fsSL https://openclaw.ai/install.sh | bash

Windows（PowerShell）：

# PowerShell 安装
iwr -useb https://openclaw.ai/install.ps1 | iex

安装脚本会自动：

安装 Node.js（如果没有）
安装 OpenClaw CLI
运行新手引导

2.3 手动安装 #

如果你已经安装了 Node.js 22+：

# npm 安装
npm install -g openclaw@latest
 
# 或 pnpm 安装（推荐）
pnpm add -g openclaw@latest
pnpm approve-builds -g  # 批准构建脚本
pnpm add -g openclaw@latest  # 重新安装执行 postinstall

2.4 安装后验证 #

# 检查版本
openclaw --version
 
# 运行健康检查
openclaw doctor
 
# 查看帮助
openclaw help

2.5 运行新手引导（重要！） #

# 启动新手引导（会自动安装 Gateway 服务）
openclaw onboard --install-daemon

新手引导会帮你：

选择 AI 模型提供商
输入 API Key
设置工作区目录
安装 Gateway 后台服务
可选连接聊天平台

三、配置 AI 模型 #

3.1 选择模型提供商 #

OpenClaw 支持两种配置方式：

方式	说明	推荐场景
新手引导	交互式选择，自动配置	首次安装
手动配置	编辑配置文件	高级定制

3.2 通过新手引导配置 #

# 运行新手引导
openclaw onboard
 
# 或指定提供商
openclaw onboard --auth-choice openai-api-key
openclaw onboard --auth-choice anthropic-api-key

按提示输入 API Key，自动完成配置。

3.3 获取 API Key #

提供商	获取方式
OpenAI	OpenAI Platform → 创建 API Key
Anthropic	Anthropic Console → 创建 API Key
DeepSeek	DeepSeek 开放平台 → 创建 API Key
Google	Google AI Studio → 获取 API Key

3.4 环境变量配置（推荐） #

Linux / macOS：

# 添加到 ~/.bashrc 或 ~/.zshrc
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export DEEPSEEK_API_KEY="sk-..."

Windows PowerShell：

# 临时设置
$env:OPENAI_API_KEY = "sk-..."
 
# 永久设置（写入用户环境变量）
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-...", "User")

3.5 配置文件方式 #

编辑配置文件 ~/.openclaw/openclaw.json：

{
  // 环境变量（可选，也可直接在系统设置）
  env: {
    OPENAI_API_KEY: "sk-...",
    ANTHROPIC_API_KEY: "sk-ant-...",
  },
 
  // 模型配置
  agents: {
    defaults: {
      // 默认模型
      model: {
        primary: "anthropic/claude-sonnet-4-5",  // 主模型
        fallbacks: ["openai/gpt-4o"],  // 失败时回退模型
      },
      // 工作区目录
      workspace: "~/.openclaw/workspace",
    },
  },
}

3.6 模型命名规则 #

OpenClaw 使用 provider/model 格式：

写法	说明
`anthropic/claude-opus-4-5`	Anthropic 的 Claude Opus 4.5
`openai/gpt-4o`	OpenAI 的 GPT-4o
`deepseek/deepseek-chat`	DeepSeek 的聊天模型
`google/gemini-2.0-flash`	Google 的 Gemini Flash

3.7 验证配置 #

# 查看已配置的模型
openclaw models list
 
# 查看模型状态（包括认证信息）
openclaw models status
 
# 切换默认模型
openclaw models set anthropic/claude-sonnet-4-5

如果显示 Missing auth，说明 API Key 未设置，需要重新配置。

四、连接聊天平台 #

4.1 WhatsApp 连接 #

# 启动 WhatsApp 配对
openclaw channels login
 
# 会显示 QR 码，用手机 WhatsApp 扫码

扫码后，AI 就能通过 WhatsApp 和你对话了。

配置 WhatsApp 白名单（只允许特定号码触发 AI）：

{
  channels: {
    whatsapp: {
      // 允许的私聊号码（E.164 格式，即国际号码格式）
      allowFrom: ["+8613800138000", "+15555550123"],
      // 群组策略
      groups: {
        "*": { requireMention: true },  // 所有群需要 @提及
        "120363403215116621@g.us": { 
          allow: true, 
          requireMention: false  // 指定群不需要提及
        },
      },
    },
  },
}

4.2 Telegram 连接 #

第一步：创建 Telegram Bot

在 Telegram 搜索 @BotFather
发送 /newbot
按提示设置 Bot 名称
获取 Bot Token（格式：123456:ABC-DEF...）

第二步：配置 OpenClaw

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC-DEF...",  // 你的 Bot Token
      // 私聊白名单
      allowFrom: ["tg:123456789", "@your_username"],
      // 群组配置
      groups: {
        "*": { requireMention: true },
        "-1001234567890": { 
          allow: true,
          requireMention: false,
        },
      },
    },
  },
}

第三步：邀请 Bot 到群组

在群组设置 → 添加成员 → 搜索你的 Bot
Bot 加入后，群里的人 @它就会触发 AI

4.3 Discord 连接 #

第一步：创建 Discord Bot

访问 Discord Developer Portal
点击 "New Application"
进入 Bot 页面，点击 "Add Bot"
复制 Bot Token

第二步：邀请 Bot 到服务器

进入 OAuth2 → URL Generator
选择 bot scope
选择需要的权限（发送消息、读取消息等）
复制生成的链接，用浏览器打开
选择服务器，授权 Bot 加入

第三步：配置 OpenClaw

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      // 服务器配置
      guilds: {
        "123456789012345678": {  // 服务器 ID
          requireMention: false,
          channels: {
            general: { allow: true },
            help: { 
              allow: true, 
              requireMention: true,
            },
          },
        },
      },
    },
  },
}

4.4 启动 Gateway 网关 #

配置完成后，启动 Gateway：

# 前台启动（可以看到日志）
openclaw gateway
 
# 后台启动（作为系统服务）
openclaw gateway start
 
# 查看状态
openclaw gateway status
 
# 停止
openclaw gateway stop

五、实战场景 #

场景 1：私聊助手（日常问答） #

效果：给 AI 发消息，它像真人一样回复。

最小配置：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-5" },
      // AI 身份（可选）
      identity: {
        name: "小助手",
        emoji: "🤖",
      },
    },
  },
 
  channels: {
    whatsapp: {
      dmPolicy: "open",  // 允许所有私聊
      allowFrom: ["*"],  // 开放模式
    },
  },
}

使用：

打开 WhatsApp，给 AI 发消息
AI 会回复，带 🤖 前缀
可以问任何问题，AI 会像真人一样回答

场景 2：群聊管家（需要 @提及） #

效果：AI 在群里安静待着，有人 @它才会回复。

配置：

{
  agents: {
    list: [
      {
        id: "main",
        identity: { name: "小助手", emoji: "🤖" },
        // 提及触发词
        groupChat: {
          mentionPatterns: ["@小助手", "@bot", "小助手"],
        },
      },
    ],
  },
 
  channels: {
    whatsapp: {
      // 私聊白名单
      allowFrom: ["+8613800138000"],
      // 群组策略
      groups: {
        "*": { requireMention: true },  // 所有群需要提及
      },
    },
  },
}

使用：

AI 在群里安静待着，不会乱发言
发送 @小助手今天天气怎么样？
AI 才会回复

场景 3：定时提醒（Cron 任务） #

效果：AI 每天早上 8 点主动给你发消息提醒。

添加定时任务：

openclaw cron add \
  --name "morning-reminder" \
  --schedule '{"kind": "cron", "expr": "0 8 * * *", "tz": "Asia/Shanghai"}' \
  --payload '{"kind": "systemEvent", "text": "早安！新的一天开始了。"}' \
  --session-target main

或通过配置文件：

{
  cron: {
    enabled: true,
    jobs: [
      {
        id: "morning-reminder",
        name: "早安提醒",
        schedule: {
          kind: "cron",
          expr: "0 8 * * *",  // 每天 8:00
          tz: "Asia/Shanghai",
        },
        payload: {
          kind: "systemEvent",
          text: "早安！别忘了查看今日日程。",
        },
        sessionTarget: "main",
        delivery: {
          mode: "announce",
          channel: "whatsapp",  // 发送到 WhatsApp
        },
      },
    ],
  },
}

Cron 表达式说明：

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日期 (1-31)
│ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ ┌───────────── 星期 (0-6, 0=周日)
│ │ │ │ │
* * * * *

常用例子：

0 8 * * * - 每天 8:00
0 9 * * 1-5 - 周一到周五 9:00
30 18 * * * - 每天 18:30

场景 4：安装技能扩展（Skills） #

效果：让 AI 学会天气预报、网页抓取、新闻推送等技能。

查看可用技能：

# 列出所有可用技能
openclaw skills list
 
# 列出已安装的技能
openclaw skills list --installed

安装技能：

# 安装天气技能
openclaw skills install weather
 
# 安装每日学习技能
openclaw skills install daily-learning
 
# 安装安全审计技能
openclaw skills install secureclaw

技能配置：

{
  skills: {
    // 启用特定技能
    entries: {
      weather: {
        enabled: true,
        env: { DEFAULT_CITY: "北京" },
      },
      daily-learning: {
        enabled: true,
      },
    },
  },
}

使用：

发送 今天天气怎么样？ → AI 查询天气
发送 上海天气 → AI 返回上海天气
AI 会自动识别需要使用哪个技能

场景 5：多模型切换 #

效果：简单问题用便宜模型，复杂问题用高级模型。

配置多模型：

{
  agents: {
    defaults: {
      models: {
        // 高级模型
        "anthropic/claude-opus-4-5": { alias: "Opus" },
        // 标准模型
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        // 快速模型
        "openai/gpt-4o-mini": { alias: "Mini" },
        // 推理模型
        "deepseek/deepseek-reasoner": { alias: "R1" },
      },
      model: {
        primary: "anthropic/claude-sonnet-4-5",  // 默认用 Sonnet
        fallbacks: ["openai/gpt-4o"],  // 失败时回退
      },
    },
  },
}

在聊天中切换模型：

/model              # 查看可用模型
/model list         # 详细列表  
/model Opus         # 切换到 Claude Opus（高级）
/model Mini         # 切换到 GPT-4o-mini（便宜快速）
/model R1           # 切换到 DeepSeek R1（推理）
/model status       # 查看当前模型状态

场景 6：心跳机制（AI 主动检查） #

效果：AI 每 30 分钟自动检查重要事项，有紧急情况时主动提醒。

配置心跳：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",        // 每 30 分钟检查一次
        target: "last",      // 发送到最后活跃的渠道
      },
    },
  },
}

创建 HEARTBEAT.md（放在工作区根目录）：

# HEARTBEAT.md
 
## 每次心跳检查项目
 
1. 检查是否有紧急邮件
2. 检查是否有即将开始的会议（2小时内）
3. 检查天气是否有异常预警
4. 检查系统健康状态
 
## 输出规则
 
- 有紧急事项 → 发送提醒消息
- 无事项 → 回复 HEARTBEAT_OK（静默）

AI 会每 30 分钟读取这个文件，执行检查任务。

六、常见问题 #

Q1: Gateway 启动失败，提示"Model is not allowed" #

原因：模型不在白名单中。

解决：

# 查看可用模型
openclaw models list
 
# 设置默认模型
openclaw models set anthropic/claude-sonnet-4-5

或在配置文件中添加：

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-5": {},  // 添加到白名单
      },
    },
  },
}

Q2: 提示"Authentication failed"或"No API key found" #

原因：API Key 未设置。

解决：

# 检查模型状态
openclaw models status
 
# 重新运行新手引导
openclaw onboard

确保：

API Key 正确复制（无多余空格）
环境变量已加载（重启终端试试）
配置文件格式正确

Q3: WhatsApp 扫码后连接不上 #

原因：认证状态失效或网络问题。

解决：

# 重置 WhatsApp 认证
rm -rf ~/.openclaw/credentials/whatsapp
 
# 重新登录
openclaw channels login

Q4: 群聊消息没有触发 AI #

原因：未配置群组白名单或提及模式。

解决：

{
  channels: {
    whatsapp: {
      // 添加群组白名单
      groupPolicy: "allowlist",
      groupAllowFrom: ["120363403215116621@g.us"],
      groups: {
        "120363403215116621@g.us": {
          allow: true,
          requireMention: false,  // 不需要提及也会回复
        },
      },
    },
  },
}

Q5: AI 回复太慢 #

原因：模型延迟高或网络问题。

解决：

换用更快模型：

{
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-4o-mini",  // 快速便宜
        fallbacks: ["anthropic/claude-sonnet-4-5"],
      },
    },
  },
}

配置模型回退：

主模型失败时自动切换到备用模型

Q6: 如何让 AI 有"记忆"？ #

方案：在工作区创建记忆文件。

OpenClaw 会自动读取这些文件：

文件	作用
`MEMORY.md`	长期记忆（重要信息、偏好）
`USER.md`	用户信息（姓名、职业、习惯）
`IDENTITY.md`	AI 身份（名字、性格、emoji）
`memory/YYYY-MM-DD.md`	每日日志

示例 USER.md：

# 用户信息
 
- 姓名：小王
- 职业：程序员
- 常用语言：Python、JavaScript
- 关注领域：AI、前端开发
- 时区：Asia/Shanghai

AI 每次对话都会读取这些内容，记住你的偏好。

Q7: 如何更新 OpenClaw？ #

# npm 方式
npm update -g openclaw
 
# 或重新安装
npm install -g openclaw@latest
 
# pnpm 方式
pnpm add -g openclaw@latest

Q8: 如何查看日志？ #

# 查看 Gateway 日志
openclaw logs
 
# 查看最近日志
openclaw logs --limit 100
 
# 实时查看日志
openclaw logs --follow

七、总结速记 #

类型	核心要点
安装	`curl -fsSL https://openclaw.ai/install.sh \| bash`
新手引导	`openclaw onboard --install-daemon`
配置模型	设置 API Key + `model.primary`
连接平台	`openclaw channels login` + 白名单配置
启动网关	`openclaw gateway` 或 `openclaw gateway start`
群聊模式	`requireMention: true` + `mentionPatterns`
定时任务	`openclaw cron add`
安装技能	`openclaw skills install <name>`
切换模型	`/model <alias>`
心跳机制	配置 `heartbeat` + 创建 `HEARTBEAT.md`

附录 #

常用命令速查表 #

命令	说明
`openclaw onboard`	新手引导
`openclaw doctor`	健康检查
`openclaw gateway`	启动网关（前台）
`openclaw gateway start`	后台启动
`openclaw gateway stop`	停止网关
`openclaw channels login`	配对聊天平台
`openclaw models list`	查看模型列表
`openclaw models status`	查看模型状态
`openclaw models set <model>`	设置默认模型
`openclaw skills list`	查看技能列表
`openclaw skills install <name>`	安装技能
`openclaw cron add`	添加定时任务
`openclaw cron list`	查看定时任务
`openclaw config get`	查看配置
`openclaw status`	查看系统状态
`openclaw logs`	查看日志
`openclaw --version`	查看版本

模型速查表 #

提供商	模型 ID	特点
Anthropic	`claude-opus-4-5`	最强推理、写作
Anthropic	`claude-sonnet-4-5`	平衡性价比
OpenAI	`gpt-4o`	多模态、速度快
OpenAI	`gpt-4o-mini`	便宜快速
DeepSeek	`deepseek-chat`	中文友好、便宜
DeepSeek	`deepseek-reasoner`	推理能力强
Google	`gemini-2.0-flash`	快速、免费额度多

资源	链接
OpenClaw 官方文档	https://docs.openclaw.ai
OpenClaw GitHub	https://github.com/openclaw/openclaw
OpenClaw 社区（Discord）	https://discord.com/invite/clawd
Skills 商店	https://clawhub.com
OpenAI API	https://platform.openai.com
Anthropic API	https://console.anthropic.com
DeepSeek API	https://platform.deepseek.com