一、先说个场景
你写了三四个 Skill，装了七八个 ClawHub 技能，日子久了发现：有的 skill 不想让它加载，有的只想给某个 agent 用，有的需要配 API Key，还有的想从公司公共仓库额外加载。这些事情不能都靠目录结构解决，必须懂 openclaw.json 里的 skills 配置块。
这篇文章把 skills 配置逐项拆开，给出可直接复制的 json5 片段。读完你会有自己的”技能开关面板”。
目录结构管的是”技能放在哪、被哪个来源发现”，但它回答不了更细的问题：同一个来源里的技能，我想关掉哪几个？不同 agent 该看到不同的技能集吗？密钥统一在哪绑？这些”策略层”的需求，只能由 openclaw.json 的 skills 块来承接。换句话说，目录决定”有没有”，配置决定”怎么用”。技能一多，二者必须配合，单靠搬文件很快就会乱成一锅粥。所以越早建立”用配置集中管理”的习惯，后面维护成本越低。
二、为什么是这样
OpenClaw 的大部分全局配置放在 ~/.openclaw/openclaw.json 里。技能相关的配置集中在 skills 块，再细分为：
allowBundled：内置技能白名单；load：加载行为，如额外目录、watch、符号链接目标；install：安装行为，如 Homebrew 优先、Node 包管理器、是否允许上传归档；workshop：Skill Workshop 提案队列的行为；entries：按技能名的细粒度开关和密钥绑定。
此外，还有 agents.defaults.skills 和 agents.entries.*.skills 给不同 agent 授权可见技能集。
理解了这些键，你就能精确控制每个技能是否加载、怎么加载、谁能看见。
三、跟着做：分步操作
1. 完整配置骨架
{
skills: {
allowBundled: ["gemini", "peekaboo"],
load: {
extraDirs: ["~/company-skills"],
allowSymlinkTargets: ["~/my-skills"],
watch: true,
},
install: {
preferBrew: true,
nodeManager: "npm",
allowUploadedArchives: false,
},
workshop: {
autonomous: { mode: "auto" },
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 },
},
},
}这个骨架把五个抽屉都亮了出来，你可以把它当成”填空模板”：暂时用不上的子项先留着也无害，等需要时再填值。注意 entries 里 sag 被显式 enabled: false，这就是”不想让它加载”的最直接写法，比删文件更可逆、也更透明。
2. 逐项解释
skills.allowBundled
只对bundled 技能生效的可选白名单。设置了以后，只有列表里的 bundled 技能才会加载；managed、agent 级、workspace 技能不受影响。
skills.load.extraDirs
额外扫描目录，~ 会展开。优先级最低，在 bundled 和 plugin 之后。适合公司公共技能库或个人技能仓库。
skills.load.allowSymlinkTargets
显式信任的符号链接目标目录。workspace / project-agent / extra-dir 默认只接受真实路径仍在配置根内的技能。如果你故意用符号链接指向根外，必须在这里声明目标目录。注意要收窄，不要写 ~ 或整个项目目录。
skills.load.watch
默认 true。监听 SKILL.md 变化并刷新技能快照，覆盖分组根下的嵌套文件。如果关闭，改完 skill 需要手动 /new 或 openclaw gateway restart。
skills.install.preferBrew
默认 true。有 Homebrew 时优先用 Homebrew 安装器。
skills.install.nodeManager
默认 "npm"。可选 npm / pnpm / yarn / bun。openclaw setup --node-manager 和 openclaw onboard --node-manager 只接受 npm/pnpm/bun，想用 yarn 要直接写进配置。
nodeManager 这个细节很能体现”配置要落地到具体值”：命令行初始化时并不接受 yarn，但配置字段本身允许。也就是说，如果你团队偏偏用 yarn，别在 setup 阶段纠结，直接把 nodeManager: "yarn" 写进 openclaw.json 即可。这种”命令受限、配置放行”的情况，遇到时别慌，直接改配置往往是最短路径。
skills.install.allowUploadedArchives
默认 false。允许通过 skills.upload.begin / chunk / commit 上传私有 zip 归档再安装。普通 ClawHub 安装不需要这个。
skills.entries.<key>
默认 key 是 skill name；如果 skill 声明了 metadata.openclaw.skillKey，用那个 key。连字符名字要加引号。
enabled: false：禁用。apiKey：绑定密钥，支持明文或 SecretRef。env：注入环境变量，仅当进程里没有同名变量时才生效。config：放自定义非敏感配置。
entries 是整个 skills 块里你打交道最多的地方，因为它是”按名字逐个点名”的唯一入口。无论是关掉某个技能、绑定密钥、注入默认配置，还是给不同技能不同 config，最终都落在这里。把 key 的取法（name 优先，缺省回退到 skillKey）记牢，能避免”我明明配了怎么不生效”——多半是 key 写错或没加引号。
3. 按 agent 授权
{
agents: {
defaults: { skills: ["github", "weather"] },
entries: {
writer: { default: true },
docs: { skills: ["docs-search"] },
"locked-down": { skills: [] },
},
},
}agents.defaults.skills 是基线，agents.entries.*.skills 是替换而不是合并。docs agent 只看 docs-search，不会继承 github 和 weather。
注意 locked-down 这个例子：给它一个空数组 skills: []，意味着它几乎看不到任何技能，是一个”最小权限”的 agent 模板。如果你在做安全敏感的场景，这种”默认什么都没有、按需逐个放开”的思路，比”默认全给、再慢慢关”安全得多。记住替换语义，才能玩转这种精细化授权。
四、可以复制的指令
// 禁用某个 skill
{
skills: {
entries: {
"some-skill": { enabled: false },
},
},
}// 从公司公共库加载技能
{
skills: {
load: {
extraDirs: ["~/company-skills"],
},
},
}// 给不同 agent 不同技能集
{
agents: {
defaults: { skills: ["github", "weather"] },
entries: {
writer: { default: true },
docs: { skills: ["docs-search"] },
},
},
}这三段覆盖了最高频的三类操作：关技能、扩来源、分 agent。建议把它们存成你的”速查三连”，遇到对应需求直接复制改名字。要说明的是，禁用用 enabled: false 比删除文件更安全——哪天想恢复，改回 true 即可，不用翻备份。而 extraDirs 和 agent 授权往往要配合使用：前者解决”去哪扫”，后者解决”谁看得见”。
五、实战案例
你管理一台团队共享服务器，上面跑三个 agent：
dev：需要 GitHub、Web Search、Browser、Coding agent。writer：需要 Web Search、newsletter-digest、PDF Parser。ops：需要 DevOps、Cloud、GitHub、Weather。
配置：
{
skills: {
load: {
extraDirs: ["/opt/company-skills"],
},
entries: {
"coding-agent": { enabled: true },
},
},
agents: {
entries: {
dev: { skills: ["github", "web-search", "browser", "coding-agent"] },
writer: { skills: ["web-search", "newsletter-digest", "pdf-parser"] },
ops: { skills: ["github", "weather", "devops", "cloud"] },
},
},
}这样每个 agent 只加载自己需要的技能，避免模型被无关能力干扰。
六、常见误区
- 误区 1：
allowBundled会影响所有技能。不会，它只限制 bundled 技能。workspace 和 global 技能不受影响。 - **误区 2：
agents.entries.*.skills会合并默认值。不会，它是替换**。要继承基线就显式写default: true。 - 误区 3：连字符 skill key 不需要引号。在 JSON5 里，
"my-skill"必须加引号。 - 误区 4：
skills.entries.<key>.env会覆盖系统变量。不会，只有当进程里没有同名变量时才注入。 - 误区 5：内置图像生成走
skills.entries。官方明确说：内置图像生成用agents.defaults.mediaModels.image+ 核心image_generate工具，不走skills.entries。
补一句误区 2 的实战影响：很多人给 docs agent 配了专属技能，却发现它还能用默认技能，于是以为是 bug。其实是他忘了”替换”语义——只要写了 agents.entries.*.skills，默认集就被整体替换，能看到的只有列表里的。如果你想要”默认集 + 额外几项”，正确做法是把默认集也写进列表，或用 default: true 继承后再叠加（具体看框架是否支持叠加写法）。总之，先想清”替换还是叠加”，再动手。
七、进阶玩法
给 coding-agent 开启并确保 CLI 已装：
{
skills: {
entries: {
"coding-agent": { enabled: true },
},
},
}注意 coding-agent 是 opt-in，启用后还要确保 claude / codex / opencode 等支持的 CLI 已安装并登录。
coding-agent 这类技能是”开关易开、前提难备”的典型：你在 entries 里把它 enabled: true 只是放行，真正的可用还依赖底层 CLI 装好并登录。所以启用后要回头核对依赖，必要时配合前面 gating 文章里的 requires.bins 做加载期检查，避免”放开了却跑不起来”。
用 config 让同一 skill 在不同项目行为不同：
{
skills: {
entries: {
"my-deploy": {
config: { env: "staging", region: "us-east-1" },
},
},
},
}脚本里读取这个 config，实现一套代码多环境复用。
config 在这里扮演”按环境调参”的角色：同一份部署技能，在 staging 和 production 下只是 env、region 不同，逻辑完全共用。你不必为不同环境复制多份技能，只要改 config 即可。把可变参数外置到 config，是让技能从”写死一个场景”升级为”适配多个场景”的关键手法，和前面 scripts/ 文章里”行为由配置驱动”的思路一脉相承。
八、小结
openclaw.json 的 skills 块是你管理技能的总开关。allowBundled 管内置，load 管扫描，install 管安装器，entries 管单个技能，按 agent 授权则控制谁能看到什么。掌握这些键，你就能把技能库整理得井井有条，而不是任其野蛮生长。