OpenClaw的tools与skills详解

下面把 OpenClaw 的 tools 与 skills 作为一套运行机制来讲。先给一句话结论：

Tools 是智能体真正能调用的"能力函数"；Skills 是教智能体"什么时候、怎么调用这些能力"的说明书；Plugins 则可以把 tools、skills、模型、渠道等能力打包发布。 OpenClaw 官方文档分层：工具是类型化函数定义，Skills 是注入提示词的 Markdown 指导，插件则可以注册/打包额外能力。([OpenClaw][1])

---

1. Tools：智能体真正能执行的能力

Tools 可以理解成 OpenClaw Agent 的"手和脚"。模型不是直接访问你的文件、浏览器、终端、消息渠道，而是通过 Gateway 暴露的工具接口来做事。

官方列出的内置工具包括：

工具	作用
exec / process	运行 shell 命令、管理后台进程
read / write / edit	工作区文件读写与编辑
apply_patch	多文件结构化补丁
browser	控制 Chromium，导航、点击、截图
web_search / x_search / web_fetch	搜索网页、X、抓取页面
message	跨渠道发消息
canvas	驱动节点 Canvas
nodes	发现和定位已配对设备
cron / gateway	计划任务、Gateway 检查/配置/更新
image / image_generate	图片理解、生成、编辑
music_generate / video_generate / tts	音乐、视频、语音生成
sessions_* / subagents / agents_list	会话管理、子智能体编排

这些是随 OpenClaw 提供的核心能力，插件还可以注册额外工具。([OpenClaw][1])

---

2. Tools 的核心机制

2.1 工具会被发给模型作为结构化函数

对 Agent 来说，tool 不是一段自然语言，而是类似这样的"可调用函数"：

{
  "tool": "exec",
  "command": "ls -la",
  "workdir": "/path/to/workspace"
}

模型判断需要用哪个工具，然后 Gateway 执行工具并把结果返回给模型。

所以 tools 的职责是：

模型意图
→ tool call
→ Gateway 执行
→ 工具结果
→ 模型继续推理或回复

2.2 可以用 allow / deny 控制工具权限

全局工具权限通过 tools.allow / tools.deny 控制，且 deny 优先于 allow。例如：

{
  tools: {
    allow: ["group:fs", "browser", "web_search"],
    deny: ["exec"]
  }
}

这表示允许文件组、浏览器和网页搜索，但拒绝 shell 执行。官方文档明确说明拒绝规则优先。([OpenClaw][1])

2.3 工具有 profile 配置档

OpenClaw 有几个工具配置档：

full       基本不限制
coding     文件、运行时、Web、sessions、memory、cron、媒体等
messaging  消息与会话相关工具
minimal    只保留 session_status

配置示例：

{
  tools: {
    profile: "coding"
  }
}

也可以按 agent 覆盖：

{
  agents: {
    list: [
      {
        id: "safe-bot",
        tools: {
          profile: "minimal"
        }
      },
      {
        id: "dev-bot",
        tools: {
          profile: "coding",
          deny: ["exec"]
        }
      }
    ]
  }
}

官方工具组包括 group:runtime、group:fs、group:web、group:ui、group:automation、group:messaging、group:media 等。([OpenClaw][1])

---

3. 最重要的工具：exec / process

exec 是最危险也最强的工具：它能在工作区运行 shell 命令。process 用来管理长期运行的后台命令，例如查看日志、发送按键、停止进程等。官方说明 exec 支持前台和后台执行；如果允许 process，长任务可以转后台并继续管理。([OpenClaw][2])

典型调用：

{
  "tool": "exec",
  "command": "npm test",
  "yieldMs": 1000
}

然后用：

{
  "tool": "process",
  "action": "poll",
  "sessionId": "<id>"
}

查看状态。

exec 的 host 参数

exec 可以在不同位置执行：

auto      默认；有沙箱则进沙箱，否则在 Gateway 主机
sandbox   强制沙箱
gateway   Gateway 主机
node      已配对节点设备

官方特别提醒：沙箱默认关闭 。如果沙箱关闭，host=auto 会解析为 Gateway 主机；显式 host=sandbox 会失败，而不是偷偷在主机上执行。([OpenClaw][3])

所以生产环境建议：

{
  tools: {
    exec: {
      host: "sandbox",
      security: "allowlist",
      ask: "on-miss"
    }
  }
}

或者直接禁用：

{
  tools: {
    deny: ["exec", "process"]
  }
}

---

4. image_generate：媒体工具的典型例子

image_generate 是核心媒体工具，负责图像生成和编辑。它只有在至少一个图像生成提供商可用时才出现；如果看不到这个工具，需要配置 agents.defaults.imageGenerationModel 或相应 API key。([OpenClaw][4])

