第2课：OpenClaw 极速体验【5分钟跑通第一个OpenClaw Agent】

上一节课我们认识了OpenClaw是什么——一个连接大模型与本地系统的“执行中枢”。你可能已经跃跃欲试，想知道：它到底能不能像传说中那样，5分钟就跑起来？

答案是：能。 不管你用Windows、Mac还是Linux，不管你是程序员还是非技术用户，这节课将带你亲手完成从零到一的完整部署。

“别让完美主义毁掉你的第一次尝试。”这是OpenClaw社区里广为流传的一句话。当你真正运行起第一个Agent并和它对话的那一刻，过去对“AI能办事”的一切抽象想象都会瞬间具体化——原来，让AI替我动手做事，就这么简单。

本节课的目标非常明确：在5到10分钟内，在你的电脑或云服务器上完成OpenClaw部署，配置好大模型API，并成功接收到第一条由AI自主执行的响应。

整个过程分为6步：

环境准备 → 一键安装 → 新手引导（配置模型和渠道） → 启动Gateway → 连接WebChat → 发送第一条指令 → 大功告成

每一步我都会给出可直接执行的命令，标注可能遇到的坑以及对应的解决方案，确保100%成功。

准备好了吗？让我们开始。

2.1 部署前的准备工作：系统要求与资源清单

一句话概括：OpenClaw对硬件和软件的门槛都很低——主流操作系统均可运行，最低2GB内存就能启动，但推荐配置会让你用得更流畅。

在实际部署之前，我们先花3分钟确认你的环境是否符合要求。这部分虽然是“准备工作”，但也是决定成败的关键一步。

操作系统要求

OpenClaw全面覆盖了三大主流操作系统：

操作系统	最低版本	推荐版本	备注
Windows	Windows 10	Windows 11	推荐配合WSL2使用以获得最佳体验
macOS	macOS 12	macOS 13或更新版本	原生支持，体验最佳
Linux	Ubuntu 22.04+	Ubuntu 24.04	其他发行版（Debian、CentOS）理论上也可运行

值得一提的是，腾讯云、阿里云、华为云等主流云平台均已提供OpenClaw一键部署镜像，可以跳过环境配置步骤，直接享受开箱即用的体验。

硬件配置要求

配置项	最低配置	推荐配置	说明
CPU	2核	2核（入门）/ 4-8核（复杂任务）	轻量模型可在CPU上运行
内存	2GB	4GB+（推荐）至8GB（复杂任务场景）	内存越大，同时运行的技能越流畅
存储空间	10GB	20GB+	主要存放依赖、日志和技能包
显卡（GPU）	不需要	6GB+显存（可选）	只有运行本地大模型时才需要

---

💡 特别说明：如果使用云端大模型（如阿里云百炼、OpenAI等），OpenClaw本体的资源消耗并不高，2核2GB的配置即可轻松运行。如果要运行本地Ollama模型（比如7B参数规模），8GB内存以上会有更好的体验。

软件依赖要求

OpenClaw的核心依赖只有Node.js。但根据你选择的安装方式，还可能需要Git和Python：

依赖组件	版本要求	是否需要手动安装	说明
Node.js	≥ v22	一键脚本自动安装	核心运行时环境
npm/pnpm	随Node.js自带	自动	包管理器
Git	任意较新版本	手动或自动	若从源码安装则需要；一键安装包通常内置
Python	3.7+	手动或自动	某些技能插件依赖Python

---

网络环境要求

场景	要求	说明
使用云端模型（百炼、OpenAI等）	需稳定外网连接	与模型API通信
使用本地模型（Ollama）	仅需内网或可离线	模型完全运行在本地设备
渠道通信（Telegram、飞书等）	需联网	接收和发送消息需要网络
完全离线部署	部分技能需调整	浏览器控制等某些任务需要联网

OpenClaw的官方安装脚本默认从GitHub下载，国内用户可能会遇到速度慢或超时问题。好在社区提供了国内镜像加速方案：

• npm镜像：可使用openclaw-cn汉化版，一键切换淘宝镜像源
• clawhub镜像站：技能商店镜像站地址为http://mirror-cn.clawhub.com，用于技能包的快速下载

权限要求

不同操作系统的权限要求如下：

• Windows：需要以管理员身份运行PowerShell
• macOS/Linux：部分命令需要sudo权限或安装开发者工具（如Xcode Command Line Tools）
• 常规操作用户权限足够

