OpenClaw 本地电脑零基础安装保姆级教程

OpenClaw 是一款强大的个人 AI 助理。为了让完全没有技术开发基础的朋友也能顺利在自己的电脑上运行它，本教程将避开复杂的代码编译，采用最简单的“一键安装”和可视化操作方式。

一键安装教程

第一步：准备“AI 大脑” (获取 API Key) OpenClaw 只是一个躯壳，它需要接入大语言模型才能进行智能思考。对于国内用户，推荐直接申请并使用智谱 AI (GLM) 或通义千问 (Qwen) ，这两个模型对中文理解极佳，且对新用户非常友好、注册简便。

1. 前往智谱 AI 或通义千问的开放平台官网。
2. 注册账号并进入“控制台”或“API 管理”页面。
3. 点击“生成新的 API Key”，你会得到一串很长的字符。请将这串字符复制并保存在一个记事本里，稍后配置时需要用到。

第二步：安装“运行环境” (Node.js) 就像玩大型电脑游戏需要预装游戏运行库一样，OpenClaw 需要一个叫 Node.js 的基础环境才能在电脑上跑起来。

1. 打开浏览器，搜索并进入 Node.js 官网。
2. 在首页下载标注着“LTS (长期支持版)”的安装包（系统要求 Node.js 版本在 22 或以上）。
3. 下载后双击运行，像安装普通软件一样全程点击“下一步 (Next)”直到完成。安装完毕后，请务必重启一次电脑。

第三步：安装 OpenClaw 系统 OpenClaw 的底层开源代码托管在多个平台上，如果你想了解或后续深入学习，可以通过 GitCode 访问它的源码仓库：OpenClaw 源码仓库 (GitCode)。 **注意：**对于没有开发经验的朋友，极其不推荐直接下载源码并手动配置编译环境（容易遇到各种报错卡关）。为了顺利上手，请直接使用官方专为新手准备的“自动化安装口令”：

• 如果你使用的是 Windows 电脑：

  1. 点击桌面左下角的“开始”菜单，搜索 PowerShell。
  2. 在搜索结果中，右键点击“Windows PowerShell”，选择“以管理员身份运行”。
  3. 在弹出的蓝底黑字窗口中，复制并粘贴下面这行指令，然后按下回车键（Enter）： iwr -useb https://openclaw.ai/install.ps1 | iex
  4. 放下鼠标耐心等待。屏幕上会滚动很多代码和进度条，直到它自动停下并提示安装成功。

• 如果你使用的是苹果 Mac 电脑：

  1. 按下键盘上的 Command + 空格 键，搜索 终端 (或 Terminal) 并打开。
  2. 复制并粘贴下面这行指令，然后按下回车键（Enter）： curl -fsSL https://openclaw.ai/install.sh | bash

第四步：激活与配置 (初始化向导) 安装完成后，继续在刚才敲指令的黑框窗口里，输入以下指令并回车，开始给 AI 助理注入灵魂： openclaw onboard 此时屏幕上会出现问答式的配置向导：

1. 选择模型 (Model Provider) ：使用键盘上下方向键，选择你第一步准备好的模型（如 Zhipu 或 Qwen），按回车确认。
2. 输入密钥 (API Key) ：将你第一步保存在记事本里的那一长串字符粘贴进去，按回车。
3. 接下来的各种高级设置选项（如是否连接 Telegram、微信等第三方工具），如果不确定怎么填，可以一路按回车键跳过。这些功能以后随时可以在可视化网页里用鼠标慢慢配置。

第五步：进入可视化中文面板 配置结束后，我们要进入类似普通软件一样好用的后台控制面板。

1. 在窗口中输入最后一条指令启动面板并按回车： openclaw dashboard
2. 此时，你的电脑浏览器会自动弹出一个网页（如果没有自动弹出，请手动在浏览器地址栏输入 http://127.0.0.1:18789）。
3. 页面会提示你需要输入一个 Token（安全密钥） 来验证身份。回到你刚才的命令行窗口，里面会有一行写着类似 Token: xxxx-xxxx-xxxx 的字样。把后面的这串密钥复制下来，粘贴到浏览器的密码框里即可。
4. 登录成功！现在你可以完全脱离枯燥的命令行代码，直接用鼠标点击的方式给你的 AI 助理分配任务、连接日常办公软件了。

