WorkBuddy2API-Hub 本地网络工具教程：为 Codex 实现本地 web_search 与 web

【免费下载链接】workbuddy2api-hub

WorkBuddy 国际国内多账号反代网关，支持 Codex / Claude Code / DSH与标准 OpenAI 客户端。

项目地址：https://gitcode.com/gh_mirrors/wo/workbuddy2api-hub

WorkBuddy2API-Hub是一个 WorkBuddy 国际/国内多账号反代网关，支持 Codex、Claude Code 与标准 OpenAI 客户端。它的「本地网络工具」功能可以让网关代跑 Codex 声明的web_search/web_fetch：在本地执行真实搜索与网页抓取，再把结果喂回模型，让 Codex 在 WorkBuddy 网关上真正拥有联网能力。本教程带你 3 分钟开启并理解它的工作原理与注意事项。

一、为什么需要"本地网络工具"？

Codex App 这类客户端在发起 Responses 请求时，会声明web_search/web_fetch这两个服务端工具，意思是"请你（服务端）帮模型搜网页"。

但 WorkBuddy 上游并没有对应的执行器——声明原样送上去，模型看到工具却没人执行，客户端最终只能收到一句unsupported call，等于白声明。

WorkBuddy2API-Hub 的解法是：网关自己当执行器。开启后，网关会把客户端的工具声明替换成自己的同名 function，拦下模型发起的调用，在本地真实执行搜索 / 抓取，再把结果作为工具响应喂回模型，整个过程对模型透明。相关实现见 wb_webtools.py，请求侧的拦截与回放逻辑在 wb_proxy.py 中。

💡 该功能默认关闭，关闭时声明原样透传，不会吞掉客户端自己的搜索工具——升级或不开启均无任何影响。

二、快速开启：设置页一键切换

开启步骤只有三步：

打开看板http://127.0.0.1:8788/，进入「设置」页；
下滑到「本地网络工具」区块（看板代码见 dashboard.html 中的setLocalWebTools区块）；
勾选「由网关代跑」→ 点「保存」。

设置项会写入accounts/settings.json的local_web_tools字段，重启不丢失；随时取消勾选即可恢复默认直通行为。

三、开启后发生了什么？工作原理拆解

🔄 一次带联网需求的对话，大致经历下面 5 步：

步骤	动作	说明
1	声明替换	网关检测到客户端声明了`web_search`/`web_fetch`，用 wb_webtools.py 的`install_tool_defs()`移除所有同名项，只装入网关自己的唯一一份定义，避免上游"看到两个同名工具"
2	本地执行	模型发起调用后，网关在 wb_webtools.py 的`execute()`里执行：搜索打搜索引擎，抓取打模型给出的 URL
3	结果喂回	搜索结果 / 页面文字作为工具响应送回，模型据此继续推理
4	卡片回放	搜索过程会以`web_search_call`卡片事件和`url_citation`引用回到 Codex 客户端，你能看到模型"搜了什么、引了哪些网页"
5	多轮代跑	模型想继续搜/抓取就再来一轮，最多代跑3 轮（`WB_MAX_WEB_ROUNDS`可调，上限 8）；最后一轮网关会收回工具声明，让模型自己用文字收尾，而不是把失败伪装成正常结束

多引擎搜索自动轮换

搜索后端全部免 API Key，引擎链默认按DuckDuckGo → Bing → Wikipedia → Stack Overflow → Google News顺序自动轮换（只用国际来源）：

常规引擎（DuckDuckGo / Bing）接手时对模型完全无感，结果格式与平常一致；
换成 Wikipedia / Stack Overflow / Google News 这类非常规来源时，结果里会带上Source: ...标明出处，并提示模型告知用户；
某家引擎被限流（HTTP 202 / 403 / 429 或反爬页）时进入冷却（默认 600 秒），不会重复挨打；
全部引擎都不可用才返回web search is temporarily unavailable并附各家原因，要求模型不要重试同一句、直接告知用户——绝不把失败伪装成"查无结果"。

web_fetch同样做了硬化：只收文本型内容（PDF 等二进制直接回可读错误）、支持 gzip、单页读取上限 4 MB、自动推断字符集、结果进缓存（默认 TTL 600 秒）。

四、安全与额度：开启前必须知道的两件事

🔒安全边界：

URL 守卫先做字面检查，再解析 DNS 核对每个地址都是公网（防 DNS rebinding 把抓取指进内网）；字面私网地址与解析进内网的域名都会被挡；
重定向指向内网时同样拦截；
抓取失败永远返回一句可读的错误给模型，不伪造结果。

💰额度消耗：

开启后每轮代跑都会多跑一次上游请求，多消耗该账号的额度——重度联网对话会明显多花 token；
网关会主动出网抓取模型给出的 URL；如果你的出口受限，可以用环境变量WB_WEB_TOOLS_PROXY给这组工具单独指定出口代理，不影响账号主链路。

五、进阶调参：环境变量一览

全部参数通过环境变量覆盖，默认值已经比较保守，一般无需改动：

环境变量	默认	作用
`WB_MAX_WEB_ROUNDS`	3	单次请求最多代跑几轮（上限 8）
`WB_WEB_ENGINES`	全链	自定义引擎链与顺序，逗号分隔，如`duckduckgo,bing`
`WB_WEB_COOLDOWN`	600 秒	被限流引擎的冷却秒数（0 = 不冷却）
`WB_WEB_CACHE_TTL`	600 秒	搜索/抓取缓存秒数（0 = 关闭）
`WB_WEB_MIN_INTERVAL`	0.5 秒	对外请求最小间隔，防止一轮打穿所有引擎
`WB_WEB_BUDGET`	25 秒	单次搜索所有引擎的总预算
`WB_WEB_TOOLS_PROXY`	无	仅这组工具专用的出口代理`http(s)://[user:pass@]host:port`

参数定义见 wb_webtools.py 的模块头注释。

六、效果验证与排错

开启后如何确认它在正常工作？

看板日志：搜索/轮换/失败分类都会以tag=webtools写进运行日志页，能看到"哪台引擎接了手、哪台进冷却"；
请求流水：数据看板最近请求里可以看到对应的上游轮次增加；
客户端侧：Codex 中会出现web_search_call搜索卡片与来源引用，答案末尾的引用链接即来自本地搜索结果；
回归测试：整条链路的契约测试在 tests/_test_local_web_tools.py，改过本地实现后可以先跑它再重启网关。

常见情况速查：

现象	原因与处理
搜索总说"暂时不可用"	出口 IP 被引擎限流，等冷却期或设置`WB_WEB_ENGINES`调整引擎顺序
结果标了`Source: Wikipedia`之类	常规引擎当时不可用、由备用引擎接手，属正常轮换，出处已如实标明
答案没有引用链接	模型本轮未实际调用工具，或你关掉了开关（关闭时透传，上游不执行）
想立刻恢复原状	设置页取消勾选「由网关代跑」并保存即可，无需重启

七、小结

只需在「设置 → 本地网络工具」勾选「由网关代跑」，Codex 在 WorkBuddy2API-Hub 上就拥有了真实的web_search/web_fetch能力；
网关用免 Key 的多引擎轮换搜索 + 带内网防护的网页抓取本地执行，结果以卡片与引用形式回到客户端；
记住两点权衡：每轮代跑多消耗一次上游额度、网关会主动出网——按需开启、配合WB_MAX_WEB_ROUNDS与WB_WEB_TOOLS_PROXY调好边界，即可放心使用。

更多背景可阅读 README.md 的「本地网络工具（可选，默认关闭）」一节，功能演进记录见 docs/CHANGELOG.md。