OpenClaw 本地部署详细教程（Windows+Mac 双系统）

前言：OpenClaw 是一款开源本地优先 AI 代理平台，支持接入飞书、钉钉、Telegram 等多渠道，可实现自动化任务、文件处理、定时调度等能力，核心优势是数据本地存储、隐私性强，且支持对接各类大模型与自定义技能。本文针对 Windows（10+）和 Mac（12+）两大主流桌面系统，提供保姆级本地部署教程，全程可复现，同时整理部署过程中 90% 新手会遇到的问题及解决方案，帮助开发者快速避坑、完成部署。

温馨提示：部署前确保设备满足基础要求------内存≥4GB（推荐8GB+），磁盘剩余空间≥500MB，全程需联网（调用云端AI模型需稳定网络，本地模型可后续配置离线使用）；所有操作路径禁止含中文、空格及特殊字符，避免安装失败或服务异常。

一、前置准备（双系统通用）

无论 Windows 还是 Mac 系统，部署前需完成以下基础准备，避免后续因依赖缺失导致部署失败：

确认系统版本：Windows 需为 10 及以上（64位，推荐 Windows 11）；Mac 需为 macOS 12.0（Monterey）及以上，支持 Intel 芯片和 Apple Silicon（M1/M2/M3）芯片。
安装核心依赖 Node.js：OpenClaw 强制要求 Node.js ≥ 18.x，推荐 v22 LTS 版本（低版本会直接导致不兼容报错），双系统安装方式不同，下文分系统详细说明。
安装 Git（可选，源码编译需用）：部分部署方式需要 Git 支持，避免出现"git: command not found"报错，双系统安装方式见下文对应章节。
网络配置：国内用户建议提前切换 npm 淘宝镜像，解决依赖下载超时问题，命令通用（后续部署中会补充）；关闭第三方杀毒软件、防火墙（或后续放行对应端口），避免拦截服务启动。

二、Windows 系统本地部署步骤（新手首选一键部署）

Windows 系统推荐「PowerShell 一键部署」（新手友好，无需手动配置复杂环境），同时补充「WSL2+Docker 隔离部署」（进阶用户，避免环境冲突），按需选择即可。

2.1 方案一：PowerShell 一键部署（新手首选，10分钟搞定）

步骤1：解锁 PowerShell 脚本权限

Windows 默认禁止运行远程脚本，不解锁权限会导致安装命令直接报错，操作如下：

按下 Win+S，搜索"PowerShell"，右键选择「以管理员身份运行」（必须管理员权限，否则权限不足）；
输入以下命令，按回车执行，允许当前用户运行远程脚本：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

执行后提示"是否要更改执行策略"，输入 Y 回车确认，权限解锁完成。

步骤2：一键安装 OpenClaw 主程序

关闭管理员 PowerShell，重新打开「普通权限 PowerShell」（避免管理员权限导致后续配置异常）；
输入官方一键安装命令，脚本会自动检测环境、安装适配版本的 Node.js（≥v22）、配置环境变量及主程序，全程自动完成：

bash 复制代码

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

补充说明：安装耗时 3-10 分钟（取决于网络速度），过程中不要关闭终端，长时间无响应可按回车刷新；终端显示"OpenClaw installed successfully"即为安装完成。

可选优化（解决国内下载超时）：若安装过程中出现 network timeout 报错，先执行以下命令切换淘宝镜像，再重新执行安装命令：

bash 复制代码

npm config set registry https://registry.npmmirror.com pnpm config set registry https://registry.npmmirror.com

步骤3：初始化配置（Onboarding 向导）

安装完成后，在同一 PowerShell 窗口输入以下命令，启动交互式配置向导，新手全程按默认选项+快速启动即可：

bash 复制代码

openclaw onboard

向导配置核心步骤（新手推荐选项）：

运行模式：选择 QuickStart（快速启动），跳过复杂高级配置；
模型提供商：无 API Key 选择 Skip for now（暂不配置），后续可在配置文件补充；有 OpenAI、Anthropic 等 Key 可直接选择对应厂商输入；
默认模型：直接回车，保持默认配置；
渠道对接：选择 Skip for now，暂不配置 Telegram、飞书等第三方渠道；
技能配置：选择 Yes，启用基础技能（文件操作、搜索等）；
其余高级配置（API 密钥、钩子等）：全部选择 Skip for now，向导自动完成初始化。

步骤4：启动服务与网页端访问

初始化完成后，输入以下命令启动网关服务（OpenClaw 核心服务，负责连接聊天平台和 AI 代理）：

