工具与技能系统全解：安装、启用、权限、调试

前面几章解决的是“先跑起来”，这一章解决的是“别只会聊，要真能干活”。
先记一句最实用的话：Tools 是工具箱，Skills 是使用说明书 + 操作步骤。

本章你将学会什么

分清 Tool、Skill、Plugin、Prompt 四个词到底谁干啥。
按“先把工具开关设好 → 再选技能来源 → 最后确认生效”的顺序，完成一次可稳定上线。
用沙箱与审批把高风险动作关进边界，而不是把风险交给“模型自觉”。
用日志与异常分类法快速定位“是依赖问题、配置问题，还是运行时问题”。
形成可复用的技能编写规范，避免“能跑但不可维护”。

读者前置

你已完成第 2 章，能够在本地完成基础对话。
你知道 openclaw.json 在哪里，且会做最基本的配置修改。
你能接受一个原则：先最小可用，再逐步扩展。

9.1 Tools 与 Skills：是什么、不是什么

9.1.1 能力地图：OpenClaw 能拿来干什么

先给你一张“我到底能拿 OpenClaw 干啥”的地图。
不用背术语，先对号入座：你想做哪件事，就开对应那一组工具。

读者场景	需要的 Tools（建议先最小开通）	推荐 Skills 形态	成功判据
内容整理与文档生产	`group:fs`（读写改文件）+ 可选 `group:web`（检索资料）	单任务技能（如摘要、周报草稿、会议纪要）	生成文件路径明确、结构固定、你按步骤走就能跑通
代码改动与排障	`group:fs` + `group:runtime`（`exec/process`）	工程型技能（检查→修改→验证）	命令可复盘重现、改动可追溯、失败可定位
网页信息采集与验证	`group:web` + `browser`（JS-heavy 页面）	采集/比对技能（来源→摘录→结论）	引用来源可追溯、结论与证据一一对应
聊天渠道自动化（消息收发）	`group:messaging` + `group:sessions`	渠道技能（收消息→处理→回发）	指定会话可收发、不会串频道
多 Agent / 多节点协作	`group:sessions` + `group:nodes`	编排技能（主会话分发子任务）	子任务可追踪、上下文边界清晰

三条新手可执行路径（按风险由低到高）：

内容生产路径：先 group:fs，跑通第 10 章示例技能，再补第 11 章“防翻车”设置。
开发协作路径：在内容路径基础上加 group:runtime，并启用审批。
渠道自动化路径：先把核心任务跑通，再开 group:messaging 做对外收发。

先看看你这台机器“现在到底有哪些技能能用”，直接跑：

openclaw skills list --eligible

如果某个技能没出现，再用下面这条看原因：

openclaw skills info <name>

9.1.2 技能与提示词的边界

一个常见误区是：写了一大段 Prompt，就觉得“我已经有 Skill 了”。
两者不是一回事：

Prompt：偏“表达意图”，告诉模型你想要什么；
Skill：偏“执行契约”，定义什么时候触发、依赖什么、怎么调用工具、失败怎么处理。

你可以把它理解为：
Prompt 更像“口头需求”，Skill 更像“可重复执行的 SOP（步骤卡）”。

一个好判断标准：
同一任务给 10 个人照着做，结果大差不差，那就是 Skill；
每次都靠“当场发挥”，那就还是 Prompt。

9.1.3 技能与插件/工具的关系

这四层你可以这样记：

Tool：最底层原子能力（读文件、执行命令、发 HTTP 等）。
Skill：把多个 Tool 组织成“可复用任务单元”。
Plugin：能力扩展包，可带来 channel、provider 或 skill 目录等扩展。
Gateway：统一调度会话、路由、执行与状态。

官方文档里，Tools 是 OpenClaw 的一等能力（first-class tools）：
你可以用 tools.profile、tools.allow/deny、group:* 控制“能用哪些工具”；
而 Skill 会从多个目录加载，负责把这些工具按步骤串起来。

9.1.4 技能设计的最小单元

给本书读者的“第一版 Skill”建议：

一个 Skill 只做一类任务（单一职责）；
输入参数尽量少（3~5 个以内）；
输出格式固定（至少固定主字段）；
失败时给“可执行下一步”，不要只给“报错字符串”。

一句话：先把一个小 Skill 做到“稳定可复用”，再追求大而全。

9.2 技能安装与启用

9.2.1 技能来源筛选与安装

