Plugin

Hermes có một hệ thống plugin để thêm các công cụ, hook và tích hợp tùy chỉnh mà không cần sửa đổi mã lõi.
Nếu bạn muốn tạo một công cụ tùy chỉnh cho chính mình, nhóm của bạn hoặc một dự án, đây thường là con đường đúng đắn. Hướng dẫn của nhà phát triển Trang Adding Tools dành cho Hermes tích hợp các công cụ cốt lõi có trong tools/ và `toolsets.py
→ Build a Hermes Plugin — hướng dẫn từng bước với ví dụ hoạt động hoàn chỉnh.
Tổng quan nhanh

Thả một thư mục vào
~/.Hermes/plugins/ với mã plugin.YAML ` và Python:
` ~/.Hermes/plugins/my-plugin/ ├── plugin.YAML # manifest ├── init.py # register() — wires schemas to handlers ├── schemas.py # tool schemas (what the LLM sees) └── tools.py # tool handlers (what runs when called)
` ``Bắt đầu Hermes — các công cụ của bạn xuất hiện cùng với các công cụ tích hợp sẵn. Người mẫu có thể gọi họ ngay lập tức.
Ví dụ hoạt động tối thiểu

Đây là một plugin hoàn chỉnh bổ sung công cụ hello_world và ghi lại mọi lệnh gọi công cụ thông qua một hook.
~/.Hermes/plugins/hello-world/plugin.YAML
name: hello-world
version: "1.0"
description: A minimal example plugin

`
``**

~/.Hermes/plugins/hello-world/__init__.py

`
**

``` python
"""Minimal Hermes plugin — registers a tool and a hook."""`import JSON

