OpenClaw 完整部署教程（双方案 + 混合模型）

网管NO.12026-03-28 8:49

教程说明

本教程适用于零基础用户，涵盖：

  • 方案一：Windows 原生直装（快速体验）

  • 方案二：WSL2 部署（生产环境推荐）

  • 混合模型配置：本地 Ollama + 云端 API 组合使用

阅读方式：可直接复制命令执行，每个步骤都包含「可能遇到的问题及解决办法」。

目录

  1. 环境准备（两种方案通用）

  2. 方案一：Windows 原生直装

  3. 方案二：WSL2 部署（推荐）

  4. 混合模型配置（本地+云端）

  5. 常用管理命令

  6. 完整常见问题汇总

一、环境准备（两种方案通用）

在开始任何方案之前，请先完成以下准备工作。

1.1 检查系统版本

Windows 用户：

  • 按 Win + R，输入 winver，回车

  • 确认版本为 Windows 10 版本 2004 或更高 / Windows 11

可能遇到的问题：

问题 原因 解决办法
系统版本过低 Windows 10 版本 1909 及以下不支持 WSL2 升级 Windows 系统，或使用原生直装方案

1.2 安装 Node.js 22+

操作步骤：

  1. 访问 Node.js 官网：https://nodejs.org/

  2. 下载 LTS 版本（推荐 22.x.x）

  3. 运行安装程序，务必勾选 "Automatically install the necessary tools" 或 "Add to PATH"

  4. 安装完成后，打开 CMD 或 PowerShell，执行验证：

cmd

复制代码 
node -v
npm -v

预期输出：

text

复制代码 
v22.14.0
10.9.2

可能遇到的问题：

问题 原因 解决办法
node 不是内部或外部命令 安装时未勾选 Add to PATH 手动添加 C:\Program Files\nodejs 到系统环境变量 Path，重启终端
版本低于 22.x 安装了旧版本 卸载后重新下载 Node.js 22.x
安装过程卡住 网络问题 关闭终端，以管理员身份重新运行安装程序

1.3 安装 Git

操作步骤：

  1. 访问 Git 官网：https://git-scm.com/download/win

  2. 下载并运行安装程序

  3. 安装时保持默认选项，确保 "Git from the command line" 被选中

  4. 验证安装：

cmd

复制代码 
git --version

预期输出：

text

复制代码 
git version 2.45.0.windows.1

1.4 配置 npm 镜像（国内用户必做）

操作步骤（在 CMD 或 PowerShell 中执行）：

cmd

复制代码 
npm config set registry https://registry.npmmirror.com/

验证配置：

cmd

复制代码 
npm config get registry

预期输出：

text

复制代码 
https://registry.npmmirror.com/

可能遇到的问题：

问题 原因 解决办法
配置后安装仍慢 镜像未生效 执行 npm config delete registry 清除后重新配置
某些包仍从国外下载 包内部硬编码了源 不影响，耐心等待即可

1.5 安装 Visual C++ Redistributable（Windows 原生版必需）

操作步骤：

  1. 访问微软官网下载：https://aka.ms/vs/17/release/vc_redist.x64.exe

  2. 运行安装程序，如果提示"已安装"则跳过

  3. 安装后建议重启电脑

可能遇到的问题：

问题 原因 解决办法
安装失败提示 0x80240017 系统更新未完成 运行 Windows Update 更新后重试
重启后仍提示缺少 dll 未安装完整 下载安装 Visual C++ 2015-2022 Redistributable（x64 和 x86 都装）

二、方案一：Windows 原生直装（快速体验）

⚠️ 注意：此方案适合快速体验，官方文档明确说明 Windows 原生环境未完全测试。如果你希望长期稳定使用，请直接跳转到 方案二：WSL2 部署。

2.1 配置 PowerShell 执行策略

操作步骤（以管理员身份打开 PowerShell）：

powershell

复制代码 
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

预期输出：无报错信息。

可能遇到的问题：

问题 原因 解决办法
提示"没有足够的权限" 未以管理员身份运行 右键 PowerShell 图标，选择"以管理员身份运行"

2.2 一键安装 OpenClaw