bash 复制代码

openclaw gateway start

终端提示"Gateway started successfully"，说明服务启动完成（默认端口 18789）。

网页端访问与授权：
1. 打开浏览器，输入访问地址：http://127.0.0.1:18789；
2. 首次访问提示"未授权：令牌缺失"，需获取授权令牌：打开路径 C:\Users\你的Windows用户名\.clawdbot，找到 clawdbot.json 文件，右键用记事本打开，查找"token"字段，复制引号内的长字符串（切勿泄露）；
3. 回到网页端，粘贴令牌并点击授权，页面正常加载即为部署成功。

2.2 方案二：WSL2+Docker 隔离部署（进阶稳定版）

该方案通过 WSL2（Linux 子系统）+Docker 实现环境隔离，彻底避免与本地 Windows 环境冲突，适合长期使用，需先配置 WSL2 和 Docker Desktop。

步骤1：启用 WSL2 与安装 Linux 子系统

以管理员身份打开 PowerShell，执行以下命令启用 WSL2 和虚拟机平台：

bash 复制代码

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart wsl --set-default-version 2

命令执行完成后，重启电脑生效；
重启后，再次打开管理员 PowerShell，安装 Ubuntu 22.04 LTS 子系统：

bash 复制代码

wsl --install -d Ubuntu-22.04

安装完成后，自动打开 Ubuntu 终端，按提示设置用户名和密码（密码输入不显示，正常输入即可）；输入 wsl -l -v 验证，显示 Ubuntu 22.04 且版本为 2 即为成功。

步骤2：安装 Docker Desktop

访问 Docker 官网下载 Windows 版本：https://www.docker.com/products/docker-desktop/；
双击安装包，全程默认安装，勾选"添加桌面快捷方式"，安装完成后重启电脑；
打开 Docker Desktop，同意协议（无账号可跳过登录），在设置中开启 WSL2 集成（Settings→Resources→WSL Integration，开启 Ubuntu 22.04 集成）。

步骤3：Docker Compose 部署 OpenClaw

打开 Ubuntu 子系统终端，创建英文项目目录：

bash 复制代码

mkdir -p ~/openclaw && cd ~/openclaw

创建 docker-compose.yml 配置文件，输入以下内容（持久化配置，避免容器重启后配置丢失）：

bash 复制代码

version: '3.8' services: openclaw: image: openclaw/openclaw:latest ports: - "18789:18789" volumes: - ~/.openclaw:/root/.openclaw env_file: ~/.openclaw/.env restart: unless-stopped

执行以下命令启动容器，完成部署：

bash 复制代码

docker-compose up -d

容器启动后，打开浏览器访问 http://127.0.0.1:18789，按提示获取令牌并授权即可使用。

三、Mac 系统本地部署步骤（原生适配，支持 Apple Silicon）

Mac 系统部署核心依赖 Homebrew 包管理器，步骤简洁，原生支持 Apple Silicon（M1/M2/M3）和 Intel 芯片，推荐「Homebrew+npm 全局安装」（稳定且便于后续升级）。

3.1 步骤1：安装 Homebrew（包管理器，必装）

Homebrew 是 Mac 上最流行的软件包管理工具，用于安装 Node.js 等依赖，操作如下：

打开 Mac 自带的 Terminal（终端，可通过 Launchpad 搜索找到）；
输入以下命令，按回车执行，根据提示输入 Mac 管理员密码（输入不显示），等待安装完成：

bash 复制代码

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，输入 brew --version 验证，显示版本号即为安装成功。

3.2 步骤2：安装 Node.js（核心依赖）

通过 Homebrew 安装 Node.js（推荐 v20 及以上版本，适配 OpenClaw 所有功能），操作如下：

在终端输入以下命令，安装 Node.js：

bash 复制代码

brew install node@20

可选：安装最新稳定版 Node.js，命令为 brew install node。

验证安装：输入以下命令，显示版本号即为成功（Node.js 版本≥18.x）：

bash 复制代码

node --version npm --version

补充：若命令不生效，需配置环境变量（根据芯片类型区分）：

Apple Silicon（M1/M2/M3）芯片：

bash 复制代码

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

Intel 芯片：

bash 复制代码

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

3.3 步骤3：安装 OpenClaw 主程序

在终端输入以下命令，全局安装 OpenClaw（需管理员权限，输入密码确认）：

bash 复制代码

sudo npm install -g openclaw

补充：若遇到权限不足报错，可执行以下命令跳过权限校验安装：

