Skills (OpenClaw)

OpenClaw sử dụng các thư mục skill tương thích với AgentSkills để dạy Agent cách sử dụng công cụ. Mỗi skill là một thư mục chứa file SKILL.md với YAML frontmatter và hướng dẫn. OpenClaw tải bundled skills cùng với các override tùy chọn từ local, và lọc chúng khi load dựa trên môi trường, config và sự hiện diện của binary.

Vị trí và thứ tự ưu tiên

Skills được tải từ ba nơi:

Bundled skills: đi kèm với bản cài đặt (npm package hoặc OpenClaw.app)
Managed/local skills: ~/.openclaw/skills
Workspace skills: <workspace>/skills

Nếu tên skill bị trùng, thứ tự ưu tiên là:

<workspace>/skills (cao nhất) → ~/.openclaw/skills → bundled skills (thấp nhất)

Ngoài ra, các bạn có thể cấu hình thêm các thư mục skill (ưu tiên thấp nhất) qua skills.load.extraDirs trong ~/.openclaw/openclaw.json.

Per-agent vs shared skills

Trong các thiết lập multi-agent, mỗi agent có workspace riêng. Điều đó có nghĩa là:

Per-agent skills nằm trong <workspace>/skills chỉ dành cho agent đó.
Shared skills nằm trong ~/.openclaw/skills (managed/local) và hiển thị với tất cả agents trên cùng một máy.
Shared folders cũng có thể được thêm qua skills.load.extraDirs (ưu tiên thấp nhất) nếu các bạn muốn một gói skills chung được dùng bởi nhiều agents.

Nếu cùng một tên skill tồn tại ở nhiều nơi, thứ tự ưu tiên thông thường được áp dụng: workspace thắng, sau đó managed/local, rồi bundled.

Plugins + skills

Plugins có thể đi kèm skills riêng bằng cách liệt kê các thư mục skills trong openclaw.plugin.json (đường dẫn tương đối với plugin root). Plugin skills được tải khi plugin được bật và tham gia vào các quy tắc ưu tiên skill thông thường. Các bạn có thể gate chúng qua metadata.openclaw.requires.config trên config entry của plugin. Xem Plugins để biết về discovery/config và Tools cho tool surface mà các skills đó dạy.

ClawHub (install + sync)

ClawHub là registry skills công khai cho OpenClaw. Truy cập tại https://clawhub.com. Dùng nó để khám phá, cài đặt, cập nhật và backup skills. Hướng dẫn đầy đủ: ClawHub.

Các luồng phổ biến:

Cài skill vào workspace của bạn:
- clawhub install <skill-slug>
Cập nhật tất cả skills đã cài:
- clawhub update --all
Sync (scan + publish updates):
- clawhub sync --all

Mặc định, clawhub cài vào ./skills trong thư mục làm việc hiện tại (hoặc fallback về OpenClaw workspace đã cấu hình). OpenClaw nhận nó như <workspace>/skills ở session tiếp theo.

Lưu ý bảo mật

Coi các skills từ bên thứ ba là untrusted code. Đọc chúng trước khi bật.
Ưu tiên chạy sandboxed cho các inputs không tin cậy và công cụ rủi ro. Xem Sandboxing.
skills.entries.*.env và skills.entries.*.apiKey inject secrets vào process host cho agent turn đó (không phải sandbox). Giữ secrets ra khỏi prompts và logs.
Để biết threat model rộng hơn và checklists, xem Security.

Format (AgentSkills + Pi-compatible)

SKILL.md phải bao gồm ít nhất:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
---

Lưu ý:

