OpenClaw 工具、技能与插件：给它加能力的正确姿势

Posted on Sun 11 October 2026 in AI 编程 • Sucre Liu

一句话分清三者

工具（Tool）：agent 能调用的动作，比如 exec、browser、web_search、message。它们是作为结构化函数定义发给模型的。
技能（Skill）：教 agent 怎么做事的指令包，一个含 SKILL.md 的目录。
插件（Plugin）：给 OpenClaw 增加运行时能力——工具、provider、通道、hooks、语音、媒体等，并可打包技能。

选择逻辑很直白：

你的需求	用什么
让它能执行/读取/发送	内置工具（先别急着扩）
教它一套可复用流程	技能
接入一个新的系统/服务/通道	插件
稍后或在后台跑	自动化（下一篇）

工具：模型只看到"活下来"的那些

这是最该理解的一点：工具策略在模型调用之前生效。 如果一个工具被策略移除，模型这一轮根本拿不到它的 schema——不是"看到了但被禁止调用"。

一个工具能不能出现在模型面前，取决于一串过滤：生效的 profile、tools.allow / tools.deny、provider 特有约束、沙箱状态、通道权限、以及插件是否可用。内置工具大致分这些类别：

类别	什么时候用	代表工具
Runtime	跑命令、管进程、共享终端、provider 侧 Python	`exec`、`process`、`terminal`、`code_execution`
Files	读写工作区文件	`read`、`write`、`edit`、`apply_patch`
Human input	停下来要用户决策 / 拿凭据但不暴露	`ask_user`、`secrets`
Web	搜网页、搜 X、抓正文	`web_search`、`x_search`、`web_fetch`
Browser	操作浏览器会话	`browser`
Messaging	发回复或通道动作	`message`
Sessions/agents	查看会话、派子代理、编排	`sessions_`、`subagents`、`agents_`
Automation	排任务、响应后台事件	`cron`、`heartbeat_respond`
Media	看图、生图、生成/朗读音视频	`view_image`、`image_generate`、`tts`
大目录	不把每个 schema 都塞进提示就能组合调用	Code Mode / Tool Search

工具"不见了"时的排查顺序

别一上来改配置。按这个顺序查当前这一轮的生效策略：

生效 profile、tools.allow、tools.deny；
provider 特有约束，以及所选模型是否支持该工具形态；
通道权限、沙箱状态、elevated 访问；
所属插件是否已安装并启用；
委派运行（子代理）的 per-agent 限制；
大目录场景下，这一轮用的是直接暴露、Code Mode 还是 Tool Search。

一个常见的误判：配了 tools.exec / tools.fs 段落，并不等于授权了工具。 那些段落是参数，不是开关；授权由 allow/deny 与 profile 决定。

技能：指令包与加载顺序

技能是 SKILL.md —— YAML frontmatter + Markdown 正文。最低要求是 name 和 description：

---
name: git-release
description: 准备发布说明、版本号与 GitHub release
---

## Workflow

1. 读取 references/release-policy.md
2. 汇总上一个 tag 以来的合并变更
3. 先提出建议的版本号，再改文件

技能从多个来源加载，优先级从高到低：

优先级	来源	路径
1	工作区技能	`<workspace>/skills`
2	项目 agent 技能	`<workspace>/.agents/skills`
3	个人 agent 技能	`~/.agents/skills`
4	托管/本地	`<state-dir>/skills`
5	Workshop 技能	`<state-dir>/agents/<agentId>/agent/workshop-skills`
6	内置 / Custodian	随安装分发
7	额外目录	`skills.load.extraDirs` + 插件技能

同名时高优先级胜出。发现是分组友好的：只要某个根下任意深度（最多 6 层）出现 SKILL.md 就会被发现，但技能名来自 frontmatter 的 name（缺省才用目录名）。

可见性（哪些 agent 能用）和位置（优先级）是两回事。 用 allowlist 控制：

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    entries: {
      docs: { skills: ["docs-search"] },  // 完全替换默认，不合并
      "locked-down": { skills: [] },       // 不给任何技能
    },
  },
}

