技能配置

大多数 skills 配置位于 ~/.openclaw/openclaw.json 的 skills 下。Agent 特定的可见性位于 agents.defaults.skills 和 agents.entries.*.skills 下。

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/path/to/agent-scripts/skills"],
      allowSymlinkTargets: ["~/path/to/skills"],
      watch: true,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
      allowUploadedArchives: false,
    },
    workshop: {
      autonomous: { mode: "auto" },
      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 },
    },
  },
}

Note

对于内置图像生成，请使用 agents.defaults.mediaModels.image 以及核心工具 image_generate，而不是 skills.entries。skill 条目仅用于自定义或第三方 skill 工作流。

加载（`skills.load`）¶

skills.load.extraDirs string[] (path): 要扫描的额外 skill 目录，优先级最低（低于内置 skills 和插件 skills）。路径支持 ~ 展开。
skills.load.allowSymlinkTargets string[] (path): 受信任的真实目标目录，被符号链接的 skill 文件夹即使符号链接位于配置根目录之外，也可以解析到这些目录。适用于有意的同级仓库布局，例如 <workspace>/skills/manager -> ~/path/to/skills。请让此列表保持狭窄——不要指向 ~ 或整个项目目录之类的宽泛根目录。
skills.load.watch boolean (path): 监听 skill 文件夹，并在 SKILL.md 文件变化时刷新 skill 快照。涵盖分组 skill 根目录下的嵌套文件。

安装（`skills.install`）¶

skills.install.preferBrew boolean (path): 当 brew 可用时，优先使用 Homebrew 安装程序。
skills.install.nodeManager "npm" | "pnpm" | "yarn" | "bun" (path) default: "npm": Node 包管理器偏好，仅影响 skill 安装。Node 仍是 OpenClaw 主要且推荐的运行时；Bun 1.4+（具备 WAL-reset-safe node:sqlite）作为显式运行时选择受支持。openclaw setup --node-manager 和 openclaw onboard --node-manager 接受 npm、pnpm 或 bun；如需使用 Yarn 进行 skill 安装，请在配置中直接设置 "yarn"。setup 会保留此偏好，除非你传入 --node-manager；全新配置默认使用 npm。
skills.install.allowUploadedArchives boolean (path) default: false: 允许受信任的 operator.admin Gateway 客户端安装通过 skills.upload.* 暂存的私有 zip 归档。普通的 ClawHub 安装不需要此设置。

操作员安装策略（`security.installPolicy`）¶

当操作员需要用受信任的本地命令按主机特定策略批准或阻止 skill 与插件安装时，可使用 security.installPolicy。该策略在 OpenClaw 完成源材料暂存之后、继续执行安装或更新之前运行。它适用于 ClawHub skills、上传的 skills、Git/本地 skills、skill 依赖安装器，以及插件安装/更新源。