先把工具开关设成“安全起步档”，再谈技能，会稳很多。
官方支持按 profile 预置工具集合，再用 allow/deny 精调。

示例：默认走 coding profile，但全局禁掉运行时命令（exec/bash/process）：

{
  "tools": {
    "profile": "coding",
    "deny": ["group:runtime"]
  }
}

如果你是“先消息接入、后自动化”的场景，可以改用：

{
  "tools": {
    "profile": "messaging"
  }
}

如果你希望不同模型走不同工具集合，可以叠加 tools.byProvider：

{
  "tools": {
    "profile": "coding",
    "byProvider": {
      "google-antigravity": { "profile": "minimal" },
      "openai/gpt-5.2": { "allow": ["group:fs", "sessions_list"] }
    },
    "deny": ["group:runtime"]
  }
}

这条规则的好处是：
全局你可以保持默认（比如 coding），但对某些 provider/model 单独“踩刹车”。

OpenClaw 当前技能来源与生效顺序是：

workspace/skills（生效顺序最高）
managed/local（如插件暴露的 skills 目录）
bundled（随安装包提供）

同名冲突时，上面优先。
所以最稳的做法是：先盘点现有技能，再决定要不要装新的。

先看全量列表：

openclaw skills list

再看“当前机器实际可用”的列表（依赖满足才算 eligible，也就是“现在真能跑”）：

openclaw skills list --eligible

如果你需要通过插件引入能力（含插件附带技能），用：

openclaw plugins install <path-or-spec>

安装后先别急着开跑，先看插件状态和详情：

openclaw plugins info <id>

9.2.2 启用流程与配置项解释

Skill 侧最常用配置集中在 skills.*。
和 Tools 联动后的最小模板如下：

{
  "tools": {
    "profile": "coding",
    "allow": ["group:fs", "group:openclaw", "browser"],
    "deny": ["group:runtime"],
    "byProvider": {
      "openai/gpt-5.2": { "allow": ["group:fs", "sessions_list"] }
    },
    "exec": {
      "applyPatch": { "enabled": false }
    }
  },
  "skills": {
    "allowBundled": ["peekaboo", "sag"],
    "load": {
      "extraDirs": ["~/team-shared-skills"],
      "watch": true,
      "watchDebounceMs": 250
    },
    "install": {
      "preferBrew": true,
      "nodeManager": "npm"
    },
    "entries": {
      "peekaboo": { "enabled": true },
      "sag": { "enabled": false }
    }
  }
}

配置解释（按新手最常问）：

tools.profile：先选一套基础工具包（比如 coding / messaging）。
tools.allow/deny：再做精细开关；同一工具冲突时，deny 优先生效。
tools.byProvider：对特定 provider/model 再加一道限制（先 profile，再 byProvider，再 allow/deny）。
group:*：工具组简写（如 group:fs、group:runtime、group:openclaw）。
tools.exec.applyPatch.enabled：开启实验性 apply_patch 工具（仅 OpenAI 模型可用，默认建议关闭）。
allowBundled：只影响 bundled 来源，不影响 workspace/managed。
load.extraDirs：追加扫描目录（生效顺序低于 workspace）。
load.watch：是否监控技能目录变化并自动刷新快照。
install.nodeManager：技能安装时用 npm/pnpm/yarn/bun，仅影响技能安装流程。
entries.<skillKey>.enabled：精确开关某个技能。

单技能核对建议配合：

openclaw skills info <name>

9.2.3 生效验证与回归测试

建议按下面顺序检查，别跳步：

结构检查：

openclaw skills check

可用性检查：

openclaw skills list --eligible

单技能元信息检查：

openclaw skills info <name>

注意一个很关键的机制：
OpenClaw 会在 session 启动时生成 skills snapshot。
你改完配置后，若当前会话没更新，可能看到“旧行为”。最稳妥方式是开启新会话再复测。

9.2.4 直接安装现成 Skills（ClawHub 新手路线）

如果你不想自己从零写 Skill，而是先拿现成的来用，按下面 5 步走就行。

第 1 步：按关键词搜索

clawhub search "<关键词>"

例如你想找“日报”或“总结”相关能力，就换成对应关键词搜索。

第 2 步：安装指定 Skill

clawhub install <slug>

slug 就是你在搜索结果里看到的技能唯一名称。

第 3 步：验证“是否真的可用”

