一文搞定 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（详细版）

1. 安装 Node.js

打开浏览器访问：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 发行版可以参考同样思路。

1. 更新系统sudo apt update
   sudo apt upgrade -y
2. 安装 Node.js（推荐使用 nvm）

安装 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 

4. 全局安装 OpenClawnpm install -g openclaw
   openclaw --version

若安装过程中报网络错误，可考虑切换为国内源（如使用 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（详细版）

1. 安装 Homebrew（如已安装可跳过）

/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 

3. 安装 OpenClawnpm install -g openclaw
   openclaw --version

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

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

5. 启动 Gatewayopenclaw gateway start
   openclaw gateway status

一般会监听在 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 基础配置说明

1. 工作目录结构（示例）

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

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

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

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

2. 常用命令总览openclaw init # 初始化工作目录
   openclaw gateway start # 启动 gateway
   openclaw gateway stop # 停止 gateway
   openclaw gateway restart # 重启 gateway
   openclaw status # 查看运行状态

七、常见问题与解决方法（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 仓库中同步（注意不要把敏感信息公开到公共仓库）。