GitHub 28万星爆火！OpenClaw新手教程：0基础让AI自己动手——读文件、发邮件、跑命令

2025 年 11 月，一个名为 OpenClaw 的开源项目在 GitHub 上线。短短四个月，它的 Star 数突破 28 万，超越 Linux、React 等老牌项目，成为 GitHub 历史上增长最快的开源 AI 项目。它被社区昵称为”AI 小龙虾”，创始人 Peter Steinberger 给它定的 slogan 是——”the AI that actually does things”（真正能执行任务的 AI）。

和 ChatGPT 这类对话式 AI 不同，OpenClaw 不只是回答问题，它能在你的电脑上读文件、操作浏览器、执行命令行、收发邮件、管理日程——真正把活干了。这篇教程将从零开始，带你完整走通 OpenClaw 的安装、配置、技能扩展、自动化实战全流程，哪怕没有任何编程基础，跟着做也能成功”养虾”。

一、OpenClaw 是什么：产品定位速览

用一句话概括：OpenClaw 是一个本地优先、模型无关的开源 AI 智能体执行框架。它本身不是大语言模型，而是给各类大模型装上”能动手的身体”——接收指令、拆解任务、调用工具、执行操作、反馈结果，形成完整的闭环。

核心定位上有三个关键词需要记住：

• 本地优先：所有交互历史、任务记录、配置文件默认存储在你的本地设备，仅在调用云端大模型 API 时联网，数据主权完全在你手里。
• 模型无关：不绑定任何大模型厂商，兼容 Claude、GPT、Gemini、Kimi、通义千问等 200+ 主流模型，支持云端 API 和本地模型双模式，可一键热切换。
• 执行导向：不是”你问它答”的聊天机器人，而是具备”意图理解 → 任务拆解 → 路径规划 → 工具调用 → 执行校验 → 结果反馈”全流程能力的智能体，能自主完成多步骤复杂工作流。

截至 2026 年 3 月，OpenClaw 采用 MIT 开源协议，社区已贡献超过 1.8 万个技能插件（Skills），覆盖办公、开发、生活、自动化等全场景。它被广泛视为 AI 从”对话时代”迈向”执行时代”的标志性产品。

二、安装准备：环境搭建全指南

OpenClaw 的安装门槛其实非常低，但不同系统的路径有差异，新手最容易在这一步踩坑。下面按操作系统分别讲解。

系统要求

macOS / Linux 安装

这是最简单的路径，打开终端，粘贴一行命令即可：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

脚本会自动检测系统、安装 Node.js 依赖和 OpenClaw 本体，全程无需手动干预。如果你已经装了 Homebrew，也可以用：

brew tap openclaw/openclaw
brew install openclaw

Windows 安装

Windows 用户有三种路径：原生安装、PowerShell 脚本、WSL2。推荐新手走 PowerShell 路径。

第一步，以管理员身份打开 PowerShell，先解锁脚本执行权限（90% 的新手在这步翻车）：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

弹出确认提示时输入 Y 回车。然后执行官方安装脚本：

iwr -useb https://openclaw.ai/install.ps1 | iex

如果一键脚本报错（npm 安装失败），改用 pnpm 安装更稳定：

npm install -g pnpm
pnpm setup
# 关闭并重新打开 PowerShell
pnpm add -g openclaw@latest

安装完成后验证：执行 openclaw --version，能输出版本号就说明成功了。

Docker 安装（跨平台通用）

docker pull openclaw/openclaw:latest
docker run -it \
  -v ~/.openclaw:/root/.openclaw \
  -e OPENAI_API_KEY=your_key_here \
  -p 18789:18789 \
  openclaw/openclaw:latest

Docker 方式把所有依赖打包在容器里，不污染系统环境，适合想保持系统干净的用户。

三、核心概念：Soul File、Gateway、Skills、Memory

