English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Bundled plugin guides

Plugin OC Path

Plugin oc-path đi kèm bổ sung CLI openclaw path cho cơ chế định địa chỉ tệp workspace oc://. Nó được phân phối trong repo OpenClaw tại extensions/oc-path/ nhưng là tùy chọn — quá trình cài đặt/build để nó ở trạng thái không hoạt động cho đến khi bạn bật nó.

Địa chỉ oc:// trỏ tới một lá đơn lẻ (hoặc một tập lá theo ký tự đại diện) bên trong một tệp workspace. Hiện nay Plugin hiểu ba loại tệp:

  • markdown (.md, .mdx): frontmatter, section, item, field
  • jsonc (.jsonc, .json5, .json): giữ nguyên comment và định dạng
  • jsonl (.jsonl, .ndjson): bản ghi theo từng dòng

Người tự host và tiện ích mở rộng trình soạn thảo dùng CLI để đọc hoặc ghi một lá đơn lẻ mà không cần script trực tiếp với SDK; agent và hook xem nó là một nền tảng xác định để các vòng khứ hồi giữ nguyên byte và lớp bảo vệ sentinel che dữ liệu áp dụng thống nhất trên mọi loại.

Vì sao nên bật nó

Bật oc-path khi bạn muốn script, hook hoặc công cụ agent cục bộ trỏ tới một phần chính xác của trạng thái workspace mà không phải tự tạo parser cho từng dạng tệp. Một địa chỉ oc:// duy nhất có thể đặt tên cho một khóa frontmatter Markdown, một item trong section, một lá cấu hình JSONC, hoặc một field sự kiện JSONL.

Điều đó quan trọng với các workflow của maintainer, nơi thay đổi cần nhỏ, dễ kiểm tra và lặp lại được: xem một giá trị, tìm các bản ghi khớp, dry-run một thao tác ghi, rồi chỉ áp dụng lá đó trong khi giữ nguyên comment, kết thúc dòng và định dạng lân cận. Việc giữ chức năng này là một Plugin tùy chọn cung cấp nền tảng định địa chỉ cho người dùng nâng cao mà không đưa dependency parser hoặc bề mặt CLI vào core cho các bản cài đặt không bao giờ cần đến nó.

Các lý do thường gặp để bật nó:

  • Tự động hóa cục bộ: shell script có thể resolve hoặc cập nhật một giá trị workspace bằng openclaw path … --json thay vì mang theo mã phân tích Markdown, JSONC và JSONL riêng.
  • Chỉnh sửa agent thấy được: agent có thể hiển thị diff dry-run cho một lá đã định địa chỉ trước khi ghi, dễ review hơn so với việc ghi lại tệp dạng tự do.
  • Tích hợp trình soạn thảo: trình soạn thảo có thể ánh xạ oc://AGENTS.md/tools/gh tới đúng node Markdown và số dòng mà không phải đoán từ văn bản heading.
  • Chẩn đoán: emit đưa một tệp qua parser rồi emitter theo vòng khứ hồi, để bạn có thể kiểm tra liệu một loại tệp có ổn định theo byte hay không trước khi dựa vào các chỉnh sửa tự động.

Ví dụ cụ thể:

# Is the GitHub plugin enabled in this config?
openclaw path resolve 'oc://config.jsonc/plugins/github/enabled' --json

# Which tool-call names appear in this session log?
openclaw path find 'oc://session.jsonl/[event=tool_call]/name' --json

# What bytes would this tiny config edit write?
openclaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

Plugin này cố ý không sở hữu các ngữ nghĩa cấp cao hơn. Các Plugin bộ nhớ vẫn sở hữu thao tác ghi bộ nhớ, các lệnh cấu hình vẫn sở hữu việc quản lý cấu hình đầy đủ, và logic LKG vẫn sở hữu restore/promotion. oc-path là lớp thao tác tệp hẹp để định địa chỉ và giữ nguyên byte mà các công cụ cấp cao hơn có thể xây dựng xung quanh.

Nó chạy ở đâu

Plugin chạy trong cùng tiến trình bên trong CLI openclaw trên host nơi bạn gọi lệnh. Nó không cần Gateway đang chạy và không mở socket mạng nào — mọi verb đều là phép biến đổi thuần trên một tệp bạn chỉ tới.

Metadata của Plugin nằm trong extensions/oc-path/openclaw.plugin.json:

{
  "id": "oc-path",
  "name": "OC Path",
  "activation": {
    "onStartup": false,
    "onCommands": ["path"]
  },
  "commandAliases": [{ "name": "path", "kind": "cli" }]
}

onStartup: false giữ Plugin ngoài hot path của Gateway. onCommands: ["path"] cho CLI biết cần lazy-load Plugin vào lần đầu bạn chạy openclaw path …, nên các bản cài đặt không dùng verb này sẽ không chịu chi phí.

Bật

openclaw plugins enable oc-path

Khởi động lại Gateway (nếu bạn chạy một Gateway) để snapshot manifest nhận trạng thái mới. Các lần gọi openclaw path thuần hoạt động ngay trên cùng host — CLI tải Plugin theo nhu cầu.

Tắt bằng:

openclaw plugins disable oc-path

Dependency

Mọi dependency parser đều nằm cục bộ trong Plugin — bật oc-path không kéo gói mới vào runtime core:

Dependency Mục đích
commander Nối subcommand cho resolve, find, set, validate, emit.
jsonc-parser Parse JSONC + chỉnh sửa lá trong khi giữ comment và dấu phẩy cuối.
markdown-it Token hóa Markdown cho mô hình section / item / field.

JSONL vẫn được viết thủ công — phân tích theo từng dòng đơn giản hơn bất kỳ dependency nào, và parse JSONC theo từng dòng đã đi qua jsonc-parser.

Nó cung cấp gì

Bề mặt Được cung cấp bởi
CLI openclaw path extensions/oc-path/cli-registration.ts
Parser / formatter oc:// extensions/oc-path/src/oc-path/oc-path.ts
Parse / emit / edit theo loại extensions/oc-path/src/oc-path/{md,jsonc,jsonl}
Resolve / find / set chung extensions/oc-path/src/oc-path/{resolve,find,edit}.ts
Bảo vệ redaction-sentinel extensions/oc-path/src/oc-path/sentinel.ts

CLI hiện là bề mặt công khai duy nhất. Các verb nền tảng là private trong Plugin; consumer dùng CLI (hoặc tự xây Plugin của họ dựa trên SDK).

Quan hệ với các Plugin khác

  • memory-*: thao tác ghi bộ nhớ đi qua các Plugin bộ nhớ, không qua oc-path. oc-path là nền tảng tệp chung; các Plugin bộ nhớ đặt ngữ nghĩa riêng của chúng lên trên.
  • LKG: path không biết về restore cấu hình Last-Known-Good. Nếu một tệp được LKG theo dõi, lần gọi observe tiếp theo quyết định promote hay recover; set --batch cho multi-set nguyên tử qua vòng đời promote/recover của LKG được lên kế hoạch cùng với nền tảng LKG-recovery.

An toàn

set ghi byte thô qua đường emit của nền tảng, nơi tự động áp dụng lớp bảo vệ redaction-sentinel. Một lá mang __OPENCLAW_REDACTED__ (nguyên văn hoặc là chuỗi con) bị từ chối khi ghi với OC_EMIT_SENTINEL. CLI cũng xóa sentinel nguyên văn khỏi mọi output cho người đọc hoặc JSON mà nó in ra, thay bằng [REDACTED] để các bản ghi terminal và pipeline không bao giờ rò rỉ marker.

Liên quan