---

云部署还是本地部署？

在正式开始前，你还需要做一个选择：将OpenClaw部署在自己电脑上，还是部署在一台云端服务器上？两者的特点和适用场景如下：

维度	本地部署	云部署
适用用户	个人开发、测试、轻度使用	企业级7×24小时生产，需要远程访问的场景
数据隐私	数据完全存储在自己电脑，不外传	数据存储于服务器磁盘，通过互联网访问
开机即用	需要自己电脑保持开机	云端实例始终保持在线
维护成本	低（关机即停止）	需要关注云服务计费和实例状态
成本	0额外费用	云服务器需付费（低配实例最低约10美元/年）
建议场景	初次体验、学习教程	生产部署、团队协同、外部渠道接入

---

如果你的目标仅仅是体验和学习，推荐先在本地部署；如果你想让它成为7×24小时在线的个人助理或团队助手，云部署会是更持久的选择。

避坑指南：初次接触建议从本地部署开始

本地部署能让你更直观地理解OpenClaw的工作机制，也更容易进行调试和排查问题。你可以在完全掌握后再转向云端。别一上来就挑战云部署，免得被网络和安全配置打乱节奏。

2.2 Node.js v22+安装指南（Mac/Linux/Windows全平台）

一句话概括：Node.js是OpenClaw的基础运行环境，版本必须≥22.0.0——如果系统尚无此环境，官方一键安装脚本会帮你自动搞定。

⚠️【重要提醒】：如果你使用Windows一键安装包（.exe）或者云服务器OpenClaw镜像部署，本节完全可以跳过——依赖已经为你准备好了。本节仅供使用终端安装方式且当前Node版本低于22的用户参考。

在开始安装OpenClaw之前，先确认一下你的Node.js版本：

node -v

如果输出类似v22.14.0或更高版本，说明已满足要求，可以直接跳过本节。如果输出版本号低于22，或提示“command not found/未找到命令”，请按照你所在的平台执行以下操作。

Windows系统

方法一：使用Node Version Manager for Windows（推荐）

nvm-windows可以让你在多个Node版本间随时切换，避免版本冲突。

下载地址：github.com/coreybutler…

下载nvm-setup.exe安装包，双击运行按向导安装即可。安装完成后，打开管理员权限的PowerShell（开始菜单搜索PowerShell → 右键以管理员身份运行），执行：

nvm list available
nvm install 22
nvm use 22
node -v

方法二：直接下载官方安装包（.msi）

前往Node.js官网（nodejs.org），下载22.x LTS版本的.msi安装包，双击运行安装即可。这种方式最简单，但无法灵活切换版本。

macOS系统

使用nvm或homebrew都是不错的选择，但有系统依赖要求的用户更推荐先装Xcode Command Line Tools。

# 先安装Xcode Command Line Tools（如果尚未安装）
xcode-select --install

# 使用nvm安装Node v22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 重启终端后执行
nvm install 22
nvm use 22
node -v

或者使用homebrew（需要先安装homebrew包管理器）：

brew install node@22

Linux系统（Ubuntu/Debian）

# 添加NodeSource官方仓库
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装Node.js
sudo apt-get install -y nodejs

# 验证安装
node -v

如果安装npm包时网络缓慢

npm的默认官方源在国外，速度往往不稳定。建议配置淘宝镜像源来加速：

npm config set registry https://registry.npmmirror.com

# 验证配置是否成功
npm config get registry
# 应该输出 https://registry.npmmirror.com

---

配置完镜像源之后，后续的任何npm包安装命令都会自动走国内镜像，下载速度快很多。

避坑指南：为什么Windows最好用WSL2？

如果你在Windows上直接运行OpenClaw，某些需要文件系统深层交互的技能可能会报错或行为异常。官方文档强烈推荐使用WSL2（Windows Subsystem for Linux）作为运行环境——在Windows上安装Ubuntu子系统，然后在Linux环境中运行OpenClaw，体验接近原生Linux服务器，也是最接近生产环境配置的方案。

WSL2的安装方法：以管理员身份打开PowerShell，运行wsl --install，重启电脑后从开始菜单启动Ubuntu，即可得到完整的Linux环境。

2.3 OpenClaw一键安装与基础配置

