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（全平台）

1. macOS：

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

1. Linux（Ubuntu/Debian）：

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

1. 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.0npm -v   # 示例输出：10.5.0

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

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

# Linuxsudo apt install git# macOSbrew install git# Windows官网下载：https://git-scm.com/download/win

1. 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/WSL2curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

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

（1）全局安装 OpenClaw

# 基础安装（所有系统）npm install -g openclaw@latest# macOS/Linux 权限不足时，添加 sudosudo npm install -g openclaw@latest# 国内用户加速（可选，切换 npm 镜像）npm config set registry https://registry.npmmirror.comnpm 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.gitcd openclaw# 2. 启动容器docker-compose up -d

（3）进入容器执行配置

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

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

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

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

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

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

1. 启动配置向导

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

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

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

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

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

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

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

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

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

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

1. 主配置目录：~/.openclaw/（Linux/macOS/WSL2）、C:Users你的用户名.openclaw（Windows）；
2. 模型认证配置：~/.openclaw/agents/[agentId]/agent/auth-profiles.json；
3. 日志文件：~/.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. 安装失败 / 权限不足

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

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

# 方案1：忽略全局 libvipsSHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest# 方案2：手动安装 libvipsbrew install vipsnpm install -g openclaw@latest

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

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

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

1. 查看端口占用：

# Linux/macOSlsof -i :3000# Windows（PowerShell）netstat -ano | findstr :3000

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

5. 配置不生效

1. 删除旧配置目录，重新初始化：

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

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

七、总结

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

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

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