openclaw skills list --eligible

能在 --eligible 里看到，才代表“这台机器现在能跑”。

第 4 步：看不可用原因（依赖缺失排查）

openclaw skills info <name>

这一步主要看 requires 字段：缺二进制、缺环境变量、缺配置项，都能在这里看到线索。

第 5 步：统一更新已安装技能

clawhub update --all

实操提醒（很重要）：

ClawHub 会按工作目录/workspace 规则安装技能；
新装技能通常在新会话里最稳妥地生效；
安装后第一件事不是“直接上生产”，而是先跑一轮最小验证输入。

9.3 权限与执行边界

9.3.1 权限分级模型

给零基础读者的实操分级（可直接照抄）：

L1 低风险：只读信息、无外部副作用；
L2 中风险：本地写入、可回滚修改；
L3 高风险：外部系统写操作、资金/权限变更、批量动作。

建议节奏：先 L1，再 L2，最后按审批放行 L3。
不要“一把梭全开”，这是最常见翻车起点。

建议把工具组和风险等级直接绑定，省得误判：

L1 常见对应：group:fs（以只读用法为主）；
L2 常见对应：group:ui、group:web；
L3 常见对应：group:runtime（exec/bash/process）。

9.3.2 执行沙箱与白名单

OpenClaw 的沙箱是“可选配置”，核心键在 agents.defaults.sandbox.*。
最常用三项：

mode: off / non-main / all
scope: session / agent / shared
workspaceAccess: none / ro / rw

一个面向生产的最小示例：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none"
      }
    }
  }
}

需要特别记住：
skills.entries.<skill>.env/apiKey 主要作用于 host run；
若会话在 Docker 沙箱里跑，环境变量需要通过 agents.defaults.sandbox.docker.env 或自定义镜像提供。

workspaceAccess 的实操建议：

none：最稳，默认隔离目录；
ro：可读工作区，不可写；
rw：读写工作区（最强也最危险），只在你明确需要写回真实项目目录时启用。

9.3.3 高风险动作审批

高风险动作建议走“三道闸”：

策略闸：默认 deny 高风险工具；
审批闸：确需执行时人工确认；
检查闸：保留命令、参数、结果与时间线。

排查“为什么不能执行”时，用：

openclaw sandbox explain

它会把 sandbox mode、tool policy 和修复建议一起给你，比“瞎猜哪里配错”靠谱得多。

如果涉及 exec，建议再加一层审批策略（exec approvals）：

security: deny / allowlist / full
ask: 建议 on-miss
askFallback: 建议保持 deny
高风险环境优先 allowlist，不要直接 full

推荐把“技能 CLI 自动放行”和“安全二进制白名单”一起配上：

{
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true
    }
  }
}

{
  "tools": {
    "exec": {
      "safeBins": ["jq", "grep", "cut", "sort", "uniq", "head", "tail", "tr", "wc"]
    }
  }
}

这两项的作用：

autoAllowSkills: true：常见技能依赖 CLI 可按技能声明自动纳入审批白名单，减少重复弹窗；
safeBins：只放“stdin-only”且低风险工具，避免在 allowlist 模式里被任意拼接成危险命令链。

9.4 调试与日志

9.4.1 输入参数调试方法

调试 Skill 时，别一上来就全链路大联调。
更稳的做法是“三步走”：

固定输入（同一段测试输入反复使用）；
固定环境（同一会话、同一配置）；
只改一个变量（参数或依赖二选一）。

先看技能声明与依赖条件，再动手：

openclaw skills info <name>

如果 --eligible 看不到该技能，优先检查 requires.bins / requires.env / requires.config 三类条件。

9.4.2 工具调用链路追踪

查执行链路时，建议“UI + 日志”一起看：

UI 看生命周期与工具事件；
终端持续看日志：

openclaw logs --follow

当你遇到“像在重复回复、又像没执行完”的情况，先看 queue mode。
当前默认是 collect，steer/followup 行为不同，表现会显著变化。

如果出现“同一类工具反复调用却无进展”，建议打开循环保护：

{
  "tools": {
    "loopDetection": {
      "enabled": true
    }
  }
}

9.4.3 异常归类与修复

建议按“现象 → 可能原因 → 第一动作”处理：

