OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Autentikasi

OpenClaw mendukung OAuth dan kunci API untuk penyedia model. Untuk host Gateway yang selalu aktif, kunci API adalah opsi yang paling dapat diprediksi; alur langganan/OAuth juga dapat digunakan jika sesuai dengan model akun penyedia Anda.

Penyiapan yang disarankan: kunci API (penyedia apa pun)

  1. Buat kunci API di konsol penyedia Anda.
  2. Tempatkan kunci tersebut di host Gateway (mesin yang menjalankan openclaw gateway):
bash
export <PROVIDER>_API_KEY="..."openclaw models status
  1. Jika Gateway berjalan di bawah systemd/launchd, tempatkan kunci di ~/.openclaw/.env agar daemon dapat membacanya:
bash
cat >> ~/.openclaw/.env <<'EOF'&lt;PROVIDER&gt;_API_KEY=...EOF
  1. Mulai ulang proses Gateway (atau daemon), lalu periksa kembali:
bash
openclaw models statusopenclaw doctor

openclaw onboard juga dapat menyimpan kunci API untuk digunakan daemon jika Anda tidak ingin mengelola variabel lingkungan sendiri. Lihat Variabel lingkungan untuk urutan prioritas pemuatan lingkungan lengkap (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: penggunaan ulang Claude CLI

Autentikasi token penyiapan Anthropic tetap menjadi jalur yang didukung. Penggunaan ulang Claude CLI (penggunaan bergaya claude -p) juga diizinkan untuk integrasi ini; jika proses masuk Claude CLI tersedia di host, itulah jalur yang diutamakan untuk penggunaan lokal/desktop. Untuk host Gateway berumur panjang, kunci API Anthropic tetap menjadi pilihan yang paling dapat diprediksi, dengan kontrol penagihan sisi server yang eksplisit.

Penyiapan host untuk penggunaan ulang Claude CLI:

bash
# Run on the gateway hostclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Proses ini terdiri dari dua langkah: masuk ke Anthropic melalui Claude Code di host, lalu beri tahu OpenClaw agar merutekan pemilihan model Anthropic melalui backend lokal claude-cli dan menyimpan profil autentikasi OpenClaw yang sesuai.

Jika claude tidak ada di PATH, instal Claude Code atau atur agents.defaults.cliBackends.claude-cli.command ke jalur biner.

Entri token secara manual

Dapat digunakan untuk penyedia apa pun; menulis penyimpanan autentikasi SQLite per agen dan memperbarui konfigurasi:

bash
openclaw models auth paste-token --provider openrouter

OpenClaw membaca profil autentikasi dari openclaw-agent.sqlite milik setiap agen. Detail endpoint (baseUrl, api, ID model, header, batas waktu) harus ditempatkan di bawah models.providers.<id> dalam openclaw.json atau models.json, bukan dalam profil autentikasi.

Jika instalasi lama masih memiliki auth-profiles.json, auth-state.json, atau bentuk datar seperti { "openrouter": { "apiKey": "..." } }, jalankan openclaw doctor --fix untuk mengimpornya ke SQLite; doctor menyimpan cadangan dengan stempel waktu di samping berkas JSON asli.

Rute autentikasi eksternal seperti auth: "aws-sdk" milik Bedrock bukanlah kredensial. Untuk rute Bedrock bernama, atur auth.profiles.<id>.mode: "aws-sdk" dalam openclaw.json — jangan tulis type: "aws-sdk" ke penyimpanan profil autentikasi. openclaw doctor --fix memigrasikan penanda AWS SDK lama dari penyimpanan kredensial ke metadata konfigurasi.

Kredensial berbasis SecretRef

  • Kredensial api_key dapat menggunakan keyRef: { source, provider, id }
  • Kredensial token dapat menggunakan tokenRef: { source, provider, id }
  • Profil bermode OAuth menolak kredensial SecretRef: jika auth.profiles.<id>.mode adalah "oauth", keyRef/tokenRef berbasis SecretRef untuk profil tersebut akan ditolak.

Memeriksa status autentikasi model

bash
openclaw models statusopenclaw doctor

Pemeriksaan yang ramah otomatisasi, keluar dengan 1 jika kedaluwarsa/tidak ada, 2 jika akan segera kedaluwarsa:

bash
openclaw models status --check

Probe autentikasi langsung (tambahkan --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency, atau --probe-max-tokens untuk mempersempit cakupan):

bash
openclaw models status --probe

Catatan:

  • Baris probe dapat berasal dari profil autentikasi, kredensial lingkungan, atau models.json.
  • Jika auth.order.<provider> menghilangkan profil yang tersimpan, probe melaporkan excluded_by_auth_order untuk profil tersebut alih-alih mencobanya.
  • Jika autentikasi tersedia tetapi OpenClaw tidak dapat menentukan model yang dapat diuji untuk penyedia tersebut, probe melaporkan status: no_model.
  • Masa jeda pembatasan laju dapat memiliki cakupan per model: profil yang sedang dalam masa jeda untuk satu model masih dapat melayani model sejawat pada penyedia yang sama.

Skrip operasional opsional (systemd/Termux): Skrip pemantauan autentikasi.

Rotasi kunci API (Gateway)

Beberapa penyedia mencoba ulang permintaan dengan kunci alternatif yang dikonfigurasi ketika suatu panggilan terkena batas laju penyedia.

Urutan prioritas kunci per penyedia:

  1. OPENCLAW_LIVE_&lt;PROVIDER&gt;_KEY (penimpaan tunggal, menetapkan satu kunci)
  2. &lt;PROVIDER&gt;_API_KEYS (daftar yang dipisahkan koma/spasi/titik koma)
  3. &lt;PROVIDER&gt;_API_KEY
  4. &lt;PROVIDER&gt;_API_KEY_* (variabel lingkungan apa pun dengan prefiks ini)

Penyedia Google (google, google-vertex) juga beralih ke GOOGLE_API_KEY sebagai cadangan. Duplikat dihapus dari daftar gabungan sebelum digunakan.

OpenClaw berotasi ke kunci berikutnya hanya ketika pesan kesalahan cocok dengan: rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted, atau too many requests. Kesalahan lain tidak dicoba ulang dengan kunci alternatif. Jika semua kunci gagal, kesalahan terakhir dari percobaan terakhir akan dikembalikan.

Menghapus autentikasi yang tersimpan tidak mencabut kunci di penyedia — rotasi atau cabut kunci tersebut di dasbor penyedia ketika Anda memerlukan pembatalan dari sisi penyedia.

Menghapus autentikasi penyedia saat Gateway sedang berjalan

Ketika Anda menghapus autentikasi penyedia melalui bidang kontrol Gateway, OpenClaw menghapus profil autentikasi yang tersimpan untuk penyedia tersebut dan membatalkan percakapan/proses agen aktif yang penyedia model pilihannya cocok dengan penyedia yang dihapus. Proses yang dibatalkan memancarkan peristiwa pembatalan/siklus hidup normal dengan stopReason: "auth-revoked", sehingga klien yang terhubung dapat menunjukkan bahwa proses dihentikan karena kredensial telah dihapus.

Mengendalikan kredensial yang digunakan

OpenAI dan ID openai-codex lama

Profil kunci API OpenAI dan profil OAuth ChatGPT/Codex sama-sama menggunakan ID penyedia kanonis openai. Gunakan ID profil openai:* dan auth.order.openai untuk konfigurasi baru.

Jika Anda melihat openai-codex dalam konfigurasi lama, ID profil autentikasi, atau auth.order.openai-codex, perlakukan sebagai masukan migrasi lama — jangan membuat profil openai-codex baru. Jalankan:

bash
openclaw doctor --fixopenclaw models auth list --provider openai

Doctor menulis ulang ID profil openai-codex:* dan entri auth.order.openai-codex lama ke rute kanonis openai. Untuk perutean model/runtime khusus OpenAI, lihat OpenAI.

Saat masuk (CLI)

bash
openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

--profile-id menjaga beberapa proses masuk OAuth untuk penyedia yang sama tetap terpisah dalam satu agen.

--force menghapus profil autentikasi yang tersimpan untuk penyedia tersebut di direktori agen yang dipilih, lalu menjalankan kembali alur autentikasi yang sama. Gunakan ketika profil tersimpan macet, kedaluwarsa, atau terikat ke akun yang salah. Opsi ini tidak mencabut kredensial di penyedia.

bash
openclaw models auth login --provider anthropic --force

Per sesi (perintah percakapan)

  • /model <alias-or-id>@<profileId> menetapkan kredensial penyedia tertentu untuk sesi saat ini (contoh ID profil: anthropic:default, anthropic:work).
  • /model (atau /model list) menampilkan pemilih ringkas; /model status menampilkan tampilan lengkap (kandidat + profil autentikasi berikutnya, serta detail endpoint penyedia jika dikonfigurasi).

Jika Anda mengubah urutan autentikasi atau penetapan profil untuk percakapan yang sudah berjalan, kirim /new atau /reset untuk memulai sesi baru — sesi yang sudah ada mempertahankan pilihan model/profil saat ini hingga diatur ulang.

Per agen (penimpaan CLI)

Penimpaan urutan autentikasi disimpan dalam status autentikasi SQLite milik agen tersebut:

bash
openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

Gunakan --agent <id> untuk menargetkan agen tertentu; hilangkan opsi tersebut untuk menggunakan agen default yang dikonfigurasi. openclaw models status --probe menampilkan profil tersimpan yang dihilangkan sebagai excluded_by_auth_order, alih-alih melewatinya secara diam-diam.

Pemecahan masalah

"Tidak ditemukan kredensial"

Konfigurasikan kunci API Anthropic di host Gateway, atau siapkan jalur token penyiapan Anthropic, lalu periksa kembali:

bash
openclaw models status

Token akan segera kedaluwarsa/sudah kedaluwarsa

Jalankan openclaw models status untuk melihat profil mana yang akan segera kedaluwarsa. Jika profil token Anthropic tidak ada atau sudah kedaluwarsa, segarkan melalui token penyiapan atau migrasikan ke kunci API Anthropic.

Terkait

Was this useful?
On this page

On this page