{
  security: {
    installPolicy: {
      enabled: true,
      // Omit targets to cover every supported target.
      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 (path) default: false: 启用由操作员所有的安装策略。在启用但没有有效 exec 命令时，安装会失败关闭。
security.installPolicy.targets ("skill" | "plugin")[] (path): 可选的目标过滤条件。省略时，策略适用于所有受支持的目标，以免新安装意外失败开放（fail open）。
security.installPolicy.exec.command string (path): 受信任策略可执行文件的绝对路径。OpenClaw 不通过 shell 运行它，并在使用前校验路径。
security.installPolicy.exec.args string[] (path): 在 command 之后传递的静态参数。
security.installPolicy.exec.timeoutMs number (path) default: 10000: 单个策略决策的最大墙钟运行时间。
security.installPolicy.exec.noOutputTimeoutMs number (path) default: timeoutMs: 策略失败关闭前，无 stdout 或 stderr 输出的最长时间。
security.installPolicy.exec.maxOutputBytes number (path) default: 1048576: 接受自策略进程的 stdout 与 stderr 合并字节数上限。

提供给策略进程的字面环境变量。

security.installPolicy.exec.passEnv string[] (path): 从 OpenClaw 进程复制到策略进程的环境变量名称。仅传递指定的这些变量。
security.installPolicy.exec.trustedDirs string[] (path): 可选的目录允许列表，策略可执行文件可位于这些目录中。

策略命令和解释器脚本参数必须是直接的常规文件，具有受信任的所有权、受限的权限和可验证的父目录。符号链接和不安全路径会被拒绝。

策略进程从 stdin 接收一个 JSON 对象，其中包含 protocolVersion: 1、openclawVersion、targetType、targetName、sourcePath、sourcePathKind，以及可选的结构化 source、结构化 origin 和 request。它必须在 stdout 上写入一个 JSON 对象，其中包含 allow、warn 或 block 决策。warn 和 block 必须提供非空的 reason；每个决策都可以包含一个 findings 数组。每个 finding 都需要非空字符串字段 ruleId 和 message，以及一个取值为 info、warn 或 critical 的 severity。可选的 file 和 evidence 值必须是非空字符串；有限的数字 line 会向下取整，并限制在 1 到 Number.MAX_SAFE_INTEGER 的安全整数范围内。格式错误的 finding 条目会被忽略，无效的可选字段会被省略。非数组的 findings 值会被视为不存在。面向操作员的 reason 和 finding 文本限制为 1,000 个字符。OpenClaw 最多保留 100 条规范化后的 findings 用于显示。只有 warn 响应携带超过 100 个有效 findings 时才失败关闭且无法确认；allow 和 block 保留前 100 个。警告会在提交前停止安装。如果某个 warn 审查的完整渲染通知（包括标题、目标、清理后的 reason 与 findings，以及恢复指南）超过 4,000 字符的聚合显示限制，则该审查失败关闭，不会呈现部分审查。超出限制的 block 仍以有界拒绝作为终止结果，而 allow 上超出限制的 findings 会在有界诊断输出中汇总。交互式 CLI 插件和 skill 命令会要求操作员输入目标名称，使用的 install anyway 或 update anyway 文案与可疑 ClawHub 发布相同，然后在继续前再次运行策略。直接 CLI 上被拒绝的命令和非交互式命令，可以使用 --acknowledge-install-policy-warning 作为该命令调用中每个警告经审查后的明确批准；每个已批准的警告在继续前都会重新评估。Control UI 可以审查并批准其插件安装请求中的警告；该批准涵盖该调用中的所有警告，并且每个警告仍会被重新评估。其他基于 Gateway 的安装和自动安装，在缺少操作员确认流程时仍会被阻止。如果存在等效的直接插件或 skill 命令，请使用它来审查并批准该警告。否则，请修改 security.installPolicy，让被审查的请求返回 allow，然后重试受管流程。--force 不会批准策略警告。block、非零退出、超时、无效 JSON、非对象响应、缺失或无效的协议版本或决策，或缺失/为空的 warn/block reason，都会始终失败关闭。

OpenClaw 在正常 Gateway 启动期间不会执行安装策略。当策略已启用但不可用时，安装和更新会失败关闭（fail closed）。openclaw doctor 执行静态验证；openclaw doctor --deep 则针对所配置的命令执行一次模拟安装探测。

批量更新按目标逐一应用策略：某项技能或插件更新被阻止时，仅该目标失败，而不会禁用策略或跳过批次中的后续目标。

示例 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"
  }
}

最小策略命令：

#!/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: "local plugin paths are not approved on this host",
      }),
    );
    return;
  }
  process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));
});

内置技能允许列表¶

skills.allowBundled string[] (path): 仅针对内置技能的可选允许列表。设置后，只有列表中的内置技能才符合条件。托管技能、代理级技能和工作区技能不受影响。

按技能条目（`skills.entries`）¶

entries 下的键默认与技能 name 匹配。如果技能定义了 metadata.openclaw.skillKey，请改用该键。带连字符的名称请加引号（JSON5 允许带引号的键）。

false 会禁用该技能，即使它是内置或已安装的。coding-agent 内置技能为选择加入（opt-in）——将其设为 true，并确保 claude、codex、opencode 或其他受支持的 CLI 之一已安装并完成认证。

为声明了 metadata.openclaw.primaryEnv 的技能提供的便捷字段。支持纯文本字符串或 SecretRef：{ source: "env", provider: "default", id: "VAR_NAME" }。

为 agent 运行注入的环境变量。仅当该变量在进程中尚未设置时才注入。

可选的配置包，用于保存自定义的按技能配置字段。

Agent 允许列表（`agents`）¶

当你希望共享同一机器/工作区技能根目录、但为每个 agent 提供不同的可见技能集合时，请使用 agent 配置。

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // shared baseline
    },
    entries: {
      writer: { default: true }, // inherits github, weather
      docs: { skills: ["docs-search"] }, // replaces defaults entirely
      "locked-down": { skills: [] }, // no skills
    },
  },
}

agents.defaults.skills string[] (path): 共享基线允许列表，供省略了 agents.entries.*.skills 的 agent 继承。完全省略该项，以便默认不限制技能。
agents.entries.*.skills string[] (path): 该 agent 的显式最终技能集合。显式列表会替换继承的默认值——不会进行合并。设为 [] 可让该 agent 不暴露任何技能。