注意：非空的 per-agent 列表是最终集合，不会和默认合并。

技能可以在加载期做门控（缺依赖就不出现在模型面前）：

---
name: image-lab
description: 用 provider 做图像生成/编辑
metadata: { "openclaw": { "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"] }, "primaryEnv": "GEMINI_API_KEY" } }
---

requires.bins / anyBins / env / config、os 过滤，加上配置里的 skills.entries.<name>.enabled，共同决定它是否生效。

一个必须记住的坑

skills.entries.*.env 和 apiKey 只注入到主机进程（那次 agent 运行），不注入沙箱。如果 agent 跑在沙箱里，这些环境变量无效。更狠的是：requires.bins 是在主机上检查的，但沙箱内要能用，还得在容器里也装上（用 setupCommand 或自定义镜像）。

在提示里引用技能用 $：在 Control UI 输入 $ 会搜索可用技能，选中插入其稳定命令名（如 $release_notes）。一条消息最多引用 8 个不同技能。设了 disable-model-invocation: true 的技能不会出现在 $ 选择器和模型常规提示里——只有你显式引用才能调用，这个开关适合有副作用的技能。

技能在会话开始时快照；之后 SKILL.md 变更、网关重启、或新节点接入等会触发刷新，下一轮生效。

ClawHub：技能的公共仓库

ClawHub 是公开的技能注册表：

openclaw skills install @owner/<slug>     # 装进当前工作区 skills/
openclaw skills install @owner/<slug> --global  # 装进共享 ~/.openclaw/skills
openclaw skills update --all
openclaw skills verify @owner/<slug>      # 校验信任信封

skills verify 会向 ClawHub 要该技能的信任信封，装过 ClawHub 技能的会按 .clawhub/origin.json 里记录的版本与注册表校验；校验失败返回非零。

安全态度要摆正：把第三方技能当不可信代码。 启用前读一读，能用沙箱跑就用沙箱。还可以配 security.installPolicy，在安装/更新前跑一个可信的本地策略命令做决策（失败即拒绝）。

插件：能力层

插件可以带来通道、provider、agent harness、工具、技能、语音、媒体、web 抓取等。安装来源：

openclaw plugins install clawhub:<package>
openclaw plugins install npm:<package>
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install --link ./my-plugin

策略要点（都在 plugins 段里）：

plugins.deny 压过 allow 和单插件启用；
plugins.allow 是排他白名单——不在其中的插件，即使 tools.allow 含 "*"，其工具也不可用；
plugins.entries.<id>.enabled: false 只关一个插件、保留其配置；
plugins.enabled: false 全局停用，跳过发现/加载；
工作区来源的插件默认禁用，要用得显式启用或加白。

验证"到底加载了没有"

这是最容易踩的运维坑：plugins list 和朴素的 plugins inspect 读的是冷配置/manifest/注册表，不能证明正在运行的 Gateway 加载了同一份代码。

openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw plugins reload <plugin-id>

--runtime 会在检查进程里实际加载插件，报告注册的工具、hooks、服务、Gateway 方法和 CLI 命令。改过 manifest 或源码就 reload；成功的 install/update/enable/disable/uninstall 已经应用变更，不需要额外 reload。

插件 hooks 有两套 API：api.on(...)（类型化生命周期钩子，支持优先级、合并、阻断/取消，首选）和 api.registerHook(...)（较粗的命令/生命周期副作用，兼容易用的 HOOK 风格）。

小结

工具是可调用动作，技能是"怎么做"的指令包，插件是运行时能力（常打包前两者）。
工具策略在模型调用之前生效——被移除的工具，模型根本看不到它的 schema。
技能按 SKILL.md 加载，高优先级胜出；per-agent 白名单非空即替换默认；有副作用的技能设 disable-model-invocation。
skills.entries.*.env / requires.bins 只在主机生效，沙箱内要另配。
第三方技能=不可信代码；插件用 allow 收紧、用 inspect --runtime 验证、改完 reload。

下一篇收尾：安全、审批与运维——三层控制（沙箱/工具策略/elevated）、会话权限模式、自动化排程，以及备份与 doctor 的正确用法。