OpenClaw 一站式安装部署教程
一、WSL安装与网络配置
微软在 Windows 11 中极大地简化了安装流程，通过单一命令即可完成组件核心的实现。
1.1 WSL版本说明
WSL（适用于Linux的Windows子系统）目前有两个主要版本：
WSL 1：早期版本，采用系统调用转换层
WSL 2：最新版本，运行完整的Linux内核，性能更佳
强烈建议使用 WSL 2，因为它提供了完整的内核支持和更好的性能。
1.2 一键安装WSL
在具有管理员权限的 PowerShell 或 Windows 终端中，执行以下命令：
wsl –install
此操作将自动执行以下逻辑：
启用虚拟机平台（Virtual Machine Platform） – WSL 2 的底层虚拟化技术
实现适用于Linux的Windows子系统-WSL核心组件
下载并安装最新的 Linux 内核- WSL 2 需要完整的内核
默认下载并安装Ubuntu发行版-主流的Linux发行版
安装完成后，必须重新启动计算机才能Hyper-V管理程序生效。
1.3 验证安装状态
重启后，通过以下命令验证状态：
wsl –status
wsl –version
预期成果：
WSL 版本: 2.0.xxxx.0
内核版本: 5.15.xxxx
WSLg 版本: 1.0.xxxx
MSRDC 版本: 1.3.xxxx
Direct3D 版本: 1.611.xxxx
DXCore 版本: 10.0.xxxx
Windows 版本: 10.0.22631.xxxx
分析结果应确认当前 WSL 版本为 2.0 以上。
1.4 现有 WSL 用户更新
如果系统中已存在旧版本WSL，建议运行以下命令更新：
wsl –update
此命令将下载并安装最新的 Linux 内核，确保镜像网络模式所需的内核组件已就绪。
1.5 Ubuntu初始化配置
首次启动Ubuntu时，系统会提示创建UNIX用户名和密码：
Installing, this may take a few minutes…
Please create a default UNIX user account. The username and password must not match your Windows username.
New UNIX username: llbk
New password:
Retype password:
该账户拥有sudo权限，是后续执行安装操作的核心身份。
1.6 系统更新与软件源配置
配置镜像国内源（如清华大学TUNA镜像或阿里云镜像），然后执行系统更新：
# 更新软件包索引
sudo apt update# 升级已安装的软件包
sudo apt upgrade -y# 安装常用工具
sudo apt install -y curl wget git
二、WSL网络架构详解与配置
理解 OpenClaw 的 WSL 网络架构的接入和 VPN 兼容性。
2.1 WSL 2 网络架构原理
WSL 2 采用轻量级虚拟机技术，完整的 Linux 内核。在网络运行方面，WSL 2 有两种主要模式：
NAT模式（默认）
在默认的 NAT（网络地址转换）模式下，WSL 2 虚拟机拥有独立的虚拟网络接口：
┌─────────────────────────────────────────────────────────┐
│ Windows 主机
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ WSL 2 虚拟机 (NAT)
│ │ │ │
│ │ eth0: 172.23.64.x (独立虚拟子网)
│ │ Gateway: 172.23.64.1
│ │ DNS: 172.23.64.1
│ └─────────────────────────────────────────────────┘ │
│
│ ▼ ▼
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 虚拟交换机 │ │ Windows │ │
│ │ (Hyper-V) │ │ 网络适配器 │ │
│ └─────────────────┘ └─────────────────┘ │
│
│ ▼
│ ┌─────────────────────────────────────────────────┐
│ │ 物理网络 / Internet │
│ └─────────────────────────────────────────────────┘
NAT模式特点：
WSL 2拥有独立的IP地址（172.xxx范围）
外部网络无法直接访问 WSL 2
需要端口转发才能实现端口访问
VPN兼容性较差，经常出现DNS解析问题
镜像模式（推荐）
镜像模式通过直接将Windows机器的网络接口状态同步到Linux内核中，消除了虚拟子网带来的复杂性：
┌─────────────────────────────────────────────────────────┐
│ Windows 主机 │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ WSL 2 虚拟机 (镜像) │ │
│ │ │ │
│ │ eth0: 与宿主机共享相同局域网 IP │ │
│ │ 直接暴露在 Windows 防火墙中 │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ │ (网络接口直接同步) │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐
│ │ 物理网络 / Internet │
│ └─────────────────────────────────────────────────┘
镜像模式特点：
与同一台机器共享相同的以太网IP
短暂的 IPv6 支持
VPN 兼容性显着提升
周边其他设备可直接发现
防火墙规则直接作用于WSL应用
2.2 镜像模式技术优势对比
维度 NAT模式（默认） 镜像模式 (推荐)
IP地址一致性 独立虚拟IP (172.xxx) 与同一机共享相同的局域网IP
IPv6支持 本质有限 全面原始支持
本地主机行为 跨平台回环综合体 现有回环支持
VPN兼容性 经常导致DNS丢包 显着提升兼容性
外观可见性 需要手动端口转发 周边其他设备可直接发现
防火墙控制 独立规则 直接使用Windows防火墙
端口转发 需要手动配置 消耗配置
2.3 配置.wslconfig 文件
镜像模式属于全局配置，需在Windows用户目录下创建或修改.wslconfig文件。
步骤一：打开文件资源管理器，导航到以下路径：
C:\Users\<您的用户名>\
步骤2：如果文件不存在，创建名为.wslconfig的新文件（注意前面的点号）。
步骤3：使用记事本打开文件，添加以下配置：
[wsl2]
# 启用镜像网络模式 – 这是最重要的配置
networkingMode=mirrored
# 启用 DNS 隧道，防止 VPN 环境下域名解析失效
dnsTunneling=true
# 强制 WSL 使用 Windows 的 HTTP 代理设置
autoProxy=true
# 启用集成防火墙支持
firewall=true[experimental]
# 自动回收闲置内存，优化性能
autoMemoryReclaim=gradual
# 支持主机回环地址访问
hostAddressLoopback=true
步骤4：保存文件。
步骤5：在Windows终端中执行以下命令以应用配置：
wsl –shutdown
步骤6：等待约8次以确保虚拟机彻底关闭，然后重新启动Ubuntu。
验证配置：
进入WSL后，执行以下命令验证网络模式：
# 查看网络接口
ip addr show# 查看路由表
ip route show# 测试与局域网的连通性
ping 192.168.1.1
如果配置成功，您应该能够看到 WSL 使用与 Windows 相同的防火墙 IP 地址段。
2.4 防火墙与策略安全调整
在镜像模式下，WSL2应用将直接暴露在Windows防火墙规则中。为了保证OpenClaw的网络端口能够被正确访问，需要配置Windows防火墙规则。
步骤一：以管理员身份打开PowerShell
在开始菜单中搜索“PowerShell”，右键选择“以管理员身份运行”。
步骤2：配置防火墙规则
在镜像模式下，WSL2应用将直接暴露在Windows防火墙规则中。以下提供两种配置方法：
方法一：标准防火墙命令（推荐用于WSL2）
对于WSL2镜像网络模式，推荐使用标准的Windows防火墙命令：
# 创建入站防火墙规则，允许 OpenClaw 服务端口
New-NetFirewallRule -DisplayName “OpenClaw-Service” -Direction Inbound -Action Allow -Protocol TCP -LocalPort 18789# 验证规则是否创建成功
Get-NetFirewallRule -DisplayName “OpenClaw-Service” | Format-Table
方法二：Hyper-V防火墙命令（需要动态获取VMCreatorId）
如果需要使用Hyper-V防火墙管理WSL2流量，请先动态获取系统的VMCreatorId：
# 步骤 1：获取当前系统所有已注册的 VM 创建者
Get-NetFirewallHyperVVMCreator
重要说明：{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}是示例 GUID，实际值因系统而异。VMCreatorId 是 Hyper-V 防火墙用于标识特定虚拟机创建者的 GUID，每个系统的值都不同。
# 步骤 2：动态获取并配置（推荐）
# 获取所有 VMCreatorId 并配置
Get-NetFirewallHyperVVMCreator | ForEach-Object {
Set-NetFirewallHyperVVMSetting -Name $_.Name -DefaultInboundAction Allow
}# 步骤 3：创建细粒度规则
New-NetFirewallHyperVRule -DisplayName “OpenClaw-Service” -Direction Inbound -Action Allow -Protocol TCP -LocalPorts 18789
步骤3：确认防火墙规则
验证规则已正确创建：
# 查看所有 OpenClaw 相关规则
Get-NetFirewallRule | Where-Object {$_.DisplayName -like “*OpenClaw*”} | Format-Table
步骤 4：测试端口评估性
在Windows主机上测试端口是否开放：
# 测试本地端口
Test-NetConnection -ComputerName localhost -Port 18789# 或使用 telnet
telnet localhost 18789
2.5 NAT模式下的端口转发（创业方案）
如果由于某些原因无法使用镜像模式，可以在NAT模式下配置端口转发：
步骤1：在PowerShell（管理员）中执行：
# 将 WSL 2 的 18789 端口转发到 localhost
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=(wsl hostname -I)
步骤2：获取WSL的IP地址：
wsl hostname -I
步骤 3：或者使用以下脚本自动获取并设置：
# 获取 WSL IP 并设置端口转发
$wslIp = wsl hostname -I
netsh interface portproxy delete v4tov4 listenport=18789 listenaddress=0.0.0.0
netsh interface portproxy add v4tov4 listenport=18789 listenaddress=0.0.0.0 connectport=18789 connectaddress=$wslIp
注意：每次重启 WSL 后，IP 地址可能会发生变化，需要重新配置端口转发。
三、WSL环境下安装OpenClaw
3.1 基础环境配置（免密设置）
为了在后续安装脚本运行中避免输入密码，建议为当前用户开启sudo免密权限：
sudo visudo
在文件补充添加以下内容（将spoto替换为你的实际用户名）：
spoto ALL=(ALL) NOPASSWD: ALL
保存并退出（Ctrl+O → Enter → Ctrl+X）。
3.2 安装基础工具
sudo apt install -y curl wget git
3.3 安装Opencode工具
Opencode用于简化后续的复杂配置过程：
3.3 安装Opencode工具
Opencode用于简化后续的复杂配置过程：
验证安装：
which opencode
opencode –version
3.4 安装 OpenClaw 官方脚本
使用官方提供的一键安装脚本进行配置：
curl -fsSL https://molt.bot/install.sh | bash
3.5 运行初始化示例
安装完成后，运行初始化完成基本配置：
openclaw onboard –install-daemon
按提示完成配置：
选择安全选项（理解风险）
配置工作区目录
设置网关认证方式
其他基本配置
3.6 验证安装
which openclaw
openclaw –version
openclaw gateway status
四、国内API配置
本章节帮助已安装OpenClaw的用户快速将LLM API替换为国内版本，支持MiniMax和智谱（GLM）两个主流国内API。
4.1 前置条件检查
检查OpenClaw是否已安装：
which openclaw
ps aux | grep openclaw
openclaw –version
4.2 获取API Key
根据您要使用的API服务，前往对应平台获取API Key：
服务商 控制台地址 API Key 获取位置
迷你麦克斯 https://www.minimaxi.com 控制台 → API 密钥
智谱AI https://bigmodel.cn 控制台 → API 密钥
4.3 备份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup
4.4 MiniMax国内版配置
MiniMax国内版API配置适用于中国区域用户，提供M2.1等高质量模型。
API端点：https://api.minimaxi.com/anthropic
完整配置示例：
{
“models”: {
“mode”: “merge”,
“providers”: {
“minimax-cn”: {
“baseUrl”: “https://api.minimaxi.com/anthropic”,
“apiKey”: “YOUR_MINIMAX_API_KEY_HERE”,
“api”: “anthropic-messages”,
“models”: [
{
“id”: “MiniMax-M2.1”,
“name”: “MiniMax M2.1 (China)”,
“reasoning”: true,
“input”: [“text”],
“contextWindow”: 204800,
“maxTokens”: 131072
}
]
}
}
}
}
4.5 智谱（GLM）配置
API端点：https://open.bigmodel.cn/api/coding/paas/v4
完整配置示例：
{
“models”: {
“mode”: “merge”,
“providers”: {
“zhipu-cn”: {
“baseUrl”: “https://open.bigmodel.cn/api/coding/paas/v4”,
“apiKey”: “YOUR_ZHIPU_API_KEY_HERE”,
“api”: “anthropic-messages”,
“models”: [
{
“id”: “glm-4.7”,
“name”: “GLM-4.7 (China)”,
“reasoning”: true,
“input”: [“text”],
“contextWindow”: 200000,
“maxTokens”: 8192
}
]
}
}
}
}
4.6 重启与验证
配置修改后，需要重启网关使配置生效：
openclaw gateway restart
验证模型列表：
openclaw models list
五、周边访问配置
本章节帮助用户配置 OpenClaw Web UI，设置可以通过消防访问。
5.1 获取本机边界IP
ip addr show | grep -E “inet ” | awk ‘{print $2}’ | cut -d’/’ -f1 | grep -v “^127”
5.2 编辑配置文件
nano ~/.openclaw/openclaw.json
5.3 修改网关配置
将bind值loopback改为lan，并添加controlUi配置：
{
“gateway”: {
“port”: 18789,
“mode”: “local”,
“bind”: “lan”,
“auth”: {
“mode”: “token”,
“token”: “your_token_here”
},
“controlUi”: {
“allowInsecureAuth”: true
}
}
}
5.4 重启网关
openclaw gateway restart
openclaw gateway status
5.5 访问Web界面
根据您的交换机IP，访问地址为：http://<你的局域网IP>:18789/
六、常见问题
Q1：网关启动失败
解决方案：
cat ~/.openclaw/openclaw.json | jq
tail -f ~/.openclaw/logs/gateway.log
cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json
openclaw gateway restart
Q2: 园区无法访问
解决方案：
sudo ufw status
sudo ufw allow 18789/tcp
openclaw gateway status
grep ‘”bind”‘ ~/.openclaw/openclaw.json
Q3：模型未在列表中显示
解决方案：
检查 JSON 语法是否正确
确认提供者名称与模型引用一致
确认API密钥有效且有访问权限
重启网关：openclaw gateway restart
Q4：认证失败（HTTP 401）
解决方案：
验证API密钥格式是否正确
确认API密钥未过期
检查API key是否有访问所用API的权限
Q5：镜像模式不生效
解决方案：
确认已执行wsl –shutdown并等待8秒后重新启动
检查.wslconfig文件路径是否正确
确认 WSL 版本为 2.0 以上
更新WSL内核：wsl –update
Q6：防火墙规则创建失败
问题表现：运行New-NetFirewallHyperVRule或Set-NetFirewallHyperVVMSetting时报错。
解决方案：
确认以管理员身份运行PowerShell
检查Hyper-V服务是否正在运行
VMCreatorId 错误：如果使用 Hyper-V 防火墙命令报错，可能是因为硬编码的 GUID 不存在于当前系统。请改用标准防火墙：
# 推荐：使用标准防火墙命令（适用于 WSL2）
New-NetFirewallRule -DisplayName “OpenClaw-Service” -Direction Inbound -Action Allow -Protocol TCP -LocalPort 18789
动态获取VMCreatorId（仅当需要使用Hyper-V防火墙时）：
# 获取系统所有 VM 创建者
Get-NetFirewallHyperVVMCreator# 使用动态获取的 GUID 配置
Get-NetFirewallHyperVVMCreator | ForEach-Object {
Set-NetFirewallHyperVVMSetting -Name $_.Name -DefaultInboundAction Allow
}
相关文章
