OpenClaw 部署安装与常见问题完全指南

OpenClaw 是一个开源的个人 AI 助手框架，可以在多种操作系统和平台上运行。它支持通过 WhatsApp、Telegram、Discord、Slack、Signal 等常用聊天工具与 AI 对话，并且支持语音、图片和浏览器自动化等高级功能。本文详细介绍 OpenClaw 的各种安装部署方式，以及常见问题的排查和解决方法。

什么是 OpenClaw

OpenClaw 是一个开源的个人 AI 助手框架，它的核心是一个始终运行的 Gateway（网关）服务。你可以把 Gateway 部署在自己的电脑、服务器或 NAS 上，然后通过你日常使用的聊天软件（如微信、Telegram、Discord 等）来和 AI 助手对话。

OpenClaw 支持的频道非常广泛，包括：

即时通讯：WhatsApp、Telegram、Signal、iMessage、微信、QQ

团队协作：Slack、Microsoft Teams、Discord、Google Chat、飞书

其他平台：Matrix、Nostr、IRC、Line、Zalo、Synology Chat 等

每个频道可以配置独立的 AI Agent，实现分平台、分任务的个性化服务。

系统要求

在安装 OpenClaw 之前，请确保你的系统满足以下要求：

项目	最低要求	推荐配置
Node.js	Node 22.14+	Node 24
内存	1 GB	2 GB 及以上
磁盘	2 GB 可用空间	5 GB 及以上
系统	macOS / Linux / Windows (WSL2)	macOS / Ubuntu 22.04+

注意：如果使用 Docker 方式部署，内存建议至少 2 GB，否则在编译依赖包时可能会因为内存不足而导致进程被 OOM Kill（错误码 137）。

安装方法详解

方法一：官方安装脚本（推荐）

官方提供了一个自动检测操作系统、安装 Node.js 并完成 OpenClaw 安装的脚本，是最简单的方式。

macOS / Linux / WSL2

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell)

iwr -useb https://openclaw.ai/install.ps1 | iex

安装脚本会自动检测系统环境并安装必要的依赖。如果你想跳过引导配置步骤（onboarding），可以加参数：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

方法二：npm / pnpm / bun 安装

如果你已经手动安装了 Node.js，可以使用包管理器来安装 OpenClaw。

npm 安装

npm install -g openclaw@latest
openclaw onboard --install-daemon

pnpm 安装

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

注意：pnpm 对包含 native 构建步骤的包（如 sharp、node-llama-cpp 等）有特殊的安全机制，首次安装后需要运行 approve-builds 命令批准构建。

bun 安装

bun add -g openclaw@latest
openclaw onboard --install-daemon

注意：bun 支持全局 CLI 安装，但 Gateway 运行时仍推荐使用 Node.js。

方法三：Docker 部署

Docker 部署适合想要隔离环境、在 VPS 上运行，或者想快速验证功能是否正常的用户。

快速部署步骤

第一步，从 GitHub 克隆仓库并执行安装脚本：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh

脚本会执行以下操作：

1. 构建 Docker 镜像（或使用预构建的 ghcr.io/openclaw/openclaw:latest 镜像）

2. 运行引导向导，提示输入 AI 提供商的 API Key

3. 生成网关令牌并写入 .env 文件

4. 通过 Docker Compose 启动 Gateway 服务

安装脚本支持以下可选环境变量：

环境变量	说明
OPENCLAW_IMAGE	使用预构建镜像而非本地构建
OPENCLAW_HOME_VOLUME	将 /home/node 持久化到命名卷
OPENCLAW_EXTRA_MOUNTS	额外的宿主机绑定挂载（逗号分隔）
OPENCLAW_SANDBOX	启用沙箱功能（设为 1）
OPENCLAW_EXTENSIONS	构建时预安装的插件名称
OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry 收集器地址

使用预构建镜像

如果你不想本地构建，可以直接使用 GitHub Container Registry 上的预构建镜像：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

常用镜像标签：

– main — 最新开发版

– latest — 最新稳定版

– 2026.4.26 — 指定版本号

手动 Docker 部署

如果不想用安装脚本，可以手动执行每一步：

# 1. 构建镜像
docker build -t openclaw:local -f Dockerfile .

# 2. 运行引导
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

# 3. 配置网关
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'

# 4. 启动服务
docker compose up -d openclaw-gateway

持久化存储配置

Docker Compose 默认会将配置目录和数据目录挂载到宿主机，确保容器重启后数据不丢失：

