国内Windows用户部署 OpenClaw 的真实记录：模型选错、镜像没配、代理踩坑，全都经历了

AiInsideView
3 阅读14分钟

引言

为什么写这篇指南

我最近在折腾 AI 编程助手，OpenClaw 是其中让我花时间最多的一个——不是因为它不好，而是从安装到真正跑起来，坑踩得不少。Windows 上没有原生支持，得借助 WSL；国内网络环境又有各种阻碍；加上大模型的选择直接影响体验好坏。折腾完之后觉得值得整理成文章，希望能帮后来人少走弯路。

我的踩坑历程

先说模型选择上的弯路。

近一个月里，我前后在闲鱼上买过智谱、MiniMax 的共享 API Key，试过智谱 GLM4.7、GLM5.0、Deepseek 3.2、MiniMax2.5，以及阿里 Qwen3-max。这些模型在当时的 OpenClaw 上的体验有一个共同问题：任务跑着跑着就中断，频繁回来询问我的意见，无法持续自主地把任务完成。直到换成 qwen3.5-plus，交代的任务才基本能直接跑完，这可能和它上下文窗口扩展到 1M 有关。

这件事让我意识到：Agent 的能力和底层大模型的能力强相关。想要好的体验，就要舍得用当前最强的生产力模型。当然，也可以慢慢等国产模型能力追上来。

下图是最开始的使用截图：

2026-03-04-23-11-39-1ac27c57d4c0b6c40e96b4f19cc3803e.jpg

最近的使用截图：

2026-03-04-23-12-09-d6a18a20750532c258637461cfe07eae.jpg

再说安装过程里的坑。

OpenClaw 安装本身不复杂，但在国内环境下有几个地方容易卡住：

  • 海外依赖下载慢：安装过程中会拉取不少海外资源，不配置国内镜像源的话速度极慢甚至超时。APT 源、npm、pip 都需要单独换源。

  • 网络代理要和宿主机同步：WSL 默认的 NAT 网络模式下，代理配置和 Windows 主机是隔离的。需要把 WSL 切换成镜像网络模式，才能让 WSL 内部自动复用 Windows 的代理设置，省去大量排查网络问题的麻烦。

  • 浏览器控制功能需要额外配置：OpenClaw 支持通过 Chrome 扩展控制浏览器，这是一个很实用的功能，但配置步骤容易被忽略，需要单独安装扩展并配置 Relay 端口。

  • Brave Search 注册会扣 1 美元：给 OpenClaw 开启网页搜索能力需要注册 Brave Search API，注册时会从海外信用卡扣 1 美元用于账号验证，几天后会退回。没有海外信用卡的话这一步会卡住，要提前做好准备。

部署环境选型

在开始之前，有必要先说清楚为什么选择 WSL，而不是其他系统或方案。

OpenClaw 本质上是一个运行在命令行环境下的 AI Agent，对操作系统的依赖主要体现在两点：命令行能力和文件系统的可访问性。

macOS — 最优选择

macOS 基于 Unix，天生具备完整的命令行环境，bash/zsh、curl、git 等工具开箱即用，同时拥有成熟的 GUI 生态（Homebrew、各类原生应用），开发体验和日常使用可以无缝共存。

如果你用 Mac，直接跳过本文，按官方文档安装即可，几乎不会遇到环境问题。

Linux — 命令行原生，但桌面生态薄弱

Linux 的命令行能力毋庸置疑，OpenClaw 在 Linux 上运行最为顺畅。但对于大多数普通用户来说，Linux 桌面生态相对薄弱，日常办公软件、国内应用的支持有限，很难作为主力工作系统使用。

Windows — 用 WSL 弥补命令行劣势

Windows 是国内用户占比最高的系统，但它对命令行的支持历来是短板。PowerShell 能处理基础任务，但面对 OpenClaw 这类依赖 Unix 工具链的应用时力不从心。

在 Windows 上运行 Linux 环境主要有两条路：

方案说明劣势
虚拟机（VMware / VirtualBox）运行完整的 Linux 系统资源占用高，文件互通繁琐，体验割裂
WSL（Windows Subsystem for Linux）微软官方 Linux 子系统极少数场景下兼容性略有限制

WSL 是更好的选择，原因在于它打破了 Windows 和 Linux 之间的壁垒：

  • 文件系统双向互通：WSL 可以直接挂载并访问 Windows 的任意目录（路径格式为 /mnt/c/...），Windows 也可以直接访问 WSL 的文件系统。无需复制、无需共享文件夹，两侧文件操作无缝衔接。

