新手推荐OpenClaw 完整多方式部署安装详细教程（全平台通用）

在这里插入图片描述

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

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

1. 系统兼容性

系统类型具体要求macOSmacOS 12+（Intel/Apple Silicon 均可）LinuxUbuntu 20.04+、Debian 11+、Fedora 38+ 等主流发行版WindowsWindows 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. 向导配置步骤（按终端提示操作）

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 辅助开发、自动化工作流等场景，大幅提升效率～