Công cụ ngữ cảnh

Một công cụ ngữ cảnh kiểm soát cách OpenClaw xây dựng ngữ cảnh mô hình cho mỗi lần chạy: những thông điệp nào cần đưa vào, cách tóm tắt lịch sử cũ hơn, và cách quản lý ngữ cảnh qua ranh giới tác tử phụ.

OpenClaw đi kèm công cụ legacy tích hợp sẵn và dùng công cụ này theo mặc định - hầu hết người dùng không bao giờ cần thay đổi điều này. Chỉ cài đặt và chọn một công cụ Plugin khi bạn muốn hành vi lắp ráp, Compaction, hoặc nhớ lại xuyên phiên khác.

# Bắt đầu nhanh

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)
      },
    },
  },
}

# Cách hoạt động

Mỗi khi OpenClaw chạy một lời nhắc mô hình, công cụ ngữ cảnh tham gia tại bốn điểm vòng đời:

Đối với bộ khai thác Codex không phải ACP được đóng gói, OpenClaw áp dụng cùng vòng đời bằng cách chiếu ngữ cảnh đã lắp ráp vào chỉ dẫn dành cho nhà phát triển Codex và lời nhắc lượt hiện tại. Codex vẫn sở hữu lịch sử luồng gốc và bộ Compaction gốc của nó.

# Vòng đời tác tử phụ (tùy chọn)

OpenClaw gọi hai hook vòng đời tác tử phụ tùy chọn:

# Phần bổ sung lời nhắc hệ thống

Phương thức assemble có thể trả về chuỗi systemPromptAddition. OpenClaw thêm chuỗi này vào trước lời nhắc hệ thống cho lần chạy. Điều này cho phép các công cụ chèn hướng dẫn nhớ lại động, chỉ dẫn truy xuất, hoặc gợi ý nhận biết ngữ cảnh mà không cần các tệp không gian làm việc tĩnh.

# Công cụ legacy

Công cụ legacy tích hợp sẵn giữ nguyên hành vi ban đầu của OpenClaw:

• Nạp vào: không làm gì (trình quản lý phiên trực tiếp xử lý việc lưu giữ thông điệp).
• Lắp ráp: truyền qua (đường ống sanitize → validate → limit hiện có trong runtime xử lý việc lắp ráp ngữ cảnh).
• Compact: ủy quyền cho Compaction 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.
• Sau lượt: không làm gì.

Công cụ legacy không đăng ký công cụ hay cung cấp systemPromptAddition.

Khi không đặt plugins.slots.contextEngine (hoặc đặt thành "legacy"), công cụ này được dùng tự động.

# Công cụ Plugin

Một Plugin có thể đăng ký công cụ ngữ cảnh bằng 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 bao gồm các giá trị config, agentDir, và workspaceDir tùy chọn để Plugin có thể khởi tạo trạng thái theo từng tác tử hoặc theo từng không gian làm việc trước khi hook vòng đời đầu tiên chạy.

Sau đó bật trong cấu hình:

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

# Giao diện ContextEngine

Các thành viên bắt buộc:

assemble trả về một AssembleResult với:

compact trả về một CompactResult. Khi Compaction xoay vòng bản ghi đang hoạt động, result.sessionId và result.sessionFile xác định phiên kế nhiệm mà lần thử lại hoặc lượt tiếp theo phải dùng.

Các thành viên tùy chọn:

# ownsCompaction

ownsCompaction kiểm soát liệu Compaction tự động trong lần thử tích hợp sẵn của Pi có tiếp tục được bật cho lần chạy hay không:

Điều đó có nghĩa là có hai mẫu Plugin hợp lệ:

Một compact() không làm gì là không an toàn cho một công cụ không sở hữu đang hoạt động vì nó vô hiệu hóa đường dẫn Compaction thông thường của /compact và khôi phục tràn cho slot công cụ đó.

# Tham chiếu cấu hình

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

# Quan hệ với Compaction và bộ nhớ

# Mẹo

• Dùng openclaw doctor để xác minh bộ máy của bạn đang tải đúng cách.
• Nếu chuyển đổi bộ máy, các phiên hiện có tiếp tục dùng lịch sử hiện tại của chúng. Bộ máy mới sẽ tiếp quản cho các lần chạy trong tương lai.
• Lỗi bộ máy được ghi nhật ký và hiển thị trong chẩn đoán. Nếu một bộ máy Plugin không đăng ký được hoặc không thể phân giải id bộ máy đã chọn, OpenClaw không tự động quay về dự phòng; 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".
• Để phát triển, dùng openclaw plugins install -l ./my-engine để liên kết một thư mục Plugin cục bộ mà không cần sao chép.

# Liên quan

• Compaction - tóm tắt các cuộc trò chuyện dài
• Ngữ cảnh - cách ngữ cảnh được xây dựng cho lượt tác nhân
• Kiến trúc Plugin - đăng ký Plugin bộ máy ngữ cảnh
• Bản kê khai Plugin - các trường bản kê khai Plugin
• Plugins - tổng quan về Plugin