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

Fundamentals

Ruang kerja agen

Ruang kerja adalah rumah agen: direktori kerja yang digunakan untuk alat berkas dan konteks ruang kerja. Jaga privasinya dan perlakukan sebagai memori.

Ini terpisah dari ~/.openclaw/, yang menyimpan konfigurasi, kredensial, dan sesi.

Lokasi default

  • Default: ~/.openclaw/workspace
  • Jika OPENCLAW_PROFILE ditetapkan dan bukan "default", default menjadi ~/.openclaw/workspace-<profile>.
  • OPENCLAW_WORKSPACE_DIR menggantikan kedua nilai di atas saat ditetapkan.
  • Agen non-default (agents.list[]) tanpa ruang kerja eksplisit diarahkan ke <state-dir>/workspace-<agentId>, bukan ruang kerja default bersama.

Ganti di ~/.openclaw/openclaw.json:

json5
{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",    },  },}

Penggantian per agen: agents.list[].workspace.

openclaw onboard, openclaw configure, atau openclaw setup membuat ruang kerja dan mengisinya dengan berkas bootstrap jika berkas tersebut tidak ada.

Jika Anda sudah mengelola sendiri berkas ruang kerja, nonaktifkan pembuatan berkas bootstrap:

json5
{ agents: { defaults: { skipBootstrap: true } } }

Folder ruang kerja tambahan

Instalasi lama mungkin telah membuat ~/openclaw. Menyimpan beberapa direktori ruang kerja dapat menyebabkan penyimpangan autentikasi atau status yang membingungkan karena hanya satu ruang kerja yang aktif pada satu waktu.

Peta berkas ruang kerja

Berkas standar yang diharapkan OpenClaw di dalam ruang kerja:

AGENTS.md - petunjuk pengoperasian

Petunjuk pengoperasian untuk agen dan cara menggunakan memori. Dimuat pada awal setiap sesi. Tempat yang tepat untuk aturan, prioritas, dan detail "cara berperilaku".

SOUL.md - persona dan nada

Persona, nada, dan batasan. Dimuat setiap sesi. Panduan: panduan kepribadian SOUL.md.

USER.md - siapa penggunanya

Siapa penggunanya dan cara menyapa mereka. Dimuat setiap sesi.

IDENTITY.md - nama, nuansa, emoji

Nama, nuansa, dan emoji agen. Dibuat/diperbarui selama ritual bootstrap.

TOOLS.md - konvensi alat lokal

Catatan tentang alat dan konvensi lokal Anda. Tidak mengendalikan ketersediaan alat; ini hanya panduan.

HEARTBEAT.md - daftar periksa Heartbeat

Daftar periksa kecil opsional untuk eksekusi Heartbeat. Pertahankan agar tetap singkat untuk menghindari pemborosan token.

BOOT.md - daftar periksa saat memulai

Daftar periksa saat memulai yang bersifat opsional dan dijalankan secara otomatis ketika Gateway dimulai ulang (saat hook internal diaktifkan). Pertahankan agar tetap singkat; gunakan alat pesan untuk pengiriman keluar.

BOOTSTRAP.md - ritual eksekusi pertama

Ritual satu kali pada eksekusi pertama. Hanya dibuat untuk ruang kerja yang benar-benar baru. Hapus setelah ritual selesai.

memory/YYYY-MM-DD.md - log memori harian

Log memori harian (satu berkas per hari). Disarankan untuk membaca hari ini + kemarin saat sesi dimulai.

MEMORY.md - memori jangka panjang yang dikurasi (opsional)

Memori jangka panjang yang dikurasi: fakta, preferensi, keputusan, dan ringkasan singkat yang bertahan lama. Simpan log terperinci di memory/YYYY-MM-DD.md agar alat memori dapat mengambilnya sesuai permintaan tanpa menyuntikkannya ke setiap prompt. Muat MEMORY.md hanya dalam sesi utama yang privat (bukan konteks bersama/grup). Lihat Memori untuk alur kerja dan pengosongan memori otomatis.

skills/ - Skills ruang kerja (opsional)

Skills khusus ruang kerja. Lokasi skill dengan prioritas tertinggi untuk ruang kerja tersebut, mendahului skill agen proyek, skill agen pribadi, skill terkelola, skill bawaan, dan skills.load.extraDirs saat nama bertabrakan.

canvas/ - berkas UI Canvas (opsional)

Berkas UI Canvas untuk tampilan node (misalnya canvas/index.html).

Yang TIDAK ada di ruang kerja

Item berikut berada di bawah ~/.openclaw/ dan TIDAK boleh di-commit ke repo ruang kerja:

  • ~/.openclaw/openclaw.json (konfigurasi)
  • ~/.openclaw/state/openclaw.sqlite (status penyiapan dan atestasi ruang kerja bersama)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (profil autentikasi model: OAuth + kunci API)
  • ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite (baris sesi, transkrip, dan status runtime per agen)
  • ~/.openclaw/agents/<agentId>/agent/codex-home/ (akun runtime Codex per agen, konfigurasi, Skills, plugin, dan status thread native)
  • ~/.openclaw/credentials/ (status kanal/penyedia beserta data impor OAuth lama)
  • ~/.openclaw/agents/<agentId>/sessions/ (sumber migrasi lama dan artefak arsip/dukungan)
  • ~/.openclaw/skills/ (Skills terkelola)

Jika Anda perlu memigrasikan sesi atau konfigurasi, salin secara terpisah dan jangan masukkan ke kontrol versi.

Rilis OpenClaw lama menulis sidecar ruang kerja openclaw-workspace-state.json, .openclaw/workspace-state.json, dan .attested. Runtime saat ini hanya menggunakan basis data SQLite bersama untuk status tersebut. Jika Doctor melaporkan salah satu berkas ini, jalankan openclaw doctor --fix; Doctor mengimpor status lama yang valid dan hanya menghapus sumber setelah memverifikasi baris basis data.

Cadangan Git (disarankan, privat)

Perlakukan ruang kerja sebagai memori privat. Masukkan ke repo git privat agar dicadangkan dan dapat dipulihkan.

Jalankan langkah-langkah ini pada mesin tempat Gateway berjalan (di situlah ruang kerja berada).

  • Inisialisasi repo

    Jika git terinstal, ruang kerja yang benar-benar baru diinisialisasi secara otomatis. Jika ruang kerja ini belum menjadi repo, jalankan:

    bash
    cd ~/.openclaw/workspacegit initgit add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/git commit -m "Add agent workspace"

  • Tambahkan remote privat

    UI web GitHub

    1. Buat repositori privat baru di GitHub.
    2. Jangan inisialisasi dengan README (untuk menghindari konflik penggabungan).
    3. Salin URL remote HTTPS.
    4. Tambahkan remote dan lakukan push:
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

    CLI GitHub (gh)

    bash
    gh auth logingh repo create openclaw-workspace --private --source . --remote origin --push

    UI web GitLab

    1. Buat repositori privat baru di GitLab.
    2. Jangan inisialisasi dengan README (untuk menghindari konflik penggabungan).
    3. Salin URL remote HTTPS.
    4. Tambahkan remote dan lakukan push:
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

  • Pembaruan berkelanjutan

    bash
    git statusgit add .git commit -m "Update memory"git push

    • Jangan commit rahasia

    Saran awal untuk .gitignore:

    gitignore
    .DS_Store.env**/*.key**/*.pem**/secrets*

    Memindahkan ruang kerja ke mesin baru

  • Clone repo

    Clone repo ke path yang diinginkan (default ~/.openclaw/workspace).

  • Perbarui konfigurasi

    Tetapkan agents.defaults.workspace ke path tersebut di ~/.openclaw/openclaw.json.

  • Isi berkas yang tidak ada

    Jalankan openclaw setup --workspace <path> untuk mengisi berkas yang tidak ada.

  • Salin sesi (opsional)

    Jika Anda memerlukan sesi, salin ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite secara terpisah dari mesin lama. Salin ~/.openclaw/agents/<agentId>/sessions/ hanya jika Anda juga memerlukan input migrasi lama atau artefak arsip/dukungan.

    • Catatan lanjutan

    • Perutean multiagen dapat menggunakan ruang kerja yang berbeda untuk setiap agen melalui agents.list[].workspace. Lihat Perutean kanal 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

    • Heartbeat - berkas ruang kerja HEARTBEAT.md
    • Sandboxing - akses ruang kerja dalam lingkungan yang menggunakan sandbox
    • Sesi - path penyimpanan sesi
    • Perintah tetap - petunjuk persisten dalam berkas ruang kerja
    Was this useful?
    On this page

    On this page