一句话概括：OpenClaw提供了分平台专用的一键安装脚本，全程自动化，无需手动处理依赖——国内用户还有专门的加速镜像版可用。

OpenClaw官方提供了两种安装途径：

方式一：一键脚本安装（推荐，覆盖全部新手场景）

全平台通用，过程自动，不易出错。脚本会自动检测并安装缺失的Node.js等依赖，帮助你快速完成核心程序安装和环境变量配置。

【Windows用户】

用管理员身份打开PowerShell（开始菜单搜索PowerShell，右键选择“以管理员身份运行”）。

⚠️ 重要前置提醒：运行安装脚本之前，请按提供的准备步骤依次关闭全部安全防护软件（包括360、安全卫生/管家、火绒、Windows Defender实时防护等），否则安装过程中依赖的Shell命令操作和端口绑定可能被误判为恶意行为而拦截，导致安装失败。

执行以下命令：

# 官方源（海外/无需加速环境）
iwr -useb https://openclaw.ai/install.ps1 | iex

# 国内用户若下载缓慢，使用国内镜像加速脚本（更推荐）
iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

等待安装完成，全程无需手动操作，脚本会自动完成Node.js检测、核心程序安装、环境变量配置。

【macOS / Linux / WSL2用户】

打开终端，直接执行：

# 官方源
curl -fsSL https://openclaw.ai/install.sh | bash

# 国内加速镜像命令（网络环境受限时推荐）
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

等待脚本执行完成，全程自动完成环境配置。

方式二：包管理器安装（适合已有Node.js环境的开发者）

如果你已经安装了Node.js 22+且希望精确管控OpenClaw版本，可以使用npm或pnpm全局安装：

# 先确认Node版本≥22
node -v

# npm安装
npm install -g openclaw@latest

# 或使用pnpm（速度更快）
pnpm add -g openclaw@latest

# 国内用户可添加镜像源加速
npm install -g openclaw@latest --registry=https://registry.npmmirror.com

---

关于“openclaw-cn”汉化版

针对国内用户使用体验和访问延迟的问题，社区推出了中文适配版openclaw-cn。它在代码结构上完全相同，仅将原始版本的内部依赖改投国内网络，让后续技能包的获取变得更快速稳定：

npm install -g openclaw-cn@latest
openclaw-cn onboard --install-daemon
openclaw-cn gateway --port 18789 --verbose

对于入门阶段的用户，我推荐使用官方脚本直接安装原版或按照一键脚本路径操作即可，后面提到OpenClaw命令的行文中会继续用“openclaw”作为命令名来统一表达。

验证安装是否成功

所有安装方法完成之后，执行以下命令确认CLI是否可以调用：

openclaw --version

如果能看到类似openclaw/2026.5.0 darwin-arm64 node-v22.14.0的版本信息输出（具体数字可能随版本变化），说明OpenClaw本体已经被系统识别。如果显示“command not found/未找到命令”，则属于环境变量未配置完全，可参考搜到的以下排查步骤：

node -v          # Node是否已安装？
npm prefix -g    # 全局包位于何处？
echo $PATH       # 全局二进制目录是否在PATH中？

---

2.4 启动Gateway并连接WebChat界面

一句话概括：Gateway是OpenClaw的数据“总枢纽”——启动Gateway后才能通过WebChat界面与你的Agent聊天。

安装完成之后，下一步是启动OpenClaw的“核心中枢”——Gateway。它是连接你、AI模型和操作系统三方之间的消息路由器。

Gateway的两种运行模式

OpenClaw支持两种Gateway运行模式：

1. 后台守护进程模式（推荐生产环境） ：Gateway以系统服务形式在后台常驻运行，服务器重启后也会自动恢复。
2. 前台调试模式（推荐首次测试） ：Gateway在当前终端窗口直接运行，关闭终端就停止，方便观察实时日志。

推荐新手走“新手引导”（Onboarding）来完成首次启动

此时OpenClaw官方设计的流程是先建立配置文件、安装基础技能，再启动Gateway。官方最推荐的入门方式是运行交互向导：

openclaw onboard --install-daemon

向导会依次引导你完成以下配置：

• Gateway模式选择：建议选择“本地Gateway”模式，让OpenClaw拥有最高系统操作权限
• 大模型供应商配置（详细见2.5节） ：选择你要接入的模型，粘贴API Key，选择模型实例名称
• IM/通信渠道配置（可绕过） ：询问是否接入Telegram、飞书等，初次你可以跳过，之后选“tui”交互界面作为代替

