Chuyển đến nội dung chính

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

TypeBox là thư viện schema ưu tiên TypeScript. Chúng tôi dùng thư viện này để định nghĩa giao thức WebSocket Gateway (bắt tay, yêu cầu/phản hồi, sự kiện máy chủ). Các schema đó điều khiển xác thực lúc chạy, xuất JSON Schema và sinh mã Swift cho ứng dụng macOS. Một nguồn sự thật duy nhất; mọi thứ khác đều được tạo sinh. Nếu bạn muốn xem ngữ cảnh giao thức ở mức cao hơn, hãy bắt đầu với kiến trúc Gateway.

​
Mô hình tư duy (30 giây)

Mọi thông điệp WS của Gateway là một trong ba frame:
  • Yêu cầu: { type: "req", id, method, params }
  • Phản hồi: { type: "res", id, ok, payload | error }
  • Sự kiện: { type: "event", event, payload, seq?, stateVersion? }
Frame đầu tiên phải là một yêu cầu connect. Sau đó, máy khách có thể gọi các phương thức (ví dụ health, send, chat.send) và đăng ký theo dõi sự kiện (ví dụ presence, tick, agent). Luồng kết nối (tối thiểu): 
Client                    Gateway
  |---- req:connect -------->|
  |<---- res:hello-ok --------|
  |<---- event:tick ----------|
  |---- req:health ---------->|
  |<---- res:health ----------|
Các phương thức + sự kiện phổ biến:
Danh mụcVí dụGhi chú
Lõiconnect, health, statusconnect phải là đầu tiên
Nhắn tinsend, agent, agent.wait, system-event, logs.tailtác dụng phụ cần idempotencyKey
Trò chuyệnchat.history, chat.send, chat.abortWebChat dùng các phương thức này
Phiênsessions.list, sessions.patch, sessions.deletequản trị phiên
Tự động hóawake, cron.list, cron.run, cron.runsđiều khiển wake + cron
Nodenode.list, node.invoke, node.pair.*WS Gateway + hành động node
Sự kiệntick, presence, agent, chat, health, shutdownmáy chủ đẩy
Kho khám phá được quảng bá chính thức nằm trong src/gateway/server-methods-list.ts (listGatewayMethods, GATEWAY_EVENTS).

​
Vị trí của các schema

  • Nguồn: src/gateway/protocol/schema.ts
  • Bộ xác thực lúc chạy (AJV): src/gateway/protocol/index.ts
  • Registry tính năng/khám phá được quảng bá: src/gateway/server-methods-list.ts
  • Bắt tay máy chủ + điều phối phương thức: src/gateway/server.impl.ts
  • Máy khách Node: src/gateway/client.ts
  • JSON Schema được tạo sinh: dist/protocol.schema.json
  • Mô hình Swift được tạo sinh: apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

​
Pipeline hiện tại

  • pnpm protocol:gen
    • ghi JSON Schema (draft-07) vào dist/protocol.schema.json
  • pnpm protocol:gen:swift
    • tạo các mô hình Gateway Swift
  • pnpm protocol:check
    • chạy cả hai trình tạo và xác minh đầu ra đã được commit

