Langsung ke konten utama
Halaman ini adalah referensi lengkap untuk openclaw onboard. Untuk panduan singkat, lihat Onboarding (CLI).

​
Apa yang dilakukan wizard

Mode lokal (default) memandu Anda melalui:
  • Penyiapan model dan autentikasi (OAuth langganan OpenAI Code, Anthropic Claude CLI atau kunci API, plus opsi MiniMax, GLM, Ollama, Moonshot, StepFun, dan AI Gateway)
  • Lokasi workspace dan file bootstrap
  • Pengaturan Gateway (port, bind, autentikasi, Tailscale)
  • Channel dan provider (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, iMessage, dan Plugin channel bawaan lainnya)
  • Instalasi daemon (LaunchAgent, unit pengguna systemd, atau Windows Scheduled Task native dengan fallback folder Startup)
  • Pemeriksaan kesehatan
  • Penyiapan Skills
Mode jarak jauh mengonfigurasi mesin ini untuk terhubung ke gateway di tempat lain. Mode ini tidak menginstal atau mengubah apa pun pada host jarak jauh.

​
Detail alur lokal

1

Deteksi konfigurasi yang ada

  • Jika ~/.openclaw/openclaw.json ada, pilih Keep, Modify, atau Reset.
  • Menjalankan ulang wizard tidak menghapus apa pun kecuali Anda secara eksplisit memilih Reset (atau meneruskan --reset).
  • CLI --reset default ke config+creds+sessions; gunakan --reset-scope full untuk juga menghapus workspace.
  • Jika konfigurasi tidak valid atau berisi key legacy, wizard berhenti dan meminta Anda menjalankan openclaw doctor sebelum melanjutkan.
  • Reset menggunakan trash dan menawarkan cakupan:
    • Hanya konfigurasi
    • Konfigurasi + kredensial + sesi
    • Reset penuh (juga menghapus workspace)
2

Model dan autentikasi

3

Workspace

  • Default ~/.openclaw/workspace (dapat dikonfigurasi).
  • Menyemai file workspace yang diperlukan untuk ritual bootstrap pertama kali.
  • Tata letak workspace: Workspace agent.
4

Gateway

  • Meminta port, bind, mode autentikasi, dan paparan Tailscale.
  • Direkomendasikan: tetap aktifkan autentikasi token bahkan untuk loopback agar klien WS lokal harus mengautentikasi.
  • Dalam mode token, penyiapan interaktif menawarkan:
    • Buat/simpan token plaintext (default)
    • Gunakan SecretRef (opt-in)
  • Dalam mode kata sandi, penyiapan interaktif juga mendukung penyimpanan plaintext atau SecretRef.
  • Jalur SecretRef token non-interaktif: --gateway-token-ref-env <ENV_VAR>.
    • Memerlukan env var yang tidak kosong dalam environment proses onboarding.
    • Tidak dapat digabungkan dengan --gateway-token.
  • Nonaktifkan autentikasi hanya jika Anda sepenuhnya memercayai setiap proses lokal.
  • Bind non-loopback tetap memerlukan autentikasi.
5

Channel

  • WhatsApp: login QR opsional
  • Telegram: token bot
  • Discord: token bot
  • Google Chat: JSON akun layanan + audiens Webhook
  • Mattermost: token bot + URL dasar
  • Signal: instalasi signal-cli opsional + konfigurasi akun
  • iMessage: jalur CLI imsg + akses DB Messages; gunakan wrapper SSH saat Gateway berjalan di luar Mac
  • Keamanan DM: default adalah pairing. DM pertama mengirim kode; setujui melalui openclaw pairing approve <channel> <code> atau gunakan allowlist.
6