面对不同系统的电脑，安装教程一样吗？

核心原理一样，但具体操作指令和遇到问题的概率完全不同。

最终通过浏览器访问的那个“可视化中文面板”在所有系统上长得都一样，但在把系统“搭”起来的前期过程中，差异很大：

Windows 电脑（包括各类 Windows 迷你主机/AI 盒子，如零刻 SER9 Pro 等）：

差异： 使用的是 PowerShell 或 CMD 命令行。

难点： Windows 系统的权限管理和执行策略比较严格，经常会拦截安装脚本。而且，如果在安装过程中涉及底层 C++ 依赖的编译，Windows 往往会提示缺少 Visual Studio Build Tools，这对非程序员来说是灾难级的体验，解决起来需要额外下载几个 G 的编译工具。

苹果 Mac 电脑（macOS）：

差异： 使用的是“终端 (Terminal)”。底层是类 Unix 系统，与开发环境天生比较契合。

难点： 总体安装比 Windows 顺畅，但遇到权限问题时需要频繁使用 sudo 命令并输入密码。如果是采用 M 系列芯片（Apple Silicon）的新款 Mac，极少数老旧的依赖包可能会存在架构不兼容的情况，不过对于 OpenClaw 这类新项目通常影响不大。

Linux 系统：

差异： 完全依靠代码和终端操作。

难点： 仅适合有一定基础的用户或被用作服务器。它不需要图形界面，但需要熟练掌握包管理工具（如 apt 或 yum）。

用户在安装 OpenClaw 时最常遇到的四大“拦路虎”及其解决办法

1. 网络连接超时或下载失败（最常见）

• 现象： 命令行里出现红色的 Timeout、Failed to connect 报错，或者进度条卡在某一个百分比一动不动。国内用户在从 GitHub 或相关镜像拉取依赖时极易遇到。

• 解决办法： * 对于 Node.js 的包管理器（npm），可以配置国内镜像源来加速下载。在命令行中输入并回车：npm config set registry https://registry.npmmirror.com/。

  • 如果在拉取 GitCode 源码或核心组件时依然卡顿，建议非技术用户在网络相对空闲的时段重试，或者检查本地的网络代理设置是否影响了命令行的网络请求。

2. API 密钥（API Key）配置错误或欠费

• 现象： 安装成功，面板也能打开，但给 AI 发消息时，它回复 Unauthorized、Invalid API Key 或 Insufficient Quota。

• 解决办法： * 如果是复制粘贴的问题，请检查密钥前后是否多复制了空格。

  • 如果使用的是智谱 AI 或通义千问（Qwen）等模型，新用户的免费额度可能已经过期或耗尽。需要登录对应的开发者控制台，检查账单状态，必要时充值几块钱即可恢复。

3. “找不到命令” (Command Not Found)

• 现象： 提示 node不是内部或外部命令 或 openclaw: command not found。
• 解决办法： 这是因为电脑不知道去哪里找这个软件。通常是因为在安装 Node.js 时，没有勾选 "Add to PATH"（添加到环境变量） 。最简单的解决办法是卸载 Node.js，重新安装一遍，并确保安装过程中勾选了所有默认的选项，安装完务必重启电脑。

4. 权限不足被系统拦截

• 现象： 屏幕提示 Permission denied，或者 Windows 提示“因为在此系统上禁止运行脚本”。

• 解决办法： * Windows： 需要给 PowerShell 放行。以管理员身份打开 PowerShell，输入 Set-ExecutionPolicy RemoteSigned，按回车，然后输入 Y 确认。

  • Mac： 有些指令前需要加管理员权限，例如将 npm install 换成 sudo npm install，然后输入电脑的开机密码（输入时屏幕不会显示字符，输完直接回车即可）。