**** 新手引导完成后，本地工作空间中会自动创建以下配置文件，这些正是你在第3课中将要详细学习的核心：

• ~/.openclaw/workspace/AGENTS.md
• ~/.openclaw/workspace/BOOTSTRAP.md
• ~/.openclaw/workspace/IDENTITY.md
• ~/.openclaw/workspace/USER.md

启动Gateway

新手引导完成之后，Gateway应该已经在后台运行了。如果你想手动管理Gateway状态，可以使用以下命令：

# 启动Gateway（后台守护进程）
openclaw gateway start

# 查看Gateway状态
openclaw gateway status

# 查看实时运行日志
openclaw logs

# 重启Gateway（修改配置后需要执行）
openclaw gateway restart

# 停止Gateway
openclaw gateway stop

---

连接到WebChat界面

Gateway启动后，你就可以通过WebChat界面和Agent对话了。WebChat有两种访问方式：

方式一：打开浏览器

Gateway默认会在本地的http://localhost:18789上启动Web服务。在浏览器地址栏输入http://127.0.0.1:18789，即可看到WebChat登录页面。

⚠️【安全提醒】：Gateway默认仅绑定本地回环地址127.0.0.1，外部无法直接访问。如需远程访问，请通过SSH隧道等安全通道进行转发，切勿简单将18789端口直接暴露在公网，以免引发严重的数据泄露和越权攻击。

方式二：macOS应用内置界面

macOS用户通过图形应用菜单中的“Lobster Menu”→“Open Chat”直接呼出聊天界面，非常方便：

# 用于测试时自动打开
dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat

初次启动的关键状态确认

Gateway启动时，终端或WebChat界面的右上角会显示“Gateway在线”或类似连接成功状态，此时你可以观察以下情况来判断是否正常：

• 命令行日志中出现类似Gateway running on port 18789或gateway started successfully的关键提示。
• WebChat界面的右上角显示一个✅绿色状态图标，说明Agent处于就绪状态。
• 第一次启动过程因为要初始化所有依赖，可能需要1-3分钟。下一次启动就很快了（几秒钟）。
• 登录WebChat时提示认证/授权——系统本身配置了默认共享密钥。如果你从未设置过密钥，会有一个安全令牌自动写到终端日志中（让你去Web控制台粘贴）。

---

避坑指南：Gateway离线了怎么办？

打开WebChat显示“Gateway离线”，这是新手最常见的故障之一。建议按以下顺序排查：

1. 检查Gateway是否正在运行：运行openclaw gateway status
2. 检查端口是否被占用：netstat -an | findstr 18789（Windows）或 lsof -i :18789（Mac/Linux）
3. 如果Gateway已经down了：执行openclaw gateway start再次启动
4. 杀毒软件拦截：观察是否因防火墙阻止了Gateway进程；如果是临时关闭杀软后重新启动
5. 检查配置文件：~/.openclaw/openclaw.json中gateway.mode是否已配置（不能为local以外的无效值）

2.5 配置第一个大模型API（阿里云百炼/OpenAI/本地Ollama）

一句话概括：OpenClaw不内置AI模型——你必须接入一个大模型才能让它拥有“思考能力”，本节课会示范配置本地Ollama、阿里云百炼和OpenAI三种最常见的方案。

你可能已经成功启动Gateway，并在WebChat界面上看到一个输入框。但此时如果你发一句话，Agent是不会回复的，因为OpenClaw本身“没有大脑”——它的思考能力来自你接入的大模型。如果缺少模型配置，OpenClaw就无法生成任何回复。

💡 核心原理：OpenClaw = 执行层（操作电脑）+ 大模型（理解和生成）。配置模型相当于给这只“龙虾”装上了一个真正会思考的大脑。

OpenClaw与主流模型的兼容性覆盖了几乎所有常见方案：只要遵循OpenAI API规范的任何大模型，都能够无缝接入OpenClaw配置体系。官方支持的模型包括：

• 国内模型：通义千问（阿里云百炼）、Kimi K2.5（月之暗面）、智谱GLM、火山豆包、腾讯混元、DeepSeek等
• 国际模型：OpenAI GPT系列、Anthropic Claude系列、Google Gemini系列
• 本地模型：Ollama本地量化模型（Qwen、DeepSeek、Phi等）

