Plugin

Documentation Index

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

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

​

Bắt đầu nhanh

openclaw plugins list

# From npm
openclaw plugins install npm:@acme/openclaw-plugin

# From a local directory or archive
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz

openclaw gateway restart

/plugin install clawhub:<package>
/plugin show <plugin-id>
/plugin enable <plugin-id>

​

Loại plugin

​

Điểm vào gói

{
  "name": "@acme/openclaw-plugin",
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"]
  }
}

​

Plugin chính thức

​

Các gói npm do OpenClaw sở hữu trong quá trình di chuyển

​

Cốt lõi (được phát hành cùng OpenClaw)

​

Cấu hình

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

• khởi động lại trong tiến trình được bật (đường dẫn openclaw gateway mặc định), thao tác khởi động lại đó thường được thực hiện tự động một lúc sau khi cấu hình được ghi. Không có đường dẫn hot-reload được hỗ trợ cho mã runtime plugin gốc hoặc hook vòng đời; hãy khởi động lại tiến trình Gateway đang phục vụ kênh trực tiếp trước khi mong đợi mã register(api) đã cập nhật, hook api.on(...), công cụ, dịch vụ, hoặc hook provider/runtime chạy.

​

Khám phá và thứ tự ưu tiên

​

Quy tắc bật

• plugins.enabled: false tắt tất cả Plugin và bỏ qua công việc phát hiện/tải Plugin
• plugins.deny luôn được ưu tiên hơn allow
• plugins.entries.\<id\>.enabled: false tắt Plugin đó
• Các Plugin có nguồn gốc từ workspace bị tắt theo mặc định (phải được bật rõ ràng)
• Các Plugin đi kèm tuân theo tập mặc định bật sẵn tích hợp trừ khi bị ghi đè
• Các slot độc quyền có thể buộc bật Plugin được chọn cho slot đó
• Một số Plugin đi kèm dạng opt-in được bật tự động khi cấu hình nêu tên một bề mặt do Plugin sở hữu, chẳng hạn như tham chiếu mô hình nhà cung cấp, cấu hình kênh, hoặc runtime harness
• Cấu hình Plugin cũ được giữ lại trong khi plugins.enabled: false đang hoạt động; hãy bật lại Plugin trước khi chạy dọn dẹp doctor nếu bạn muốn xóa các id cũ
• Các route Codex thuộc họ OpenAI giữ ranh giới Plugin riêng: openai-codex/* thuộc về Plugin OpenAI, trong khi Plugin app-server Codex đi kèm được chọn bằng agentRuntime.id: "codex" hoặc các tham chiếu mô hình codex/* cũ

​

Khắc phục sự cố runtime hook

• Chạy openclaw gateway status --deep --require-rpc và xác nhận URL Gateway đang hoạt động, profile, đường dẫn cấu hình, và tiến trình là những thứ bạn đang chỉnh sửa.
• Khởi động lại Gateway trực tiếp sau khi thay đổi cài đặt/cấu hình/mã Plugin. Trong các container wrapper, PID 1 có thể chỉ là supervisor; hãy khởi động lại hoặc gửi tín hiệu cho tiến trình con openclaw gateway run.
• Dùng openclaw plugins inspect <id> --json để xác nhận đăng ký hook và chẩn đoán. Các hook hội thoại không đi kèm như llm_input, llm_output, before_agent_finalize, và agent_end cần plugins.entries.<id>.hooks.allowConversationAccess=true.
• Đối với chuyển đổi mô hình, ưu tiên before_model_resolve. Nó chạy trước khi phân giải mô hình cho lượt tác tử; llm_output chỉ chạy sau khi một lần thử mô hình tạo ra đầu ra assistant.
• Để chứng minh mô hình phiên hiệu lực, dùng openclaw sessions hoặc các bề mặt phiên/trạng thái Gateway và, khi gỡ lỗi payload nhà cung cấp, khởi động Gateway với --raw-stream --raw-stream-path <path>.

​

Trùng quyền sở hữu kênh hoặc công cụ

• channel already registered: <channel-id> (<plugin-id>)
• channel setup already registered: <channel-id> (<plugin-id>)
• plugin tool name conflict (<plugin-id>): <tool-name>

• Chạy openclaw plugins list --enabled --verbose để xem mọi Plugin đã bật và nguồn gốc.
• Chạy openclaw plugins inspect <id> --json cho từng Plugin nghi ngờ và so sánh channels, channelConfigs, tools, và chẩn đoán.
• Chạy openclaw plugins registry --refresh sau khi cài đặt hoặc gỡ bỏ các gói Plugin để metadata đã lưu phản ánh bản cài đặt hiện tại.
• Khởi động lại Gateway sau các thay đổi cài đặt, registry, hoặc cấu hình.

• Nếu một Plugin cố ý thay thế Plugin khác cho cùng id kênh, Plugin được ưu tiên nên khai báo channelConfigs.<channel-id>.preferOver với id Plugin có độ ưu tiên thấp hơn. Xem /plugins/manifest#replacing-another-channel-plugin.
• Nếu trùng lặp là ngoài ý muốn, tắt một bên bằng plugins.entries.<plugin-id>.enabled: false hoặc gỡ bản cài đặt Plugin cũ.
• Nếu bạn đã bật rõ ràng cả hai Plugin, OpenClaw giữ yêu cầu đó và báo cáo xung đột. Chọn một chủ sở hữu cho kênh hoặc đổi tên các công cụ do Plugin sở hữu để bề mặt runtime không mơ hồ.

​

Slot Plugin (danh mục độc quyền)

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable
      contextEngine: "legacy", // or a plugin id
    },
  },
}

​

Tham chiếu CLI

openclaw plugins list                       # compact inventory
openclaw plugins list --enabled            # only enabled plugins
openclaw plugins list --verbose            # per-plugin detail lines
openclaw plugins list --json               # machine-readable inventory
openclaw plugins inspect <id>              # deep detail
openclaw plugins inspect <id> --json       # machine-readable
openclaw plugins inspect --all             # fleet-wide table
openclaw plugins info <id>                 # inspect alias
openclaw plugins doctor                    # diagnostics
openclaw plugins registry                  # inspect persisted registry state
openclaw plugins registry --refresh        # rebuild persisted registry
openclaw doctor --fix                      # repair plugin registry state

openclaw plugins install <package>         # install (ClawHub first, then npm)
openclaw plugins install clawhub:<pkg>     # install from ClawHub only
openclaw plugins install npm:<pkg>         # install from npm only
openclaw plugins install <spec> --force    # overwrite existing install
openclaw plugins install <path>            # install from local path
openclaw plugins install -l <path>         # link (no copy) for dev
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin      # record exact resolved npm spec
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # update one plugin
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all            # update all
openclaw plugins uninstall <id>          # remove config and plugin index records
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

openclaw plugins enable <id>
openclaw plugins disable <id>

​

Tổng quan API Plugin

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});

• before_tool_call: { block: true } là trạng thái kết thúc; các handler có mức ưu tiên thấp hơn bị bỏ qua.
• before_tool_call: { block: false } là không thao tác và không xóa một chặn trước đó.
• before_install: { block: true } là trạng thái kết thúc; các handler có mức ưu tiên thấp hơn bị bỏ qua.
• before_install: { block: false } là không thao tác và không xóa một chặn trước đó.
• message_sending: { cancel: true } là trạng thái kết thúc; các handler có mức ưu tiên thấp hơn bị bỏ qua.
• message_sending: { cancel: false } là không thao tác và không xóa một hủy trước đó.

​

Liên quan

• Xây dựng Plugin — tạo Plugin của riêng bạn
• Gói Plugin — khả năng tương thích gói Codex/Claude/Cursor
• Manifest Plugin — schema manifest
• Đăng ký công cụ — thêm công cụ agent trong một Plugin
• Nội bộ Plugin — mô hình khả năng và pipeline tải
• Plugin cộng đồng — danh sách bên thứ ba