Gateway

Semantik kredensial autentikasi

Dokumen ini mendefinisikan semantik kelayakan dan resolusi kredensial kanonis yang digunakan di seluruh:

resolveAuthProfileOrder
resolveApiKeyForProfile
models status --probe
doctor-auth

Tujuannya adalah menjaga perilaku saat pemilihan dan runtime tetap selaras.

Kode alasan probe yang stabil

ok
excluded_by_auth_order
missing_credential
invalid_expires
expired
unresolved_ref
no_model

Kredensial token

Kredensial token (type: "token") mendukung token inline dan/atau tokenRef.

Aturan kelayakan

Profil token tidak memenuhi syarat ketika token dan tokenRef sama-sama tidak ada.
expires bersifat opsional.
Jika expires ada, nilainya harus berupa angka terbatas yang lebih besar dari 0.
Jika expires tidak valid (NaN, 0, negatif, tidak terbatas, atau tipe salah), profil tidak memenuhi syarat dengan invalid_expires.
Jika expires berada di masa lalu, profil tidak memenuhi syarat dengan expired.
tokenRef tidak melewati validasi expires.

Aturan resolusi

Semantik resolver cocok dengan semantik kelayakan untuk expires.
Untuk profil yang memenuhi syarat, materi token dapat di-resolve dari nilai inline atau tokenRef.
Ref yang tidak dapat di-resolve menghasilkan unresolved_ref dalam output models status --probe.

Portabilitas salinan agen

Pewarisan autentikasi agen bersifat read-through. Ketika agen tidak memiliki profil lokal, agen dapat me-resolve profil dari penyimpanan agen default/utama pada runtime tanpa menyalin materi rahasia ke auth-profiles.json miliknya sendiri.

Alur salin eksplisit, seperti openclaw agents add, menggunakan kebijakan portabilitas ini:

Profil api_key portabel kecuali copyToAgents: false.
Profil token portabel kecuali copyToAgents: false.
Profil oauth secara default tidak portabel karena token refresh dapat bersifat sekali pakai atau sensitif terhadap rotasi.
Alur OAuth milik provider dapat ikut serta dengan copyToAgents: true hanya ketika penyalinan materi refresh lintas agen diketahui aman.

Profil non-portabel tetap tersedia melalui pewarisan read-through kecuali agen target masuk secara terpisah dan membuat profil lokalnya sendiri.

Rute autentikasi khusus konfigurasi

Entri auth.profiles dengan mode: "aws-sdk" adalah metadata routing, bukan kredensial tersimpan. Entri tersebut valid ketika provider target menggunakan models.providers.<id>.auth: "aws-sdk" atau rute AWS SDK penyiapan Amazon Bedrock milik plugin. Id profil ini dapat muncul dalam auth.order dan penimpaan sesi meskipun tidak ada entri yang cocok di auth-profiles.json.

Jangan tulis type: "aws-sdk" ke dalam auth-profiles.json. Jika instalasi lama memiliki penanda seperti itu, openclaw doctor --fix memindahkannya ke auth.profiles dan menghapus penanda tersebut dari penyimpanan kredensial.

Pemfilteran urutan autentikasi eksplisit

Ketika auth.order.<provider> atau penimpaan urutan auth-store ditetapkan untuk sebuah provider, models status --probe hanya mem-probe id profil yang tetap berada dalam urutan autentikasi yang di-resolve untuk provider tersebut.
Profil tersimpan untuk provider tersebut yang dihilangkan dari urutan eksplisit tidak dicoba diam-diam nanti. Output probe melaporkannya dengan reasonCode: excluded_by_auth_order dan detail Excluded by auth.order for this provider.

Resolusi target probe

Target probe dapat berasal dari profil autentikasi, kredensial lingkungan, atau models.json.
Jika sebuah provider memiliki kredensial tetapi OpenClaw tidak dapat me-resolve kandidat model yang dapat di-probe untuknya, models status --probe melaporkan status: no_model dengan reasonCode: no_model.

Penemuan kredensial CLI eksternal

Kredensial khusus runtime yang dimiliki oleh CLI eksternal ditemukan hanya ketika provider, runtime, atau profil autentikasi berada dalam cakupan operasi saat ini, atau ketika profil lokal tersimpan untuk sumber eksternal tersebut sudah ada.
Pemanggil auth-store sebaiknya memilih mode penemuan CLI eksternal yang eksplisit: none hanya untuk autentikasi persisten/plugin, existing untuk menyegarkan profil CLI eksternal yang sudah tersimpan, atau scoped untuk set provider/profil konkret.
Jalur baca-saja/status meneruskan allowKeychainPrompt: false; jalur tersebut hanya menggunakan kredensial CLI eksternal berbasis file dan tidak membaca atau menggunakan kembali hasil macOS Keychain.

Penjaga Kebijakan OAuth SecretRef

Input SecretRef hanya untuk kredensial statis.
Jika kredensial profil adalah type: "oauth", objek SecretRef tidak didukung untuk materi kredensial profil tersebut.
Jika auth.profiles.<id>.mode adalah "oauth", input keyRef/tokenRef berbasis SecretRef untuk profil tersebut ditolak.
Pelanggaran adalah kegagalan keras dalam jalur resolusi autentikasi startup/reload.

Pesan yang Kompatibel dengan Sistem Lama

Untuk kompatibilitas skrip, kesalahan probe mempertahankan baris pertama ini tanpa perubahan:

Auth profile credentials are missing or expired.

Detail yang ramah manusia dan kode alasan stabil dapat ditambahkan pada baris berikutnya.

Terkait

Was this useful?