2026-03-04-23-13-40-image.png

  • 网络共享：配置镜像网络模式后，WSL 与 Windows 共享同一个网络栈，代理、端口、局域网访问全部打通，不存在虚拟机的网络隔离问题。
  • 性能接近原生：WSL 2 运行完整的 Linux 内核，性能远优于虚拟机。
  • 与 Windows 生态共存：你可以继续使用熟悉的 Windows 应用、输入法、浏览器，同时在 WSL 里运行 Linux 工具链。

综合来看，WSL + Windows 的组合体验接近 macOS：既有完整的 Unix 命令行环境，又保留了 Windows 丰富的桌面生态，两套系统的文件和网络融为一体。这也是本文选择 WSL 方案的核心原因。

本文的所有内容均基于 Windows 11 + WSL 2 + Ubuntu 环境编写。Windows 10 用户需确保系统版本支持 WSL 2（Build 19041 及以上）。

这篇指南能帮你做什么

从零开始，在 Windows 11 的 WSL 环境中完整安装并运行 OpenClaw，并接入国内大模型 API。每个容易踩坑的环节都有详细说明，零基础新手也可以跟着一步步完成。

目录

一、快速开始

本章节面向有经验的用户，Windows 系统中已有 WSL 环境的，提供快速安装指引。零基础新手请跳转到第二章。

1. 安装 WSL（PowerShell 管理员）

wsl --install

2. 重启后，创建配置文件 C:\Users\<用户名>\.wslconfig

