OpenClaw完整安装教程2026：全平台通用详解

OpenClaw 这个 AI 助手，功能确实强大——支持本地部署、能接入 GLM-4.6 和 Claude 等多款模型，还能搞定代码辅助、自动化工作流这些核心场景。不过，对新手来说，拿到安装指南往往就傻眼了。所以这里直接梳理一份零基础友好、全平台兼容、并且可以直接复制命令来操作的完整指南。包括一键安装、手动安装、Docker 部署、GLM-4.6 模型配置以及常见的奇葩问题排查。跟着走，新手也能在 10 分钟内搞定。

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

1. 系统兼容性

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. 向导配置步骤（按终端提示操作）

1. 选择网关类型：新手推荐「Local Gateway（本地网关）」，不用额外折腾服务器；
2. 选择 AI 模型提供商：

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

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

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

1. 配置聊天平台（可选）：可以连接 Telegram、Discord 等，新手直接跳过也没问题；
2. 安装后台守护进程：

• 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）。在浏览器打开后：

1. 进入「模型测试」页面；
2. 输入测试指令：你好，请用 GLM-4.6 介绍自己；
3. 如果你收到包含「GLM-4.6」关键词的回复，恭喜，安装 + 配置全部成功。

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

想在 VS Code 里直接调用 GLM-4.6 辅助开发？操作很简单：

1. 打开 VS Code → 扩展面板（Ctrl+Shift+X）；
2. 搜索「OpenClaw」→ 安装官方插件（Anthropic 认证）；
3. 插件会自动读取 ~/.openclaw/ 目录下的配置，不需要额外设置；
4. 使用方式：右键代码 → 选择「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 辅助开发、自动化工作流等场景，效率直接起飞～

来源：互联网