如何给外部模型加联网搜索：Codex Router独立搜索与Perplexity侧车完整解析

如何给外部模型加联网搜索：Codex Router独立搜索与Perplexity侧车完整解析

【免费下载链接】codex-routerExternal-model router for Codex with guided Kimi OAuth/API, DeepSeek, safe migration, and rollback.项目地址: https://gitcode.com/gh_mirrors/co/codex-router

Codex Router是一个运行在本地的外部模型路由器，它让 Codex、Claude Code 等客户端在不换账号、不换工作流的前提下调用 DeepSeek、Kimi、MiMo 等外部模型。而外部模型最常见的短板就是"上不了网"——本文将完整解析 Codex Router 的三种联网搜索模式，以及怎么用Perplexity 搜索侧车（Search Sidecar）三步给指定模型加上独立搜索能力。

🤔 为什么外部模型需要联网搜索

把 Codex 接到外部模型后，模型默认只能基于训练数据和上下文回答，遇到"最新版本号""刚发布的新闻"这类实时问题就力不从心了。Codex Router 没有简单粗暴地"全员开通搜索"，而是提供了三种精度不同的方案：

💡 核心设计原则：路由永远不会因为某个模型是"OpenAI 兼容接口"就推断它支持搜索。每种能力都必须对应"精确的模型/供应商路由"经过验证后才会生效。

🔍 模式一：独立搜索（Standalone Web Search）

从 Codex 0.146 开始，客户端可以为自定义模型供应商自己执行联网搜索。外部模型只要在自己的元数据中声明"searchTool": { "mode": "standalone" }，合并后的模型目录就会对外广告这个搜索能力，搜索结果再随正常的路由轮次送回模型。

内置注册表中目前已在以下路由开启独立搜索：

• DeepSeek V4 Flash：直连 API 与 opencode Go 路由
• DeepSeek V4 Flash Vision Exp
• 小米 MiMo v2.5
• GLM-5.3（Z.ai Coding Plan 路由）

还有一个容易混淆的细节能帮你避坑：supportsSearchHistory是更窄的能力——它只表示该路由能回放历史中已完成的搜索调用，并不代表能发起新搜索。两者分开声明，避免了"能续聊 ≠ 能搜索"的误判。

如果 Codex 仍然向不支持的路由塞入托管搜索字段，路由器会在受管的 Responses 边界只剥掉这些搜索扩展，其余工具字段逐字节保留。这套边界逻辑见 src/search-capability.mjs。

🧩 模式二：Perplexity 搜索侧车是什么

侧车（Sidecar）是给"完全没有搜索能力"的路由模型准备的外挂搜索插件，它有三个关键特征：

1. 按精确模型绑定：不是全局开关，绑定必须写明完整的供应商/模型路由名，已有搜索能力的模型会被直接拒绝覆盖
2. 独立密钥：Perplexity API Key 单独存放在受保护的凭据文件中，与模型路由的密钥互不干扰
3. 本地拦截：Codex 的认证搜索请求由路由本地处理，永不回落到原生 ChatGPT 搜索后端；未绑定的模型保持原有行为

信任边界非常严格：供应商必须是启用状态、仅公网、openai-chat适配器、且 Base URL 恰好为https://api.perplexity.ai的通用供应商描述符，请求路径固定为/search。策略判定逻辑在 src/search-sidecar-policy.mjs。

🚀 三步给指定模型加联网搜索

以 macOS/Linux 为例，只需三条命令（Windows 版本见文末）：

第一步：添加 Perplexity 搜索供应商

./bin/model-router codex providers generic add perplexity-search \ --name "Perplexity Search" \ --base-url https://api.perplexity.ai \ --adapter openai-chat

第二步：在隐藏提示下输入 API 密钥

./bin/model-router codex providers generic credential perplexity-search set

注意：这条命令绝不接受把密钥当作命令行参数，密钥在隐藏终端提示中录入，避免进入 shell 历史记录。

第三步：绑定到你的模型并查看状态

./bin/model-router codex search-sidecar set PROVIDER/MODEL perplexity-search ./bin/model-router codex search-sidecar status PROVIDER/MODEL

把PROVIDER/MODEL换成你想加搜索的精确路由名（例如某个 DeepSeek 或 Kimi 路由）。status会输出ready: true/false以及具体问题列表，比如"模型未注册""凭据不可用"，是排查配置问题的第一站。

Windows 用户可通过codex-router.ps1执行同样的命令：

.\codex-router.ps1 search-sidecar set PROVIDER/MODEL perplexity-search

CLI 支持的动作还包括enable / disable / remove，以及调参选项--timeout-ms、--max-results、--cache-ttl-ms、--max-attempts、--retry-delay-ms等，默认值定义在 src/search-sidecar-state.mjs：超时 10 秒、最多返回 8 条结果、缓存 60 秒、最多重试 2 次。

🛡️ 侧车的安全设计：为什么可以放心用

侧车执行器 src/search-sidecar.mjs 里藏着不少值得新手了解的防护细节：

• 输入白名单：只接受 1~4 条search_query命令且仅含q字段，其他过滤器或 Web 命令按名称直接拒绝
• 出口锁定：搜索请求走 DNS 固定（pinning）、拒绝重定向的传输层，且只允许公共地址
• 引用净化：返回的结果 URL 必须通过公共 DNS 解析，解析到内网/链路本地地址即丢弃；携带凭据特征的 URL 和正文一律拒收
• 统一截止时间：整个操作（含重试与退避）共享同一个超时，不会因为重试把等待时间无限拉长
• 隐私缓存：缓存键按"调用方账号 + 模型 + 供应商 + 凭据引用"作用域划分；用量记录只保留状态、耗时、重试/缓存/结果计数，永不记录查询文本、引用内容和密钥

📊 验证与管理：状态、用量与清理

日常操作速查：

两条容易踩的运维要点：

1. 改完绑定后要完全退出并重新打开 Codex，模型目录才会刷新，搜索能力才会出现在客户端里
2. 删除通用供应商是级联操作：移除perplexity-search供应商会同时删除其凭据和所有依赖它的侧车绑定，清理时要心里有数

📚 相关文档与源码

想深入了解可以按顺序阅读：

• 工作原理与搜索边界说明：docs/HOW-IT-WORKS.md（"Standalone web search"与"Per-model search sidecar"两节）
• 快速上手与命令示例：README.md
• 侧车执行器源码：src/search-sidecar.mjs
• 绑定状态与默认参数：src/search-sidecar-state.mjs
• CLI 控制命令（status/set/enable/disable/remove）：src/search-sidecar-control.mjs
• 能力判定与搜索契约剥离：src/search-capability.mjs
• 独立入口脚本：bin/search-sidecar

一句话总结：有托管搜索用托管，模型本身验证过就用独立搜索，其余模型用 Perplexity 侧车按名绑定——三条路径互不越界，这正是 Codex Router 让外部模型"安全上网"的答案。

【免费下载链接】codex-routerExternal-model router for Codex with guided Kimi OAuth/API, DeepSeek, safe migration, and rollback.项目地址: https://gitcode.com/gh_mirrors/co/codex-router