在动手配置之前，先理解 OpenClaw 的四个核心概念，后面所有操作都围绕它们展开。

Soul File：AI 的”灵魂档案”

位置：~/.openclaw/SOUL.md。这是一个 Markdown 格式的配置文件，定义你的 AI 是谁、怎么说话、偏好什么。你可以把它理解为给小龙虾写的一份”人设说明书”。

示例内容：

# Soul File - 我的 AI 助手

## 身份
- **名字**: 小龙
- **角色**: 专业且高效的个人助理
- **语气**: 简洁、有条理、直奔重点

## 沟通风格
- 使用简体中文回复
- 回答要简洁，避免冗长
- 不确定时诚实告知

## 偏好
- 时区: Asia/Shanghai
- 代码风格: 注释清晰、结构化

随时编辑这个文件，Agent 的行为会即时更新。这让你的 AI 越用越符合你的个人风格。

Gateway：总调度中心

Gateway 是 OpenClaw 的核心服务进程，默认运行在 18789 端口。它负责接收来自各个渠道（网页、QQ、飞书、Telegram 等）的消息，分配给 AI 处理，再把结果返回给你。

关键配置项：

• Gateway port：通信端口，默认 18789
• Gateway bind：绑定地址，默认 Loopback（127.0.0.1），仅本机可访问，最安全
• Gateway auth：认证模式，默认 Token，系统自动生成密钥

Skills：能力扩展插件

Skills 是 OpenClaw 的插件系统，本质是包含 SKILL.md 文件的文件夹。没装 Skills 的龙虾只会聊天，装了之后才能真正干活——搜索网页、操作浏览器、管理文件、收发邮件、生成 PPT 等。

安装路径优先级从高到低：项目目录/skills/ > ~/.openclaw/skills/ > 内置 Skills。名称冲突时高优先级覆盖低优先级。

Memory：长期记忆

OpenClaw 具备长期记忆能力，能记住你的偏好、过往对话要点和重要信息。记忆文件存储在本地工作区目录下，跨会话延续，让 Agent 越用越懂你。

四、第一步实操：Onboard 向导全流程

安装完成后，执行以下命令启动配置向导：

openclaw onboard --install-daemon

--install-daemon 参数会同时安装后台服务，让 Gateway 关掉终端也能持续运行。向导会一步步引导你完成以下配置：

第 1 步：安全确认

屏幕会显示安全警告——因为 OpenClaw 能操作你的电脑（包括执行命令行、读写文件），提醒你在虚拟机或备用设备上使用。确认理解风险后选择 Yes。

第 2 步：选择安装模式

QuickStart（快速开始）或 Manual（手动配置）。新手直接选 QuickStart，它会用默认配置快速搞定。

第 3 步：配置 AI 大模型

这是最关键的一步——给龙虾选”大脑”。向导会列出可选的模型提供商：

• Moonshot AI（Kimi K2.5）：中国用户推荐，国内直连，注册即送免费额度
• Qwen（通义千问）：支持 OAuth 扫码登录，免手动填 API Key，适合快速体验
• Anthropic（Claude）：综合能力最强，但价格较高，适合进阶用户
• OpenAI（GPT-4o）：代码能力强，海外用户首选
• Z.AI（GLM-5）：国产模型，性价比高

以 Kimi 为例：选择 Moonshot AI → 选择 .cn 接入点 → 登录 platform.moonshot.cn 获取 API Key → 粘贴回终端 → 选择 Kimi-K2.5 模型。

第 4 步：选择聊天渠道

向导会问是否连接 Telegram、WhatsApp、Discord 等平台。新手建议先跳过，直接用 Web UI 体验，后续再按需接入。

第 5 步：安装基础 Skills

选择 Yes 启用技能配置，至少安装 ClawHub（官方技能市场），之后就能随时搜索和安装社区技能包。技能安装工具选 npm 即可。

第 6 步：启动 Gateway

