Mesin konteks

Sebuah mesin konteks mengontrol bagaimana OpenClaw membangun konteks model untuk setiap proses: pesan mana yang disertakan, bagaimana meringkas riwayat lama, dan bagaimana mengelola konteks lintas batas subagent.

OpenClaw dilengkapi mesin bawaan legacy dan menggunakannya secara default - sebagian besar pengguna tidak perlu mengubah ini. Instal dan pilih mesin Plugin hanya ketika Anda menginginkan perilaku assembly, Compaction, atau pengingatan lintas-sesi yang berbeda.

# Mulai cepat

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

openclaw plugins install @martian-engineering/lossless-claw

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

// openclaw.json
{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}

# Cara kerjanya

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

Untuk harness Codex non-ACP bawaan, OpenClaw menerapkan siklus hidup yang sama dengan memproyeksikan konteks yang telah dirakit ke dalam instruksi developer Codex dan prompt giliran saat ini. Codex tetap memiliki riwayat thread native dan compactor native-nya sendiri.

# Siklus hidup subagent (opsional)

OpenClaw memanggil dua hook siklus hidup subagent opsional:

# Penambahan prompt sistem

Metode assemble dapat mengembalikan string systemPromptAddition. OpenClaw menambahkannya di awal prompt sistem untuk proses tersebut. Ini memungkinkan mesin menyuntikkan panduan pengingatan dinamis, instruksi retrieval, atau petunjuk sadar-konteks tanpa memerlukan file workspace statis.

# Mesin legacy

Mesin legacy bawaan mempertahankan perilaku asli OpenClaw:

• Ingest: no-op (manajer sesi menangani persistensi pesan secara langsung).
• Assemble: pass-through (pipeline sanitize → validate → limit yang ada di runtime menangani assembly konteks).
• Compact: mendelegasikan ke Compaction peringkasan bawaan, yang membuat satu ringkasan pesan lama dan menjaga pesan terbaru tetap utuh.
• Setelah giliran: no-op.

Mesin legacy tidak mendaftarkan alat atau menyediakan systemPromptAddition.

Ketika tidak ada plugins.slots.contextEngine yang ditetapkan (atau diatur ke "legacy"), mesin ini digunakan secara otomatis.

# Mesin Plugin

Sebuah Plugin dapat mendaftarkan mesin konteks menggunakan API Plugin:

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 }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },

    async compact({ sessionId, force }) {
      // Summarize older context
      return { ok: true, compacted: true };
    },
  }));
}

Factory ctx mencakup nilai config, agentDir, dan workspaceDir opsional sehingga Plugin dapat menginisialisasi status per-agen atau per-workspace sebelum hook siklus hidup pertama berjalan.

Lalu aktifkan di config:

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

# Antarmuka ContextEngine

Anggota wajib:

assemble mengembalikan AssembleResult dengan:

compact mengembalikan CompactResult. Ketika Compaction merotasi transkrip aktif, result.sessionId dan result.sessionFile mengidentifikasi sesi penerus yang harus digunakan oleh percobaan ulang atau giliran berikutnya.

Anggota opsional:

# ownsCompaction

ownsCompaction mengontrol apakah auto-compaction bawaan dalam-percobaan milik Pi tetap aktif untuk proses tersebut:

Itu berarti ada dua pola Plugin yang valid:

compact() no-op tidak aman untuk mesin non-owning aktif karena menonaktifkan jalur Compaction normal /compact dan pemulihan overflow untuk slot mesin tersebut.

# Referensi konfigurasi

{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}

# Hubungan dengan Compaction dan memori

# Tips

• Gunakan openclaw doctor untuk memverifikasi mesin Anda dimuat dengan benar.
• Jika beralih mesin, sesi yang ada terus berjalan dengan riwayatnya saat ini. Mesin baru mengambil alih untuk eksekusi berikutnya.
• Kesalahan mesin dicatat dan ditampilkan dalam diagnostik. Jika mesin Plugin gagal didaftarkan atau id mesin yang dipilih tidak dapat diselesaikan, OpenClaw tidak otomatis beralih ke cadangan; eksekusi gagal sampai Anda memperbaiki Plugin atau mengalihkan plugins.slots.contextEngine kembali ke "legacy".
• Untuk pengembangan, gunakan openclaw plugins install -l ./my-engine untuk menautkan direktori Plugin lokal tanpa menyalin.

# Terkait

• Compaction - meringkas percakapan panjang
• Konteks - cara konteks dibangun untuk giliran agen
• Arsitektur Plugin - mendaftarkan Plugin mesin konteks
• Manifes Plugin - kolom manifes Plugin
• Plugin - ikhtisar Plugin