操作步骤（在 PowerShell 中执行）：

powershell

复制代码 
iwr -useb https://openclaw.ai/install.ps1 | iex

如果上述命令失败，尝试备用命令：

powershell

复制代码 
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta

预期过程：

  • 自动下载安装脚本

  • 安装 OpenClaw 到全局

  • 显示安装完成信息

可能遇到的问题：

问题 原因 解决办法
iwr : 无法连接到远程服务器 网络问题，无法访问 openclaw.ai 检查网络连接，或配置代理；可尝试使用 npm install -g openclaw@latest 替代
Windows Defender 拦截 安全软件误报 点击"更多信息"→"仍要运行"；或临时关闭实时防护
安装过程卡住 20 分钟以上 sharp/vips 等原生模块编译慢 耐心等待；若持续失败，改用 WSL2 方案

2.3 验证安装

powershell

复制代码 
openclaw --version

预期输出：

text

复制代码 
2026.3.13

可能遇到的问题：

问题 原因 解决办法
openclaw : 无法将"openclaw"项识别为 cmdlet npm 全局路径未加入 PATH 1. 关闭 PowerShell 重新打开 2. 若仍无效，手动添加路径：C:\Users\你的用户名\AppData\Roaming\npm 到环境变量 Path

2.4 初始化配置

操作步骤：

powershell

复制代码 
openclaw onboard --install-daemon

向导会依次询问以下问题（建议选择）：

提示 推荐选择 说明
I understand this is powerful and inherently risky. Continue? Yes 确认风险
Onboarding mode QuickStart 快速开始模式
Model/auth provider Skip for now 稍后配置模型（或直接选 OpenAI）
Filter models by provider All providers 显示所有模型
Default model 回车使用默认 默认即可
Select channel Skip for now 稍后配置频道
Configure skills now? No 稍后配置技能
Install systemd service? Yes（如提示） 安装服务（Windows 原生可能无此选项）

可能遇到的问题：

问题 原因 解决办法
向导中途退出 网络超时或配置写入失败 重新执行 openclaw onboard
提示"未找到 API Key" 选择了 Skip 后续通过 openclaw config 手动配置

2.5 启动 Gateway 服务

powershell

复制代码 
openclaw gateway start

预期输出：

text

复制代码 
Gateway started on port 18789

可能遇到的问题：

