技能
Skills 配置
大多数 Skills 配置位于
~/.openclaw/openclaw.json 中的 skills 下。Agent 专属的可见性配置位于
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: { 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 }, }, },}加载（skills.load）
skills.load.extraDirsstring[]要扫描的其他 Skill 目录，优先级最低（低于
内置和插件 Skills）。路径展开支持 ~。
skills.load.allowSymlinkTargetsstring[]受信任的真实目标目录；符号链接的 Skill 文件夹可以解析到这些目录，
即使符号链接位于配置的根目录之外。将其用于有意采用的相邻仓库布局，例如
<workspace>/skills/manager -> ~/Projects/manager/skills。此列表应保持
严格范围——不要指向 ~ 或 ~/Projects 等宽泛的根目录。
skills.load.watchbooleandefault: true监视 Skill 文件夹，并在 SKILL.md 文件
发生变化时刷新 Skills 快照。涵盖分组 Skill 根目录下的嵌套文件。
安装（skills.install）
skills.install.preferBrewbooleandefault: true当 brew 可用时，优先使用 Homebrew 安装程序。
skills.install.nodeManager"npm" | "pnpm" | "yarn" | "bun"default: "npm"安装 Skill 时首选的 Node 包管理器。此设置仅影响 Skill
安装——OpenClaw CLI 和 Gateway 网关运行时需要 Node，因为
规范状态存储使用 node:sqlite。openclaw setup --node-manager 和
openclaw onboard --node-manager 接受 npm、pnpm 或 bun；对于
由 Yarn 支持的 Skill 安装，请直接在配置中设置 "yarn"。
skills.install.allowUploadedArchivesbooleandefault: false允许受信任的 operator.admin Gateway 网关客户端安装通过
skills.upload.* 暂存的私有 zip 归档。常规 ClawHub 安装不需要
此设置。
操作员安装策略（security.installPolicy）
当操作员需要通过受信任的本地命令，依据主机特定策略批准或阻止 Skill 和插件安装时，
请使用 security.installPolicy。该策略在 OpenClaw 暂存源材料之后、
安装或更新继续之前运行。它适用于 ClawHub Skills、上传的 Skills、Git/本地
Skills、Skill 依赖项安装程序，以及插件安装/更新源。
{ 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"], }, }, },}security.installPolicy.enabledbooleandefault: false启用由操作员管理的安装策略。如果启用后没有有效的 exec
命令，安装将以关闭方式失败。
security.installPolicy.targets("skill" | "plugin")[]可选的目标筛选器。省略时，策略适用于所有支持的 目标，因此新的安装类型不会意外开放。
security.installPolicy.exec.commandstring受信任策略可执行文件的绝对路径。OpenClaw 不通过 shell 运行该文件，并会在使用前验证路径。
security.installPolicy.exec.argsstring[]在 command 之后传递的静态参数。
security.installPolicy.exec.timeoutMsnumberdefault: 10000单次策略决策允许的最大实际运行时间。
security.installPolicy.exec.noOutputTimeoutMsnumberdefault: timeoutMs在策略以关闭方式失败之前，stdout 或 stderr 无输出的最长 时间。
security.installPolicy.exec.maxOutputBytesnumberdefault: 1048576从策略进程接受的 stdout 和 stderr 合计最大字节数。
security.installPolicy.exec.env"Record<string,security.installPolicy.exec.passEnvstring[]从 OpenClaw 进程复制到 策略进程的环境变量名称。仅传递指定名称的变量。
security.installPolicy.exec.trustedDirsstring[]可以包含策略可执行文件的目录可选允许列表。
security.installPolicy.exec.allowInsecurePathbooleandefault: false绕过命令路径所有权和权限检查。仅当 该路径受其他机制保护时使用。
security.installPolicy.exec.allowSymlinkCommandbooleandefault: false允许配置的命令路径为符号链接。解析后的目标 仍必须满足其他路径检查。解释器脚本参数必须 是直接的常规文件，不能是符号链接。
该策略通过 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
针对配置的命令执行合成安装探测。
批量更新会对每个目标应用策略：被阻止的 Skill 或插件更新会导致 该目标失败，但不会禁用策略，也不会跳过批次中的后续目标。
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: "此主机不允许使用本地插件路径", }), ); return; } process.stdout.write(JSON.stringify({ protocolVersion: 1, decision: "allow" }));});内置 Skill 允许列表
skills.allowBundledstring[]仅适用于内置 Skills 的可选允许列表。设置后，只有列表中的内置 Skills 符合使用条件。托管级、Agent 级和工作区 Skills 不受影响。
按 Skill 配置的条目（skills.entries）
默认情况下，entries 下的键与 Skill 的 name 匹配。如果 Skill 定义了
metadata.openclaw.skillKey，则改用该键。包含连字符的名称需要加引号
（JSON5 允许带引号的键）。
OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk
.enabled" type="boolean">
false 会禁用该 Skill，即使它是内置或已安装的。内置
Skill coding-agent 需要主动启用——将其设置为 true，并确保
claude、codex、opencode 或其他受支持的 CLI 之一已安装且
已完成身份验证。
OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InNraWxscy5lbnRyaWVzLjxrZXk
.apiKey" type='string | { source, provider, id }'>
为声明 metadata.openclaw.primaryEnv 的 Skills 提供的便捷字段。
支持纯文本字符串或 SecretRef：{ source: "env", provider: "default", id: "VAR_NAME" }。
"skills.entries.<key �����r�"skills.entries.<key �w₫��ܩAgent 允许列表（agents）
如果希望使用同一台机器/工作区的 Skill 根目录，但为每个 Agent 设置不同的可见 Skill 集，请使用 Agent 配置。
{ agents: { defaults: { skills: ["github", "weather"], // 共享基线 }, list: [ { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 完全替换默认值 { id: "locked-down", skills: [] }, // 无 Skills ], },}agents.defaults.skillsstring[]由省略 agents.entries.*.skills 的 Agents 继承的
共享基线允许列表。完全省略可使 Skills 默认不受
限制。
agents.entries.*.skillsstring[]该 Agent 的明确最终 Skill 集。明确指定的列表会替换
继承的默认值，而不会合并。设置为 [] 可不向
该 Agent 公开任何 Skills。
Workshop（skills.workshop）
skills.workshop.autonomous.enabledbooleandefault: false当 true 时，OpenClaw 可以根据持久化更正创建待处理提案，
并可在系统进入空闲状态后审查已成功完成且具有实质性的工作。
这可能会在符合条件的轮次后增加一次后台模型运行。当此设置为 false 时，
用户提示触发的技能创建和 /learn 仍可正常工作。
有关资格条件、隐私、成本、仅提案权限和故障排除，请参阅自我学习。
skills.workshop.approvalPolicy"pending" | "auto"default: "auto"auto 允许智能体主动应用、拒绝或隔离提案，无需额外的审批提示。
pending 则需要操作员审批。
skills.workshop.allowSymlinkTargetWritesbooleandefault: false允许 Skill Workshop 在工作区技能符号链接的真实目标已受
skills.load.allowSymlinkTargets 信任时，通过这些符号链接写入。除非应用生成的提案时
应修改该共享技能根目录，否则请保持禁用此选项。
skills.workshop.maxPendingnumberdefault: 50每个工作区保留的待处理和已隔离提案的最大数量（允许范围：1-200）。
skills.workshop.maxSkillBytesnumberdefault: 40000提案正文的最大字节数（允许范围：1024-200000）。提案描述另有 160 字节的硬性上限，因为它们会出现在发现和列表输出中。
有关此配置所控制的提案生命周期、CLI 命令、智能体工具参数和 Gateway 网关方法， 请参阅 Skill Workshop。
使用符号链接的技能根目录
默认情况下，工作区、项目智能体、额外目录和内置技能根目录均为
包含范围边界。位于 <workspace>/skills 下、解析结果超出根目录的
符号链接技能文件夹将被跳过，并记录一条日志消息。
若要允许有意设置的符号链接布局，请声明受信任的目标：
{ skills: { load: { extraDirs: ["~/Projects/manager/skills"], allowSymlinkTargets: ["~/Projects/manager/skills"], }, },}使用此配置后，<workspace>/skills/manager -> ~/Projects/manager/skills
将在 realpath 解析后被接受。extraDirs 会直接扫描同级仓库；
allowSymlinkTargets 则为现有布局保留符号链接路径。
默认情况下，Skill Workshop 在应用提案时不会通过这些符号链接写入。 若要允许 Workshop 在应用提案时修改已受信任的符号链接目标下的技能， 请单独选择启用：
{ skills: { load: { allowSymlinkTargets: ["~/Projects/manager/skills"], }, workshop: { allowSymlinkTargetWrites: true, }, },}托管的 ~/.openclaw/skills 和个人的 ~/.agents/skills 目录
已无条件接受技能目录符号链接（仍会对每个技能应用
SKILL.md 包含范围检查）——只有工作区、额外目录和项目智能体
（<workspace>/.agents/skills）根目录才需要 allowSymlinkTargets。
沙箱隔离的技能和环境变量
通过以下配置将密钥传入 Docker 沙箱：
{ agents: { defaults: { sandbox: { docker: { env: { GEMINI_API_KEY: "your-key-here" }, }, }, }, },}加载顺序提醒
workspace/skills （最高）workspace/.agents/skills~/.agents/skills~/.openclaw/skills内置技能skills.load.extraDirs （最低）启用监视器后，对技能和配置的更改将在下一个新会话中生效； 当监视器检测到更改时，也可在智能体的下一轮中生效。