自动化排障脚本

第一阶段：环境自检与静默安装（扫清最大障碍）：小白用户最容易卡在 Node.js 环境的配置上。脚本运行后的第一件事，必须是环境侦测。

• 逻辑： 自动执行 node -v 命令。
• 分支 A（已安装）： 如果有版本号返回，且版本符合要求（如 >= 22），则直接进入下一阶段。
• 分支 B（未安装或版本过低）： 脚本自动中断，弹出友好的中文提示：“检测到您的电脑缺少运行所需的 Node.js 核心组件。正在为您自动下载并安装，请稍候...”。
• 动作： 脚本后台通过国内镜像源下载 Node.js 的免安装版或独立安装包，并静默配置好环境变量，避免用户去官网下载时遇到网络卡顿或忘记勾选配置项。

第二阶段：国内网络环境优化（解决 80% 的报错）：由于 OpenClaw 需要拉取许多依赖包，直接连外网极易发生 Timeout（超时）报错。

• 逻辑： 在下载任何组件之前，脚本强制将包管理器的下载源切换为国内高速通道。
• 动作： 自动执行 npm config set registry https://registry.npmmirror.com/。并在屏幕上提示：“正在为您切换至国内高速网络通道...”。

第三阶段：源码拉取与构建：避开国外的 GitHub，直接使用国内速度更稳定的 GitCode。

• 逻辑： 检查本地是否已有 OpenClaw 文件夹。
• 动作： 如果没有，脚本自动从 GitCode 的克隆链接拉取代码（或直接解压你预先打包好并放在同级目录的压缩包，这种方式对小白最稳妥）。然后自动执行依赖安装命令。

第四阶段：大模型 API 引导配置（可视化输入）：这是唯一需要用户手动参与的环节，但我们要让它变得极度简单。

• 逻辑： 脚本运行到此处时，弹出一个简单的输入框（可以使用 PowerShell 的 UI 模块调用一个简易窗口）。
• 动作： 提示文字为：“请输入您的智谱 AI 或通义千问 API Key（若还没有，请点击这里获取：[附带注册链接]）”。用户输入完成后，脚本自动将这串密钥写入到 OpenClaw 的本地配置文件（如 .env 文件）中，无需用户去繁杂的命令行里做问答式配置。

第五阶段：一键启动与浏览器唤醒

• 逻辑： 启动本地服务。
• 动作： 脚本自动执行 npm start（或对应的启动命令）。并设置一个 3-5 秒的延迟，随后自动调用电脑的默认浏览器，打开 http://127.0.0.1:18789 可视化面板，让用户直接看到最终成果。

极简版的 Windows 批处理（.bat）逻辑演示

如果你要自己编写这个脚本，骨架代码大概长这样（仅供参考逻辑）：

chcp 65001 >nul
title OpenClaw 一键安装与启动助手

echo ========================================
echo      欢迎使用 OpenClaw 智能助理一键安装
echo ========================================
echo.

:: 1. 检测 Node.js
node -v >nul 2>&1
if %errorlevel% neq 0 (
    echo [警告] 未检测到 Node.js 环境！
    echo 正在为您准备下载链接，请下载安装后重新运行此脚本。
    :: 这里可以替换为自动下载解压逻辑
    pause
    exit
)

:: 2. 优化网络
echo [进度] 正在优化国内网络环境...
npm config set registry https://registry.npmmirror.com/

:: 3. 安装依赖 (假设源码已和此脚本在同级目录)
echo [进度] 正在安装核心组件，这可能需要几分钟，请耐心等待...
call npm install

:: 4. 引导输入 API Key
echo.
set /p apiKey="请输入您的通义千问或智谱 AI 的 API Key 并按回车: "
echo MODEL_PROVIDER=qwen> .env
echo API_KEY=%apiKey%>> .env

:: 5. 启动服务
echo [成功] 配置完成！正在启动您的 AI 助理...
start http://127.0.0.1:18789
call npm run start

pause