Windows 可能弹出防火墙提示，务必点击”允许”。Gateway 启动后，选择 Web UI 方式，浏览器会自动打开控制面板。

# 验证 Gateway 状态
openclaw gateway status

# 打开控制面板
openclaw dashboard

在网页里发送一条”你好，测试连接”，收到 AI 回复就说明你的小龙虾正式上线了。

五、配置详解：Gateway 与模型调优

向导跑完后，所有配置都存在一个文件里：

• macOS / Linux：~/.openclaw/openclaw.json
• Windows：C:\Users\你的用户名\.openclaw\openclaw.json

模型配置

如果你想在向导之后切换模型，直接编辑配置文件的 model 部分：

{
  "model": {
    "type": "moonshot",
    "api_key": "你的API Key",
    "model_name": "kimi-k2.5",
    "max_tokens": 4096,
    "temperature": 0.7,
    "timeout": 60
  }
}

修改后重启 Gateway 生效：

openclaw gateway restart

多模型路由

进阶玩法是配置多个模型，按任务类型自动路由——简单任务用便宜模型，复杂任务才调贵模型：

{
  "ai": {
    "providers": {
      "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" },
      "openai": { "apiKey": "${OPENAI_API_KEY}" }
    },
    "routing": {
      "simple": "claude-3-haiku",
      "complex": "claude-sonnet-4",
      "code": "gpt-4-turbo"
    }
  }
}

Gateway 安全配置

默认配置已经足够安全——仅本机访问 + Token 认证。如果需要远程访问（比如部署在云服务器上），需要修改绑定地址并加强认证：

{
  "gateway": {
    "port": 18789,
    "bind": "0.0.0.0",
    "auth": "token",
    "token": "你的自定义强密码Token"
  }
}

部署在公网服务器时，务必确保防火墙只放行必要端口，并使用足够复杂的 Token。

六、指令模板：让 AI 听懂你的话

OpenClaw 的强大在于它能理解自然语言指令并自动拆解执行。但指令写得好不好，直接影响执行效果。下面是几类高频场景的指令模板。

文件管理类

整理我电脑 D 盘/工作文档文件夹，按 2025、2026 年分类，生成汇总清单 PDF，发送到 test@163.com

信息检索类

搜索今天的科技新闻头条，挑出 5 条最重要的，用简洁格式整理，加上 emoji 标注类别

代码开发类

拉取 github.com/xxx/xxx.git 到本地 /Users/xxx/code 目录，安装依赖，运行测试，打包为 dist 文件夹

浏览器自动化类

帮我在京东搜索 MacBook Pro 价格，截取前 5 个商品的名称和价格，整理成表格

会议纪要类

我把刚才的会议记录发给你，请帮我：
1) 生成一份结构清晰的会议纪要，包含时间、参会人、讨论要点
2) 提取所有待办事项，标明负责人和截止时间
3) 把待办事项写入飞书多维表格

写指令的通用原则：任务目标明确、步骤分步列出、输出格式具体。你描述得越清楚，AI 执行得越精准。

七、常用命令速查表

掌握以下命令，日常使用就够用了：

八、进阶玩法：Skills 安装与开发

三种 Skills 安装方式

方式一：ClawHub CLI 安装（推荐）

# 搜索技能
npx clawhub@latest search "gitee"

# 安装指定技能
npx clawhub@latest install github
npx clawhub@latest install agent-browser
npx clawhub@latest install summarize

方式二：对话安装（最简单）

直接在聊天窗口对 OpenClaw 说：”帮我安装一个能查天气的技能”，它会自动推荐并安装。

方式三：手动安装

# 全局安装（所有项目可用）
cp -r skill-folder ~/.openclaw/skills/

# 项目级安装（仅当前项目生效）
cp -r skill-folder ./skills/

新手必备 Skills 推荐

安装后重启 Gateway 让技能生效：openclaw gateway restart

自定义 Skill 开发

