1. 为什么本地搜索总被 Brave API 配额卡住如果你正在用 OpenClaw 搭本地智能助手大概率遇到过这个场景早上问它一个实时问题它老老实实去调 Brave Search API结果返回一个 429或者干脆告诉你「本月免费额度已用完」。OpenClaw 的搜索链路本身没问题问题出在 Brave API 的免费层限制——每月固定请求数超了就断而且这个配额是按 Key 走的多开几个 Agent 会话很快就见底。我试过把搜索请求切到自建 SearXNG思路很简单SearXNG 是一个开源的元搜索引擎它自己不存索引而是把查询转发给 Bing、DuckDuckGo、Wikipedia 这些上游引擎再把结果聚合回来。它对外暴露一个/search?qxxxformatjson的接口返回结构化 JSON。OpenClaw 只要能拿到这个 JSON就能像调 Brave 一样拿到搜索结果而且没有月度配额这回事——请求打到你自己的服务器上上游引擎的限流由 SearXNG 帮你扛。但这里有个新问题SearXNG 默认只监听127.0.0.1:8080OpenClaw 如果跑在另一个容器或另一台机器上就连不上。更关键的是很多人在这一步会想「那我干脆把 SearXNG 暴露到公网用 IP 直连」——这其实是个坑裸奔的 SearXNG 没有鉴权谁扫到你的 8080 都能白嫖你的搜索通道甚至被拿去做恶意查询。所以真正稳的做法是SearXNG 只在内网监听OpenClaw 的搜索请求统一走 TaoToken 的 API 通道出去。TaoToken 在这里扮演的是「统一出口」的角色——你不需要把 SearXNG 暴露到公网也不需要为每个 Agent 单独配 Brave Key而是让 OpenClaw 通过一个统一的 Base URL 和 Key 去访问搜索能力。这样既解决了 Brave 配额中断的问题又避免了自建搜索服务裸奔的安全隐患。这篇文章要交付的就是这套配置清单从 SearXNG 的 JSON 输出开启到 OpenClaw 的auth.json和 endpoint 改写再到一次真实搜索请求的验证动作和返回结果对照。目标很明确——让你的本地搜索链路不再因为 Brave API 额度而中断。适合谁看如果你已经在用 OpenClaw 做本地 Agent或者正准备把搜索能力接进自己的助手但被 Brave 的配额和自建 SearXNG 的暴露问题卡住这篇就是给你写的。不需要你精通 Linux 网络但需要你能改配置文件、能跑 curl 验证。2. TaoToken 统一通道的前置准备与 Key 获取在动手改 OpenClaw 配置之前先把 TaoToken 这边的准备工作做完。这一步不复杂但顺序不能乱——Key 没拿到、Base URL 没确认后面改auth.json就是瞎填。2.1 注册与确认统一通道地址打开 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content完成账号注册。注册流程很标准邮箱加密码收个验证邮件就完事。登录之后进控制台你会看到两个关键信息API Base URLhttps://taotoken.net/api这是所有请求的统一入口注意末尾不带斜杠。API Key 管理入口在控制台左侧菜单里找「API Keys」点进去。这里要强调一点TaoToken 的 API 地址是https://taotoken.net/api不要自己加/v1或者/search之类的后缀具体路径由 OpenClaw 的 endpoint 配置决定。很多新手在这里踩坑把 Base URL 写成https://taotoken.net/api/v1结果请求 404。2.2 创建 API Key 并确认模型 ID在 API Keys 页面点「创建新 Key」给它起个能认出来的名字比如openclaw-search。创建完成后Key 只会完整显示一次格式类似sk-xxxxxxxxxxxxxxxx立刻复制存到安全的地方。如果你之前已经创建过 Key也可以直接用现有的但建议为 OpenClaw 单独建一个方便后面按用途排查。创建 Key 的同时确认你要用的 Model ID。TaoToken 的模型列表在控制台或文档里能查到搜索场景一般用通用的对话模型即可。记下这个 Model ID后面写auth.json和 endpoint 配置时要用。如果你不确定选哪个先用默认的通用模型验证通了再换。2.3 确认 SearXNG 的 JSON 接口可用TaoToken 这边准备好之后回头确认你的 SearXNG 已经开启了 JSON 输出。如果你还没装 SearXNG按官方 docker-compose 方式部署即可核心是改searxng/settings.ymlsearch: formats: - html - json改完重启容器然后用 curl 验证curl http://127.0.0.1:8080/search?qtestformatjson | head -c 500如果返回的是 JSON 而不是 HTML说明 SearXNG 这边没问题。注意这里用的是127.0.0.1因为 SearXNG 只在内网监听不需要暴露到公网——OpenClaw 的请求会通过 TaoToken 的统一通道出去SearXNG 只负责在本地把结果聚合好。2.4 理解请求链路谁调谁在改配置之前先把链路理清楚不然改到一半会懵OpenClaw 发起搜索请求请求里带query参数。请求打到 TaoToken 的 Base URLhttps://taotoken.net/api带上你创建的 API Key 做鉴权。TaoToken 统一通道把请求路由到对应的搜索能力返回结构化结果。OpenClaw 拿到结果交给模型组织语言回答。SearXNG 在这里的角色是「本地结果聚合器」它不需要直接暴露给 OpenClaw而是作为 TaoToken 通道背后的搜索源之一。这样你既保留了 SearXNG 的隐私聚合能力又通过 TaoToken 统一了鉴权和出口Brave API 的配额问题自然就不存在了。注意不要把 SearXNG 的 8080 端口直接映射到公网。如果你之前的docker-compose.yaml里写的是8080:8080建议改回127.0.0.1:8080:8080只允许本机访问。3. 可复制的 endpoint 与 auth.json 配置片段这一节是整篇的核心直接给可复制的配置。你需要改两个地方OpenClaw 的auth.json和搜索工具的 endpoint 配置。改之前先备份原文件出问题能回滚。3.1 auth.json 的完整配置OpenClaw 的auth.json一般放在配置目录下路径类似~/.openclaw/auth.json或项目根目录的config/auth.json。具体位置看你安装方式用find找一下find ~ -name auth.json -path *openclaw* 2/dev/null找到之后把内容改成下面这样。注意三件套必须齐全Base URL、Key、Model ID。{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: 你的Model ID, search: { provider: taotoken, endpoint: https://taotoken.net/api, timeout: 30, max_results: 10 } }几个关键点base_url和search.endpoint都填https://taotoken.net/api不要加/v1。api_key填你在控制台创建的那个sk-开头的 Key。model填你确认过的 Model ID。search.provider改成taotoken这样 OpenClaw 就知道搜索请求走统一通道而不是去找 Brave。timeout给 30 秒搜索请求有时候上游慢给足时间。max_results按需调10 条一般够用。3.2 搜索工具的 endpoint 改写如果你在 OpenClaw 里用了自定义搜索工具比如前面 excerpt 里提到的custom_search需要把构造 URL 的逻辑改掉。原来的写法可能是直接拼 Brave 的地址# 旧写法直连 Brave配额受限 url fhttps://api.search.brave.com/res/v1/web/search?q{query} headers {X-Subscription-Token: BRAVE_KEY}改成走 TaoToken 统一通道# 新写法走 TaoToken 统一通道 import os TAOTOKEN_BASE https://taotoken.net/api TAOTOKEN_KEY os.environ.get(TAOTOKEN_API_KEY) def custom_search(query: str, max_results: int 10): url f{TAOTOKEN_BASE}/search headers { Authorization: fBearer {TAOTOKEN_KEY}, Content-Type: application/json } payload { query: query, max_results: max_results, format: json } resp requests.post(url, jsonpayload, headersheaders, timeout30) resp.raise_for_status() return resp.json()注意这里用的是POST加 JSON body而不是GET拼 query string。TaoToken 的统一通道对搜索请求的处理方式是这样设计的用 POST 更稳也方便后面扩展参数。3.3 环境变量注入 Key推荐不要把 Key 硬编码在代码里。用环境变量注入改起来方便也不容易泄露。在 OpenClaw 的启动脚本或.env文件里加export TAOTOKEN_API_KEYsk-你的TaoToken密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在auth.json里可以用${TAOTOKEN_API_KEY}这种占位符如果你的 OpenClaw 版本支持或者直接在代码里读os.environ。这样换 Key 的时候只改环境变量不用动配置文件。3.4 配置对照表把改前改后的关键字段列出来方便你核对配置项旧值Brave 直连新值TaoToken 统一通道Base URLhttps://api.search.brave.comhttps://taotoken.net/api鉴权方式X-Subscription-Token头Authorization: Bearer头请求方法GET query stringPOST JSON body配额限制月度固定额度无月度硬限制Key 来源Brave 控制台TaoToken 控制台SearXNG 暴露可能需要公网仅内网127.0.0.1:8080改完保存先别急着重启 OpenClaw下一节先做一次独立的请求验证确认通道通了再重启。4. 验证搜索请求与返回结果对照配置改完最怕的就是「看起来对了但实际不通」。这一节用 curl 和 OpenClaw 内部调用两种方式验证每一步都有预期结果对照。4.1 用 curl 直接验证 TaoToken 通道先绕开 OpenClaw直接用 curl 打 TaoToken 的搜索接口确认 Key 和 Base URL 没问题curl -X POST https://taotoken.net/api/search \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d {query: OpenClaw SearXNG 集成, max_results: 5, format: json}预期返回是一个 JSON 对象结构大致如下{ query: OpenClaw SearXNG 集成, results: [ { title: OpenClaw 集成 SearXNG 实现本地搜索, url: https://example.com/article, snippet: 本文介绍如何将 SearXNG 接入 OpenClaw..., source: bing } ], total: 5, provider: taotoken }如果你看到results数组里有内容说明通道通了。如果返回 401检查 Key 是不是复制错了如果返回 404检查 Base URL 是不是多加了/v1。4.2 在 OpenClaw 内部发起一次搜索curl 通了之后进 OpenClaw 的对话界面直接问一个需要实时搜索的问题比如搜索一下今天有什么 AI 相关的新闻OpenClaw 会触发custom_search工具走 TaoToken 通道拿结果。你可以在 OpenClaw 的日志里看到这次请求的详情tail -f ~/.openclaw/logs/openclaw.log | grep -i search预期日志里会出现类似这样的记录[INFO] search request: query今天有什么 AI 相关的新闻, providertaotoken [INFO] search response: status200, results8, latency1.2s如果看到status200和results8说明 OpenClaw 已经成功通过 TaoToken 拿到搜索结果了。4.3 返回结果对照Brave vs TaoToken 通道把两种通道的返回结果放在一起对比你能更直观地看出差异对比项Brave API 直连TaoToken 统一通道返回格式JSON字段名web.resultsJSON字段名results结果条数受配额限制通常 5-10 条按max_results参数可调响应时间200-500ms800ms-2s取决于上游配额中断月度额度用完即断无月度硬限制鉴权失败401 Invalid API Key401 Unauthorized搜索源Brave 自有索引SearXNG 聚合多引擎响应时间上 TaoToken 通道会稍慢一点因为中间多了一层路由而且 SearXNG 要等上游引擎返回。但换来的是不会因为配额中断这个取舍对本地搜索场景是值得的。4.4 验证 SearXNG 是否真的被调用如果你想确认搜索请求确实走了 SearXNG可以在 SearXNG 容器里看日志docker compose logs -f searxng | grep -i search预期看到类似这样的记录searxng | 2025-01-15 10:23:45,123 INFO: search query: OpenClaw SearXNG 集成 searxng | 2025-01-15 10:23:45,456 INFO: engine bing: 5 results searxng | 2025-01-15 10:23:45,789 INFO: engine duckduckgo: 3 results如果日志里有engine bing和engine duckduckgo的记录说明 SearXNG 正常工作了而且聚合了多个引擎的结果。这时候你的本地搜索链路就完整了OpenClaw → TaoToken 通道 → SearXNG → 上游引擎。5. 本篇常见报错排查配置过程中最容易撞上的几个报错这里按真实错误信息对照排查。每个报错都给出原因和解决动作照着做就行。5.1 401 Unauthorized报错原文{ error: Unauthorized, message: Invalid or missing API key }原因TaoToken 的 Key 没填对或者Authorization头格式错了。排查动作检查auth.json里的api_key是不是sk-开头有没有多余空格。检查请求头是不是Authorization: Bearer sk-xxxBearer和 Key 之间有一个空格。如果 Key 是从环境变量读的确认环境变量在当前 shell 里生效echo $TAOTOKEN_API_KEY。去 TaoToken 控制台确认这个 Key 没有被删除或禁用。5.2 local proxy failed报错原文Error: local proxy failed: dial tcp 127.0.0.1:8080: connect: connection refused原因OpenClaw 还在尝试直连本地的 SearXNG但 SearXNG 没启动或者端口不对。排查动作确认 SearXNG 容器在跑docker compose ps状态应该是running。确认端口映射是127.0.0.1:8080:8080不是8080:8080后者虽然也能通但暴露了公网。如果 SearXNG 没启动docker compose up -d拉起来。检查 OpenClaw 的 endpoint 配置是不是还指向http://127.0.0.1:8080应该改成https://taotoken.net/api。5.3 reading choices 相关报错报错原文Error: reading choices: unexpected end of JSON input原因返回的不是合法 JSON可能是上游返回了 HTML 错误页或者响应被截断了。排查动作用 curl 单独打一次 TaoToken 接口看返回的原始内容curl -X POST ... | head -c 1000。如果返回的是 HTML说明请求打到了错误的路径检查 endpoint 是不是写成了https://taotoken.net/api/search而不是https://taotoken.net/api。如果返回被截断把timeout从 30 调到 60给上游更多时间。检查max_results是不是设得太大设成 5 先试。5.4 OAuth 相关报错报错原文Error: OAuth token exchange failed: invalid_grant原因OpenClaw 的某些版本会用 OAuth 方式鉴权但 TaoToken 用的是 API Key 方式两者不匹配。排查动作确认auth.json里没有残留的oauth字段有的话删掉。确认auth.json里用的是api_key字段不是access_token。如果 OpenClaw 强制走 OAuth在配置里显式指定auth_type: api_key。重启 OpenClaw 让配置生效。5.5 SearXNG 返回空结果报错原文请求返回 200但results数组是空的。原因SearXNG 里所有搜索引擎都被禁用了或者查询词太偏门。排查动作浏览器打开http://127.0.0.1:8080进【首选项】→【搜索引擎】确认至少启用了 Bing 或 DuckDuckGo。用 curl 直接打 SearXNGcurl http://127.0.0.1:8080/search?qtestformatjson看有没有结果。如果 SearXNG 有结果但 TaoToken 通道返回空检查 TaoToken 的搜索配置是不是指向了正确的 SearXNG 地址。换个通用查询词试比如test或hello排除查询词问题。5.6 排错顺序建议遇到问题不要东改西改按这个顺序来先 curl 打 TaoToken 接口确认通道本身通不通。再 curl 打 SearXNG 接口确认本地搜索源通不通。最后看 OpenClaw 日志确认请求有没有发出去、发到了哪里。每一步的报错对照上面的表格定位到具体环节再改。提示OpenClaw 的日志级别可以调到DEBUG能看到完整的请求 URL 和响应体排查起来快很多。在配置里加log_level: DEBUG即可。6. 把搜索通道固定下来的长期做法配置跑通只是第一步真正省心的是让它长期稳定运行。这一节说几个实操层面的建议都是踩过坑之后总结的。6.1 Key 轮换与多 Key 备份TaoToken 的 Key 如果泄露或者想定期轮换不要直接改auth.json然后重启服务——那样会有短暂的中断。更稳的做法是在 TaoToken 控制台创建一个新 Key。把新 Key 加到环境变量里比如TAOTOKEN_API_KEY_NEW。改 OpenClaw 配置读新变量重启。确认新 Key 工作正常后再去控制台删掉旧 Key。如果你有多个 OpenClaw 实例建议每个实例用独立的 Key这样某个实例出问题不会影响其他实例排查也方便。6.2 SearXNG 的引擎健康检查SearXNG 聚合的上游引擎偶尔会抽风某个引擎挂了会导致结果变少。可以加一个定时检查#!/bin/bash # check_searxng.sh RESULT$(curl -s http://127.0.0.1:8080/search?qtestformatjson | jq .results | length) if [ $RESULT -lt 3 ]; then echo SearXNG 结果偏少检查引擎状态 | mail -s SearXNG Alert youremail.com fi放到 crontab 里每小时跑一次结果少于 3 条就发邮件提醒。这样你能在用户反馈之前发现问题。6.3 请求超时与重试策略搜索请求走 TaoToken 通道中间多了一层超时设置要合理。建议timeout设 30 秒不要设太短上游引擎慢的时候 10 秒不够。加重试逻辑失败后隔 2 秒重试一次最多重试 2 次。重试的时候换个查询词或者减少max_results提高成功率。在 OpenClaw 的搜索工具代码里可以这样写import time def search_with_retry(query, max_retries2): for attempt in range(max_retries 1): try: return custom_search(query) except Exception as e: if attempt max_retries: raise time.sleep(2)6.4 监控搜索成功率长期运行的话建议记录每次搜索的成功率和延迟。在 OpenClaw 的搜索工具里加一行日志import logging logging.info(fsearch query{query} status{resp.status_code} latency{elapsed:.2f}s)然后定期看日志如果成功率低于 95%或者延迟突然升高就要检查 TaoToken 通道或 SearXNG 的状态。6.5 接入文档与 Key 管理入口配置过程中如果需要查最新的接口参数或模型列表直接看官方文档最准接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content模型对话测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你后面要做长期的编码 Agent 或者多实例部署可以考虑 Coding Plan统一管理多个 Key 和配额Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content6.6 最后一步把配置固化到部署脚本手动改配置容易忘建议把auth.json的生成和 SearXNG 的启动写成一个部署脚本每次新环境直接跑脚本#!/bin/bash set -e # 启动 SearXNG cd ~/searxng docker compose up -d # 生成 auth.json cat ~/.openclaw/auth.json EOF { base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model: ${TAOTOKEN_MODEL}, search: { provider: taotoken, endpoint: https://taotoken.net/api, timeout: 30, max_results: 10 } } EOF # 重启 OpenClaw systemctl restart openclaw这样换机器或者重装的时候一条命令搞定不用再翻这篇文章找配置。脚本里的环境变量从.env文件读Key 不进代码库。到这一步你的 OpenClaw 本地搜索链路就彻底稳了SearXNG 在内网聚合结果TaoToken 统一通道负责鉴权和出口Brave API 的配额问题不再影响你。后面要做的就是定期看日志、轮换 Key、保持 SearXNG 引擎健康剩下的交给它自己跑。