何时必须自定义 web_search 提供方
默认集成适合验证流程；一旦涉及数据出境、发票封顶或安全部白名单，就需要把搜索迁到已评审的企业 API 或自建检索代理。自定义不是「换个 URL」，而是把身份、配额、观测与回滚写进运行手册，和 CI 密钥同级管理。
内网知识库优先复用带 ACL 的检索服务，保证模型片段与人工控制台一致；需有人维护索引与降级。模型重试会放大 QPS，常在 token 上限前撞 429：拆 key、限流并把搜索 QPS 与 CPU/内存同表。
可用性要覆盖公司正向代理、分屏 DNS、证书巡检。笔记本上 curl 成功不代表 systemd 服务账户同路径可用；必须在同一用户、同一环境文件、同一 cgroup复现。
运维上，Telegram 通道与搜索集成都应服从同一套分层排障，避免 wiki 各写一套。读完 网关运维 再改 JSON，可显著减少「doctor 绿但业务红」的玄学时间。
变更流程建议走代码评审：懂 SSRF 的 reviewer、CI 校验 JSON schema、发布窗口内冷重启并留快照，参考 升级与快照 的纪律。
痛点拆解
痛点 1：密钥散落。把 Bearer 明文写进同步盘里的 JSON，比 SSH 泄露更快。用环境变量间接引用，并设轮换节奏。
痛点 2：查询串 SSRF。若后端对命中结果无脑二次抓取，模型可控字符串即可变成内网探测。服务端必须再校验协议与主机。
痛点 3：doctor 盲区。doctor 解决本地一致性，不保证供应商 SLA；需金丝雀查询与外拨监控。
痛点 4：热重载≠子进程回收。与 MCP 文类似，改集成后倾向冷重启并观察子进程与句柄。
痛点 5：搜索当爬虫。批量网页抓取应走专用抓取通道（限速、缓存、robots），不要滥用 search 接口刷流量。
提供方选型决策矩阵
| 形态 | 优势 | 成本 | 安全要点 | 适用 |
|---|---|---|---|---|
| 商业 JSON API | 合规叙事快 | 按量计费与突发加价 | 密钥季度轮换、401 监控 | 已采购企业搜索的客户 |
| 内网检索代理 | ACL 一致 | 索引与工程债 | 禁 file:// 与元数据 SSRF | 强隔离文档库 |
| 自建聚合 | 单价可控 | 运维与硬件 | 管理面单独加固 | 实验室与专网 |
| 插件 shim | 可接老协议 | 多一个二进制补丁面 | 升级策略比照 MCP | 遗留 SOAP 等桥接 |
每环境一条主路径；大版本后复审字段，CI schema 校验提前拦截。
openclaw.json 配置骨架（示例）
{
"tools": {
"web": {
"search": {
"provider": "customHttp",
"baseUrl": "https://search.corp.example/api/v1/query",
"auth": {
"type": "bearer",
"tokenEnv": "CORP_SEARCH_TOKEN"
},
"timeoutMs": 12000,
"maxResults": 8,
"allowedHosts": ["search.corp.example"]
}
}
}
}
字段名以你所用版本为准；示例只描述结构。生产勿把令牌写进 argv 或截图可见处。
步骤 1 备份 JSON 并记录网关运行用户。步骤 2 部署 HTTP 服务并接好 mTLS/网络策略。步骤 3 应用配置、冷重启、执行 openclaw doctor。步骤 4 金丝雀查询，日志级别 info 且脱敏。步骤 5 打开延迟与 HTTP 码面板再全量放开自动化。
可量化指标：别让账单偷袭
按自动化与 key 统计 QPS，日限额 70% 软告警；重试曲线与搜索叠图防 backoff 风暴。p95 延迟单独看，DNS/TLS 问题常在尾部。摘要过大抬 token，可在代理截断。保留脱敏 curl 复现；季度与财务对账抓影子 key。
出站安全与 SSRF 同源思维
搜索是出站，但若后端跟链任意 URL，就与入站 Webhook 的 SSRF 面同源思考。对齐 生产加固文 的威胁模型，在配置层与防火墙双层限制目标主机，日志带自动化标识便于溯源。
生产与预发令牌物理隔离，baseUrl 也分离，减少复制粘贴事故。TLS 巡检代理根证书要装进服务账户信任库，不仅是管理员会话。
哪些自动化可无监督调用搜索、哪些必须走人机确认，应写成策略条款，与 HITL 文章同级的审批链。
与 MCP、网页抓取的分工
MCP 适合需要本地二进制或复杂工具链的场景，生命周期见 MCP 排障。web_search 应保持「薄 HTTP + 明确配额」。若把任意 URL 抓取叠进 search，会失去限速与合规边界。
变更后冷重启，再跑 doctor 与通道探针；TLS 边缘见 反向代理；安装漂移见 安装对比。建议阅读顺序：网关 → MCP → TLS → 本文 → SSRF。
术语表
tools.web.search：声明搜索 HTTP 集成的 JSON 子树（具体键名随发行版）。
自定义提供方：非默认演示后端的自管或合同 API。
金丝雀查询：固定语句用于发布后验证时延与鉴权。
冷重启：完整退出再拉起网关进程以清缓存状态。
doctor：本地配置/环境体检，不等于供应商监控。
出站策略：写明自动化可访问的主机、端口与代理要求。
429：速率限制，应配合退避与告警。
分屏 DNS：内外解析同名不同地址。
托管远程 Mac：SFTPMAC 提供的稳定 macOS 网关与构建入口组合。
FAQ 与为什么考虑 SFTPMAC 托管远程 Mac
搜索密钥能跟大模型供应商共用吗？
不建议。拆分便于轮换、计费归因与爆炸半径控制。
只在公司内网有索引怎么办？
与 SSH 同等信任路径接入 mesh/VPN，MTU 与 DNS 写进同一 runbook。
总结：自定义 web_search = 配置 + 出站安全 + 观测；把它当生产集成而非隐藏浏览器。
局限：自建网关要同时维护代理、密钥、磁盘与 Apple 侧构建环境；若希望在线性与目录隔离外包、团队专注交付，SFTPMAC 托管远程 Mac能把网关稳定与 SFTP/rsync 面打包成可运营服务。
需要稳定 macOS 网关与合规文件通道时，评估托管远程 Mac 资源池与套餐说明。