​
Cách schema được dùng lúc chạy

  • Phía máy chủ: mọi frame đến đều được xác thực bằng AJV. Bắt tay chỉ chấp nhận yêu cầu connect có params khớp với ConnectParams.
  • Phía máy khách: máy khách JS xác thực các frame sự kiện và phản hồi trước khi sử dụng chúng.
  • Khám phá tính năng: Gateway gửi danh sách features.methods và features.events thận trọng trong hello-ok từ listGatewayMethods() và GATEWAY_EVENTS.
  • Danh sách khám phá đó không phải là bản kết xuất được tạo sinh của mọi helper có thể gọi trong coreGatewayHandlers; một số RPC helper được triển khai trong src/gateway/server-methods/*.ts mà không được liệt kê trong danh sách tính năng được quảng bá.

​
Frame ví dụ

Connect (thông điệp đầu tiên): 
{
  "type": "req",
  "id": "c1",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 4,
    "client": {
      "id": "openclaw-macos",
      "displayName": "macos",
      "version": "1.0.0",
      "platform": "macos 15.1",
      "mode": "ui",
      "instanceId": "A1B2"
    }
  }
}
Phản hồi hello-ok: 
{
  "type": "res",
  "id": "c1",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 4,
    "server": { "version": "dev", "connId": "ws-1" },
    "features": { "methods": ["health"], "events": ["tick"] },
    "snapshot": {
      "presence": [],
      "health": {},
      "stateVersion": { "presence": 0, "health": 0 },
      "uptimeMs": 0
    },
    "policy": { "maxPayload": 1048576, "maxBufferedBytes": 1048576, "tickIntervalMs": 30000 }
  }
}
Yêu cầu + phản hồi: 
{ "type": "req", "id": "r1", "method": "health" }

{ "type": "res", "id": "r1", "ok": true, "payload": { "ok": true } }
Sự kiện: 
{ "type": "event", "event": "tick", "payload": { "ts": 1730000000 }, "seq": 12 }

​
Máy khách tối thiểu (Node.js)

Luồng hữu ích nhỏ nhất: kết nối + kiểm tra sức khỏe. 
import { WebSocket } from "ws";

const ws = new WebSocket("ws://127.0.0.1:18789");

ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "req",
      id: "c1",
      method: "connect",
      params: {
        minProtocol: 4,
        maxProtocol: 4,
        client: {
          id: "cli",
          displayName: "example",
          version: "dev",
          platform: "node",
          mode: "cli",
        },
      },
    }),
  );
});

ws.on("message", (data) => {
  const msg = JSON.parse(String(data));
  if (msg.type === "res" && msg.id === "c1" && msg.ok) {
    ws.send(JSON.stringify({ type: "req", id: "h1", method: "health" }));
  }
  if (msg.type === "res" && msg.id === "h1") {
    console.log("health:", msg.payload);
    ws.close();
  }
});

​
Ví dụ hoàn chỉnh: thêm một phương thức từ đầu đến cuối

Ví dụ: thêm một yêu cầu system.echo mới trả về { ok: true, text }.
  1. Schema (nguồn sự thật)
Thêm vào src/gateway/protocol/schema.ts: 
export const SystemEchoParamsSchema = Type.Object(
  { text: NonEmptyString },
  { additionalProperties: false },
);

export const SystemEchoResultSchema = Type.Object(
  { ok: Type.Boolean(), text: NonEmptyString },
  { additionalProperties: false },
);
Thêm cả hai vào ProtocolSchemas và xuất kiểu: 
  SystemEchoParams: SystemEchoParamsSchema,
  SystemEchoResult: SystemEchoResultSchema,

export type SystemEchoParams = Static<typeof SystemEchoParamsSchema>;
export type SystemEchoResult = Static<typeof SystemEchoResultSchema>;
  1. Xác thực
Trong src/gateway/protocol/index.ts, xuất một bộ xác thực AJV: 
export const validateSystemEchoParams = ajv.compile<SystemEchoParams>(SystemEchoParamsSchema);
  1. Hành vi máy chủ
Thêm một handler trong src/gateway/server-methods/system.ts: 
export const systemHandlers: GatewayRequestHandlers = {
  "system.echo": ({ params, respond }) => {
    const text = String(params.text ?? "");
    respond(true, { ok: true, text });
  },
};
Đăng ký nó trong src/gateway/server-methods.ts (đã hợp nhất systemHandlers), sau đó thêm "system.echo" vào đầu vào listGatewayMethods trong src/gateway/server-methods-list.ts. Nếu phương thức có thể được gọi bởi máy khách operator hoặc node, cũng hãy phân loại nó trong src/gateway/method-scopes.ts để việc thực thi phạm vi và quảng bá tính năng hello-ok luôn khớp nhau.
  1. Tạo sinh lại
pnpm protocol:check
  1. Kiểm thử + tài liệu
Thêm một kiểm thử máy chủ trong src/gateway/server.*.test.ts và ghi chú phương thức trong tài liệu.

​
Hành vi sinh mã Swift

Trình tạo Swift phát ra:
  • enum GatewayFrame với các trường hợp req, res, event và unknown
  • struct/enum payload được định kiểu mạnh
  • các giá trị ErrorCode, GATEWAY_PROTOCOL_VERSION và GATEWAY_MIN_PROTOCOL_VERSION
Các kiểu frame không xác định được giữ lại dưới dạng payload thô để tương thích về sau.

​
Phiên bản hóa + tương thích

  • PROTOCOL_VERSION nằm trong src/gateway/protocol/version.ts.
  • Máy khách gửi minProtocol + maxProtocol; máy chủ từ chối các khoảng không bao gồm giao thức hiện tại của nó.
  • Các mô hình Swift giữ lại kiểu frame không xác định để tránh làm hỏng máy khách cũ hơn.

​
Mẫu và quy ước schema

  • Hầu hết object dùng additionalProperties: false cho payload nghiêm ngặt.
  • NonEmptyString là mặc định cho ID và tên phương thức/sự kiện.
  • GatewayFrame cấp cao nhất dùng một bộ phân biệt trên type.
  • Các phương thức có tác dụng phụ thường yêu cầu idempotencyKey trong params (ví dụ: send, poll, agent, chat.send).
  • agent chấp nhận internalEvents tùy chọn cho ngữ cảnh điều phối được tạo lúc chạy (ví dụ bàn giao hoàn tất tác vụ subagent/cron); hãy xem đây là bề mặt API nội bộ.

​
JSON schema trực tiếp

JSON Schema được tạo sinh nằm trong repo tại dist/protocol.schema.json. Tệp thô đã xuất bản thường có tại:

​
Khi bạn thay đổi schema

  1. Cập nhật các schema TypeBox.
  2. Đăng ký phương thức/sự kiện trong src/gateway/server-methods-list.ts.
  3. Cập nhật src/gateway/method-scopes.ts khi RPC mới cần phân loại phạm vi operator hoặc node.
  4. Chạy pnpm protocol:check.
  5. Commit schema được tạo sinh lại + mô hình Swift.

​
Liên quan