ClawRouter

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

Kredensial hulu dan penerusan khusus penyedia tetap berada di ClawRouter, sehingga Anda tidak perlu menginstal atau mengautentikasi setiap Plugin penyedia hulu 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>

Penerapan noninteraktif terkelola

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

Sebagai contoh, pengontrol penerapan dapat mengelola tambalan JSON5 berikut:

{  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 penerapan menetapkan plugins.allow, pertahankan entri yang sudah ada dan tambahkan clawrouter. Validasi dan terapkan tanpa wisaya interaktif:

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

Uji coba menyelesaikan 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. Berkas konfigurasi dan referensi model tidak berubah.

Untuk Gateway Docker mandiri yang dibangun dari sumber, ClawRouter sudah disertakan dalam runtime akar. Pilih hanya Plugin kanal yang memerlukan pemaketan terpisah, seperti OPENCLAW_EXTENSIONS=clickclack, slack, atau msteams; lihat citra yang dibangun dari sumber dengan Plugin terpilih. Penerapan arsip/perangkat harus memaketkan sumber yang sama yang telah digabungkan melalui alur artefak mereka sendiri, bukan menggunakan citra OCI.

Kesiapan dan bukti langsung

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

# Hanya kesehatan proses ClawRouter; tidak ada kredensial atau model hulu yang diuji.curl -fsS https://clawrouter.internal.example/v1/health # Hanya kesiapan mulai 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 tepat.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Reply exactly: CLAWROUTER_CANARY_OK" \  --json

Gunakan model yang dikembalikan oleh katalog dengan cakupan tersebut, alih-alih menyalin model contoh tanpa pemeriksaan. Respons /readyz yang berhasil berarti Gateway dapat melayani permintaan; respons tersebut tidak menyatakan bahwa ClawRouter, kredensialnya, atau penyedia hulu telah siap. Probe model dan canary agen merupakan bukti inferensi.

Untuk diagnosis langsung, jalankan canary dan periksa log standar Gateway. Diagnostik transpor model yang hanya memuat metadata menghasilkan baris dengan bentuk seperti:

[model-fetch] start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] response 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 dengan panjang terbatas saat pengenal tersebut tersedia. Plugin juga memetakan callId diagnostik panggilan model (<run-id>:model:<n>) ke X-Request-ID, sehingga peristiwa panggilan model OpenClaw dapat dihubungkan dengan jejak audit ClawRouter yang hanya memuat metadata. Nilai yang berada dalam batas 128 karakter untuk ID permintaan bersifat identik. Nilai yang lebih panjang mempertahankan akhiran :model:<n> dan hash deterministik agar setiap panggilan tetap memiliki panjang terbatas dan dapat dihubungkan. Metadata penerapan statis seperti X-ClawRouter-Project-Id dapat ditetapkan dalam peta headers penyedia. Header atribusi agen dan sesi mempertahankan batas terpisah sebesar 256 karakter. ID permintaan otomatis yang memuat karakter di luar kumpulan pengenal ASCII ClawRouter menggunakan bentuk deterministik dengan panjang terbatas yang sama. Header eksplisit yang dikonfigurasi, termasuk variasi kapitalisasi apa pun dari X-Request-ID, diutamakan daripada nilai otomatis. Diagnostik transpor mencatat metadata perutean dan respons; diagnostik tersebut tidak mencatat kredensial, ID permintaan, prompt, atau penyelesaian. Peristiwa audit milik ClawRouter menyediakan penyedia hulu yang dipilih dan status retensi konten.

Penemuan model

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

• kebijakan kredensial memberikan akses ke penyedianya;
• model katalog mengumumkan 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 transpor di bawah ini.

Menambahkan model ke penyedia ClawRouter yang didukung tidak memerlukan rilis OpenClaw: penyegaran katalog berikutnya (di-cache selama 60 detik untuk setiap cakupan kredensial) akan menemukannya. Model yang memerlukan protokol jaringan baru harus mendapatkan dukungan Plugin terlebih dahulu.

Protokol dan Plugin penyedia

ClawRouter mengelola kredensial hulu; katalognya memberi tahu OpenClaw transpor mana yang harus digunakan, sehingga Anda tidak perlu menginstal Plugin autentikasi dari setiap perusahaan penyedia hulu.

Plugin juga menerapkan kebijakan pemutaran ulang dan skema alat yang cocok untuk keluarga tersebut (kompatibilitas skema alat OpenAI/DeepSeek/Gemini; kebijakan pemutaran ulang Anthropic dan Google Gemini yang asli). Penyedia katalog yang hanya mengekspos format permintaan yang tidak didukung sengaja tidak diumumkan sebagai model teks OpenClaw. Normalkan penyedia tersebut ke salah satu kontrak yang didukung di ClawRouter, alih-alih mengirim payload yang tidak kompatibel.

Kuota dan penggunaan

Respons /v1/usage ClawRouter mengisi permukaan penggunaan penyedia OpenClaw yang normal: total permintaan, token, dan pengeluaran, ditambah jendela anggaran bulanan ketika kunci memiliki batas. Kunci tanpa pengukuran tetap menampilkan penggunaan agregat tanpa jendela persentase.

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

Periksa snapshot langsung dengan:

openclaw status --usageopenclaw models status

Snapshot penyedia yang sama tersedia untuk /status dalam obrolan dan UI penggunaan OpenClaw. Anggaran berlaku di 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 di-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, dan nilai yang mengandung karakter kontrol ditolak sebelum pengiriman. Nilai atribusi dibatasi hingga 256 karakter; id permintaan dibatasi hingga 128 karakter.
• 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 masing-masing hanya saat pengiriman.
• Baris katalog yang tidak didukung atau tidak diberi izin ditolak secara tertutup dan tidak dapat dipilih.

Terkait