Langsung ke konten utama

​
SecretRef Vault

Plugin Vault bawaan memungkinkan OpenClaw me-resolve SecretRef exec dari HashiCorp Vault saat Gateway dimulai dan dimuat ulang. OpenClaw menyimpan referensi Vault dalam konfigurasi, mempertahankan nilai yang telah di-resolve dalam snapshot rahasia di memori, dan tidak menulis kembali kunci API yang telah di-resolve ke openclaw.json. Gunakan ini jika Anda sudah menjalankan Vault atau ingin menyimpan kunci penyedia model di luar file konfigurasi OpenClaw. Untuk model runtime SecretRef, lihat Pengelolaan rahasia.

​
Sebelum memulai

Anda memerlukan:
  • OpenClaw dengan plugin vault bawaan yang tersedia
  • server Vault yang dapat dijangkau
  • autentikasi Vault yang dapat menghasilkan token klien dengan akses baca ke jalur rahasia yang perlu di-resolve oleh OpenClaw
  • lingkungan yang memulai Gateway harus menyertakan VAULT_ADDR dan salah satu dari VAULT_TOKEN, OPENCLAW_VAULT_AUTH_METHOD=token_file dengan VAULT_TOKEN_FILE, atau login JWT/Kubernetes yang telah dikonfigurasi
Resolver berkomunikasi dengan Vault melalui HTTP dari Node. Gateway tidak memerlukan CLI Vault untuk me-resolve SecretRef. Aktifkan plugin bawaan sebelum menjalankan perintah openclaw vault:

​
Menyimpan kunci penyedia di Vault

OpenClaw secara default menggunakan KV v2 yang dipasang di secret, sesuai dengan contoh server pengembangan Vault. Untuk Vault produksi, atur OPENCLAW_VAULT_KV_MOUNT ke jalur pemasangan KV yang sebenarnya sebelum membuat ID SecretRef. Dengan pengaturan default OpenClaw, ID SecretRef ini:
membaca bidang Vault berikut:
Salah satu cara untuk membuatnya dengan CLI Vault adalah:
Gunakan token klien dengan cakupan terbatas untuk OpenClaw, bukan token root. Untuk tata letak KV v2 default, kebijakan minimal bagi kunci penyedia model terlihat seperti:

​
Membuat Vault terlihat oleh Gateway

Untuk Gateway lokal tanpa kontainer, ekspor pengaturan Vault di shell yang sama yang memulai OpenClaw. Metode autentikasi default membaca token klien Vault dari VAULT_TOKEN:
Jika Vault Agent menulis file sink token, gunakan autentikasi file token:
Untuk server Vault yang ditandatangani oleh CA privat, instal CA tersebut di penyimpanan kepercayaan host dan aktifkan kepercayaan sistem Node:
Atau berikan bundel PEM secara langsung:
Variabel-variabel ini harus tersedia saat OpenClaw dimulai. Plugin Vault meneruskannya ke proses resolver-nya. Untuk autentikasi JWT noninteraktif, gunakan file JWT beban kerja dan peran Vault bertipe jwt:
File JWT harus berupa token beban kerja yang diproyeksikan, seperti token akun layanan Kubernetes dengan audiens yang diterima oleh peran Vault. Login peramban OIDC interaktif berguna bagi manusia, tetapi runtime Gateway memerlukan login JWT noninteraktif atau file token. Untuk metode autentikasi Kubernetes milik Vault, gunakan kubernetes. Ini ditujukan bagi Gateway yang berjalan sebagai Pod; pemasangan default adalah kubernetes, dan file JWT default adalah jalur token akun layanan standar:
Atur OPENCLAW_VAULT_AUTH_MOUNT hanya jika Vault memasang autentikasi Kubernetes di lokasi selain auth/kubernetes. Atur OPENCLAW_VAULT_JWT_FILE hanya jika token akun layanan diproyeksikan ke jalur khusus. Pengaturan opsional:
Periksa apa yang dapat dilihat oleh shell saat ini:
Jika lebih dari satu penyedia rahasia berbasis Vault dikonfigurasi, pilih salah satunya berdasarkan alias:
openclaw vault status tidak pernah mencetak VAULT_TOKEN; perintah ini hanya melaporkan apakah token, file token, dan file JWT telah diatur.
Jika Gateway berjalan sebagai layanan, LaunchAgent, unit systemd, tugas terjadwal, atau kontainer, lingkungan runtime tersebut harus menerima variabel Vault yang sama. Mengatur variabel dalam shell interaktif hanya membuktikan bahwa shell tersebut memilikinya, bukan Gateway yang sudah berjalan.

​
Membuat dan menerapkan rencana SecretRef

