OpenClaw 完整安装教程详解(2026最新版,全平台通用)

2026-03-04 15:09:02 南啸天

OpenClaw 是一款强大的 AI 助手工具，支持本地部署、多模型接入（含 GLM-4.6、Claude 等），可实现代码辅助、自动化工作流等核心能力。本文整理零基础友好、全平台兼容、可直接复制发布的安装指南，包含一键安装、手动安装、Docker 部署、GLM-4.6 模型配置及常见问题排查，新手也能 10 分钟快速上手。

一、系统与环境要求（必看）

1. 系统兼容性

系统类型	具体要求
macOS	macOS 12+（Intel/Apple Silicon 均可）
Linux	Ubuntu 20.04+、Debian 11+、Fedora 38+ 等主流发行版
Windows	Windows 10/11（必须开启 WSL2，原生 Windows 仅支持 PowerShell 脚本，兼容性有限）

2. 核心依赖（提前安装）

OpenClaw 基于 Node.js 开发，必须先安装 Node.js v20+（推荐 v22 LTS 版本），步骤如下：

（1）安装 Node.js（全平台）

macOS：

\# 方式1：Homebrew 安装（推荐，自动配置环境）
brew install node@22
\# 方式2：官网下载 pkg 安装包
\# 地址：https://nodejs.org/zh-cn/download/

Linux（Ubuntu/Debian）：

\# 添加 Node.js 源
curl -fsSL https://deb.nodesource.com/setup\_22.x | sudo -E bash -
\# 安装 Node.js
sudo apt-get install -y nodejs

Windows（WSL2）：

\# 同 Linux 步骤，在 WSL2 终端执行
curl -fsSL https://deb.nodesource.com/setup\_22.x | sudo -E bash -
sudo apt-get install -y nodejs

（2）验证安装

终端执行以下命令，输出版本号即成功（Node.js 版本需 ≥v20.0.0）：

node -v  # 示例输出：v22.0.0
npm -v   # 示例输出：10.5.0

（3）可选依赖（提升兼容性）

Git：用于源码安装 / 工具更新，推荐安装：

\# Linux
sudo apt install git
\# macOS
brew install git
\# Windows
官网下载：https://git-scm.com/download/win

pnpm：替代 npm，安装速度更快、磁盘占用更小：

npm install -g pnpm

二、3 种安装方式（按需选择）

方式 1：官方一键安装（新手首选，3 分钟搞定）

自动检测系统环境、安装缺失依赖（如 Node.js）、全局部署 OpenClaw 并启动配置向导，全程无需手动干预，适合零基础用户：

（1）macOS/Linux/WSL2

终端执行以下命令：

curl -fsSL https://openclaw.ai/install.sh | bash

（2）Windows（PowerShell 管理员权限）

打开「管理员模式 PowerShell」，执行：

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

（3）跳过配置向导（仅安装 CLI，高级用户）

\# macOS/Linux/WSL2
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

方式 2：npm 手动安装（适合已装 Node.js 用户）

（1）全局安装 OpenClaw

\# 基础安装（所有系统）
npm install -g openclaw@latest
\# macOS/Linux 权限不足时，添加 sudo
sudo npm install -g openclaw@latest
\# 国内用户加速（可选，切换 npm 镜像）
npm config set registry https://registry.npmmirror.com
npm install -g openclaw@latest
\# 若 sharp 依赖安装失败（macOS 常见问题）
SHARP\_IGNORE\_GLOBAL\_LIBVIPS=1 npm install -g openclaw@latest

（2）验证安装

openclaw --version  # 输出版本号即成功，示例：v1.8.2

方式 3：Docker 部署（隔离环境，稳定不污染系统）

适合服务器部署、多环境隔离场景，无需手动安装 Node.js，步骤如下：

（1）安装 Docker Desktop

官网下载：https://www.docker.com/products/docker-desktop/，安装后启动 Docker 服务（需等待服务初始化完成）。

（2）拉取并启动 OpenClaw 容器

\# 方式1：直接使用官方镜像（推荐）
docker run -d \\
  \--name openclaw \\
  -p 3000:3000 \\
  -v \~/.openclaw:/root/.openclaw \\
  openclaw/openclaw:latest
\# 方式2：通过 docker-compose 启动（更灵活）
\# 1. 克隆仓库（可选）
git clone https://github.com/openclaw/openclaw.git
cd openclaw
\# 2. 启动容器
docker-compose up -d

（3）进入容器执行配置

docker exec -it openclaw bash
openclaw onboard --install-daemon

方式 4：源码安装（开发者 / 贡献者）

适合二次开发、定制功能场景，步骤如下：

\# 1. 克隆源码仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
\# 2. 安装依赖并构建
pnpm install
pnpm ui:build  # 构建前端界面
pnpm build
\# 3. 全局链接并启动配置向导
pnpm link --global
openclaw onboard --install-daemon

三、初始化配置（核心步骤）

