1. OpenClaw 跨平台部署到底卡在哪OpenClaw 是一个支持工具调用的 AI Agent 框架你可以把它理解成一个「能自己动手干活」的助手不只是聊天还能调用搜索、读写文件、执行命令。SearXNG 则是一个自托管的元搜索引擎把多个上游搜索源的结果聚合在一起不追踪用户、不需要商业 API Key。把这两者通过 MCPModel Context Protocol接起来本地跑的 OpenClaw 就能获得实时联网搜索能力而且搜索通道完全免费、数据不出自己的机器。听起来很美好但真正动手时Windows 和 macOS 的坑完全不一样。Windows 上 npm 编译原生模块经常报错路径里的反斜杠和空格会让 MCP 子进程启动失败macOS 上 Apple Silicon 和 Intel 的二进制差异、zsh 的 PATH 加载顺序、Node 版本过低导致的 spawn EINVAL每一个都能让你卡半小时。更麻烦的是SearXNG 默认关闭 JSON 输出很多人配好了 MCP 却发现搜索工具返回 400其实是 settings.yml 里少了一行 formats。这篇教程面向在 Windows 10/11 和 macOS 上从零部署 OpenClaw、并接入 SearXNG 免费搜索的开发者。我会给出可直接复制的 config.toml 与 settings.json 骨架、SearXng 实例地址的填写位置以及启动后验证搜索与模型调用是否生效的具体动作。模型调用通道统一走 TaoToken这样你不需要在多个平台之间来回切换 Key一个 API 通道就能覆盖 OpenClaw 的模型请求。2. 前置准备TaoToken 统一 Key 与 API 通道在开始装 OpenClaw 之前先把模型调用的通道准备好。OpenClaw 本身不绑定任何模型供应商它通过 OpenAI 兼容接口发请求所以你需要一个稳定的 Base URL 和 API Key。TaoToken 提供的就是这个统一通道一个 Key 可以调用多种模型接口格式与 OpenAI 兼容OpenClaw 的 onboard 流程里直接选 OpenAI Compatible 就能接上。先到 TaoToken 控制台创建一个 API Key。登录后进入 console 页面在 API Keys 菜单里新建一个 Key复制保存好后面配置里要用。如果你还没决定用哪个模型可以先去模型对话页面试几个确认工具调用function calling能力正常再写进配置——这一点很关键不支持工具调用的模型即使 MCP 注册成功也不会去调搜索。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 填入。OpenClaw 的配置里需要的是完整的/v1路径所以实际填https://taotoken.net/api/v1。API Key 放在请求头的 Authorization 字段格式是Bearer sk-xxxx。如果你打算长期跑编码类 Agent 任务可以了解一下 Coding Plan它针对高频调用场景做了额度优化只是偶尔验证模型效果的话模型对话页面就够用了。接入文档里有完整的接口说明和错误码对照遇到 401/429 先查文档比瞎试快得多。注意TaoToken 是合规的 API 聚合通道不是灰色中转。所有请求走标准 HTTPSKey 只在你本地配置文件和请求头里出现不要提交到 Git 仓库。3. 可复制配置config.toml 与 settings.json 骨架这一节给出两个核心配置文件的完整骨架。OpenClaw 的配置在~/.openclaw/openclaw.jsonWindows 是C:\Users\你的用户名\.openclaw\openclaw.jsonSearXNG 的配置在安装目录下的settings.yml。下面分别给出可直接复制的版本你只需要替换路径和 Key。3.1 OpenClaw 的 openclaw.json 骨架这个文件同时包含模型供应商配置和 MCP 服务器配置。模型部分指向 TaoTokenMCP 部分指向本地的 searxng-mcp 服务。{ models: { providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api/v1, apiKey: sk-你的TaoToken密钥, models: [gpt-4o-mini, claude-3-5-sonnet] } }, default: taotoken/gpt-4o-mini }, plugins: { allow: [openclaw-mcp-adapter], entries: { mcp-adapter: { enabled: true, config: { servers: [ { name: searxng, transport: stdio, command: node, args: [/绝对路径/到/searxng-mcp/server.js], env: { SEARXNG_BASE: http://localhost:8888 } } ], toolPrefix: true } } } }, tools: { allow: [*] } }Windows 用户注意args里的路径必须用双反斜杠转义比如D:\\tools\\searxng-mcp\\server.js。macOS 用户用正斜杠比如/Users/你的用户名/tools/searxng-mcp/server.js。SEARXNG_BASE的端口要和你实际启动的 SearXNG 实例一致默认 8888。3.2 SearXNG 的 settings.yml 关键片段SearXNG 默认只输出 HTMLMCP 服务器需要 JSON 格式。找到settings.yml里的search段改成下面这样search: safe_search: 0 autocomplete: default_lang: zh-CN formats: - html - jsonformats里必须包含json否则/search?qtestformatjson会返回 403。如果你用的是 Docker 部署需要把自定义的 settings.yml 挂载进去命令类似-v /你的路径/settings.yml:/etc/searxng/settings.yml。simplexng 部署的话配置文件在~/.config/simplexng/simplexng_settings.yml改法一样。3.3 环境变量与启动顺序三个服务有依赖关系启动顺序不能乱先起 SearXNG确认 8888 端口能返回 JSON再起 searxng-mcp确认 node server.js 不报错最后重启 OpenClaw gateway让它加载 MCP 配置。如果你把顺序搞反了OpenClaw 启动时连不上 MCP 子进程工具就不会注册。# 1. 启动 SearXNG以 simplexng 为例 simplexng --open # 2. 另开终端测试 JSON 接口 curl http://localhost:8888/search?qtestformatjson # 3. 启动 searxng-mcp cd ~/tools/searxng-mcp node server.js # 4. 重启 OpenClaw 网关 openclaw gateway restart4. 验证请求搜索与模型调用是否生效配置写完不代表能用必须做两步验证先确认 SearXNG 的 JSON 接口正常再确认 OpenClaw 成功注册了搜索工具最后发一条真实指令看 AI 会不会调用。4.1 验证 SearXNG JSON 接口在浏览器或 curl 里访问http://localhost:8888/search?qOpenClawformatjson。正常返回应该是一个 JSON 对象包含results数组每个结果有title、url、content字段。如果返回 HTML 页面或者 403说明formats没配好回去检查 settings.yml。如果返回空 results说明上游搜索引擎不可达需要在 SearXNG 的 Web 界面「首选项」里手动启用 Bing、Baidu 等可访问的引擎。4.2 验证 MCP 工具注册重启 OpenClaw 网关后观察启动日志。你应该能看到类似这样的输出[mcp-adapter] searxng: found 1 tools [mcp-adapter] Registered: searxng_searxng_search如果只看到found 0 tools说明 searxng-mcp 的 server.js 路径写错了或者 node 进程启动失败。可以手动跑node server.js看报错。如果日志里完全没有 mcp-adapter 相关行检查plugins.allow里有没有openclaw-mcp-adapter以及entries里的enabled是不是 true。4.3 验证模型调用与工具触发在 OpenClaw 的聊天框里输入一条明确要求使用搜索的指令使用 searxng_searxng_search 工具搜索「OpenClaw MCP 配置」返回前三条结果的标题和链接。如果模型支持工具调用且配置正确你会看到它先输出一段「正在调用搜索工具」的提示然后返回搜索结果。同时 OpenClaw 的网关日志里会出现工具调用记录。如果模型只是用自然语言回答而没有真正调用工具说明当前模型不支持 function calling换一个支持工具调用的模型再试。提示验证模型调用是否走 TaoToken可以在 TaoToken 控制台的请求日志里看。每次 OpenClaw 发请求console 的用量页面都会有记录包括模型名、token 数和时间戳。如果日志里没有记录说明 Base URL 或 Key 填错了。5. 本篇常见错排查部署过程中最容易踩的坑集中在路径、版本和引擎可用性三块。下面按报错现象分类给出原因和解决动作。5.1 Windows 下 npm 安装 OpenClaw 失败报错通常是node-gyp编译失败或者MSBuild.exe找不到。原因是缺少 C 编译工具链。解决方法是安装 Visual Studio Build Tools安装时勾选「使用 C 的桌面开发」工作负载。装完后以管理员身份打开 PowerShell重新执行npm install -g openclawlatest。如果还是失败先npm cache clean --force再重试。5.2 macOS 下 spawn EINVAL 错误这个错误通常出现在 Node 版本过低或者路径里有空格时。OpenClaw 要求 Node.js 22.12.0 或更高先用node --version确认。如果版本够但还是报错检查args里的路径有没有空格——macOS 的Application Support这类目录名带空格MCP 子进程启动时会解析失败。把 searxng-mcp 放到~/tools/这种无空格路径下即可。5.3 SearXNG 返回 400 或 403先确认formatjson能返回 JSON 而不是 HTML 错误页。如果 settings.yml 里已经加了 json 还是 403检查文件缩进——YAML 对缩进敏感formats必须和search同级缩进两个空格。Docker 部署的话确认挂载的配置文件路径正确容器内实际读取的是你改过的那个文件。5.4 工具已注册但 AI 不调用三个可能原因模型不支持工具调用、tools.allow没放开、提示词不够明确。先确认模型支持 function callingqwen3:8b、gpt-4o-mini、claude-3-5-sonnet 都支持。然后执行openclaw config set tools.allow [*]放开所有工具。最后在指令里显式写出工具名比如「使用 searxng_searxng_search 工具搜索……」强制模型走工具通道。5.5 搜索返回空结果SearXNG 本身不产生搜索结果它只是聚合上游引擎。如果所有上游都不可达results 就是空的。打开http://localhost:8888进入「首选项」在引擎列表里手动勾选 Bing、Baidu 等可访问的引擎保存后再测。另外default_lang设成zh-CN对中文搜索更友好。6. 接入与排障从 API Key 到 Coding Plan配置跑通之后日常使用中如果遇到模型调用报错优先检查三处TaoToken 的 API Key 是否过期、Base URL 是否写成https://taotoken.net/api/v1、请求日志里有没有 401/429。401 是 Key 无效429 是频率超限接入文档里有完整的错误码说明和重试建议。如果你只是偶尔验证模型效果模型对话页面可以直接测试工具调用是否正常不用每次都启动 OpenClaw。如果你打算把 OpenClaw 当作长期编码助手或 Agent 运行环境Coding Plan 的额度模型更适合高频场景配合 MCP 搜索工具可以覆盖查文档、找报错、读源码这类日常任务。最后提醒一个实操细节OpenClaw 的配置文件修改后必须重启 gateway 才生效openclaw gateway restart比重新登录更省事。SearXNG 的 settings.yml 改完也要重启服务simplexng 直接 CtrlC 再simplexng --open即可。把这两个重启动作记牢能省掉一半「改了没反应」的困惑。
OpenClaw 跨平台部署与 SearXng 免费搜索配置教程（Windows/macOS）
1. OpenClaw 跨平台部署到底卡在哪OpenClaw 是一个支持工具调用的 AI Agent 框架你可以把它理解成一个「能自己动手干活」的助手不只是聊天还能调用搜索、读写文件、执行命令。SearXNG 则是一个自托管的元搜索引擎把多个上游搜索源的结果聚合在一起不追踪用户、不需要商业 API Key。把这两者通过 MCPModel Context Protocol接起来本地跑的 OpenClaw 就能获得实时联网搜索能力而且搜索通道完全免费、数据不出自己的机器。听起来很美好但真正动手时Windows 和 macOS 的坑完全不一样。Windows 上 npm 编译原生模块经常报错路径里的反斜杠和空格会让 MCP 子进程启动失败macOS 上 Apple Silicon 和 Intel 的二进制差异、zsh 的 PATH 加载顺序、Node 版本过低导致的 spawn EINVAL每一个都能让你卡半小时。更麻烦的是SearXNG 默认关闭 JSON 输出很多人配好了 MCP 却发现搜索工具返回 400其实是 settings.yml 里少了一行 formats。这篇教程面向在 Windows 10/11 和 macOS 上从零部署 OpenClaw、并接入 SearXNG 免费搜索的开发者。我会给出可直接复制的 config.toml 与 settings.json 骨架、SearXng 实例地址的填写位置以及启动后验证搜索与模型调用是否生效的具体动作。模型调用通道统一走 TaoToken这样你不需要在多个平台之间来回切换 Key一个 API 通道就能覆盖 OpenClaw 的模型请求。2. 前置准备TaoToken 统一 Key 与 API 通道在开始装 OpenClaw 之前先把模型调用的通道准备好。OpenClaw 本身不绑定任何模型供应商它通过 OpenAI 兼容接口发请求所以你需要一个稳定的 Base URL 和 API Key。TaoToken 提供的就是这个统一通道一个 Key 可以调用多种模型接口格式与 OpenAI 兼容OpenClaw 的 onboard 流程里直接选 OpenAI Compatible 就能接上。先到 TaoToken 控制台创建一个 API Key。登录后进入 console 页面在 API Keys 菜单里新建一个 Key复制保存好后面配置里要用。如果你还没决定用哪个模型可以先去模型对话页面试几个确认工具调用function calling能力正常再写进配置——这一点很关键不支持工具调用的模型即使 MCP 注册成功也不会去调搜索。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 填入。OpenClaw 的配置里需要的是完整的/v1路径所以实际填https://taotoken.net/api/v1。API Key 放在请求头的 Authorization 字段格式是Bearer sk-xxxx。如果你打算长期跑编码类 Agent 任务可以了解一下 Coding Plan它针对高频调用场景做了额度优化只是偶尔验证模型效果的话模型对话页面就够用了。接入文档里有完整的接口说明和错误码对照遇到 401/429 先查文档比瞎试快得多。注意TaoToken 是合规的 API 聚合通道不是灰色中转。所有请求走标准 HTTPSKey 只在你本地配置文件和请求头里出现不要提交到 Git 仓库。3. 可复制配置config.toml 与 settings.json 骨架这一节给出两个核心配置文件的完整骨架。OpenClaw 的配置在~/.openclaw/openclaw.jsonWindows 是C:\Users\你的用户名\.openclaw\openclaw.jsonSearXNG 的配置在安装目录下的settings.yml。下面分别给出可直接复制的版本你只需要替换路径和 Key。3.1 OpenClaw 的 openclaw.json 骨架这个文件同时包含模型供应商配置和 MCP 服务器配置。模型部分指向 TaoTokenMCP 部分指向本地的 searxng-mcp 服务。{ models: { providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api/v1, apiKey: sk-你的TaoToken密钥, models: [gpt-4o-mini, claude-3-5-sonnet] } }, default: taotoken/gpt-4o-mini }, plugins: { allow: [openclaw-mcp-adapter], entries: { mcp-adapter: { enabled: true, config: { servers: [ { name: searxng, transport: stdio, command: node, args: [/绝对路径/到/searxng-mcp/server.js], env: { SEARXNG_BASE: http://localhost:8888 } } ], toolPrefix: true } } } }, tools: { allow: [*] } }Windows 用户注意args里的路径必须用双反斜杠转义比如D:\\tools\\searxng-mcp\\server.js。macOS 用户用正斜杠比如/Users/你的用户名/tools/searxng-mcp/server.js。SEARXNG_BASE的端口要和你实际启动的 SearXNG 实例一致默认 8888。3.2 SearXNG 的 settings.yml 关键片段SearXNG 默认只输出 HTMLMCP 服务器需要 JSON 格式。找到settings.yml里的search段改成下面这样search: safe_search: 0 autocomplete: default_lang: zh-CN formats: - html - jsonformats里必须包含json否则/search?qtestformatjson会返回 403。如果你用的是 Docker 部署需要把自定义的 settings.yml 挂载进去命令类似-v /你的路径/settings.yml:/etc/searxng/settings.yml。simplexng 部署的话配置文件在~/.config/simplexng/simplexng_settings.yml改法一样。3.3 环境变量与启动顺序三个服务有依赖关系启动顺序不能乱先起 SearXNG确认 8888 端口能返回 JSON再起 searxng-mcp确认 node server.js 不报错最后重启 OpenClaw gateway让它加载 MCP 配置。如果你把顺序搞反了OpenClaw 启动时连不上 MCP 子进程工具就不会注册。# 1. 启动 SearXNG以 simplexng 为例 simplexng --open # 2. 另开终端测试 JSON 接口 curl http://localhost:8888/search?qtestformatjson # 3. 启动 searxng-mcp cd ~/tools/searxng-mcp node server.js # 4. 重启 OpenClaw 网关 openclaw gateway restart4. 验证请求搜索与模型调用是否生效配置写完不代表能用必须做两步验证先确认 SearXNG 的 JSON 接口正常再确认 OpenClaw 成功注册了搜索工具最后发一条真实指令看 AI 会不会调用。4.1 验证 SearXNG JSON 接口在浏览器或 curl 里访问http://localhost:8888/search?qOpenClawformatjson。正常返回应该是一个 JSON 对象包含results数组每个结果有title、url、content字段。如果返回 HTML 页面或者 403说明formats没配好回去检查 settings.yml。如果返回空 results说明上游搜索引擎不可达需要在 SearXNG 的 Web 界面「首选项」里手动启用 Bing、Baidu 等可访问的引擎。4.2 验证 MCP 工具注册重启 OpenClaw 网关后观察启动日志。你应该能看到类似这样的输出[mcp-adapter] searxng: found 1 tools [mcp-adapter] Registered: searxng_searxng_search如果只看到found 0 tools说明 searxng-mcp 的 server.js 路径写错了或者 node 进程启动失败。可以手动跑node server.js看报错。如果日志里完全没有 mcp-adapter 相关行检查plugins.allow里有没有openclaw-mcp-adapter以及entries里的enabled是不是 true。4.3 验证模型调用与工具触发在 OpenClaw 的聊天框里输入一条明确要求使用搜索的指令使用 searxng_searxng_search 工具搜索「OpenClaw MCP 配置」返回前三条结果的标题和链接。如果模型支持工具调用且配置正确你会看到它先输出一段「正在调用搜索工具」的提示然后返回搜索结果。同时 OpenClaw 的网关日志里会出现工具调用记录。如果模型只是用自然语言回答而没有真正调用工具说明当前模型不支持 function calling换一个支持工具调用的模型再试。提示验证模型调用是否走 TaoToken可以在 TaoToken 控制台的请求日志里看。每次 OpenClaw 发请求console 的用量页面都会有记录包括模型名、token 数和时间戳。如果日志里没有记录说明 Base URL 或 Key 填错了。5. 本篇常见错排查部署过程中最容易踩的坑集中在路径、版本和引擎可用性三块。下面按报错现象分类给出原因和解决动作。5.1 Windows 下 npm 安装 OpenClaw 失败报错通常是node-gyp编译失败或者MSBuild.exe找不到。原因是缺少 C 编译工具链。解决方法是安装 Visual Studio Build Tools安装时勾选「使用 C 的桌面开发」工作负载。装完后以管理员身份打开 PowerShell重新执行npm install -g openclawlatest。如果还是失败先npm cache clean --force再重试。5.2 macOS 下 spawn EINVAL 错误这个错误通常出现在 Node 版本过低或者路径里有空格时。OpenClaw 要求 Node.js 22.12.0 或更高先用node --version确认。如果版本够但还是报错检查args里的路径有没有空格——macOS 的Application Support这类目录名带空格MCP 子进程启动时会解析失败。把 searxng-mcp 放到~/tools/这种无空格路径下即可。5.3 SearXNG 返回 400 或 403先确认formatjson能返回 JSON 而不是 HTML 错误页。如果 settings.yml 里已经加了 json 还是 403检查文件缩进——YAML 对缩进敏感formats必须和search同级缩进两个空格。Docker 部署的话确认挂载的配置文件路径正确容器内实际读取的是你改过的那个文件。5.4 工具已注册但 AI 不调用三个可能原因模型不支持工具调用、tools.allow没放开、提示词不够明确。先确认模型支持 function callingqwen3:8b、gpt-4o-mini、claude-3-5-sonnet 都支持。然后执行openclaw config set tools.allow [*]放开所有工具。最后在指令里显式写出工具名比如「使用 searxng_searxng_search 工具搜索……」强制模型走工具通道。5.5 搜索返回空结果SearXNG 本身不产生搜索结果它只是聚合上游引擎。如果所有上游都不可达results 就是空的。打开http://localhost:8888进入「首选项」在引擎列表里手动勾选 Bing、Baidu 等可访问的引擎保存后再测。另外default_lang设成zh-CN对中文搜索更友好。6. 接入与排障从 API Key 到 Coding Plan配置跑通之后日常使用中如果遇到模型调用报错优先检查三处TaoToken 的 API Key 是否过期、Base URL 是否写成https://taotoken.net/api/v1、请求日志里有没有 401/429。401 是 Key 无效429 是频率超限接入文档里有完整的错误码说明和重试建议。如果你只是偶尔验证模型效果模型对话页面可以直接测试工具调用是否正常不用每次都启动 OpenClaw。如果你打算把 OpenClaw 当作长期编码助手或 Agent 运行环境Coding Plan 的额度模型更适合高频场景配合 MCP 搜索工具可以覆盖查文档、找报错、读源码这类日常任务。最后提醒一个实操细节OpenClaw 的配置文件修改后必须重启 gateway 才生效openclaw gateway restart比重新登录更省事。SearXNG 的 settings.yml 改完也要重启服务simplexng 直接 CtrlC 再simplexng --open即可。把这两个重启动作记牢能省掉一半「改了没反应」的困惑。
