OpenAI Web Search 工具怎么用？

官方资料（2026-11-01 核对）：Web search guide · Responses create reference · API Pricing · Safety best practices

先选对搜索入口

最小示例：Responses API 启用 Web Search

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const response = await client.responses.create({
  model: "gpt-5.5",
  tools: [{ type: "web_search" }],
  input: "查找今天的 OpenAI API 官方更新，并给出可点击来源。"
});

console.log(response.output_text);

for (const item of response.output) {
  if (item.type === "web_search_call") {
    console.log(item.action);
  }
}

API Key 只能放在服务端。模型是否搜索取决于请求、模型和 tool_choice；因此不要把“配置了工具”等同于“本次一定查过网”。对时效性问题，业务层应检查是否出现 web_search_call，并保存搜索动作、请求 ID、模型和时间。

auto、required 与明确指定工具

• tool_choice:"auto"：模型可以搜索，也可以直接回答；适合无需每次联网的通用助手。
• tool_choice:"required"：要求调用某个工具；当唯一工具就是 Web Search 时，可用于强制查网。
• 明确指定 Web Search：工具较多且必须搜索时，指定该工具，减少模型选到其他工具的歧义。

const response = await client.responses.create({
  model: "gpt-5.5",
  tools: [{ type: "web_search" }],
  tool_choice: "required",
  input: "核对 OpenAI Pricing 当前 Web Search 工具价格并引用官方页面。"
});

强制搜索也不保证答案正确。若搜索失败、来源不足或相互矛盾，界面应显示“未能验证”并允许重试，不要静默回退成无来源的确定结论。

响应里有什么：动作、正文、引用与完整来源

const response = await client.responses.create({
  model: "gpt-5.5",
  tools: [{ type: "web_search" }],
  include: ["web_search_call.action.sources"],
  input: "比较最近两次 OpenAI API 价格更新，只使用官方来源。"
});

域名过滤：允许与排除名单

Responses API 的 web_search 当前可通过 filters 配置最多 100 个 allowed_domains 或最多 100 个 blocked_domains。域名不写协议和路径，例如写 openai.com 而不是 https://openai.com/docs；子域名也包含在匹配范围内。

const response = await client.responses.create({
  model: "gpt-5.5",
  tools: [{
    type: "web_search",
    filters: {
      allowed_domains: [
        "developers.openai.com",
        "openai.com"
      ]
    }
  }],
  include: ["web_search_call.action.sources"],
  input: "查找 Web Search 工具的最新官方接入规则。"
});

高风险事实优先用允许名单；开放探索可使用排除名单降低明显低质量来源，但不能替代来源评分。过滤只控制检索范围，不证明页面内容正确，也不能阻止被允许网页中的提示注入。

实时联网、缓存索引与地理位置

• 默认实时：省略 external_web_access 时，Responses 的 web_search 默认允许实时访问外部网页。
• 缓存模式：设为 false 时只使用离线或缓存索引；适合可重复评测，但不适合承诺“最新”。
• 预览差异：web_search_preview 会忽略 external_web_access，按允许实时访问处理。
• 位置：可提供近似 country、city、region、timezone 改善本地搜索；不要发送精确住址或不必要的个人信息。

tools: [{
  type: "web_search",
  external_web_access: true,
  user_location: {
    type: "approximate",
    country: "CN",
    timezone: "Asia/Shanghai"
  }
}]

若产品展示“截至某时”，请把实际检索时间写进结果。缓存模式、实时模式和模型回答时间不能混为一谈；第三方页面也可能在搜索后发生变更。

成本：工具调用、搜索内容 Token 和模型 Token

一次搜索的费用不只等于模型输出 Token。官方当前计费包含搜索动作的工具调用费用；搜索索引返回并送入模型的内容 Token 按所选模型规则计费，用户输入与模型输出也各自计费。某些模型/搜索组合还有固定搜索内容 Token 规则。

• 按每个 search action 统计工具调用，而不是只按 API 请求数。
• 记录模型、搜索动作数、search content tokens、输入/输出 Token、延迟和缓存/实时模式。
• return_token_budget:"unlimited" 仅在确实需要长研究时使用；它可能增加延迟和成本。
• 展示价格时不要在代码里永久写死，发布前重新读取官方 Pricing。

用量和预算基线见 OpenAI API Usage 指南；长研究任务的异步执行见 Background Mode 指南。

安全：网页内容是数据，不是可信指令

• 把搜索结果当成不可信输入；网页中的“忽略之前指令”“发送密钥”等文本不得改变系统或开发者规则。
• 网页不能直接授权付款、删除、发信、运行代码或修改账号；不可逆动作要通过独立权限、参数校验和人工审批。
• 不要把 API Key、Cookie、内部提示词、用户私密资料或其他凭据放入搜索查询。
• 对高风险结论优先官方/监管/原始来源，并至少进行多源交叉核对。
• 保留可点击引用、检索时间和来源快照标识；来源无法访问时标注，而不是伪造引用。
• 为域名、URL 协议、重定向、下载大小和内容类型设置限制，避免 SSRF 与资源消耗风险。

常见失败与排查顺序

上线前检查清单

1. 新集成使用 web_search，没有误把 preview 当成长期默认。
2. 已决定 auto、required 或明确工具选择，并验证实际出现 web_search_call。
3. annotations 的引用在界面中清晰可见且可点击；完整 sources 可审计。
4. allowed/blocked domains、实时联网、近似位置和隐私边界有明确配置。
5. 网页内容不会覆盖系统规则，也不能直接触发不可逆动作。
6. 请求日志不含密钥、Cookie、敏感查询或完整私密网页内容。
7. 已记录搜索动作数、Token、延迟、失败、来源质量和单位可用答案成本。
8. 价格、模型、控制项和限制均在上线当天重新核对官方文档。

常见问题

本文核对日期为 2026-11-01。模型、工具参数、搜索能力、价格、可用地区和数据控制会调整；生产上线前请重新读取官方 Web search、Responses Reference 与 Pricing。