🧠 方案一：接入本地Ollama（最具隐私安全性，完全免费，可离线）

这个方案适合希望你希望AI完全运行在你自己的电脑上、数据不经过任何云服务器、也没有API费用风险的场景。Ollama提供了一个极其简洁的模型部署环境。你需要准备的是：

• 一台至少8GB内存的电脑
• 经过评估的足够存储空间（约6-10GB目标模型占用）
• 无需互联网连接（首次下载模型除外）

第1步：安装Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows（PowerShell管理员）
winget install Ollama.Ollama

---

第2步：拉取并启动一个适合你硬件的模型

# 最小资源消耗模型（入门选择，适合1.5B参数规模）
ollama run qwen2.5:1.5b

# 均衡版中英模型，推荐主流配置
ollama run qwen2.5:7b

# 推理增强模型
ollama run deepseek-r1:7b

---

⚠️【资源评估】：
- 1.5B模型：~1GB存储，可在仅CPU条件下流畅运行（入门推荐）
- 7B模型：~4.7GB存储，多轮对话上下文能力大幅强化（主流配备）
- 如果出现“显存不足”，使用更小的量化版本，或只调用qwen2.5:3b

第3步：通过openclaw onboard进行模型配置

在终端中执行openclaw onboard --install-daemon，然后在“Model and auth配置”步骤中：

• 选择“Ollama”作为模型供应商
• 当向导请求配置接入地址时，填写http://localhost:11434
• 选择刚刚拉取的模型名称（如qwen2.5:7b）

如果希望手动编辑配置文件，直接在~/.openclaw/openclaw.json中添加Ollama模型条目：

{
  "providers": [
    {
      "id": "ollama-local",
      "label": "Ollama Local",
      "type": "openai",
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": "ollama"
    }
  ],
  "primary": "ollama-local/models/qwen2.5:7b"
}

---

☁️ 方案二：接入阿里云百炼API（国内最稳定，免费额度充足）

面向国内开发者最省心稳定的云端接入方案。百炼平台支持通义千问系列模型，并提供固定月费套餐，成本可控。

第1步：获取API Key

1. 登录阿里云百炼控制台
2. 进入「API Key管理」→「创建API Key」
3. 系统会生成一个以“sk-”开头的密钥字符串，请立刻复制保存好（关闭页面后无法查看）
4. 推荐开通Coding Plan套餐作为成本控制——按月度固定费用收取，超出部分不再额外收费（仅接口报错），避免API费用失控

第2步：选择配置方法

方法一：通过openclaw onboard向导（新手最推荐）

运行openclaw onboard --install-daemon，向导到配置模型步骤时选择Bailian或Aliyun Bailian选项，按提示粘贴API Key，然后选择模型（推荐选qwen-plus，综合效果出色）。

方法二：手动编辑配置文件

在文件~/.openclaw/openclaw.json中添加模型配置：

{
  "providers": [
    {
      "id": "aliyun-bailian",
      "label": "Aliyun Bailian",
      "type": "openai",
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "apiKey": "sk-你的API-Key"
    }
  ],
  "primary": "aliyun-bailian/models/qwen-plus"
}

🌍 方案三：接入OpenAI API（国际开发者通用方案）

第1步：获取API Key

1. 登录OpenAI API 平台
2. 点击“Create new secret key”生成密钥
3. 复制并妥善保存密钥

第2步：配置OpenClaw

在~/.openclaw/openclaw.json中添加：

{
  "providers": [
    {
      "id": "openai",
      "label": "OpenAI",
      "type": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "sk-你的OpenAI-API-Key"
    }
  ],
  "primary": "openai/models/gpt-4"
}

验证模型配置是否成功

无论你选择了哪种方案，完成模型配置之后都需要执行以下验证步骤：

# 查看当前配置的模型（确认可用性）
openclaw models list

# 如果看到你刚刚添加的模型且状态为“active”，说明配置成功

配置有变动后，要记得重启Gateway：

openclaw gateway restart

---

⚠️【费用提醒】
- 阿里云百炼Coding Plan：按固定月费计费，成本完全可控。
- OpenAI API：按实际调用Token计费，请密切关注用量面板，避免意外的超额扣费。
- Ollama本地模型：完全免费，无任何调用限制。
- 个人体验阶段可以向Ollama轻量模型或百炼免费额度靠拢，不必提前承担费用风险。