[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true
firewall=true

[experimental]
autoMemoryReclaim=gradual
hostAddressLoopback=true

3. 应用配置

wsl --shutdown

4. 进入 WSL，配置国内镜像源后安装 OpenClaw（镜像源配置参考第四章）

curl -fsSL https://molt.bot/install.sh | bash

5. 运行初始化向导

openclaw onboard --install-daemon

6. 配置国内 API

安装完 OpenClaw 后，推荐使用 Claude Code 自动完成 API Key 写入，参考第六章。

7. 重启服务

openclaw gateway restart

二、前置知识

2.1 核心概念简介

WSL（Windows Subsystem for Linux）

  • 微软官方提供的 Windows 子系统，可在 Windows 上原生运行 Linux 环境
  • 无需虚拟机，性能优异，与 Windows 文件系统无缝集成

OpenClaw

  • 本地 AI 编程助手，支持多种大语言模型（LLM）
  • 提供 MCP（Model Context Protocol）插件协议，可扩展各种功能
  • 支持国内 API（MiniMax、智谱 GLM 等）

MCP（Model Context Protocol）

  • AI 插件协议，允许 LLM 调用外部工具和服务
  • 社区有丰富的 MCP 服务器（浏览器、数据库、文件系统等）

2.2 系统要求

要求项最低配置推荐配置
操作系统Windows 11 22H2+Windows 11 最新版
内存8GB RAM16GB+ RAM
存储10GB 可用空间30GB+ SSD
网络稳定网络连接配置代理更佳

三、WSL 安装与网络配置

3.1 安装 WSL

WSL（适用于 Linux 的 Windows 子系统）目前有两个主要版本：

版本说明推荐度
WSL 1早期版本，采用系统调用转换层⭐⭐
WSL 2运行完整的 Linux 内核，性能更佳⭐⭐⭐⭐⭐

强烈建议使用 WSL 2。

一键安装 WSL

在具有管理员权限的 PowerShell 或 Windows 终端中，执行以下命令：

wsl --install

此命令将自动执行：

  1. 启用虚拟机平台（Virtual Machine Platform）
  2. 启用适用于 Linux 的 Windows 子系统
  3. 下载并安装最新的 Linux 内核
  4. 默认下载并安装 Ubuntu 发行版

安装完成后，必须重启计算机以使 Hyper-V 管理程序生效。

验证安装状态

重启后，通过以下命令验证：

wsl --status
wsl --version

预期输出示例：

WSL 版本: 2.0.xxxx.0
内核版本: 5.15.xxxx
Windows 版本: 10.0.22631.xxxx

现有 WSL 用户更新

如果系统中已存在旧版 WSL，建议运行以下命令更新：

wsl --update

3.2 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: yourname
New password:
Retype new password:

此账户拥有 sudo 权限，是后续执行安装操作的核心身份。

3.3 WSL 网络模式配置

WSL 2 有两种网络模式，选择正确的模式对后续使用至关重要。

NAT 模式 vs 镜像模式

维度NAT 模式 (默认)镜像模式 (推荐)
IP 地址独立虚拟 IP (172.x.x.x)与宿主机共享相同局域网 IP
IPv6 支持极其有限全面原生支持
VPN 兼容性经常导致 DNS 丢包显著提升兼容性
局域网可见性需要手动端口转发局域网内其他设备可直接发现
防火墙控制独立规则直接使用 Windows 防火墙

推荐使用镜像模式。

配置镜像网络模式

步骤 1：打开文件资源管理器，导航到以下路径：

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 地址段。

3.4 防火墙配置

在镜像模式下，WSL2 应用将直接暴露在 Windows 防火墙规则中。

创建防火墙规则

以管理员身份打开 PowerShell，执行以下命令：

# 创建入站防火墙规则，允许 OpenClaw 服务端口
New-NetFirewallRule -DisplayName "OpenClaw-Service" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 18789

# 验证规则是否创建成功
Get-NetFirewallRule -DisplayName "OpenClaw-Service" | Format-Table

测试端口连通性

# 测试本地端口
Test-NetConnection -ComputerName localhost -Port 18789

四、国内镜像源配置

在国内使用 WSL 安装 OpenClaw 及相关依赖时，配置国内镜像源可以显著加速下载。

4.1 Ubuntu APT 源

备份原配置

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

配置清华镜像源

Ubuntu 24.04 (Noble)：

sudo tee /etc/apt/sources.list << 'EOF'
# 清华大学镜像源 - Ubuntu 24.04 (noble)
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-backports main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ noble-security main restricted universe multiverse
EOF

Ubuntu 22.04 (Jammy)：

sudo tee /etc/apt/sources.list << 'EOF'
# 清华大学镜像源 - Ubuntu 22.04 (jammy)
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
EOF

更新软件包索引

sudo apt update && sudo apt upgrade -y

其他可选镜像源

镜像源地址
清华大学https://mirrors.tuna.tsinghua.edu.cn/ubuntu/
阿里云https://mirrors.aliyun.com/ubuntu/
中科大https://mirrors.ustc.edu.cn/ubuntu/
华为云https://repo.huaweicloud.com/ubuntu/

4.2 npm 镜像源

# 设置淘宝镜像（npmmirror.com）
npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry

4.3 pip 镜像源

# 创建配置目录
mkdir -p ~/.pip

# 写入配置文件
cat > ~/.pip/pip.conf << 'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

4.4 一键配置脚本

将以下脚本保存为 setup-mirrors.sh，一键配置所有常用镜像：

#!/bin/bash
# WSL 国内镜像源一键配置脚本

echo "=== 配置 APT 源（清华镜像）==="
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak 2>/dev/null
CODENAME=$(lsb_release -cs)
sudo tee /etc/apt/sources.list << EOF
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ $CODENAME main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ $CODENAME-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ $CODENAME-backports main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ $CODENAME-security main restricted universe multiverse
EOF
sudo apt update

echo "=== 配置 npm 源（淘宝镜像）==="
npm config set registry https://registry.npmmirror.com

echo "=== 配置 pip 源（清华镜像）==="
mkdir -p ~/.pip
cat > ~/.pip/pip.conf << 'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

echo "=== 配置完成！==="

运行脚本：

chmod +x setup-mirrors.sh
./setup-mirrors.sh

五、OpenClaw 安装

5.1 基础环境配置

安装基础工具

sudo apt install -y curl wget git

配置 sudo 免密（可选）

为了避免在后续安装脚本运行中频繁输入密码，可以为当前用户开启 sudo 免密权限：

sudo visudo

在文件末尾添加以下内容（将 your_username 替换为你的实际用户名）：

your_username ALL=(ALL) NOPASSWD: ALL

保存并退出（Ctrl+O → Enter → Ctrl+X）。

5.2 安装 OpenClaw

使用官方提供的一键安装脚本进行部署：

curl -fsSL https://molt.bot/install.sh | bash

5.3 运行初始化向导

安装完成后，运行初始化向导完成基本配置：

openclaw onboard --install-daemon

安装结束后会自动出现提示信息，请根据提示信息完成 OpenClaw 配置，参考配置如下：

配置项配置内容
I understand this is powerful and inherently risky. Continue?选择 "Yes"
Onboarding mode选择 "QuickStart"
Model/auth provider选择 "Skip for now"，后续可以配置
Filter models by provider选择 "All providers"
Default model使用默认配置
Select channel (QuickStart)选择 "Skip for now"，后续可以配置
Configure skills now? (recommended)选择 "No"，后续可以配置
Enable hooks?按空格键选中选项，按回车键进入下一步
How do you want to hatch your bot?选择 "Hatch in TUI"

5.4 验证安装

# 检查 OpenClaw 版本
openclaw --version

# 检查 Gateway 状态
openclaw gateway status

六、配置国内大模型 API

完成 OpenClaw 安装后，需要将 ~/.openclaw/openclaw.json 中的 LLM 配置设置为国内大模型 API。以下提供两种方式供选择。

6.1 阿里百炼 Code Plan

国内用户在选择大模型服务商时，可以试试 阿里百炼 Code Plan（Lite 版）。理由如下：

  • 价格低廉：首个月仅需 7.5 元，第二个月也只要 20 元（原价 40 元），适合个人开发者低成本上手。
  • 一站式多模型访问：订阅后不仅能使用阿里自家模型，还能直接调用阿里平台部署的智谱、MiniMax 等最新公开模型，无需逐一前往各厂商官网注册和订阅，节省时间和管理成本。
  • 开箱即用：API 格式兼容主流标准，接入 OpenClaw 配置简单。

🔗 订阅 Code Plan

📖 阿里百炼 Code Plan 配置 OpenClaw 官方文档

完成订阅后，可参考上方官方文档获取 API Key 并完成 OpenClaw 对接（阿里网站页面较复杂，API Key 的位置可参考上篇文章《国内安装 Claude Code 并切换使用国内大模型 API：完整指南》），也可继续按照 6.2 节使用 Claude Code 自动完成配置。

6.2 使用 Claude Code 配置国内 API

手动编辑 JSON 配置文件容易出错，可以使用 Claude Code 来完成这一步——它能自动定位配置文件、写入正确的字段格式，并运行测试请求验证配置是否生效。

6.2.1 前置：安装并配置 Claude Code

如果你还没有安装 Claude Code，请参考配套文章：

《国内安装 Claude Code 并切换使用国内大模型 API：完整指南》

该文章涵盖：

  • Claude Code 的安装方式（原生客户端，无需 Node.js）
  • 如何获取 DeepSeek、阿里百炼、智谱 GLM 等国内 API Key
  • 如何配置 ~/.claude/settings.json 让 Claude Code 使用国内 API

💡 Claude Code 本身也需要一个大模型 API 才能运行，同样可以使用国产大模型 API，上篇文章有详细介绍，这里不赘述。

6.2.2 用 Claude Code 配置 OpenClaw API

Claude Code 安装并连接好国内 API 之后，进入你的工作目录，启动 Claude Code：

cd ~
claude

然后直接用自然语言描述你想要的配置，例如：

配置 MiniMax：

帮我配置 OpenClaw 使用 MiniMax 国内 API。
配置文件在 ~/.openclaw/openclaw.json，
我的 API Key 是 <你的 MiniMax API Key>。
配置好之后重启 Gateway 并验证模型列表是否正常。

配置智谱 GLM：

帮我配置 OpenClaw 使用智谱 GLM API。
配置文件在 ~/.openclaw/openclaw.json，
我的 API Key 是 <你的智谱 API Key>。
配置好之后重启 Gateway 并验证模型列表是否正常。

Claude Code 会自动完成以下步骤：

  1. 读取 ~/.openclaw/openclaw.json 当前内容
  2. 备份配置文件（生成 .backup）
  3. 写入正确的 provider 配置块（baseUrl、apiKey、model 列表等）
  4. 执行 openclaw gateway restart
  5. 执行 openclaw models list 验证模型是否出现

6.2.3 配置文件参考格式

如果你需要了解配置文件的字段结构，以下是两个服务商的参考格式，不需要手动复制粘贴，让 Claude Code 来写即可：

MiniMax 参考：

{
  "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.5",
            "name": "MiniMax M2.5 (China)",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 204800,
            "maxTokens": 131072
          }
        ]
      }
    }
  }
}

