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

Fundamentals

Mesin konteks

Sebuah mesin konteks mengontrol cara OpenClaw membangun konteks model untuk setiap proses: pesan mana yang disertakan, cara meringkas riwayat lama, dan cara mengelola konteks melintasi batas subagen.

OpenClaw disertai mesin legacy bawaan dan menggunakannya secara default. Instal dan pilih mesin Plugin hanya jika Anda menginginkan perilaku penyusunan, Compaction, atau pengingatan lintas sesi yang berbeda.

Mulai cepat

  • Periksa mesin yang aktif

    bash
    openclaw doctor# atau periksa konfigurasi secara langsung:cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

  • Instal mesin Plugin

    Plugin mesin konteks diinstal seperti Plugin OpenClaw lainnya.

    Dari npm

    bash
    openclaw plugins install @martian-engineering/lossless-claw

    Dari jalur lokal

    bash
    openclaw plugins install -l ./my-context-engine

  • Aktifkan dan pilih mesin

    json5
    // openclaw.json{  plugins: {    slots: {      contextEngine: "lossless-claw", // harus cocok dengan id mesin yang didaftarkan Plugin    },    entries: {      "lossless-claw": {        enabled: true,        // Konfigurasi khusus Plugin ditempatkan di sini (lihat dokumentasi Plugin)      },    },  },}

    Mulai ulang Gateway setelah menginstal dan mengonfigurasinya.

  • Beralih kembali ke mesin lama (opsional)

    Tetapkan contextEngine ke "legacy" (atau hapus kunci tersebut sepenuhnya—"legacy" adalah nilai default).

    • Cara kerjanya

    Setiap kali OpenClaw menjalankan prompt model, mesin konteks berpartisipasi pada empat titik siklus hidup:

    1. Penyerapan

    Dipanggil saat pesan baru ditambahkan ke sesi. Mesin dapat menyimpan atau mengindeks pesan tersebut di penyimpanan datanya sendiri.

    2. Penyusunan

    Dipanggil sebelum setiap proses model. Mesin mengembalikan kumpulan pesan yang terurut (dan systemPromptAddition opsional) yang sesuai dengan anggaran token.

    3. Compaction

    Dipanggil saat jendela konteks penuh, atau saat pengguna menjalankan /compact. Mesin meringkas riwayat lama untuk mengosongkan ruang.

    4. Setelah giliran

    Dipanggil setelah proses selesai. Mesin dapat mempertahankan status, memicu Compaction di latar belakang, atau memperbarui indeks.

    Mesin juga dapat mengimplementasikan metode maintain() opsional untuk pemeliharaan transkrip (penulisan ulang aman melalui runtimeContext.rewriteTranscriptEntries()) setelah bootstrap, giliran yang berhasil, atau Compaction. Tetapkan info.turnMaintenanceMode: "background" untuk menjalankannya sebagai pekerjaan tertunda, bukan memblokir balasan.

    Untuk harness Codex non-ACP yang disertakan, OpenClaw menerapkan siklus hidup yang sama dengan memproyeksikan konteks yang telah disusun ke dalam instruksi pengembang Codex dan prompt giliran saat ini. Codex tetap mengelola riwayat utas native dan pemadat native-nya.

    Siklus hidup subagen (opsional)

    OpenClaw memanggil dua hook siklus hidup subagen opsional:

    prepareSubagentSpawnmethod

    Siapkan status konteks bersama sebelum proses turunan dimulai. Hook menerima kunci sesi induk/turunan, contextMode (isolated atau fork), id/file transkrip yang tersedia, dan TTL opsional. Jika mengembalikan handel pembatalan, OpenClaw akan memanggilnya ketika pemijahan gagal setelah persiapan berhasil. Pemijahan subagen native yang meminta lightContext dan ditetapkan menjadi contextMode="isolated" secara sengaja melewati hook ini agar turunan dimulai dari konteks bootstrap ringan tanpa status pra-pemijahan yang dikelola mesin konteks.

    onSubagentEndedmethod

    Lakukan pembersihan saat sesi subagen selesai atau disapu.

    Tambahan prompt sistem

    Metode assemble dapat mengembalikan string systemPromptAddition. OpenClaw menambahkannya di awal prompt sistem untuk proses tersebut. Hal ini memungkinkan mesin menyuntikkan panduan pengingatan dinamis, instruksi pengambilan, atau petunjuk sadar konteks tanpa memerlukan file ruang kerja statis.

    Mesin lama

    Mesin legacy bawaan mempertahankan perilaku asli OpenClaw:

    • Penyerapan: tanpa operasi (pengelola sesi menangani persistensi pesan secara langsung).
    • Penyusunan: diteruskan tanpa perubahan (pipeline sanitasi → validasi → pembatasan yang ada dalam runtime menangani penyusunan konteks).
    • Compaction: mendelegasikan ke Compaction peringkasan bawaan, yang membuat satu ringkasan pesan lama dan mempertahankan pesan terbaru secara utuh.
    • Setelah giliran: tanpa operasi.

    Mesin lama tidak mendaftarkan alat atau menyediakan systemPromptAddition.

    Jika plugins.slots.contextEngine tidak ditetapkan (atau ditetapkan ke "legacy"), mesin ini digunakan secara otomatis.

    Mesin Plugin

    Sebuah Plugin dapat mendaftarkan mesin konteks menggunakan API Plugin:

    ts
     export default function register(api) {  api.registerContextEngine("my-engine", (ctx) => ({    info: {      id: "my-engine",      name: "My Context Engine",      ownsCompaction: true,    },     async ingest({ sessionId, message, isHeartbeat }) {      // Simpan pesan di penyimpanan data Anda      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // Kembalikan pesan yang sesuai dengan anggaran      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // Ringkas konteks lama      return { ok: true, compacted: true };    },  }));}

    Factory ctx menyertakan nilai config, agentDir, dan workspaceDir opsional agar Plugin dapat menginisialisasi status per agen atau per ruang kerja sebelum pemanggilan siklus hidup pertama. Sebelum pemanggilan assemble() non-lama, host menyelesaikan persiapan prompt memori asinkron yang terdaftar. Pembantu sinkron buildMemorySystemPromptAddition(...) membaca snapshot proses yang tidak dapat diubah tersebut; teruskan konteks alat, kutipan, agen, dan sesi yang diberikan tanpa perubahan.

    Kemudian aktifkan dalam konfigurasi:

    json5
    {  plugins: {    slots: {      contextEngine: "my-engine",    },    entries: {      "my-engine": {        enabled: true,      },    },  },}

    Antarmuka ContextEngine

    Anggota wajib:

    Anggota Jenis Tujuan
    info Properti Id mesin, nama, versi, dan apakah mesin mengelola Compaction
    ingest(params) Metode Menyimpan satu pesan
    assemble(params) Metode Membangun konteks untuk proses model (mengembalikan AssembleResult)
    compact(params) Metode Meringkas/mengurangi konteks

    assemble mengembalikan AssembleResult dengan:

    messagesMessage[]required

    Pesan terurut yang akan dikirim ke model.

    estimatedTokensnumberrequired

    Estimasi mesin atas jumlah total token dalam konteks yang telah disusun. OpenClaw menggunakan ini untuk keputusan ambang Compaction dan pelaporan diagnostik.

    systemPromptAdditionstring

    Ditambahkan di awal prompt sistem.

    promptAuthority"assembled" | "preassembly_may_overflow"

    Mengontrol estimasi token mana yang digunakan runner untuk pemeriksaan awal luapan secara preventif. Nilai defaultnya adalah "assembled", yang berarti hanya estimasi prompt yang telah disusun yang diperiksa untuk mesin yang tidak mengelola Compaction. Mesin yang menetapkan ownsCompaction: true mengelola penerimaan promptnya sendiri, sehingga secara default OpenClaw melewati pemeriksaan awal pra-prompt generik. Tetapkan "preassembly_may_overflow" hanya jika tampilan yang Anda susun dapat menyembunyikan risiko luapan dalam transkrip yang mendasarinya; runner kemudian mempertahankan pemeriksaan awal generik dan mengambil nilai maksimum antara estimasi yang telah disusun dan estimasi riwayat sesi pra-penyusunan (tanpa jendela) saat memutuskan apakah perlu melakukan Compaction secara preventif. Dalam kedua kasus, pesan yang Anda kembalikan tetap menjadi apa yang dilihat model—promptAuthority hanya memengaruhi pemeriksaan awal.

    contextProjectionContextEngineProjection

    Siklus hidup proyeksi opsional untuk host dengan utas backend persisten (misalnya app-server Codex). mode: "thread_bootstrap" dengan epoch yang stabil meminta host menyuntikkan konteks yang telah disusun sekali per epoch dan menggunakan kembali utas backend hingga epoch berubah, alih-alih memproyeksikan ulang setiap giliran. Hilangkan bidang ini untuk proyeksi normal per giliran.

    compact mengembalikan CompactResult. Saat Compaction mengubah identitas sesi aktif, result.sessionTarget (ContextEngineSessionTarget bertipe yang membawa identitas sesi dan cakupan penyimpanan) mengidentifikasi sesi penerus yang harus digunakan oleh percobaan ulang atau giliran berikutnya; result.sessionId mencerminkan id penerus tersebut.

    Anggota opsional:

    Anggota Jenis Tujuan
    bootstrap(params) Metode Menginisialisasi status mesin untuk sebuah sesi. Dipanggil sekali saat mesin pertama kali menemukan sesi (misalnya, mengimpor riwayat).
    maintain(params) Metode Pemeliharaan transkrip setelah bootstrap, giliran yang berhasil, atau Compaction. Gunakan runtimeContext.rewriteTranscriptEntries() untuk penulisan ulang yang aman.
    ingestBatch(params) Metode Menyerap giliran yang selesai sebagai batch. Dipanggil setelah proses selesai, dengan semua pesan dari giliran tersebut sekaligus.
    afterTurn(params) Metode Pekerjaan siklus hidup pascaproses (mempertahankan status, memicu Compaction di latar belakang).
    prepareSubagentSpawn(params) Metode Menyiapkan status bersama untuk sesi turunan sebelum dimulai.
    onSubagentEnded(params) Metode Melakukan pembersihan setelah subagen berakhir.
    dispose() Metode Melepaskan sumber daya. Dipanggil selama penghentian Gateway atau pemuatan ulang Plugin—bukan per sesi.

    Pengaturan runtime

    Hook siklus hidup yang berjalan di dalam OpenClaw menerima objek runtimeSettings opsional. Ini adalah permukaan API produsen/konsumen internal hanya-baca dan berversi: OpenClaw memproduksinya untuk mesin konteks yang dipilih, dan mesin konteks mengonsumsinya di dalam hook siklus hidup. Objek ini tidak dirender langsung kepada pengguna dan tidak membuat permukaan pelaporan khusus.

    • schemaVersion: saat ini 1
    • runtime: host OpenClaw, mode runtime (normal, fallback, atau degraded), serta id harness/runtime opsional
    • contextEngineSelection: id mesin konteks yang dipilih dan sumber pemilihan
    • executionHost: id dan label host untuk permukaan yang memanggil hook
    • model: model yang diminta, model yang ditetapkan, penyedia, dan keluarga model opsional
    • limits: anggaran token prompt dan token keluaran maksimum jika diketahui
    • diagnostics: kode alasan fallback tertutup dan kondisi terdegradasi jika diketahui

    Bidang yang nilainya mungkin tidak diketahui direpresentasikan sebagai null; bidang diskriminator seperti mode runtime dan sumber pemilihan tetap tidak dapat bernilai null. Mesin lama tetap kompatibel: jika mesin lama yang ketat menolak runtimeSettings sebagai properti yang tidak dikenal, OpenClaw mencoba kembali pemanggilan siklus hidup tanpa properti tersebut alih-alih mengarantina mesin.

    Persyaratan host

    Mesin konteks dapat mendeklarasikan persyaratan kemampuan host pada info.hostRequirements. OpenClaw memeriksa persyaratan ini sebelum memulai operasi dan gagal secara tertutup dengan pesan kesalahan deskriptif ketika runtime yang dipilih tidak dapat memenuhinya.

    Untuk proses agen, deklarasikan assemble-before-prompt ketika mesin harus mengendalikan prompt model yang sebenarnya melalui assemble():

    ts
    info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Gunakan runtime native Codex atau runtime tertanam OpenClaw, atau pilih mesin konteks lama.",    },  },}

    Proses agen native Codex dan agen tertanam OpenClaw memenuhi assemble-before-prompt. Backend CLI generik tidak memenuhinya, sehingga mesin yang memerlukannya ditolak sebelum proses CLI dimulai.

    Isolasi kegagalan

    OpenClaw mengisolasi mesin plugin yang dipilih dari jalur balasan inti. Jika mesin nonlama tidak tersedia, gagal dalam validasi kontrak, melempar kesalahan saat pembuatan factory, atau melempar kesalahan dari metode siklus hidup, OpenClaw mengarantina mesin tersebut untuk proses Gateway saat ini dan menurunkan pekerjaan mesin konteks ke mesin bawaan legacy. Kesalahan dicatat bersama operasi yang gagal agar operator dapat memperbaiki, memperbarui, atau menonaktifkan plugin tanpa membuat agen berhenti merespons.

    Kegagalan persyaratan host berbeda: ketika mesin mendeklarasikan bahwa suatu runtime tidak memiliki kemampuan yang diwajibkan, OpenClaw gagal secara tertutup sebelum memulai proses. Hal itu melindungi mesin yang dapat merusak status jika dijalankan pada host yang tidak didukung.

    ownsCompaction

    ownsCompaction mengontrol apakah pemadatan otomatis bawaan dalam percobaan milik runtime OpenClaw tetap diaktifkan untuk proses tersebut:

    ownsCompaction: true

    Mesin memiliki perilaku pemadatan. OpenClaw menonaktifkan pemadatan otomatis bawaan runtime OpenClaw dan pemeriksaan awal luapan generik sebelum prompt untuk proses tersebut, dan implementasi compact() milik mesin bertanggung jawab atas /compact, pemadatan pemulihan luapan penyedia, serta pemadatan proaktif apa pun yang ingin dilakukannya dalam afterTurn(). OpenClaw tetap menjalankan perlindungan luapan sebelum prompt ketika mesin mengembalikan promptAuthority: "preassembly_may_overflow" dari assemble().

    ownsCompaction: false atau tidak ditetapkan

    Pemadatan otomatis bawaan runtime OpenClaw mungkin tetap berjalan selama eksekusi prompt, tetapi metode compact() milik mesin aktif tetap dipanggil untuk /compact dan pemulihan luapan.

    Artinya, terdapat dua pola plugin yang valid:

    Mode kepemilikan

    Implementasikan algoritme pemadatan Anda sendiri dan tetapkan ownsCompaction: true.

    Mode delegasi

    Tetapkan ownsCompaction: false dan buat compact() memanggil delegateCompactionToRuntime(...) dari openclaw/plugin-sdk/core untuk menggunakan perilaku pemadatan bawaan OpenClaw.

    Implementasi tanpa operasi pada compact() tidak aman untuk mesin aktif yang tidak memiliki pemadatan karena implementasi tersebut menonaktifkan jalur pemadatan normal /compact dan pemulihan luapan untuk slot mesin tersebut.

    Referensi konfigurasi

    json5
    {  plugins: {    slots: {      // Pilih mesin konteks aktif. Default: "legacy".      // Tetapkan ke id plugin untuk menggunakan mesin plugin.      contextEngine: "legacy",    },  },}

    Hubungan dengan pemadatan dan memori

    Compaction

    Compaction adalah salah satu tanggung jawab mesin konteks. Mesin lama mendelegasikan ke peringkasan bawaan OpenClaw. Mesin plugin dapat mengimplementasikan strategi pemadatan apa pun (ringkasan DAG, pengambilan vektor, dan sebagainya).

    Plugin memori

    Plugin memori (plugins.slots.memory) terpisah dari mesin konteks. Plugin memori menyediakan pencarian/pengambilan; mesin konteks mengontrol apa yang dilihat model. Keduanya dapat bekerja bersama—mesin konteks dapat menggunakan data plugin memori selama perakitan. Mesin plugin yang ingin menggunakan jalur prompt memori aktif harus menggunakan buildMemorySystemPromptAddition(...) dari openclaw/plugin-sdk/core, yang mengonversi bagian prompt memori yang disiapkan host menjadi systemPromptAddition yang siap ditambahkan di awal tanpa mengekspos tata letak plugin memori.

    Pemangkasan sesi

    Pemangkasan hasil alat lama dalam memori tetap berjalan terlepas dari mesin konteks mana yang aktif.

    Kiat

    • Gunakan openclaw doctor untuk memverifikasi bahwa mesin Anda dimuat dengan benar.
    • Saat beralih mesin, sesi yang ada tetap menggunakan riwayat saat ini. Mesin baru mengambil alih untuk proses berikutnya.
    • Kesalahan mesin dicatat dan mesin plugin yang dipilih dikarantina untuk proses Gateway saat ini. OpenClaw melakukan fallback ke legacy untuk giliran pengguna agar balasan dapat berlanjut, tetapi Anda tetap harus memperbaiki, memperbarui, menonaktifkan, atau menghapus instalasi plugin yang rusak.
    • Untuk pengembangan, gunakan openclaw plugins install -l ./my-engine untuk menautkan direktori plugin lokal tanpa menyalinnya.

    Terkait

    Was this useful?
    On this page

    On this page