安装完成后，必须执行初始化向导，完成模型接入、网关配置、后台服务部署，步骤如下：

1. 启动配置向导

\# 启动向导并安装后台守护进程（开机自启）
openclaw onboard --install-daemon

2. 向导配置步骤（按终端提示操作）

选择网关类型：新手推荐「Local Gateway（本地网关）」，无需额外服务器；
选择 AI 模型提供商：

接入 GLM-4.6：选择「Custom/Other」（自定义模型）；
接入 Claude：选择「Anthropic」，直接输入 Claude API Key；

配置 GLM-4.6（重点步骤）：

输入智谱 AI API Key（从智谱开放平台获取：注册→登录→API 密钥管理→创建密钥）；
输入 Base URL：https://open.bigmodel.cn/api/anthropic；
输入模型名称：glm-4.6（区分大小写，不可修改）；

配置聊天平台（可选）：可连接 Telegram、Discord 等，新手可直接跳过；
安装后台守护进程：

macOS：自动配置 launchd，支持开机自启；
Linux/WSL2：自动配置 systemd，支持开机自启；
Windows：自动配置系统服务，后台运行。

3. 配置文件路径（重要）

后续修改配置、查看日志可访问以下路径：

主配置目录：~/.openclaw/（Linux/macOS/WSL2）、C:\Users\你的用户名\.openclaw\（Windows）；
模型认证配置：~/.openclaw/agents/[agentId]/agent/auth-profiles.json；
日志文件：~/.openclaw/logs/。

四、启动与验证

1. 启动 OpenClaw 服务

\# 启动服务（后台运行）
openclaw start
\# 查看服务状态
openclaw status
\# 停止服务
openclaw stop
\# 重启服务（配置修改后需执行）
openclaw restart

2. 验证 GLM-4.6 模型

服务启动后，终端会显示 Web 控制台地址（默认：http://localhost:3000），浏览器打开后：

进入「模型测试」页面；
输入测试指令：你好，请用 GLM-4.6 介绍自己；
收到包含「GLM-4.6」关键词的回复，即表示安装 + 配置成功。

五、VS Code 插件集成（可选）

在 VS Code 中直接调用 GLM-4.6 辅助开发，步骤如下：

打开 VS Code → 扩展面板（Ctrl+Shift+X）；
搜索「OpenClaw」→ 安装官方插件（Anthropic 认证）；
插件会自动读取 ~/.openclaw/ 目录下的配置，无需额外设置；
使用方式：右键代码 → 选择「OpenClaw：代码解释 / 重构 / 补全」，或使用快捷键 Ctrl+Shift+P 调用命令。

六、常见问题排查（避坑指南）

1. 安装失败 / 权限不足

Linux/macOS：命令前添加 sudo（如 sudo npm install -g openclaw@latest）；
Windows：必须以「管理员身份」打开 PowerShell 执行安装脚本；
npm 权限报错：执行 sudo chown -R $USER:$GROUP ~/.npm（Linux/macOS）修复权限。

2. sharp 依赖安装失败（macOS 常见）

\# 方案1：忽略全局 libvips
SHARP\_IGNORE\_GLOBAL\_LIBVIPS=1 npm install -g openclaw@latest
\# 方案2：手动安装 libvips
brew install vips
npm install -g openclaw@latest

3. GLM-4.6 调用报错（401/403 / 模型不存在）

检查 API Key：是否正确、未过期、有 GLM-4.6 调用权限；
确认 Base URL：必须为 https://open.bigmodel.cn/api/anthropic（不可多斜杠 / 少斜杠）；
模型名称：严格为 glm-4.6（区分大小写）；
重启服务：openclaw restart 使配置生效。

4. 服务无法启动 / 端口占用

查看端口占用：

\# Linux/macOS
lsof -i :3000
\# Windows（PowerShell）
netstat -ano | findstr :3000

杀死占用进程：kill -9 进程ID（Linux/macOS），或在任务管理器结束对应进程（Windows）；
修改端口：编辑 ~/.openclaw/config.json，修改 port 字段为其他端口（如 3001），重启服务。

5. 配置不生效

rm -rf \~/.openclaw  # Linux/macOS/WSL2
openclaw onboard --install-daemon

重启终端 / 电脑，确保环境变量生效。

七、总结

OpenClaw 安装核心流程：安装 Node.js → 选择安装方式（一键 / 手动 / Docker）→ 初始化配置 GLM-4.6 → 启动服务验证。

新手用户：优先选择「官方一键安装」，全程自动化，无需手动配置；
服务器部署：推荐「Docker 部署」，环境隔离，稳定不污染系统；
开发者：选择「源码安装」，支持二次开发与功能定制。

配置完成后，即可在本地 Web 控制台、VS Code 中高效调用 GLM-4.6，实现 AI 辅助开发、自动化工作流等场景，大幅提升效率～

到此这篇关于OpenClaw 完整安装教程详解(2026最新版,全平台通用)的文章就介绍到这了,更多相关OpenClaw安装教程内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！