一文搞定 OpenClaw 部署：Windows / Ubuntu / macOS 全平台超详细教程

一、OpenClaw 简介

OpenClaw 是一个用于统一管理和控制多渠道 AI 助手会话的开源平台，可以在本地机器、服务器、NAS、云主机上运行。
它的核心特点包括：

通过一个 Gateway 统一管理多个对话会话（webchat、Telegram、Discord、WhatsApp 等）
支持“技能（AgentSkills）”扩展能力，可以把各种自动化脚本封装成可复用工具
强调本地可控、安全、可定制，适合开发者和对隐私有要求的用户

本文将详细介绍如何在 Windows、Ubuntu（Linux）、macOS 三个平台上部署 OpenClaw，并在最后整理常见问题及排查思路。
二、通用前置条件

无论在哪个平台部署 OpenClaw，基本前置条件是类似的：

Node.js 环境（建议 20+ 或官方推荐版本）
能访问 GitHub/npm 的网络（或者使用镜像源）
有一个用于存放 OpenClaw 工作目录的路径（workspace）

官方推荐使用 npm 全局安装的方式来部署。
三、Windows 下部署 OpenClaw（详细版）

打开浏览器访问：https://nodejs.org/
下载对应系统的安装包（建议 LTS 版本）。
按默认选项安装，确保勾选了 “Add to PATH”。
安装完成后，打开 PowerShell 或 CMD，检查版本：

node -v
npm -v

如果能正常输出版本号，说明 Node.js 与 npm 安装成功。
2. 配置 npm 全局目录（可选，但推荐）

默认全局目录可能在用户目录下，如果你遇到权限问题，可以单独指定全局路径，例如：

npm config set prefix "C:\\npm-global"

然后把 C:\\npm-global 下的 bin 路径加入系统环境变量 PATH。
3. 全局安装 OpenClaw

npm install -g openclaw

安装完成后确认：

openclaw –version
openclaw help

如果出现 openclaw 不是内部或外部命令，一般是 PATH 问题，需要把 npm 全局安装路径加入环境变量。
4. 创建工作目录并初始化

建议单独弄一个目录，例如：

mkdir D:\\openclaw-workspace
cd D:\\openclaw-workspace
openclaw init

openclaw init 会在当前目录生成一套基础文件，例如：

AGENTS.md
SOUL.md
USER.md
HEARTBEAT.md
skills/ 目录（可能因版本略有不同）

这些文件定义了你的助手人格、用户信息和技能逻辑。
5. 启动 OpenClaw Gateway

在刚才的工作目录中执行：

openclaw gateway start

再执行：

openclaw gateway status

如果显示 gateway 已启动，就表示服务正常运行。这时一般会有一个 Web 控制界面（具体端口和 URL 会在启动日志里提示，例如 http://localhost:xxxx）。
6. Windows 上的常见优化建议

如果你不想每次都开 PowerShell，可以写一个 .bat 启动脚本。
如果想要后台常驻，可以结合 任务计划程序 或 NSSM 把 OpenClaw 包装成服务。
遇到端口冲突时，可以在配置文件中修改 gateway 的监听端口。

四、Ubuntu（Linux）下部署 OpenClaw（详细版）

以下以 Ubuntu 为例，其他 Linux 发行版可以参考同样思路。

安装 nvm（若已安装可跳过）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

让 nvm 生效

source ~/.bashrc

安装 Node.js 20（示例）

nvm install 20
nvm use 20

node -v
npm -v

使用 nvm 的好处是可以在不同 Node 版本之间自由切换，避免系统自带 Node 过旧的问题。
3. 为 npm 设置本地全局目录（避免 sudo）

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

若安装过程中报网络错误，可考虑切换为国内源（如使用 cnpm 或设置 registry）。
5. 创建 workspace 并初始化

mkdir -p ~/openclaw-workspace
cd ~/openclaw-workspace
openclaw init

确认工作目录下是否生成 AGENTS.md、SOUL.md 等文件。
6. 前台启动测试

openclaw gateway start
openclaw gateway status

如果输出类似 “gateway running” 的信息，就说明启动成功。可以打开日志中提示的 URL，访问控制 UI / WebChat 界面。
7. 使用 pm2 进行进程守护（推荐）

npm install -g pm2

启动 OpenClaw gateway

