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 đư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 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. Chỉ cài đặt và chọn công cụ Plugin khi bạn muốn cách tập hợp, Compaction hoặc truy hồi giữa các phiên hoạt động khác đi.

Bắt đầu nhanh

openclaw doctor# hoặc kiểm tra trực tiếp cấu hình: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", // phải khớp với mã định danh công cụ đã đăng ký của Plugin    },    entries: {      "lossless-claw": {        enabled: true,        // Cấu hình dành riêng cho Plugin đặt tại đây (xem tài liệu của Plugin)      },    },  },}

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 thời điểm trong vòng đời:

Các công cụ cũng có thể triển khai phương thức maintain() không bắt buộc để bảo trì bản ghi hội thoại (ghi lại an toàn thông qua runtimeContext.rewriteTranscriptEntries()) sau khi khởi tạo, sau một lượt thành công hoặc sau Compaction. Đặt info.turnMaintenanceMode: "background" để chạy phương thức này dưới dạng công việc trì hoãn thay vì chặn phản hồi.

Đối với bộ khung Codex không dùng ACP đi kèm, OpenClaw áp dụng cùng vòng đời bằng cách chiếu ngữ cảnh đã tập hợp vào chỉ dẫn dành cho nhà phát triển của Codex và lời nhắc của lượt hiện tại. Codex vẫn quản lý lịch sử luồng gốc và trình thu gọn gốc của riêng mình.

Vòng đời subagent (không bắt buộc)

OpenClaw gọi hai hook vòng đời subagent không bắt buộc:

Phần bổ sung cho lời nhắc 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 đầu 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 truy hồi động, chỉ dẫn truy xuất hoặc gợi ý nhận biết ngữ cảnh mà không yêu cầu các tệp không gian làm việc tĩnh.

Công cụ cũ

Công cụ legacy tích hợp sẵn duy trì hành vi ban đầu của OpenClaw:

• Tiếp nhận: không thực hiện thao tác nào (trình quản lý phiên trực tiếp xử lý việc lưu trữ thông điệp).
• Tập hợp: chuyển tiếp nguyên trạng (pipeline làm sạch → xác thực → giới hạn hiện có trong runtime xử lý việc tập hợp ngữ cảnh).
• Thu gọn: ủ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 cho 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 thực hiện thao tác nào.

Công cụ cũ không đăng ký công cụ hỗ trợ hoặc cung cấp systemPromptAddition.

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

Các công cụ Plugin

Plugin có thể đăng ký một 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 }) {      // Lưu thông điệp trong kho dữ liệu      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // 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: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // Tóm tắt ngữ cảnh cũ hơn      return { ok: true, compacted: true };    },  }));}

Factory ctx bao gồm các giá trị config, agentDir và workspaceDir không bắt buộc để các Plugin có thể khởi tạo trạng thái theo từng agent hoặc từng không gian làm việc trước lần gọi vòng đời đầu tiên. Trước một lần gọi assemble() không thuộc chế độ cũ, máy chủ hoàn tất việc chuẩn bị lời nhắc bộ nhớ bất đồng bộ đã đăng ký. Hàm trợ giúp đồng bộ buildMemorySystemPromptAddition(...) đọc ảnh chụp nhanh bất biến của lần chạy đó; hãy truyền nguyên trạng ngữ cảnh công cụ, trích dẫn, agent và phiên được cung cấp.

Sau đó bật công cụ 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 thay đổi danh tính phiên đang hoạt động, result.sessionTarget (một ContextEngineSessionTarget có kiểu, mang danh tính phiên và phạm vi kho lưu trữ) 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; result.sessionId phản ánh mã định danh kế nhiệm.

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

Cài đặt runtime

Các hook vòng đời chạy bên trong OpenClaw nhận một đối tượng runtimeSettings không bắt buộc. Đây là một bề mặt API nội bộ chỉ đọc, có phiên bản, theo mô hình bên tạo/bên sử dụng: OpenClaw tạo đối tượng này 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. Đối tượng này không được hiển thị trực tiếp cho người dùng và không tạo ra một bề mặt báo cáo chuyên biệt.

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

Các trường có thể không xác định được biểu diễn bằng 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ũ vẫn tương thích: nếu một công cụ cũ nghiêm ngặt từ chối runtimeSettings vì đây là một thuộc tính không xác định, OpenClaw sẽ thử lại lệnh gọi vòng đời mà không có thuộc tính đó thay vì cách ly công cụ.

Yêu cầu đối với máy chủ

Các công cụ ngữ cảnh có thể khai báo yêu cầu về khả năng của máy chủ 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à dừng theo hướng đóng 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ượt chạy của tác tử, hãy 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:        "Hãy sử dụng Codex gốc hoặc runtime nhúng OpenClaw, hoặc chọn công cụ ngữ cảnh cũ.",    },  },}

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

Cô lập lỗi

OpenClaw cô lập công cụ Plugin đã chọn khỏi đường dẫn phản hồi cốt lõi. Nếu một công cụ không phải loại cũ bị thiếu, không vượt qua bước xác thực hợp đồng, phát sinh ngoại lệ khi tạo factory hoặc phát sinh ngoại lệ từ một phương thức vòng đời, OpenClaw sẽ cách ly công cụ đó trong tiến trình Gateway hiện tại và hạ cấp công việc của 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ý cùng thao tác gặp lỗi để người vận hành có thể sửa chữa, cập nhật hoặc vô hiệu hóa Plugin mà không khiến tác tử ngừng phản hồi.

Lỗi yêu cầu máy chủ là trường hợp khác: khi một công cụ khai báo rằng runtime thiếu một khả năng bắt buộc, OpenClaw sẽ dừng theo hướng đóng 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ạy trên máy chủ không được hỗ trợ.

ownsCompaction

ownsCompaction kiểm soát việc tính năng tự động Compaction trong mỗi lần thử được tích hợp sẵn của runtime OpenClaw có tiếp tụ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 thực hiện thao tác nào là không an toàn đối với công cụ không sở hữu đang hoạt động vì nó vô hiệu hóa đường dẫn Compaction /compact thông thường và khôi phục sau tình trạng tràn cho khe công cụ đó.

Tham chiếu cấu hình

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

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

Mẹo

• Sử dụng openclaw doctor để xác minh công cụ của bạn đang tải đúng cách.
• Khi 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ô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 trong tiến trình Gateway hiện tại. OpenClaw chuyển sang legacy cho các lượt tương tác của người dùng để có thể tiếp tục phản hồi, nhưng bạn vẫn nên sửa chữa, cập nhật, vô hiệu hóa hoặc gỡ cài đặt Plugin bị lỗi.
• Để phát triển, hãy sử dụng openclaw plugins install -l ./my-engine nhằm 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 các lượt tương tác của tác tử
• Kiến trúc Plugin - đăng ký các Plugin công cụ ngữ cảnh
• Tệp kê khai Plugin - các trường trong tệp kê khai Plugin
• Plugin - tổng quan về Plugin