现象	高概率根因	第一动作
`skills list` 有条目，但 `--eligible` 没有	依赖条件未满足（bin/env/config）	先 `skills info <name>` 查 `requires`
Host 可跑，Sandbox 失败	容器里缺依赖或无网络/写权限	查 `sandbox.docker.setupCommand` 与 `docker.network`
明明配了 `apiKey` 仍报缺少变量	变量注入在 host，当前 run 在 sandbox	把变量放到 `sandbox.docker.env`
技能改了但表现没变	会话仍使用旧 skills snapshot	新开会话后复测
工具被跳过（Skipped due to queued…）	queue mode 导致中途切换	核对 queue mode 与当前会话队列状态

9.5 最小可用规范

9.5.1 技能文档模板

最低要求：每个技能目录至少有 SKILL.md，并清楚写出四件事：

这个技能解决什么问题；
何时调用、何时不要调用；
依赖哪些命令/变量/配置；
失败时怎么反馈给用户。

一个极简模板：

---
name: daily-report
description: 生成日报并输出固定 Markdown 结构
---

## Use when
- 用户明确要求“生成日报/周报”

## Inputs
- date（必填）
- project（可选）

## Steps
1. 收集输入
2. 调用工具生成草稿（写明会用到哪些工具）
3. 按模板输出

## Output
- 标题
- 今日进展
- 风险与阻塞
- 明日计划

## Failure
- 缺少参数时给出补齐提示
- 工具失败时给出可重试建议

9.5.2 参数与返回约定

建议统一一个“机器能读、人也看得懂”的返回骨架：

status: ok / error
summary: 一句话结果
data: 结构化结果（可为空）
nextAction: 用户下一步建议

这样有个直接好处：
后面接 UI、做检查、做回归时，不用每个技能都重新学一遍输出格式。

9.5.3 失败策略与用户提示规范

对小白读者最友好的失败提示，不是“堆栈信息”，而是三段式：

发生了什么（现象）
你已尝试什么（系统动作）
用户下一步做什么（可执行命令或操作）

示例（建议风格）：

未能完成“日报发送”：缺少 FEISHU_WEBHOOK。
我已完成内容生成，但发送步骤被跳过。
请先在配置中补充变量后重试，或选择“仅导出为本地 Markdown”。

本章小结

Tools 是工具，Skills 是把工具串起来的步骤；两者合起来才有持续生产力。
安装与启用建议按“先开关、再配置、后验证”走，并用 --eligible 判断是否真可用。
权限管理核心就一句：默认收紧、按级放权、全程可追溯。
调试时先分类型：依赖条件、沙箱边界、会话快照、队列模式。
有统一模板和失败规范，技能才能从“偶尔能跑”变成“长期稳定能跑”。

关键断言清单（Claims）

openclaw skills 当前包含 list / list --eligible / info / check 等命令。
Skills 的来源生效顺序为 workspace > managed/local > bundled。
skills.allowBundled 仅影响 bundled 技能，不影响 workspace/managed。
skills.install.nodeManager 可选 npm/pnpm/yarn/bun，仅影响技能安装流程。
skills.entries.<skill>.enabled 可禁用已安装/已内置技能。
Skills 在 session 启动时会生成快照，配置变更并非总是“当轮立即生效”。
沙箱 mode 支持 off/non-main/all，scope 支持 session/agent/shared，workspaceAccess 支持 none/ro/rw。
skills.entries.<skill>.env/apiKey 与 sandbox 变量注入路径不同，sandbox 下需走 sandbox.docker.env 或镜像。
Queue mode 当前默认是 collect，并支持 steer/followup/steer-backlog。
插件命令包含 install/enable/disable/update/uninstall/doctor 等生命周期操作。
tools.profile 可设基础工具集合，且 tools.allow/deny 可用 group:*（含 group:openclaw）简写做管理。
tools.byProvider 可按 provider/model 叠加 profile 与 allow/deny 限制。
tools.exec.applyPatch.enabled 用于开启实验性 apply_patch（OpenAI 模型）。
tools.loopDetection.enabled 默认为 false，需显式开启。
exec approvals 可叠加在工具策略之上提供二次防护，含 autoAllowSkills。
tools.exec.safeBins 可放置 stdin-only 命令，在 allowlist 模式下减少低风险人工审批。
官方提供 coding/messaging/minimal 等工具 profile，并支持 group:* 能力分组管理。
ClawHub 支持 search/install/update，并且安装后的技能要用 openclaw skills list --eligible 与 skills info 做可用性确认。