Warning

Agent 技能允许列表是 OpenClaw 技能发现、提示词、斜杠命令发现、沙箱同步和技能快照的可见性与加载过滤器，而非 shell 层的授权边界。如果 agent 能够运行宿主机 exec，该 shell 仍然可以运行外部客户端，或读取执行用户可见的宿主机文件，包括 MCP 客户端注册表（如 ~/.openclaw/skills/config/mcporter.json）。要实现按 agent 的 MCP 隔离，请将技能允许列表与沙箱/OS 用户隔离结合使用，对宿主机 exec 采取拒绝或严格白名单策略，并在 MCP 服务器端优先使用按 agent 的凭证。

Workshop（`skills.workshop`）¶

skills.workshop.autonomous.mode "off" | "propose" | "auto" (path) 默认值："auto": off 禁用自主捕获，同时保留持久指令的建议提示。propose 会根据纠正内容及大量已完成的工作创建待处理提案。auto 使用常规 agent 工具直接进行逐轮及每周 Workshop 维护，不进行提案扫描，也不创建自动回滚快照。即时前台修复仍会使用扫描器门控的提案应用流程。用户主动发起的技能创建、/learn 以及手动学习会话在所有模式下均继续有效。

有关资格、隐私、成本、仅提案权限及故障排查，请参阅自我学习。

skills.workshop.approvalPolicy "pending" | "auto" (path) 默认值："auto": auto 允许 agent 发起的应用、拒绝或隔离操作，而无需额外的批准提示。pending 需要操作员批准。
skills.workshop.maxPending number (path) 默认值：50: 每个 agent 保留的最大待处理及已隔离提案数量（允许范围：1-200）。
skills.workshop.maxSkillBytes number (path) 默认值：40000: 提案正文的最大字节数（允许范围：1024-200000）。提案描述另有 160 字节的硬上限，因为描述会出现在发现和列表输出中。

有关此配置所控制的提案生命周期、CLI 命令、代理工具参数和 Gateway 方法，请参阅 Skill Workshop。

符号链接技能根目录¶

默认情况下，workspace、project-agent、extra-dir 和 bundled 技能根目录是包含边界。位于 <workspace>/skills 下、解析到根目录之外的符号链接技能文件夹会被跳过，并记录一条日志消息。

若要允许有意设计的符号链接布局，请声明受信任的目标：

{
  skills: {
    load: {
      extraDirs: ["~/path/to/skills"],
      allowSymlinkTargets: ["~/path/to/skills"],
    },
  },
}

在此配置下，<workspace>/skills/manager -> ~/path/to/skills 在 realpath 解析后会被接受。extraDirs 会直接扫描同级仓库；allowSymlinkTargets 会为现有布局保留符号链接路径。

Skill Workshop 使用每个代理的 <state-dir>/agents/<agentId>/agent/workshop-skills 包含边界。它不使用 allowSymlinkTargets，并会拒绝解析到该目录之外的符号链接技能。

托管的 ~/.openclaw/skills 和个人 ~/.agents/skills 目录已无条件接受技能目录符号链接（每个技能的 SKILL.md 包含规则仍然适用）—— 仅 workspace、extra-dir 和 project-agent（<workspace>/.agents/skills）根目录需要 allowSymlinkTargets。

沙箱技能与环境变量¶

Warning

skills.entries.<skill>.env 和 apiKey 仅适用于 host 运行。在沙箱内部它们没有效果——依赖 GEMINI_API_KEY 的技能会因 apiKey not configured 而失败，除非单独向沙箱提供该变量。

使用以下方式将密钥传入 Docker 沙箱：

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

Note

具有 Docker 守护进程访问权限的用户可以通过 Docker 元数据检查 sandbox.docker.env 值。如果这种暴露不可接受，请使用挂载的密钥文件、自定义镜像或其他传递路径。

加载顺序提醒¶

有关源优先级（包括每个代理的 Workshop 层级），请参阅加载顺序；有关更改何时可见，请参阅快照与刷新。

技能参考

技能是什么、加载顺序、门控以及 SKILL.md 格式。

创建技能

编写自定义 workspace 技能。

Skill Workshop

代理起草技能的提案队列。

自我学习

来自已完成工作的保守型、可选启用的提案。

斜杠命令

原生斜杠命令目录和聊天指令。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

技能配置

加载（skills.load）¶

安装（skills.install）¶

操作员安装策略（security.installPolicy）¶