1. 为什么我要把 openclaw 的 web_search 换掉openclaw 这类 Agent 框架默认的web_search工具背后通常接的是公共搜索接口。跑 demo 的时候没感觉一旦让它连续做几十轮检索、抓取、总结问题就冒出来了请求频率一高就被限流返回结构偶尔缺字段最要命的是搜索词和结果会经过第三方做内部资料整理时心里总不踏实。我试过在几个项目里直接用它查技术文档前几次还行后面开始间歇性返回空结果Agent 拿不到内容就反复重试token 消耗直接翻倍。SearXNG 正好能补上这块。它是一个开源的元搜索引擎本身不存搜索历史、不做用户画像把 Google、Bing、DuckDuckGo 等多个来源的结果聚合后统一返回。你可以把它理解成一个「搜索路由器」Agent 只跟你的私有实例说话具体去哪个上游引擎查、怎么合并去重都由 SearXNG 在本地完成。对 openclaw 来说只要把web_search的 base URL 指向这个实例就能用同一套工具协议拿到结构化 JSON不用改 Agent 的推理逻辑。这套方案适合谁一是本地或内网跑 Agent、不想让检索流量外露的开发者二是被公共搜索接口限流搞烦、想要稳定 QPS 的团队三是想给 openclaw 加一个可控搜索后端、方便做结果缓存和审计的人。整篇我会按「Docker 拉起 SearXNG → 改 settings.yml 开 JSON → 配 openclaw 指向私有实例 → 验证请求 → 排错」的顺序走配置都能直接复制。如果你后面还要接 Claude Code 或做长期编码 Agent可以顺带了解下 TaoToken 的 Coding Plan模型调用和搜索后端分开管排查问题时边界更清楚。需要先说明一点SearXNG 默认只给浏览器用JSON 输出是关着的很多人部署完发现formatjson返回 403就是卡在这一步。下面会专门处理。2. 用 Docker 拉起 SearXNG 并开放 JSON 接口先说前置条件一台能跑 Docker 的机器本地或服务器都行装好 Docker 和 Docker Compose 插件docker compose version能输出版本号即可。不需要公网 IP内网访问完全够用openclaw 和 SearXNG 在同一台机器或同一内网时最省事。先建目录把配置和容器数据分开方便后面回滚mkdir -p /opt/searxng cd /opt/searxng接着写docker-compose.yml。这里用官方镜像加一个 Redis 做缓存Redis 不是必须的但加上之后重复查询会快很多Agent 反复搜同一批关键词时体感明显services: searxng: image: searxng/searxng:latest container_name: searxng ports: - 8888:8080 volumes: - ./settings.yml:/etc/searxng/settings.yml:ro environment: - SEARXNG_BASE_URLhttp://127.0.0.1:8888/ - SEARXNG_SECRETchange-this-to-a-random-string depends_on: - redis restart: unless-stopped redis: image: redis:alpine container_name: searxng-redis restart: unless-stopped注意SEARXNG_BASE_URL要和你实际访问地址一致。如果 openclaw 在另一台机器上把127.0.0.1换成 SearXNG 所在机器的内网 IP比如http://192.168.1.20:8888/。这个值影响返回结果里的链接拼接填错会导致结果 URL 指向错误。然后是关键的settings.yml。SearXNG 对配置结构校验很严最稳的写法是用use_default_settings: true继承默认配置只覆盖你要改的字段。JSON 输出必须显式在search.formats里加上json否则接口不认use_default_settings: true general: instance_name: searxng-private enable_metrics: true search: safe_search: 0 autocomplete: default_lang: zh-CN formats: - html - json server: secret_key: change-this-to-a-random-string limiter: false image_proxy: true ui: default_theme: simple几个点解释一下。limiter: false是关掉内置限流因为 openclaw 的请求来自本机、频率可控开着反而容易误伤如果你把实例暴露到公网建议保持开启并配合反向代理。autocomplete设成空字符串是关掉自动补全Agent 用不到还能少一次外部请求。formats里同时保留html和json这样浏览器调试和程序调用都不耽误。配置写完直接起docker compose up -d docker compose psdocker compose ps里两个容器都显示running就对了。如果 searxng 反复重启先看日志docker compose logs --tail50 searxng最常见的报错是Invalid settings.yml基本都是 YAML 缩进或字段层级写错对照上面这份改就行。3. 把 openclaw 的 web_search 指向私有实例容器起来后先确认 SearXNG 本身能返回 JSON再动 openclaw 的配置这样出问题好定位。用 curl 打一发curl -s http://127.0.0.1:8888/search?qopenclawformatjson | head -c 500能吐出一段 JSON、里面有results数组说明接口通了。如果返回 403回到上一节检查formats里有没有json以及limiter是不是还开着。接下来是 openclaw 侧。openclaw 的搜索工具配置一般放在项目根目录的config或settings文件里不同版本字段名略有差异核心是三件套Base URL、API KeySearXNG 本地实例通常不需要留空或填占位、以及工具类型。下面是一份可直接改的 JSON 片段路径按你项目实际的配置文件来{ tools: { web_search: { provider: searxng, base_url: http://127.0.0.1:8888, api_key: , search_path: /search, default_params: { format: json, language: zh-CN, safesearch: 0 }, timeout_ms: 8000, max_results: 8 } } }如果你的 openclaw 版本用的是 TOML 配置等价写法是这样[tools.web_search] provider searxng base_url http://127.0.0.1:8888 api_key search_path /search timeout_ms 8000 max_results 8 [tools.web_search.default_params] format json language zh-CN safesearch 0这里provider字段是关键它决定 openclaw 用哪套请求和解析逻辑。如果框架内置了searxng这个 provider直接填它如果没有就选一个「自定义 HTTP 搜索」类的 provider然后把base_url和search_path指过去返回结构 SearXNG 是标准的results[].title/url/content大部分通用解析器都能吃。max_results建议别设太大8 到 10 条足够 Agent 做摘要设到 20 以上会明显拖慢单轮响应而且后面的结果相关性下降。timeout_ms给 8000 是留了余量SearXNG 聚合多个上游时偶尔会慢超时太短会导致 Agent 误判搜索失败。改完配置重启 openclaw 进程让它重新加载工具定义。到这一步链路就通了openclaw 调web_search→ 打到本地 SearXNG → SearXNG 聚合上游 → 返回 JSON → openclaw 解析成工具结果。4. 验证一次真实搜索请求与结果解析配置改完不能只看「没报错」得跑一次完整请求确认返回结构能被 openclaw 正确解析。分两步验证。第一步直接对 SearXNG 发请求看原始返回长什么样curl -s http://127.0.0.1:8888/search?qDocker%20compose%20healthcheckformatjsonlanguagezh-CN \ | python3 -m json.tool | head -40正常返回里会有query、number_of_results、results这几个顶层字段results里每条包含title、url、content、engine。engine字段能告诉你这条结果来自哪个上游排查「为什么某类结果缺失」时很有用。第二步在 openclaw 里触发一次工具调用。最直接的方式是给它一个必须联网的问题比如让它查某个库的最新版本号然后看日志里web_search的调用记录。如果框架有 debug 日志打开后能看到请求 URL 和返回条数。我实测下来一次正常调用应该在 1 到 3 秒内返回条数和max_results接近。如果 openclaw 侧拿不到结果但 curl 是通的问题多半在解析层。常见情况是框架期望的字段名和 SearXNG 不一致比如它找snippet而 SearXNG 给的是content。这时候有两个办法一是在 openclaw 的 provider 配置里加字段映射二是写一层很薄的适配把 SearXNG 的返回转成框架要的结构。多数情况下改配置就能解决不用动代码。再补一个健康检查动作方便你以后做监控。SearXNG 自带/healthz端点curl -s -o /dev/null -w %{http_code} http://127.0.0.1:8888/healthz返回200就说明服务活着。可以把这个塞进定时任务容器挂了能第一时间知道而不是等 Agent 报错才发现。5. 部署与接入常见报错排查这一节按真实会撞到的报错来对每条给出原因和动作。报错一ValueError: Invalid settings.yml容器起不来。原因基本是 YAML 结构不合法SearXNG 对字段层级校验严格多一层少一层都会挂。动作确认顶层有use_default_settings: truesearch.formats是列表而不是字符串缩进统一用两个空格。改完docker compose restart searxng再看日志。报错二formatjson返回 403 Forbidden。这是最高频的坑。SearXNG 默认只开html格式JSON 要手动加。动作检查settings.yml的search.formats里有没有json同时确认server.limiter为false。两个都对了还 403看请求有没有带正常 User-Agent某些版本对空 UA 会拦。报错三openclaw 日志出现local proxy failed或连接被拒。说明 openclaw 根本没连上 SearXNG。动作先docker compose ps确认容器在跑再确认base_url里的 IP 和端口对得上。如果 openclaw 跑在容器里、SearXNG 在宿主机127.0.0.1是不通的要换成宿主机内网 IP 或 Docker 网络别名。报错四返回 200 但results为空或报reading choices之类的解析错误。空结果通常是上游引擎被限流或查询词太偏换个词再试如果换词也空检查default_lang和safesearch设置。解析错误则是 openclaw 拿到的结构和预期不符动作用 curl 看原始 JSON对照框架文档确认字段名必要时加映射。报错五401 Unauthorized。SearXNG 本地实例默认不需要鉴权出现 401 一般是 openclaw 配置里api_key填了非空值、而实例又没开鉴权或者反过来实例开了鉴权但 key 没填。动作本地部署把api_key留空如果确实要鉴权在反向代理层加别在 SearXNG 里硬塞。报错六OAuth 相关报错。这个和 SearXNG 无关通常是 openclaw 里其他模型 provider 的凭证过期了搜索工具本身不涉及 OAuth。动作单独测web_search工具把模型调用和搜索调用分开验证别混在一起排查。排查时记住一个原则先用 curl 确认 SearXNG 这一层是好的再去查 openclaw 的配置和解析。两层分开测定位速度快很多。6. 后续怎么把这套搜索后端用顺跑通之后有几个小调整能让它更耐用。一是给 Redis 设个内存上限避免长时间运行把内存吃满在 compose 里给 redis 加command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru就行。二是如果 openclaw 的检索量上来了可以在 SearXNG 前面加一层 Nginx 做缓存和限速把重复查询挡在容器外。三是定期看docker compose logs searxng里哪些上游引擎报错多在settings.yml的engines里把不稳定的关掉结果质量会稳一些。如果你后面要把这套 Agent 接到更强的模型上做长期编码任务模型调用和搜索后端建议分开管理。搜索这块你已经有了私有实例模型这块可以看下 TaoToken 的 Coding Plan专门给长期编码和 Agent 场景做的额度方案和本地搜索后端配合起来整条链路的可控性会好很多。需要的话从 API Keys 页面拿凭证接入文档里有各框架的配置示例照着改 base URL 和 model ID 即可。