Gateway

Semantik kredensial autentikasi

Semantik ini menjaga perilaku autentikasi saat pemilihan dan saat runtime tetap selaras. Semantik ini digunakan bersama oleh:

resolveAuthProfileOrder (pengurutan profil)
resolveApiKeyForProfile (resolusi kredensial runtime)
openclaw models status --probe
pemeriksaan autentikasi openclaw doctor (doctor-auth)

Kode alasan probe yang stabil

Hasil probe membawa kelompok status (ok, auth, rate_limit, billing, timeout, format, unknown, no_model) serta reasonCode yang stabil ketika probe tidak pernah mencapai pemanggilan model:

`reasonCode`	Arti
`excluded_by_auth_order`	Profil tidak disertakan dalam urutan autentikasi eksplisit untuk penyedianya.
`missing_credential`	Tidak ada kredensial inline atau SecretRef yang dikonfigurasi.
`expired`	Token `expires` sudah melewati waktunya.
`invalid_expires`	`expires` bukan stempel waktu Unix dalam milidetik yang positif dan valid.
`unresolved_ref`	SecretRef yang dikonfigurasi tidak dapat diresolusi.
`ineligible_profile`	Profil tidak kompatibel dengan konfigurasi penyedia (termasuk masukan kunci yang tidak valid).
`no_model`	Kredensial tersedia, tetapi tidak ada kandidat model yang dapat diprobe yang berhasil diresolusi.

Pemeriksaan kelayakan melaporkan ok sebagai kode alasan untuk kredensial yang dapat digunakan.

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 tersedia (missing_credential).
expires bersifat opsional. Jika tersedia, nilainya harus berupa jumlah milidetik epoch Unix terbatas yang lebih besar dari 0 dan tidak melebihi stempel waktu maksimum Date JavaScript (8640000000000000).
Jika expires tidak valid (tipe salah, NaN, 0, negatif, tidak terbatas, atau melampaui nilai maksimum tersebut), profil tidak memenuhi syarat dengan invalid_expires.
Jika expires sudah berlalu, profil tidak memenuhi syarat dengan expired.
tokenRef tidak melewati validasi expires.

Aturan resolusi

Semantik resolver sesuai dengan semantik kelayakan untuk expires.
Untuk profil yang memenuhi syarat, materi token dapat diresolusi dari nilai inline atau tokenRef.
Referensi yang tidak dapat diresolusi menghasilkan unresolved_ref dalam keluaran models status --probe.

Portabilitas penyalinan agen

Pewarisan autentikasi agen menggunakan pembacaan langsung. Ketika agen tidak memiliki profil lokal, agen tersebut meresolusi profil dari penyimpanan agen utama/bawaan saat runtime tanpa menyalin materi rahasia ke penyimpanan kredensialnya sendiri (agents/<agentId>/agent/openclaw-agent.sqlite).

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

Profil api_key dan token bersifat portabel kecuali jika copyToAgents: false.
Profil oauth secara bawaan tidak bersifat portabel karena token penyegaran dapat bersifat sekali pakai atau sensitif terhadap rotasi.
Alur OAuth milik penyedia dapat mengaktifkannya dengan copyToAgents: true hanya jika penyalinan materi penyegaran antaragen diketahui aman; pengaktifan ini hanya berlaku ketika profil membawa materi akses/penyegaran inline.

Profil yang tidak portabel tetap tersedia melalui pewarisan pembacaan langsung, kecuali agen tujuan masuk secara terpisah dan membuat profil lokalnya sendiri.

Rute autentikasi khusus konfigurasi

Entri auth.profiles dengan mode: "aws-sdk" merupakan metadata perutean, bukan kredensial tersimpan. Entri ini valid ketika penyedia tujuan menggunakan models.providers.<id>.auth: "aws-sdk", yaitu rute yang ditulis oleh penyiapan Amazon Bedrock milik Plugin. ID profil ini dapat muncul dalam auth.order dan penggantian sesi meskipun tidak ada entri yang sesuai dalam penyimpanan kredensial.

Jangan menulis type: "aws-sdk" ke penyimpanan kredensial; kredensial tersimpan hanya berupa api_key, token, atau oauth. Jika auth-profiles.json lama memiliki penanda seperti itu, openclaw doctor --fix memindahkannya ke auth.profiles dan menghapus penanda tersebut dari penyimpanan.

Pemfilteran urutan autentikasi eksplisit

Ketika auth.order.<provider> atau penggantian urutan penyimpanan autentikasi ditetapkan untuk suatu penyedia, models status --probe hanya memprobe ID profil yang tetap berada dalam urutan autentikasi hasil resolusi untuk penyedia tersebut. Penggantian tersimpan lebih diutamakan daripada konfigurasi auth.order.
Profil tersimpan untuk penyedia tersebut yang tidak disertakan dalam urutan eksplisit tidak dicoba secara diam-diam di kemudian waktu. Keluaran probe melaporkannya dengan reasonCode: excluded_by_auth_order dan detail Dikecualikan oleh auth.order untuk penyedia ini.

Resolusi target probe

Target probe dapat berasal dari profil autentikasi, kredensial lingkungan, atau models.json (source hasil: profile, env, models.json).
Jika penyedia memiliki kredensial tetapi OpenClaw tidak dapat meresolusi kandidat model yang dapat diprobe untuknya, models status --probe melaporkan status: no_model dengan reasonCode: no_model.

Penemuan kredensial CLI eksternal

Kredensial khusus runtime yang dimiliki CLI eksternal (Claude CLI untuk claude-cli, Codex CLI untuk openai, MiniMax CLI untuk minimax-portal) hanya ditemukan ketika penyedia, runtime, atau profil autentikasi berada dalam cakupan operasi saat ini, atau ketika profil lokal tersimpan untuk sumber eksternal tersebut sudah ada.
Pemanggil penyimpanan autentikasi memilih mode penemuan CLI eksternal secara eksplisit: none hanya untuk autentikasi tersimpan/Plugin, existing untuk menyegarkan profil CLI eksternal yang sudah tersimpan, atau scoped untuk sekumpulan penyedia/profil tertentu.
Jalur hanya-baca/status meneruskan allowKeychainPrompt: false; jalur tersebut hanya menggunakan kredensial CLI eksternal berbasis berkas dan tidak membaca atau menggunakan kembali hasil macOS Keychain.

Pengaman kebijakan SecretRef OAuth

Masukan SecretRef hanya ditujukan untuk kredensial statis. Kredensial OAuth dapat berubah saat runtime (alur penyegaran menyimpan token yang telah dirotasi), sehingga materi OAuth berbasis SecretRef akan membagi status yang dapat berubah ke beberapa penyimpanan.

Jika kredensial profil memiliki type: "oauth", objek SecretRef ditolak untuk semua bidang materi kredensial pada profil tersebut.
Jika auth.profiles.<id>.mode adalah "oauth", masukan keyRef/tokenRef berbasis SecretRef untuk profil tersebut ditolak.
Pelanggaran merupakan kegagalan fatal (galat yang dilempar) dalam jalur persiapan rahasia saat mulai/muat ulang dan resolusi profil.

Pesan yang kompatibel dengan versi lama

Demi kompatibilitas skrip, galat probe mempertahankan baris pertama ini tanpa perubahan:

Auth profile credentials are missing or expired.

Detail yang mudah dipahami dan kode alasan yang stabil menyusul pada baris-baris berikutnya dalam bentuk ↳ Auth reason [code]: ....

Terkait

Was this useful?