1. OpenClaw 局域网发现失败Bonjour 广播收不到怎么排查同一台路由器下面Gateway 已经跑起来了客户端却死活扫不到节点日志里只有一行discovery timeout。这个场景我遇到过不止一次问题往往不在 OpenClaw 本身而在 Bonjour也就是 mDNS / DNS-SD这条零配置发现链路上。Bonjour 是什么一句话它让局域网设备不用手填 IP靠多播就能互相报名字、报端口。OpenClaw 的 Gateway 启动时会往_openclaw._tcp.local这个服务类型上广播自己客户端发查询、收响应、拿到192.168.x.x:18789再自动连。适合谁适合把 OpenClaw 部署在办公室、家庭 NAS、树莓派上希望多台机器免配置接入的人。但“开箱即用”有个前提多播流量得真的能过去。UDP 5353 被防火墙拦、设备跨了子网、Linux 没装 avahi-daemon、Windows 没装 Bonjour 服务任意一条中招发现就失败。这篇我按“先确认广播、再确认查询、最后接 TaoToken 统一通道”的顺序走一遍给你能直接复制的 config.toml 骨架和 CC Switch 片段最后做一次可复现的发现验证。核心检索词先记住OpenClaw Bonjour 发现失败排查配合 avahi-daemon 和 mDNS 一起用。先说清楚 Bonjour 在 OpenClaw 里的默认行为。Gateway 启动即注册服务服务类型_openclaw._tcp.local端口 18789TXT 记录里带version1.0、namegateway-name、channelschannel-count。客户端侧不需要你写 IP它发 mDNS Query 搜这个服务类型Gateway 回 Response客户端解析出地址和端口后自动连接。整条链路里任何一环断了表现都是“发现不到 Gateway”但原因完全不同。所以排查不能瞎试要分层定位先看广播在不在再看查询能不能收到响应最后才怀疑配置。我一般先跑openclaw config get gateway.discovery.bonjour看当前状态确认enabled是不是 true、serviceType有没有被改坏。很多人排查半天结果是之前为了“安全”把 Bonjour 关了或者 serviceName 改成了带空格和特殊字符导致广播异常。确认配置没问题再上网络层工具。下面几节按平台给命令Linux 用 avahimacOS 用 dns-sdWindows 用 Bonjour Print Services 自带的工具。每一步都有预期输出对不上就说明卡在这一层。2. TaoToken 前置统一 Key 与 API 通道准备在动手排查发现之前先把 TaoToken 这条统一通道准备好因为后面 config.toml 和 CC Switch 都要填 Base URL、Key、Model ID 三件套。TaoToken 是什么它是一个统一的模型 API 接入通道你拿一个 Key就能在 OpenClaw、CC Switch、Cline 这些工具里走同一套地址不用每个工具单独配一家。适合谁适合同时用多个编码/Agent 工具、不想反复换 Key 的人。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里就写干净的。第一步去控制台建 Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 登录后在 API Keys 页面新建一个复制出来先存好。这个 Key 就是后面 config.toml 里的api_key也是 CC Switch 里的ANTHROPIC_AUTH_TOKEN或对应字段。别把它贴到公开仓库本地配置文件记得加进 .gitignore。第二步确认你要用的 Model ID。不同工具对模型名的写法略有差异但走 TaoToken 统一通道时Model ID 按文档里给的写就行。文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各工具的接入示例。我建议先把 Model ID 抄到便签上因为 config.toml 和 CC Switch 两处都要用写错一个字符就是 404 或 model not found。第三步想清楚你要走哪条路。如果你只是想让 OpenClaw 的 Gateway 能调模型那 config.toml 里配好 Base URL Key Model ID 就够。如果你还要在 Claude Code 这类编码工具里用那就顺手把 CC Switch 也配了两者共用同一个 Key省得管理多份。长期跑编码和 Agent 任务的话可以了解下 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 按需选就行这里不展开价格。准备动作就这些一个 Key、一个 Model ID、一个 Base URLhttps://taotoken.net/api。三件套齐了下面进配置环节。记住发现排查和 API 接入是两条独立的链路Bonjour 管的是“客户端能不能找到 Gateway”TaoToken 管的是“Gateway 找到之后能不能调通模型”。两条都通整个流程才算闭环。3. 可复制配置config.toml 骨架与 CC Switch 片段这一节给能直接抄的配置。先看 OpenClaw 的 config.toml 骨架。路径按你实际安装位置来Linux 常见在~/.config/openclaw/config.tomlmacOS 在~/Library/Application Support/openclaw/config.tomlWindows 在%APPDATA%\openclaw\config.toml。下面这段把 Bonjour 发现和 TaoToken 通道放在一起字段名和原文一致[gateway] port 18789 [gateway.discovery.bonjour] enabled true serviceName OpenClaw Gateway serviceType _openclaw._tcp [gateway.discovery.bonjour.txtRecords] description My Gateway version 1.0 [model] provider taotoken base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model_id 你的ModelID几个点说明一下。serviceName在同一局域网有多个 Gateway 时必须区分开比如改成Office Gateway、Lab Gateway否则客户端会看到重名连错节点。serviceType保持_openclaw._tcp不要动改了客户端就搜不到。txtRecords是自定义元数据description随便写version建议保留1.0有些客户端会校验。model 段里的base_url写https://taotoken.net/api不要带末尾斜杠也不要带 UTM 参数。改完配置用命令行确认避免手滑openclaw config get gateway.discovery.bonjour openclaw config set gateway.discovery.bonjour.serviceName Office Gateway第二条是自定义服务名的写法多个 Gateway 场景用得上。如果你在公共网络、不希望被别的设备发现可以关掉openclaw config set gateway.discovery.bonjour.enabled false再说 CC Switch 的配置片段。CC Switch 用来在多个编码工具间切换供应商走 TaoToken 时填三件套。它的配置文件一般是 JSON路径在~/.cc-switch/config.json或应用内设置里直接填。片段如下{ providers: [ { name: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: 你的ModelID } ] }如果你用的是 Claude Code 那套环境变量方式对应写export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoTokenKey export ANTHROPIC_MODEL你的ModelID注意 Base URL、Key、Model ID 三件套在 config.toml、CC Switch、环境变量里必须一致尤其是 Model ID大小写和连字符都不能错。我踩过的坑就是 Model ID 少写了一个版本后缀结果请求返回 model not found排查了半天以为是网络问题。配置改完记得重启 Gateway让 Bonjour 重新注册服务。4. 验证请求一次可复现的 Bonjour 发现动作配置好了现在做一次可复现的发现验证。分平台给命令你按自己的系统选。先确认 Gateway 在跑然后开一个终端看广播。Linux 用 avahi 工具链先确保装好sudo apt install avahi-daemon avahi-utils sudo systemctl enable avahi-daemon sudo systemctl start avahi-daemon然后浏览服务avahi-browse -rt _openclaw._tcp预期输出里能看到服务名、hostname、address、port 和 txt。类似 eth0 IPv4 OpenClaw Gateway _openclaw._tcp local hostname [my-server.local] address [192.168.1.10] port [18789] txt [version1.0 channels3]macOS 用系统自带的 dns-sddns-sd -B _openclaw._tcp local输出会列出实例名按 CtrlC 退出。想进一步解析地址和端口用dns-sd -L OpenClaw Gateway _openclaw._tcp localWindows 需要先装 Bonjour Print Services装完用dns-sd.exe -B _openclaw._tcp local命令和 macOS 一致。如果 Windows 上命令找不到说明 Bonjour 服务没装好回去装一遍。看到广播之后验证客户端能不能自动发现。在另一台同局域网的机器上启动 OpenClaw 客户端观察它是否自动列出 Gateway。如果客户端有openclaw discover之类的子命令直接跑openclaw discover --timeout 5预期在 5 秒内返回发现的节点列表包含 IP 和端口。这一步成功说明 Bonjour 链路通了。接着验证 TaoToken 通道用 curl 打一次模型接口curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的TaoTokenKey返回模型列表就说明 Key 和 Base URL 没问题。如果这一步 401问题在 Key如果连不上问题在网络或 Base URL 写错。两条链路都验证过整个接入才算完成。发现验证建议每次改完网络配置都跑一遍因为防火墙规则、子网变动都会影响 mDNS。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth发现和接入过程中报错就那么几类对照着查最快。401 UnauthorizedTaoToken Key 错了、过期了或者请求头格式不对。检查Authorization: Bearer sk-xxx里 Bearer 后面有没有空格Key 有没有复制漏字符。CC Switch 里如果填的是apiKey字段确认没有多余引号。还有一种情况是 Base URL 写成了带路径的https://taotoken.net/api/v1而工具自己会拼/v1导致路径重复。统一写https://taotoken.net/api。local proxy failed本地代理起不来常见于 CC Switch 或 Cline 这类需要本地转发端口的工具。检查端口有没有被占用换个端口重试。另外确认没有残留的旧进程占着端口lsof -i :端口号看一下。这个报错和 Bonjour 无关是 API 通道层的问题。reading choices 相关报错一般是响应体解析失败说明请求发出去了但返回格式不对。常见原因是 Model ID 写错或者 Base URL 指向了不兼容的端点。核对 Model ID 和文档一致确认走的是 TaoToken 统一通道而不是别的地址。如果返回的是 HTML 而不是 JSON多半是 Base URL 写错打到了网页。OAuth 相关报错某些工具默认走 OAuth 登录流程但你用的是 Key 方式两者冲突。检查工具配置里有没有强制 OAuth 的开关关掉它改用 Key。Claude Code 环境下确认ANTHROPIC_AUTH_TOKEN设对了而不是走交互式登录。发现不到 Gateway回到 Bonjour 层。先avahi-browse -rt _openclaw._tcp看广播在不在。不在就查 Gateway 是否启动、enabled是否 true。在但客户端搜不到查防火墙 UDP 5353sudo ufw allow 5353/udp跨子网的情况 mDNS 默认不过路由器需要确保设备在同一网段。多个 Gateway 同名就连错改serviceName区分。Windows 发现不了先确认 Bonjour Print Services 装了。排查顺序建议先 Bonjour 广播再客户端查询最后 API 通道。别一上来就怀疑 Key很多时候是发现层就没通。每改一项配置就重启 Gateway 并重跑验证命令避免多个变量混在一起。6. 接入文档与后续动作发现验证通过、TaoToken 通道打通之后日常使用就顺了。后续如果要换模型或加工具回控制台建新 Key 或调整 Model ID 即可Base URL 不变。接入细节和更多工具示例看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要新建或轮换 Key 去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先在网页里试模型对话用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期跑编码和 Agent 任务看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留个实用习惯把avahi-browse -rt _openclaw._tcp和curl -s https://taotoken.net/api/v1/models -H Authorization: Bearer $KEY存成两个小脚本网络一变就跑一遍三十秒定位问题在哪一层。Bonjour 发现和 API 通道分开验证比混在一起猜快得多。