Mình tuân theo spec AgentSkills cho layout/intent.
Parser được dùng bởi embedded agent chỉ hỗ trợ các key frontmatter single-line.
metadata nên là một single-line JSON object.
Dùng {baseDir} trong instructions để tham chiếu đường dẫn thư mục skill.
Các key frontmatter tùy chọn:
- homepage — URL hiển thị như “Website” trong macOS Skills UI (cũng được hỗ trợ qua metadata.openclaw.homepage).
- user-invocable — true|false (mặc định: true). Khi true, skill được expose như một user slash command.
- disable-model-invocation — true|false (mặc định: false). Khi true, skill bị loại khỏi model prompt (vẫn có sẵn qua user invocation).
- command-dispatch — tool (tùy chọn). Khi set thành tool, slash command bỏ qua model và dispatch trực tiếp đến một tool.
- command-tool — tên tool để invoke khi command-dispatch: tool được set.
- command-arg-mode — raw (mặc định). Cho tool dispatch, forwards chuỗi args thô đến tool (không parse core).
  
  Tool được invoke với params: { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

Gating (load-time filters)

OpenClaw lọc skills khi load bằng cách dùng metadata (single-line JSON):

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

Các field trong metadata.openclaw:

always: true — luôn bao gồm skill (bỏ qua các gates khác).
emoji — emoji tùy chọn được dùng bởi macOS Skills UI.
homepage — URL tùy chọn hiển thị như “Website” trong macOS Skills UI.
os — danh sách platforms tùy chọn (darwin, linux, win32). Nếu set, skill chỉ eligible trên các OSes đó.
requires.bins — danh sách; mỗi cái phải tồn tại trên PATH.
requires.anyBins — danh sách; ít nhất một phải tồn tại trên PATH.
requires.env — danh sách; env var phải tồn tại hoặc được cung cấp trong config.
requires.config — danh sách các đường dẫn openclaw.json phải là truthy.
primaryEnv — tên env var liên kết với skills.entries.<name>.apiKey.
install — mảng tùy chọn các installer specs được dùng bởi macOS Skills UI (brew/node/go/uv/download).

Lưu ý về sandboxing:

requires.bins được kiểm tra trên host khi load skill.
Nếu một agent được sandboxed, binary cũng phải tồn tại bên trong container. Cài nó qua agents.defaults.sandbox.docker.setupCommand (hoặc một custom image). setupCommand chạy một lần sau khi container được tạo. Package installs cũng yêu cầu network egress, một writable root FS, và một root user trong sandbox. Ví dụ: skill summarize (skills/summarize/SKILL.md) cần summarize CLI trong sandbox container để chạy ở đó.

Ví dụ installer:

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

Lưu ý:

Nếu nhiều installers được liệt kê, gateway chọn một tùy chọn ưu tiên duy nhất (brew khi có sẵn, nếu không thì node).
Nếu tất cả installers là download, OpenClaw liệt kê từng entry để các bạn có thể thấy các artifacts có sẵn.
Installer specs có thể bao gồm os: ["darwin"|"linux"|"win32"] để lọc tùy chọn theo platform.
Node installs tuân theo skills.install.nodeManager trong openclaw.json (mặc định: npm; tùy chọn: npm/pnpm/yarn/bun). Điều này chỉ ảnh hưởng đến skill installs; Gateway runtime vẫn nên là Node (Bun không được khuyên dùng cho WhatsApp/Telegram).
Go installs: nếu go thiếu và brew có sẵn, gateway cài Go qua Homebrew trước và set GOBIN thành bin của Homebrew khi có thể.
Download installs: url (bắt buộc), archive (tar.gz | tar.bz2 | zip), extract (mặc định: auto khi phát hiện archive), stripComponents, targetDir (mặc định: ~/.openclaw/tools/<skillKey>).

Nếu không có metadata.openclaw, skill luôn eligible (trừ khi bị disabled trong config hoặc bị chặn bởi skills.allowBundled cho bundled skills).

Config overrides (`~/.openclaw/openclaw.json`)

Bundled/managed skills có thể được toggle và cung cấp với các giá trị env:

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Lưu ý: nếu tên skill chứa dấu gạch ngang, quote key (JSON5 cho phép quoted keys).

Config keys khớp với skill name theo mặc định. Nếu một skill định nghĩa metadata.openclaw.skillKey, dùng key đó trong skills.entries.

Quy tắc:

enabled: false vô hiệu hóa skill ngay cả khi nó bundled/installed.
env: được inject chỉ khi biến chưa được set trong process.
apiKey: tiện lợi cho các skills khai báo metadata.openclaw.primaryEnv.
config: bag tùy chọn cho các field per-skill tùy chỉnh; các key tùy chỉnh phải nằm ở đây.
allowBundled: allowlist tùy chọn chỉ cho bundled skills. Nếu set, chỉ bundled skills trong danh sách là eligible (managed/workspace skills không bị ảnh hưởng).

Environment injection (per agent run)

Khi một agent run bắt đầu, OpenClaw:

Đọc skill metadata.
Áp dụng bất kỳ skills.entries.<key>.env hoặc skills.entries.<key>.apiKey nào vào process.env.
Build system prompt với các skills eligible.
Khôi phục môi trường gốc sau khi run kết thúc.

Điều này được scoped cho agent run, không phải một global shell environment.

Session snapshot (performance)

OpenClaw snapshot các eligible skills khi một session bắt đầu và tái sử dụng danh sách đó cho các turns tiếp theo trong cùng session. Các thay đổi đối với skills hoặc config có hiệu lực ở session mới tiếp theo.

Skills cũng có thể refresh giữa session khi skills watcher được bật hoặc khi một remote node eligible mới xuất hiện (xem bên dưới). Nghĩ về điều này như một hot reload: danh sách đã refresh được nhận ở agent turn tiếp theo.

Remote macOS nodes (Linux gateway)

Nếu Gateway đang chạy trên Linux nhưng một macOS node được kết nối với system.run được phép (Exec approvals security không set thành deny), OpenClaw có thể coi các macOS-only skills là eligible khi các binaries yêu cầu có mặt trên node đó. Agent nên thực thi các skills đó qua tool nodes (thường là nodes.run).

Điều này dựa vào node báo cáo command support của nó và trên một bin probe qua system.run. Nếu macOS node offline sau đó, các skills vẫn hiển thị; invocations có thể fail cho đến khi node reconnect.

Skills watcher (auto-refresh)

Mặc định, OpenClaw theo dõi các thư mục skill và bumps skills snapshot khi các file SKILL.md thay đổi. Cấu hình điều này trong skills.load:

{
  skills: {
    load: {
      watch: true,
      watchDebounceMs: 250,
    },
  },
}

Token impact (skills list)

Khi skills eligible, OpenClaw inject một danh sách XML compact của các skills có sẵn vào system prompt (qua formatSkillsForPrompt trong pi-coding-agent). Chi phí là deterministic:

Base overhead (chỉ khi ≥1 skill): 195 ký tự.
Per skill: 97 ký tự + độ dài của các giá trị <name>, <description>, và <location> đã XML-escaped.

Công thức (ký tự):

total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))

