做 AI Agent 的朋友应该都有过这种体验OpenClaw 自带的 web_search 用起来是挺省事但跑几天下来问题就攒起来了。额度说没就没请求稍微密集一点就被限流更别提频繁换 key、调参数那些碎活。我一开始也忍着后来实在觉得这玩意儿不够稳就在本地用 Docker 部署了一个 SearXNG 私有搜索引擎然后把 OpenClaw 的 web_search 整个替换成了这个本地服务。SearXNG 是个开源的元搜索引擎能把多个搜索引擎的结果聚合到一个统一页面和统一 API 里。对 OpenClaw 这类 Agent 来说最有价值的其实是它的 JSON 接口搜索、抓结果、回传结构化数据一条链路下来非常干净。这篇文章就把我的完整操作整理出来从 Docker 环境准备、SearXNG 启动到 OpenClaw 接入配置和踩坑排查适合手头有 OpenClaw、想干掉外部搜索限额的朋友参考。1. 先把话说清楚OpenClaw 为什么需要一个私有搜索引擎1.1 内置 web_search 的三个扛不住我挑三个最典型的来说。第一是限额。OpenClaw 内建的 web_search 背后通常是某家搜索引擎或 AI 平台的 API免费额度给得很抠一个稍微复杂点的 Agent 任务可能几分钟就烧完了。我的项目经常要批量查资料基本一天不到就见底然后整个任务链就瘫了。第二是限流。额度没烧完也会遇到 429 状态码脚本一密集就触发然后整个 Agent 流程卡在那里等重试还是等超时非常尴尬。尤其是我这边喜欢一次性丢给 Agent 十几个子任务每个子任务都要查好几轮资料限流几乎成了必然事件。第三是隐私。所有关键字都走在第三方通道上做内部资料检索的时候总觉得不太踏实。虽然不是机密内容但每次查询都被外部服务记录时间久了心里难免犯嘀咕。这三个问题不是设置一两个参数能解决的本质上是“搜索这个能力不掌握在自己手里”。我当时选型的标准非常明确本地部署、有标准化 API、支持 Docker、不会被上游随时改规则。SearXNG 恰好全都满足。1.2 为什么是 SearXNG 而不是别的可能有人会说直接申请一个正式搜索引擎官方 API 不就行了可以但那条路要绑卡、填申请、走审核流程个人项目用起来很重。还有一条路是让 OpenClaw 直接解析某个网页搜索结果的 HTML这个太脆了页面结构一改就挂维护成本全堆在自己身上。剩下一个候选是本地跑一个爬虫脚本自己抓代码量不小还得处理反爬和去重想着就头大。SearXNG 在这几个方案里算是最省事的它把多个来源的搜索结果统一成自己的格式提供 HTML 页面和 JSON API 两种出口。镜像在 Docker Hub 上一直有维护装完以后基本零维护。另外它本身就是隐私友好定位没有任何商业压力不会无缘无故砍掉某个接口。我把几个方案放在一起比过方案部署成本稳定性是否需要付费API 完备度隐私可控OpenClaw 内置 web_search无一般受上游影响按量或限额封装好但不可控低申请搜索引擎官方 API中高通常收费高中自己写爬虫脚本高低无自己说了算高Docker 部署 SearXNG低高无高JSON API高1.3 替换之后的整体架构部署完以后的链路是这样OpenClaw 发起搜索请求配置里的 web_search 地址指向本地 SearXNG 的 JSON 接口SearXNG 再去上游搜索引擎取结果统一转成结构化 JSON 返回给 OpenClaw。整个链路里只有 SearXNG 到上游搜索这一段依赖外网其他全部在本机闭环。搜索历史、缓存、临时数据都留在这台机器上。这个架构最大的好处是OpenClaw 的代码不用大改只在配置层把搜索工具的 endpoint 换一下就行。而且因为 SearXNG 天然支持多种格式输出就算后面 OpenClaw 升级了或者你想接别的 Agent 框架这套搜索服务仍然可以直接复用。2. Docker 环境准备Windows 和 Linux 两套方案2.1 Windows 下 Docker Desktop 安装的关键点如果你的本机是 Windows路径通常是安装 Docker Desktop。这里有两个开关容易卡住一是 WSL2二是 BIOS 里的虚拟化。Docker Desktop 现在默认用 WSL2 后端跑 Linux 容器所以装之前先把 Windows 的“适用于 Linux 的 Windows 子系统”功能打开。打开方式控制面板程序和功能启用或关闭 Windows 功能勾选“适用于 Linux 的 Windows 子系统”然后重启。想确认 WSL2 是不是默认版本可以在 PowerShell 里敲wsl --status看到“默认版本: 2”就对了。如果你之前装过 WSL1 的老环境可能需要手动wsl --set-default-version 2升级一下。另一个更隐蔽的坑是 BIOS 虚拟化没开。很多机器买回来默认没开 SVMAMD或 VT-xIntelDocker Desktop 启动时会直接报 Virtualization support not detected 或者 Docker Desktop failed to start 这类提示。解决办法是进 BIOS找到虚拟化开关打开。具体按键因主板而异常见的是开机时按 Del 或 F2进去找 AMD SVM 或 Intel VT-x把 Disabled 改成 Enabled保存重启。2.2 Linux 下安装 Docker EngineLinux 的安装路径清爽很多以 Ubuntu 和 Debian 系为例直接走官方脚本最简单curl -fsSL https://get.docker.com | bash sudo usermod -aG docker $USER newgrp docker第一行装好 Docker Engine 和 compose 插件第二三行把你的用户加进 docker 组避免每次敲命令都要 sudo。Debian 或 Ubuntu 老版本如果脚本跑不了就用手动方式加 GPG key、加软件源、apt install docker-ce docker-ce-cli containerd.io三步走完也不复杂。装完以后验证一下docker --version docker compose version能看到版本号就说明环境没问题了。这里有个小提醒很多教程让新手装 Docker Desktop 的 Linux 版本其实 Linux 服务器上完全不需要装 Engine 就够了少一层 GUI 反而更省资源更稳定。2.3 镜像拉不动先配镜像加速器这一步经常被忽略等 deploy 的时候才发现镜像下不动。SearXNG 的官方镜像在 Docker Hub 上国内直连的速度很看网络心情。最简单的办法是给 Docker 配置 registry mirror。Windows 和 Linux 都一样在 Docker Engine 配置文件里加一段registry-mirrors填入可用的镜像加速地址然后重启 Docker。注意镜像加速只影响 docker pull 环节拉下来之后容器运行不受影响。如果你用 Docker Desktop直接在 Settings 的 Docker Engine 页面里编辑 JSON 就行保存后会自动重启引擎。Linux 下则改/etc/docker/daemon.json改完执行sudo systemctl restart docker。如果不想动全局配置也可以对单条命令加参数但日常使用还是全局配置省心。我建议在部署 SearXNG 之前就把这一步做好免得 docker compose up 的时候卡在 pull 镜像上那种等待非常磨人。3. SearXNG 一键部署从 docker-compose 到浏览器验证3.1 准备部署目录和 docker-compose.yml先给出一个完整可复制的部署目录searxng/ ├── docker-compose.yml └── searxng-data/ # 挂载出来的配置目录启动后自动生成docker-compose.yml 核心内容version: 3 services: searxng: image: searxng/searxng:latest container_name: searxng ports: - 8080:8080 environment: - SEARXNG_BASE_URLhttp://127.0.0.1:8080/ - SEARXNG_SECRETgenerate_a_long_random_string volumes: - ./searxng-data:/etc/searxng restart: unless-stopped几个点解释一下。端口映射写的是8080:8080左边是宿主机端口右边是容器端口如果你机器上 8080 已有服务在跑把左边改成 8081 就行容器内部不用动。SEARXNG_SECRET是必填的官方镜像启动时如果检测不到这个变量会直接拒绝启动因为后面所有 session、API 签名都要用它。生成随机串最快的方法是openssl rand -hex 32SEARXNG_BASE_URL看起来只是个展示地址但它会影响页面里生成的链接和部分 API 返回值建议填你实际访问这个服务的地址。如果你后面让 OpenClaw 也部署在同一台机器保持 127.0.0.1 是最省事的。restart: unless-stopped的意思是容器崩了自动拉起但手动 stop 之后不会自动复活适合常驻服务。3.2 settings.ymlJSON 接口和限速开关镜像第一次启动时会向挂载目录写入一份默认配置。默认配置可以直接用但如果要让 OpenClaw 能拿到 JSON 结果必须确认一下search.formats里有没有json。新版本默认是开了的旧版本可能只有 html。看配置目录下的 settings.yml找到这两个块server: secret_key: your_random_secret_key limiter: true search: formats: - html - jsonlimiter: true默认开启对公网实例是好事防止被刷。但如果你是本地或者内网专用它反而可能误伤高频调用Agent 一批任务下去容易触发 429。我个人的做法是内网部署时把它改成 false或者先用默认配置跑一阵观察一下会不会频繁 429再决定要不要关。3.3 启动服务和浏览器验证配置好了直接docker compose up -d第一次会拉镜像稍等片刻。启动以后浏览器打开http://127.0.0.1:8080/应该能看到一个偏简洁的搜索页面搜个关键词能出结果就说明实例活了。这时建议顺手检查一下容器状态docker ps docker logs -f searxngdocker logs里如果出现类似 listen tcp :8080: bind: address already in use 就说明端口冲突了回去改映射端口就好。如果没有报错下一步才是关键。3.4 JSON API 验证OpenClaw 要用的不是网页是 JSON 接口。用 curl 测一下curl http://127.0.0.1:8080/search?qtestformatjson返回大段 JSON里面能看到results、query、number_of_results这些字段就说明 API 通道是通的。这时候可以看一眼返回结构里每个结果的字段通常有url、title、content、engine、score等Agent 解析主要靠这几个字段。有些时候页面上能搜到结果但 API 返回空多半是 SearXNG 对 JSON 请求走了另一套引擎策略后面排查章节再谈。4. 把 OpenClaw 的 web_search 切到 SearXNG4.1 先想清楚 OpenClaw 侧要改什么OpenClaw 的 web_search 工具本质上是“调用一个搜索 API 然后把结果喂回给模型”。要换成 SearXNG核心就一件事把搜索工具的请求地址从原来的外部服务改成http://127.0.0.1:8080/search。不同版本的 OpenClaw 配置入口可能略有差异有的在配置文件的 tools 段有的在启动时的参数里但思路都一样。我在用的版本里搜索工具相关配置大概是这样的结构tools: web_search: provider: custom api_base: http://127.0.0.1:8080/search api_format: json query_param: q max_results: 10这是基于我实际部署时记录下来的配置形态如果你的版本字段名不同对照一下官方文档里的 web_search 配置说明即可核心字段无非是 endpoint、请求格式、结果条数这几个。如果你的 OpenClaw 是通过 MCP 插件体系接入工具的那更简单社区里有现成的 SearXNG MCP Server把 MCP 的 server 地址指向http://127.0.0.1:8080/search就行工具名照样还是 web_search 或者 searxng_search。4.2 一个最容易忽略的坑127.0.0.1 到底是哪台机器如果你的 OpenClaw 和 Docker 跑在同一台物理机上127.0.0.1:8080没问题。但如果 OpenClaw 跑在宿主机Docker 也跑在宿主机而 OpenClaw 本身又跑在容器里常见于 OpenClaw 也容器化部署那“127.0.0.1”指向的是 OpenClaw 自己的容器根本访问不到 SearXNG。这时候要么让 OpenClaw 容器和 SearXNG 容器挂同一个 Docker network然后地址写服务名http://searxng:8080/search要么直接用宿主机局域网 IP比如http://192.168.1.100:8080/search。我在 Ubuntu 上装 OpenClaw 时就是这么处理的OpenClaw 在本机进程里SearXNG 在 Docker 里两者共享宿主机的网络命名空间所以写127.0.0.1就通。如果你的环境是 Windows 上跑 WSL2情况又不一样从 Windows 侧访问 WSL2 里容器映射出来的端口通常用localhost没问题但反过来 WSL2 里访问 Windows 侧的 OpenClaw 服务就要用 Windows 主机 IP 了。这个链路经常把人绕晕建议在改配置之前先做一次连通性验证别等 Agent 跑起来才发现全是不通的。4.3 配置完的完整测试路径改完配置不要急着跑完整 Agent 流程先用最小方式验证在 OpenClaw 的交互面板里单独调用一次 web_search输入一个测试关键词比如“OpenClaw 最新版本”看返回是否正常。正常的返回应该是有几条带 title、url、content 的结果列表。如果这一步通了再跑一个带搜索环节的完整任务观察日志里搜索请求是否都打到了 SearXNG 上。我换完以后跑过一批需要联网查资料的任务效果提升最明显的是不再 429响应速度稳定在几百毫秒到一两秒而且搜索结果不受外部额度限制。整个过程下来 OpenClaw 的代码一行没改纯粹是配置替换。5. 踩坑实录部署和接入过程中的典型问题5.1 Docker Desktop 启动失败Virtualization support not detected这个报错出现频率极高我第一次在 Windows 上装就遇到了。原因基本就是 BIOS 里的虚拟化没开或者 Hyper-V 没启用。解决顺序先确认 BIOS 里 SVM 或 VT-x 是 Enabled再确认 Windows 功能里的 Hyper-V 和“虚拟机平台”都勾上了。如果 BIOS 已经开了还是报错去 PowerShell 里以管理员身份跑bcdedit /set hypervisorlaunchtype auto然后重启。这些都是常规操作但顺序别搞反先 BIOS 后系统。如果你用的是 AMD 平台BIOS 里那项通常叫 SVM ModeIntel 平台叫 VT-x 或者 Virtualization Technology不同主板命名略有差异但找“Virtualization”关键词一般没错。5.2 容器起不来或反复重启docker ps -a看容器状态如果是 Exited用docker logs searxng看日志。我遇到过的两类典型问题一是 secret_key 没设日志里明确会提示缺少 secret_key二是挂载目录权限不对导致容器内进程写不了配置文件日志里会出现 permission denied解决方法是给目录加写权限或者修正目录属主。还有一种情况是内存不足。SearXNG 本身不重但 Docker Desktop 在 Windows 上默认内存配额不高跑的任务多了可能 OOM去 Docker Desktop Settings 里把内存调到 4GB 以上更稳。Linux 服务器上如果同时跑着 OpenClaw 和其他容器也要留意系统可用内存free -h看一眼就知道够不够。5.3 页面能搜到结果但 JSON 接口返回空这个我实打实排查过。页面和 JSON 接口在部分引擎下会走不同的策略比如某些引擎对无浏览器环境返回空结果。方法有三在 settings.yml 里多启用几个上游引擎别单一依赖某个容易空的把server.limiter关掉或者调高时间窗口确认请求头里有合理的 User-Agent。还有一个细节JSON 格式下若返回 403多半是 SearXNG 把非浏览器请求当成了机器人可以尝试在 settings.yml 里调整 botdetection 配置本地部署可以直接放宽。5.4 搜索接口正常但 OpenClaw 解析不到结果这个现象我遇到过两次表现为日志里明明打了搜索请求返回也有 JSON但 Agent 认为没结果。原因通常是 SearXNG 返回结构里的字段名和 OpenClaw 预期解析的字段名对不上。比如 OpenClaw 期望content字段当摘要SearXNG 某些引擎返回的却是空 content只有snippet。解法是检查你传入的max_results参数不要太激进同时确认 SearXNG 返回的results列表长度不是 0。另外有些引擎对连续查询会临时封掉导致间歇性空结果可以在 settings.yml 里把search.safe_search调一下或者直接换更稳定的引擎组合。5.5 高频调用被限流频繁触发 429本地自建搜索引擎的唯一好处就是没有云厂商限流但 SearXNG 自己默认的 limiter 还是会拦。前面提过server.limiter: true改成 false 是最直接的解法但要注意如果端口暴露到了公网这个开关就不建议关。内网和本机使用关了没问题。如果不想全关也可以调整限流的时间窗口和请求次数上限按你的实际调用频率配一个余量。我自己的配置是直接把 limiter 关掉了因为就我一个人用不存在被刷的风险。5.6 数据持久化和升级备份最后补一条运维向的。SearXNG 的挂载目录里不止有 settings.yml还有搜索引擎的缓存数据。升级镜像前先备份整个searxng-data/目录特别是当你在 settings.yml 里改过自定义引擎配置时备份能让你失败后一秒回滚。升级操作也很简单docker compose pull docker compose up -d容器会自动用新镜像重建数据目录因为挂载在外面所以不会丢。这个习惯我一直在用每次改配置或者升级前都会顺手 tar 一下整个目录成本极低但真到要回滚的时候能救命。我个人在实际使用中的一个体会是SearXNG 最值钱的不是那个搜索页面而是那个稳定的 JSON 接口。把 OpenClaw 的 web_search 切过来以后我一直是让 Agent 在本地查资料额度焦虑直接消失了。最后再分享一个习惯每次改完 settings.yml 我都会用docker compose restart重启容器并且翻一下docker logs确认没有加载报错再去跑任务这个小习惯帮我避免了很多“看似正常其实配置没生效”的尴尬。如果你也正在给 OpenClaw 找稳定的搜索后端这套方案可以直接复制过去试试。