docs/tools/skills-config.md
Most skills configuration lives under skills in
~/.openclaw/openclaw.json. Agent-specific visibility lives under
agents.defaults.skills and agents.list[].skills.
{
skills: {
allowBundled: ["gemini", "peekaboo"],
load: {
extraDirs: ["~/Projects/agent-scripts/skills"],
allowSymlinkTargets: ["~/Projects/manager/skills"],
watch: true,
watchDebounceMs: 250,
},
install: {
preferBrew: true,
nodeManager: "npm",
allowUploadedArchives: false,
},
workshop: {
autonomous: { enabled: false },
approvalPolicy: "pending",
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.install)security.installPolicy)Use security.installPolicy when operators need a trusted local command to
approve or block skill and plugin installs with host-specific policy. The policy
runs after OpenClaw has staged source material and before the install or update
continues. It applies to ClawHub skills, uploaded skills, Git/local skills,
skill dependency installers, and plugin install/update sources.
{
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"],
},
},
},
}
The policy receives one JSON object on stdin with protocolVersion: 1,
openclawVersion, targetType, targetName, sourcePath, sourcePathKind,
optional structured source, structured origin, and request. It must write
one JSON object on stdout: { "protocolVersion": 1, "decision": "allow" } or
{ "protocolVersion": 1, "decision": "block", "reason": "..." }. Non-zero
exit, timeout, malformed JSON, missing fields, or unsupported protocol versions
fail closed.
OpenClaw does not execute install policy during normal Gateway startup. Installs
and updates fail closed when policy is enabled but unavailable. openclaw doctor
performs static validation, and openclaw doctor --deep executes a synthetic
install probe against the configured command.
Bulk updates apply policy per target: a blocked skill or plugin update fails that target without disabling the policy or skipping later targets in the batch.
Example 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:[email protected]"
},
"skill": {
"installId": "clawhub"
}
}
Minimal policy command:
#!/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.entries)Keys under entries match the skill name by default. If a skill defines
metadata.openclaw.skillKey, use that key instead. Quote hyphenated names
(JSON5 allows quoted keys).
agents)Use agent config when you want the same machine/workspace skill roots but a different visible skill set per agent.
{
agents: {
defaults: {
skills: ["github", "weather"], // shared baseline
},
list: [
{ id: "writer" }, // inherits github, weather
{ id: "docs", skills: ["docs-search"] }, // replaces defaults entirely
{ id: "locked-down", skills: [] }, // no skills
],
},
}
skills.workshop)By default, workspace, project-agent, extra-dir, and bundled skill roots are
containment boundaries. A symlinked skill folder under <workspace>/skills
that resolves outside the root is skipped with a log message.
To allow an intentional symlink layout, declare the trusted target:
{
skills: {
load: {
extraDirs: ["~/Projects/manager/skills"],
allowSymlinkTargets: ["~/Projects/manager/skills"],
},
},
}
With this config, <workspace>/skills/manager -> ~/Projects/manager/skills is
accepted after realpath resolution. extraDirs scans the sibling repo directly;
allowSymlinkTargets preserves the symlinked path for existing layouts.
Managed ~/.openclaw/skills and personal ~/.agents/skills directories
already accept skill-directory symlinks (per-skill SKILL.md containment still
applies).
Pass secrets into a Docker sandbox with:
{
agents: {
defaults: {
sandbox: {
docker: {
env: { GEMINI_API_KEY: "your-key-here" },
},
},
},
},
}
workspace/skills (highest)
workspace/.agents/skills
~/.agents/skills
~/.openclaw/skills
bundled skills
skills.load.extraDirs (lowest)
Changes to skills and config take effect on the next new session when the watcher is enabled, or on the next agent turn when the watcher detects a change.