Langsung ke konten utama

​
Ruang kerja agen

Ruang kerja adalah rumah agen. Ini adalah satu-satunya direktori kerja yang digunakan untuk alat file dan untuk konteks ruang kerja. Jaga agar tetap privat dan perlakukan sebagai memori. Ini terpisah dari ~/.openclaw/, yang menyimpan konfigurasi, kredensial, dan sesi. Penting: ruang kerja adalah cwd default, bukan sandbox kaku. Alat menyelesaikan path relatif terhadap ruang kerja, tetapi path absolut masih dapat menjangkau lokasi lain di host kecuali sandboxing diaktifkan. Jika Anda memerlukan isolasi, gunakan agents.defaults.sandbox (dan/atau konfigurasi sandbox per agen). Saat sandboxing diaktifkan dan workspaceAccess bukan "rw", alat beroperasi di dalam ruang kerja sandbox di bawah ~/.openclaw/sandboxes, bukan ruang kerja host Anda.

​
Lokasi default

  • Default: ~/.openclaw/workspace
  • Jika OPENCLAW_PROFILE disetel dan bukan "default", default menjadi ~/.openclaw/workspace-<profile>.
  • Timpa di ~/.openclaw/openclaw.json:
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}
openclaw onboard, openclaw configure, atau openclaw setup akan membuat ruang kerja dan mengisi file bootstrap jika belum ada. Salinan seed sandbox hanya menerima file reguler di dalam ruang kerja; alias symlink/hardlink yang mengarah ke luar ruang kerja sumber akan diabaikan. Jika Anda sudah mengelola file ruang kerja sendiri, Anda dapat menonaktifkan pembuatan file bootstrap: 
{ agent: { skipBootstrap: true } }

​
Folder ruang kerja tambahan

Instalasi lama mungkin telah membuat ~/openclaw. Menyimpan beberapa direktori ruang kerja sekaligus dapat menyebabkan autentikasi atau status menjadi membingungkan, karena hanya satu ruang kerja yang aktif pada satu waktu. Rekomendasi: pertahankan satu ruang kerja aktif. Jika Anda tidak lagi menggunakan folder tambahan, arsipkan atau pindahkan ke Trash (misalnya trash ~/openclaw). Jika Anda memang sengaja menyimpan beberapa ruang kerja, pastikan agents.defaults.workspace menunjuk ke yang aktif. openclaw doctor akan memberi peringatan ketika mendeteksi direktori ruang kerja tambahan.

​
Peta file ruang kerja (arti tiap file)

Ini adalah file standar yang diharapkan OpenClaw ada di dalam ruang kerja:
  • AGENTS.md
    • Instruksi operasional untuk agen dan cara agen harus menggunakan memori.
    • Dimuat pada awal setiap sesi.
    • Tempat yang baik untuk aturan, prioritas, dan detail “cara berperilaku”.
  • SOUL.md
  • USER.md
    • Siapa pengguna dan bagaimana menyapanya.
    • Dimuat setiap sesi.
  • IDENTITY.md
    • Nama, vibe, dan emoji agen.
    • Dibuat/diperbarui selama ritual bootstrap.
  • TOOLS.md
    • Catatan tentang alat dan konvensi lokal Anda.
    • Tidak mengontrol ketersediaan alat; ini hanya panduan.
  • HEARTBEAT.md
    • Daftar periksa kecil opsional untuk eksekusi heartbeat.
    • Buat tetap singkat untuk menghindari pemborosan token.
  • BOOT.md
    • Daftar periksa startup opsional yang dijalankan saat Gateway dimulai ulang ketika hook internal diaktifkan.
    • Buat tetap singkat; gunakan alat message untuk pengiriman keluar.
  • BOOTSTRAP.md
    • Ritual sekali jalan untuk eksekusi pertama.
    • Hanya dibuat untuk ruang kerja yang benar-benar baru.
    • Hapus setelah ritual selesai.
  • memory/YYYY-MM-DD.md
    • Log memori harian (satu file per hari).
    • Disarankan membaca hari ini + kemarin saat memulai sesi.
  • MEMORY.md (opsional)
    • Memori jangka panjang yang dikurasi.
    • Hanya dimuat di sesi utama dan privat (bukan konteks bersama/grup).