智谱 GLM 参考：

{
  "models": {
    "mode": "merge",
    "providers": {
      "zhipu-cn": {
        "baseUrl": "https://open.bigmodel.cn/api/anthropic",
        "apiKey": "YOUR_ZHIPU_API_KEY_HERE",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "glm-4",
            "name": "GLM-4 (China)",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

6.2.4 手动备份配置

无论是否使用 Claude Code，修改配置前请先手动备份：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

配置出错时可通过以下命令恢复：

cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json
openclaw gateway restart

七、服务管理与访问

7.1 Gateway 命令大全

命令说明
openclaw gateway status检查 Gateway 状态
openclaw gateway install安装 Gateway 为系统服务
openclaw gateway start启动 Gateway 服务
openclaw gateway stop停止 Gateway 服务
openclaw gateway restart重启 Gateway 服务
openclaw gateway uninstall卸载 Gateway 服务
openclaw logs --follow实时查看日志

前台运行模式（调试用）

# 基础前台运行
openclaw gateway --port 18789

# 详细日志模式
openclaw gateway --port 18789 --verbose

# 强制启动（忽略 TS 编译警告）
openclaw gateway --force

状态检查选项

# 深度扫描（包括系统服务）
openclaw gateway status --deep

# 跳过 RPC 探测（网络故障时有用）
openclaw gateway status --no-probe

# JSON 输出（适合脚本）
openclaw gateway status --json

7.2 systemd 服务配置

WSL 环境下，OpenClaw Gateway 作为 systemd 用户服务运行。

启用服务自启动

# 启用 lingering（必须，使服务在登出后继续运行）
sudo loginctl enable-linger $USER

# 启用并启动服务
systemctl --user enable --now openclaw-gateway.service

# 查看服务状态
systemctl --user status openclaw-gateway

# 查看服务日志
journalctl --user -u openclaw-gateway -f

启用 WSL systemd

编辑 /etc/wsl.conf：

sudo nano /etc/wsl.conf

添加或确认以下内容：

[boot]
systemd=true

重启 WSL：

wsl --shutdown

7.3 Control UI 访问

本地访问

# 打开 Dashboard
openclaw dashboard

# 或直接访问
# http://127.0.0.1:18789/

局域网访问配置

编辑 ~/.openclaw/openclaw.json：

nano ~/.openclaw/openclaw.json

修改 Gateway 配置：

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your_token_here"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

获取本机局域网 IP：

ip addr show | grep -E "inet " | awk '{print $2}' | cut -d'/' -f1 | grep -v "^127"

访问地址：http://<局域网IP>:18789/

八、高级配置

8.1 浏览器控制配置

OpenClaw 的 Browser 技能让 AI 可以直接操控浏览器——打开网页、点击元素、填写表单、读取内容。在 WSL 环境下有多种实现方式，先看整体对比再选择适合自己的方案。

五种方式对比

方法登录持久JS 渲染推荐度适用场景
Windows Chrome + CDP✅ 复用现有会话✅⭐⭐⭐⭐⭐日常使用首选
WSL Chrome + WSLg✅ 独立持久✅⭐⭐⭐⭐纯 WSL 工作流
Playwright 独立浏览器⚠️ 每次新会话✅⭐⭐⭐自动化爬虫
OpenClaw Browser 工具⚠️ 临时✅⭐⭐⭐简单任务
curl / HTTP 请求⚠️ 手动❌⭐⭐纯接口调用

对于大多数用户，方案一（Windows Chrome + CDP）是最佳选择，可以直接复用已登录的 Chrome 会话，不需要重新登录各网站。有纯 WSL 工作流需求的用户可以选择方案二。

方案一：Windows Chrome + CDP（推荐）

思路： 不在 WSL 里跑浏览器，而是让 Windows 侧的 Chrome 开放调试端口，WSL 里的 OpenClaw 通过 Chrome DevTools Protocol（CDP）远程连接控制。

架构：

┌─────────────────────────────────────────┐
│  Windows                                │
│  ┌──────────────────────────────────┐   │
│  │  Chrome (--remote-debugging-port) │   │
│  │  监听 127.0.0.1:9222             │   │
│  └──────────┬───────────────────────┘   │
│             │ CDP (WebSocket)            │
│  ┌──────────▼───────────────────────┐   │
│  │  WSL (Ubuntu)                    │   │
│  │  OpenClaw Gateway                │   │
│  │  → cdpUrl: http://127.0.0.1:9222 │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘

启动方式：

在 Windows 终端（非 WSL）中执行：

# 方式一：PowerShell 直接启动
Start-Process "chrome.exe" "--remote-debugging-port=9222 --user-data-dir=C:\chrome-openclaw"

# 方式二：通过 WSL 调用 Windows Chrome
/mnt/c/Windows/System32/cmd.exe /c "start chrome.exe --remote-debugging-port=9222 --user-data-dir=C:\chrome-openclaw"

⚠️ 关键踩坑：Chrome 调试端口不生效

Chrome 有一个隐蔽的行为：如果系统中已有 Chrome 进程在运行，新启动的 Chrome 窗口会加入已有进程，--remote-debugging-port 参数被静默忽略，调试端口根本不会开放。

很多人会反复尝试命令、检查端口，却始终连不上，原因就在这里。

解决方法：

# 步骤 1：先彻底关闭所有 Chrome 进程（包括后台）
taskkill /F /IM chrome.exe

# 步骤 2：等待 2 秒确认进程退出
Start-Sleep -Seconds 2

# 步骤 3：再带参数启动，用独立 user-data-dir 隔离配置
Start-Process "chrome.exe" "--remote-debugging-port=9222 --user-data-dir=C:\chrome-openclaw"

💡 使用独立的 --user-data-dir 有两个好处：一是彻底避免与现有 Chrome 进程合并；二是给 OpenClaw 维护一个独立的登录会话，不影响日常使用的 Chrome。

验证端口是否开放：

# 在 Windows PowerShell 中检查
Test-NetConnection -ComputerName localhost -Port 9222

或在 WSL 中：

curl http://127.0.0.1:9222/json/version

返回 JSON 内容说明连接成功。

配置 OpenClaw 连接：

编辑 ~/.openclaw/openclaw.json：

{
  "tools": {
    "browser": {
      "enabled": true,
      "attachOnly": true,
      "cdpUrl": "http://127.0.0.1:9222"
    }
  }
}

方案二：WSL Chrome + WSLg

思路： 在 WSL 内安装 Linux 版 Chrome，借助 WSLg 将窗口显示在 Windows 桌面上。适合不想依赖 Windows Chrome、需要纯 WSL 工作流的用户。

优点缺点
✅ 原生 Linux 应用，与 WSL 完全集成⚠️ 需要 WSLg 支持（Windows 11 或 Win10 最新版）
✅ 无需跨系统互操作⚠️ 中文输入法可能有问题
✅ 支持 CDP 远程调试⚠️ 登录会话与 Windows Chrome 独立，需重新登录

安装 Chrome：

cd /tmp
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt-get install -f -y

# 验证
google-chrome --version

启动（附带代理和调试端口）：

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=~/.chrome-wsl \
  --proxy-server="http://127.0.0.1:7890" &

浏览器窗口不显示的解决方法：

# 在 Windows PowerShell 中更新 WSL
wsl --update
wsl --shutdown

重启 WSL 后再尝试。

配置代理（永久生效，推荐）：

创建 wrapper 脚本，省去每次手动加参数：

mkdir -p ~/bin
cat > ~/bin/google-chrome << 'EOF'
#!/bin/bash
/usr/bin/google-chrome \
  --proxy-server="http://127.0.0.1:7890" \
  --remote-debugging-port=9222 \
  --user-data-dir=~/.chrome-wsl \
  "$@"
EOF
chmod +x ~/bin/google-chrome

# 确保 ~/bin 优先于系统路径
grep -q 'export PATH="$HOME/bin:$PATH"' ~/.bashrc \
  || echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

方案三：Playwright 独立浏览器

OpenClaw 通过 Playwright 启动一个独立的 Chromium 实例，每次任务结束后会话即销毁。适合不需要登录状态的自动化爬虫场景，不适合需要持久登录的日常任务。

方案四：OpenClaw Browser 工具（内置）

OpenClaw 自带的浏览器控制工具，无需额外配置。功能相对基础，适合简单的网页读取任务。开启方式见 8.2 节 Skills 配置。

方案五：curl / HTTP 请求

直接发送 HTTP 请求，轻量快速，但无法执行 JavaScript，仅适合纯接口调用或静态页面抓取。

OpenClaw Chrome 扩展安装（方案一 / 二通用）

OpenClaw 提供了 Chrome 浏览器扩展（Browser Relay），用于将 OpenClaw 连接到现有的 Chrome 标签页，实现浏览器自动化控制。

步骤 1：安装扩展文件

# 安装扩展到本地目录
openclaw browser extension install

# 查看扩展安装路径
openclaw browser extension path

扩展默认安装在：~/.openclaw/browser/chrome-extension

步骤 2：在 Chrome 中加载扩展

  1. 打开 Chrome 浏览器，访问 chrome://extensions/
  2. 开启右上角的**"开发者模式"**
  3. 点击**"加载已解压的扩展程序"**
  4. 导航到扩展目录并选择

⚠️ 常见问题：找不到 .openclaw 目录

在 WSL 中运行的 Chrome 文件选择器默认不显示隐藏目录（以 . 开头的目录）。

解决方案：

  • 方法 1（推荐）：在文件选择器对话框中按 Ctrl + H 切换显示隐藏文件，然后导航到 /home/<用户名>/.openclaw/browser/chrome-extension

  • 方法 2：创建软链接到非隐藏目录

    ln -s ~/.openclaw/browser/chrome-extension ~/openclaw-chrome-extension

    然后在文件选择器中选择 /home/<用户名>/openclaw-chrome-extension

也可以直接在 Windows 文件浏览器地址栏输入 \\wsl$\Ubuntu\home\<用户名> 来访问 WSL 文件系统，直接定位到扩展目录。

步骤 3：配置扩展

扩展加载成功后，需要配置 Gateway Token：

  1. 右键点击扩展图标 → 选择**"选项"**
  2. 填入以下配置：
    • Port：18792（默认值）
    • Gateway token：你的 Gateway 认证 Token

获取 Gateway Token：

# 方法 1：通过命令获取（会显示为 REDACTED）
openclaw config get gateway.auth.token

# 方法 2：直接从配置文件读取
grep -A2 '"auth"' ~/.openclaw/openclaw.json | grep token

配置成功后，扩展选项页面会显示：

Relay reachable and authenticated at http://127.0.0.1:18792/

步骤 4：使用扩展

  1. 将扩展固定到 Chrome 工具栏（点击拼图图标 → 点击 OpenClaw 旁边的 📌）
  2. 打开要控制的网页
  3. 点击工具栏上的 OpenClaw 扩展图标进行 attach/detach

Browser Service 配置

编辑 ~/.openclaw/openclaw.json：

{
  "tools": {
    "browser": {
      "enabled": true,
      "headless": false,
      "profiles": 2
    }
  }
}

8.2 Skills 启用

Skills - OpenClaw 的扩展功能模块。

编辑 ~/.openclaw/openclaw.json：

{
  "skills": {
    "allowBundled": [
      "mcporter",
      "browser",
      "web-search"
    ]
  }
}

mcporter 配置

mcporter - MCP 配置共享工具，可复用 Cursor/Claude Desktop 的 MCP 配置。

安装 mcporter：

sudo npm install -g mcporter

启用后，OpenClaw 可以自动检测并使用以下配置文件：

  • ~/.cursor/mcp.json - Cursor 的 MCP 配置
  • ~/.claude/mcp.json - Claude Desktop 的 MCP 配置

8.3 Telegram 渠道配置

Telegram - 通过 Telegram Bot 与 OpenClaw 进行对话的渠道。

创建 Telegram Bot

  1. 在 Telegram 中搜索 @BotFather 并发送 /newbot
  2. 按提示设置 Bot 名称和用户名
  3. 保存返回的 Bot Token（格式如：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

配置 Telegram 渠道

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN"
    }
  }
}

⚠️ 常见问题：Telegram API 连接失败

问题表现：openclaw status --deep 显示 Telegram 状态异常，或 Bot 无法收发消息。

原因分析：

  • Telegram API (api.telegram.org) 在国内无法直接访问
  • Node.js 的 fetch() 不会自动使用系统代理环境变量

解决方案：在 Telegram 配置中显式指定代理：

# 使用命令行配置代理
openclaw config set channels.telegram.proxy "http://127.0.0.1:7890"

或手动编辑配置文件：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN",
      "proxy": "http://127.0.0.1:7890"
    }
  }
}