2.6 发送第一条自然语言指令并见证Agent执行

一句话概括：关键的激动时刻——当你在WebChat中输入“你好”，如果能在几秒内收到有意义的回复，就说明你的整个部署以及模型配置都行得通啦！

模型已接入，Gateway已启动，WebChat界面已在眼前。现在发正式消息之前，不妨执行两条健康检查命令确认一切就绪：

openclaw health         # 如果看到OK，说明系统核心组件正确就位
openclaw models status  # 查看模型API是否已就绪

---

如果health命令看见“OK”字样，而models status状态也显示为“active”或“ready”，你就可以正式在WebChat界面发起第一条指令了。

第一条指令试试这些

为了让你获得可能更直观的成就感，这里提供三个不同难度级别的入门对话测试：

Level 1：基本对话测试

在WebChat界面的输入框中键入：

你好，请介绍一下你自己

预期行为：Agent会生成并返回一条文本消息，例如“你好！我是OpenClaw开源智能体框架下运行的Agent，可以通过连接你的本地系统来帮你完成文件处理、浏览器控制、消息管理等各种任务。”

Level 2：文件系统实操（有一定本地操作）

请帮我在桌面上创建一个名为“我的第一个OpenClaw Agent”的文件夹

预期行为：Agent调用文件技能，自动在桌面上建立一个新文件夹。

⚠️【安全警告】：文件创建是安全可控的基础文件操作，不会造成任何损害。但授予Agent对整个文件系统的读写权限后，理论上它可能删除或修改重要系统文件（如果下达了恶意指令）。因此，请避免将关键系统目录暴露给Agent，也不要随意下载来源不明的技能。本课节的涉及文件操作都需要进入策略确认实施之前得到书面明确。

Level 3：组合型任务测试（可选进阶）

在桌面上创建一个名为test.json的文件，写入{"status": "OpenClaw is running"}，然后格式化后再次展示给我。

预期行为：Agent先创建文件，再写入JSON格式内容，接着从中读取内容并将其格式刷并返回。

哪怕只完成Level 1，你已经让一个全功能AI Agent成功跑在自己的设备上并自主执行了第一次任务。这就是OpenClaw的魔力。

避坑指南：模型一直不回复怎么办？

如果发送消息后Agent迟迟没有响应，8-10秒都无回应：

1. 检查模型状态：运行openclaw models status，确认模型显示为“active”
2. 检查API Key额度：到云平台控制台查看API Key是否余额不足或已达配额
3. 检查Ollama服务：运行ollama list查看本地模型是否已正常启动
4. 查看Gateway日志：运行openclaw logs，搜索“ERROR”关键字定位具体问题

比如常见报错“No API key found for provider”通常意味着环境变量未配置正确，你只需在执行Gateway之前运行export OPENAI_API_KEY=sk-xxx或通过向导可视化配置即可。

2.7 常见启动错误与解决方案清单

任何新工具的首次运行都不会一帆风顺。这里按照可能出现的阶段整理一份高频报错及解决思路，旨在让你一遇到问题就能在最少时间内定位到出路。

阶段一：安装依赖阶段出错

问题现象	可能原因	解决方案
EBADENGINE — Node.js版本错误	Node版本过低或过高，不符合22+要求	nvm install 22、nvm use 22，然后重新运行安装。（参考2.2节）
下载/npm install缓慢、卡死	未切换国内镜像源	切换至淘宝镜像源：npm config set registry https://registry.npmmirror.com
安装脚本取资源超时	网络防火墙/节点超时	尝试用openclaw-cn汉化版命令进行安装，或者提前下载clawhub的技能包。
PowerShell报“禁止运行脚本”	系统脚本执行策略受限	管理员身份打开PowerShell后运行：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。
后台锁定错误	杀毒软件拦截	暂时关闭360、Windows Defender等防护软件；确保安装路径是纯英文。
Git clone失败	源码仓库连接不通	一键脚本安装已自动处理；或重复用包安装方案。

阶段二：Gateway启动报错