Lưu ý:

XML escaping mở rộng & < > " ' thành entities (&, <, v.v.), tăng độ dài.
Token counts thay đổi theo model tokenizer. Một ước tính kiểu OpenAI thô là ~4 chars/token, vì vậy 97 chars ≈ 24 tokens per skill cộng với độ dài field thực tế của các bạn.

Managed skills lifecycle

OpenClaw đi kèm một bộ skills cơ bản như bundled skills như một phần của bản cài đặt (npm package hoặc OpenClaw.app). ~/.openclaw/skills tồn tại cho các local overrides (ví dụ, pinning/patching một skill mà không thay đổi bundled copy). Workspace skills thuộc sở hữu của user và override cả hai khi tên bị trùng.

Config reference

Xem Skills config cho schema cấu hình đầy đủ.

Tìm thêm skills?

Truy cập https://clawhub.com.

Skills (OpenClaw)

Vị trí và thứ tự ưu tiên

Per-agent vs shared skills

Plugins + skills

ClawHub (install + sync)

Lưu ý bảo mật

Format (AgentSkills + Pi-compatible)

Gating (load-time filters)

Config overrides (~/.openclaw/openclaw.json)

Environment injection (per agent run)

Session snapshot (performance)

Remote macOS nodes (Linux gateway)

Skills watcher (auto-refresh)

Token impact (skills list)

Managed skills lifecycle

Config reference

Tìm thêm skills?

Config overrides (`~/.openclaw/openclaw.json`)