问题 原因 解决办法
Error: listen EADDRINUSE: address already in use :::18789 端口 18789 被占用 1. 查找占用进程：`netstat -ano
Gateway 启动后立即退出，无任何输出 原生模块（matrix-sdk）下载不完整 卸载重装：npm uninstall -g openclaw → npm install -g openclaw

2.6 打开 Web 控制台

powershell

复制代码 
openclaw dashboard

浏览器会自动打开 http://localhost:18789

可能遇到的问题：

问题 原因 解决办法
浏览器显示"无法访问此网站" Gateway 未启动 检查 openclaw gateway status，若未运行则执行 openclaw gateway start
提示需要 Token 未生成访问令牌 执行 openclaw token generate 查看令牌

三、方案二：WSL2 部署（推荐）

✅ 这是官方推荐的部署方式，兼容性最好，支持完整的 systemd 服务管理，适合长期使用。

3.1 安装 WSL2

操作步骤（以管理员身份打开 PowerShell）：

powershell

复制代码 
# 安装 WSL2 和默认 Ubuntu 发行版
wsl --install

如果需要指定 Ubuntu 版本：

powershell

复制代码 
wsl --install -d Ubuntu-24.04

预期过程：

  • 启用 Windows 功能

  • 下载并安装 WSL2 内核

  • 下载 Ubuntu 镜像

  • 提示重启电脑

可能遇到的问题：

问题 原因 解决办法
wsl : 无法将"wsl"项识别为 cmdlet Windows 版本过低 升级到 Windows 10 2004+ 或 Windows 11
安装过程卡在 0% 或 75% 网络问题，无法下载镜像 1. 检查网络连接 2. 手动下载发行版：在 Microsoft Store 搜索 Ubuntu 安装
提示"WSL 2 需要更新其内核组件" 内核未安装 执行 wsl --update

重启电脑后继续。

3.2 初始化 Ubuntu

操作步骤：

  1. 在开始菜单中找到 "Ubuntu" 并打开

  2. 等待初始化完成（约 1-2 分钟）

  3. 提示输入 用户名 （如 yourname，小写字母）

  4. 提示输入 密码（输入时不显示，正常输入后回车）

  5. 确认密码

可能遇到的问题：

问题 原因 解决办法
打开 Ubuntu 后黑屏闪退 WSL2 未正确安装 在 PowerShell 执行 wsl --unregister Ubuntu 后重新安装
提示"参考的对象类型不支持尝试的操作" Windows 代理软件冲突 以管理员身份执行 netsh winsock reset，重启电脑

3.3 更新系统并安装基础工具

操作步骤（在 Ubuntu 终端中执行）：

bash

复制代码 
# 更新软件源
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install curl git build-essential python3 python3-pip -y

可能遇到的问题：

问题 原因 解决办法
sudo: command not found 未正确进入 Ubuntu 环境 确认打开的是 Ubuntu 终端，而非 PowerShell
更新过程卡住 网络问题 等待或 Ctrl+C 取消后重试
Unable to fetch some archives 源连接失败 执行 sudo apt update 重试

3.4 配置 WSL2 内存限制（关键步骤）

默认 WSL2 会占用宿主机最多 50% 的内存，可能导致 OpenClaw 运行不稳定或被系统终止。此步骤强制限制内存使用。

操作步骤（回到 Windows，在 PowerShell 中执行）：

powershell

复制代码 
# 进入用户目录
cd $env:USERPROFILE

# 创建 .wslconfig 文件
New-Item -Path $env:USERPROFILE -Name ".wslconfig" -ItemType "File"

# 用记事本打开编辑
notepad .wslconfig

在记事本中输入以下内容（根据你的电脑配置调整数值）：

ini

复制代码 
[wsl2]
memory=8GB
processors=4
swap=4GB
localhostForwarding=true

配置参考表（宿主机配置 → 推荐值）：

宿主机内存 推荐 memory 推荐 processors 推荐 swap
8GB 4GB 2 2GB
16GB 8-10GB 4 4GB
32GB 16-20GB 6-8 8GB

保存文件（Ctrl+S）并关闭记事本。

使配置生效（在 PowerShell 中执行）：

powershell

复制代码 
wsl --shutdown

然后重新打开 Ubuntu 终端。

验证配置（在 Ubuntu 终端中执行）：

bash

复制代码 
free -h

观察 Mem: 行的 total 值，应接近你设置的 memory 值（允许 ±200MB 误差）。

可能遇到的问题：

问题 原因 解决办法
free -h 显示的值与设置不符 WSL2 预留了少量内存 误差在 200MB 内属正常
配置后 Windows 变卡 memory 设置过高 降低 memory 值，留足够内存给 Windows
无法创建 .wslconfig 文件 文件名不正确 确保文件名为 .wslconfig（注意开头有点），存放在 C:\Users\你的用户名\ 下

3.5 启用 Systemd

OpenClaw 需要 systemd 来管理后台服务，WSL2 默认未启用。

操作步骤（在 Ubuntu 终端中执行）：

bash

复制代码 
# 编辑配置文件
sudo nano /etc/wsl.conf

在打开的编辑器中输入：

ini

复制代码 
[boot]
systemd=true

保存退出：

  • 按 Ctrl + X

  • 按 Y 确认保存

  • 按 Enter 退出

重启 WSL（在 Windows PowerShell 中执行）：

powershell

复制代码 
wsl --shutdown

重新打开 Ubuntu 终端。

验证 systemd（在 Ubuntu 终端中执行）：

bash

复制代码 
systemctl --version

预期输出 ：显示 systemd 版本号（如 systemd 255 (255.4-1ubuntu8)）

可能遇到的问题：

问题 原因 解决办法
Failed to connect to bus: No such file or directory systemd 未启用 检查 /etc/wsl.conf 内容是否正确，确认执行了 wsl --shutdown
编辑 nano 时不知道如何保存 不熟悉 nano 可使用 sudo vi /etc/wsl.conf，或改用 sudo tee /etc/wsl.conf <<EOF 方式

3.6 安装 OpenClaw

操作步骤（在 Ubuntu 终端中执行）：

bash

复制代码 
# 一键安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

如果需要使用 Git 方式安装（推荐，更稳定）：

bash

复制代码 
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

预期过程：

  • 检测 Node.js 环境（若缺失会自动安装）

  • 下载 OpenClaw

  • 全局安装

  • 显示安装成功信息

可能遇到的问题：

问题 原因 解决办法
curl: (7) Failed to connect to openclaw.ai 网络问题 检查网络连接；可尝试配置代理：export https_proxy=http://代理地址:端口
安装后 openclaw: command not found npm 全局路径未加入 PATH 执行：export PATH="$(npm prefix -g)/bin:$PATH"，并添加到 ~/.bashrc
Error: EACCES: permission denied 权限不足 使用 sudo npm install -g openclaw，但推荐修复 npm 权限

3.7 初始化并安装系统服务

操作步骤（在 Ubuntu 终端中执行）：

bash

复制代码 
openclaw onboard --install-daemon

向导会依次询问：

提示 推荐选择 说明
I understand this is powerful and inherently risky. Continue? Yes 确认风险
Onboarding mode QuickStart 快速开始
Model/auth provider Skip for now 稍后配置（或直接选 OpenAI/其他）
Filter models by provider All providers 显示所有模型
Default model 回车 使用默认
Select channel Skip for now 稍后配置
Configure skills now? No 稍后配置
Install systemd service? Yes 安装系统服务（关键）
Enable service on boot? Yes 开机自启

预期输出：

text

复制代码 
✓ OpenClaw installed successfully
✓ Systemd service created
✓ Gateway started on port 18789

可能遇到的问题：

问题 原因 解决办法
向导提示 systemd 相关错误 WSL2 中 systemd 未正确启用 返回 3.5 启用 Systemd 重新配置
openclaw onboard --install-daemon 挂起 网络超时或等待输入 检查是否有未回答的问题；按 Ctrl+C 取消后重试
服务安装成功但 Gateway 未启动 端口冲突或配置错误 执行 openclaw gateway status 检查，若未运行则 openclaw gateway start

3.8 验证部署

bash

复制代码 
# 检查服务状态
openclaw gateway status

预期输出：

text

复制代码 
Gateway status: running (PID: 1234)
Listening on: http://127.0.0.1:18789

bash

复制代码 
# 打开 Web 控制台
openclaw dashboard

浏览器自动打开 http://localhost:18789。

可能遇到的问题：

问题 原因 解决办法
Gateway status: stopped 服务未启动 执行 openclaw gateway start
Web 控制台无法访问 端口未放行 检查防火墙：sudo ufw allow 18789；WSL2 中需确认 Windows 防火墙放行
提示"未找到 Token" 首次访问需令牌 执行 openclaw token generate 查看令牌，或配置 openclaw config set gateway.auth none（不推荐）

3.9 配置 Windows 开机自动启动 WSL（可选）

如果你希望 OpenClaw 在 Windows 开机后自动运行，执行以下配置。

操作步骤（以管理员身份打开 PowerShell）：

powershell

复制代码 
# 查看你的 WSL 发行版名称
wsl --list --verbose

记下发行版名称（如 Ubuntu）。

创建开机启动计划任务：

powershell

复制代码 
schtasks /create /tn "OpenClaw WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM

在 WSL 内启用用户服务持久化（在 Ubuntu 终端中执行）：

bash

复制代码 
sudo loginctl enable-linger "$(whoami)"

验证 ：重启 Windows 后，打开 Ubuntu 终端，执行 openclaw gateway status 检查服务是否自动运行。

可能遇到的问题：

问题 原因 解决办法
开机后服务未启动 linger 未生效或 WSL 启动慢 在 WSL 中执行 openclaw gateway start 手动启动
计划任务创建失败 权限不足 确保 PowerShell 以管理员身份运行

四、混合模型配置（本地+云端）

OpenClaw 支持同时配置多个模型，通过 fallback 机制自动调度，实现成本与效果的平衡。

4.1 安装 Ollama（本地模型）

WSL2 环境（在 Ubuntu 终端中执行）：

bash

复制代码 
# 使用官方脚本安装（国内用户可能较慢）
curl -fsSL https://ollama.com/install.sh | sh

# 或使用阿里云镜像加速（国内用户推荐）
curl -fsSL https://mirrors.aliyun.com/ollama/install.sh | sh

验证安装：

bash

复制代码 
ollama --version

启动 Ollama 服务：

bash

复制代码 
# 以后台服务方式运行
ollama serve &

下载本地模型（推荐千问 3.5 系列）：

bash

复制代码 
# 轻量版（约 0.8B，适合低配设备）
ollama pull qwen3.5:0.8b

# 标准版（约 7B，推荐，需 8GB+ 内存）
ollama pull qwen3.5:7b

# 专业版（约 35B，需 32GB+ 内存）
ollama pull qwen3.5:35b

验证模型可用：

bash

复制代码 
ollama run qwen3.5:7b "你好，请介绍一下你自己"

可能遇到的问题：

问题 原因 解决办法
ollama: command not found 安装未完成或 PATH 未更新 重新打开终端，或执行 export PATH=$PATH:/usr/local/bin
下载模型速度极慢 网络问题 配置代理，或使用阿里云镜像；可尝试 ollama pull qwen3.5:7b --insecure
运行模型时提示"no such file or directory" 模型未下载完成 执行 ollama list 查看已下载模型，重新下载缺失的模型
内存不足导致模型运行卡顿 模型过大 改用更小的模型（如 qwen3.5:0.8b），或增加 WSL2 内存配置

4.2 获取云端 API Key

阿里云千问 API：

  1. 访问 https://bailian.console.aliyun.com/

  2. 登录阿里云账号（需实名认证）

  3. 进入"密钥管理"，点击"创建 API-Key"

  4. 复制保存生成的 API Key（格式：sk-xxxxx）

腾讯云混元 API：

  1. 访问 https://console.cloud.tencent.com/hunyuan

  2. 开通服务

  3. 进入"接入管理"，创建 API Key

DeepSeek API：

  1. 访问 https://platform.deepseek.com/

  2. 注册账号

  3. 在 API Keys 页面创建密钥

可能遇到的问题：

问题 原因 解决办法
创建 API-Key 后找不到 Secret 仅生成时可见 立即复制保存；若丢失，删除后重新创建
实名认证失败 身份信息不匹配 按平台要求重新提交认证材料

4.3 配置 OpenClaw 多模型

操作步骤（在 Ubuntu 终端或 WSL 中执行）：

配置阿里云千问：

bash

复制代码 
openclaw config set 'models.providers.qwen' --json '{
  "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "apiKey": "sk-你的千问API-Key",
  "api": "openai-completions",
  "models": [
    { "id": "qwen-plus", "name": "Qwen Plus" },
    { "id": "qwen-max", "name": "Qwen Max" },
    { "id": "qwen-turbo", "name": "Qwen Turbo" }
  ]
}'

配置腾讯云混元：

bash

复制代码 
openclaw config set 'models.providers.hunyuan' --json '{
  "baseUrl": "https://api.hunyuan.cloud.tencent.com/v1",
  "apiKey": "你的混元API-Key",
  "api": "openai-completions",
  "models": [
    { "id": "hunyuan-turbos-latest", "name": "Hunyuan Turbos" },
    { "id": "hunyuan-t1-latest", "name": "Hunyuan T1" }
  ]
}'

配置 DeepSeek：

bash

复制代码 
openclaw config set 'models.providers.deepseek' --json '{
  "baseUrl": "https://api.deepseek.com/v1",
  "apiKey": "sk-你的DeepSeek-API-Key",
  "api": "openai-completions",
  "models": [
    { "id": "deepseek-chat", "name": "DeepSeek Chat" },
    { "id": "deepseek-coder", "name": "DeepSeek Coder" }
  ]
}'

配置 Ollama 本地模型：

bash

复制代码 
openclaw config set 'models.providers.ollama' --json '{
  "baseUrl": "http://localhost:11434",
  "api": "ollama",
  "models": [
    { "id": "qwen3.5:7b", "name": "Qwen 3.5 7B" },
    { "id": "qwen3.5:0.8b", "name": "Qwen 3.5 0.8B" }
  ]
}'

设置模型合并模式（允许同时使用多个提供商）：

bash

复制代码 
openclaw config set models.mode merge

设置默认模型：

bash

复制代码 
# 设置为 DeepSeek 作为默认（性价比高）
openclaw models set deepseek/deepseek-chat

# 或设置为本地模型（免费但速度较慢）
openclaw models set ollama/qwen3.5:7b

# 或设置为千问（国内稳定）
openclaw models set qwen/qwen-plus

验证模型配置：

bash

复制代码 
# 列出所有已配置模型
openclaw models list

# 探测模型连通性（会发送真实请求）
openclaw models status --probe

预期输出：

text

复制代码 
✓ deepseek/deepseek-chat: OK (latency: 1.2s)
✓ qwen/qwen-plus: OK (latency: 0.8s)
✓ ollama/qwen3.5:7b: OK (latency: 3.5s)

可能遇到的问题：

问题 原因 解决办法
Invalid configuration: provider 'xxx' has no 'api' field 配置格式错误 确保 "api" 字段正确（openai-completions 或 ollama）
Failed to probe model: 401 Unauthorized API Key 无效 检查 API Key 是否正确，是否已过期
Failed to probe model: ECONNREFUSED 本地 Ollama 未运行 执行 ollama serve & 启动 Ollama
模型列表为空 配置未生效 执行 openclaw gateway restart 重启网关后重试

4.4 配置 Fallback 链（可选）

操作步骤 ：编辑配置文件 ~/.openclaw/openclaw.json

bash

复制代码 
nano ~/.openclaw/openclaw.json

添加或修改 llm 部分：

json

复制代码 
{
  "llm": {
    "fallback": {
      "strategy": "priority",
      "chain": [
        { "provider": "deepseek/deepseek-chat", "timeout": 30 },
        { "provider": "qwen/qwen-plus", "timeout": 45 },
        { "provider": "ollama/qwen3.5:7b", "timeout": 60 }
      ]
    }
  }
}

保存后重启网关：

bash

复制代码 
openclaw gateway restart

工作原理：

  1. 优先使用 DeepSeek（性价比高）

  2. 如果 DeepSeek 超时或失败，自动切换到千问

  3. 如果千问也失败，最后使用本地 Ollama

4.5 测试混合模型

bash

复制代码 
# 使用默认模型对话
openclaw agent --message "你好，介绍一下你自己"

# 指定使用特定模型
openclaw agent --model deepseek/deepseek-chat --message "用中文介绍 DeepSeek"

# 指定使用本地模型
openclaw agent --model ollama/qwen3.5:7b --message "1+1等于几？"

可能遇到的问题：

问题 原因 解决办法
模型响应极慢 本地模型运行慢或云端 API 延迟高 检查网络；本地模型可改用更小的版本
模型返回乱码 模型编码问题 确认请求使用 UTF-8，尝试其他模型
本地模型无响应 Ollama 服务中断 执行 ollama list 确认服务运行，否则重新启动 ollama serve

五、常用管理命令

5.1 服务管理

bash

复制代码 
# 查看 Gateway 状态
openclaw gateway status

# 启动 Gateway
openclaw gateway start

# 停止 Gateway
openclaw gateway stop

# 重启 Gateway
openclaw gateway restart

5.2 配置管理

bash

复制代码 
# 查看当前配置
openclaw config get

# 设置配置项
openclaw config set key value

# 查看模型列表
openclaw models list

# 查看模型状态（连通性探测）
openclaw models status --probe

# 设置默认模型
openclaw models set provider/model-id

5.3 日志查看

bash

复制代码 
# 查看实时日志
openclaw logs follow

# 查看最近 50 行日志
openclaw logs --tail 50

# 查看特定级别日志
openclaw logs --level debug

5.4 诊断与故障排除

bash

复制代码 
# 运行健康检查（首选诊断命令）
openclaw doctor

5.5 Web 控制台

bash

复制代码 
# 打开 Web 控制台
openclaw dashboard

# 生成访问令牌
openclaw token generate

5.6 技能管理

bash

复制代码 
# 列出已安装技能
openclaw skills list

# 安装技能
openclaw skills install skill-name

# 更新技能
openclaw skills update skill-name

没有问题就结束了嗷，直接自己操作去就中了

六、完整常见问题汇总

6.1 安装问题

问题现象 可能原因 解决方案
openclaw: command not found npm 全局路径未加入 PATH WSL2 ：export PATH="$(npm prefix -g)/bin:$PATH" 并添加到 ~/.bashrc Windows ：将 C:\Users\用户名\AppData\Roaming\npm 添加到系统环境变量 Path
sharp 模块编译失败 Windows 原生环境缺少编译工具 执行：SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw
Gateway 启动无任何输出，进程退出 matrix-sdk 原生二进制下载不完整（正常应 ~22MB，下载不完整时仅 2.4MB） 检查文件大小：ls -lh $(npm root -g)/openclaw/node_modules/.pnpm/@matrix-org+*/node_modules/@matrix-org/matrix-sdk-crypto-nodejs/*.node 重新安装：npm uninstall -g openclaw && npm install -g openclaw
ReferenceError: Cannot access 'ANTHROPIC_MODEL_ALIASES' before initialization v2026.3.12 版本存在 TDZ bug 降级到稳定版：npm install -g openclaw@2026.3.11 或升级到已修复版本：npm install -g openclaw@2026.3.13-1
Windows Defender 拦截安装 安全软件误报 点击"更多信息"→"仍要运行"；或在 Windows 安全中心添加排除项
安装脚本下载失败 网络无法访问 openclaw.ai 配置代理；或使用阿里云镜像安装（见下文备用方案）

6.2 WSL2 专属问题

问题现象 可能原因 解决方案
Failed to connect to bus: No such file or directory systemd 未启用 检查 /etc/wsl.conf 是否包含 [boot] systemd=true；执行 wsl --shutdown 完全重启
内存不足导致进程被 Killed WSL2 默认内存限制过高或过低 配置 .wslconfig 文件，根据物理内存设置合理值（8GB 内存建议设置 4-6GB）
WSL2 开机后 OpenClaw 服务未启动 linger 未生效或启动顺序问题 执行 sudo loginctl enable-linger "$(whoami)"；或在 Windows 创建计划任务
openclaw onboard --install-daemon 挂起 systemd --user 检测失败 若 systemd 无法启用，改用手动后台启动：nohup openclaw gateway start > ~/.openclaw/logs/gateway.log 2>&1 &
无法访问 Gateway（localhost:18789） Windows 防火墙阻止 在 PowerShell（管理员）执行：New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

6.3 运行问题

问题现象 可能原因 解决方案
EADDRINUSE: address already in use :::18789 端口被占用 查找占用：lsof -i :18789（WSL2）或 `netstat -ano
Gateway 频繁崩溃（Telegram 渠道） Telegram 长轮询超时未捕获 配置自动重启：在 systemd 服务中添加 Restart=on-failure
内存溢出（OOM） Node.js 堆内存不足 限制堆内存：openclaw config set gateway.nodeOptions "--max-old-space-size=512" 或降级到内存占用较低的版本
openclaw node run 命令挂起 Gateway 未运行或连接问题 检查 Gateway 状态：openclaw gateway status；完整重启：openclaw gateway stop && openclaw gateway start