每个 Skill 只需要一个 SKILL.md 文件。OpenClaw 官方还提供了 skill-creator 技能，可以用自然语言让 AI 帮你生成 Skill 骨架：

mkdir -p ~/.openclaw/workspace/skills/my-skill

# 编辑 SKILL.md
# 格式：frontmatter（元数据）+ 使用说明
# OpenClaw 会自动扫描并加载

九、实战案例：三个真实应用场景

案例一：每日晨报自动生成

这是最经典的新手实战。让 OpenClaw 每天早上自动为你生成一份个人晨报，包含新闻、天气、日程。

第一步，安装必要技能：

openclaw skills install calendar email web_search

第二步，创建定时任务。在 Web UI 中或通过命令行添加一个 Cron Job：

openclaw cron add \
  --name "每日晨报" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "请为我准备今日早报：
1. 搜索今天的科技新闻头条（3-5条）
2. 查看今天的天气（上海）
3. 查看我今天的日历安排
4. 用简洁的格式整理，加上 emoji" \
  --wake now

每天早上 8 点，你的小龙虾会自动执行这个任务，把整理好的晨报推送到你指定的聊天渠道。

案例二：群消息智能整理

如果你接入了飞书或 Telegram，群消息经常多到看不过来。让 OpenClaw 帮你按优先级归类：

帮我看一下昨天晚上 6 点到今天早上 9 点之间，所有飞书群的未读消息。
按紧急程度分三级整理：
1) 需要我立刻回复或处理的
2) 需要我知晓但不急的
3) 纯闲聊可以跳过的
每条列出群名、发言人、核心内容摘要。
如果有 @ 我的消息，单独标出来放在最前面。

它会调用 feishu-im-read 读取群消息，按优先级归类输出。5 分钟看完以前要翻半小时的内容，还能自动汇总成飞书云文档。

案例三：竞品价格监控

每天定时抓取竞品官网的产品价格和新闻动态，生成日报发到飞书群：

openclaw cron add \
  --name "竞品监控" \
  --cron "0 9 * * 1-5" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "检查以下竞品网站的最新动态：
1. 竞品A：抓取首页产品价格变化
2. 竞品B：查看最新新闻公告
3. 竞品C：检查新功能上线情况
整理成日报格式，包含：产品名称、价格变化、新闻摘要、行动建议" \
  --delivery-mode announce \
  --delivery-to "feishu:your-group-id"

工作日每天 9 点自动执行，结果直接推送到飞书群，全程无需人工干预。

十、效率技巧：Heartbeat 与 Hooks

Heartbeat：心跳检查

Heartbeat 是 OpenClaw 的定期轮询机制，默认每 30 分钟执行一次，在主会话中运行，拥有完整上下文。适合不需要精确时间但需要定期关注的场景。

在 <workspace>/HEARTBEAT.md 中编写检查清单：

# HEARTBEAT.md

## 每日检查（轮流执行，避免频繁 API 调用）

### 周一、三、五
- 检查邮箱未读邮件，重要邮件立即通知
- 普通邮件积累到 3 封以上再汇总通知

### 周二、四
- 检查日历中未来 30 分钟内的会议
- 如果有会议，提前发送提醒

### 每次心跳
- 记录状态到 memory/heartbeat-state.json
- 如果没有需要通知的事项，回复 HEARTBEAT_OK

Hooks：事件钩子

Hooks 是事件驱动的触发器，在某件事发生时自动执行：

• command:new — 新会话开始时触发
• gateway:startup — Gateway 启动后触发
• message:sent — 消息发出后触发
• session:compact:before — 压缩历史前触发

比如配置一个 Hook：每次开新会话时自动注入今天的待办列表，这样每次新对话 AI 都知道你今天要干什么。

Cron vs Heartbeat 选型指南

经验法则：准时很重要用 Cron，需要上下文或批量检查用 Heartbeat，两者经常搭配使用。