配置完成后重启 Gateway：

openclaw gateway restart

# 验证 Telegram 连接状态
openclaw status --deep

成功后应显示：

Telegram: OK

8.4 Brave Search 配置

Brave Search - 网页搜索技能，让 OpenClaw 具备搜索能力和读取网页内容的能力。

获取 API Key：brave.com/search/api/

免费计划每个用户每月有 2000 次免费搜索，前提是要绑定海外信用卡，注册时会扣费 1 美元用于验证，几天后会自动退回。

方法一：使用配置命令

openclaw configure --section web

方法二：手动编辑配置

编辑 ~/.openclaw/openclaw.json：

{
  "tools": {
    "web": {
      "search": {
        "apiKey": "your_brave_api_key"
      }
    }
  }
}

8.5 环境变量

变量说明
OPENCLAW_HOME设置 Home 目录
OPENCLAW_STATE_DIR覆盖状态目录
OPENCLAW_CONFIG_PATH覆盖配置文件路径
OPENCLAW_GATEWAY_TOKENGateway 认证 Token

8.6 TUI 终端界面

# 启动终端用户界面
openclaw tui

# 退出 TUI
/exit

九、使用踩坑技巧

⚠️ 重要：AI 修改配置文件前先备份

问题描述：

让 OpenClaw 的 AI 助手修改 openclaw.json 配置文件时，可能会因为配置错误导致 OpenClaw 无法启动。