Instalasi daemon

  • macOS: LaunchAgent
    • Memerlukan sesi pengguna yang login; untuk headless, gunakan LaunchDaemon khusus (tidak disertakan).
  • Linux dan Windows melalui WSL2: unit pengguna systemd
    • Wizard mencoba loginctl enable-linger <user> agar gateway tetap berjalan setelah logout.
    • Dapat meminta sudo (menulis /var/lib/systemd/linger); ini mencoba tanpa sudo terlebih dahulu.
  • Windows native: Scheduled Task terlebih dahulu
    • Jika pembuatan task ditolak, OpenClaw fallback ke item login folder Startup per pengguna dan langsung memulai gateway.
    • Scheduled Tasks tetap lebih disukai karena menyediakan status supervisor yang lebih baik.
  • Pemilihan runtime: Node (direkomendasikan; diperlukan untuk WhatsApp dan Telegram). Bun tidak direkomendasikan.
7

Pemeriksaan kesehatan

  • Memulai gateway (jika diperlukan) dan menjalankan openclaw health.
  • openclaw status --deep menambahkan probe kesehatan gateway live ke output status, termasuk probe channel saat didukung.
8

Skills

  • Membaca skill yang tersedia dan memeriksa persyaratan.
  • Memungkinkan Anda memilih manajer node: npm, pnpm, atau bun.
  • Menginstal dependensi opsional untuk skill bawaan tepercaya saat installer yang diperlukan tersedia.
  • Melewati installer Homebrew, uv, dan Go yang tidak tersedia, lalu mengelompokkan skill yang terdampak dengan panduan penyiapan manual. Jalankan openclaw doctor setelah menginstal prasyarat yang hilang.
9

Selesai

  • Ringkasan dan langkah berikutnya, termasuk opsi aplikasi iOS, Android, dan macOS.
Jika tidak ada GUI yang terdeteksi, wizard mencetak instruksi port-forward SSH untuk Control UI alih-alih membuka browser. Jika aset Control UI tidak ada, wizard mencoba membangunnya; fallback adalah pnpm ui:build (menginstal otomatis dependensi UI).

​
Detail mode jarak jauh

