OpenClaw 是一个统一管理多渠道 AI 助手会话的开源平台，支持本地部署。在 Windows、Ubuntu 和 macOS 系统上通过 npm 全局安装并配置 OpenClaw 的步骤，包括环境准备（Node.js）、工作目录初始化、Gateway 启动及进程守护方案。此外，还涵盖了基础配置文件说明及常见部署问题的排查方法，帮助用户快速搭建本地可控的 AI 助手环境。
OpenClaw 是一个用于统一管理和控制多渠道 AI 助手会话的开源平台，可以在本地机器、服务器、NAS、云主机上运行。 它的核心特点包括：
本文将详细介绍如何在 Windows、Ubuntu（Linux）、macOS 三个平台上部署 OpenClaw，并在最后整理常见问题及排查思路。
无论在哪个平台部署 OpenClaw，基本前置条件是类似的：
官方推荐使用 npm 全局安装的方式来部署。
打开浏览器访问：https://nodejs.org/ 下载对应系统的安装包（建议 LTS 版本）。 按默认选项安装，确保勾选了 'Add to PATH'。 安装完成后，打开 PowerShell 或 CMD，检查版本：
node -v
npm -v
如果能正常输出版本号，说明 Node.js 与 npm 安装成功。
默认全局目录可能在用户目录下，如果你遇到权限问题，可以单独指定全局路径，例如：
npm config set prefix "C:\npm-global"
然后把 C:\npm-global 下的 bin 路径加入系统环境变量 PATH。
npm install -g openclaw
安装完成后确认：
openclaw --version
openclaw help
如果出现 openclaw 不是内部或外部命令，一般是 PATH 问题，需要把 npm 全局安装路径加入环境变量。
建议单独弄一个目录，例如：
mkdir D:\openclaw-workspace
cd D:\openclaw-workspace
openclaw init
openclaw init 会在当前目录生成一套基础文件，例如：
AGENTS.md
SOUL.md
USER.md
HEARTBEAT.md
skills/ 目录（可能因版本略有不同）
这些文件定义了你的助手人格、用户信息和技能逻辑。
在刚才的工作目录中执行：
openclaw gateway start
再执行：
openclaw gateway status
如果显示 gateway 已启动，就表示服务正常运行。这时一般会有一个 Web 控制界面（具体端口和 URL 会在启动日志里提示，例如 http://localhost:xxxx）。
以下以 Ubuntu 为例，其他 Linux 发行版可以参考同样思路。
sudo apt update
sudo apt upgrade -y
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
node -v
npm -v
使用 nvm 的好处是可以在不同 Node 版本之间自由切换，避免系统自带 Node 过旧的问题。
mkdir -p ~/.npm-global
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw
openclaw --version
若安装过程中报网络错误，可考虑切换为国内源（如使用 cnpm 或设置 registry）。
mkdir -p ~/openclaw-workspace
cd ~/openclaw-workspace
openclaw init
确认工作目录下是否生成 AGENTS.md、SOUL.md 等文件。
openclaw gateway start
openclaw gateway status
如果输出类似 'gateway running' 的信息，就说明启动成功。可以打开日志中提示的 URL，访问控制 UI / WebChat 界面。
npm install -g pm2
pm2 start "openclaw gateway start" --name openclaw
pm2 save
pm2 status
这样，即使重启服务器，OpenClaw 也可以通过 pm2 自动拉起。
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装完成后记得根据提示把 brew 加入 shell 配置文件。
使用 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
npm install -g openclaw
openclaw --version
如遇到权限错误，可以像 Linux 那样设置 ~/.npm-global 为全局目录，并调整 PATH。
mkdir -p ~/openclaw-workspace
cd ~/openclaw-workspace
openclaw init
openclaw gateway start
openclaw gateway status
一般会监听在 localhost 的某个端口，可在浏览器中访问控制 UI。
npm install -g pm2
pm2 start "openclaw gateway start" --name openclaw
pm2 save
在 openclaw init 后，典型的工作目录可能包含：
你可以根据需求修改这些文件，例如：
openclaw init # 初始化工作目录
openclaw gateway start # 启动 gateway
openclaw gateway stop # 停止 gateway
openclaw gateway restart # 重启 gateway
openclaw status # 查看运行状态
原因分析：
解决办法：
# 检查 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
可能原因：
排查步骤：
# 检查 Node.js 版本
node -v
# 若版本过低，使用 nvm 升级
# 在一个全新目录重新 init 测试
mkdir ~/openclaw-test
cd ~/openclaw-test
openclaw init
openclaw gateway start
# 如果新目录正常，说明原 workspace 配置可能有问题，可以逐步对比差异
# 查看日志或终端输出，留意具体错误信息（如端口被占用）
可能原因：
解决方法：
# 确认 gateway 状态
openclaw gateway status
# 查看启动时终端输出，记录监听地址（例如 http://localhost:7777 之类）
# 本地访问时优先使用 http://127.0.0.1:端口，远程访问时注意云服务器的安全组、防火墙是否允许该端口
解决方法：
# 卸载旧版本
npm uninstall -g openclaw
# 清除缓存
npm cache clean --force
# 重新安装
npm install -g openclaw
openclaw --version
思路：
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online