def register(ctx):

    # --- Tool: hello_world ---
    schema = &#123;
        "name": "hello_world",
        "description": "Returns a friendly greeting for the given name.",
        "parameters": &#123;
            "type": "object",
            "properties": &#123;
                "name": &#123;
                    "type": "string",
                    "description": "Name to greet",
                &#125;
            &#125;,
            "required": ["name"],
        &#125;,
    &#125;`def handle_hello(params, **kwargs):
        del kwargs
        name = params.get("name", "World")
        return JSON.dumps(\&#123;"success": True, "greeting": f"Hello, \&#123;name&#125;!"&#125;)

ctx.register_tool(
        name="hello_world",
        toolset="hello_world",
        schema=schema,
        handler=handle_hello,
        description="Return a friendly greeting for the given name.",
    )

# --- Hook: log every tool call ---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] tool called: \&#123;tool_name&#125;")

ctx.register_hook("post_tool_call", on_tool_call)

`
``Thả cả hai tệp vào 

~/.Hermes/plugins/hello-world/

, khởi động lại Hermes và mô hình có thể gọi ngay 
`hello_world

. Móc in một dòng nhật ký sau mỗi lần gọi công cụ.

Các plugin dự án cục bộ trong 

./.Hermes/plugins/
` bị tắt theo mặc định. Chỉ kích hoạt chúng cho các kho lưu trữ đáng tin cậy bằng cách đặt 
`Hermes_ENABLE_PROJECT_PLUGINS=true
` trước khi khởi động Hermes.

## Plugin có thể làm gì

Mọi API 
`ctx.*
` bên dưới đều có sẵn bên trong chức năng 
`register(ctx)
` của plugin.

| Năng lực | Như thế nào |
|----------||------|
| Thêm công cụ |

ctx.register_tool(name=..., toolset=..., schema=..., handler=...)
` |
| Thêm móc |

ctx.register_hook("post_tool_call", callback)
` |
| Thêm lệnh gạch chéo |

ctx.register_command(name, handler, description)

 - thêm 

/name
` trong phiên CLI và cổng |
| Công cụ điều phối từ lệnh |

ctx.dispatch_tool(name, args)

 - gọi một công cụ đã đăng ký với ngữ cảnh tác nhân gốc được tự động kết nối |
| Thêm lệnh CLI |

ctx.register_CLI_command(name, help, setup_fn, handler_fn)

 - thêm 
`Hermes &lt;plugin &lt;subcommand
` |
| Tiêm tin nhắn |

ctx.inject_message(content, role="user")

 - xem [Injecting Messages](#injecting-messages) |
| Gửi tập tin dữ liệu |

Path(__file__).parent / "data" / "file.YAML"
` |
| Gói kỹ năng |

ctx.register_skill(name, path)
` — được đặt tên là 
`plugin:skill

, được tải qua 
`skill_view("plugin:skill")
` |
| Cổng trên env vars |

requires_env: [API_KEY]
` trong plugin.YAML — được nhắc trong 
`Hermes plugins install
` |
| Phân phối qua pip |

[project.entry-points."Hermes_agent.plugins"]
` |
| Đăng ký nền tảng cổng (Discord, Telegram, IRC, …) |

ctx.register_platform(name, label, adapter_factory, check_fn, ...)

 - xem [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) |
| Đăng ký một chương trình phụ trợ tạo hình ảnh |

ctx.register_image_gen_provider(provider)

 - xem [Image Generation Provider Plugins](/docs/developer-guide/image-gen-provider-plugin) |
| Đăng ký phần phụ trợ tạo video |

ctx.register_video_gen_provider(provider)

 - xem [Video Generation Provider Plugins](/docs/developer-guide/video-gen-provider-plugin) |
| Đăng ký một công cụ nén ngữ cảnh |

ctx.register_context_engine(engine)

 - xem [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) |
| Đăng ký phụ trợ bộ nhớ | Phân lớp 
`MemoryProvider
` trong 
`plugins/memory/&lt;name/__init__.py

 - xem [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) (sử dụng hệ thống khám phá riêng) |
| Thực hiện cuộc gọi LLM do máy chủ sở hữu |

ctx.LLM.complete(...)
` / 
`ctx.LLM.complete_structured(...)

 - mượn mô hình hoạt động + xác thực của người dùng để hoàn thành một lần với xác thực lược đồ JSON tùy chọn. Xem [Plugin LLM Access](/docs/developer-guide/plugin-LLM-access) |
| Đăng ký phần phụ trợ suy luận (nhà cung cấp LLM) |

register_provider(ProviderProfile(...))
` trong 
`plugins/model-providers/&lt;name/__init__.py

 - xem [Model Provider Plugins](/docs/developer-guide/model-provider-plugin) (sử dụng hệ thống khám phá riêng) |

## Khám phá plugin

| Nguồn | Đường dẫn | Trường hợp sử dụng |
|--------|------|----------|
| Đi kèm |

&lt;repo/plugins/
` | Vận chuyển với Hermes - xem [Built-in Plugins](/docs/user-guide/features/built-in-plugins) |
| Người dùng |

~/.Hermes/plugins/
` | Plugin cá nhân |
| Dự án |

.Hermes/plugins/
` | Các plugin dành riêng cho dự án (yêu cầu 
`Hermes_ENABLE_PROJECT_PLUGINS=true

) |
| pip | Điểm vào 
`Hermes_agent.plugins
` | Gói phân phối |
| Nix |

services.Hermes-agent.extraPlugins
` / 
`extraPythonPackages
` | Cài đặt khai báo NixOS - xem [Nix Setup](/docs/getting-started/nix-setup#plugins) |

Các nguồn sau này ghi đè các nguồn trước đó do xung đột tên, do đó, một plugin người dùng có cùng tên với plugin đi kèm sẽ thay thế nó.

### Danh mục phụ plugin

Trong mỗi nguồn, Hermes cũng nhận ra các thư mục danh mục phụ định tuyến các plugin đến các hệ thống khám phá chuyên biệt:| Thư mục con | Nó chứa đựng những gì | Hệ thống khám phá |
|---|---|---|
| 
`plugins/
` (gốc) | Các plugin chung — công cụ, hook, lệnh gạch chéo, lệnh CLI, kỹ năng đi kèm |

PluginManager
` (loại: 
`standalone
` hoặc 
`backend

) |
| 
`plugins/platforms/&lt;name/
` | Bộ điều hợp kênh cổng (
`ctx.register_platform()

) | 
`PluginManager
` (loại: 
`platform

, sâu hơn một cấp) |
| 
`plugins/image_gen/&lt;name/
` | Phần phụ trợ tạo hình ảnh (
`ctx.register_image_gen_provider()

) | 
`PluginManager
` (loại: 
`backend

, sâu hơn một cấp) |
| 
`plugins/memory/&lt;name/
` | Nhà cung cấp bộ nhớ (phân lớp 
`MemoryProvider

) | **Trình tải riêng** trong 
`plugins/memory/__init__.py
` (loại: 
`exclusive
` — mỗi lần một hoạt động) |
| 
`plugins/context_engine/&lt;name/
` | Công cụ nén ngữ cảnh (
`ctx.register_context_engine()

) | **Trình tải riêng** trong 
`plugins/context_engine/__init__.py
` (mỗi lần một hoạt động) |
| 
`plugins/model-providers/&lt;name/
` | Hồ sơ nhà cung cấp LLM (
`register_provider(ProviderProfile(...))

) | **Trình tải riêng** trong 
`providers/__init__.py
` (được quét một cách lười biếng trong cuộc gọi 
`get_provider_profile()
` đầu tiên) |

Các plugin người dùng tại 

~/.Hermes/plugins/model-providers/&lt;name/
` và 

~/.Hermes/plugins/memory/&lt;name/
` ghi đè các plugin đi kèm cùng tên — người viết cuối cùng giành chiến thắng trong 
`register_provider()
` / 
`register_memory_provider()

. Thả một thư mục vào và nó sẽ thay thế thư mục tích hợp sẵn mà không cần bất kỳ chỉnh sửa repo nào.

Các plugin danh mục phụ hiển thị trong 
`Hermes plugins list
` và giao diện người dùng 
`Hermes plugins
` tương tác dưới **khóa dẫn xuất đường dẫn** của chúng - ví dụ: 
`observability/Langfuse

, 
`image_gen/OpenAI

, 
`platforms/teams

. Khóa đó (không phải tệp kê khai đơn giản 
`name:

) là giá trị bạn chuyển tới 
`Hermes plugins enable …
` / 
`disable …
` và chuỗi cần thêm vào dưới 
`plugins.enabled
` trong 
`config.yaml

.

## Plugin được chọn tham gia (với một vài ngoại lệ)

**Các plugin chung và chương trình phụ trợ do người dùng cài đặt bị tắt theo mặc định** — quá trình khám phá sẽ tìm thấy chúng (vì vậy chúng hiển thị trong 
`Hermes plugins
` và 

/plugins

), nhưng không tải được móc hoặc công cụ nào cho đến khi bạn thêm tên plugin vào 
`plugins.enabled
` trong 

~/.Hermes/config.yaml

. Điều này ngăn mã của bên thứ ba chạy mà không có sự đồng ý rõ ràng của bạn.

``` yaml
plugins:
  enabled:

    - my-tool-plugin
    - disk-cleanup
  disabled:       # optional deny-list — always wins if a name appears in both
    - noisy-plugin

`
``Ba cách để chuyển trạng thái:

``` bash
Hermes plugins                    # interactive toggle (space to check/uncheck)
Hermes plugins enable &lt;name      # add to allow-list
Hermes plugins disable &lt;name     # remove from allow-list + add to disabled

`
``Sau 
`Hermes plugins install owner/repo

, bạn được hỏi 
`Enable 'name' now? [y/N]
` — mặc định là không. Bỏ qua lời nhắc cài đặt theo tập lệnh với 

`
--enable
` hoặc 

--no-enable

.

### Danh sách cho phép KHÔNG cổng gì

Một số danh mục plugin bỏ qua 
`plugins.enabled
` — chúng là một phần của bề mặt tích hợp của Hermes và sẽ phá vỡ chức năng cơ bản nếu bị tắt theo mặc định:

| Loại plugin | Thay vào đó nó được kích hoạt như thế nào |
|---|---|
| **Các plugin nền tảng đi kèm** (IRC, Teams, v.v. trong 
`plugins/platforms/

) | Tự động tải để mọi kênh cổng vận chuyển đều có sẵn. Kênh thực tế bật qua 
`gateway.platforms.&lt;name.enabled
` trong 
`config.yaml

. |
| **Phần phụ trợ đi kèm** (nhà cung cấp thế hệ hình ảnh theo 
`plugins/image_gen/

, v.v.) | Tự động tải để chương trình phụ trợ mặc định "chỉ hoạt động". Việc lựa chọn diễn ra thông qua 

