OpenClaw 跨平台部署指南：Windows / Ubuntu / macOS

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 仓库中同步（注意不要把敏感信息公开到公共仓库）。