一、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. 全局安装 OpenClaw
npm 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. 安装 OpenClaw
npm install -g openclaw
openclaw --version
如遇到权限错误，可以像 Linux 那样设置 ~/.npm-global 为全局目录，并调整 PATH。
4. 创建 workspace 并初始化
mkdir -p ~/openclaw-workspace
cd ~/openclaw-workspace
openclaw init
5. 启动 Gateway
openclaw 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 仓库中同步（注意不要把敏感信息公开到公共仓库）。