示例：

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        fallbacks: [
          "google/gemini-3.1-flash-image-preview",
          "fal/fal-ai/flux/dev"
        ]
      }
    }
  }
}

生成图像时，OpenClaw 会按这个顺序尝试：工具调用里的 model 参数、配置的 primary、配置的 fallbacks、最后自动检测可用提供商。([OpenClaw][4])

---

5. Skills：教 Agent 怎么用工具

Skills 不是工具本身。它更像一本"操作手册"。

官方定义是：OpenClaw 使用 AgentSkills 兼容的技能文件夹，每个 skill 是一个目录，里面至少有一个带 YAML frontmatter 和说明的 SKILL.md；OpenClaw 会加载内置 Skills、本地覆盖项，并按环境、配置、二进制是否存在做过滤。([OpenClaw][5])

最小 Skill：

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

Use `image_generate` when the user asks to create or edit images.

When editing an image:
1. Ask for or use the provided reference image.
2. Prefer `images` for multiple references.
3. Use a concise visual prompt.
4. Return the generated media attachment.

这段不会自动创造一个新工具；它只是告诉模型：遇到什么场景时，应该怎么调用已有工具。

---

6. Tools 与 Skills 的区别

维度	Tools	Skills
本质	可执行能力 / 函数	Markdown 指南 / 操作说明
是否执行代码	可以	本身不执行，除非指导模型调用工具或脚本
被谁调用	模型通过 Gateway 调用	被注入/提供给模型阅读
例子	exec, browser, web_search, image_generate	github, weather, browser-automation, image-lab
权限控制	tools.allow / tools.deny / profile	agents.defaults.skills / agents.list[].skills
风险	直接执行动作	可诱导模型执行危险动作

一句话：

Tool = 能做什么
Skill = 什么时候做、怎么做、有哪些约束
Plugin = 把工具、技能、渠道、模型等打包

---

7. Skills 的加载路径与优先级

OpenClaw 会从多个目录加载 Skills。若同名冲突，优先级是：

<workspace>/skills                      最高
→ <workspace>/.agents/skills
→ ~/.agents/skills
→ ~/.openclaw/skills
→ 内置 Skills
→ skills.load.extraDirs                 最低

官方文档说明工作区 skill 会覆盖项目、个人、共享、本地、内置和额外目录中的同名 skill。([OpenClaw][5])

这意味着你可以：

全局安装一个 github skill
但在某个项目的 <workspace>/skills/github/SKILL.md 中覆盖它

适合做项目级约束，比如：

Always use our internal branch naming convention:
feature/<ticket-id>-<short-name>

---

8. 每个 Agent 可以有不同 Skills

Skills 的"位置"和"可见性"是两套控制。位置决定同名时谁胜出；agent allowlist 决定某个 agent 实际能看到哪些 skills。([OpenClaw][5])

示例：

{
  agents: {
    defaults: {
      skills: ["github", "weather"]
    },
    list: [
      { id: "writer" },
      { id: "docs", skills: ["docs-search"] },
      { id: "locked-down", skills: [] }
    ]
  }
}

含义：

writer       继承默认 skills：github, weather
docs         只使用 docs-search，不会与 defaults 合并
locked-down  不暴露任何 skills

官方文档明确说：非空的 agents.list[].skills 是该 agent 的最终集合，不会与 defaults 合并。([OpenClaw][5])

---

9. Skills 配置

Skills 的加载、安装和 per-skill 覆盖大多在 ~/.openclaw/openclaw.json 的 skills 下配置。官方示例包括 allowBundled、load.extraDirs、load.watch、install.nodeManager 和 entries。([OpenClaw][6])

示例：

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: [
        "~/Projects/agent-scripts/skills",
        "~/Projects/oss/some-skill-pack/skills"
      ],
      watch: true,
      watchDebounceMs: 250
    },
    install: {
      preferBrew: true,
      nodeManager: "npm"
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: {
          source: "env",
          provider: "default",
          id: "GEMINI_API_KEY"
        },
        env: {
          GEMINI_API_KEY: "GEMINI_KEY_HERE"
        }
      },
      sag: {
        enabled: false
      }
    }
  }
}

几个重点：

allowBundled       只限制内置 Skills
load.extraDirs     额外扫描目录，优先级最低
load.watch         监听变更，下一轮 agent 处理时生效
entries.<skill>    对单个 skill 做启用、环境变量、API key 覆盖
enabled: false     禁用某个 skill

如果启用了 watcher，对 Skills 的修改会在下一次智能体轮次中生效。([OpenClaw][6])

---

10. SKILL.md 的关键字段

最小 frontmatter：

---
name: my-skill
description: What this skill helps the agent do
---

常用可选字段：

---
name: browser-automation
description: Use browser tool for multi-step web workflows
homepage: https://example.com
user-invocable: true
disable-model-invocation: false
---

官方支持的关键项包括：

字段	作用
name	skill 名称
description	触发/用途描述
homepage	在 macOS Skills UI 中显示网站
user-invocable	是否作为用户斜杠命令暴露，默认 true
disable-model-invocation	是否从模型常规提示中排除
command-dispatch: tool	斜杠命令绕过模型，直接分发到工具
command-tool	直接分发时调用哪个工具
command-arg-mode: raw	将原始参数字符串传给工具

这些字段在官方 Skills 格式说明里列出。([OpenClaw][5])

---

11. Skill 的门控规则

Skills 可以声明依赖，只有依赖满足时才加载。例如：

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata: {"openclaw":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
---

可用门控包括：

requires.bins       PATH 中必须存在这些二进制
requires.anyBins    至少存在其中一个二进制
requires.env        必须有环境变量或配置提供
requires.config     openclaw.json 中对应路径必须为真
os                  限制 darwin / linux / win32
primaryEnv          与 skills.entries.<name>.apiKey 关联
install             安装器规范

官方提醒：requires.bins 是在宿主机检查；如果 agent 在沙箱里运行，容器内部也必须有对应二进制。([OpenClaw][5])

---

12. Skills 与斜杠命令

当 user-invocable: true 时，skill 可以作为用户斜杠命令出现。例如：

/github review this PR
/weather Montreal tomorrow
/image-lab make a poster

如果设置：

---
name: my-command
description: Run a direct command
user-invocable: true
command-dispatch: tool
command-tool: exec
command-arg-mode: raw
---

那么用户调用这个 skill 时，可以绕过模型，直接把原始参数传给指定工具。官方说明这种情况下工具会收到：

{
  "command": "<raw args>",
  "commandName": "<slash command>",
  "skillName": "<skill name>"
}

这很强，但也更危险，尤其是 dispatch 到 exec 之类工具时。([OpenClaw][5])

---

13. 插件、Tools、Skills 的组合关系

插件可以同时提供：

一个或多个 tools
一个或多个 skills
模型 provider
渠道
媒体能力
搜索/抓取能力
语音/实时转写能力

插件也可以在 openclaw.plugin.json 中列出自己的 skills 目录；启用插件后，这些 plugin skills 会加载。官方说明插件 skills 会合并到类似 skills.load.extraDirs 的低优先级路径，所以同名的工作区、agent、托管、本地或内置 skill 会覆盖它们。([OpenClaw][5])

典型插件结构可以理解为：

plugin/
  openclaw.plugin.json
  tools/
    browser-tool.ts
  skills/
    browser-automation/
      SKILL.md

其中：

tool 负责提供 browser 操作能力
skill 负责告诉 agent 多步骤浏览器任务怎么做

---

14. ClawHub：安装第三方 Skills

OpenClaw 的公共 Skills 注册表是 ClawHub。官方命令包括：

openclaw skills install <skill-slug>
openclaw skills update --all
clawhub sync --all

openclaw skills install 会把 skill 安装到当前活动工作区的 skills/ 目录；下一次会话中 OpenClaw 会把它识别为 <workspace>/skills。([OpenClaw][5])

---

15. 安全重点：第三方 Skills 要按"不可信代码"对待

这里要特别强调。官方文档明确说：将第三方 skills 视为不受信任的代码，启用前先阅读；对不受信任输入和高风险工具，优先使用沙箱隔离运行。 官方还说明 Gateway 支持的 skill 依赖安装会运行内置危险代码扫描器，critical 级别默认阻止继续；但 openclaw skills install <slug> 是下载 ClawHub skill 到工作区，不走同一条安装器元数据路径。([OpenClaw][5])

这不是理论风险。近期有安全报道提到，ClawHub 上出现过伪装成加密货币工具的恶意 skills，试图通过安装/执行流程窃取浏览器、钱包或凭证数据；报道也强调这类 skill 可能引导用户或 agent 运行恶意命令。([Tom's Hardware][7])

建议做法：

{
  tools: {
    profile: "coding",
    deny: ["exec", "process"]
  },
  agents: {
    list: [
      {
        id: "third-party-skill-bot",
        skills: ["some-reviewed-skill"],
        tools: {
          profile: "minimal",
          allow: ["web_search", "web_fetch"],
          deny: ["exec", "process", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

如果必须允许执行命令：

{
  tools: {
    exec: {
      host: "sandbox",
      security: "allowlist",
      ask: "on-miss",
      strictInlineEval: true
    }
  }
}

---

16. 实战设计Skill

假设写一个 repo-review skill，让 agent 审查代码仓库。不要在 skill 里只写"review code"。要告诉它：

---
name: repo-review
description: Review a software repository using read, grep, test, and patch tools
---

Use this skill when the user asks for a repository review, bug hunt, refactor plan, or PR-level assessment.

Workflow:
1. Inspect the repository structure first.
2. Read README, package manifests, test config, and key source files.
3. Prefer `read` and search tools before using `exec`.
4. If tests are needed, run the smallest relevant test command first.
5. Do not modify files unless the user explicitly asks for changes.
6. When editing, use `apply_patch` instead of shell redirection.
7. Summarize findings by severity:
   - correctness
   - security
   - maintainability
   - tests
8. Include exact file paths and minimal reproduction steps.

Safety:
- Never run install scripts without approval.
- Never print secrets or `.env` contents.
- Do not execute remote curl/bash commands.

这个 skill 的作用不是"增加读文件能力"，而是把已有工具组合成稳定流程。

---

17. 推荐配置模板

安全聊天型 Agent

{
  agents: {
    list: [
      {
        id: "chat",
        skills: ["weather", "docs-search"],
        tools: {
          profile: "messaging",
          allow: ["web_search", "web_fetch"],
          deny: ["exec", "process", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

编程 Agent

{
  agents: {
    list: [
      {
        id: "dev",
        skills: ["github", "repo-review"],
        tools: {
          profile: "coding",
          deny: []
        }
      }
    ]
  },
  tools: {
    exec: {
      host: "sandbox",
      security: "allowlist",
      ask: "on-miss",
      timeoutSec: 1800,
      strictInlineEval: true
    }
  }
}

第三方 Skills 测试 Agent

{
  agents: {
    list: [
      {
        id: "skill-test",
        skills: ["third-party-skill"],
        tools: {
          profile: "minimal",
          allow: ["web_search", "web_fetch"],
          deny: [
            "exec",
            "process",
            "write",
            "edit",
            "apply_patch",
            "message",
            "gateway"
          ]
        }
      }
    ]
  }
}

---

18. 常见误区

误区 1：安装 Skill 就等于安装工具。

不一定。Skill 多数只是 SKILL.md 指令，可能依赖已有工具，也可能依赖外部 CLI。真正的执行能力仍来自 tools 或外部二进制。

误区 2：禁用 exec 后 Skills 就安全了。

更安全，但不等于绝对安全。Skill 仍可能诱导使用浏览器、消息、文件写入、Web 抓取等工具泄露信息。所以还要限制 message、write、browser 等高风险工具。

误区 3：agents.defaults.skills 会和 agents.list[].skills 合并。

不会。某个 agent 显式设置了 skills，它就是最终集合。官方文档明确说明不会与 defaults 合并。([OpenClaw][5])

误区 4：沙箱默认开启。

不是。官方 exec 文档强调沙箱隔离默认关闭；没有沙箱时 host=auto 会解析为 Gateway 主机。([OpenClaw][3])

---

19. 总结

OpenClaw 的 tools / skills 可以这样理解：

Gateway
  └── Agent
        ├── Tools：实际可执行能力
        │     ├── exec / process
        │     ├── read / write / edit / apply_patch
        │     ├── browser / web_search / web_fetch
        │     ├── image_generate / video_generate / tts
        │     └── message / cron / gateway / nodes
        │
        └── Skills：使用这些能力的方法论
              ├── SKILL.md
              ├── frontmatter
              ├── 工作流说明
              ├── 约束与安全规则
              └── 斜杠命令入口

建议：先用 tools.profile 和 tools.allow/deny 控制硬权限，再用 agents.*.skills 控制软能力和流程；第三方 skills 一律先审查、沙箱、最小权限运行。

参考链接：

1\]: https://docs.openclaw.ai/zh-CN/tools "工具和插件 - OpenClaw" \[2\]: https://docs.openclaw.ai/zh-CN/tools/exec?utm_source=chatgpt.com "执行工具 - OpenClaw" \[3\]: https://docs.openclaw.ai/zh-CN/tools/exec "Exec 工具 - OpenClaw" \[4\]: https://docs.openclaw.ai/zh-CN/tools/image-generation "图像生成 - OpenClaw" \[5\]: https://docs.openclaw.ai/zh-CN/tools/skills "Skills - OpenClaw" \[6\]: https://docs.openclaw.ai/zh-CN/tools/skills-config "Skills 配置 - OpenClaw" \[7\]: https://www.tomshardware.com/tech-industry/cyber-security/malicious-moltbot-skill-targets-crypto-users-on-clawhub?utm_source=chatgpt.com "Malicious OpenClaw 'skill' targets crypto users on ClawHub - 14 malicious skills were uploaded to ClawHub last month"