Windows、macOS、Linux三系统本地部署OpenClaw+避坑指南+Docker一键部署,30分钟搞定

2026-03-10 16:02:48 脚本之家

这是一份全网最全的OpenClaw安装部署教程，覆盖Windows、macOS、Linux三系统本地部署，并最终提供Docker一键部署方案。所有命令均可直接复制执行，包含完整的docker-compose.yml文件和安全操作命令。

一、部署方案对比：先选你的路

部署方式	适用场景	优点	缺点
Windows本地	日常个人电脑使用	数据本地存储，操作便捷	权限配置稍复杂，防火墙需放行
macOS本地	Mac用户日常使用	环境统一，配合Homebrew顺滑	需安装Xcode Command Line Tools
Linux本地	开发机/长期运行	稳定高效，资源占用低	命令行操作，对新手略硬核
Docker部署	推荐方案	环境隔离，跨平台统一，一键迁移，安全可控	需安装Docker，稍多一步

如果你是新手或希望长期稳定使用，直接跳至第六章「终极方案：Docker一键部署」。

二、准备篇

2.1 Node.js（必需）

OpenClaw运行环境，必须 ≥ v22.x。

node -v   # 检查版本

2.2 API Key（必需）

OpenClaw需要“大脑”——大模型API。推荐国内用户使用阿里云百炼（免费额度充足）或MiniMax。

阿里云百炼获取：登录阿里云百炼控制台 → 密钥管理 → 创建API-Key，保存 Access Key ID 和 Access Key Secret。
备用方案：OpenAI、Anthropic Claude等需海外网络。

2.3 终端工具

Windows：以管理员身份运行 PowerShell（右键点击选择）
macOS/Linux：终端（Terminal）

三、Windows 11本地部署

3.1 解锁PowerShell执行权限

Set-ExecutionPolicy Bypass -Scope Process -Force

输入 Y 确认。

3.2 一键安装OpenClaw

# 官方稳定版脚本
iwr -useb https://openclaw.ai/install.ps1 | iex

如果慢或用国内镜像：

iwr -useb https://clawd.org.cn/install.ps1 | iex

等待5-10分钟，自动安装Node.js及依赖。

3.3 验证安装

openclaw --version
# 应输出如 2026.3.2-beta.1

3.4 配置并启动服务

openclaw config set gateway.mode local   # 设为本地模式
openclaw gateway install                  # 安装为Windows计划任务（开机自启）
openclaw gateway start                     # 启动服务
openclaw gateway status                     # 检查状态，应为Running

3.5 访问Web控制台

浏览器打开：http://127.0.0.1:18789。

3.6 Windows常见问题

问题	解决
node -v 不是内部命令	安装Node.js时未勾选“Add to PATH”，重装勾选
端口18789被占用	netstat -ano \| findstr 18789 查PID，taskkill /PID 编号 /F
防火墙拦截	控制面板 → Windows Defender防火墙 → 允许应用 → 添加Node.js

四、MacOS本地部署

4.1 安装Homebrew（如无）

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

4.2 安装Node.js

brew install node@24
node -v   # 确保 ≥ v22

4.3 一键安装OpenClaw

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

或用国内镜像：

curl -fsSL https://clawd.org.cn/install.sh | bash

4.4 配置并启动

openclaw config set gateway.mode local
openclaw gateway start
# 可选安装为服务（开机自启）
sudo openclaw gateway install

4.5 访问

浏览器打开 http://localhost:18789。

4.6 macOS常见问题

问题	解决
`brew install` 卡住	按 `Ctrl+C`，换国内镜像安装脚本
权限报错 `EACCES`	命令前加 `sudo`
端口占用	`lsof -i :18789` 查PID，`kill -9 PID`

五、Linux本地部署（Ubuntu 20.04+ 示例）

5.1 安装Node.js

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash -
sudo apt install -y nodejs
node -v   # 验证

5.2 安装OpenClaw

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

5.3 配置并启动

openclaw config set gateway.mode local
openclaw gateway start
# 安装为服务
sudo openclaw gateway install

5.4 访问

浏览器打开 http://localhost:18789。

5.5 Linux常见问题

问题	解决
`openclaw: command not found`	npm全局路径未加入PATH：`export PATH=$PATH:$(npm prefix -g)/bin`，加入 `~/.bashrc`
3000端口被占用（源码安装）	`lsof -i:3000` 查杀

六、终极方案：Docker一键部署（跨平台，强烈推荐）

Docker方案环境隔离、统一体验、安全可控，适合服务器或个人长期运行。

6.1 前提：安装Docker和Docker Compose

Docker Desktop：官网下载（Windows/macOS）
Linux：

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER   # 退出重登录生效

6.2 完整 docker-compose.yml 文件

创建项目目录：

mkdir ~/openclaw-docker && cd ~/openclaw-docker

新建 docker-compose.yml，粘贴以下内容：