# docker-compose.yml 关键挂载
volumes:
  - ./openclaw-config:/home/node/.openclaw
  - ./openclaw-workspace:/home/node/.openclaw/workspace
  - openclaw-plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps

在宿主机上创建对应的目录并设置正确的权限（uid 1000）：

mkdir -p openclaw-config openclaw-workspace
sudo chown -R 1000:1000 openclaw-config openclaw-workspace

方法四：从源码编译

如果你想参与 OpenClaw 的开发或使用最新特性，可以从源码构建：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm add -g .
openclaw onboard --install-daemon

注意：从源码编译需要 Node.js 24 和 pnpm，编译过程中会下载并构建多个 native 依赖（如 node-llama-cpp、sharp 等），首次构建可能需要较长时间。

初始化与配置

运行引导向导

openclaw onboard --install-daemon

向导会引导你完成以下步骤：

1. 选择 AI 提供商（Anthropic、OpenAI、Google、Ollama、LM Studio 等）

2. 输入 API Key 或完成 OAuth 认证

3. 配置网关的基本参数（端口、绑定地址等）

4. 选择要启用的聊天频道

5. 设置安全策略（DM 配对模式等）

如果想在 Docker 环境中完成引导（适合无头服务器）：

# 在 Docker 中完成引导
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

验证网关状态

引导完成后，验证 Gateway 是否正常运行：

openclaw gateway status

正常的输出应显示：

– Runtime: running

– Connectivity probe: ok

– Capability: admin-capable（或 read-only / write-capable）

也可以用探针命令深度检测：

openclaw gateway probe
openclaw status
openclaw status --all

打开控制面板

在浏览器中打开 http://127.0.0.1:18789/，将引导时设置的共享密钥粘贴到设置中即可进入控制面板。

如果需要重新获取控制面板地址：

openclaw dashboard
openclaw dashboard --no-open

常见问题与解决方法

问题一：网关无法启动（EADDRINUSE）

症状：运行 openclaw gateway start 时报错 EADDRINUSE 或提示端口已被占用。

解决方法：

# 1. 检查是否有其他进程占用了 18789 端口
lsof -i :18789

# 2. 如果是旧的 openclaw 进程在运行，先停止
openclaw gateway stop

# 3. 如果端口被其他程序占用，修改 OpenClaw 的监听端口
openclaw config set gateway.port 18790
openclaw gateway start

问题二：Node 版本不兼容

症状：安装时报错 Unsupported engine 或运行时报模块找不到的错误。

解决方法：OpenClaw 需要 Node 22.14 及以上版本，推荐 Node 24。

# 检查当前 Node 版本
node --version

# 使用 nvm 切换到兼容版本
nvm install 24
nvm use 24

# 重新安装 openclaw
npm install -g openclaw@latest

问题三：sharp 构建失败（npm 安装）

症状：在 npm 安装过程中，sharp native 模块构建失败。

解决方法：

# 方法一：设置 SHARP 忽略全局 libvips
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

# 方法二：使用 pnpm 替代 npm
npm uninstall -g openclaw
pnpm add -g openclaw@latest

问题四：Docker 镜像构建 OOM（内存不足）

症状：Docker 构建过程中进程被 Kill，日志显示 exit 137。

这是编译 native 依赖时内存不足导致的。请确保：

1. Docker 运行所在虚拟机/容器至少分配 2 GB 内存

2. 增加 swap 空间：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

问题五：频道连接成功但消息不发送

症状：在控制面板中频道显示已连接，但发送消息后 AI 没有回复。

排查步骤：

# 1. 查看日志中的关键词
openclaw logs --follow

# 常见日志标识：
# "pairing request"     -> 发送者尚未通过配对验证
# "blocked / allowlist" -> 发送者不在白名单中
# "mention required"    -> 群组中需要 @ 机器人才能触发

解决方法 — 配对模式：默认情况下，未知发送者需要配对才能使用 AI。配对码会通过私信发送给你，你需要在自己的终端批准：

openclaw pairing list --channel telegram
openclaw pairing approve telegram <code>

解决方法 — 白名单模式：如果希望任何人都能使用，设置 dmPolicy=open 并将发送者加入白名单：