Mode jarak jauh mengonfigurasi mesin ini untuk terhubung ke gateway di tempat lain.
Mode jarak jauh tidak menginstal atau mengubah apa pun pada host jarak jauh.
Yang Anda tetapkan:
  • URL gateway jarak jauh (ws://...)
  • Token jika autentikasi gateway jarak jauh diperlukan (direkomendasikan)
  • Jika gateway hanya loopback, gunakan tunneling SSH atau tailnet.
  • Petunjuk discovery:
    • macOS: Bonjour (dns-sd)
    • Linux: Avahi (avahi-browse)

​
Opsi autentikasi dan model

Menggunakan ANTHROPIC_API_KEY jika ada atau meminta kunci, lalu menyimpannya untuk penggunaan daemon.
Alur browser; tempel code#state.Menetapkan agents.defaults.model ke openai/gpt-5.5 melalui runtime Codex saat model belum ditetapkan atau sudah dalam keluarga OpenAI.
Alur pairing browser dengan kode perangkat yang berumur singkat.Menetapkan agents.defaults.model ke openai/gpt-5.5 melalui runtime Codex saat model belum ditetapkan atau sudah dalam keluarga OpenAI.
Menggunakan OPENAI_API_KEY jika ada atau meminta kunci, lalu menyimpan kredensial dalam profil autentikasi.Menetapkan agents.defaults.model ke openai/gpt-5.5 saat model belum ditetapkan, openai/*, atau ref model Codex legacy.
Login browser untuk akun SuperGrok atau X Premium yang memenuhi syarat. Ini adalah jalur xAI yang direkomendasikan untuk sebagian besar pengguna. OpenClaw menyimpan profil autentikasi yang dihasilkan untuk model Grok, Grok web_search, x_search, dan code_execution.
Login browser yang ramah jarak jauh dengan kode singkat alih-alih callback localhost. Gunakan ini dari host SSH, Docker, atau VPS.
Meminta XAI_API_KEY dan mengonfigurasi xAI sebagai provider model. Gunakan ini saat Anda menginginkan kunci API xAI Console alih-alih OAuth langganan.
Meminta OPENCODE_API_KEY (atau OPENCODE_ZEN_API_KEY) dan memungkinkan Anda memilih katalog Zen atau Go. URL penyiapan: opencode.ai/auth.
Menyimpan kunci untuk Anda.
Meminta AI_GATEWAY_API_KEY. Detail selengkapnya: Vercel AI Gateway.
Meminta ID akun, ID gateway, dan CLOUDFLARE_AI_GATEWAY_API_KEY. Detail selengkapnya: Cloudflare AI Gateway.
Konfigurasi ditulis otomatis. Default hosted adalah MiniMax-M3; penyiapan kunci API menggunakan minimax/..., dan penyiapan OAuth menggunakan minimax-portal/.... Detail selengkapnya: MiniMax.
Konfigurasi ditulis otomatis untuk StepFun standar atau Step Plan pada endpoint China atau global. Standar saat ini mencakup step-3.5-flash, dan Step Plan juga mencakup step-3.5-flash-2603. Detail selengkapnya: StepFun.
Meminta SYNTHETIC_API_KEY. Detail selengkapnya: Synthetic.
Meminta Cloud + Local, Cloud only, atau Local only terlebih dahulu. Cloud only menggunakan OLLAMA_API_KEY dengan https://ollama.com. Mode berbasis host meminta URL dasar (default http://127.0.0.1:11434), menemukan model yang tersedia, dan menyarankan default. Cloud + Local juga memeriksa apakah host Ollama tersebut sudah login untuk akses cloud. Detail selengkapnya: Ollama.
Konfigurasi Moonshot (Kimi K2) dan Kimi Coding ditulis otomatis. Detail selengkapnya: Moonshot AI (Kimi + Kimi Coding).
Bekerja dengan endpoint yang kompatibel OpenAI dan kompatibel Anthropic.Onboarding interaktif mendukung pilihan penyimpanan kunci API yang sama seperti alur kunci API provider lainnya:
  • Tempel kunci API sekarang (plaintext)
  • Gunakan referensi secret (ref env atau ref provider yang dikonfigurasi, dengan validasi preflight)
Flag non-interaktif:
  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key (opsional; fallback ke CUSTOM_API_KEY)
  • --custom-provider-id (opsional)
  • --custom-compatibility <openai|openai-responses|anthropic> (opsional; default openai)
  • --custom-image-input / --custom-text-input (opsional; menimpa kapabilitas input model yang diinferensikan)
Membiarkan autentikasi tidak dikonfigurasi.
Perilaku model:
  • Pilih model default dari opsi yang terdeteksi, atau masukkan provider dan model secara manual.
  • Onboarding provider kustom menginferensikan dukungan gambar untuk ID model umum dan hanya bertanya saat nama model tidak diketahui.
  • Saat onboarding dimulai dari pilihan autentikasi provider, pemilih model secara otomatis memprioritaskan provider tersebut. Untuk Volcengine dan BytePlus, preferensi yang sama juga cocok dengan varian coding-plan mereka (volcengine-plan/*, byteplus-plan/*).
  • Jika filter provider pilihan tersebut akan kosong, pemilih fallback ke katalog lengkap alih-alih tidak menampilkan model.
  • Wizard menjalankan pemeriksaan model dan memperingatkan jika model yang dikonfigurasi tidak dikenal atau autentikasinya hilang.
Jalur kredensial dan profil:
  • Profil autentikasi (kunci API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Impor OAuth legacy: ~/.openclaw/credentials/oauth.json
Mode penyimpanan kredensial:
  • Perilaku onboarding bawaan menyimpan kunci API sebagai nilai plaintext di profil auth.
  • --secret-input-mode ref mengaktifkan mode referensi alih-alih penyimpanan kunci plaintext. Dalam setup interaktif, Anda dapat memilih salah satu:
    • ref variabel lingkungan (misalnya keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
    • ref penyedia terkonfigurasi (file atau exec) dengan alias penyedia + id
  • Mode referensi interaktif menjalankan validasi preflight cepat sebelum menyimpan.
    • Ref env: memvalidasi nama variabel + nilai tidak kosong di lingkungan onboarding saat ini.
    • Ref penyedia: memvalidasi konfigurasi penyedia dan menyelesaikan id yang diminta.
    • Jika preflight gagal, onboarding menampilkan kesalahan dan memungkinkan Anda mencoba lagi.
  • Dalam mode non-interaktif, --secret-input-mode ref hanya didukung env.
    • Atur env var penyedia di lingkungan proses onboarding.
    • Flag kunci inline (misalnya --openai-api-key) mengharuskan env var tersebut diatur; jika tidak, onboarding gagal cepat.
    • Untuk penyedia kustom, mode non-interaktif ref menyimpan models.providers.<id>.apiKey sebagai { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
    • Dalam kasus penyedia kustom tersebut, --custom-api-key mengharuskan CUSTOM_API_KEY diatur; jika tidak, onboarding gagal cepat.
  • Kredensial auth Gateway mendukung pilihan plaintext dan SecretRef dalam setup interaktif:
    • Mode token: Buat/simpan token plaintext (bawaan) atau Gunakan SecretRef.
    • Mode kata sandi: plaintext atau SecretRef.
  • Jalur SecretRef token non-interaktif: --gateway-token-ref-env <ENV_VAR>.
  • Setup plaintext yang sudah ada tetap berfungsi tanpa perubahan.
Kiat headless dan server: selesaikan OAuth di mesin dengan browser, lalu salin auth-profiles.json milik agen tersebut (misalnya ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, atau jalur $OPENCLAW_STATE_DIR/... yang sesuai) ke host Gateway. credentials/oauth.json hanya merupakan sumber impor legacy.

​
Output dan internal

Field umum di ~/.openclaw/openclaw.json:
  • agents.defaults.workspace
  • agents.defaults.skipBootstrap saat --skip-bootstrap diteruskan
  • agents.defaults.model / models.providers (jika Minimax dipilih)
  • tools.profile (onboarding lokal secara bawaan menggunakan "coding" saat belum diatur; nilai eksplisit yang sudah ada dipertahankan)
  • gateway.* (mode, bind, auth, tailscale)
  • session.dmScope (onboarding lokal secara bawaan mengatur ini ke per-channel-peer saat belum diatur; nilai eksplisit yang sudah ada dipertahankan)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • Allowlist channel (Slack, Discord, Matrix, Microsoft Teams) saat Anda ikut serta selama prompt (nama diselesaikan menjadi ID jika memungkinkan)
  • skills.install.nodeManager
    • Flag setup --node-manager menerima npm, pnpm, atau bun.
    • Konfigurasi manual tetap dapat mengatur skills.install.nodeManager: "yarn" nanti.
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
  • wizard.securityAcknowledgedAt
openclaw agents add menulis agents.list[] dan bindings opsional. Kredensial WhatsApp ditempatkan di bawah ~/.openclaw/credentials/whatsapp/<accountId>/. Sesi disimpan di bawah ~/.openclaw/agents/<agentId>/sessions/.
Sebagian channel dikirimkan sebagai plugin. Saat dipilih selama setup, wizard meminta untuk menginstal plugin (npm atau jalur lokal) sebelum konfigurasi channel.
RPC wizard Gateway:
  • wizard.start
  • wizard.next
  • wizard.cancel
  • wizard.status
Klien (aplikasi macOS dan Control UI) dapat merender langkah tanpa mengimplementasikan ulang logika onboarding. Perilaku setup Signal:
  • Mengunduh aset rilis yang sesuai
  • Menyimpannya di bawah ~/.openclaw/tools/signal-cli/<version>/
  • Menulis channels.signal.cliPath dalam konfigurasi
  • Build JVM memerlukan Java 21
  • Build native digunakan saat tersedia
  • Windows menggunakan WSL2 dan mengikuti alur signal-cli Linux di dalam WSL

​
Dokumen terkait