2.1 系统要求与运行前检查

本节梳理了在安装前必须核对的系统环境与网络连通性要求。

2.1.1 核心准备清单

主要准备依赖：

1. 一台能上网的电脑：支持 macOS、绝大多数 Linux 发行版或 Windows 的 WSL2 系统。只要是近 5 年的机器基本都能跑。最省事的办法是一台云虚拟机，但要注意能连通到互联网。

2. 一个 API Key（模型服务密钥）：申请任意一家大语言模型（如 OpenAI、KIMI、MiniMax 等）的 API 密钥，这是让系统具备推理与生成能力的关键。

2.1.2 硬性运行时环境要求

无论采用何种安装方式，底层运行时环境的纯净度与版本兼容性是第一道门槛。

1. 操作系统：支持 macOS、绝大多数 Linux 发行版（如 Ubuntu 24.04 LTS）、以及 Windows 的 WSL2（最好是 Ubuntu 子系统）。在 Windows 原生命令行下易出现文件路径和权限的适配问题，不推荐在生产使用。

2. Node.js 环境：要求 Node.js 22 或更新版本。可以通过 node --version 检查。版本过低会导致依赖与运行时能力不兼容。

3. 包管理器（可选）：若不使用官方推荐的一键安装脚本，而选择 Node 原生体系安装，则需准备 npm。

4. 内存与硬件规格：最低 4 GB 内存，如果需要运行浏览器工具，推荐 8 GB 或以上。

[!WARNING] 内存过低会导致很多问题。 服务器在执行自动升级、运行浏览器或处理长上下文任务时，容易频繁出现 OOM（内存溢出）导致进程卡死，甚至无法完成自身升级。省下的费用远不抵后续排障成本。

2.1.3 网络连通性验证

由于 OpenClaw 系统重度依赖各种远端 API，网络状况直接决定可用性。它主要分为两部分。

1. 安装期网络：确保机器能够正常拉取 npm registry 或 docker.io（如果使用容器化部署），必要时需配置 HTTP 代理及镜像源。

2. 运行时网络：必须确保能够连通所选 LLM 供应商的接口。若要接入 Telegram Bot 等海外渠道平台，机器必须具备无阻碍地访问这些渠道的能力。

在终端中快速做两类连通性验证：

1. 安装期：能访问包仓库（npm registry 或镜像源）。

2. 运行期：能访问你选择的模型供应商 API（以下以 OpenAI 为例，其他供应商请替换为对应接口与域名）。

# 安装期网络：npm registry

curl -sS -m 5 -o /dev/null -w "npm registry: %{http_code}\n" https://registry.npmjs.org/

# 运行期网络：模型供应商 API（以 OpenAI 为例）

curl -sS -m 10 -o /dev/null -w "llm provider: %{http_code}\n" https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# 说明：

# - 200 表示鉴权通过且网络可达

# - 401/403 往往表示鉴权未通过，但网络链路通常是通的（仍可用于“能否连通”的快速判断）

2.1.4 权限与系统时间

一些经常被忽略但极为致命的隐蔽项如下。

1. 系统时间漂移：很多云厂商的 API 鉴权基于 JWT 并且有严格的有效期校验。若服务器时间漂移超过 5 分钟，可能会遇到意外的权限拒绝错误。生产环境务必启用时间同步服务（chrony / systemd-timesyncd / ntpd 均可）。

2. 运行账号权限：OpenClaw 并非系统级内核驱动， 绝不需要 root 权限 运行。创建一个专用的普通用户账号分类分配必要的工作目录读写权限即可。

2.1.5 账号与密钥整备

为了保证即插即用，在安装前预先把以下关键物料备齐入密码管理器或环境变量中，切勿硬编码进代码。

• 核心物料：至少一个 LLM 供应商的 API 密钥（例如 KIMI，或者 Anthropic）。

• 渠道物料：Telegram Bot Token（向 @BotFather 申请）或其它你想首跑接入的渠道凭证（如飞书 App Secret）。

[!CAUTION] 绝对不要为了图省事把 API Token 硬编码在测试脚本中，或者通过聊天软件复制黏贴发送给其他人。推荐使用环境变量的方式进行管理。

2.1.6 一键环境排查脚本示例

可以通过统一的脚本进行环境检测。下面是一个前置诊断脚本 check_env.sh，它可以验证最基本的核心依赖。

#!/bin/bash
echo "=== OpenClaw 环境自检 ==="
node --version || echo "警告: 未安装 Node.js，或者版本低于 22"
npm --version || echo "提示: 未安装 npm。如果不使用自动化脚本安装，这是必需项"
docker --version || echo "提示: 未安装 Docker (如使用容器化部署则是必需项)"

echo "测试网络连通（官方安装脚本）..."
curl -s -m 5 -o /dev/null -w "install script: %{http_code}\n" https://openclaw.ai/install.sh

echo "测试运行期网络（模型供应商 API，以 OpenAI 为例，可替换为你的供应商）..."
if [ -n "${OPENAI_API_KEY:-}" ]; then
  curl -sS -m 10 -o /dev/null -w "llm provider: %{http_code}\n" https://api.openai.com/v1/models \
    -H "Authorization: Bearer $OPENAI_API_KEY"
else
  curl -sS -m 10 -o /dev/null -w "llm provider: %{http_code}\n" https://api.openai.com/v1/models
fi
echo "提示: 200 表示鉴权通过；401/403 多为无 Key/无权限但网络可达。"
echo "自检完成"