技能配置

大多数技能配置位于 ~/.openclaw/openclaw.json 中的 skills 下。按代理划分的可见性位于 agents.defaults.skills 和 agents.entries.*.skills 中。

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

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

加载（`skills.load`）

string[]

要扫描的额外 skill 目录，优先级最低（低于内置和插件 skill）。路径会展开，并支持 ~。

string[]

受信任的真实目标目录，符号链接的 skill 文件夹可以解析到这些目录中，即使符号链接位于配置的根目录之外。用于有意采用的兄弟仓库布局，例如 <workspace>/skills/manager -> ~/Projects/manager/skills。请将此列表保持得尽量精简——不要指向像 ~ 或 ~/Projects 这样过于宽泛的根目录。

boolean

default:"true"

监视 skill 文件夹，并在 SKILL.md 文件变更时刷新 skills 快照。覆盖分组 skill 根目录下的嵌套文件。

安装（`skills.install`）

boolean

default:"true"

在 brew 可用时优先使用 Homebrew 安装器。

"npm" | "pnpm" | "yarn" | "bun"

default:"\"npm\""

技能安装的 Node 包管理器偏好。此设置仅影响技能安装——OpenClaw CLI 和 Gateway 运行时需要 Node，因为规范状态存储使用 node:sqlite。openclaw setup --node-manager 和 openclaw onboard --node-manager 接受 npm、pnpm 或 bun；如果要使用基于 Yarn 的技能安装，请直接在配置中设置 "yarn"。

boolean

default:"false"

允许受信任的 operator.admin Gateway 客户端安装通过 skills.upload.* 暂存的私有 zip 压缩包。正常的 ClawHub 安装不需要此设置。

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

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

{
  security: {
    installPolicy: {
      enabled: true,
      // 省略 targets 可覆盖所有支持的目标。
      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"],
      },
    },
  },
}

boolean

default:"false"

启用操作员拥有的安装策略。启用但没有有效 exec 命令时，安装将失败并关闭。

("skill" | "plugin")[]

可选的目标过滤器。省略时，策略将应用于每个受支持的目标，因此新的安装不会意外地“失败开放”。

string

受信任策略可执行文件的绝对路径。OpenClaw 会在无 shell 的情况下运行它，并在使用前验证该路径。

string[]

在 command 之后传递的静态参数。

number

default:"10000"

单次策略决策的最大墙钟运行时间。

number

default:"timeoutMs"

在没有 stdout 或 stderr 输出的情况下，策略失败并关闭之前的最长时间。

number

default:"1048576"

策略进程可接受的 stdout 和 stderr 合计最大字节数。

Record<string, string>

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

string[]

从 OpenClaw 进程复制到策略进程的环境变量名称。仅传递命名的变量。

string[]

可选的目录白名单，策略可执行文件可以位于其中。

策略命令和解释器脚本参数必须是具有受信任所有权、受限权限且其父目录可验证的直接常规文件。符号链接和不安全路径将被拒绝。策略会在 stdin 上接收一个 JSON 对象，其中包含 protocolVersion: 1、openclawVersion、targetType、targetName、sourcePath、sourcePathKind、可选的结构化 source、结构化 origin 和 request。它必须在 stdout 上写入一个 JSON 对象：{ "protocolVersion": 1, "decision": "allow" } 或 { "protocolVersion": 1, "decision": "block", "reason": "..." }。非零退出、超时、JSON 格式错误、缺失字段或不支持的协议版本都会导致失败并关闭。 OpenClaw 在正常 Gateway 启动期间不会执行安装策略。当启用策略但策略不可用时，安装和更新会失败并关闭。
openclaw doctor 会执行静态验证；openclaw doctor --deep 会针对配置的命令执行一个合成安装探测。批量更新会按目标分别应用策略：被阻止的技能或插件更新只会使该目标失败，而不会禁用策略，也不会在批处理中跳过后续目标。输入示例：

{
  "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:[email protected]"
  },
  "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: "本地主机上的插件路径未获批准",
      }),
    );
    return;
  }
  process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));
});

捆绑技能白名单

string[]

仅适用于捆绑技能的可选允许列表。设置后，只有列表中的捆绑技能才具备资格。托管、代理级别和工作区技能不受影响。

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

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

boolean

false 会在技能即使已捆绑或已安装时也将其禁用。coding-agent 捆绑的技能默认不启用——将其设为 true，并确保已安装且已认证 claude、codex、opencode 或其他受支持的 CLI 之一。

string | { source, provider, id }

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

Record<string, string>

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

object

自定义按技能配置字段的可选对象。

代理允许列表（`agents`）

当你希望使用相同的机器/工作区技能根目录，但为每个代理提供不同的可见技能集时，请使用代理配置。

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

string[]

被未指定 agents.entries.*.skills 的代理继承的共享基线允许列表。完全省略则默认不限制技能。

string[]

