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 的 chat completions 图像 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 可以通过共享的 tools.media.audio 路径，使用其 STT 端点（/audio/transcriptions）转录入站语音/音频附件。这适用于任何会将入站语音/音频转发到媒体理解预检的渠道插件。

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "openrouter", model: "openai/whisper-large-v3-turbo" }],      },    },  },}

OpenClaw 会将 OpenRouter STT 请求作为 JSON 发送，并在 input_audio 下携带 base64 音频（OpenRouter STT 契约），而不是作为 multipart OpenAI 表单上传。

身份验证和标头

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

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

高级配置

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

相关