大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



我折腾 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年2月9号最开始的使用截图：

下面是最近的使用截图：

再说安装过程里的坑。

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 环境主要有两条路：

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

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

• 网络共享：配置镜像网络模式后，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。每个容易踩坑的环节都有详细说明，零基础新手也可以跟着一步步完成。

---

• 引言
• 一、快速开始
• 二、前置知识
• [三、WSL 安装与网络配置](#三、WSL 安装与网络配置 "#%E4%B8%89wsl-%E5%AE%89%E8%A3%85%E4%B8%8E%E7%BD%91%E7%BB%9C%E9%85%8D%E7%BD%AE")
  • [3.0 启用 WSL 功能（前置步骤）](#3.0 启用 WSL 功能（前置步骤） "#30-%E5%90%AF%E7%94%A8-wsl-%E5%8A%9F%E8%83%BD%E5%89%8D%E7%BD%AE%E6%AD%A5%E9%AA%A4")
  • [3.1 安装 Ubuntu 到指定目录（可选）](#3.1 安装 Ubuntu 到指定目录（可选） "#31-%E5%AE%89%E8%A3%85-ubuntu-%E5%88%B0%E6%8C%87%E5%AE%9A%E7%9B%AE%E5%BD%95%E5%8F%AF%E9%80%89")
  • [3.2 安装 WSL](#3.2 安装 WSL "#32-%E5%AE%89%E8%A3%85-wsl")
  • [3.3 Ubuntu 初始化](#3.3 Ubuntu 初始化 "#33-ubuntu-%E5%88%9D%E5%A7%8B%E5%8C%96")
  • [3.4 WSL 与 Windows 文件互访](#3.4 WSL 与 Windows 文件互访 "#34-wsl-%E4%B8%8E-windows-%E6%96%87%E4%BB%B6%E4%BA%92%E8%AE%BF")
  • [3.5 WSL 网络模式配置](#3.5 WSL 网络模式配置 "#35-wsl-%E7%BD%91%E7%BB%9C%E6%A8%A1%E5%BC%8F%E9%85%8D%E7%BD%AE")
  • [3.6 防火墙配置](#3.6 防火墙配置 "#36-%E9%98%B2%E7%81%AB%E5%A2%99%E9%85%8D%E7%BD%AE")
• 四、国内镜像源配置
• [五、OpenClaw 安装](#五、OpenClaw 安装 "#%E4%BA%94openclaw-%E5%AE%89%E8%A3%85")
• [六、配置国内大模型 API](#六、配置国内大模型 API "#%E5%85%AD%E9%85%8D%E7%BD%AE%E5%9B%BD%E5%86%85%E5%A4%A7%E6%A8%A1%E5%9E%8B-api")
• 七、服务管理与访问
• 八、高级配置
• 九、使用踩坑技巧
• [十、常见问题 FAQ](#十、常见问题 FAQ "#%E5%8D%81%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98-faq")
• 十一、相关资源

---

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

1. 安装 WSL（PowerShell 管理员）

 
2. 重启后，创建配置文件 
 
3. 应用配置
 
4. 进入 WSL，配置国内镜像源后安装 OpenClaw （镜像源配置参考第四章）
 
5. 运行初始化向导
 
6. 配置国内 API
 

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

7. 重启服务

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 服务器（浏览器、数据库、文件系统等）

---

在安装 WSL 之前，需要先确保 Windows 已启用两个底层功能组件：适用于 Linux 的 Windows 子系统 和 虚拟机平台。

💡 如果你直接执行 就能成功安装，说明系统已经自动启用了这些功能，可以跳过本节。但如果 报错或提示功能未启用，就需要手动开启。

方式一：GUI 方式（控制面板）

1. 按 搜索 "启用或关闭 Windows 功能" ，点击打开
2. 在弹出的窗口中，找到并勾选以下两项：
   • ✅ 适用于 Linux 的 Windows 子系统（Windows Subsystem for Linux）
   • ✅ 虚拟机平台（Virtual Machine Platform）
3. 点击 "确定" ，等待系统安装完成
4. 重启计算机

方式二：命令行方式（dism.exe）

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

 
两条命令执行完毕后，必须重启计算机。
 

重启后，建议将 WSL 默认版本设置为 2：

 
验证功能是否已启用
 

重启后，在 PowerShell 中执行：

 
两个功能的状态都应显示为 "已启用"（Enabled） 。
 

默认情况下， 会将 Ubuntu 安装到系统盘（C 盘），随着使用时间增长，WSL 的虚拟磁盘文件（）会越来越大。如果你的 C 盘空间有限，建议将 Ubuntu 安装到其他磁盘。

💡 如果你不在意安装位置，可以直接跳到 [3.2 安装 WSL](#3.2 安装 WSL "#32-%E5%AE%89%E8%A3%85-wsl")，使用默认的一键安装方式。

方式一：使用 --location 参数直接安装到指定目录（推荐）

WSL 较新版本（2.0+）支持 参数，可以在安装时直接指定存储位置。

步骤 1：先确保 WSL 已更新到最新版本：

 
步骤 2 ：使用 参数安装 Ubuntu 到指定目录：
 
安装完成后，Ubuntu 的虚拟磁盘文件将存储在 目录下，而非默认的 C 盘。
 

验证安装位置：

⚠️ 如果你的 WSL 版本较旧， 参数可能不被支持，会提示"无法识别的参数"。此时请使用方式二。

方式二：手动下载离线包安装到指定目录

这种方式兼容性最好，适用于所有 WSL 版本，原理是手动下载 Ubuntu 发行版包，解压到目标目录后注册。

步骤 1：下载 Ubuntu 离线安装包

在 PowerShell 中执行（以 Ubuntu 24.04 为例）：

💡 常用下载地址：

• Ubuntu 24.04：
• Ubuntu 22.04：
• 更多发行版：微软官方 WSL 手动安装页面

步骤 2：解压安装包

 
解压后，目录下会出现一个类似 的子包文件，继续解压它：
 
步骤 3：运行安装程序
 
首次运行会提示创建用户名和密码（与默认安装流程相同）。
 

步骤 4：清理安装包（可选）

 
方式三：先默认安装，再迁移到指定目录
 

如果你已经用 完成了默认安装（在 C 盘），也可以事后迁移到其他磁盘。

步骤 1：导出当前 Ubuntu 为备份文件

 
步骤 2：注销 C 盘上的旧实例
 
步骤 3：导入到新目录
 
步骤 4：设置默认登录用户
 

迁移后 WSL 默认会以 root 身份登录，需要恢复为之前创建的普通用户：

 
如果 命令不可用，可以在 中配置：
 
在 WSL 中编辑配置文件：
 
然后重启 WSL：
 
步骤 5：验证并清理
 

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

强烈建议使用 WSL 2。

一键安装 WSL

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

 
此命令将自动执行：
 

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

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

验证安装状态

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

预期输出示例：

现有 WSL 用户更新

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

首次启动 Ubuntu 时，系统会提示创建 UNIX 用户名和密码：

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

WSL 和 Windows 的文件系统是双向互通的，这是 WSL 相比传统虚拟机最大的优势之一。以下是常用路径的对照表：

WSL 中访问 Windows 文件

在 WSL 终端中，Windows 的各个磁盘自动挂载在 目录下：

使用示例：

Windows 中访问 WSL 文件

Windows 可以通过网络路径 或 访问 WSL 的文件系统：

使用方式：

1. 文件资源管理器地址栏 ：直接输入 即可浏览 WSL 文件
2. 左侧导航栏 ：文件资源管理器左侧通常会显示 "Linux" 图标，点击可展开所有已安装的发行版
3. 映射网络驱动器 ：右键 → 映射网络驱动器，即可为 WSL 分配盘符（如 ），方便日常访问

💡 性能提示 ：WSL 内的程序访问 下的 Windows 文件时，I/O 性能会显著低于访问 WSL 原生文件系统（ 下）。因此，建议将需要频繁读写的项目文件放在 WSL 文件系统内，而非 Windows 磁盘上。

快速路径对照速查表

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

NAT 模式 vs 镜像模式

推荐使用镜像模式。

💡 WSL 1 用户注意 ：镜像网络模式是 WSL 2 专属功能， 中的 配置段对 WSL 1 不生效。不过 WSL 1 也不需要这个配置------WSL 1 没有虚拟机层，网络栈直接与 Windows 共享，天然不存在 NAT 隔离问题。这也是本文推荐 WSL 2 的原因之一：虽然需要额外配置镜像模式，但 WSL 2 运行完整的 Linux 内核，性能和兼容性远优于 WSL 1，配好镜像模式后网络体验与 WSL 1 同样透明。

配置镜像网络模式

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

步骤 2 ：创建或修改名为 的文件（注意前面的点号）

步骤 3：使用记事本打开文件，添加以下配置：

步骤 4：保存文件

步骤 5：在 Windows 终端中执行以下命令以应用配置：

步骤 6：等待约 8 秒钟以确保虚拟机彻底关闭，然后重新启动 Ubuntu

验证网络模式

进入 WSL 后，执行以下命令验证：

如果配置成功，WSL 将使用与 Windows 相同的局域网 IP 地址段。

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

创建防火墙规则

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

测试端口连通性

---

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

备份原配置

配置清华镜像源

Ubuntu 24.04 (Noble) ：

Ubuntu 22.04 (Jammy) ：

更新软件包索引

其他可选镜像源

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

运行脚本：

---

安装基础工具

配置 sudo 免密（可选）

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

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

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

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

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

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

---

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

国内用户在选择大模型服务商时，可以试试 阿里百炼 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 自动完成配置。

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

6.2.1 前置：安装并配置 Claude Code

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

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

该文章涵盖：

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

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

6.2.2 用 Claude Code 配置 OpenClaw API

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

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

配置 MiniMax：

配置智谱 GLM：

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

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

6.2.3 配置文件参考格式

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

MiniMax 参考：

智谱 GLM 参考：

6.2.4 手动备份配置

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

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

---

前台运行模式（调试用）

状态检查选项

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

启用服务自启动

启用 WSL systemd

编辑 ：

添加或确认以下内容：

重启 WSL：

本地访问

局域网访问配置

编辑 ：

修改 Gateway 配置：

获取本机局域网 IP：

访问地址：

---

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

五种方式对比

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

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

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

架构：

启动方式：

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

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

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

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

解决方法：

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

验证端口是否开放：

或在 WSL 中：

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

配置 OpenClaw 连接：

编辑 ：

方案二：WSL Chrome + WSLg

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

安装 Chrome：

启动（附带网络工具和调试端口）：

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

重启 WSL 后再尝试。

配置浏览器网络环境（永久生效，推荐）：

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

方案三：Playwright 独立浏览器

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

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

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

方案五：curl / HTTP 请求

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

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

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

步骤 1：安装扩展文件

扩展默认安装在：

步骤 2：在 Chrome 中加载扩展

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

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

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

解决方案：

• 方法 1（推荐） ：在文件选择器对话框中按 Ctrl + H 切换显示隐藏文件，然后导航到
• 方法 2：创建软链接到非隐藏目录

  然后在文件选择器中选择

也可以直接在 Windows 文件浏览器地址栏输入 来访问 WSL 文件系统，直接定位到扩展目录。

步骤 3：配置扩展

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

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

获取 Gateway Token：

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

步骤 4：使用扩展

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

Browser Service 配置

编辑 ：

Skills - OpenClaw 的扩展功能模块。

编辑 ：

mcporter 配置

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

安装 mcporter：

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

• - Cursor 的 MCP 配置
• - Claude Desktop 的 MCP 配置

通过飞书机器人与 OpenClaw 进行对话，支持私聊和群聊， 国内网络环境下可直接使用。

💡 OpenClaw 通过 WebSocket 长连接接入飞书，不需要公网 URL， 也不需要配置回调地址，对 WSL 本地部署非常友好。

整体流程分为四步：安装飞书插件 → 创建飞书应用 → 配置 OpenClaw 飞书参数 → 配置飞书机器人权限， 最后完成配对授权即可开始对话。

前置准备

飞书开放平台入口：open.feishu.cn/app

---

第一步：安装 OpenClaw 飞书插件

提供四种安装方式，按顺序尝试，方式一失败则依次尝试后续方式。

方式一：官方命令安装（推荐）

方式二：手动下载安装

方式三：让 OpenClaw 自动安装

在 TUI 或 Web UI 的 Chat 界面发送以下内容 （将 和 替换为下一步创建飞书应用后获取的信息）：

OpenClaw 会自动完成安装、配置、重启，无需手动执行后续配置命令。

方式四：通过 openclaw config 界面选择安装（新版支持，最便捷）

进入配置界面后选择飞书插件进行安装。

---

第二步：在飞书开放平台创建企业自建应用

1. 登录飞书开放平台后，点击右上角「开发者后台」
2. 点击「创建企业自建应用」，填写应用名称（如"OpenClaw 机器人"）和描述，点击创建

4. 进入「基础信息」→「凭证与基础信息」，记录 App ID 和 App Secret，后续配置需用

---

第三步：在 OpenClaw 中配置飞书参数

如果你使用了上方方式三或方式四完成安装，跳过此步骤。

将 和 替换为实际信息，逐行执行：

配置完成后重启 Gateway：

也可直接编辑配置文件 ：

验证飞书渠道状态：

成功后应显示：

---

第四步：配置飞书机器人权限与事件订阅

回到飞书开发者后台，按以下步骤配置，每步配置后记得保存：

1. 添加机器人能力

左侧菜单 → 「应用能力」 → 「添加应用能力」，点击「机器人」卡片添加。

2. 完善机器人说明

在机器人配置区域，点击「如何开始使用」旁的编辑按钮，添加简单说明 （如"OpenClaw AI 机器人，输入问题即可解答"）。

3. 配置事件订阅

左侧菜单 → 「开发配置」 → 「事件与回调」， 订阅方式选择「使用长连接接收事件」并保存。

⚠️ 最容易遗漏的配置：如果机器人能发消息但收不到消息， 99% 是因为没有选择「使用长连接接收事件」，默认是 Webhook 模式。

4. 添加接收消息事件

点击「添加事件」，搜索 ，添加并确认开通对应权限。

5. 开通核心权限

左侧菜单 → 「开发配置」 → 「权限管理」：

• 应用身份权限 ：搜索 ，全部选中并开通
• 用户身份权限 ：搜索 ，选中并开通

6. 创建版本并发布

点击页面顶部「应用发布」 → 「版本管理与发布」， 创建新版本并填写更新说明后申请发布。

💡 企业自建应用发布后无需平台审核，直接生效。

---

第五步：配对授权（最后一步）

飞书机器人配置完成后，需完成配对授权才能正常响应消息， 未授权时发送消息会提示权限错误。

获取配对码

在飞书中向配置的机器人发送任意消息（如"测试"）， 机器人会回复包含配对码的提示：

执行配对命令

复制回复中的配对命令，将 替换为实际配对码，在 WSL 终端执行：

终端输出 表示配对成功。

重启 Gateway 使授权生效

验证是否成功

再次在飞书向机器人发送消息（如"你好"），机器人能正常响应即授权成功。

若仍提示权限问题，等待 2-3 分钟再试，飞书权限同步存在一定延迟。 群聊中需 @机器人 才能响应，单聊可直接发送消息。

---

⚠️ 常见问题

机器人能发消息但收不到消息

回到飞书开放平台 → 事件与回调，确认已选择「使用长连接接收事件」， 而不是默认的 Webhook 模式。

插件加载报错

应用发布后机器人仍无法使用

确认已开通 权限，权限变更后需重新发布应用版本才能生效。

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

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

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

方法一：使用配置命令

方法二：手动编辑配置

编辑 ：

---

问题描述：

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

**实践：

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

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

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

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

---

解决方案：

解决方案：

解决方案：

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

解决方案：

1. 确认已执行 并等待 8 秒后重新启动
2. 检查 文件路径是否正确（）
3. 确认 WSL 版本为 2.0 以上
4. 更新 WSL 内核：

问题表现：

 
原因分析：
 

• Windows 的 环境变量会被 WSL 继承
• Windows PATH 中包含带括号的路径，如
• 如果 中的 语句没有使用双引号，bash 会将括号解释为子 shell 语法

解决方案：

步骤 1 ：使用 参数启动 bash（绕过 ）：

步骤 2 ：修复 文件：

步骤 3：验证修复：

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

原因分析：

1. OpenClaw Gateway 作为 systemd 用户服务运行时，不会自动继承 中的环境变量
2. Node.js 的原生 不会自动读取系统网络环境变量

解决方案：

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

编辑 OpenClaw Gateway 服务文件：

在 部分添加网络环境变量：

重载并重启服务：

方法 2：使用网络工具 TUN 模式（最简单）

如果你使用 Clash 等网络工具，可以启用 TUN 模式，让所有网络流量自动走指定通道，无需逐个配置。

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

解决方案：

添加或确认以下内容：

解决方案：

解决方案：

---

• 国内安装 Claude Code 并切换使用国内大模型 API：完整指南（本系列上篇，包含 API Key 获取、Claude Code 配置方法）

• OpenClaw 官方文档
• OpenClaw GitHub

• MiniMax 官网
• 智谱 AI 官网
• 阿里百炼

• Shambix WSL 安装教程
• OpenClaw FAQ
• 飞书开放平台文档

---

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

---

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