6.4 API 配置问题

问题现象 可能原因 解决方案
No API key found for provider API Key 未配置或配置错误 检查配置：openclaw config get models.providers.提供商名称 重新配置：openclaw config set models.providers.提供商名称.apiKey "你的密钥"
401 Unauthorized API Key 无效或过期 登录平台控制台重新生成 API Key，更新配置后重启 Gateway
429 Too Many Requests 触发限流 降低请求频率；检查是否开启了免费额度耗尽
模型返回空响应或超时 网络问题或模型服务异常 检查网络连通性；尝试切换其他模型；增加 timeout 配置
阿里云千问返回错误码 API 调用格式问题 确认 baseUrl 为 https://dashscope.aliyuncs.com/compatible-mode/v1，api 字段为 openai-completions

6.5 诊断命令速查

当遇到任何问题时，按以下顺序执行诊断：

bash

复制代码 
# 1. 运行健康检查（最重要）
openclaw doctor

# 2. 检查 Node.js 版本
node -v  # 必须是 v22.x

# 3. 检查 OpenClaw 版本
openclaw --version

# 4. 检查 Gateway 状态
openclaw gateway status

# 5. 查看最近日志
openclaw logs --tail 50

# 6. 检查模型连通性
openclaw models status --probe

# 7. 检查配置是否有效
openclaw config get | head -20