十一、成本分析：用 OpenClaw 要花多少钱

OpenClaw 本身是开源免费的，你需要支付的是所使用的大模型 API 费用。不同模型的成本差异很大：

省钱建议：简单任务用轻量模型（Haiku、Flash），复杂任务才调大模型；启用多模型路由自动分配；Heartbeat 间隔不要太短（建议 ≥ 15 分钟），避免不必要的 Token 消耗。

十二、避坑清单：新手常踩的 10 个坑

1. Windows 脚本权限未解锁：执行安装命令前务必先运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，否则 90% 会报红字错误。
2. Node.js 版本过低：OpenClaw 要求 Node.js ≥ 22，低于这个版本会各种报错。用 node -v 检查。
3. 改了配置不重启：修改 openclaw.json 后必须执行 openclaw gateway restart，否则不生效。
4. 防火墙没放行：Windows 首次启动 Gateway 时弹出的防火墙提示一定要点”允许”，否则网关无法工作。如果错过了，去 Windows 防火墙设置里手动添加。
5. npm 安装失败：国内网络访问 npm 官方源经常超时。配置镜像加速：npm config set registry https://registry.npmmirror.com
6. pnpm approve-builds 报错：这个命令目前在部分环境下有 bug，但不执行也不影响正常使用，直接忽略即可。
7. API Key 填错：复制 Key 时注意不要多空格，检查账户余额是否充足，确认所在地区支持该 API。
8. Skills 安装来源不安全：Snyk 安全报告显示 13.4% 的第三方 Skills 存在严重安全问题。只从 ClawHub 官方市场或有真实下载量的来源安装，不装来路不明的技能。
9. 命令找不到（command not found）：安装成功但终端找不到 openclaw 命令，通常是 PATH 没配好。执行 echo $PATH 检查，把全局包目录加入 PATH。
10. 权限过度授予：给 Skills 开权限时按需开放，别一股脑全给。敏感操作（发消息、删文件）让 AI 先问一句再动手。

十三、对比竞品：OpenClaw vs 其他 AI 工具

简单来说：如果你只需要聊天问问题，ChatGPT 够用；如果你需要 AI 真正帮你干活、操作电脑、管理文件，OpenClaw 是目前最完整的开源方案。

十四、总结与下一步行动

回顾一下这篇教程，你已经掌握了：

• OpenClaw 的核心定位——本地优先、模型无关的 AI 执行框架
• 跨平台安装流程——macOS/Linux/Windows/Docker 全覆盖
• Onboard 向导全流程——从模型配置到 Gateway 启动
• 四大核心概念——Soul File、Gateway、Skills、Memory
• Skills 安装与推荐——三种安装方式 + 新手必备清单
• 自动化实战——Cron 定时任务、Heartbeat 心跳检查、Hooks 事件钩子
• 成本控制——多模型路由 + 省钱策略
• 10 个新手常见坑及解决方案

建议的学习路径

第一周：完成安装配置，用 Web UI 体验基本对话，让 AI 帮你做 3-5 件简单任务（查文件、搜索信息、写总结）。

第二周：安装 5-10 个 Skills，尝试浏览器自动化和文件管理，接入一个聊天渠道（推荐飞书或 QQ）。

第三周：配置第一个 Cron 定时任务（每日晨报或邮件检查），编辑 Soul File 打造个性化 AI。

第一个月：建立完整的个人自动化工作流——日常办公、信息整理、定时汇报，把重复性事务交给龙虾。

OpenClaw 的核心价值在于：它不是一个你问它才答的工具，而是一个能主动干活、持续运行、越用越懂你的数字分身。花 30 分钟完成安装，再花 1 小时建立你的第一个自动化任务，你会发现原来每天可以省下这么多时间。

AI Agent 的时代已经到来，而你现在就站在浪潮的最前沿。准备好让你的小龙虾开工了吗？