OpenRouter

OpenRouter định tuyến các yêu cầu đến nhiều mô hình thông qua một API và một khóa duy nhất. Dịch vụ này tương thích với OpenAI, vì vậy OpenClaw giao tiếp với nó qua cùng phương thức truyền tải kiểu openai-completions được sử dụng cho các nhà cung cấp proxy khác.

Bắt đầu

openclaw onboard --auth-choice openrouter-oauth

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

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

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

Ví dụ cấu hình

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

Tham chiếu mô hình

Các mô hình dự phòng được đóng gói sẵn, dùng khi không thể khám phá danh mục trực tiếp:

Mọi tham chiếu openrouter/<provider>/<model> khác, bao gồm openrouter/openrouter/fusion (xem bộ định tuyến Fusion), đều được phân giải động dựa trên danh mục mô hình trực tiếp của OpenRouter.

Tạo hình ảnh

OpenRouter có thể cung cấp nền tảng cho công cụ image_generate. Đặt một mô hình hình ảnh OpenRouter trong agents.defaults.imageGenerationModel:

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

OpenClaw gửi các yêu cầu hình ảnh đến API hình ảnh hoàn tất hội thoại của OpenRouter với modalities: ["image", "text"]. Các mô hình hình ảnh Gemini còn nhận thêm gợi ý aspectRatio và resolution thông qua image_config của OpenRouter; các mô hình hình ảnh khác thì không. Sử dụng agents.defaults.imageGenerationModel.timeoutMs cho các mô hình chậm hơn; giá trị timeoutMs theo từng lệnh gọi của công cụ image_generate vẫn được ưu tiên.

Tạo video

OpenRouter có thể cung cấp nền tảng cho công cụ video_generate thông qua API /videos bất đồng bộ. Đặt một mô hình video OpenRouter trong agents.defaults.videoGenerationModel:

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

OpenClaw gửi các tác vụ chuyển văn bản thành video và hình ảnh thành video, thăm dò polling_url được trả về và tải video hoàn tất từ unsigned_urls của OpenRouter hoặc điểm cuối nội dung của tác vụ. Theo mặc định, hình ảnh tham chiếu được dùng làm khung hình đầu/cuối; thay vào đó, các hình ảnh được gắn thẻ reference_image sẽ được gửi làm tham chiếu đầu vào. Mặc định google/veo-3.1-fast được đóng gói sẵn hỗ trợ thời lượng 4/6/8 giây, độ phân giải 720P/1080P và tỷ lệ khung hình 16:9/9:16. Không hỗ trợ chuyển video thành video: API thượng nguồn chỉ chấp nhận văn bản và hình ảnh tham chiếu.

Tạo nhạc

OpenRouter có thể cung cấp nền tảng cho công cụ music_generate thông qua đầu ra âm thanh của API hoàn tất hội thoại. Đặt một mô hình âm thanh OpenRouter trong agents.defaults.musicGenerationModel:

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      musicGenerationModel: {        primary: "openrouter/google/lyria-3-pro-preview",        timeoutMs: 180_000,      },    },  },}

Nhà cung cấp nhạc OpenRouter được đóng gói sẵn mặc định sử dụng google/lyria-3-pro-preview và cũng cung cấp google/lyria-3-clip-preview. OpenClaw gửi modalities: ["text", "audio"], truyền phát phản hồi, thu thập các đoạn âm thanh và lưu kết quả dưới dạng nội dung đa phương tiện được tạo để phân phối qua kênh. Các mô hình Lyria chấp nhận một hình ảnh tham chiếu thông qua tham số dùng chung music_generate image=.... Âm thanh truyền phát, việc lưu giữ bản chép lời và lớp bao sự kiện SSE được tạo ra bị giới hạn bởi agents.defaults.mediaMaxMb (giới hạn âm thanh mặc định là 16 MB).

Chuyển văn bản thành giọng nói

OpenRouter có thể hoạt động như một nhà cung cấp TTS thông qua điểm cuối /audio/speech tương thích với OpenAI.

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

Nếu messages.tts.providers.openrouter.apiKey bị bỏ qua, TTS sẽ lần lượt dùng models.providers.openrouter.apiKey, rồi OPENROUTER_API_KEY làm phương án dự phòng.

Chuyển giọng nói thành văn bản (âm thanh đầu vào)

OpenRouter có thể phiên âm các tệp đính kèm giọng nói/âm thanh đầu vào thông qua đường dẫn dùng chung tools.media.audio, bằng điểm cuối STT (/audio/transcriptions). Điều này áp dụng cho mọi Plugin kênh chuyển tiếp giọng nói/âm thanh đầu vào sang bước kiểm tra sơ bộ để nhận hiểu nội dung đa phương tiện.

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

