ClawRouter

ClawRouter memberi OpenClaw satu kunci dengan cakupan kebijakan untuk beberapa penyedia model upstream. Plugin clawrouter bawaan hanya menemukan model yang diizinkan untuk kunci tersebut, merutekan setiap model melalui protokol yang dideklarasikannya, dan melaporkan anggaran kunci serta penggunaan agregat pada antarmuka penggunaan OpenClaw.

Kredensial upstream dan penerusan khusus penyedia tetap berada di ClawRouter, sehingga Anda tidak perlu memasang atau mengautentikasi setiap plugin penyedia upstream pada host OpenClaw. Plugin ini disertakan bersama OpenClaw (enabledByDefault: true); Anda hanya memerlukan kredensial ClawRouter yang telah diterbitkan.

Memulai

export CLAWROUTER_API_KEY="..."openclaw onboard --auth-choice clawrouter-api-keyopenclaw plugins enable clawrouter

openclaw models list --all --provider clawrouter

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

Deployment noninteraktif terkelola

Simpan kunci proksi dalam injeksi secret beban kerja dan hanya simpan SecretRef di openclaw.json. Bidang terkelola kanonisnya adalah:

Sebagai contoh, pengontrol deployment dapat mengelola patch JSON5 ini:

{  plugins: {    entries: { clawrouter: { enabled: true } },  },  models: {    providers: {      clawrouter: {        baseUrl: "https://clawrouter.internal.example",        apiKey: {          source: "env",          provider: "default",          id: "CLAWROUTER_API_KEY",        },        headers: {          "X-ClawRouter-Project-Id": "fakeco",        },      },    },  },  agents: {    defaults: {      model: { primary: "clawrouter/openai/gpt-5.5" },    },  },}

Jika deployment menetapkan plugins.allow, pertahankan entri yang ada dan tambahkan clawrouter. Validasi dan terapkan tanpa wizard interaktif:

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --jsonopenclaw config patch --file ./clawrouter.patch.json5

Uji coba kering me-resolve SecretRef tetapi tidak pernah mencetak nilainya. Untuk merotasi kredensial, perbarui Secret eksternal yang menyediakan CLAWROUTER_API_KEY dan mulai ulang beban kerja gateway agar lingkungan proses baru dimuat. File konfigurasi dan referensi model tidak berubah.

Untuk gateway Docker mandiri yang dibangun dari sumber, ClawRouter sudah disertakan dalam runtime root. Pilih hanya plugin saluran yang memerlukan pengemasan terpisah, seperti OPENCLAW_EXTENSIONS=clickclack, slack, atau msteams; lihat citra yang dibangun dari sumber dengan plugin terpilih. Deployment arsip/perangkat harus mengemas sumber yang sama yang telah digabungkan melalui pipeline artefak mereka sendiri, bukan menggunakan citra OCI.

Kesiapan dan pembuktian langsung

Pemeriksaan ini membuktikan batas yang berbeda; jangan menggantikan satu dengan yang lain:

# Hanya kesehatan proses ClawRouter; tidak ada kredensial atau model upstream yang diuji.curl -fsS https://clawrouter.internal.example/v1/health # Hanya kesiapan startup gateway OpenClaw; tidak ada panggilan model yang dilakukan.curl -fsS http://127.0.0.1:18789/readyz # Penemuan katalog dengan cakupan kredensial.openclaw models list --all --provider clawrouter --json # Probe inferensi nyata minimal melalui penyedia ClawRouter yang dikonfigurasi.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Canary beban kerja menggunakan referensi model yang diberikan secara persis.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Balas persis: CLAWROUTER_CANARY_OK" \  --json

Gunakan model yang dikembalikan oleh katalog tercakup, bukan menyalin model contoh secara membuta. Respons /readyz yang berhasil berarti gateway dapat melayani permintaan; hal itu tidak menyatakan bahwa ClawRouter, kredensialnya, atau penyedia upstream sudah siap. Probe model dan canary agen merupakan bukti inferensi.

Untuk diagnosis langsung, jalankan canary dan periksa log standar gateway. Diagnostik transportasi model yang hanya berisi metadata menghasilkan baris dengan bentuk seperti:

[model-fetch] mulai provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] respons provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