&lt;category.provider
` trong 
`config.yaml
` (ví dụ: 
`image_gen.provider: OpenAI

). |
| **Nhà cung cấp bộ nhớ** (
`plugins/memory/

) | Tất cả đều được phát hiện; chính xác một cái đang hoạt động, được 
`memory.provider
` chọn trong 
`config.yaml

. |
| **Công cụ bối cảnh** (
`plugins/context_engine/

) | Tất cả đều được phát hiện; một đang hoạt động, được chọn bởi 
`context.engine
` trong 
`config.yaml

. |
| **Nhà cung cấp mô hình** (
`plugins/model-providers/

) | Tất cả các nhà cung cấp đi kèm theo 
`plugins/model-providers/
` đều khám phá và đăng ký trong cuộc gọi 
`get_provider_profile()
` đầu tiên. Người dùng chọn từng cái một thông qua 

--provider
` hoặc 
`config.yaml

. |
| **Các plugin 
`backend
` được cài đặt trong pip** | Chọn tham gia qua 
`plugins.enabled
` (giống như các plugin chung). |
| **Nền tảng do người dùng cài đặt** (thuộc 

~/.Hermes/plugins/platforms/

) | Chọn tham gia thông qua 
`plugins.enabled
` — bộ điều hợp cổng của bên thứ ba cần có sự đồng ý rõ ràng. |

Tóm lại: **tải cơ sở hạ tầng "luôn hoạt động" đi kèm; Các plugin chung của bên thứ ba được chọn tham gia.** Danh sách cho phép 
`plugins.enabled
` là cổng dành riêng cho mã tùy ý mà người dùng thả vào 

~/.Hermes/plugins/

.

### Di chuyển cho người dùng hiện tạiKhi bạn nâng cấp lên phiên bản Hermes có plugin chọn tham gia (lược đồ cấu hình v21+), mọi plugin người dùng đã được cài đặt trong 

~/.Hermes/plugins/
` mà chưa có trong 
`plugins.disabled
` đều **tự động được chuyển thành** vào 
`plugins.enabled

. Thiết lập hiện tại của bạn tiếp tục hoạt động. Các plugin độc lập đi kèm KHÔNG được cấp phép — ngay cả người dùng hiện tại cũng phải chọn tham gia một cách rõ ràng. (Các plugin nền tảng/phụ trợ đi kèm không bao giờ cần có sự hỗ trợ vì chúng không bao giờ bị kiểm soát.)

## Móc có sẵn

Các plugin có thể đăng ký lệnh gọi lại cho các sự kiện trong vòng đời này. Xem **[Event Hooks page](/docs/user-guide/features/hooks#plugin-hooks)** để biết đầy đủ chi tiết, chữ ký gọi lại và ví dụ.

| Móc | Kích hoạt khi |
|------|-------------|
| [XPROTECTX128XPROTECTX](/docs/user-guide/features/hooks#pre_tool_call) | Trước khi bất kỳ công cụ nào thực thi |
| [XPROTECTX129XPROTECTX](/docs/user-guide/features/hooks#post_tool_call) | Sau khi bất kỳ công cụ nào trả về |
| [XPROTECTX130XPROTECTX](/docs/user-guide/features/hooks#pre_LLM_call) | Một lần trong lượt, trước vòng lặp LLM - có thể trả 

\&#123;"context": "..."&#125;
` về [inject context into the user message](/docs/user-guide/features/hooks#pre_LLM_call) |
| [XPROTECTX132XPROTECTX](/docs/user-guide/features/hooks#post_LLM_call) | Một lần trong lượt, sau vòng LLM (chỉ những lượt thành công) |
| [XPROTECTX133XPROTECTX](/docs/user-guide/features/hooks#on_session_start) | Đã tạo phiên mới (chỉ lượt đầu tiên) |
| [XPROTECTX134XPROTECTX](/docs/user-guide/features/hooks#on_session_end) | Kết thúc mọi cuộc gọi 
`run_conversation

 + trình xử lý thoát CLI |
| [XPROTECTX136XPROTECTX](/docs/user-guide/features/hooks#on_session_finalize) | CLI/gateway phá bỏ phiên hoạt động (

/new

, GC, CLI thoát) |
| [XPROTECTX138XPROTECTX](/docs/user-guide/features/hooks#on_session_reset) | Hoán đổi cổng trong khóa phiên mới (

/new

, 

/reset

, 

/clear

, xoay không tải) |
| [XPROTECTX142XPROTECTX](/docs/user-guide/features/hooks#subagent_stop) | Một lần cho mỗi trẻ sau khi 
`delegate_task
` kết thúc |
| [XPROTECTX144XPROTECTX](/docs/user-guide/features/hooks#pre_gateway_dispatch) | Gateway đã nhận được tin nhắn của người dùng trước khi xác thực + gửi đi. Trả lại 

\&#123;"action": "skip" \| "rewrite" \| "allow", ...&#125;
` để tác động đến dòng chảy. |

## Các loại plugin

Hermes có bốn loại plugin:

| Loại | Nó làm gì | Lựa chọn | Vị trí |
|------|-------------|----------|----------|
| **Plugin chung** | Thêm công cụ, hook, lệnh gạch chéo, lệnh CLI | Chọn nhiều (bật/tắt) |

~/.Hermes/plugins/
` |
| **Nhà cung cấp bộ nhớ** | Thay thế hoặc tăng cường bộ nhớ tích hợp | Chọn một lần (một lần kích hoạt) |

plugins/memory/
` |
| **Công cụ bối cảnh** | Thay thế trình nén ngữ cảnh tích hợp | Chọn một lần (một lần kích hoạt) |

plugins/context_engine/
` |
| **Nhà cung cấp mô hình** | Khai báo một backend suy luận (OpenRouter, Anthropic,…) | Nhiều đăng ký, được chọn bởi 

--provider
` / 
`config.yaml
` | 
`plugins/model-providers/
` |

Trình cung cấp bộ nhớ và công cụ ngữ cảnh là **plugin của nhà cung cấp** — mỗi loại chỉ có thể hoạt động một trong số đó. Nhà cung cấp mô hình cũng là plugin, nhưng nhiều plugin tải cùng lúc; người dùng chọn từng cái một thông qua 

--provider
` hoặc 
`config.yaml

. Các plugin chung có thể được kích hoạt theo bất kỳ cách kết hợp nào.

## Giao diện có thể cắm được - vị trí của mỗi giao diện

Bảng trên hiển thị bốn danh mục plugin, nhưng trong "plugin chung", 
`PluginContext
` hiển thị một số điểm mở rộng riêng biệt — và Hermes cũng chấp nhận các tiện ích mở rộng bên ngoài hệ thống plugin Python (các chương trình phụ trợ được định hướng theo cấu hình, các lệnh được nối với shell, máy chủ bên ngoài, v.v.). Sử dụng bảng này để tìm tài liệu phù hợp cho nội dung bạn muốn xây dựng:| Muốn thêm… | Như thế nào | Hướng dẫn soạn thảo |
|---|---|---|
| Một **công cụ** LLM có thể gọi | Plugin Python — 
`ctx.register_tool()
` | [Build a Hermes Plugin](/docs/guides/build-a-Hermes-plugin) · [Adding Tools](/docs/developer-guide/adding-tools) |
| **Móc vòng đời** (trước/sau LLM, bắt đầu/kết thúc phiên, bộ lọc công cụ) | Plugin Python — 
`ctx.register_hook()
` | [Hooks reference](/docs/user-guide/features/hooks) · [Build a Hermes Plugin](/docs/guides/build-a-Hermes-plugin) |
| **Lệnh gạch chéo** cho CLI / cổng | Plugin Python — 
`ctx.register_command()
` | [Build a Hermes Plugin](/docs/guides/build-a-Hermes-plugin) · [Extending the CLI](/docs/developer-guide/extending-the-CLI) |
| **lệnh phụ** dành cho 
`Hermes &lt;thing
` | Plugin Python — 
`ctx.register_CLI_command()
` | [Extending the CLI](/docs/developer-guide/extending-the-CLI) |
| Một **kỹ năng** đi kèm mà plugin của bạn cung cấp | Plugin Python — 
`ctx.register_skill()
` | [Creating Skills](/docs/developer-guide/creating-skills) |
| **Phần phụ trợ suy luận** (Nhà cung cấp LLM: OpenAI-compat, Codex, Anthropic-Messages, Bedrock) | Plugin nhà cung cấp — 
`register_provider(ProviderProfile(...))
` trong 
`plugins/model-providers/&lt;name/
` | **[Model Provider Plugins](/docs/developer-guide/model-provider-plugin)** · [Adding Providers](/docs/developer-guide/adding-providers) |
| Một **kênh cổng** (Discord / Telegram / IRC / Teams / v.v.) | Plugin nền tảng — 
`ctx.register_platform()
` trong 
`plugins/platforms/&lt;name/
` | [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) |
| Một **phụ trợ bộ nhớ** (Honcho, Mem0, Supermemory, …) | Plugin bộ nhớ - lớp con 
`MemoryProvider
` trong 
`plugins/memory/&lt;name/
` | [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) |
| **Chiến lược nén ngữ cảnh** | Plugin công cụ ngữ cảnh - 
`ctx.register_context_engine()
` | [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) |
| **Phần phụ trợ tạo hình ảnh** (DALL·E, SDXL, …) | Plugin phụ trợ — 
`ctx.register_image_gen_provider()
` | [Image Generation Provider Plugins](/docs/developer-guide/image-gen-provider-plugin) |
| **Phần phụ trợ tạo video** (Veo, Kling, Pixverse, Grok-Imagine, Runway, …) | Plugin phụ trợ — 
`ctx.register_video_gen_provider()
` | [Video Generation Provider Plugins](/docs/developer-guide/video-gen-provider-plugin) |
| **Phần phụ trợ TTS** (bất kỳ CLI nào — piper, VoxCPM, Kokoro, xtts, tập lệnh sao chép giọng nói,…) | Dựa trên cấu hình - khai báo theo 
`tts.providers.&lt;name
` với 
`type: command
` trong 
`config.yaml
` | [TTS setup](/docs/user-guide/features/tts#custom-command-providers) |
| **Phần phụ trợ STT** (nhị phân thì thầm tùy chỉnh, ASR CLI cục bộ) | Định hướng theo cấu hình - đặt 
`Hermes_LOCAL_STT_COMMAND
` env var thành mẫu shell | [Voice Message Transcription (STT)](/docs/user-guide/features/tts#voice-message-transcription-stt) |
| **Các công cụ bên ngoài thông qua MCP** (hệ thống tệp, GitHub, Linear, Notion, bất kỳ máy chủ MCP nào) | Định hướng theo cấu hình — khai báo 
`MCP_servers.&lt;name
` với 
`command:
` / 
`url:
` trong 
`config.yaml

. Hermes tự động khám phá các công cụ của máy chủ và đăng ký chúng cùng với các công cụ tích hợp sẵn. | [MCP](/docs/user-guide/features/MCP) |
| **Các nguồn kỹ năng bổ sung** (kho GitHub tùy chỉnh, chỉ mục kỹ năng riêng) | CLI — 
`Hermes skills tap add &lt;repo
` | [Skills Hub](/docs/user-guide/features/skills#skills-hub) · [Publishing a custom tap](/docs/user-guide/features/skills#publishing-a-custom-skill-tap) |
| **Móc sự kiện cổng** (kích hoạt 
`gateway:startup

, 
`session:start

, 
`agent:end

, 
`command:*

) | Thả 
`HOOK.YAML

 + 
`handler.py
` vào 

~/.Hermes/hooks/&lt;name/
` | [Event Hooks](/docs/user-guide/features/hooks#gateway-event-hooks) |
| **Shell hooks** (chạy lệnh shell trên các sự kiện - thông báo, nhật ký kiểm tra, cảnh báo trên màn hình) | Định hướng cấu hình — khai báo theo 
`hooks:
` trong 
`config.yaml
` | [Shell Hooks](/docs/user-guide/features/hooks#shell-hooks) |

:::note
Không phải mọi thứ đều là plugin Python. Một số bề mặt mở rộng có chủ ý sử dụng **các lệnh shell điều khiển bằng cấu hình** (TTS, STT, shell hook) để bất kỳ CLI nào bạn đã có đều trở thành plugin mà không cần viết Python. Những người khác là **máy chủ bên ngoài** (MCP) mà tác nhân kết nối và tự động đăng ký các công cụ từ đó. Và một số là **thư mục thả vào** (móc cổng) với định dạng tệp kê khai riêng. Chọn bề mặt phù hợp cho kiểu tích hợp phù hợp với trường hợp sử dụng của bạn; hướng dẫn soạn thảo trong bảng phía trên mỗi phần bao gồm phần giữ chỗ, khám phá và ví dụ.
:::

## Plugin khai báo NixOS

Trên NixOS, các plugin có thể được cài đặt theo cách khai báo thông qua các tùy chọn mô-đun - không cần 
`Hermes plugins install

. Xem **[Nix Setup guide](/docs/getting-started/nix-setup#plugins)** để biết chi tiết đầy đủ.

`nix
services.Hermes-agent = &#123;
  # Directory plugin (source tree with plugin.YAML)
  extraPlugins = [ (pkgs.fetchFromGitHub &#123; ... &#125;) ];
  # Entry-point plugin (pip package)
  extraPythonPackages = [ (pkgs.Python312Packages.buildPythonPackage &#123; ... &#125;) ];
  # Enable in config
  settings.plugins.enabled = [ "my-plugin" ];
&#125;;

`
``Các plugin khai báo được liên kết tượng trưng với tiền tố 
`nix-managed-

 - chúng cùng tồn tại với các plugin được cài đặt thủ công và được dọn sạch tự động khi bị xóa khỏi cấu hình Nix.

## Quản lý plugin

``` bash
Hermes plugins                                       # unified interactive UI
Hermes plugins list                                  # table: enabled / disabled / not enabled
Hermes plugins install user/repo                     # install from Git, then prompt Enable? [y/N]
Hermes plugins install user/repo --enable            # install AND enable (no prompt)
Hermes plugins install user/repo --no-enable         # install but leave disabled (no prompt)
Hermes plugins update my-plugin                      # pull latest
Hermes plugins remove my-plugin                      # uninstall
Hermes plugins enable my-plugin                      # add to allow-list (flat plugin)
Hermes plugins enable observability/Langfuse         # add to allow-list (sub-category plugin)
Hermes plugins disable my-plugin                     # remove from allow-list + add to disabled

`
``Đối với các plugin trong thư mục danh mục phụ (ví dụ: 
`plugins/observability/Langfuse/

, 
`plugins/image_gen/OpenAI/

), hãy sử dụng khóa 

&lt;category/&lt;plugin
` đầy đủ — đó chính xác là những gì 
`Hermes plugins list
` hiển thị trong cột **Tên**.

### Giao diện người dùng tương tác

Chạy 
`Hermes plugins
` không có đối số sẽ mở ra màn hình tương tác tổng hợp:

`
Plugins
  ↑↓ navigate  SPACE toggle  ENTER configure/confirm  ESC done

General Plugins
 → [✓] my-tool-plugin — Custom search tool
   [ ] webhook-notifier — Event hooks
   [ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled]
   [ ] observability/Langfuse — Trace turns / LLM calls / tools to Langfuse [bundled]

Provider Plugins
     Memory Provider          ▸ Honcho
     Context Engine           ▸ compressor

`

- **Phần Plugin chung** — các hộp kiểm, chuyển đổi bằng SPACE. Đã chọn = trong 
`plugins.enabled

, bỏ chọn = trong 
`plugins.disabled
` (tắt rõ ràng).

- **Phần Plugin nhà cung cấp** — hiển thị lựa chọn hiện tại. Nhấn ENTER để đi sâu vào bộ chọn đài nơi bạn chọn một nhà cung cấp đang hoạt động.
- Các plugin đi kèm xuất hiện trong cùng danh sách với thẻ 

[bundled]

.

Các lựa chọn plugin của nhà cung cấp được lưu vào 
`config.yaml

:

``` yaml
memory:
  provider: "Honcho"      # empty string = built-in only`context:
  engine: "compressor"    # default built-in compressor

`

### Đã bật so với bị vô hiệu hóa so với không

Các plugin chiếm một trong ba trạng thái:

| Tiểu bang | Ý nghĩa | Trong 
`plugins.enabled

? | Trong 
`plugins.disabled

? |
|---|---|---|---|
| 
`enabled
` | Đã tải vào phiên tiếp theo | Có | Không |
| 
`disabled
` | Tắt hoàn toàn — sẽ không tải ngay cả khi có trong 
`enabled
` | (không liên quan) | Có |
| 
`not enabled
` | Đã phát hiện nhưng chưa bao giờ chọn tham gia | Không | Không |

Mặc định cho plugin mới được cài đặt hoặc đi kèm là 
`not enabled

. 
`Hermes plugins list
` hiển thị cả ba trạng thái riêng biệt để bạn có thể biết trạng thái nào đã bị tắt rõ ràng và trạng thái nào đang chờ được bật.

Trong phiên chạy, 

/plugins
` hiển thị plugin nào hiện đang được tải.

## Chèn tin nhắn

Các plugin có thể đưa tin nhắn vào cuộc trò chuyện đang diễn ra bằng 
`ctx.inject_message()

:

`Python
ctx.inject_message("New data arrived from the webhook", role="user")

`
``**Chữ ký:** 
`ctx.inject_message(content: str, role: str = "user") -> bool
``Nó hoạt động như thế nào:
- Nếu tác nhân **nhàn rỗi** (đợi người dùng nhập), tin nhắn sẽ được xếp hàng đợi làm đầu vào tiếp theo và bắt đầu một lượt mới.

- Nếu tác nhân đang **giữa lượt** (đang chạy), thông báo sẽ làm gián đoạn hoạt động hiện tại — giống như việc người dùng nhập tin nhắn mới và nhấn Enter.
- Đối với các vai trò không phải 

"user"

, nội dung có tiền tố 

[role]
` (ví dụ: 

[system] ...

).
- Trả về 
`True
` nếu tin nhắn được xếp hàng thành công, 
`False
` nếu không có tham chiếu CLI (ví dụ: ở chế độ cổng).

Điều này cho phép các plugin như trình xem điều khiển từ xa, cầu nối nhắn tin hoặc trình nhận webhook đưa tin nhắn vào cuộc trò chuyện từ các nguồn bên ngoài.

:::note
`inject_message
` chỉ khả dụng ở chế độ CLI. Ở chế độ cổng, không có tham chiếu CLI và phương thức trả về 
`False

.
:::

Xem **[full guide](/docs/guides/build-a-Hermes-plugin)** để biết các hợp đồng xử lý, định dạng lược đồ, hành vi hook, xử lý lỗi và các lỗi phổ biến.
Tổng quan nhanh​

Ví dụ hoạt động tối thiểu​

Tổng quan nhanh

Ví dụ hoạt động tối thiểu
