Server Tools 是 OpenRouter 运营的服务端工具，任何模型在一次请求中都可调用 0 到多次，执行完全由 OpenRouter 在服务端处理，无需客户端实现。与 Plugins（每次请求固定运行一次）和 User-Defined Tools（由客户端应用执行）不同，Server Tools 通过 tools 数组指定，类型前缀为 openrouter:。目前提供三种工具：Web Search（实时网页搜索）、Datetime（获取当前时间）、Image Generation（文本生成图片）。Server Tools 和自定义 function 工具可在同一请求中混合使用，usage 对象中记录 server_tool_use 统计。

Server Tools 是 OpenRouter 运营的服务端工具，任何模型在请求处理过程中都可以调用。OpenRouter 在服务端执行工具调用并将结果返回给模型，客户端无需实现任何额外逻辑。

Beta 提醒：Server Tools 目前处于 Beta 阶段，API 和行为可能会有变更。

Server Tools vs Plugins vs User-Defined Tools

	Server Tools	Plugins	User-Defined Tools
调用决策者	模型	始终运行	模型
执行者	OpenRouter	OpenRouter	你的应用
每次请求调用次数	0 到多次	固定一次	0 到多次
通过什么指定	tools 数组	plugins 数组	tools 数组
类型前缀	openrouter:*	不适用	function

• Server Tools：模型可以零次或多次调用，OpenRouter 透明执行
• Plugins：开启后每次请求自动运行一次（如 PDF 解析、响应修复）
• User-Defined Tools：标准函数调用工具，模型建议调用，你的应用执行

可用的 Server Tools

工具	类型	说明
Web Search	openrouter:web_search	搜索网页获取实时信息
Datetime	openrouter:datetime	获取当前日期和时间
Image Generation	openrouter:image_generation	根据文本描述生成图片

工作流程

1. 在 API 请求的 tools 数组中包含一个或多个 Server Tools
2. 模型根据用户的请求决定是否以及何时调用各工具
3. OpenRouter 拦截工具调用，在服务端执行，并将结果返回给模型
4. 模型利用结果生成最终回复，必要时可再次调用工具

快速开始

在 tools 数组中使用 openrouter: 类型前缀：

const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    messages: [
      {
        role: 'user',
        content: 'AI 领域最近有什么新进展？'
      }
    ],
    tools: [
      { type: 'openrouter:web_search' },
      { type: 'openrouter:datetime' }
    ]
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

与 User-Defined Tools 混合使用

Server Tools 和自定义 function 工具可以在同一请求中共存：

{
  "model": "openai/gpt-4o",
  "messages": [...],
  "tools": [
    { "type": "openrouter:web_search", "parameters": { "max_results": 3 } },
    { "type": "openrouter:datetime" },
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "获取股票当前价格",
        "parameters": {
          "type": "object",
          "properties": {
            "ticker": { "type": "string" }
          },
          "required": ["ticker"]
        }
      }
    }
  ]
}

模型可以调用任意组合的 Server Tools 和自定义工具。OpenRouter 自动执行 Server Tools，你的应用处理自定义工具调用。

用量追踪

Server Tool 用量记录在响应的 usage 对象中：

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 250,
    "server_tool_use": {
      "web_search_requests": 2
    }
  }
}

常见问题

Q: Server Tools 和我自己实现的 function 工具有什么区别？

A: Server Tools 由 OpenRouter 在服务端执行，模型调用后客户端无需做任何额外处理，一次 API 调用就能得到最终结果。User-Defined Tools 需要"多轮"交互：模型返回工具调用请求 → 你的应用执行 → 将结果附加到下一轮请求中。Server Tools 更简单，但功能固定；User-Defined Tools 灵活，可以接入任何自定义逻辑。

Q: 使用多个 Server Tools 时，模型会按什么顺序调用？

A: 模型自主决定调用顺序，可能并发调用也可能按需序列调用，取决于请求内容。你无法控制调用顺序，但可以通过系统提示影响模型的行为。

Q: Server Tools 的 Beta 状态意味着什么？

A: Beta 意味着 API 接口和行为可能还会调整，不保证向后兼容。建议在生产环境中谨慎使用，并关注 OpenRouter 的更新通知。一旦功能稳定，Beta 标记会移除。