> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.1_requirements.md).

# 2.1 系统要求与运行前检查

> **预计耗时**：5–10 分钟

在正式安装 OpenClaw 之前，确认环境满足最小要求是必要的投入。本节按照**必须、强烈建议、可选增强**的三层逻辑组织检查清单，你可以从第一层快速验证，遇到问题时再回头补齐后续层级。这样的分层设计既能让新手快速上手，也不会让初装者被过多细节压垮。

## 2.1.1 环境与硬件要求

安装前请核对以下依赖：

1. **操作系统**：macOS、绝大多数 Linux 发行版（推荐 Ubuntu 24.04 LTS），以及 Windows（原生 PowerShell 或 WSL2 均受支持，其中 WSL2 通常更稳定）。
2. **Node.js**：当前官方安装器默认使用 **Node.js 24**，并继续兼容 **Node.js 22 LTS（当前支持线为 22.19+）**。可通过 `node --version` 确认；官方安装脚本会自动检测并补齐 Node，手动管理运行时时应优先使用 Node 24。
3. **内存**：最低 **4 GB**；如需运行[浏览器工具](/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills/5.4_browser_nodes.md)，推荐 **8 GB 及以上**。
4. **模型认证方式**：至少准备一种可用的模型认证路径，例如 API Key、OAuth，或供应商支持的 setup-token / CLI 复用途径。
5. **包管理器（可选）**：全局安装可使用 `npm`、`pnpm` 或 `bun`；源码构建需要 `pnpm`。

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

## 2.1.2 网络连通性验证

OpenClaw 重度依赖远端 API，网络状况直接决定可用性：

1. **安装期**：确保能拉取 npm registry 或 docker.io，必要时配置 HTTP 代理及镜像源。
2. **运行期**：必须能连通所选 LLM 供应商的接口；接入 Telegram 等海外渠道须能无阻碍访问对应平台。

快速连通性验证：

```bash
# 安装期：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.3 权限与系统时间

1. **系统时间漂移**：系统时间仍应同步，主要影响 TLS、OAuth/供应商 token 过期判断和日志排障；Gateway 本地鉴权使用 token/password/device/bootstrap/trusted-proxy 等模式，不是 JWT 时间偏移校验。生产环境务必启用时间同步服务（`chrony` / `systemd-timesyncd` / `ntpd` 均可）。
2. **运行账号权限**：OpenClaw **无需 root 权限**，使用普通用户账号并分配必要目录读写权限即可。

## 2.1.4 账号与密钥整备

安装前预先备好以下物料，存入密码管理器或环境变量，切勿硬编码进代码：

* **核心物料**：至少一种可用的模型认证材料（如 API Key、OAuth 账号，或供应商要求的 setup token）。
* **渠道物料**：Telegram Bot Token（向 [@BotFather](https://t.me/BotFather) 申请）或其他渠道凭证（如飞书 App Secret）。

> \[!CAUTION] 绝对不要把 API Token 硬编码在测试脚本中，或通过聊天软件发送给他人。推荐使用环境变量管理。

详细的环境排查脚本见[附录：环境自检工具](/openclaw_guide/fu-lu/appendix/env_check.md)。