Bộ máy 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: bao gồm những thông điệp nào, cách tóm tắt lịch sử cũ hơn, và cách quản lý ngữ cảnh qua các ranh giới subagent.

OpenClaw đi kèm công cụ legacy tích hợp sẵn và sử 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 prompt mô hình, công cụ ngữ cảnh tham gia tại bốn điểm vòng đời:

Đối với harness Codex không phải ACP được đóng gói kèm, 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 của Codex và prompt của lượt hiện tại. Codex vẫn sở hữu lịch sử luồng gốc và bộ nén gốc của nó.

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

OpenClaw gọi hai hook vòng đời subagent tùy chọn:

Phần bổ sung prompt hệ thống

Phương thức assemble có thể trả về một chuỗi systemPromptAddition. OpenClaw thêm chuỗi này vào trước prompt 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 workspace 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: không thao tác (trình quản lý phiên xử lý trực tiếp việc lưu thông điệp).
• Lắp ráp: chuyển tiếp (pipeline sanitize → validate → limit hiện có trong runtime xử lý 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 thao tác.

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

Khi không đặt plugins.slots.contextEngine (hoặc đặt thành "legacy"), công cụ này được sử 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 agent hoặc theo workspace trước khi hook vòng đời đầu tiên chạy.

Sau đó bật nó 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 sử dụng.

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

Cài đặt runtime

Các hook vòng đời chạy bên trong OpenClaw nhận một đối tượng runtimeSettings tùy chọn. Đây là một bề mặt API producer/consumer nội bộ, chỉ đọc, có phiên bản: OpenClaw tạo nó cho công cụ ngữ cảnh đã chọn, và công cụ ngữ cảnh sử dụng nó bên trong các hook vòng đời. Nó không được hiển thị trực tiếp cho người dùng và không tạo một bề mặt báo cáo chuyên biệt.

• schemaVersion: hiện là 1
• runtime: host OpenClaw, chế độ runtime (normal, fallback, hoặc degraded), và các id harness/runtime tùy chọn
• contextEngineSelection: id công cụ ngữ cảnh đã chọn và nguồn lựa chọn
• executionHost: id host và nhãn cho bề mặt gọi hook
• model: mô hình được yêu cầu, mô hình đã phân giải, provider, và họ mô hình tùy chọn
• limits: ngân sách token prompt và số token đầu ra tối đa khi biết
• diagnostics: các mã lý do fallback đóng và degraded khi biết

Các trường có thể không biết được biểu diễn là null; các trường phân biệt như chế độ runtime và nguồn lựa chọn vẫn không thể null. Các công cụ cũ hơn vẫn tương thích: nếu một công cụ legacy nghiêm ngặt từ chối runtimeSettings như một thuộc tính không xác định, OpenClaw thử lại lệnh gọi vòng đời mà không có nó thay vì cách ly công cụ.

Yêu cầu host

Công cụ ngữ cảnh có thể khai báo yêu cầu năng lực host trên info.hostRequirements. OpenClaw kiểm tra các yêu cầu này trước khi bắt đầu thao tác và fail closed với lỗi mô tả rõ ràng khi runtime đã chọn không thể đáp ứng chúng.

Đối với các lần chạy agent, khai báo assemble-before-prompt khi công cụ phải kiểm soát prompt mô hình thực tế thông qua assemble():

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Use the native Codex or OpenClaw embedded runtime, or select the legacy context engine.",    },  },}

Các lần chạy agent Codex gốc và OpenClaw nhúng đáp ứng assemble-before-prompt. Các backend CLI chung thì không, vì vậy các công cụ yêu cầu năng lực này bị từ chối trước khi tiến trình CLI bắt đầu.

Cách ly lỗi

OpenClaw cô lập công cụ Plugin đã chọn khỏi đường phản hồi lõi. Nếu một công cụ không kế thừa bị thiếu, không vượt qua xác thực hợp đồng, ném lỗi trong khi tạo factory, hoặc ném lỗi từ một phương thức vòng đời, OpenClaw sẽ cách ly công cụ đó cho tiến trình Gateway hiện tại và hạ cấp công việc công cụ ngữ cảnh xuống công cụ legacy tích hợp sẵn. Lỗi được ghi nhật ký kèm thao tác thất bại để người vận hành có thể sửa, cập nhật, hoặc vô hiệu hóa Plugin mà không làm tác tử im lặng.

Các lỗi yêu cầu host thì khác: khi một công cụ khai báo rằng runtime thiếu một năng lực bắt buộc, OpenClaw sẽ đóng thất bại trước khi bắt đầu lượt chạy. Điều đó bảo vệ các công cụ có thể làm hỏng trạng thái nếu chúng chạy trong một host không được hỗ trợ.

ownsCompaction

ownsCompaction kiểm soát việc auto-compaction trong-lần-thử tích hợp sẵn của runtime OpenClaw có tiếp tục được bật cho lượt 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 /compact và compaction khôi phục khi tràn bình thường 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 công cụ của bạn đang tải đúng cách.
• Nếu chuyển đổi công cụ, các phiên hiện có tiếp tục với lịch sử hiện tại của chúng. Công cụ mới tiếp quản các lượt chạy trong tương lai.
• Lỗi công cụ được ghi nhật ký và công cụ Plugin đã chọn bị cách ly cho tiến trình Gateway hiện tại. OpenClaw quay về legacy cho các lượt của người dùng để phản hồi có thể tiếp tục, nhưng bạn vẫn nên sửa, cập nhật, vô hiệu hóa, hoặc gỡ cài đặt Plugin bị hỏng.
• Khi 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 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 của tác tử
• Kiến trúc Plugin - đăng ký Plugin công cụ ngữ cảnh
• Manifest Plugin - các trường manifest của Plugin
• Plugins - tổng quan về Plugin