技能配置
大多数技能配置位于 ~/.openclaw/openclaw.json 的 skills 下。代理特定的可见性配置位于
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" },
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。技能条目
仅用于自定义或第三方技能工作流。
加载(skills.load)¶
skills.load.extraDirsstring[] (path)- 额外的技能目录,按最低优先级扫描(位于内置技能和插件技能之下)。
路径支持
~展开。 skills.load.allowSymlinkTargetsstring[] (path)- 受信任的真实目标目录,符号链接技能文件夹可解析到这些目录,即使符号链接
位于已配置的根目录之外。适用于有意的同级仓库布局,例如
<workspace>/skills/manager -> ~/path/to/skills。请保持此列表精简—— 不要指向~或整个项目目录等宽泛根路径。 skills.load.watchboolean (path)- 监听技能文件夹,并在
SKILL.md文件发生变化时刷新技能快照。 涵盖分组技能根目录下的嵌套文件。
安装(skills.install)¶
skills.install.preferBrewboolean (path)- 当
brew可用时,优先使用 Homebrew 安装程序。 skills.install.nodeManager"npm" | "pnpm" | "yarn" | "bun" (path) default:"npm"- 技能安装的 Node 包管理器偏好。仅影响技能安装。Node 仍是 OpenClaw 首选且推荐的
主要运行时;具备 WAL 重置安全
node:sqlite的 Bun 1.4+ 可作为显式运行时选项使用。openclaw setup --node-manager和openclaw onboard --node-manager接受npm、pnpm或bun;如需基于 Yarn 的技能安装,请在配置中直接设置"yarn"。除非传入--node-manager,否则 Setup 会保留此偏好;全新配置默认为npm。 skills.install.allowUploadedArchivesboolean (path) default:false- 允许受信任的
operator.adminGateway 客户端安装通过skills.upload.*暂存的私有 zip 压缩包。常规 ClawHub 安装不需要此设置。
操作员安装策略(security.installPolicy)¶
当操作员需要受信任的本地命令来根据主机特定策略批准或阻止技能与插件安装时,
请使用 security.installPolicy。该策略在 OpenClaw 暂存源材料之后、安装或更新
继续之前运行。它适用于 ClawHub 技能、上传的技能、Git/本地技能、技能依赖安装器
以及插件安装/更新源。
{
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.enabledboolean (path) default:false- 启用操作员自有的安装策略。在未提供有效
exec命令的情况下启用时, 安装将失败关闭(fail closed,默认拒绝)。 security.installPolicy.targets("skill" | "plugin")[] (path)- 可选的目标过滤器。省略时,策略适用于所有受支持的目标,以便新安装 不会意外地失败开放(fail open,默认放行)。
security.installPolicy.exec.commandstring (path)- 受信任策略可执行文件的绝对路径。OpenClaw 不使用 shell 运行它, 并在使用前验证该路径。
security.installPolicy.exec.argsstring[] (path)- 在
command之后传入的静态参数。 security.installPolicy.exec.timeoutMsnumber (path) default:10000- 单次策略决策的最大实际运行时长(wall-clock)。
security.installPolicy.exec.noOutputTimeoutMsnumber (path) default:timeoutMs- 在没有 stdout 或 stderr 输出的情况下,策略进程的最大运行时间; 超过后策略将失败关闭。
security.installPolicy.exec.maxOutputBytesnumber (path) default:1048576- 从策略进程接受的 stdout 和 stderr 合并输出的最大字节数。
<ParamField path="security.installPolicy.exec.env" type="Record
security.installPolicy.exec.passEnvstring[] (path)- 从 OpenClaw 进程复制到策略进程的环境变量名称。仅传递指定的变量。
security.installPolicy.exec.trustedDirsstring[] (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
用于显示。只有包含超过 100 条有效 findings 的 warn 响应才会失败关闭且无法被确认;
allow 和 block 保留前 100 条。警告会在提交前停止安装。warn 评审如果其完整渲染
的通知(包括标题、目标、净化后的 reason 和 findings 以及恢复指南)超过 4,000 个
字符的总体显示限制,则会失败关闭,且不会呈现部分评审。超出预算的 block 仍以
有界的拒绝告终;而 allow 上超出预算的 findings 则会在有界的诊断输出中汇总。
交互式 CLI 插件和技能命令会要求操作员输入目标名称,使用与可疑 ClawHub 发布相同的
install anyway 或 update anyway 文案,然后在继续之前重新运行策略。直接 CLI 上
被拒绝的命令和非交互式命令,可以在审查后使用 --acknowledge-install-policy-warning
作为该命令调用中每个警告的显式批准;每个已批准的警告在继续之前都会重新评估。
Control UI 可以审查并批准其插件安装请求中的警告;该批准涵盖该调用中的每个警告,
且每个警告仍会被重新评估。其他基于 Gateway 的安装和自动安装在缺少操作员确认流程时
仍会保持阻止状态。当存在等效的直接插件或技能命令时,请使用它来审查并批准该警告。
否则,请修改 security.installPolicy,让已审查的请求返回 allow,然后重试托管流程。
--force 不会批准策略警告。block、非零退出码、超时、无效 JSON、非对象响应、
缺失或无效的协议版本或决策,以及缺失或为空的 warn/block reason,都会一律
失败关闭。
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: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.allowBundledstring[](路径)- 仅针对捆绑技能的可选允许列表。设置后,仅列表中的捆绑 技能符合条件。托管、代理级别和工作区技能不受影响。
每个技能条目(skills.entries)¶
entries 下的键默认匹配技能的 name。如果技能定义了
metadata.openclaw.skillKey,则改用该键。带连字符的名称需要加引号
(JSON5 允许带引号的键)。
<ParamField path="skills.entries.false 会禁用该技能,即使它是捆绑技能或已安装。
coding-agent 捆绑技能为可选启用——将其设置为 true,并确保已安装并
认证了 claude、codex、opencode 或其他受支持的 CLI 之一。
<ParamField path="skills.entries.metadata.openclaw.primaryEnv 的技能提供的便捷字段。
支持明文字符串或 SecretRef:{ source: "env", provider: "default", id: "VAR_NAME" }。
<ParamField path="skills.entries.
<ParamField path="skills.entries.
代理允许列表(agents)¶
当你希望使用相同的机器/工作区技能根目录,但为每个代理配置不同的可见技能集时,请使用代理配置。
{
agents: {
ownership: "explicit",
defaults: {
skills: ["github", "weather"], // shared baseline
heartbeat: { agentId: "writer" },
systemAgent: { agentId: "writer" },
authInheritance: { agentId: "writer" },
},
entries: {
writer: { workspace: "~/.openclaw/workspace" }, // inherits github, weather
docs: { skills: ["docs-search"] }, // replaces defaults entirely
"locked-down": { skills: [] }, // no skills
},
},
talk: { agentId: "writer" },
}
agents.defaults.skillsstring[](路径)- 由省略
agents.entries.*.skills的代理继承的共享基线允许列表。 完全省略则默认不限制技能。 agents.entries.*.skillsstring[](路径)- 该代理的显式最终技能集。显式列表替换
继承的默认值——它们不会合并。设置为
[]可为该代理不暴露任何技能。
Warning
代理技能允许列表是 OpenClaw 技能发现、提示、斜杠命令发现、沙箱同步和技能
快照的可见性与加载过滤器。它们不是 shell 时授权边界。如果代理
可以运行主机 exec,该 shell 仍可能运行外部客户端或读取
执行用户可见的主机文件,包括 MCP 客户端
注册表,例如 ~/.openclaw/skills/config/mcporter.json。对于
按代理隔离 MCP,请将技能允许列表与沙箱/操作系统用户
隔离结合使用,拒绝或严格允许主机 exec,并优先在 MCP 服务器端使用按代理
凭据。
Workshop(skills.workshop)¶
skills.workshop.autonomous.mode"off" | "auto"(路径)默认值:"auto"auto允许代理保存和更新 Workshop 技能:在大量工作之后会运行 后台审查,30 天未使用的已学习技能会被归档。 审查变更会在对话中通知,并且每个变更都可以 撤销。off禁用后台审查和未使用技能清理。 用户提示的技能创建、/learn和手动学习会话在 两种模式下均可用。
查看 自我学习 了解资格、隐私、成本 和故障排除。
skills.workshop.maxSkillBytesnumber(路径)默认值:40000- Workshop 技能的
SKILL.md最大字节数(允许范围: 1024-200000)。技能描述单独限制为 1024 字节;请 将其保持在 160 字节左右,因为它们会出现在发现和列表输出中。
openclaw doctor --fix 会迁移来自已移除提案流程的配置:它
将 autonomous.mode: "propose" 更改为 "off",并删除
skills.workshop.approvalPolicy 和 skills.workshop.maxPending。运行
openclaw config set skills.workshop.autonomous.mode auto 可重新启用自动
学习。
参见 Skill Workshop 了解此配置所控制的技能生命周期、CLI 命令、代理工具参数和 Gateway 方法。
符号链接技能根目录¶
默认情况下,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 包含规则仍然适用)——allowSymlinkTargets 仅对 workspace、extra-dir 和 project-agent(<workspace>/.agents/skills)根目录是必需的。
沙箱技能与环境变量¶
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 技能。
代理学习的技能、变更历史和撤销。
从已完成工作中自动进行可撤销的技能学习。
原生斜杠命令目录和聊天指令。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw