Cấu hình Skills

Hầu hết cấu hình Skills nằm trong skills tại ~/.openclaw/openclaw.json. Khả năng hiển thị dành riêng cho từng agent nằm trong agents.defaults.skills và agents.list[].skills.

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
      allowUploadedArchives: false,
    },
    workshop: {
      autonomous: { enabled: false },
      allowSymlinkTargetWrites: false,
      approvalPolicy: "auto",
      maxPending: 50,
      maxSkillBytes: 40000,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

Để tạo hình ảnh tích hợp sẵn, hãy sử dụng agents.defaults.imageGenerationModel cùng với công cụ image_generate cốt lõi thay vì skills.entries. Các mục Skills chỉ dành cho quy trình Skills tùy chỉnh hoặc của bên thứ ba.

​

Tải (skills.load)

skills.load.extraDirs · string[]

Các thư mục Skills bổ sung cần quét, có mức ưu tiên thấp nhất (thấp hơn Skills đi kèm và Skills của Plugin). Đường dẫn được mở rộng với hỗ trợ ~.

skills.load.allowSymlinkTargets · string[]

Các thư mục đích thực, đáng tin cậy mà thư mục Skills dùng liên kết tượng trưng có thể phân giải tới, ngay cả khi liên kết tượng trưng nằm ngoài thư mục gốc đã cấu hình. Sử dụng tùy chọn này cho các bố cục kho lưu trữ ngang hàng có chủ đích như <workspace>/skills/manager -> ~/Projects/manager/skills. Giữ danh sách này ở phạm vi hẹp — không trỏ đến các thư mục gốc rộng như ~ hoặc ~/Projects.

skills.load.watch · boolean · mặc định: "true"

Theo dõi các thư mục Skills và làm mới ảnh chụp nhanh Skills khi các tệp SKILL.md thay đổi. Bao gồm các tệp lồng nhau trong các thư mục gốc Skills được nhóm.

skills.load.watchDebounceMs · number · mặc định: "250"

Khoảng thời gian chống dội cho các sự kiện theo dõi Skills, tính bằng mili giây.

​

Cài đặt (skills.install)

skills.install.preferBrew · boolean · mặc định: "true"

Ưu tiên trình cài đặt Homebrew khi có brew.

skills.install.nodeManager · "npm" | "pnpm" | "yarn" | "bun" · mặc định: "\"npm\""

Lựa chọn ưu tiên trình quản lý gói Node để cài đặt Skills. Tùy chọn này chỉ ảnh hưởng đến việc cài đặt Skills — CLI OpenClaw và môi trường chạy Gateway yêu cầu Node vì kho trạng thái chuẩn sử dụng node:sqlite. openclaw setup --node-manager và openclaw onboard --node-manager chấp nhận npm, pnpm hoặc bun; đặt "yarn" trực tiếp trong cấu hình để cài đặt Skills dựa trên Yarn.

skills.install.allowUploadedArchives · boolean · mặc định: "false"

Cho phép các máy khách Gateway operator.admin đáng tin cậy cài đặt kho lưu trữ zip riêng tư được đưa vào vùng tạm thông qua skills.upload.*. Các lượt cài đặt ClawHub thông thường không cần thiết lập này.

​

Chính sách cài đặt của người vận hành (security.installPolicy)

Sử dụng security.installPolicy khi người vận hành cần một lệnh cục bộ đáng tin cậy để phê duyệt hoặc chặn việc cài đặt Skills và Plugin bằng chính sách dành riêng cho máy chủ. Chính sách chạy sau khi OpenClaw đã đưa tài liệu nguồn vào vùng tạm và trước khi quá trình cài đặt hoặc cập nhật tiếp tục. Chính sách áp dụng cho Skills ClawHub, Skills đã tải lên, Skills từ Git/cục bộ, trình cài đặt phần phụ thuộc của Skills và các nguồn cài đặt/cập nhật Plugin.

{
  security: {
    installPolicy: {
      enabled: true,
      // Bỏ qua targets để áp dụng cho mọi mục tiêu được hỗ trợ.
      targets: ["skill", "plugin"],
      exec: {
        source: "exec",
        command: "/usr/local/bin/openclaw-install-policy",
        args: ["--json"],
        timeoutMs: 10000,
        noOutputTimeoutMs: 10000,
        maxOutputBytes: 1048576,
        passEnv: ["OPENCLAW_STATE_DIR", "PATH"],
        env: { POLICY_MODE: "strict" },
        trustedDirs: ["/usr/local/bin"],
      },
    },
  },
}

security.installPolicy.enabled · boolean · mặc định: "false"

Bật chính sách cài đặt do người vận hành sở hữu. Khi được bật mà không có lệnh exec hợp lệ, quá trình cài đặt sẽ đóng khi lỗi.

security.installPolicy.targets · ("skill" | "plugin")[]

Bộ lọc mục tiêu tùy chọn. Khi bỏ qua, chính sách áp dụng cho mọi mục tiêu được hỗ trợ để các lượt cài đặt mới không bất ngờ mở khi lỗi.

security.installPolicy.exec.command · string

Đường dẫn tuyệt đối đến tệp thực thi chính sách đáng tin cậy. OpenClaw chạy tệp này mà không dùng shell và xác thực đường dẫn trước khi sử dụng.

security.installPolicy.exec.args · string[]

Các đối số tĩnh được truyền sau command.

security.installPolicy.exec.timeoutMs · number · mặc định: "10000"

Thời gian chạy theo đồng hồ thực tối đa cho một quyết định chính sách.

security.installPolicy.exec.noOutputTimeoutMs · number · mặc định: "timeoutMs"

Thời gian tối đa không có đầu ra stdout hoặc stderr trước khi chính sách đóng khi lỗi.

security.installPolicy.exec.maxOutputBytes · number · mặc định: "1048576"

Số byte stdout và stderr kết hợp tối đa được chấp nhận từ tiến trình chính sách.

security.installPolicy.exec.env · Record<string, string>

Các biến môi trường dạng chữ được cung cấp cho tiến trình chính sách.

security.installPolicy.exec.passEnv · string[]

Tên các biến môi trường được sao chép từ tiến trình OpenClaw vào tiến trình chính sách. Chỉ các biến được nêu tên mới được truyền.

security.installPolicy.exec.trustedDirs · string[]

Danh sách cho phép tùy chọn gồm các thư mục có thể chứa tệp thực thi chính sách.

security.installPolicy.exec.allowInsecurePath · boolean · mặc định: "false"

Bỏ qua các bước kiểm tra quyền sở hữu và quyền truy cập của đường dẫn lệnh. Chỉ sử dụng khi đường dẫn được bảo vệ bằng một cơ chế khác.

security.installPolicy.exec.allowSymlinkCommand · boolean · mặc định: "false"

Cho phép đường dẫn lệnh đã cấu hình là một liên kết tượng trưng. Đích đã phân giải vẫn phải đáp ứng các bước kiểm tra đường dẫn khác. Đối số tập lệnh của trình thông dịch phải là tệp thông thường trực tiếp, không phải liên kết tượng trưng.

Chính sách nhận một đối tượng JSON trên stdin với protocolVersion: 1, openclawVersion, targetType, targetName, sourcePath, sourcePathKind, source có cấu trúc và tùy chọn, origin có cấu trúc và request. Chính sách phải ghi một đối tượng JSON trên stdout: { "protocolVersion": 1, "decision": "allow" } hoặc { "protocolVersion": 1, "decision": "block", "reason": "..." }. Mã thoát khác 0, hết thời gian chờ, JSON không hợp lệ, thiếu trường hoặc phiên bản giao thức không được hỗ trợ đều khiến hệ thống đóng khi lỗi.

OpenClaw không thực thi chính sách cài đặt trong quá trình khởi động Gateway thông thường. Các lượt cài đặt và cập nhật sẽ đóng khi lỗi nếu chính sách được bật nhưng không khả dụng. openclaw doctor thực hiện xác thực tĩnh; openclaw doctor --deep thực thi một phép thăm dò cài đặt mô phỏng đối với lệnh đã cấu hình.

Cập nhật hàng loạt áp dụng chính sách cho từng mục tiêu: một bản cập nhật Skills hoặc Plugin bị chặn sẽ làm mục tiêu đó thất bại mà không vô hiệu hóa chính sách hoặc bỏ qua các mục tiêu sau trong lô.

Ví dụ stdin:

{
  "protocolVersion": 1,
  "openclawVersion": "2026.6.1",
  "targetType": "skill",
  "targetName": "weather",
  "sourcePath": "/var/folders/.../openclaw-skill-clawhub/root",
  "sourcePathKind": "directory",
  "source": {
    "kind": "clawhub",
    "authority": "openclaw",
    "mutable": false,
    "network": true
  },
  "origin": {
    "type": "clawhub",
    "registry": "https://clawhub.openclaw.ai",
    "slug": "weather",
    "version": "1.0.0"
  },
  "request": {
    "kind": "skill-install",
    "mode": "install",
    "requestedSpecifier": "clawhub:weather@1.0.0"
  },
  "skill": {
    "installId": "clawhub"
  }
}

Lệnh chính sách tối thiểu:

#!/usr/bin/env node

let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  input += chunk;
});
process.stdin.on("end", () => {
  const request = JSON.parse(input);
  if (request.targetType === "plugin" && request.source?.kind === "local-path") {
    process.stdout.write(
      JSON.stringify({
        protocolVersion: 1,
        decision: "block",
        reason: "đường dẫn plugin cục bộ không được phê duyệt trên máy chủ này",
      }),
    );
    return;
  }
  process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));
});

​

Danh sách cho phép Skills đi kèm

skills.allowBundled · string[]

Danh sách cho phép tùy chọn chỉ dành cho Skills đi kèm. Khi được đặt, chỉ Skills đi kèm trong danh sách mới đủ điều kiện. Skills được quản lý, ở cấp agent và trong không gian làm việc không bị ảnh hưởng.

​

Mục dành cho từng Skills (skills.entries)

Theo mặc định, các khóa trong entries khớp với name của Skills. Nếu một Skills định nghĩa metadata.openclaw.skillKey, hãy sử dụng khóa đó thay thế. Đặt tên có dấu gạch nối trong dấu ngoặc kép (JSON5 cho phép khóa được đặt trong dấu ngoặc kép).

skills.entries.<key>.enabled · boolean

false vô hiệu hóa Skills ngay cả khi đi kèm hoặc đã cài đặt. Skills đi kèm coding-agent yêu cầu chủ động bật — đặt thành true và bảo đảm một trong claude, codex, opencode hoặc CLI được hỗ trợ khác đã được cài đặt và xác thực.

skills.entries.<key>.apiKey · string | { source, provider, id }

Trường tiện ích dành cho Skills khai báo metadata.openclaw.primaryEnv. Hỗ trợ chuỗi văn bản thuần hoặc SecretRef: { source: "env", provider: "default", id: "VAR_NAME" }.

skills.entries.<key>.env · Record<string, string>

Các biến môi trường được chèn vào lượt chạy agent. Chỉ được chèn khi biến chưa được đặt trong tiến trình.

skills.entries.<key>.config · object

Đối tượng tùy chọn chứa các trường cấu hình tùy chỉnh cho từng Skills.

​

Danh sách cho phép của agent (agents)

Sử dụng cấu hình agent khi muốn dùng cùng các thư mục gốc Skills của máy/không gian làm việc nhưng mỗi agent có một tập Skills hiển thị khác nhau.

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // đường cơ sở dùng chung
    },
    list: [
      { id: "writer" }, // kế thừa github, weather
      { id: "docs", skills: ["docs-search"] }, // thay thế hoàn toàn giá trị mặc định
      { id: "locked-down", skills: [] }, // không có Skills
    ],
  },
}

agents.defaults.skills · string[]

Danh sách cho phép cơ sở dùng chung được kế thừa bởi các agent bỏ qua agents.list[].skills. Bỏ qua hoàn toàn để mặc định không hạn chế Skills.

agents.list[].skills · string[]

Tập Skills cuối cùng được chỉ định rõ cho agent đó. Các danh sách được chỉ định rõ sẽ thay thế giá trị mặc định được kế thừa — chúng không hợp nhất. Đặt thành [] để không hiển thị Skills nào cho agent đó.

Danh sách cho phép Skills của agent là bộ lọc khả năng hiển thị và tải cho hoạt động khám phá Skills, lời nhắc, khám phá lệnh gạch chéo, đồng bộ sandbox và ảnh chụp nhanh Skills của OpenClaw. Đây không phải là ranh giới ủy quyền tại thời điểm chạy shell. Nếu một agent có thể chạy exec trên máy chủ, shell đó vẫn có thể chạy các máy khách bên ngoài hoặc đọc các tệp máy chủ hiển thị với người dùng thực thi, bao gồm các sổ đăng ký máy khách MCP như ~/.openclaw/skills/config/mcporter.json. Để cô lập MCP theo từng agent, hãy kết hợp danh sách cho phép Skills với cơ chế cô lập sandbox/người dùng hệ điều hành, từ chối hoặc giới hạn nghiêm ngặt quyền thực thi trên máy chủ bằng danh sách cho phép, đồng thời ưu tiên thông tin xác thực riêng cho từng agent tại máy chủ MCP.

​

Workshop (skills.workshop)

skills.workshop.autonomous.enabled · boolean · mặc định: "false"

Khi true, OpenClaw có thể tạo các đề xuất đang chờ xử lý từ những bản sửa lỗi bền vững và có thể xem xét công việc đáng kể đã hoàn thành thành công sau khi hệ thống chuyển sang trạng thái rảnh. Điều này có thể thêm một lượt chạy mô hình nền sau các lượt đủ điều kiện. Việc tạo skill theo yêu cầu của người dùng và /learn vẫn hoạt động khi cài đặt là false.

Xem Tự học để biết điều kiện đủ, quyền riêng tư, chi phí, quyền chỉ dành cho đề xuất và cách khắc phục sự cố.

skills.workshop.approvalPolicy · "pending" | "auto" · mặc định: "\"auto\""

auto cho phép tác nhân tự khởi tạo việc áp dụng, từ chối hoặc cách ly mà không cần thêm lời nhắc phê duyệt. pending yêu cầu người vận hành phê duyệt.

skills.workshop.allowSymlinkTargetWrites · boolean · mặc định: "false"

Cho phép thao tác áp dụng của Skill Workshop ghi thông qua các liên kết tượng trưng đến skill trong không gian làm việc có đích thực đã được skills.load.allowSymlinkTargets tin cậy. Hãy giữ tùy chọn này ở trạng thái tắt trừ khi việc áp dụng đề xuất được tạo cần sửa đổi thư mục gốc skill dùng chung đó.

skills.workshop.maxPending · number · mặc định: "50"

Số lượng tối đa các đề xuất đang chờ xử lý và bị cách ly được giữ lại trên mỗi không gian làm việc (phạm vi cho phép: 1-200).

skills.workshop.maxSkillBytes · number · mặc định: "40000"

Kích thước nội dung đề xuất tối đa tính bằng byte (phạm vi cho phép: 1024-200000). Phần mô tả đề xuất được giới hạn cứng riêng ở 160 byte vì chúng xuất hiện trong kết quả khám phá và liệt kê.

Xem Skill Workshop để biết vòng đời đề xuất, các lệnh CLI, tham số công cụ tác nhân và các phương thức Gateway mà cấu hình này kiểm soát.

​

Thư mục gốc skill dùng liên kết tượng trưng

Theo mặc định, các thư mục gốc skill của không gian làm việc, tác nhân dự án, thư mục bổ sung và skill đi kèm là các ranh giới bao chứa. Một thư mục skill dùng liên kết tượng trưng bên dưới <workspace>/skills mà phân giải ra bên ngoài thư mục gốc sẽ bị bỏ qua kèm theo thông báo nhật ký.

Để cho phép một bố cục liên kết tượng trưng có chủ đích, hãy khai báo đích đáng tin cậy:

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

Với cấu hình này, <workspace>/skills/manager -> ~/Projects/manager/skills được chấp nhận sau khi phân giải đường dẫn thực. extraDirs quét trực tiếp kho lưu trữ cùng cấp; allowSymlinkTargets giữ nguyên đường dẫn dùng liên kết tượng trưng cho các bố cục hiện có.

Theo mặc định, thao tác áp dụng của Skill Workshop không ghi thông qua các liên kết tượng trưng đó. Để cho phép thao tác áp dụng của Workshop sửa đổi các skill bên dưới các đích liên kết tượng trưng đã được tin cậy, hãy bật riêng tùy chọn này:

{
  skills: {
    load: {
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    workshop: {
      allowSymlinkTargetWrites: true,
    },
  },
}

Các thư mục ~/.openclaw/skills được quản lý và ~/.agents/skills cá nhân đã luôn chấp nhận vô điều kiện các liên kết tượng trưng đến thư mục skill (quy tắc bao chứa SKILL.md theo từng skill vẫn được áp dụng) — allowSymlinkTargets chỉ cần thiết cho các thư mục gốc của không gian làm việc, thư mục bổ sung và tác nhân dự án (<workspace>/.agents/skills).

​

Skill trong sandbox và biến môi trường

skills.entries.<skill>.env và apiKey chỉ áp dụng cho các lượt chạy trên máy chủ. Bên trong sandbox, chúng không có tác dụng — một skill phụ thuộc vào GEMINI_API_KEY sẽ thất bại với apiKey not configured trừ khi sandbox được cung cấp biến đó riêng.

Truyền các thông tin bí mật vào sandbox Docker bằng:

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          env: { GEMINI_API_KEY: "your-key-here" },
        },
      },
    },
  },
}

Người dùng có quyền truy cập daemon Docker có thể kiểm tra các giá trị sandbox.docker.env thông qua siêu dữ liệu Docker. Hãy sử dụng tệp bí mật được gắn kết, ảnh tùy chỉnh hoặc một phương thức truyền khác khi mức độ lộ thông tin đó không thể chấp nhận được.

​

Nhắc lại thứ tự tải

workspace/skills      (cao nhất)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
skill đi kèm
skills.load.extraDirs (thấp nhất)

Các thay đổi đối với skill và cấu hình có hiệu lực trong phiên mới tiếp theo khi trình theo dõi được bật, hoặc trong lượt tác nhân tiếp theo khi trình theo dõi phát hiện thay đổi.

​

Liên quan

Tài liệu tham khảo về skill

Khái niệm skill, thứ tự tải, kiểm soát điều kiện và định dạng SKILL.md.

Tạo skill

Biên soạn skill tùy chỉnh cho không gian làm việc.

Skill Workshop

Hàng đợi đề xuất dành cho các skill do tác nhân soạn thảo.

Tự học

Các đề xuất thận trọng, tự nguyện bật từ công việc đã hoàn thành.

Lệnh gạch chéo

Danh mục lệnh gạch chéo gốc và các chỉ thị trò chuyện.