bash 复制代码

npm install -g openclaw --unsafe-perm=true

验证安装：输入 openclaw --version，显示版本号即为安装成功。

3.4 步骤4：启动网关服务与网页端访问

Mac 系统推荐使用 LaunchAgent 方式启动服务，实现开机自启动，操作如下：

安装并启动 LaunchAgent（自动创建服务配置）：

bash 复制代码

openclaw gateway install

检查服务状态：输入以下命令，显示"Service: Loaded、Gateway: running on port 18789"即为启动成功：

bash 复制代码

openclaw gateway status

备用方案（手动启动）：若 LaunchAgent 方式不生效，输入以下命令手动启动网关（后台运行）：

bash 复制代码

nohup node node_modules/openclaw/dist/index.js gateway --port 18789 > ~/openclaw_gateway.log 2>&1 & echo $!

网页端访问：方式1：终端输入 open http://localhost:18789/，自动打开浏览器；
方式2：手动打开 Safari/Chrome，输入 http://localhost:18789/；
首次访问需获取令牌：终端输入以下命令提取令牌，复制后粘贴到网页端授权即可：

bash 复制代码

TOKEN=$(grep -oP '"token": "\K(^")+' ~/.openclaw/openclaw.json) echo $TOKEN

Mac 系统推荐使用 LaunchAgent 方式启动服务，实现开机自启动，操作如下：

安装并启动 LaunchAgent（自动创建服务配置）：

bash 复制代码

openclaw gateway install

检查服务状态：输入以下命令，显示"Service: Loaded、Gateway: running on port 18789"即为启动成功：

bash 复制代码

openclaw gateway status

备用方案（手动启动）：若 LaunchAgent 方式不生效，输入以下命令手动启动网关（后台运行）：

bash 复制代码

nohup node node_modules/openclaw/dist/index.js gateway --port 18789 > ~/openclaw_gateway.log 2>&1 & echo $!

3.5 步骤5：初始化配置（可选，与 Windows 一致）

终端输入 openclaw onboard，按交互式向导完成模型配置、渠道对接等操作，新手可选择 QuickStart 快速启动，跳过复杂配置。

四、部署后验证（双系统通用）

部署完成后，通过以下3步验证服务是否正常运行，避免后续使用出现异常：

验证服务状态：终端输入 openclaw gateway status，确认网关处于 running 状态；
验证版本与环境：输入 openclaw doctor，诊断 Node.js 版本、依赖、配置文件及网络连接，无报错即为正常；
功能测试：网页端授权后，发送消息"你能做什么？"，若能正常回复，说明部署成功且可正常使用。

五、常见问题及解决方案（90% 新手踩坑汇总）

部署过程中遇到报错不要慌，以下是高频问题及解决方案，覆盖双系统常见场景，按报错现象快速定位即可。

5.1 基础环境类问题（双系统通用）

问题1：Node.js 版本不兼容，报错"unsupported node.js version"

现象：安装或启动时报错，伴随服务闪退、依赖安装失败、模块找不到等问题；

根因：OpenClaw 强制要求 Node.js ≥ 18.x，低版本完全不兼容（新手最易踩坑）；

解决方案：

Windows：卸载旧版 Node.js，重新安装官方 LTS 版本（v22 优先），安装后重启终端验证；
Mac：通过 Homebrew 升级 Node.js，命令：brew upgrade node，升级后验证版本。

问题2：依赖下载超时，报错"network timeout"

现象：npm 下载依赖时卡住，提示网络超时、依赖拉取失败；

根因：国内网络访问 npm 官方源速度慢，导致下载失败；

解决方案：切换淘宝镜像，永久生效，终端输入以下命令：

bash 复制代码

npm config set registry https://registry.npmmirror.com pnpm config set registry https://registry.npmmirror.com

问题3：Git 未安装，报错"git: command not found"

现象：脚本执行失败，终端提示 Git 命令不存在；

解决方案：

Windows：安装 Git for Windows，安装时勾选"添加到系统 PATH"，安装后重启终端；
Mac：终端输入 brew install git，通过 Homebrew 安装，安装后验证 git --version。

5.2 安装与权限类问题（双系统通用）

问题4：全局安装权限不足，报错"EPERM/EACCES"

现象：Windows 提示"EPERM: operation not permitted"；Mac/Linux 提示"EACCES: permission denied"；

解决方案：

Windows：不要用管理员 CMD/PowerShell，切换为普通权限执行安装命令；
Mac：修复 npm 权限，避免使用 sudo 安装，终端输入以下命令：