pm2 start "openclaw gateway start" –name openclaw

保存进程列表，实现开机自启（根据 pm2 提示配置）

pm2 save
pm2 status

这样，即使重启服务器，OpenClaw 也可以通过 pm2 自动拉起。
五、macOS 下部署 OpenClaw（详细版）

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

安装完成后记得根据提示把 brew 加入 shell 配置文件。
2. 安装 Node.js

使用 Homebrew：

brew install node
node -v
npm -v

如果你偏好使用 nvm，也可以与 Linux 类似：

brew install nvm
mkdir -p ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

nvm install 20
nvm use 20

如遇到权限错误，可以像 Linux 那样设置 ~/.npm-global 为全局目录，并调整 PATH。
4. 创建 workspace 并初始化

mkdir -p ~/openclaw-workspace
cd ~/openclaw-workspace
openclaw init

一般会监听在 localhost 的某个端口，可在浏览器中访问控制 UI。
6. macOS 上保持常驻的方式

使用 tmux 或 screen，在会话里运行 openclaw gateway start，即使关闭终端窗口也能保持进程存在（只要会话不结束）。

使用 pm2，方法与 Linux 基本一致：

npm install -g pm2
pm2 start "openclaw gateway start" –name openclaw
pm2 save

六、OpenClaw 基础配置说明

在 openclaw init 后，典型的工作目录可能包含：

AGENTS.md：说明 agent 工作方式、记忆策略等
SOUL.md：定义助手的人格、风格、边界
USER.md：记录用户信息（称呼、时区、偏好）
MEMORY.md：长期记忆，重要信息的归档
memory/YYYY-MM-DD.md：按日期划分的日记式记忆
skills/：存放 AgentSkills 的目录，每个 skill 是一个小型功能模块

你可以根据需求修改这些文件，例如：

调整 SOUL 中的“Vibe”，让助手更正式或更幽默；
在 USER 中补充自己的昵称、常用工作内容等；
添加或安装新的 skills，扩展功能。

七、常见问题与解决方法（FAQ）
问题 1：openclaw: command not found / ‘openclaw’ 不是内部或外部命令

原因分析：

npm 全局目录没有成功加入 PATH
安装失败或被安全软件拦截

解决办法：

检查 npm 全局目录：

npm root -g

对应的 bin 目录一般就是命令的所在位置。
将该路径加入环境变量 PATH：
Windows：在系统高级设置 → 环境变量中，找到 PATH，添加如 C:\\npm-global 或 C:\\Users\\用户名\\AppData\\Roaming\\npm。
Linux/macOS：在 ~/.bashrc 或 ~/.zshrc 中加入：

export PATH="$HOME/.npm-global/bin:$PATH"

重新打开终端，执行：

openclaw –version

问题 2：openclaw gateway start 启动后立即退出

可能原因：

Node.js 版本过低或不兼容
配置文件损坏
端口被占用

排查步骤：

检查 Node.js 版本：

node -v

若版本过低，使用 nvm 升级。
在一个全新目录重新 init 测试：

mkdir ~/openclaw-test
cd ~/openclaw-test
openclaw init
openclaw gateway start

如果新目录正常，说明原 workspace 配置可能有问题，可以逐步对比差异。
查看日志或终端输出，留意具体错误信息（如端口被占用）。

问题 3：控制 UI / WebChat 无法访问

可能原因：

gateway 没有启动成功
防火墙或安全组拦截访问
使用了错误的地址或端口

解决方法：

确认 gateway 状态：

openclaw gateway status

查看启动时终端输出，记录监听地址（例如 http://localhost:7777 之类）。
本地访问时优先使用 http://127.0.0.1:端口，远程访问时注意云服务器的安全组、防火墙是否允许该端口。

问题 4：升级 OpenClaw 失败或版本混乱

解决方法：

卸载旧版本：

npm uninstall -g openclaw

清除缓存：

npm cache clean –force

重新安装：

npm install -g openclaw
openclaw –version

问题 5：多设备、多环境如何协同使用 OpenClaw？

思路：

方案一：在一台固定服务器（或 NAS）上部署 OpenClaw，作为“中枢”，通过 WebChat 或消息通道远程使用。
方案二：在多台机器上分别部署 OpenClaw，但把 workspace 放在一个 Git 仓库中同步（注意不要把敏感信息公开到公共仓库）。