OpenClaw 技能配置文件位于 ~/.openclaw/openclaw.json 的 skills 下。本页覆盖所有配置字段（allowBundled、load.extraDirs、install.nodeManager、entries 等）、Agent 技能白名单、symlink 跨目录允许规则，以及沙箱环境变量注入方式。注意：沙箱内不继承宿主环境变量，需通过 agents.defaults.sandbox.docker.env 或自定义镜像注入；symlink 默认被跳过，需配置 allowSymlinkTargets 和 extraDirs 才能生效。

OpenClaw Skills 技能配置参数与常见问题排查

全局技能配置

所有技能加载/安装配置都放在 ~/.openclaw/openclaw.json 的 skills 下。Agent 级别的技能可见性则在 agents.defaults.skills 和 agents.list[].skills 中配置。

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true,
      watchDebounceMs: 250,
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway 运行时仍需 Node；不推荐 bun)
      allowUploadedArchives: false,
    },
    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.imageGenerationModel 加核心 image_generate 工具。skills.entries.* 仅用于自定义或第三方技能工作流。

如果你选择了特定的图像 Provider/模型，还需要配置该 Provider 的认证/API Key。典型示例：google/* 用 GEMINI_API_KEY 或 GOOGLE_API_KEY，openai/* 用 OPENAI_API_KEY，fal/* 用 FAL_KEY。

示例：

• 原生 Nano Banana Pro 风格设置：agents.defaults.imageGenerationModel.primary: "google/gemini-3-pro-image-preview"
• 原生 fal 设置：agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"

Agent 技能白名单

当同机、同工作区的技能根目录共享，但需要不同 Agent 拥有不同可见技能集时，使用 Agent 配置。

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // 继承 defaults -> github, weather
      { id: "docs", skills: ["docs-search"] }, // 替换 defaults
      { id: "locked-down", skills: [] }, // 无技能
    ],
  },
}

规则：

• agents.defaults.skills：Agent 默认技能白名单，当 agents.list[].skills 未定义时继承。
• 省略 agents.defaults.skills 则默认不限制技能。
• agents.list[].skills：显式指定该 Agent 的最终技能集，不会与 defaults 合并。
• agents.list[].skills: []：该 Agent 不暴露任何技能。

字段说明

• 内置技能根目录始终包括 ~/.openclaw/skills、~/.agents/skills、<workspace>/.agents/skills 和 <workspace>/skills。
• allowBundled：可选，仅对内置技能进行白名单。设置后只有列表中的内置技能符合条件（managed、Agent 和工作区技能不受影响）。
• load.extraDirs：额外技能目录，优先级最低。
• load.allowSymlinkTargets：可信的符号链接实际目标目录。当工作区、项目 Agent 或 extraDirs 下的技能文件夹是 symlink 时，如果目标在此允许列表内，则允许解析。用于有意设计的同级仓库布局，例如 <workspace>/skills/manager -> ~/Projects/manager/skills。注意：managed ~/.openclaw/skills 和 personal ~/.agents/skills 根目录默认允许技能目录 symlink（因为它们是用户本地技能管理器的入口），但每个 SKILL.md 仍必须在其自身技能目录内解析。保持目标条目范围狭窄，不要指向 ~ 或 ~/Projects 等宽泛根目录，除非其下所有技能树都是可信的。
• load.watch：监视技能文件夹并刷新技能快照（默认：true）。
• load.watchDebounceMs：技能监视器事件的防抖时间，单位毫秒（默认：250）。
• install.preferBrew：有 brew 时优先使用 brew 安装器（默认：true）。
• install.nodeManager：Node 安装器偏好（npm | pnpm | yarn | bun，默认：npm）。这只影响技能安装；Gateway 运行时仍需 Node（WhatsApp/Telegram 不推荐 bun）。另外，openclaw setup --node-manager 目前只接受 npm、pnpm 或 bun，如需 Yarn 需在配置中手动设置 skills.install.nodeManager: "yarn"。
• install.allowUploadedArchives：允许受信任的 operator.admin Gateway 客户端安装通过 skills.upload.* 暂存的私有 zip 归档（默认：false）。仅启用上传归档路径；正常 ClawHub 安装不需要此设置。
• entries.<skillKey>：单技能覆盖。

单技能字段：

• enabled：设为 false 可禁用该技能，即使已内置/安装。
• env：Agent 运行时注入的环境变量（仅在变量尚未设置时注入）。
• apiKey：为声明了主要环境变量的技能提供的便捷配置，支持纯文本字符串或 SecretRef 对象（{ source, provider, id }）。

Symlink 同级仓库

默认情况下，工作区、项目 Agent、extraDirs 和内置技能根目录都是容器边界。如果 <workspace>/skills 下的技能文件夹是 symlink 且解析到 <workspace>/skills 之外，OpenClaw 会跳过并记录 Skipping escaped skill path outside its configured root。

如果需要允许 symlink 跨目录，需同时配置 extraDirs 和 allowSymlinkTargets：

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

这样，symlink 如 <workspace>/skills/manager -> ~/Projects/manager/skills 在 realpath 解析后会被接受。extraDirs 也会直接扫描同级仓库，而 allowSymlinkTargets 保留了现有工作区技能布局的 symlink 路径。managed ~/.openclaw/skills 和 ~/.agents/skills 目录默认接受技能目录 symlink，但每个 SKILL.md 的容器限制仍然适用。始终将 target 条目保持为窄范围，不要指向宽泛根目录如 ~ 或 ~/Projects，除非其下所有技能树都是可信的。

注意事项

• entries 下的 key 默认与技能名称匹配。如果技能定义了 metadata.openclaw.skillKey，则使用该 key。
• 加载优先级：<workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 内置技能 → skills.load.extraDirs。
• 启用监视器时，技能变更在下一次 Agent 轮次时生效。

沙箱技能与环境变量

当会话处于沙箱模式时，技能进程运行在沙箱后端内（例如 Docker）。沙箱不继承宿主 process.env。

WARNING

全局 env 和 skills.entries.<skill>.env/apiKey 仅适用于宿主运行。在沙箱内无效，因此依赖 GEMINI_API_KEY 的技能会失败并提示 apiKey not configured，除非单独向沙箱提供该变量。

使用以下方式之一：

• agents.defaults.sandbox.docker.env（Docker 后端适用；或单 Agent 的 agents.list[].sandbox.docker.env）
• 将环境变量烘焙到自定义沙箱镜像或远程沙箱环境中。

对于 Docker 沙箱，配置的 sandbox.docker.env 值会成为明确的容器环境变量。如果 Docker 守护进程可访问，用户可以通过 Docker 元数据查看它们，因此当不可接受暴露时，应使用挂载的密钥文件、自定义镜像或其他传递路径。

常见问题

技能无法加载，日志显示 “Skipping escaped skill path” 怎么解决？

这通常是因为工作区下的技能文件夹是 symlink，但目标未在 skills.load.allowSymlinkTargets 中允许。需要同时配置 allowSymlinkTargets 指定目标目录，并将该目标目录也加入 load.extraDirs。详细配置见上文 “Symlink 同级仓库” 部分。

沙箱中技能报错 “apiKey not configured” 怎么办？

沙箱不继承宿主环境变量。需在 agents.defaults.sandbox.docker.env 中设置所需环境变量，例如 "GEMINI_API_KEY": "your_key"。或将该变量烘焙到自定义沙箱镜像中。注意全局 skills.entries.*.env 在沙箱内无效。

安装了 yarn 但技能安装仍用 npm，怎么切换？

skills.install.nodeManager 默认是 npm。手动设置 "nodeManager": "yarn" 即可。注意 openclaw setup --node-manager 命令只支持 npm、pnpm、bun，yarn 需要通过配置文件手动设置。