Buat rencana yang memetakan kunci API penyedia model OpenRouter ke Vault:
Terapkan dan verifikasi rencana:
Gunakan --allow-exec karena plugin Vault melakukan resolusi melalui penyedia SecretRef exec yang dikelola OpenClaw. Jika Gateway belum berjalan, mulai seperti biasa setelah menerapkan rencana alih-alih menjalankan openclaw secrets reload.

​
Mengonfigurasi lebih banyak kunci penyedia

Pintasan bawaan:
Beberapa kunci penyedia dalam satu rencana:
Penyedia bawaan tanpa pintasan, atau penyedia model kompatibel OpenAI dan khusus yang sudah dikonfigurasi, menggunakan --provider-key:
Setiap --provider-key <provider=id> menulis SecretRef ke models.providers.<provider>.apiKey. Untuk penyedia khusus, perintah ini tidak membuat pengaturan baseUrl, api, atau models milik penyedia; konfigurasikan pengaturan tersebut terlebih dahulu. Gunakan --target <path=id> untuk setiap jalur target SecretRef yang diketahui:
Jalur target polos diterapkan ke openclaw.json. Gunakan auth-profiles:<agentId>:<path> untuk target auth-profiles.json yang sudah ada. Jalur target harus merupakan target SecretRef OpenClaw yang terdaftar. Perintah penyiapan tidak membuat rahasia bernama secara sembarang di OpenClaw; Vault tetap menjadi penyimpanan rahasia, dan OpenClaw hanya menyimpan SecretRef pada bidang konfigurasi yang didukung.

​
Format ID SecretRef

ID SecretRef Vault menggunakan konvensi berikut:
Contoh:
ID SecretRefPembacaan Vault KV v2 defaultBidang yang dikembalikan
providers/openrouter/apiKeysecret/data/providers/openrouterapiKey
providers/openai/apiKeysecret/data/providers/openaiapiKey
teams/agent-prod/openroutersecret/data/teams/agent-prodopenrouter
Bidang Vault yang dikembalikan harus berupa string. Untuk KV v1, atur:
Kemudian providers/openrouter/apiKey membaca:

​
Yang disimpan OpenClaw

Menerapkan rencana penyiapan Vault akan menyimpan penyedia yang dikelola plugin:
Bidang kredensial mengarah ke penyedia tersebut:
Nilai yang di-resolve hanya berada dalam snapshot rahasia runtime yang aktif.

​
Kontainer dan penerapan terkelola

Gateway dalam kontainer tetap menggunakan plugin dan konfigurasi SecretRef yang sama. Kontainer harus menerima:
  • VAULT_ADDR
  • satu sumber autentikasi:
    • VAULT_TOKEN
    • OPENCLAW_VAULT_AUTH_METHOD=token_file ditambah VAULT_TOKEN_FILE
    • OPENCLAW_VAULT_AUTH_METHOD=jwt ditambah OPENCLAW_VAULT_AUTH_MOUNT, OPENCLAW_VAULT_AUTH_ROLE, dan OPENCLAW_VAULT_JWT_FILE
    • OPENCLAW_VAULT_AUTH_METHOD=kubernetes ditambah OPENCLAW_VAULT_AUTH_ROLE; secara opsional timpa OPENCLAW_VAULT_AUTH_MOUNT atau OPENCLAW_VAULT_JWT_FILE
  • VAULT_NAMESPACE, OPENCLAW_VAULT_KV_MOUNT, dan OPENCLAW_VAULT_KV_VERSION yang bersifat opsional
Saat menggunakan Kubernetes, utamakan OPENCLAW_VAULT_AUTH_METHOD=kubernetes jika Vault telah mengonfigurasi autentikasi Kubernetes untuk klaster. Gunakan OPENCLAW_VAULT_AUTH_METHOD=jwt hanya jika Vault dikonfigurasi untuk memperlakukan klaster sebagai penerbit JWT/OIDC generik. Kedua opsi tersebut lebih baik daripada token Vault berumur panjang dalam Secret Kubernetes. Penerapan sidecar atau injektor Vault Agent dapat menggunakan token_file sebagai gantinya. Untuk penyiapan Vault multipenyewa, pertahankan perutean penyewa dalam kebijakan Vault dan konfigurasi penerapan. OpenClaw tidak memerlukan pemasangan, peran, atau jalur tetap: setiap lingkungan Gateway dapat mengatur OPENCLAW_VAULT_KV_MOUNT, OPENCLAW_VAULT_AUTH_ROLE, dan ID SecretRef-nya sendiri. Jika satu Gateway bersama harus me-resolve pengguna Vault yang berbeda secara bersamaan, gunakan penyedia exec yang dikonfigurasi secara manual dan membungkus lingkungan autentikasi yang berbeda, atau pisahkan penyewa ke beberapa lingkungan Gateway dengan lingkungan Vault terpisah.

​
Terkait