最佳实践：

在 AGENTS.md 或 SOUL.md 中添加以下规则，让 AI 每次修改配置文件前自动备份：

## 📁 文件修改规则

修改 `~/.openclaw/openclaw.json` 或其他关键配置文件前：

1. **必须先备份当前配置**
   ```bash
   cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup_$(date +%Y%m%d_%H%M%S)

  1. 修改后验证配置

    openclaw status

  2. 如果改挂了，快速恢复

    # 停止 Gateway
openclaw gateway stop

# 恢复备份
cp ~/.openclaw/openclaw.json.backup_* ~/.openclaw/openclaw.json

# 重启 Gateway
openclaw gateway start

备用方式：通过 Windows 文件浏览器直接操作

如果命令行恢复不方便，也可以直接在 Windows 文件浏览器地址栏输入以下路径，找到对应文件手动改名恢复：

\\wsl$\Ubuntu\home\<用户名>\.openclaw\

这是 WSL 文件系统双向互通的优势之一，GUI 操作比命令行更直观。

2026-03-04-23-28-17-image.png

十、常见问题 FAQ

Q1: Gateway 启动失败

解决方案：

# 检查配置文件语法
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

# 检查 Gateway 状态
openclaw gateway status

# 检查 bind 配置
grep '"bind"' ~/.openclaw/openclaw.json

Q3: 模型未显示在列表中

解决方案：

  1. 检查 JSON 语法是否正确
  2. 确认 provider 名称与模型引用一致
  3. 确认 API key 有效且有访问权限
  4. 重启 Gateway：openclaw gateway restart

Q4: 镜像模式不生效

解决方案：

  1. 确认已执行 wsl --shutdown 并等待 8 秒后重新启动
  2. 检查 .wslconfig 文件路径是否正确（C:\Users\<用户名>\.wslconfig）
  3. 确认 WSL 版本为 2.0 以上
  4. 更新 WSL 内核：wsl --update

Q5: .bashrc 语法错误导致 Shell 无法启动

问题表现：

-bash: /home/user/.bashrc: line 163: syntax error near unexpected token `('

原因分析：

  • Windows 的 PATH 环境变量会被 WSL 继承
  • Windows PATH 中包含带括号的路径，如 C:\Program Files (x86)\...
  • 如果 .bashrc 中的 export PATH=... 语句没有使用双引号，bash 会将括号解释为子 shell 语法

解决方案：

步骤 1：使用 --norc 参数启动 bash（绕过 .bashrc）：

wsl -d Ubuntu -u your_username -e bash --norc

步骤 2：修复 .bashrc 文件：

# 查看问题行
sed -n '160,170p' ~/.bashrc

# 备份原文件
cp ~/.bashrc ~/.bashrc.backup

# 删除损坏的 PATH 行（根据实际行号调整）
sed -i '163d' ~/.bashrc

# 添加正确格式的 PATH（注意使用双引号）
echo 'export PATH="/home/your_username/.openclaw/venv/bin:$PATH"' >> ~/.bashrc

步骤 3：验证修复：

source ~/.bashrc
echo $PATH

Q6: OpenClaw 网络代理配置

问题表现：OpenClaw 的 web_search 工具无法访问外部网络，报错 fetch failed。

原因分析：

  1. OpenClaw Gateway 作为 systemd 用户服务运行时，不会自动继承 .bashrc 中的环境变量
  2. Node.js 的原生 fetch() 不会自动使用 HTTP_PROXY 环境变量

解决方案：

方法 1：配置 systemd 服务环境变量（推荐）

编辑 OpenClaw Gateway 服务文件：

nano ~/.config/systemd/user/openclaw-gateway.service

在 [Service] 部分添加代理环境变量：

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="http_proxy=http://127.0.0.1:7890"
Environment="https_proxy=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,::1"

重载并重启服务：

systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

方法 2：使用 Clash TUN 模式（最简单）

如果你使用 Clash 作为代理软件，可以启用 TUN 模式，让所有网络流量自动通过代理，无需逐个配置。

Q7: systemd 用户服务不自动启动

问题表现：每次启动 WSL 后，OpenClaw Gateway 服务没有自动运行。

解决方案：

# 步骤 1：确认 WSL 已启用 systemd
sudo nano /etc/wsl.conf

添加或确认以下内容：

[boot]
systemd=true

# 步骤 2：重启 WSL
wsl --shutdown

# 步骤 3：启用服务自启动
systemctl --user enable openclaw-gateway

# 步骤 4：启用用户服务的持久化
sudo loginctl enable-linger $USER

Q8: Browser control service timed out

解决方案：

# 检查浏览器进程
ps aux | grep chrome

# 重启 Gateway
openclaw gateway restart

# 检查 CDP 端口
netstat -tlnp | grep 9222

Q9: Gateway 端口被占用

解决方案：

# 查找占用端口的进程
lsof -i :18789

# 杀死进程
kill -9 <PID>

十一、相关资源

配套文章

官方资源

国内 API 服务商

参考教程

附录

A. 常用镜像源速查表

类型推荐镜像地址
APT清华大学https://mirrors.tuna.tsinghua.edu.cn/ubuntu/
npm淘宝 npmmirrorhttps://registry.npmmirror.com
pip清华大学https://pypi.tuna.tsinghua.edu.cn/simple
Docker中科大https://docker.mirrors.ustc.edu.cn

B. OpenClaw 配置文件路径

文件路径
主配置~/.openclaw/openclaw.json
配置备份~/.openclaw/openclaw.json.backup
Gateway 日志~/.openclaw/logs/gateway.log
systemd 服务~/.config/systemd/user/openclaw-gateway.service
WSL 配置/etc/wsl.conf
Windows WSL 配置C:\Users\<用户名>\.wslconfig

C. OpenClaw 端口速查表

端口服务说明
18789Gateway 主服务OpenClaw 核心 API 和 Control UI 访问端口
18792Browser RelayChrome 扩展与 Gateway 通信的 WebSocket 端口
9222Chrome CDPChrome DevTools Protocol 调试端口（浏览器自动化）

注意：配置 Chrome 扩展时填写的是 Browser Relay 端口 18792，而不是 Gateway 主端口 18789。两者用途不同，请勿混淆。

注意：请妥善保管您的 API Key 和 Token，定期检查系统安全。使用商业 LLM 时，请注意数据隐私，不要发送敏感信息。

avatar
文章
阅读
粉丝