Cấu hình Skills

Tất cả cấu hình liên quan đến skills nằm trong phần skills của file ~/.openclaw/openclaw.json.

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime vẫn dùng Node; không khuyên dùng bun)
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Các trường cấu hình

  • allowBundled: allowlist tùy chọn chỉ dành cho bundled skills. Khi được thiết lập, chỉ những bundled skills trong danh sách này mới được sử dụng (managed/workspace skills không bị ảnh hưởng).
  • load.extraDirs: các thư mục skill bổ sung để quét (độ ưu tiên thấp nhất).
  • load.watch: theo dõi các thư mục skill và làm mới snapshot (mặc định: true).
  • load.watchDebounceMs: thời gian debounce cho các sự kiện theo dõi skill tính bằng milliseconds (mặc định: 250).
  • install.preferBrew: ưu tiên dùng brew installers khi có sẵn (mặc định: true).
  • install.nodeManager: tùy chọn node installer (npm | pnpm | yarn | bun, mặc định: npm). Cái này chỉ ảnh hưởng đến việc cài đặt skill; Gateway runtime vẫn nên dùng Node (không khuyên dùng Bun cho WhatsApp/Telegram).
  • entries.<skillKey>: cấu hình ghi đè cho từng skill.

Các trường cho mỗi skill:

  • enabled: đặt false để vô hiệu hóa một skill ngay cả khi nó đã được bundled/cài đặt.
  • env: các biến môi trường được inject cho agent run (chỉ khi chưa được thiết lập).
  • apiKey: tiện ích tùy chọn cho các skill khai báo một biến env chính.

Lưu ý

  • Các key trong entries mặc định map với tên skill. Nếu một skill định nghĩa metadata.openclaw.skillKey, thì dùng key đó thay thế.
  • Các thay đổi đối với skills sẽ được áp dụng ở lượt agent tiếp theo khi watcher được bật.

Sandboxed skills + biến môi trường

Khi một session được sandboxed, các skill process chạy bên trong Docker. Sandbox không kế thừa process.env của host.

Các bạn dùng một trong các cách sau:

  • agents.defaults.sandbox.docker.env (hoặc theo từng agent agents.list[].sandbox.docker.env)
  • nhúng env vào custom sandbox image của các bạn

env toàn cục và skills.entries.<skill>.env/apiKey chỉ áp dụng cho host runs.