问题现象	可能原因	解决方案
Gateway拒绝启动	.openclaw/openclaw.json缺少关键合法性配置	运行openclaw onboard向导完成配置，或临时用openclaw gateway --allow-unconfigured --port 18789覆盖限制。
端口已被占用	18789端口被其他进程占用	`netstat -ano	findstr 18789`查看PI后终止或换端口启动。
启动后断开无日志	前台模式终止运行	改为后台守护方式启动：openclaw gateway start。
无法与Channel通信	渠道Token无效或权限不足	检查渠道应用（如QQ机器人）已批准加入群聊，重新生成Token。

阶段三：模型验证报错（API调用）

问题现象	可能原因	解决方案
401 Unauthorized	API Key失效或无效	重新生成一个有效Key并更新配置文件。
429 Rate Limit	额度不足/操作请求过量	检查账户余额，或切换到Ollama本地模型
模型没返回/Timeout	API服务过载/网络断流	使用curl测试API的连通性确认存活状态；尝试切换备用模型
“Model not found”	你填入的Model ID/实例名称拼错了	查询对应API文档的Model name，逐个核对。

终极自救技巧

当上述零散排查仍然无效时，求助通道：

1. 运行诊断命令：openclaw doctor会报告完整的检查结果和修复建议。
2. 查看完整日志：Linux后台日志通过journalctl -u openclaw-gateway -f；MacOS用户通过openclaw logs --follow。
3. 完全重置环境：备份~/.openclaw配置文件，卸载OpenClaw后重新按本文步骤安装（删除~/.openclaw，npm uninstall -g openclaw，全新运行openclaw onboard）。

2.8 本节小结

回顾全篇，我用一场“手把手式的流水线式操作”带你完成了：

• 系统环境核查和依赖软件的准备（Node 22+、Git等）
• 通过一键脚本或手工方式安装OpenClaw
• 熟悉Gateway的启动模式，并通过WebChat界面建立起对Agent的标准化聊天通道
• 手把手完成了三种主流模型（Ollama、阿里云百炼、OpenAI）的接入
• 体验了不同类型任务的自动执行，并获得了第一条AI回复
• 建立了一个简洁的避坑索引，能够自主排查绝大多数常见的故障

从“听说有这样一个AI”到“真正跑起来并听到它说你好”——这是OpenClaw入门分水岭中最为关键的一步。从这节课开始，AI已经从远方的“科幻概念”开始走进你的现实，成为能够和你日常沟通的数字助理。

2.9 课后习题

1. 自我测试运行

请在你的浏览器中打开OpenClaw的WebChat，然后输入“帮我列举出当前工作目录下有哪些文件”。检查Agent的回答——如果是“我无法执行此操作”或各种模型错误，回来检查：

• 你是否配置了模型Api Key并且模型处于有效状态；
• Agent的相关文件系统技能有没有默认被安装；
• Gateway是否拥有系统级读写权限。

2. 多模型对比

同时配置Ollama本地模型和阿里云百炼云端模型（如果可行的话），每次发同一个问题给两种模型，比较回答的质量差异和反应耗时差异。哪个任务对本地模型有天然的数据隐私优势？

3. 分享你的成功记录

在你创建的第一条对话中，Agent的自主执行导致你感到惊讶的点是什么？将这条聊天记录复制下来，在下一次社群或社区中向更多人展示，推动更多人进入AI Agent的门槛。

4. 隐患思考

参考本节的安全红线，想一想：如果有人不经过你的允许也可以向你的本地OpenClaw发送文件删除指令，会发生什么？查阅资料思考应该在本地系统里设置哪几层保护防线？

5. 预习下一课

阅读本节配置Onboarding时生成的工作区内的AGENTS.md文件中的内容（位于~/.openclaw/workspace/），猜猜哪些文字是用来描述Agent角色和任务的——这是第3课的重点内容，会完整讲解！

---

🔗《30节课精通 OpenClaw》系列课程导航

去订阅

第一部分（第1-5课）：基础认知与入门部署——解决“这是什么、怎么搭建”的问题。

第二部分（第6-10课）：核心原理深度剖析——解决“底层怎么工作”的问题。

第三部分（第11-15课） ：应用场景与平台集成——解决“能用来做什么”的问题。

第四部分（第16-21课） ：技能开发与定制扩展——解决“如何自己扩能力”的问题。

第五部分（第22-26课）：高级特性与性能优化——解决“怎么用得更好”的问题。

第六部分（第27-30课） ：安全、运维与生态进阶——解决“如何安全可靠地规模化”的问题。