OpenClaw完整安装避坑指南

🦞

OpenClaw

完整安装避坑指南

新手小白的血泪史 · 从零开始手把手教你跳过所有坑

本文以真实安装经历，完整记录了 OpenClaw 安装过程中的所有问题和解决方案。

如果你也是新手，跟着这篇指南走，能避开我踩过的所有坑。

第一关搞清楚 OpenClaw 是什么

🦞 OpenClaw

AI 消息路由网关，让 AI 接入 WhatsApp、Telegram、Discord 等聊天平台

💻 WorkBuddy

本地执行助理，帮你批量处理文件、生成 PPT、分析数据

💡 关系说明

两者不是竞争关系，而是互补：OpenClaw 负责“连接渠道”，WorkBuddy 负责“深度办公”。

第二关安装环境选择

✅ 官方推荐

官方明确推荐使用 WSL2 环境安装，更稳定、更兼容。

🖥️Windows 11 — 宿主系统

⬇️WSL2（Windows Subsystem for Linux 2）— 虚拟化技术层

⬇️Ubuntu（Linux 发行版）— 你安装的系统✅

🤞 OpenClaw

📦 Node.js v22

🔧 Build Tools

📌 确认方法

在 PowerShell 里执行 wsl --install 然后安装 Ubuntu = WSL2 下的 Ubuntu ✅，这正是官方推荐的方式。

第三关网络故障大坑（重点！）

⚠️ 警告

这是整个安装过程中最大的坑！安装前务必先检查网络。

终端输出

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

# 报错：

curl: (6) Could not resolve host: openclaw.ai

诊断输出

wsl -e bash -c "ip link"

# 输出：

wsl: 检测到 localhost 代理配置，但未镜像到 WSL...

1: lo:...

link/loopback00:00:00:00:00:00

❌ 根本原因

WSL2 网络完全没启动。配置了 networkingMode=mirrored（镜像网络模式）但系统不兼容，错误代码 0x8007054f。

①

打开配置文件

PowerShell

notepad $env:USERPROFILE\.wslconfig

②

删除或注释镜像配置

配置文件

[wsl2]

# networkingMode=mirrored← 删除或注释这一行

③

重启 WSL2

PowerShell

wsl --shutdown

wsl

④

验证网络

终端

hostname -I

# 输出：172.17.148.133（有 IP 就说明正常）

第四关安装过程详解

安装命令

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

安装日志

· Installing Linux build tools (make/g++/cmake/python3)

✓ Build tools installed

✓ Node.js v22 installed

· Active Node.js: v22.22.2 (/usr/bin/node)

· Active npm: 10.9.7 (/usr/bin/npm)

[2/3] Installing OpenClaw

✓ Git already installed

· Configuring npm for user-local installs

✓ npm configured for user installs

· Installing OpenClaw v2026.4.12

组件

作用说明

Build Tools

编译 C/C++ 扩展模块所需的基础工具

Node.js v22

OpenClaw 的运行时依赖

npm

Node 包管理器，管理依赖包

user-local 配置

避免使用 sudo，更安全

第五关安全警告与配置向导

安全提示

🦞 OpenClaw 2026.4.12 (1c0672b)

Security warning — please read.

OpenClaw is a hobby project and still in beta.

Expect sharp edges.

By default, OpenClaw is a personal agent:

one trusted operator boundary.

This bot can read files and run actions

if tools are enabled.

🔒 核心意思

OpenClaw 能读取文件、执行命令，默认是个人使用边界。如果多人共用或暴露到公网，需要做好权限隔离。选择 Yes 继续即可。

第六关模型配置坑

错误输出

◇MiniMax auth method

│MiniMax OAuth (CN)

│

◇MiniMax OAuth failed:

fetchfailed | getaddrinfo EAI_AGAIN api.minimaxi.com

❌ 错误分析

EAI_AGAIN 是 DNS 解析超时，说明 WSL2 虽然网络通了，但访问外部 API 还是有问题。

✅ 操作指引

返回上一步，选择 API Key 方式（而非 OAuth）。模型选择默认的 MiniMax-M2.7 即可（200k 上下文，带推理能力）。

第七关Gateway 启动与访问

配置完成输出

Web UI: http://127.0.0.1:18789/

Gateway WS: ws://127.0.0.1:18789

Gateway: not detected (gateway closed (1006))

Configure complete.

⚠️ 注意

Gateway 显示 closed (1006) 说明服务还没启动，需要手动启动！

①

启动 Gateway

终端

openclaw gateway start

# 输出：

Restarted systemd service: openclaw-gateway.service

②

验证状态

终端

openclaw gateway status

# 正常输出：

Service: systemd (enabled)

Runtime: running (pid 772, state active)

RPC probe: ok

Listening: 127.0.0.1:18789

Dashboard: http://127.0.0.1:18789/

第八关Web 界面访问

终端

openclaw dashboard

# 输出：

Dashboard URL: http://127.0.0.1:18789/#token=b13255e9...

Copied to clipboard.

浏览器地址栏

http://localhost:18789/

# 或带 token 的完整链接：

http://localhost:18789/#token=b13255e9c35cb29e1547...

📋完整问题汇总表

阶段

问题

错误信息

解决方案

安装前

不清楚安装环境

—

官方推荐 WSL2

网络

DNS 解析失败

Could not resolve host

修复 WSL2 网络配置

网络

WSL2 无网卡

hostname -I 无输出

删除 .wslconfig 镜像配置

网络

镜像模式不兼容

0x8007054f

恢复 NAT 模式

配置

OAuth 超时

EAI_AGAIN

改用 API Key 方式

启动

Gateway 未运行

closed (1006)

openclaw gateway start

访问

浏览器打不开

127.0.0.1 拒绝连接

确认 Gateway + localhost

🏆核心经验总结

1. WSL2 网络是最大坑

• 安装前务必检查 hostname -I 是否有输出

• 镜像模式（mirrored）并非所有系统都兼容

• 遇到网络问题，优先恢复默认 NAT 模式

2. 模型配置选 API Key

• OAuth 需要稳定的网络连接，容易失败

• API Key 方式更可靠，国内用户推荐

3. Gateway 状态要确认

• 配置完成后务必执行 openclaw gateway status

• 确保 Runtime: running 和 RPC probe: ok

4. 访问方式

• WSL2 和 Windows 网络互通后，用 http://localhost:18789/ 访问

• 首次登录需要带 token 的链接

希望这篇指南能帮到你！

如果觉得有用，欢迎分享给更多朋友 ❤️