Plugin mengirim header X-ClawRouter-Client, X-ClawRouter-Agent-Id, dan X-ClawRouter-Session-Id yang dibatasi ketika pengidentifikasi tersebut tersedia. Plugin juga memetakan callId diagnostik panggilan model (<run-id>:model:<n>) ke X-Request-ID, sehingga peristiwa panggilan model OpenClaw dapat digabungkan dengan jejak audit ClawRouter yang hanya berisi metadata. Nilai dalam batas request-id 128 karakter bersifat identik. Nilai yang lebih panjang mempertahankan sufiks :model:<n> dan hash deterministik agar panggilan yang berbeda tetap terbatas dan dapat digabungkan. Metadata deployment statis seperti X-ClawRouter-Project-Id dapat ditetapkan dalam peta headers penyedia. Header atribusi agen dan sesi mempertahankan batas 256 karakter yang terpisah. ID permintaan otomatis yang memuat karakter di luar kumpulan pengidentifikasi ASCII ClawRouter menggunakan bentuk deterministik terbatas yang sama. Header eksplisit yang dikonfigurasi, termasuk variasi kapitalisasi apa pun dari X-Request-ID, lebih diutamakan daripada nilai otomatis. Diagnostik transportasi mencatat metadata perutean dan respons; diagnostik tersebut tidak mencatat kredensial, ID permintaan, prompt, atau hasil penyelesaian. Peristiwa audit ClawRouter sendiri menyediakan penyedia upstream yang dipilih dan status retensi konten.

Penemuan model

GET /v1/catalog mengembalikan { providers: [...] }, dengan setiap entri penyedia mencantumkan models[] miliknya sendiri (dengan ID upstream, kemampuan, dan harga) serta rute permintaan yang didukungnya. OpenClaw tidak menyertakan daftar tetap kedua untuk model ClawRouter. Model katalog ditampilkan sebagai model OpenClaw ketika:

• kebijakan kredensial memberikan akses ke penyedianya;
• model katalog mengiklankan kemampuan LLM yang didukung (llm.responses, llm.chat, llm.messages, atau llm.stream dengan rute streaming yang cocok); dan
• penyedia mengekspos rute yang cocok untuk salah satu transportasi di bawah ini.

Menambahkan model ke penyedia ClawRouter yang didukung tidak memerlukan rilis OpenClaw: penyegaran katalog berikutnya (di-cache selama 60 detik per cakupan kredensial) akan menemukannya. Model yang memerlukan protokol wire baru terlebih dahulu memerlukan dukungan plugin.

Protokol dan plugin penyedia

ClawRouter mengelola kredensial upstream; katalognya memberi tahu OpenClaw transportasi mana yang harus digunakan, sehingga Anda tidak perlu memasang plugin autentikasi setiap perusahaan upstream.

Plugin juga menerapkan kebijakan replay dan skema alat yang cocok untuk keluarga tersebut (kompatibilitas skema alat OpenAI/DeepSeek/Gemini/Perplexity; kebijakan replay native Anthropic dan Google Gemini). Model Perplexity mendapatkan penulisan ulang skema yang ketat: patternProperties dan additionalProperties dihapus dan setiap skema objek mendeklarasikan properties, karena Perplexity menolak skema alat tanpanya. Penyedia katalog yang hanya mengekspos format permintaan yang tidak didukung sengaja tidak ditampilkan sebagai model teks OpenClaw. Normalisasikan penyedia tersebut ke salah satu kontrak yang didukung di ClawRouter, alih-alih mengirim payload yang tidak kompatibel.

Kuota dan penggunaan

Respons /v1/usage ClawRouter memasok antarmuka penggunaan penyedia OpenClaw standar: total permintaan, token, dan pengeluaran, serta periode anggaran bulanan ketika kunci memiliki batas. Kunci tanpa pengukuran tetap menampilkan penggunaan agregat tanpa periode persentase.

Pencarian kuota menggunakan kunci tercakup yang sama dengan penemuan model. Kegagalan pencarian kuota tidak memblokir eksekusi model.

Periksa snapshot langsung dengan:

openclaw status --usageopenclaw models status

Snapshot penyedia yang sama tersedia bagi /status dalam obrolan dan UI penggunaan OpenClaw. Anggaran berlaku untuk seluruh kebijakan, sehingga permintaan yang dibuat oleh klien lain menggunakan kebijakan ClawRouter yang sama dapat mengubah persentase yang tersisa.

Pemecahan masalah

Perilaku keamanan

• Penemuan katalog dibatasi pada kunci proksi yang dikonfigurasi dan disimpan dalam cache per cakupan kredensial (direktori agen, direktori ruang kerja, id profil autentikasi, dan URL dasar).
• Kunci proksi hanya disertakan saat pengiriman permintaan; kunci tersebut tidak disimpan dalam metadata model.
• Nilai atribusi otomatis dan korelasi permintaan dipangkas serta ditolak jika mengandung karakter kontrol sebelum pengiriman. Nilai atribusi dibatasi hingga 256 karakter; id permintaan dibatasi hingga 128.
• Diagnostik transportasi model hanya berisi metadata dan tidak pernah menyertakan kunci proksi atau konten model.
• Id model asli Anthropic dan Gemini ditulis ulang menjadi id upstream-nya hanya saat pengiriman.
• Baris katalog yang tidak didukung atau belum diberi izin akan gagal secara tertutup dan tidak dapat dipilih.

Terkait