安装 OpenClaw

> 官方文档优先：https://docs.openclaw.ai

> 遇到任何安装问题，先查官方文档/手册寻找解决方案，再尝试其他途径。

| 资源 | 链接 | 说明 |

|------|------|------|

| 官方文档 | https://docs.openclaw.ai | 安装/配置/使用的一切问题 |

| 安装指南 | https://docs.openclaw.ai/install | 官方安装教程 |

| GitHub | https://github.com/openclaw/openclaw | 源码仓库 |

步骤 0：确定执行环境

如果上下文已明确，跳过此步：用户明确说了目标环境（如"在服务器上装"→ 远程，"本地装"→ 本地），或对话中已建立远程连接上下文。

否则，用 AskUserQuestion 询问用户在哪里安装 OpenClaw：

• 本地：后续命令用 Bash 工具执行
• 远程主机：见下方远程模式初始化

远程模式初始化

确定为远程主机后，按以下顺序执行：

1. 尝试加载 `/ssh` skill：用 Skill 工具调用 ssh。该 skill 包含远程服务器选择、MCP 执行规则、代理隧道配置等完整知识。加载失败（skill 不存在）不影响后续流程，继续执行。

2. 确认远程执行工具：确认用户有哪些可用的 MCP SSH 工具（如 mcp__*__exec），后续命令通过对应工具执行。

官方支持的安装方式

| 方式 | 命令 | 说明 |

|------|------|------|

| Installer 脚本（官方推荐） | curl -fsSL https://openclaw.ai/install.sh \| bash | 自动处理 Node 检测和安装 |

| npm | npm install -g openclaw@latest | 需预装 Node 22+ |

| pnpm | pnpm add -g openclaw@latest | 需预装 Node 22+ |

| 源码构建 | git clone → pnpm install → pnpm build | 开发者用 |

| Docker / Podman / Nix / Ansible | 见官方文档 | 容器化部署 |

安装偏好

使用 npm 安装，不使用 Docker 方式。 原因：目标服务器已有 Node 环境，npm 方式更轻量、便于调试和更新。

官方要求

• 运行时：Node ≥ 22
• 初始化：openclaw onboard --install-daemon（安装 systemd 守护进程）
• 验证：openclaw doctor（诊断配置问题）
• 更新渠道：stable / beta / dev，通过 openclaw update --channel <渠道> 切换
• 验证命令：openclaw doctor / openclaw status / openclaw dashboard

流程

1. 环境检查

node --version 2>/dev/null
npm --version 2>/dev/null
cat /etc/os-release | head -5
free -h | head -2
df -h / | tail -1

检查操作系统版本、内存、磁盘、Node.js 版本。

• Node.js 未安装或 < 22 → 进入步骤 2
• Node.js ≥ 22 → 跳到步骤 3

2. 安装 Node.js 22（如需）

# 添加 NodeSource 源（sudo）
curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/nodesource_setup.sh && bash /tmp/nodesource_setup.sh

# 安装（sudo，DEBIAN_FRONTEND 避免 debconf 在无 TTY 环境下的警告噪音）
DEBIAN_FRONTEND=noninteractive apt-get install -y nodejs

# 验证
node --version && npm --version

3. 网络环境判断

自动检测服务器是否能直连外网：

curl -sI --connect-timeout 5 https://www.google.com 2>&1 | head -3

根据结果分流：

• 返回 HTTP 200 → 外网畅通，直接跳到步骤 5 安装
• 超时或无响应 → 境内服务器，进入步骤 4 代理引导

4. 境内服务器代理引导

用 AskUserQuestion 向用户提问：

> 你本地电脑是否有代理软件（如 v2rayN、Clash 等）？

>

> - 有代理软件 → 继续代理配置

> - 没有 → 跳到步骤 5 直接尝试（用国内镜像加速，git 依赖可能失败）

#### 4a. 有代理：配置 SSH 隧道

向用户确认代理端口（v2rayN 默认 10808，Clash 默认 7890），然后确认 SSH 配置是否已有 RemoteForward。

如果用户不了解 RemoteForward，说明原理并引导添加到 ~/.ssh/config：

Host <服务器别名>
    RemoteForward <端口> 127.0.0.1:<端口>

添加后需重新建立 SSH 连接才生效。

验证代理隧道：

curl -x http://127.0.0.1:<端口> -sI --connect-timeout 5 https://www.google.com 2>&1 | head -3

返回 200 → 代理就绪，进入步骤 5a。

#### 4b. 没有代理：降级方案

npm config set registry https://registry.npmmirror.com

进入步骤 5b 尝试安装。告知用户 npm 镜像只能加速 registry 中的包，git 类型依赖（如 libsignal-node）仍走 GitHub 直连，可能会卡住。

5. 安装 OpenClaw

#### 5a. 走代理安装（境内 + 有代理）

所有流量走代理时使用官方 registry，不要用国内镜像（代理已解决网络问题，镜像反而可能与代理冲突）：

npm config set registry https://registry.npmjs.org

nohup env https_proxy=http://127.0.0.1:<端口> \
          http_proxy=http://127.0.0.1:<端口> \
          all_proxy=socks5://127.0.0.1:<端口> \
  npm install -g openclaw@latest > /tmp/openclaw-install.log 2>&1 &
echo "PID: $!"

关键点：

• 代理变量通过 env 传递，仅当前命令生效，不污染系统环境
• 必须同时设 http_proxy、https_proxy、all_proxy，确保 npm 和 git 子进程都走代理
• 不要持久化代理配置（npm config set proxy / git config），SSH 隧道断开后会导致所有请求卡住

#### 5b. 直连安装（境外 / 无代理降级）

nohup npm install -g openclaw@latest > /tmp/openclaw-install.log 2>&1 &
echo "PID: $!"

6. 监控安装进度

MCP exec 有 60 秒超时，所以用 nohup 后台安装，然后轮询：

ps aux | grep <PID> | grep -v grep
tail -20 /tmp/openclaw-install.log
which openclaw

注意：npm 日志可能在前几分钟完全为空（0 字节），这是正常的——npm 在解析和下载依赖时不写 stdout。判断进程是否活跃应看 ps aux 中的 CPU 占用和内存（RSS）变化，而非日志。

完成标志：

• 日志出现 added XXX packages in Xm
• which openclaw 返回路径

预期 2-5 分钟。超过 10 分钟且 CPU/内存无变化 → 网络卡住，参考 [references/troubleshooting.md](references/troubleshooting.md)。

7. 验证与初始化

# 验证安装
openclaw --version

# 诊断配置
openclaw doctor

# 初始化（安装 systemd 守护进程）
# MCP 无 TTY 环境下必须加 --non-interactive --accept-risk，否则会被拒绝
openclaw onboard --install-daemon --non-interactive --accept-risk

踩坑经验

详见 [references/troubleshooting.md](references/troubleshooting.md)