1. 故障现象与根本原因

常见报错：

• 前端 UI 提示：[tools] web_search failed: fetch failed

• 后台日志警告：Sandbox mode requires Docker / Small models (<=300B params) detected... unsafe; sandbox=off; web=[off]

根本原因分析： 当在 OpenClaw 中使用本地小模型（如 Ollama 的 qwen2.5:7b）时，系统底层安全策略会强制切断其直接联网的能力（防止恶意网页进行 Prompt 注入攻击）。要让小模型合法联网，必须满足三个条件：

1. 宿主机必须安装并运行 Docker 作为隔离沙盒。

2. 必须在 OpenClaw 中强制开启全局沙盒模式。

3. 必须手动将 Web 工具组加入允许名单，并指定搜索引擎提供商。

---

2. 环境准备：安装与配置 Docker (Windows 篇)

OpenClaw 的沙盒机制强依赖于 Docker。

步骤：

1. 下载安装包：前往 Docker 官网，下载 Download for Windows – AMD64 版本。

2. 执行安装：双击运行，务必勾选 "Use WSL 2 instead of Hyper-V"。安装完成后重启电脑。

3. 修复 WSL 内核（如遇报错）：

   • 如果 Docker 启动时提示 "WSL needs updating"，请以管理员身份运行 PowerShell。

   • 执行更新命令：wsl --update

   • 更新完毕后，在 Docker 界面点击 "Try Again"。

4. 状态确认：等待 Docker Desktop 左下角亮起绿色的 "Engine running" 指示灯，即代表底层环境准备完毕。

---

3. OpenClaw 核心权限配置

在 PowerShell 中执行以下命令，为小模型放行权限。

开启全局沙盒模式：

PowerShell

openclaw config set agents.defaults.sandbox.mode "all"

放行 Web 工具组权限（注意 Windows 下需用单引号包裹 JSON 数组）：

PowerShell

openclaw config set tools.allow '["group:web"]'

---

4. 搜索引擎提供商 (Provider) 设定

你需要告诉 OpenClaw 使用哪个引擎进行搜索。

步骤：

1. 找到并使用文本编辑器打开配置文件：C:\Users\admin\.openclaw\openclaw.json

2. 定位到 "tools" -> "web" -> "search" 节点。

3. 增加 "provider" 字段，并配置对应的 API 密钥。

配置示例（以 Gemini/Google 为例）：

JSON

  "tools": {
    "allow": [
      "group:web"
    ],
    "profile": "coding",
    "web": {
      "search": {
        "provider": "gemini",
        "gemini": {
          "apiKey": "你的_API_KEY_填在这里"
        }
      }
    }
  }

⚠️ 严重安全提示： 你之前在测试时曾在日志中暴露过真实的 Google API Key (AIzaSy...)。请务必前往 Google Cloud 控制台将其作废并重新生成，以免产生意外计费！ 💡 免配置方案： 如果不想配置 API Key，可将 "provider" 的值改为 "duckduckgo"，它无需鉴权即可免费进行基础搜索。

---

5. 解决 Node.js 网络底层报错 (可选/进阶)

如果在完成以上所有步骤后，依然间歇性出现 fetch failed，这通常是高版本 Node.js (v20+) 在 Windows 下默认优先解析 IPv6 导致的连接失败。

修复方法： 在启动 OpenClaw 前，临时或永久设置环境变量强制走 IPv4：

PowerShell

$env:NODE_OPTIONS="--dns-result-order=ipv4first"

---

6. 重启服务以生效

完成所有配置后，必须重启 OpenClaw 网关服务：

PowerShell

openclaw gateway restart

重启后，即可在 UI 界面中测试类似“搜索一下今天的科技新闻”的指令。