第 2 章 从零开始安装 OpenClaw
🚀 本章特色：在上一章中，我们了解了 OpenClaw 是什么以及它为什么值得关注。本章正式动手，从依赖软件准备到一键安装、初始化配置、首次启动，手把手带你完成 OpenClaw 的本地部署。整个过程通常只需几十分钟，不需要任何编程基础。
本章目录：
| 节 | 内容 | 你将学到 |
|---|---|---|
| 1 | 安装前的准备 | 硬件要求、操作系统支持、网络环境 |
| 2 | 依赖软件：Node.js 与 Git | 两个必备依赖的作用和安装方法 |
| 3 | 安装 OpenClaw | CMD 和 PowerShell 两种一键安装方式 |
| 4 | 初始化配置 | 选择模型、配置 API Key、绑定聊天渠道 |
| 5 | 启动与首次使用 | 启动 Gateway、访问控制台、发送第一条消息 |
| 6 | 常见问题排查 | 安装失败、网络超时、权限问题的解决方案 |
| 7 | 总结与进阶 | 核心知识回顾、课后练习 |
1. 安装前的准备
1.1 硬件要求
在开始安装之前，先确认你的电脑满足以下基本要求：
| 硬件 | 最低要求 | 推荐配置 | 说明 |
|---|---|---|---|
| CPU | 双核处理器 | 四核及以上 | OpenClaw 本身轻量，但浏览器自动化会消耗较多资源 |
| 内存 | 4 GB | 8 GB 及以上 | 多代理并行时内存消耗更大 |
| 硬盘 | 2 GB 可用空间 | 10 GB 及以上 | 会话历史、记忆文件、技能模块都需要存储空间 |
| 网络 | 稳定的互联网连接 | 带宽 10 Mbps 以上 | 需要访问大模型 API 和安装依赖包 |
OpenClaw 本身是一个轻量级的 Node.js 应用，对硬件要求并不高。真正的计算密集任务（大模型推理）发生在云端 API 服务器上，你的电脑主要负责消息路由、工具执行和本地文件管理。
1.2 操作系统支持
OpenClaw 支持以下操作系统：
- 🔹 Windows：Windows 10 及以上（本书主要面向 Windows 用户）
- 🔹 macOS：macOS 12 (Monterey) 及以上
- 🔹 Linux：Ubuntu 20.04、Debian 11、Fedora 36 及以上主流发行版
本书的安装步骤以 Windows 为主。macOS 和 Linux 用户可以参考 OpenClaw 官方文档（https://docs.openclaw.ai）完成安装，核心流程相似，只是包管理器和路径约定有所不同。
1.3 网络环境
安装过程中需要从互联网下载以下内容：
| 下载内容 | 来源 | 大小 | 说明 |
|---|---|---|---|
| OpenClaw 安装包 | npm 仓库 | 约 50 MB | 核心程序及其依赖 |
| Node.js | nodejs.org | 约 30 MB | 安装脚本会自动处理 |
| 技能模块 | GitHub | 不等 | 部分技能需要从 GitHub 克隆代码 |
如果你的网络环境无法直接访问上述地址（比如公司内网有限制），可以考虑使用代理或镜像站。国内用户可以通过 npm 镜像加速安装：
npm config set registry https://registry.npmmirror.com
简单来说：一台近五年内购买的电脑，加上稳定的网络连接，就足够运行 OpenClaw 了。
确认硬件和网络没有问题后，接下来安装两个必备依赖。
2. 依赖软件：Node.js 与 Git
OpenClaw 的运行依赖 Node.js，部分内置技能（Skills，结构化的指令文件集合）的安装和更新依赖 Git。这两个工具是 OpenClaw 能在你的电脑上正常工作的基础。
2.1 Node.js：JavaScript 运行时
Node.js（JavaScript 运行时引擎） 是一个让 JavaScript 可以脱离浏览器独立运行的平台。OpenClaw 本身使用 TypeScript 编写，需要 Node.js（版本 ≥ 22.16）来运行。
Node.js 不仅提供运行环境，还自带了包管理器 npm（Node Package Manager），OpenClaw 及其依赖包都通过 npm 来安装和管理。你可以把 npm 理解为"JavaScript 世界的软件商店"，你需要什么工具，一条命令就能下载安装。
好消息是：OpenClaw 的安装脚本会自动为你检测并安装 Node.js，大多数情况下无需手动操作。
如果你因网络或其他原因需要手动安装，可以从官网下载最新版本：
https://nodejs.org/dist/v24.19.0/node-v24.19.0-x64.msi
安装时一路点击"下一步"即可，安装程序会自动将 Node.js 添加到系统环境变量。安装完成后，打开命令提示符验证：
node --version
npm --version
正常情况下会输出类似以下内容：
v24.19.0
10.x.x
看到版本号就说明 Node.js 已经就位了。
2.2 Git：版本控制系统
Git（分布式版本控制系统） 是程序员日常协作开发的基础工具。OpenClaw 在安装或更新某些技能时会通过 Git 从 GitHub 拉取代码，因此也需要提前装好。
⚠️ 重要提醒：Git 不会随 OpenClaw 安装脚本自动安装，你必须手动完成这一步。 安装脚本会检查 Git 是否已就位，只有检测通过才会继续后续步骤。
安装步骤：
- 访问官方下载页面：https://git-scm.com/install/windows
- 下载安装程序（如果下载速度慢，可以使用清华大学或华为云的镜像站加速）
- 运行安装程序，务必勾选"Add Git to PATH"，这样 OpenClaw 才能在命令行中直接调用 Git
- 其他选项保持默认即可
安装完成后，打开命令提示符验证：
git --version
正常情况下会输出：
git version 2.47.0.windows.1
下面用一张表总结两个依赖的要点：
| 依赖 | 作用 | 是否自动安装 | 验证命令 |
|---|---|---|---|
| Node.js (≥ 22.16) | 运行 OpenClaw 核心程序 | ✅ 安装脚本自动处理 | node --version |
| Git | 克隆和更新技能模块 | ❌ 必须手动安装 | git --version |
两个依赖都就绪后，就可以安装主角 OpenClaw 了。
3. 安装 OpenClaw
OpenClaw 在 Windows 下提供了两种一键安装方式。推荐使用 CMD 批处理脚本安装，兼容性更好，出错时更容易排查。
3.1 方式一：CMD 批处理安装（推荐）
按 Win + R 打开运行窗口，输入 cmd 回车，打开命令提示符，然后执行以下命令：
curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
这条命令做了三件事：
┌──────────────────────────────────────────────────────┐
│ 一键安装命令的三步流程 │
│ │
│ ① curl -fsSL ... -o install.cmd │
│ 从官网下载安装脚本 │
│ │ │
│ ▼ │
│ ② install.cmd │
│ 执行安装脚本： │
│ - 检测 Node.js 版本 │
│ - 安装或升级 Node.js（如需要） │
│ - 通过 npm 安装 OpenClaw │
│ - 配置环境变量 │
│ （通常需要 10 到 30 分钟，取决于网络速度） │
│ │ │
│ ▼ │
│ ③ del install.cmd │
│ 删除临时脚本文件，保持系统整洁 │
└──────────────────────────────────────────────────────┘
📌 小提示：该命令依赖 Windows 自带的
curl.exe，Windows 10 及以上版本通常已预装。如果你的系统版本较旧没有 curl，可以手动从浏览器下载安装脚本后运行。
3.2 方式二：PowerShell 一键安装
如果你习惯使用 PowerShell，也可以用它来安装。打开 PowerShell（普通用户权限即可，无需管理员），执行：
iwr -useb https://openclaw.ai/install.ps1 | iex
这条命令的含义：
- 🔹
iwr（Invoke-WebRequest）从官网下载安装脚本 - 🔹
iex（Invoke-Expression）将脚本内容立即执行 - 🔹 脚本会自动检测环境、安装 Node.js（如需要）、配置环境变量，并完成 OpenClaw 的安装
3.3 验证安装
无论使用哪种方式安装，安装完成后都需要验证。运行以下命令查看版本：
openclaw --version
正常情况下会输出类似以下内容：
OpenClaw 2026.7.1-2 (0790d9f)
还可以查看帮助信息，确认所有子命令都可用：
openclaw --help
🦞 OpenClaw 2026.7.1-2 (0790d9f) — All your chats, one OpenClaw.
Usage: openclaw [options] [command]
看到类似输出，说明安装成功。
如果安装过程中遇到问题，不要着急，本章第 6 节列出了常见问题和解决方案。安装成功后，接下来进行首次配置。
4. 初始化配置
安装完成后，首次运行需要进行基础配置。这一步会确定 OpenClaw 使用哪个大模型、如何连接你的聊天工具、数据存放在哪里。
4.1 运行初始化向导
在命令提示符中执行：
openclaw setup
该命令会启动一个交互式向导，引导你完成以下设置：
┌──────────────────────────────────────────────────────┐
│ openclaw setup 配置向导流程 │
│ │
│ ① 选择大语言模型 │
│ OpenAI / Anthropic / 通义千问 / Ollama（本地） │
│ │ │
│ ▼ │
│ ② 配置 API 密钥 │
│ 填入对应模型供应商的 API Key │
│ （选择本地模型则跳过此步） │
│ │ │
│ ▼ │
│ ③ 绑定聊天渠道 │
│ Telegram Bot Token / 微信 / Discord 等 │
│ （可以稍后再配置） │
│ │ │
│ ▼ │
│ ④ 设置工作目录与日志级别 │
│ 一般保持默认即可 │
│ │ │
│ ▼ │
│ 配置完成！ │
└──────────────────────────────────────────────────────┘
4.2 选择大语言模型
这是配置中最关键的一步。OpenClaw 支持多种大语言模型供应商：
| 模型供应商 | 代表模型 | 价格区间 | 适合场景 |
|---|---|---|---|
| Anthropic | Claude Sonnet 4 | 较高 | 代码、复杂推理、长文写作 |
| OpenAI | GPT-4o、GPT-4.1 | 中高 | 通用对话、创意写作 |
| 通义千问 | qwen-max、qwen-plus | 较低 | 中文场景性价比高 |
| Ollama | Llama 3、Qwen 2 | 免费（本地） | 离线体验、隐私敏感场景 |
💡 建议：如果你暂时不想注册付费模型，可以先选择 Ollama 本地模式，完全离线运行，零成本体验。不过需要说明的是，本地模型受硬件限制，响应速度较慢、回答质量也不如主流云端模型，适合尝鲜和测试，不建议作为日常主力使用。
4.3 配置 API 密钥
如果选择了云端模型，你需要提供对应的 API Key（应用程序接口密钥，用于身份验证和计费的字符串）。
获取 API Key 的一般步骤：
- 访问模型供应商的官方网站，注册账号
- 进入开发者控制台或 API 管理页面
- 创建一个新的 API Key
- 复制 Key 并粘贴到 OpenClaw 的配置向导中
⚠️ 安全提醒：API Key 相当于你的"钱包钥匙"，持有它的人可以用你的额度调用模型服务。请妥善保管，不要分享给他人，也不要提交到公开的代码仓库中。
4.4 绑定聊天渠道
你可以在这一步绑定一个或多个聊天渠道。最常见的是 Telegram，因为它配置最简单：
- 在 Telegram 中搜索
@BotFather - 发送
/newbot，按提示创建一个新的机器人 - 复制 BotFather 返回的 Bot Token
- 粘贴到 OpenClaw 的配置向导中
其他渠道（微信、Discord、Slack 等）可以在后续使用中逐步配置，不必一次全部完成。渠道配置的详细方法将在第 9 章深入讲解。
配置完成后，就可以启动 OpenClaw 了。
5. 启动与首次使用
5.1 启动 Gateway
Gateway（网关，OpenClaw 的核心调度服务） 是 OpenClaw 的"中枢神经"，负责连接所有聊天渠道，并将消息路由给 AI 智能体。在命令行中运行：
openclaw gateway
启动后，Gateway 会在后台持续运行，等待消息到来。你会在终端看到一系列启动日志，确认各个模块加载正常。
如果你想让 Gateway 在后台静默运行（不占用命令行窗口），可以使用：
openclaw gateway --daemon
5.2 打开 Web 控制面板
OpenClaw 提供了一个基于浏览器的管理界面（Control UI，Web 端仪表盘），让你可以可视化管理整个系统。打开方式有两种：
方式一：在命令行执行
openclaw dashboard
系统会自动打开默认浏览器并跳转到控制面板。
方式二：直接在浏览器地址栏输入
http://localhost:18791
5.3 发送第一条消息
在控制面板的聊天界面中，输入一条简单的消息试试：
你好，介绍一下你自己
如果一切正常，几秒钟后你会收到 AI 的回复。🎉 恭喜，你的 OpenClaw 已经成功运行了！
第一次对话通常会触发 BOOTSTRAP 引导流程（详见第 6 章），智能体会和你互相认识，确定它的名字、性格和角色。按照提示完成引导即可。
5.4 控制面板功能一览
在 Dashboard 中，你可以：
- 🔹 查看实时聊天记录和会话状态
- 🔹 管理已安装的 Skills（技能模块）
- 🔹 监控节点状态，包括手机等配对设备
- 🔹 调试浏览器自动化任务
- 🔹 查看 Token 消耗和费用统计
- 🔹 配置代理和路由规则
控制面板是你日常管理 OpenClaw 的主要入口，建议收藏到浏览器书签。
首次使用成功后，接下来看看安装过程中可能遇到的问题及解决方案。
6. 常见问题排查
安装过程中可能会遇到各种问题。以下是社区用户反馈最多的几个场景和对应的解决方案。
6.1 Node.js 版本过低
现象：安装脚本报错 Node.js version >= 22.16 required。
原因：系统中已安装了旧版本的 Node.js，版本不满足要求。
解决方案：
# 查看当前版本
node --version
# 如果版本低于 22.16，卸载旧版本后重新安装
# 或者直接访问 https://nodejs.org 下载最新 LTS 版本
6.2 npm 安装超时
现象：安装过程中出现 npm ERR! network timeout 或长时间卡在某一步。
原因：网络环境不稳定，无法顺畅访问 npm 官方仓库。
解决方案：切换到国内镜像源：
npm config set registry https://registry.npmmirror.com
然后重新运行安装命令。
6.3 Git 未安装或未加入 PATH
现象：安装脚本提示 git: command not found 或 Git is not installed。
原因：Git 没有安装，或者安装时没有勾选"Add Git to PATH"。
解决方案：
- 从 https://git-scm.com/install/windows 下载并安装 Git
- 安装时务必勾选"Add Git to PATH"
- 安装完成后重新打开命令提示符（旧的终端窗口不会自动刷新 PATH）
6.4 API Key 配置错误
现象：启动后发送消息，收到 Authentication failed 或 Invalid API key 错误。
原因：API Key 填写有误，或者 Key 已过期、余额不足。
解决方案：
- 登录模型供应商的官网，确认 Key 的状态和余额
- 重新生成 Key 并通过以下命令更新配置：
openclaw setup
- 在向导中重新输入正确的 API Key
6.5 端口被占用
现象：启动 Gateway 时报错 Port 18791 is already in use。
原因：已有另一个 OpenClaw 实例在运行，或者其他程序占用了 18791 端口。
解决方案：
# 查看哪个进程占用了端口
netstat -ano | findstr 18791
# 如果是旧的 OpenClaw 进程，先停止它
taskkill /PID <进程号> /F
# 然后重新启动
openclaw gateway
下面用一张表汇总常见问题：
| 问题 | 现象关键词 | 快速解决 |
|---|---|---|
| Node.js 版本过低 | version >= 22.16 required |
升级到最新 LTS 版本 |
| npm 安装超时 | network timeout |
切换到 npmmirror 镜像 |
| Git 未安装 | git: command not found |
安装 Git 并勾选 Add to PATH |
| API Key 错误 | Authentication failed |
检查 Key 状态和余额 |
| 端口被占用 | Port 18791 already in use |
停止旧进程或更换端口 |
7. 总结与进阶
7.1 本章核心知识回顾
本章带你完成了 OpenClaw 从零到一的全部安装过程。回顾一下关键步骤：
安装前确认硬件和网络满足要求。安装两个必备依赖：Node.js（安装脚本自动处理）和 Git（必须手动安装）。通过一键安装命令完成 OpenClaw 的安装。运行 openclaw setup 完成模型选择、API Key 配置和渠道绑定。启动 Gateway，打开控制面板，发送第一条消息验证安装成功。
整个流程可以用下图总结：
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 环境检查 │ ──→│ 安装依赖 │ ──→│ 安装 │ ──→│ 初始化 │ ──→│ 首次启动 │
│ 硬件/网络 │ │ Git │ │ OpenClaw │ │ setup │ │ gateway │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
7.2 下一步建议
- 🔹 验证安装：在 Dashboard 中发送一条测试消息，确认能正常收到 AI 回复
- 🔹 熟悉控制面板：浏览 Dashboard 的各个功能页面，了解系统的整体布局
- 🔹 安全第一：首次使用建议在非生产环境测试，谨慎授予敏感权限（如文件系统写入、浏览器控制等），确认一切正常后再逐步放开
- 🔹 加入社区：访问 openclaw.bjbook.net 获取最新教程和常见问答
7.3 课后练习
-
基础题：按照本章步骤完成 OpenClaw 的安装，在控制面板中发送"你好"并确认收到回复。截图记录
openclaw --version的输出结果。 -
进阶题：创建一个 Telegram Bot 并绑定到 OpenClaw。在 Telegram 中向你的 Bot 发送一条消息，确认能收到 AI 回复。记录下整个配置过程中遇到的任何问题。
-
思考题：如果你需要在公司内网（无法直接访问外网）安装 OpenClaw，你会怎么解决网络限制问题？列出你能想到的所有可行方案。
本章完
本文为《OpenClaw 实战指南》系列第 2 篇。下一章，我们将深入 OpenClaw 的典型使用场景，看看它到底能帮你做些什么。