Skills 上手：安装、使用与配置
一句话目标：把第一个 OpenClaw Skills（技能）装进你的 Gateway，确认它被正确加载，并完成门控与 allowlist 的基础配置。
准备
- 已读完前置页《进阶手册：Skills 与安全加固》，Gateway 正常运行（OpenClaw 2.0 即 v2026.8.1 及以上；Node 需 24.16.0+ 或 26.1.0+）。
- 知道自己的 workspace 目录和 state 目录在哪里。
- 至少一个聊天渠道（Discord、Telegram 等）已连上 Claw，方便对话验证。
- 先建立概念：Skill 不是代码插件，而是 markdown 指令文件，教 agent 如何、何时使用工具。每个技能是一个目录，内含
SKILL.md（YAML frontmatter + markdown 正文）。OpenClaw 会加载内置技能和本地覆盖，并在加载时按环境、配置、二进制是否存在过滤。
跟我做
第 1 步：安装一个 Skill
从 ClawHub 浏览并挑选一个社区技能，用 CLI 安装，也可以走本地方式放入技能目录。
openclaw skills install @owner/<slug>默认装进当前 workspace 的 skills/；加 --global 则装进共享的 <state-dir>/skills/。
本地方式：把整个技能目录（必须含 SKILL.md）复制到加载目录，例如 workspace 级的 <workspace>/skills/，或受管理的 <state-dir>/skills/。
预期结果：技能目录出现在目标位置，重载 Gateway 后被扫描加载。
第 2 步：确认加载与优先级
用 CLI 查看已加载的技能列表，确认新技能在列；同名冲突时按优先级表从高到低排查。
openclaw skills list同名技能出现在多个位置时，高优先级来源胜出：
| 优先级 | 来源 | 路径 |
|---|---|---|
| 1（最高） | Workspace 技能 | <workspace>/skills |
| 2 | 项目 agent 技能 | <workspace>/.agents/skills |
| 3 | 个人 agent 技能 | ~/.agents/skills（仅默认 state） |
| 4 | 受管/本地技能 | <state-dir>/skills |
| 5 | Workshop 技能 | <state-dir>/agents/<agentId>/agent/workshop-skills |
| 6 | 内置 / Custodian 技能 | 随安装包分发；Custodian 技能仅在 agents.defaults.systemAgent.agentId 指定的系统代理下可见 |
| 7（最低） | 额外目录 | 由 skills.* 配置指定 |
预期结果：列表里能看到新技能；同名冲突时高优先级来源胜出。
第 3 步：配置门控与 allowlist
在配置文件（默认 ~/.openclaw/openclaw.json）里，技能门控与环境注入配在 skills.* 节，agent allowlist（限定哪些 agent 能用哪些技能）配在 agents.* 节。改完保存，运行 openclaw gateway restart 重载 Gateway。
skills.* 常用键：skills.entries.<技能名>.enabled（门控单个技能的开关）、skills.entries.<技能名>.env 与 apiKey（环境注入）、skills.load.extraDirs（附加加载目录）、skills.install.*（安装行为）、skills.allowBundled（内置技能白名单）。allowlist 规则：省略 agents.defaults.skills 表示不限制；agents.entries.<agentId>.skills 是该 agent 的最终技能集合（整体替换而非合并），[] 表示无技能。
预期结果：被门控的技能不再对所有 agent 生效；allowlist 内的 agent 使用正常。
验证
在聊天渠道对 Claw 说一句能触发该技能的话，看它是否按 SKILL.md 的说明调用工具、执行流程。再把技能目录临时改名并重载，确认技能从列表消失——证明加载确实来自你放置的目录，而不是内置同名技能。
常见坑
- 同名技能被静默覆盖：高优先级来源直接胜出，不报错。排查时按上面优先级表逐层找。
- 技能死活不加载：OpenClaw 在加载时按环境、配置、二进制存在与否过滤。技能依赖的命令行工具没装，它可能被直接过滤掉。用
openclaw skills check区分 inventory/readiness/visibility 三类问题。 - 目录放错层：
~/.agents/skills只在默认 state 下作为个人 agent 技能来源；共享 Gateway 上的个人库技能按身份与修订选择，不靠扫描每个用户的文件。 - 把 Skill 当程序写：它只是 markdown 指令，教 agent 用工具。想让 Claw 自己长技能，去看 Skill Workshop——2.0 起它收集 proposals/checks/decisions，v2026.10.5 起支持版本历史与撤销。
下一课
技能跑通后，进入《写自己的 Skill：SKILL.md 与 ClawHub 发布》，从零写一个 SKILL.md 并发布到 ClawHub。延伸阅读：《Skill Workshop：让 Claw 自己学技能》《MCP 接入：给 Claw 外挂工具箱》。