1. 项目概述为OpenClaw构建私有搜索后端如果你和我一样在折腾本地AI工具链时对OpenClaw的web_search功能又爱又恨那么这个项目可能就是你的解药。OpenClaw是一个强大的AI代理框架但其内置的网页搜索功能通常依赖于Brave Search等外部商业API。对于注重隐私、希望数据不出内网或者单纯想省下API调用费用的自托管玩家来说这多少有点“卡脖子”的感觉。openclaw-searxng-bridge这个项目本质上是一个轻量级的“协议转换器”。它巧妙地利用了OpenClaw某些版本中web_search工具对Brave Search API的硬编码依赖在中间插入了一个兼容层。这个兼容层会拦截原本发往Brave的搜索请求将其无缝转发到你自托管的SearXNG实例再由SearXNG去聚合Google、Bing、DuckDuckGo等各大搜索引擎的结果。最终你得到的是一个完全私有化、可掌控的搜索数据流而OpenClaw对此浑然不觉依然以为自己在和Brave愉快地对话。这个方案特别适合已经拥有或打算搭建SearXNG搜索集群的Homelab爱好者、隐私敏感型开发者或者任何希望将AI工作流的依赖项尽可能内网化的技术玩家。它不要求你修改OpenClaw的核心代码而是通过一个简单的Node.js服务和一个补丁脚本实现“偷梁换柱”。接下来我会带你从零开始手把手搭建这套系统并分享我在部署和调试过程中踩过的坑和总结的技巧。2. 核心架构与设计思路拆解在动手之前理解整个数据流是如何工作的至关重要。这能帮助你在出现问题时快速定位是哪个环节掉了链子。2.1 数据流转全景图整个系统的核心数据流可以概括为以下路径OpenClaw Agent (发起 web_search 请求) - OpenClaw Gateway (路由请求使用 provider: brave 配置) - 硬编码的Brave Search API端点 (已被补丁修改) - openclaw-searxng-bridge 服务 (监听在 http://bridge-host:8899/res/v1/web/search) - 自托管 SearXNG 实例 (监听在 http://searxng-host:8888/search) - 上游搜索引擎 (Google, Bing, DuckDuckGo等)这个链条的关键在于“补丁”环节。在OpenClaw的某些发行版中Brave Search API的URL是直接写死在编译后的JavaScript bundle文件里的。我们的补丁脚本就是去找到这些硬编码的URL字符串将其替换为我们桥接服务的地址。这样当OpenClaw试图调用Brave时请求实际上被重定向到了我们自己的服务器上。2.2 为何选择桥接方案而非直接修改OpenClaw你可能会问为什么不直接给OpenClaw贡献代码增加一个原生的SearXNG搜索提供商呢这是一个好问题也是项目作者在Roadmap中提到的最终目标。但在当下桥接方案有几个现实优势即时可用性无需等待OpenClaw官方合并、发布新版本。你现在就能用上自托管的搜索后端。非侵入性你不需要理解或修改OpenClaw复杂的内部工具调用逻辑和认证机制。桥接服务只模拟Brave API的接口形态内部实现完全自定义。低风险补丁仅修改分发文件不触及源代码。如果出现问题恢复备份或重新部署OpenClaw即可回退。灵活性桥接服务是你完全控制的。你可以在其中添加日志、结果过滤、缓存、甚至请求重试等逻辑而无需动OpenClaw分毫。当然这个方案也有其局限性最主要的就是依赖补丁。每次升级OpenClaw如果其分发文件被覆盖就需要重新打补丁。这算是一个为了快速实现功能而接受的“技术债”。2.3 组件选型与部署考量项目推荐将SearXNG和桥接服务部署在同一台“搜索虚拟机”上而OpenClaw Gateway部署在另一台机器。我强烈建议遵循这个架构原因如下网络隔离与安全桥接服务端口8899和SearXNG端口8888只需要在搜索主机内部互通。你只需要将桥接服务的8899端口暴露给运行OpenClaw的主机即可无需将SearXNG的管理界面或API直接暴露给OpenClaw网络。这遵循了最小权限原则。资源管理SearXNG在进行搜索时可能会消耗一定的CPU和内存资源取决于并发请求和启用的引擎数量。将其与OpenClaw Gateway分离可以避免资源竞争影响AI推理的稳定性。维护便利搜索基础设施SearXNG Bridge可以作为一个独立的单元进行维护、备份和升级。在桥接服务的实现上项目选择了Node.js。这是一个合理的选择因为它轻量、异步IO模型适合处理网络代理请求并且生态丰富。对于SearXNG项目示例使用了Podman容器部署这也是目前最主流、最便捷的方式能很好地解决依赖和环境一致性问题。3. 分步部署与核心配置详解理论说完了我们进入实战环节。我会假设你拥有两台Linux主机物理机或虚拟机均可并具备基本的命令行操作和编辑配置文件的能力。3.1 阶段一搭建SearXNG搜索实例首先在你的“搜索主机”上操作。1. 准备工作目录与配置# 创建一个专用用户和目录可选但推荐用于权限隔离 sudo useradd -m -s /bin/bash searxng sudo su - searxng mkdir -p ~/searxng cd ~/searxng2. 生成关键的settings.yml配置文件这是SearXNG的核心配置文件。项目提供了一个极简版本但为了长期稳定运行我建议进行一些增强。创建一个settings.yml文件# 使用默认设置作为基础 use_default_settings: true server: # 绑定地址设为0.0.0.0以接受来自本机桥接服务的请求 bind_address: 127.0.0.1 # 必须修改使用一个强密钥以下命令生成openssl rand -hex 32 secret_key: 你的32位以上十六进制密钥 # 限制器关闭因为我们是内部服务无需防爬虫 limiter: false # 启用JSON格式输出这是桥接服务需要的 formats: - json - html search: # 安全搜索过滤器设为0关闭避免结果被过滤 safe_search: 0 # 每个请求的最大结果数可以调高 max_results: 20 # 搜索引擎超时时间秒 timeout: 5.0 # 日志配置方便排查问题 logging: level: INFO关键提示secret_key绝对不能使用默认的ultrasecretkey。请务必使用openssl rand -hex 32或项目提供的Python脚本生成一个随机字符串。这是SearXNG的安全基石。3. 使用Podman启动SearXNG容器Podman是一个无需守护进程的容器运行时比Docker更轻量。确保已安装podman。# 退出searxng用户环境如果还在的话 exit # 使用root或具有sudo权限的用户操作 sudo podman run -d --name searxng \ --restartalways \ -p 127.0.0.1:8888:8080 \ -v /home/searxng/searxng/settings.yml:/etc/searxng/settings.yml:Z \ docker.io/searxng/searxng:latest这里有一个重要细节-p 127.0.0.1:8888:8080将容器端口8080映射到宿主机的127.0.0.1:8888。这意味着SearXNG服务只对本机可见外部网络无法直接访问增加了安全性。桥接服务作为本机进程可以通过127.0.0.1:8888访问它。4. 验证SearXNG运行状态curl -s http://127.0.0.1:8888/search?qtestformatjson | jq .results[0].title 2/dev/null || echo 请安装jq工具或直接查看原始JSON输出如果返回了包含“test”相关结果的JSON对象说明SearXNG运行正常。如果失败检查Podman容器日志sudo podman logs searxng。常见错误是settings.yml格式错误YAML对缩进极其敏感或者secret_key未更改。3.2 阶段二部署OpenClaw-SearXNG桥接服务桥接服务是本次改造的核心枢纽它运行在搜索主机上。1. 获取并准备桥接服务代码假设我们在/opt目录下操作sudo mkdir -p /opt/openclaw-bridge sudo chown $USER:$USER /opt/openclaw-bridge cd /opt/openclaw-bridge # 假设你已经通过git clone或下载zip包获得了项目代码 # 项目结构应包含 bridge.js, package.json 等文件2. 安装Node.js依赖并测试运行确保你的Node.js版本在18以上推荐22。npm install # 设置环境变量并临时运行 PORT8899 SEARXNG_BASEhttp://127.0.0.1:8888 npm start如果看到服务启动在8899端口的日志说明基础运行成功。按CtrlC停止。3. 创建系统服务Systemd实现开机自启这是保证服务稳定性的关键步骤。创建服务文件/etc/systemd/system/searxng-bridge.service[Unit] DescriptionOpenClaw to SearXNG Bridge Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple # 指定运行用户建议使用非root用户如 searxng Usersearxng Groupsearxng # 设置工作目录和环境变量 WorkingDirectory/opt/openclaw-bridge EnvironmentPORT8899 EnvironmentSEARXNG_BASEhttp://127.0.0.1:8888 # 启动命令使用绝对路径的node ExecStart/usr/bin/node /opt/openclaw-bridge/bridge.js Restartalways RestartSec10 # 日志相关 StandardOutputjournal StandardErrorjournal SyslogIdentifiersearxng-bridge # 安全加固 NoNewPrivilegestrue ProtectSystemstrict ReadWritePaths/opt/openclaw-bridge PrivateTmptrue [Install] WantedBymulti-user.target注意User和Group需要根据你实际的用户设置修改。WorkingDirectory必须指向桥接服务代码所在的目录。SEARXNG_BASE环境变量必须与你的SearXNG实例地址一致。4. 启动并启用服务sudo systemctl daemon-reload sudo systemctl enable --now searxng-bridge sudo systemctl status searxng-bridge查看状态应为active (running)。你可以用之前的命令测试桥接服务是否正常工作curl http://127.0.0.1:8899/healthz # 应返回 OK curl http://127.0.0.1:8899/res/v1/web/search?qopenclaw | head -c 200第二个命令应该能返回从SearXNG获取的搜索结果摘要。3.3 阶段三配置OpenClaw并应用补丁现在转到运行OpenClaw Gateway的主机上操作。你需要知道搜索主机的IP地址假设为192.168.1.100。1. 配置OpenClaw的web_search工具编辑你的OpenClaw配置文件通常是openclaw.json或类似名称。找到tools.web.search部分确保其配置如下{ tools: { web: { search: { enabled: true, provider: brave, // 关键必须保持为 brave apiKey: dummy-key-required, // 关键某些版本需要非空值任意字符串即可 brave: { mode: web } } } } }这里的provider: brave是触发OpenClaw使用Brave API路径的关键。apiKey在某些OpenClaw构建版本中是必填的验证字段虽然我们的桥接服务会忽略它但填一个占位符可以避免OpenClaw因验证失败而拒绝发送请求。2. 获取并运行补丁脚本将openclaw-searxng-bridge项目中的scripts/patch-openclaw-searxng.sh脚本复制到OpenClaw主机上。你需要修改脚本中的一个关键点或者直接在运行时传入参数。首先查看你的OpenClaw安装目录。通常可执行文件或网关服务所在的目录下会有一个dist或build文件夹里面存放着编译后的前端资源JavaScript bundle文件。补丁脚本就是在这里面查找并替换硬编码的Brave API URL。运行脚本假设脚本已赋予执行权限chmod x patch-openclaw-searxng.sh# 假设搜索主机IP是 192.168.1.100桥接服务端口是默认的8899 ./patch-openclaw-searxng.sh 192.168.1.100脚本会执行以下操作备份dist目录例如dist_backup_20250415。递归查找dist目录下所有.js文件。将文件中所有匹配https://api.search.brave.com/res/v1/web/search的字符串替换为http://192.168.1.100:8899/res/v1/web/search。输出替换了多少处匹配。尝试重启OpenClaw网关服务如果检测到systemd服务名为openclaw或openclaw-gateway。3. 验证补丁是否生效补丁完成后重启OpenClaw网关服务如果脚本没有自动完成sudo systemctl restart openclaw-gateway # 请根据你的实际服务名调整然后通过OpenClaw的Web界面或API触发一个web_search。同时在搜索主机上监控桥接服务的日志sudo journalctl -u searxng-bridge -f --since 1 min ago如果你看到类似GET /res/v1/web/search?q...的访问日志并且返回了200状态码那么恭喜你补丁成功流量已经导向了你的私有搜索桥接4. 深度排错与运维经验实录即使按照步骤操作也可能会遇到各种问题。下面是我在多次部署中遇到的典型问题及其解决方案。4.1 桥接服务启动失败或无法连接问题现象systemctl status searxng-bridge显示失败或curl http://localhost:8899/healthz无响应。排查步骤检查Node.js环境与依赖node --version # 确保 18 cd /opt/openclaw-bridge npm list # 查看依赖是否完整安装没有明显的ERROR有时npm install可能因为网络问题失败。可以删除node_modules和package-lock.json后重试。检查端口冲突sudo ss -tulpn | grep :8899如果8899端口已被其他进程占用修改bridge.js中的默认端口或systemd服务文件中的PORT环境变量。检查SearXNG连接 桥接服务启动时需要能访问SEARXNG_BASE。手动测试curl -v http://127.0.0.1:8888/healthz # SearXNG的健康检查端点如果有 curl -v http://127.0.0.1:8888/search?qtestformatjson如果SearXNG没响应检查Podman容器状态sudo podman ps查看日志sudo podman logs searxng。查看详细日志sudo journalctl -u searxng-bridge -n 50 --no-pager关注错误堆栈信息。常见错误包括环境变量未设置、配置文件路径错误、权限问题如服务用户无法读取工作目录等。4.2 补丁后OpenClaw仍调用原始Brave API问题现象OpenClaw执行搜索时桥接服务日志无任何请求记录但网络抓包显示请求发向了api.search.brave.com。原因与解决补丁未找到所有硬编码点OpenClaw的不同构建版本其代码打包和压缩方式可能不同硬编码的URL字符串可能以多种形式存在如分段字符串、编码后字符串。补丁脚本使用的是简单的字符串替换可能不全面。解决方案检查补丁脚本的输出看替换了多少处。如果为0说明没找到匹配项。你需要手动搜索dist目录下的文件grep -r api.search.brave.com /path/to/openclaw/dist/ --include*.js grep -r brave.com/res/v1 /path/to/openclaw/dist/ --include*.js找到具体的字符串后可以手动编辑文件替换或者修改补丁脚本的正则表达式以匹配找到的格式。浏览器或客户端缓存如果你通过Web界面测试浏览器可能缓存了旧的JavaScript文件。解决方案强制刷新浏览器缓存CtrlShiftR或使用无痕模式测试。OpenClaw服务未正确重启补丁修改的是磁盘文件需要重启OpenClaw进程才能加载新的代码。解决方案确认重启了正确的服务。有时可能不止一个相关进程如前端服务、后端网关。找到主服务并重启sudo systemctl list-units | grep -i openclaw sudo systemctl restart 正确的服务名4.3 SearXNG返回结果慢或超时问题现象OpenClaw搜索响应很慢桥接服务日志显示请求到SearXNG耗时很长或SearXNG日志显示上游引擎超时。分析与优化调整SearXNG配置编辑settings.yml重点关注以下参数search: timeout: 3.0 # 降低超时时间避免单个引擎拖死整个请求 max_redirects: 1 # 减少重定向次数 # 精简启用的搜索引擎。并非所有引擎都需要保留几个稳定快速的即可。 engines: - name: google engine: google shortcut: g timeout: 3.0 # 可以配置代理如果需要 # proxy: socks5://localhost:1080 - name: bing engine: bing shortcut: b timeout: 3.0 - name: duckduckgo engine: duckduckgo shortcut: d timeout: 3.0禁用一些不必要或速度慢的引擎可以显著提升响应速度。网络与DNS问题SearXNG需要访问外网上游引擎。确保搜索主机网络通畅DNS解析快速可靠。可以考虑在主机或容器内配置更优的DNS服务器如8.8.8.8,1.1.1.1。桥接服务超时设置默认的bridge.js可能没有设置下游请求超时。如果SearXNG挂起桥接也会一直等待。你可以修改bridge.js在向SearXNG发起请求时添加超时选项例如使用axios或node-fetch的timeout配置。4.4 安全加固要点项目文档提到了安全建议这里我再强调和补充几点防火墙规则在搜索主机上使用防火墙如ufw或firewalld严格限制端口访问。# 假设OpenClaw主机IP是 192.168.1.200 sudo ufw allow from 192.168.1.200 to any port 8899 proto tcp sudo ufw deny 8888/tcp # 禁止外部直接访问SearXNG管理端口 sudo ufw enable只允许OpenClaw主机访问桥接服务的8899端口。SearXNG的8888端口只允许本机127.0.0.1访问。服务运行权限切勿以root用户运行桥接服务或SearXNG容器。按照上文创建专用用户如searxng并分配最小必要权限。配置文件的秘密管理settings.yml中的secret_key以及任何可能的API密钥如果SearXNG引擎需要应妥善保管。可以考虑使用环境变量或密钥管理工具注入而不是明文写在配置文件中。定期更新关注SearXNG和Node.js依赖的安全更新。定期执行# 更新SearXNG容器 sudo podman pull docker.io/searxng/searxng:latest sudo podman stop searxng sudo podman rm searxng # 重新运行本文3.1节的podman run命令 # 更新桥接服务依赖 cd /opt/openclaw-bridge npm update sudo systemctl restart searxng-bridge5. 性能调优与高级玩法基础功能跑通后我们可以考虑让这套系统更强大、更贴合个人需求。5.1 为桥接服务添加结果缓存频繁搜索相同内容会重复消耗SearXNG和上游引擎的资源。为桥接服务添加一个简单的内存缓存可以极大提升响应速度并减少外部请求。这里提供一个修改bridge.js的思路// 在文件开头引入一个内存缓存例如使用 node-cache const NodeCache require(node-cache); const searchCache new NodeCache({ stdTTL: 600, checkperiod: 120 }); // 缓存10分钟 // 在处理 /res/v1/web/search 的路由函数中 async function handleSearch(req, res) { const query req.query.q; if (!query) { return res.status(400).json({ error: Missing query }); } // 1. 检查缓存 const cachedResult searchCache.get(query); if (cachedResult) { console.log(Cache hit for query: ${query}); return res.json(cachedResult); } // 2. 未命中缓存请求SearXNG try { const searxngResponse await axios.get(${searxngBase}/search, { params: { q: query, format: json }, timeout: 10000, }); const resultData searxngResponse.data; // 3. 可选对结果进行裁剪或格式化以更贴近Brave API的响应结构 const formattedResults resultData.results.slice(0, 10).map(r ({ title: r.title, url: r.url, description: r.content, // ... 其他可能需要的字段 })); const finalResponse { // 模拟Brave API的响应结构 web: { results: formattedResults } }; // 4. 存入缓存 searchCache.set(query, finalResponse); res.json(finalResponse); } catch (error) { console.error(Error fetching from SearXNG:, error.message); res.status(502).json({ error: Upstream search error }); } }注意这是一个简化示例。实际Brave API的响应结构可能更复杂需要你根据OpenClaw的预期格式进行调整。添加缓存后记得npm install node-cache。5.2 部署高可用SearXNG集群对于重度用户单个SearXNG实例可能成为瓶颈或单点故障。你可以部署多个SearXNG实例并在桥接服务中实现简单的负载均衡或故障转移。架构思路在搜索主机上使用Docker Compose或Kubernetes部署2-3个SearXNG容器实例每个实例使用不同的本地端口如8888, 8889, 8890。修改桥接服务维护一个可用的SearXNG实例地址列表。在handleSearch函数中随机选择一个实例或使用轮询方式发起请求。如果某个实例请求失败自动切换到列表中的下一个。这能提升系统的吞吐量和容错能力。桥接服务可以作为一个简单的负载均衡器。5.3 集成其他搜索源SearXNG本身支持众多引擎但你也可以让桥接服务不止于SearXNG。例如你可以让它同时查询SearXNG和一个本地的文档数据库如Elasticsearch然后将结果合并、去重、排序后返回给OpenClaw。这需要你修改桥接服务的逻辑使其成为一个“元搜索聚合器”。实现的关键在于理解OpenClaw的web_search工具期望的响应格式。你需要通过抓包或查看OpenClaw源码弄清楚它如何解析Brave API的返回结果然后让你的桥接服务模拟出相同的格式。6. 未来展望与维护建议目前这个桥接方案是一个优雅的“临时”解决方案。它的长期维护性取决于两个因素OpenClaw官方对SearXNG的支持正如项目Roadmap所言当OpenClaw原生集成SearXNG作为搜索提供商时这个桥接方案就可以光荣退役了。届时你只需要在OpenClaw配置中将provider从brave改为searxng并配置对应的地址和密钥即可。OpenClaw构建版本的变化如果未来OpenClaw的构建流程改变导致硬编码的API URL模式发生变化补丁脚本可能需要更新。给你的维护建议文档化你的部署详细记录你的SearXNG配置、桥接服务安装路径、补丁脚本位置、OpenClaw版本以及所有自定义修改。这会在未来升级或故障排查时拯救你。监控服务状态为searxng-bridge服务和SearXNG容器设置简单的监控比如使用systemctl状态检查或者一个定时curl健康检查的脚本失败时发送通知。定期测试搜索功能每隔一段时间手动触发一次OpenClaw的搜索确保整个链路依然畅通。自动化测试更好。关注上游更新订阅OpenClaw和SearXNG的发布动态。OpenClaw的大版本升级很可能需要你重新评估并应用补丁。这个项目展示了在现有生态中通过“适配层”解决兼容性问题的经典思路。它可能不是永久性的但它提供了当下就能实现的、完全自控的搜索能力。对于追求数据主权和隐私的Homelab玩家来说这种掌控感带来的满足远超过搭建过程中的那一点点折腾。