Lihat Memori untuk alur kerja dan flush memori otomatis.
  • skills/ (opsional)
    • Skills khusus ruang kerja.
    • Lokasi skill dengan prioritas tertinggi untuk ruang kerja tersebut.
    • Menimpa skill agen proyek, skill agen pribadi, skill terkelola, skill bawaan, dan skills.load.extraDirs ketika nama bertabrakan.
  • canvas/ (opsional)
    • File UI canvas untuk tampilan node (misalnya canvas/index.html).
Jika ada file bootstrap yang hilang, OpenClaw menyisipkan penanda “file missing” ke dalam sesi dan melanjutkan. File bootstrap yang besar dipotong saat disisipkan; sesuaikan batas dengan agents.defaults.bootstrapMaxChars (default: 20000) dan agents.defaults.bootstrapTotalMaxChars (default: 150000). openclaw setup dapat membuat ulang default yang hilang tanpa menimpa file yang ada.

​
Apa yang TIDAK ada di ruang kerja

Ini berada di bawah ~/.openclaw/ dan TIDAK boleh dikomit ke repo ruang kerja:
  • ~/.openclaw/openclaw.json (konfigurasi)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (profil autentikasi model: OAuth + API key)
  • ~/.openclaw/credentials/ (status channel/provider plus data impor OAuth lama)
  • ~/.openclaw/agents/<agentId>/sessions/ (transkrip sesi + metadata)
  • ~/.openclaw/skills/ (skill terkelola)
Jika Anda perlu memigrasikan sesi atau konfigurasi, salin secara terpisah dan jangan masukkan ke version control.

​
Pencadangan Git (direkomendasikan, privat)

Perlakukan ruang kerja sebagai memori privat. Masukkan ke repo git privat agar dicadangkan dan dapat dipulihkan. Jalankan langkah-langkah ini di mesin tempat Gateway berjalan (di situlah ruang kerja berada).

​
1) Inisialisasi repo

Jika git terpasang, ruang kerja yang benar-benar baru akan diinisialisasi secara otomatis. Jika ruang kerja ini belum menjadi repo, jalankan: 
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

​
2) Tambahkan remote privat (opsi ramah pemula)

Opsi A: UI web GitHub
  1. Buat repository privat baru di GitHub.
  2. Jangan inisialisasi dengan README (menghindari konflik merge).
  3. Salin URL remote HTTPS.
  4. Tambahkan remote dan push:
git branch -M main
git remote add origin <https-url>
git push -u origin main
Opsi B: GitHub CLI (gh) 
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
Opsi C: UI web GitLab
  1. Buat repository privat baru di GitLab.
  2. Jangan inisialisasi dengan README (menghindari konflik merge).
  3. Salin URL remote HTTPS.
  4. Tambahkan remote dan push:
git branch -M main
git remote add origin <https-url>
git push -u origin main

​
3) Pembaruan berkelanjutan

git status
git add .
git commit -m "Update memory"
git push

​
Jangan komit rahasia

Bahkan di repo privat, hindari menyimpan rahasia di ruang kerja:
  • API key, token OAuth, kata sandi, atau kredensial privat.
  • Apa pun di bawah ~/.openclaw/.
  • Dump mentah chat atau lampiran sensitif.
Jika Anda harus menyimpan referensi sensitif, gunakan placeholder dan simpan rahasia sebenarnya di tempat lain (pengelola kata sandi, variabel lingkungan, atau ~/.openclaw/). Contoh awal .gitignore yang disarankan: 
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

​
Memindahkan ruang kerja ke mesin baru

  1. Clone repo ke path yang diinginkan (default ~/.openclaw/workspace).
  2. Setel agents.defaults.workspace ke path tersebut di ~/.openclaw/openclaw.json.
  3. Jalankan openclaw setup --workspace <path> untuk mengisi file yang masih kurang.
  4. Jika Anda memerlukan sesi, salin ~/.openclaw/agents/<agentId>/sessions/ dari mesin lama secara terpisah.

​
Catatan lanjutan

  • Perutean multi-agen dapat menggunakan ruang kerja yang berbeda per agen. Lihat Perutean channel untuk konfigurasi perutean.
  • Jika agents.defaults.sandbox diaktifkan, sesi non-utama dapat menggunakan ruang kerja sandbox per sesi di bawah agents.defaults.sandbox.workspaceRoot.

​
Terkait

  • Standing Orders — instruksi persisten dalam file ruang kerja
  • Heartbeat — file ruang kerja HEARTBEAT.md
  • Sesi — path penyimpanan sesi
  • Sandboxing — akses ruang kerja di lingkungan tersandbox