​

Context Engine

​

Bắt đầu nhanh

openclaw doctor
# hoặc kiểm tra cấu hình trực tiếp:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

​

Cài đặt plugin engine ngữ cảnh

# Cài đặt từ npm
openclaw plugins install @martian-engineering/lossless-claw

# Hoặc cài đặt từ đường dẫn địa phương (dành cho phát triển)
openclaw plugins install -l ./my-context-engine

// openclaw.json
{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // phải khớp với id engine đã đăng ký của plugin
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Cấu hình cụ thể của plugin nằm ở đây (xem tài liệu của plugin)
      },
    },
  },
}

​

Cách hoạt động

1. Ingest — được gọi khi một thông điệp mới được thêm vào session. Engine có thể lưu trữ hoặc lập chỉ mục thông điệp trong kho dữ liệu của nó.
2. Assemble — được gọi trước mỗi lần chạy mô hình. Engine trả về một tập hợp thông điệp có thứ tự (và một systemPromptAddition tùy chọn) phù hợp với ngân sách token.
3. Compact — được gọi khi cửa sổ ngữ cảnh đầy, hoặc khi người dùng chạy /compact. Engine tóm tắt lịch sử cũ hơn để giải phóng không gian.
4. After turn — được gọi sau khi một lần chạy hoàn tất. Engine có thể lưu trữ trạng thái, kích hoạt nén nền, hoặc cập nhật chỉ mục.

​

Vòng đời subagent (tùy chọn)

• onSubagentEnded — dọn dẹp khi một session subagent hoàn tất hoặc bị quét.

​

Thêm vào system prompt

​

Engine cũ

• Ingest: không thực hiện gì (trình quản lý session xử lý lưu trữ thông điệp trực tiếp).
• Assemble: truyền qua (pipeline hiện tại sanitize → validate → limit trong runtime xử lý lắp ráp ngữ cảnh).
• Compact: ủy quyền cho nén tóm tắt tích hợp sẵn, tạo một bản tóm tắt duy nhất của các thông điệp cũ hơn và giữ nguyên các thông điệp gần đây.
• After turn: không thực hiện gì.

​

Plugin engines

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    info: {
      id: "my-engine",
      name: "My Context Engine",
      ownsCompaction: true,
    },

    async ingest({ sessionId, message, isHeartbeat }) {
      // Lưu trữ thông điệp trong kho dữ liệu của bạn
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget }) {
      // Trả về các thông điệp phù hợp với ngân sách
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: "Use lcm_grep to search history...",
      };
    },

    async compact({ sessionId, force }) {
      // Tóm tắt ngữ cảnh cũ hơn
      return { ok: true, compacted: true };
    },
  }));
}

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

​

Giao diện ContextEngine

• messages — các thông điệp có thứ tự để gửi đến mô hình.
• estimatedTokens (bắt buộc, number) — ước tính của engine về tổng số token trong ngữ cảnh đã lắp ráp. OpenClaw sử dụng điều này cho các quyết định ngưỡng nén và báo cáo chẩn đoán.
• systemPromptAddition (tùy chọn, string) — được thêm vào đầu system prompt.

​

ownsCompaction

• true — engine sở hữu hành vi nén. OpenClaw vô hiệu hóa nén tự động tích hợp sẵn của Pi cho lần chạy đó, và việc thực hiện compact() của engine chịu trách nhiệm cho /compact, nén phục hồi tràn, và bất kỳ nén chủ động nào mà nó muốn thực hiện trong afterTurn().
• false hoặc không đặt — nén tự động tích hợp sẵn của Pi vẫn có thể chạy trong quá trình thực hiện prompt, nhưng phương thức compact() của engine đang hoạt động vẫn được gọi cho /compact và nén phục hồi tràn.

• Chế độ sở hữu — thực hiện thuật toán nén của riêng bạn và đặt ownsCompaction: true.
• Chế độ ủy quyền — đặt ownsCompaction: false và để compact() gọi delegateCompactionToRuntime(...) từ openclaw/plugin-sdk/core để sử dụng hành vi nén tích hợp sẵn của OpenClaw.

​

Tham khảo cấu hình

{
  plugins: {
    slots: {
      // Chọn engine ngữ cảnh đang hoạt động. Mặc định: "legacy".
      // Đặt thành một id plugin để sử dụng engine plugin.
      contextEngine: "legacy",
    },
  },
}

​

Mối quan hệ với nén và bộ nhớ

• Nén là một trách nhiệm của context engine. Engine cũ ủy quyền cho tóm tắt tích hợp sẵn của OpenClaw. Các engine plugin có thể thực hiện bất kỳ chiến lược nén nào (tóm tắt DAG, truy xuất vector, v.v.).
• Plugin bộ nhớ (plugins.slots.memory) tách biệt với context engines. Plugin bộ nhớ cung cấp tìm kiếm/truy xuất; context engines kiểm soát những gì mô hình thấy. Chúng có thể hoạt động cùng nhau — một context engine có thể sử dụng dữ liệu plugin bộ nhớ trong quá trình lắp ráp.
• Cắt tỉa session (cắt bớt kết quả công cụ cũ trong bộ nhớ) vẫn chạy bất kể context engine nào đang hoạt động.

​

Mẹo

• Sử dụng openclaw doctor để xác minh engine của bạn đang tải đúng cách.
• Nếu chuyển đổi engine, các session hiện tại tiếp tục với lịch sử hiện tại của chúng. Engine mới tiếp quản cho các lần chạy trong tương lai.
• Lỗi engine được ghi lại và hiển thị trong chẩn đoán. Nếu một plugin engine không đăng ký được hoặc id engine đã chọn không thể được giải quyết, OpenClaw không tự động quay lại; các lần chạy sẽ thất bại cho đến khi bạn sửa plugin hoặc chuyển plugins.slots.contextEngine về "legacy".
• Đối với phát triển, sử dụng openclaw plugins install -l ./my-engine để liên kết một thư mục plugin địa phương mà không cần sao chép.