bash 复制代码

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

问题5：安装完成后，报错"openclaw command not found"

现象：输入 openclaw 相关命令，终端提示命令无法识别；

根因：npm 全局路径未添加到系统环境变量；

解决方案：

终端输入 npm config get prefix，获取 npm 全局路径；
将该路径添加到系统环境变量（Windows 需手动添加到 PATH，Mac 执行 echo 命令添加，参考前文环境变量配置）；
重启终端，输入 openclaw --version 验证。

5.3 网关服务类问题（双系统通用）

问题6：启动网关报错"listen EADDRINUSE :::18789"

现象：启动网关时失败，提示端口 18789 被占用；

解决方案：

Windows：终端输入以下命令，杀死占用端口的进程：

bash 复制代码

netstat -ano | findstr :18789
taskkill /PID 进程号 /F

Mac：终端输入以下命令，杀死占用端口的进程：

bash 复制代码

lsof -ti:18789 | xargs kill -9

可选：修改配置文件指定自定义端口，命令：openclaw config set gateway.port 自定义端口（如 18790）。

问题7：网页访问提示"gateway token missing""401 Unauthorized"

现象：网页访问 http://127.0.0.1:18789，提示未授权、令牌缺失；

解决方案：

Windows：找到路径 C:\Users\你的Windows用户名\.clawdbot\clawdbot.json，复制"token"字段内容，粘贴到网页端授权；
Mac：终端输入以下命令提取令牌，复制后粘贴到网页端授权：

bash 复制代码

TOKEN=$(grep -oP '"token": "\K(^")+' ~/.openclaw/openclaw.json)
echo $TOKEN

问题8：网关启动失败、服务崩溃

现象：输入启动命令后，终端无成功提示，或启动后立即闪退；

解决方案：

查看服务状态：openclaw gateway status；
查看实时日志，定位报错原因：openclaw logs --follow；
强制重装服务：openclaw gateway install --force，重装后重新启动。

5.4 系统专属问题

Windows 专属：PowerShell 脚本执行报错"无法加载文件，因为在此系统上禁止运行脚本"

根因：未解锁 PowerShell 脚本执行权限；

解决方案：重新执行前文"2.1 步骤1"，解锁脚本权限，确保命令执行成功后再进行安装。

Windows 专属：WSL2 宿主机无法访问网关（WSL 内启动正常，Windows 浏览器无法访问）

现象：WSL2 内启动 OpenClaw 网关后，Windows 浏览器输入 http://127.0.0.1:18789 无法访问；

解决方案：网关绑定 0.0.0.0，同时 Windows 防火墙放行 18789 端口，直接用 localhost:18789 访问。

Mac 专属：LaunchAgent 启动失败，无法实现开机自启动

现象：执行 openclaw gateway install 后，检查服务状态显示未加载；

解决方案：手动删除 LaunchAgent 配置文件，重新安装，命令如下：

bash 复制代码

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
rm ~/Library/LaunchAgents/ai.openclaw.gateway.plist
openclaw gateway install

5.5 模型与配置类问题

问题：模型调用失败，报错"all models failed""401/404"

现象：配置 API Key 后，无法调用模型，提示 401 未授权、404 模型不存在、429 限流；

解决方案：

检查 API Key 格式：确保以 sk- 开头，无多余空格；
验证 BaseURL：部分厂商需带 /v1 后缀，检查配置文件是否正确；
确认账户余额充足、API 权限已开通；
关闭代理，确保网络可正常连通模型厂商服务器。

六、总结与后续优化

本文覆盖 Windows（一键部署+Docker 隔离部署）和 Mac 系统的 OpenClaw 本地部署全流程，步骤简洁可复现，同时汇总了部署过程中高频踩坑点及解决方案，新手可按步骤操作，进阶用户可选择 Docker 隔离部署提升稳定性。

后续优化建议：

定期升级 OpenClaw：Windows/Mac 通用命令（npm 安装）：npm update -g openclaw@latest；
配置本地模型：通过 Ollama 部署本地大模型，实现离线使用，提升隐私性；
对接第三方渠道：参考官方文档，配置飞书、钉钉等渠道，实现多平台调用 OpenClaw；
备份配置文件：定期备份 ~/.openclaw 目录下的配置文件，避免重装系统或误操作导致配置丢失。

如果部署过程中遇到本文未覆盖的问题，可查看 OpenClaw 官方文档（https://openclaws.io/zh/install/），或在评论区留言交流，笔者会及时回复补充。