version: '3.8'
services:
openclaw-gateway:
    # 使用官方预构建镜像（推荐，避免本地编译）
    image:ghcr.io/openclaw/openclaw:latest
    container_name:openclaw
    restart:unless-stopped
    # 安全绑定：仅监听127.0.0.1，防止公网直接暴露
    ports:
      -"127.0.0.1:18789:18789"
    volumes:
      # 持久化配置、会话、记忆数据
      -./data:/home/node/.openclaw
      # 如需让AI操作宿主机文件，可挂载额外目录（可选）
      # - /宿主机路径:/容器内路径:ro
    environment:
      -TZ=Asia/Shanghai
      -NODE_ENV=production
      # 如需配置代理（使用宿主机代理）
      # - http_proxy=http://host.docker.internal:7890
      # - https_proxy=http://host.docker.internal:7890
    # 安全加固：降低容器权限
    cap_drop:
      -NET_RAW
      -NET_ADMIN
    security_opt:
      -no-new-privileges:true

6.3 完整安全命令（部署+启动）

# 1. 创建数据持久化目录
mkdir -p ./data
# 2. 启动容器（后台运行）
docker compose up -d
# 3. 查看实时日志，确认启动成功
docker compose logs -f
# 看到类似 "[gateway] listening on ws://0.0.0.0:18789" 即成功
# 4. 进入容器执行初始化配置向导
docker exec -it openclaw bash

6.4 容器内初始化（首次必需）

进入容器后，执行：

# 运行onboard向导
openclaw onboard

向导会依次询问：

工作区路径：直接回车（默认）
AI模型提供商：选 aliyun-bailian（阿里云）或 minimax 等
输入API Key：粘贴你获取的Key（阿里云需填 AccessKey ID 和 Secret）
网关端口：直接回车（18789）
聊天平台接入：先选 Skip（后续可配）
安装守护进程：选 N（容器内不需要）

完成后输入 exit 退出容器。

6.5 获取访问令牌并登录

# 查看生成的网关令牌
grep -A1 '"token"' ./data/openclaw.json

输出类似：

"token": "你的令牌字符串"

浏览器访问：http://127.0.0.1:18789/?token=你的令牌字符串。

安全提示：令牌是访问控制UI的凭证，切勿泄露。

6.6 Docker常用管理命令

命令	说明
`docker compose up -d`	后台启动
`docker compose down`	停止并删除容器
`docker compose restart`	重启
`docker compose logs -f`	查看实时日志
`docker exec -it openclaw bash`	进入容器
`docker compose pull`	更新镜像到最新版

6.7 安全加固建议（生产环境必看）

端口暴露：配置中已绑定 127.0.0.1，宿主机外无法直接访问。如需公网访问，必须使用反向代理+HTTPS+令牌认证。
数据持久化：./data目录包含API Key等敏感信息，务必定期备份，勿提交到Git。
更新镜像：定期执行 docker compose pull && docker compose up -d 获取安全更新。
防火墙：如非必要，公网防火墙关闭18789端口。

七、初始化配置向导（onboard）详解

无论哪种安装方式，首次运行都必须执行 openclaw onboard。以下是关键步骤：

安全确认：阅读并同意安全最佳实践。
选择模型提供商：根据你获取的API Key选择（阿里云百炼、MiniMax、OpenAI等）。
输入API凭据：
阿里云百炼：需 AccessKey ID 和 AccessKey Secret
其他：通常只需 API Key
配置渠道：可选择接入飞书、Telegram等（初次可跳过）。
Skills配置：推荐安装默认技能包（浏览器控制、定时任务等）。
完成：向导自动生成配置文件并启动服务。

验证配置成功：

openclaw doctor    # 全面健康检查
openclaw status    # 查看网关状态
openclaw dashboard # 打开Web控制台（需已启动）

八、常见问题速查表

现象	可能原因	解决方案
`openclaw: command not found`	PATH未包含npm全局目录	执行 `export PATH=$PATH:$(npm prefix -g)/bin`，并加入shell配置
安装时报 `EACCES`	权限不足	Mac/Linux加 `sudo`；Windows用管理员PowerShell
网关启动报 `port already in use`	端口18789被占用	查杀占用进程，或修改配置换端口
WebUI打不开	网关未启动/防火墙拦截	执行 `openclaw gateway status`；Windows放行防火墙
发消息无回复/报错	API Key无效/额度用完	执行 `openclaw configure` 重输Key；登录云平台检查余额
Docker容器启动后无法访问	令牌未提供	访问时加 `?token=你的令牌`，或先运行 `openclaw dashboard`
阿里云百炼API调用失败	Key错误/未实名/地域不对	检查控制台实名状态和额度，确认endpoint正确

九、总结性的两句

从零到一，你已成功在本地或Docker中运行起OpenClaw。它不再是只会说话的聊天机器人，而是一个真正能帮你干活、24小时在线的数字员工。

文件整理：一句话归档桌面文件
信息速读：丢给它论文或链接，自动总结摘要
定时任务：每天早报、邮件提醒自动推送
未来扩展：接入飞书/钉钉、安装社区Skills，让它学会更多技能

接下来可以做什么？

浏览官方Skill市场：openclaw skills list
学习飞书接入教程（后续文章）
关注版本更新：openclaw --version，定期升级

到此这篇关于Windows、macOS、Linux三系统本地部署OpenClaw+避坑指南+Docker一键部署,30分钟搞定的文章就介绍到这了,更多相关OpenClaw安装部署教程内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！