Plugin

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.

​

Bắt đầu nhanh

openclaw plugins list

# Search ClawHub plugins
openclaw plugins search "calendar"

# From ClawHub
openclaw plugins install clawhub:openclaw-codex-app-server

# From npm
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm-pack:./openclaw-plugin-1.2.3.tgz

# From git
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0

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

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

# If the plugin registered a CLI root, run one command from that root.
openclaw <plugin-command> --help

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

​

Quyền sở hữu đường dẫn plugin bị chặn

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

sudo chown -R root:root /path/to/openclaw-config/npm

​

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

​

Lõi (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á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 khám phá/tải Plugin
• plugins.deny luôn thắng allow
• plugins.entries.\<id\>.enabled: false tắt Plugin đó
• Plugin có nguồn gốc từ workspace bị tắt theo mặc định (phải được bật rõ ràng)
• 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 khe độc quyền có thể buộc bật Plugin được chọn cho khe đó
• Một số Plugin đi kèm dạng chọn tham gia đượ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ư ref 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; 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 tuyến 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ởi các ref agent openai/* chuẩn, agentRuntime.id: "codex" dạng provider/model rõ ràng, hoặc các ref mô hình codex/* cũ

​

Xử lý sự cố hook runtime

• Chạy openclaw gateway status --deep --require-rpc và xác nhận URL Gateway, profile, đường dẫn cấu hình và tiến trình đang hoạt động là những thứ bạn đang chỉnh sửa.
• Khởi động lại Gateway trực tiếp sau các 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> --runtime --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ư before_model_resolve, before_agent_reply, before_agent_run, llm_input, llm_output, before_agent_finalize và agent_end cần plugins.entries.<id>.hooks.allowConversationAccess=true.
• Với chuyển đổi mô hình, ưu tiên before_model_resolve. Nó chạy trước quá trình phân giải mô hình cho các lượt agent; 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 dụng, hãy 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>.

​

Thiết lập công cụ Plugin chậm

openclaw config set logging.level trace
openclaw logs --follow

[trace:plugin-tools] factory timings ...

openclaw plugins inspect <plugin-id> --runtime --json

​

Quyền sở hữu kênh hoặc công cụ trùng lặp

• 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> --runtime --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à vô tình, hãy 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ồ.

​

Khe 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 search <query>            # search ClawHub plugin catalog
openclaw plugins inspect <id>              # static detail
openclaw plugins inspect <id> --runtime    # registered hooks/tools/CLI/gateway methods
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 from npm by default
openclaw plugins install clawhub:<pkg>     # install from ClawHub only
openclaw plugins install npm:<pkg>         # install from npm only
openclaw plugins install git:<repo>        # install from git
openclaw plugins install git:<repo>@<ref>  # install from git ref
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

# Verify runtime registrations after install.
openclaw plugins inspect <id> --runtime --json

# Run plugin-owned CLI commands directly from the OpenClaw root CLI.
openclaw <plugin-command> --help

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à kết thúc; các handler có độ ưu tiên thấp hơn bị bỏ qua.
• before_tool_call: { block: false } là no-op và không xóa một block trước đó.
• before_install: { block: true } là kết thúc; các handler có độ ưu tiên thấp hơn bị bỏ qua.
• before_install: { block: false } là no-op và không xóa một block trước đó.
• message_sending: { cancel: true } là kết thúc; các handler có độ ưu tiên thấp hơn bị bỏ qua.
• message_sending: { cancel: false } là no-op và không xóa một cancel 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 capability và pipeline tải
• ClawHub - khám phá Plugin bên thứ ba