OpenClaw gửi yêu cầu STT tới OpenRouter dưới dạng JSON, với âm thanh mã hóa base64 trong input_audio (theo hợp đồng STT của OpenRouter), thay vì dưới dạng tệp tải lên qua biểu mẫu OpenAI nhiều phần.

Bộ định tuyến Fusion

OpenRouter Fusion gửi một tham chiếu mô hình OpenClaw đến nhiều mô hình OpenRouter song song, để OpenRouter đánh giá câu trả lời của chúng, rồi trả về một phản hồi cuối cùng thông qua điểm cuối OpenRouter thông thường. Định danh mô hình phía thượng nguồn là openrouter/fusion, vì vậy tham chiếu mô hình OpenClaw chứa cả tiền tố nhà cung cấp OpenClaw và không gian tên OpenRouter phía thượng nguồn:

openclaw models set openrouter/openrouter/fusion

Cấu hình nhóm mô hình và mô hình đánh giá của Fusion thông qua params.extraBody của mô hình; các trường này được chuyển tiếp trực tiếp vào phần thân yêu cầu hoàn thành trò chuyện của OpenRouter. Fusion hoạt động với cả quy trình thiết lập bằng OAuth hoặc khóa API; nếu dùng OAuth, hãy bỏ dòng env.OPENROUTER_API_KEY bên dưới.

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      model: { primary: "openrouter/openrouter/fusion" },      models: {        "openrouter/openrouter/fusion": {          params: {            extraBody: {              plugins: [                {                  id: "fusion",                  analysis_models: [                    "google/gemini-3.5-flash",                    "moonshotai/kimi-k2.6",                    "deepseek/deepseek-v4-pro",                  ],                  model: "google/gemini-3.5-flash",                },              ],            },          },        },      },    },  },}

analysis_models là nhóm mô hình chạy song song; model bên trong cấu hình Plugin Fusion là mô hình đánh giá. Không đặt tool_choice cấp cao nhất thành "required" trong các lượt tác tử/trò chuyện thông thường để cố buộc dùng Fusion: các lượt OpenClaw có thể bao gồm định nghĩa công cụ riêng, và lựa chọn bắt buộc dùng công cụ ở cấp cao nhất có thể chọn một trong các công cụ đó thay vì bộ định tuyến Fusion. Khi có cấu hình Plugin Fusion này, OpenClaw thêm một ghi chú đã được làm sạch vào lời nhắc hệ thống, liệt kê các mô hình phân tích đã cấu hình và mô hình đánh giá, để tác tử có thể trả lời câu hỏi về chính nhóm Fusion của mình. Các trường extraBody khác không được sao chép vào lời nhắc.

Fusion được thiết kế để chậm hơn: OpenRouter phân phối lời nhắc đến nhiều mô hình phân tích, sau đó chạy một bước đánh giá/tổng hợp, nên độ trễ cao hơn yêu cầu trực tiếp đến một mô hình duy nhất. Hãy dùng Fusion cho các câu trả lời có chủ đích, chất lượng cao hoặc các lộ trình chuyển cấp, không dùng làm lựa chọn mặc định nhạy cảm với độ trễ. Giữ nhóm mô hình ở quy mô nhỏ và chọn các mô hình phân tích/đánh giá nhanh hơn để nhận phản hồi nhanh hơn.

Kiểm thử một tham chiếu đã cấu hình bằng lệnh gọi cục bộ một lần:

openclaw infer model run --local \  --model openrouter/openrouter/fusion \  --prompt "Reply with exactly: FUSION_OK" \  --json

Xác thực và tiêu đề

OpenRouter sử dụng mã thông báo Bearer lấy từ khóa API của bạn. OAuth của OpenRouter là một luồng đăng nhập PKCE cấp khóa API OpenRouter, vì vậy OpenClaw lưu kết quả trong cùng hồ sơ xác thực bằng khóa API openrouter:default được dùng khi thiết lập khóa API thủ công.

Để đăng nhập hoặc xoay vòng khóa đã lưu trên một bản cài đặt hiện có mà không phải chạy lại toàn bộ quy trình thiết lập ban đầu:

openclaw models auth login --provider openrouter --method oauthopenclaw models auth login --provider openrouter --method api-key

Trên các yêu cầu OpenRouter đã xác minh (https://openrouter.ai/api/v1), OpenClaw thêm các tiêu đề ghi nhận ứng dụng theo tài liệu của OpenRouter:

Cấu hình nâng cao

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

{  models: {    providers: {      openrouter: {        params: {          provider: {            sort: "latency",            require_parameters: true,            data_collection: "deny",          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openrouter/anthropic/claude-sonnet-4-6": {          params: {            provider: {              order: ["anthropic"],              allow_fallbacks: false,            },          },        },      },    },  },}

Liên quan