该代理的显式最终技能集。显式列表会替换继承的默认值——不会合并。设置为 [] 可为该代理暴露零个技能。

代理技能允许列表是 OpenClaw 技能发现、提示词、斜杠命令发现、沙箱同步和技能快照的可见性与加载过滤器。它们不是 shell 运行时的授权边界。如果某个代理可以运行主机 exec，那么该 shell 仍然可以运行外部客户端，或读取执行用户可见的主机文件，包括诸如 ~/.openclaw/skills/config/mcporter.json 之类的 MCP 客户端注册表。对于按代理隔离 MCP，请将技能允许列表与沙箱/OS 用户隔离结合使用，禁止或严格允许主机 exec，并优先在 MCP 服务器端为每个代理使用凭据。

工作坊 (`skills.workshop`)

"off" | "propose" | "auto"

default:"\"auto\""

off 会在保留持久指令建议提示的同时禁用自主捕获。propose 会根据更正内容和已完成的重要工作创建待处理提案。auto 会通过正常的扫描器门控 Workshop 应用路径发送相同的捕获内容，并运行每日收集清理，以重写或丢弃符合条件的可写技能。用户提示的技能创建、/learn 和手动历史扫描在所有模式下都能继续工作。

请参见自学习了解资格、隐私、成本、仅提案权限以及故障排除。

"pending" | "auto"

default:"\"auto\""

auto 允许代理发起应用、拒绝或隔离操作，无需额外的审批提示。pending 需要操作员批准。

boolean

default:"false"

允许技能工作坊应用通过工作区技能符号链接写入，其真实目标已被 skills.load.allowSymlinkTargets 视为受信任。除非生成的提案应用应该修改该共享技能根目录，否则请保持禁用。

number

default:"50"

每个工作区保留的待处理和已隔离提案的最大数量（允许范围：1-200）。

number

default:"40000"

提案正文的最大字节数（允许范围：1024-200000）。提案描述单独硬性限制为 160 字节，因为它们会出现在发现和列表输出中。

有关该配置控制的提案生命周期、CLI 命令、代理工具参数以及网关方法，请参见技能工作坊。

符号链接的技能根目录

默认情况下，workspace、project-agent、extra-dir 和 bundled 的技能根目录都属于内容边界。位于 <workspace>/skills 下、但解析后指向根目录之外的符号链接技能文件夹，会被跳过并记录日志。若要允许有意使用符号链接布局，请声明受信任目标：

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

使用此配置后，<workspace>/skills/manager -> ~/Projects/manager/skills 在 realpath 解析后会被接受。extraDirs 会直接扫描兄弟仓库； allowSymlinkTargets 会为现有布局保留符号链接路径。默认情况下，Skill Workshop apply 不会通过这些符号链接写入。若要让 Workshop apply 修改已受信任的符号链接目标下的技能，请单独启用：

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

受管理的 ~/.openclaw/skills 和个人 ~/.agents/skills 目录已经无条件接受技能目录符号链接（但每个技能的 SKILL.md 内容边界仍然适用）—— allowSymlinkTargets 仅在 workspace、extra-dir 和 project-agent (<workspace>/.agents/skills) 根目录中需要。

沙箱化技能与环境变量

skills.entries.<skill>.env 和 apiKey 仅适用于 宿主机 运行。在沙箱中，它们不起作用——依赖 GEMINI_API_KEY 的技能会失败，并提示 apiKey not configured，除非为沙箱单独提供该变量。

将密钥传入 Docker 沙箱：

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

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

加载顺序提醒

workspace/skills      (最高)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
bundled skills
skills.load.extraDirs (最低)

对技能和配置的更改会在下一个新会话中生效（当 watcher 启用时），或者在 watcher 检测到更改后的下一个 agent 回合中生效。

技能参考

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

创建技能

编写自定义工作区技能。

技能工作坊

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

自学习

来自已完成工作的保守、可选择加入的提案。

斜杠命令

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

概览

插件

插件指南

构建插件

技能

自动化

工具

智能体协作

加载（`skills.load`）

安装（`skills.install`）

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

捆绑技能白名单

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

代理允许列表（`agents`）

工作坊 (`skills.workshop`)

符号链接的技能根目录

沙箱化技能与环境变量

加载顺序提醒

相关内容

技能参考

创建技能

技能工作坊

自学习

斜杠命令

​加载（skills.load）

​安装（skills.install）

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

​捆绑技能白名单

​按技能的条目（skills.entries）

​代理允许列表（agents）

​工作坊 (skills.workshop)

​符号链接的技能根目录

​沙箱化技能与环境变量

​加载顺序提醒

​相关内容

技能参考

创建技能

技能工作坊

自学习

斜杠命令

加载（`skills.load`）

安装（`skills.install`）

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

捆绑技能白名单

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

代理允许列表（`agents`）

工作坊 (`skills.workshop`)

符号链接的技能根目录

沙箱化技能与环境变量

加载顺序提醒

相关内容