6.6 常用备用安装方案

如果官方安装脚本无法访问，使用以下备用方案：

方案一：使用 npm 直接安装：

bash

复制代码 
npm install -g openclaw@latest
openclaw onboard

方案二：使用阿里云镜像安装（国内用户）：

bash

复制代码 
# 设置 npm 镜像
npm config set registry https://registry.npmmirror.com

# 安装
npm install -g openclaw@latest

方案三：使用 pnpm 安装：

bash

复制代码 
# 安装 pnpm
npm install -g pnpm

# 使用 pnpm 安装 openclaw
pnpm add -g openclaw@latest

方案四：Docker 部署（适用于云服务器）：

bash

复制代码 
# 拉取镜像
docker pull openclaw/openclaw:latest

# 创建数据目录
mkdir -p ~/.openclaw/{config,skills,logs,memory,workspace}

# 启动容器
docker run -d \
  --name openclaw \
  --restart always \
  -p 18789:18789 \
  -v ~/.openclaw/config:/app/config \
  -v ~/.openclaw/skills:/app/skills \
  -v ~/.openclaw/logs:/app/logs \
  -v ~/.openclaw/memory:/app/memory \
  -v ~/.openclaw/workspace:/app/workspace \
  -e TZ=Asia/Shanghai \
  openclaw/openclaw:latest

