OpenRouter

OpenRouter 提供一个统一 API，可以通过单一端点和 API key 将请求路由到多个模型。它与 OpenAI 兼容，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。

# 入门指南

openclaw onboard --auth-choice openrouter-api-key

openclaw models set openrouter/<provider>/<model>

# 配置示例

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/auto" },
    },
  },
}

# 模型引用

内置回退示例：

# 图像生成

OpenRouter 也可以作为 image_generate 工具的后端。在 agents.defaults.imageGenerationModel 下使用 OpenRouter 图像模型：

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
        timeoutMs: 180_000,
      },
    },
  },
}

OpenClaw 会将图像请求发送到 OpenRouter 的聊天补全图像 API，并带上 modalities: ["image", "text"]。Gemini 图像模型会通过 OpenRouter 的 image_config 接收受支持的 aspectRatio 和 resolution 提示。对于较慢的 OpenRouter 图像模型，请使用 agents.defaults.imageGenerationModel.timeoutMs；image_generate 工具的单次调用 timeoutMs 参数仍然优先。

# 视频生成

OpenRouter 也可以通过其异步 /videos API 作为 video_generate 工具的后端。在 agents.defaults.videoGenerationModel 下使用 OpenRouter 视频模型：

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "openrouter/google/veo-3.1-fast",
      },
    },
  },
}

OpenClaw 会向 OpenRouter 提交文生视频和图生视频任务，轮询返回的 polling_url，并从 OpenRouter 的 unsigned_urls 或已记录的任务内容端点下载已完成的视频。参考图像默认会作为首帧/末帧图像发送；标记为 reference_image 的图像会作为 OpenRouter 输入引用发送。内置的 google/veo-3.1-fast 默认值声明当前支持 4/6/8 秒时长、720P/1080P 分辨率，以及 16:9/9:16 宽高比。OpenRouter 未注册视频到视频，因为上游视频生成 API 目前接受文本和图像引用。

# 文本转语音

OpenRouter 也可以通过其与 OpenAI 兼容的 /audio/speech 端点用作 TTS 提供商。

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          model: "hexgrad/kokoro-82m",
          voice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

如果省略 messages.tts.providers.openrouter.apiKey，TTS 会复用 models.providers.openrouter.apiKey，然后使用 OPENROUTER_API_KEY。

# 身份验证和标头

OpenRouter 底层使用带有你的 API key 的 Bearer token。

在真实的 OpenRouter 请求（https://openrouter.ai/api/v1）中，OpenClaw 还会添加 OpenRouter 文档中记录的应用归因标头：

# 高级配置

{
  agents: {
    defaults: {
      models: {
        "openrouter/auto": {
          params: {
            responseCache: true,
            responseCacheTtlSeconds: 300,
          },
        },
      },
    },
  },
}

# 相关内容