{
  "channels": {
    "telegram": {
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  }
}

问题六：WhatsApp / Telegram 登录失效

症状：之前正常的 WhatsApp 或 Telegram 频道突然断开连接。

解决方法：

# Telegram：重新添加 bot token
docker compose run --rm openclaw-cli channels add --channel telegram --token "<new-token>"

# WhatsApp：重新扫码登录
docker compose run --rm openclaw-cli channels login --channel whatsapp

# 查看详细的频道诊断
openclaw channels status --probe

WhatsApp 登录失效通常是因为 WhatsApp 检测到多设备登录异常。建议使用专门的 WhatsApp Business 账号而非个人账号。

问题七：Control UI（控制面板）无法打开

症状：浏览器访问 http://127.0.0.1:18789/ 一直转圈或显示 502。

排查步骤：

# 1. 确认网关在运行
openclaw gateway status

# 2. 查看控制面板地址
openclaw gateway status | grep Dashboard

# 3. 检查日志
openclaw logs --follow

常见原因 — 设备未授权：新浏览器需要完成设备配对。在日志中查找 device identity required，然后：

# 获取新的仪表盘链接并批准设备
docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

常见原因 — Origin 不允许：如果从非 localhost 访问，需要在配置中添加允许的 Origin：

{
  "gateway": {
    "controlUi": {
      "allowedOrigins": ["http://你的域名.com", "https://你的域名.com"]
    }
  }
}

问题八：提示 missing scope: operator.read

这是 openclaw gateway probe 的正常降级提示，不代表连接失败。

– 如果你能正常打开控制面板并使用 AI 对话，则无需担心

– 如果无法正常使用，再用 openclaw status –deep 做进一步诊断

问题九：代理（Proxy）环境下无法连接

如果你在公司网络或使用 VPN 的环境下，代理可能会干扰 WebSocket 连接。

# 设置 HTTPS_PROXY 环境变量
export HTTPS_PROXY=http://your-proxy:8080

# 或者在配置中设置
openclaw config set gateway.proxy "http://your-proxy:8080"
openclaw gateway restart

问题十：Ollama / LM Studio 等本地模型无法调用

Docker 部署时，由于容器内的 127.0.0.1 指向容器自身而非宿主机，需要使用特殊地址：

提供商	宿主机地址	Docker 内地址
LM Studio	http://127.0.0.1:1234	http://host.docker.internal:1234
Ollama	http://127.0.0.1:11434	http://host.docker.internal:11434

同时确保本地模型服务监听的地址是 0.0.0.0 而非 127.0.0.1：

# LM Studio
lms server start --port 1234 --bind 0.0.0.0

# Ollama
OLLAMA_HOST=0.0.0.0:11434 ollama serve

安全建议

OpenClaw 连接真实的聊天平台，处理不受信任的输入时需要注意以下安全要点：

默认 DM 配对机制：在 Telegram、WhatsApp、Discord 等平台，陌生人的私信默认会被拦截并要求配对。切勿将 dmPolicy 设置为 open 除非你确实需要向所有人开放。

不要在公开群组暴露 AI 访问权限：如果 AI 在公开频道运行，设置群组白名单，只允许特定用户触发 AI。

定期检查已批准设备列表：

openclaw devices list
openclaw devices revoke <deviceId>

敏感操作需要确认：默认配置下，危险操作（如执行系统命令、访问文件等）会触发审批流程，不要随意绕过。

更新与升级

保持 OpenClaw 更新可以获取最新功能和安全性修复。

# 检查当前版本
openclaw --version

# 升级到最新稳定版
openclaw update

# 在 Docker 中更新
docker compose pull
docker compose up -d openclaw-gateway

# 运行 doctor 检查更新后的状态
openclaw doctor

建议在更新前备份配置文件 ~/.openclaw/openclaw.json，以便在出现问题时快速回滚。

什么是 OpenClaw

系统要求

安装方法详解

方法一：官方安装脚本（推荐）

macOS / Linux / WSL2

Windows (PowerShell)

方法二：npm / pnpm / bun 安装

npm 安装

pnpm 安装

bun 安装

方法三：Docker 部署

快速部署步骤

使用预构建镜像

手动 Docker 部署

持久化存储配置

方法四：从源码编译

初始化与配置

运行引导向导

验证网关状态

打开控制面板

常见问题与解决方法

问题一：网关无法启动（EADDRINUSE）

问题二：Node 版本不兼容

问题三：sharp 构建失败（npm 安装）

问题四：Docker 镜像构建 OOM（内存不足）

问题五：频道连接成功但消息不发送

问题六：WhatsApp / Telegram 登录失效

问题七：Control UI（控制面板）无法打开

问题八：提示 missing scope: operator.read

问题九：代理（Proxy）环境下无法连接

问题十：Ollama / LM Studio 等本地模型无法调用

安全建议

更新与升级

相关资源

相关推荐

Docker 部署 WordPress 完整指南：从安装到常见问题排查

Hermes Agent 多 Agent 实战：创建、部署与配置完整指南

Hermes Agent 部署安装与常见问题完全指南