# 进入容器配置
docker exec -it openclaw bash
openclaw onboard
exit

总结

对比项 方案一（原生直装） 方案二（WSL2）
安装难度 ⭐⭐ ⭐⭐⭐
稳定性 ⭐⭐ ⭐⭐⭐⭐⭐
systemd 服务支持 ❌ ✅
插件兼容性 部分问题 完整支持
开机自启 需手动创建计划任务 systemd 自动管理
推荐场景 快速体验、尝鲜 生产使用、长期运行

最终建议：

  • 新手/长期使用：选择方案二（WSL2）

  • 只是想试试：可选择方案一，遇到问题再切回 WSL2

  • 遇到任何问题 ：第一个命令永远是 openclaw doctor

祝部署顺利！如有问题，可通过 openclaw logs 查看日志进行排查。

相关推荐
荣仔灬2 小时前
怎么查询SSL证书的信息？
网络·网络协议·ssl
cui_win2 小时前
Rocky Linux(9.7) 完整使用指南（ISO下载 + 系统安装 + 网络配置）
linux·网络·rocky linux
有毒的教程2 小时前
Ubuntu 日常常用命令速查表（新手版）
linux·服务器·ubuntu
腾科IT教育2 小时前
华为数通Datacom认证各级别难度差多少？
运维·服务器·信息与通信·华为认证·hcip
羑悻的小杀马特2 小时前
从入门到稳定运行：RocketMQ 5.3.4 单机版安装与开机自启配置详解
运维·服务器·rocketmq
卓豪终端管理2 小时前
当补丁还在路上，如何打赢零日漏洞的时间战？
网络·安全·web安全
ywf12152 小时前
Nginx 缓存清理
运维·nginx·缓存
曹牧2 小时前
Java：解析Json字符串格式要求
java·linux·运维·前端
海海不瞌睡（捏捏王子）2 小时前
《计算机网络》再学习
网络·学习·计算机网络
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03围棋-html版本04班级宠物园部署指南05小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）06【计算机一级WPSoffice】小黑课堂题库软件下载安装教程（2026年3月最新版）07Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南08UV安装并设置国内源09OpenClaw 使用和管理 MCP 完全指南10中国象棋-html版本