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

前面几章解决的是“先跑起来”，这一章解决的是“别只会聊，要真能干活”。

先记一句最实用的话：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、group:runtime 是什么？它们是工具组的简写。比如 group:fs 就是“文件操作相关的一大类工具”，group:runtime 就是“运行命令相关的一大类工具”。这样写比一个个列工具名省事儿。

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

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

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

openclaw skills list --eligible

敲命令前先看：这行命令是查看“当前这台机器真正能用的技能”。--eligible 这个参数很关键，加上它才代表“这个技能现在真的能跑”，不加的话可能看到的是“安装过但缺依赖不能用”的技能。

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

openclaw skills info <name>

这行啥意思：<name> 是技能名字，你得换成具体的名字。比如查一个叫 daily-report 的技能，就敲 openclaw skills info daily-report。这命令会告诉你这个技能需要什么依赖、怎么配置。

9.1.2 技能与提示词的边界

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

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

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

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

一句话总结：Prompt 是你跟模型说的话，Skill 是能让模型照着步骤干活的东西。

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

这四层你可以这样记：

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

帮你理解：你可以把 Tool 想象成螺丝刀、扳手这些单个工具；Skill 则是把这些工具组合起来的“使用说明书”，告诉你什么场景用什么工具、怎么用；Plugin 像是工具箱套装，买一套插件等于同时获得好几种工具和说明书；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"]
  }
}

这配置啥意思：第一行 profile: "coding" 说的是“先开一套 coding 工具包”，第二行 deny: ["group:runtime"] 说的是“但是禁用运行命令这一大类工具”。这样就算开了 coding 包，也不会一上来就能执行危险命令。

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

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

啥是 messaging profile：这套工具是专门给聊天渠道自动化用的，包含了收发消息、会话管理之类的能力。如果你主要想让它帮你回消息、处理群聊，选这个。

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

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

byProvider 是啥：这行配置的意思是“不同的模型给不同的工具权限”。比如你有两个模型，一个叫 google-antigravity，只给它开 minimal（最小）权限；另一个叫 gpt-5.2，只给它开文件操作和查看会话列表的权限。这样每个模型各司其职，不会一个模型权限过大。

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

provider 和 model 的区别：provider 是“模型提供商”（比如 OpenAI、Google），model 是具体的模型名字（比如 gpt-5.2）。一个提供商下面通常有多个模型。

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

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

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

先看全量列表：

openclaw skills list

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

openclaw skills list --eligible

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

openclaw plugins install <path-or-spec>

plugins install 怎么用：这里 <path-or-spec> 可以是本地插件文件夹的路径，也可以是一个插件的名称。比如你有一个本地插件包放在 ./my-plugin，就写 ./my-plugin；如果是从插件市场安装，就写插件名字。

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

openclaw plugins info <id>

info 能看到啥：能看到这个插件提供了哪些工具、哪些技能，需要什么依赖，有没有什么已知问题。

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：精确开关某个技能。

配置太多记不住？记住这三点就行：

profile 选一个基础工具包

allow/deny 做精细控制

entries 决定哪个技能开、哪个技能关

单技能核对建议配合：

openclaw skills info <name>

9.2.3 生效验证与回归测试

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

结构检查：

openclaw skills check

可用性检查：

openclaw skills list --eligible

单技能元信息检查：

openclaw skills info <name>

检查顺序不能乱：第一步检查技能文件结构有没有写对（比如缺少必填字段），第二步看这个技能现在能不能跑，第三步看具体这个技能需要什么。如果你跳步直接看第三步，可能会发现技能“看起来正常但就是跑不起来”，因为缺的是依赖条件。

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

snapshot 是啥：你可以理解为“技能的照片”。每次开新会话时，系统会给技能拍个照片，之后这个会话里用的都是这张照片上的版本。所以你改了配置，老会话是不知道的，得开新会话。

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

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

第 1 步：按关键词搜索

clawhub search "<关键词>"

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

clawhub 是啥：这是官方的技能市场，你可以把它理解为“技能的应用商店”。里面有很多别人写好的技能，你可以直接搜、直接装。

第 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：让模型帮你查资料、读文件、总结内容（只看不改）

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"
      }
    }
  }
}

这三个配置啥意思：

mode：沙箱模式，off 是不开沙箱，non-main 是非主会话开沙箱，all 是全部开沙箱

scope：沙箱作用范围，session 是当前会话，agent 是单个智能体，shared 是共享的

workspaceAccess：能不能访问工作区，none 是不能，ro 是只能读，rw 是能读写

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

环境变量易踩的坑：如果你在技能里配了 apiKey，结果沙箱里跑不起来，很可能是因为环境变量没传进去。host 跑和沙箱跑是“两套环境”，配在 host 里的变量沙箱看不到。

workspaceAccess 的实操建议：

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

9.3.3 高风险动作审批

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

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

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

openclaw sandbox explain

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

sandbox explain 超有用：当你配置完沙箱，结果模型“不能执行这个命令”时，别急着改配置，先跑这行命令。它会告诉你具体是哪个配置项拦住了这个命令，以及应该怎么调整。

如果涉及 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 模式里被任意拼接成危险命令链。

safeBins 是什么：这是一批“被认为是安全的命令”白名单。比如 jq 是处理 JSON 的，grep 是搜索文本的，它们都只从标准输入读取数据、不会偷偷执行危险操作。把这些加到白名单里，模型用这些命令时就不用每次都弹窗问你“能不能执行”。

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

logs —follow 怎么用：这行命令会持续输出日志，就像 tail -f 那样。你开一个会话让它跑，然后敲这行命令，就能实时看到它在干什么、调用了什么工具、返回了什么结果。

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

queue mode 是啥：这是“队列模式”，管的是模型输出和工具调用怎么排队。collect 是收集模式，模型会先收集一堆输出再一起处理；steer 是导向模式，模型可以直接控制下一步干什么。新手遇到“模型好像卡住了”或者“模型在重复说话”，可以试试换这个模式。

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

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

loopDetection 帮你防死循环：有些情况下模型会反复调用同一个工具，比如反复读同一个文件、反复发同一个请求，自己出不来了。打开这个检测后，系统会强制停止这种循环，防止资源耗尽。

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 与当前会话队列状态

最常见的问题：技能改了但不生效。记住，修改配置或技能后，一定要开新会话！老会话用的是“旧照片”（snapshot），看不到你的改动。

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、做检查、做回归时，不用每个技能都重新学一遍输出格式。

统一返回格式的好处：就像所有手机充电口都改成 Type-C 一样，统一格式后，前端显示、日志分析、自动化测试都能复用同一套代码，不用每个技能单独写解析逻辑。

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

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

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

示例（建议风格）：

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

失败提示怎么写：别扔一堆技术术语给用户。用户看到“报错了”其实不知道怎么办。你要告诉他“出什么事了”、“系统做了什么”、“他接下来应该做什么”。就像上面的例子，用户一看就知道要去配飞书的 webhook。

本章小结

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 做可用性确认。